+188 -375

AGENTS.md

··· 1 1 - # Tangled CLI – Agent Handoff (Massive Context) 1 1 + # Tangled CLI – Current Implementation Status 2 2 3 3 - This document is a complete handoff for the next Codex instance working on the Tangled CLI (Rust). It explains what exists, what to build next, where to edit, how to call the APIs, how to persist sessions, how to print output, and how to validate success. 3 3 + This document provides an overview of the Tangled CLI implementation status for AI agents or developers working on the project. 4 4 5 5 - Primary focus for this session: implement authentication (auth login/status/logout) and repository listing (repo list). 5 5 + ## Implementation Status 6 6 7 7 - -------------------------------------------------------------------------------- 7 7 + ### ✅ Fully Implemented 8 8 9 9 - ## 0) TL;DR – Immediate Actions 9 9 + #### Authentication (`auth`) 10 10 + - `login` - Authenticate with AT Protocol using `com.atproto.server.createSession` 11 11 + - `status` - Show current authentication status 12 12 + - `logout` - Clear stored session from keyring 10 13 11 11 - - Implement `auth login` using AT Protocol `com.atproto.server.createSession`. 12 12 - - Prompt for handle/password if flags aren’t provided. 13 13 - - POST to `/xrpc/com.atproto.server.createSession` at the configured PDS (default `https://bsky.social`). 14 14 - - Persist `{accessJwt, refreshJwt, did, handle}` via `SessionManager` (keyring-backed). 15 15 - - `auth status` reads keyring and prints handle + did; `auth logout` clears keyring. 14 14 + #### Repositories (`repo`) 15 15 + - `list` - List repositories using `com.atproto.repo.listRecords` with `collection=sh.tangled.repo` 16 16 + - `create` - Create repositories with two-step flow: 17 17 + 1. Create PDS record via `com.atproto.repo.createRecord` 18 18 + 2. Initialize bare repo via `sh.tangled.repo.create` with ServiceAuth 19 19 + - `clone` - Clone repositories using libgit2 with SSH agent support 20 20 + - `info` - Display repository information including stats and languages 21 21 + - `delete` - Delete repositories (both PDS record and knot repo) 22 22 + - `star` / `unstar` - Star/unstar repositories via `sh.tangled.feed.star` 16 23 17 17 - - Implement `repo list` using Tangled’s repo list method (tentative `sh.tangled.repo.list`). 18 18 - - GET `/xrpc/sh.tangled.repo.list` with optional params: `user`, `knot`, `starred`. 19 19 - - Include `Authorization: Bearer <accessJwt>` if required. 20 20 - - Print results as table (default) or JSON (`--format json`). 24 24 + #### Issues (`issue`) 25 25 + - `list` - List issues via `com.atproto.repo.listRecords` with `collection=sh.tangled.repo.issue` 26 26 + - `create` - Create issues via `com.atproto.repo.createRecord` 27 27 + - `show` - Show issue details and comments 28 28 + - `edit` - Edit issue title, body, or state 29 29 + - `comment` - Add comments to issues 21 30 22 22 - Keep edits minimal and scoped to these features. 31 31 + #### Pull Requests (`pr`) 32 32 + - `list` - List PRs via `com.atproto.repo.listRecords` with `collection=sh.tangled.repo.pull` 33 33 + - `create` - Create PRs using `git format-patch` for patches 34 34 + - `show` - Show PR details and diff 35 35 + - `review` - Review PRs with approve/request-changes flags 36 36 + - `merge` - Merge PRs via `sh.tangled.repo.merge` with ServiceAuth 23 37 24 24 - -------------------------------------------------------------------------------- 38 38 + #### Knot Management (`knot`) 39 39 + - `migrate` - Migrate repositories between knots 40 40 + - Validates working tree is clean and pushed 41 41 + - Creates new repo on target knot with source seeding 42 42 + - Updates PDS record to point to new knot 25 43 26 26 - ## 1) Repository Map (Paths You Will Touch) 44 44 + #### Spindle CI/CD (`spindle`) 45 45 + - `config` - Enable/disable or configure spindle URL for a repository 46 46 + - Updates the `spindle` field in `sh.tangled.repo` record 47 47 + - `list` - List pipeline runs via `com.atproto.repo.listRecords` with `collection=sh.tangled.pipeline` 48 48 + - `logs` - Stream workflow logs via WebSocket (`wss://spindle.tangled.sh/spindle/logs/{knot}/{rkey}/{name}`) 49 49 + - `secret list` - List secrets via `sh.tangled.repo.listSecrets` with ServiceAuth 50 50 + - `secret add` - Add secrets via `sh.tangled.repo.addSecret` with ServiceAuth 51 51 + - `secret remove` - Remove secrets via `sh.tangled.repo.removeSecret` with ServiceAuth 27 52 28 28 - - CLI (binary): 29 29 - - `tangled/crates/tangled-cli/src/commands/auth.rs` → implement login/status/logout. 30 30 - - `tangled/crates/tangled-cli/src/commands/repo.rs` → implement list. 31 31 - - `tangled/crates/tangled-cli/src/cli.rs` → already contains arguments and subcommands; no structural changes needed. 32 32 - - `tangled/crates/tangled-cli/src/main.rs` → no change. 53 53 + ### 🚧 Partially Implemented / Stubs 33 54 34 34 - - Config + session: 35 35 - - `tangled/crates/tangled-config/src/session.rs` → already provides `Session` + `SessionManager` (keyring). 36 36 - - `tangled/crates/tangled-config/src/config.rs` → optional use for PDS/base URL (MVP can use CLI flags/env vars). 55 55 + #### Spindle CI/CD (`spindle`) 56 56 + - `run` - Manually trigger a workflow (stub) 57 57 + - **TODO**: Parse `.tangled.yml` to determine workflows 58 58 + - **TODO**: Create pipeline record and trigger spindle ingestion 59 59 + - **TODO**: Support manual trigger inputs 37 60 38 38 - - API client: 39 39 - - `tangled/crates/tangled-api/src/client.rs` → add XRPC helpers and implement `login_with_password` and `list_repos`. 40 40 - 41 41 - -------------------------------------------------------------------------------- 42 42 - 43 43 - ## 2) Current State Snapshot 44 44 - 45 45 - - Workspace is scaffolded and compiles after wiring dependencies (network needed to fetch crates): 46 46 - - `tangled-cli`: clap CLI with subcommands; commands currently log stubs. 47 47 - - `tangled-config`: TOML config loader/saver; keyring-backed session store. 48 48 - - `tangled-api`: client struct with placeholder methods. 49 49 - - `tangled-git`: stubs for future. 50 50 - - Placeholder lexicons in `tangled/lexicons/sh.tangled/*` are not authoritative; use AT Protocol docs and inspect real endpoints later. 51 51 - 52 52 - Goal: replace CLI stubs with real API calls for auth + repo list. 53 53 - 54 54 - -------------------------------------------------------------------------------- 55 55 - 56 56 - ## 3) Endpoints & Data Shapes 57 57 - 58 58 - ### 3.1 AT Protocol – Create Session 59 59 - 60 60 - - Method: `com.atproto.server.createSession` 61 61 - - HTTP: `POST /xrpc/com.atproto.server.createSession` 62 62 - - Request JSON: 63 63 - - `identifier: string` → user handle or email (e.g., `alice.bsky.social`). 64 64 - - `password: string` → password or app password. 65 65 - - Response JSON (subset used): 66 66 - - `accessJwt: string` 67 67 - - `refreshJwt: string` 68 68 - - `did: string` (e.g., `did:plc:...`) 69 69 - - `handle: string` 70 70 - 71 71 - Persist to keyring using `SessionManager`. 72 72 - 73 73 - ### 3.2 Tangled – Repo List (tentative) 74 74 - 75 75 - - Method: `sh.tangled.repo.list` (subject to change; wire in a constant to adjust easily). 76 76 - - HTTP: `GET /xrpc/sh.tangled.repo.list?user=<..>&knot=<..>&starred=<true|false>` 77 77 - - Auth: likely required; include `Authorization: Bearer <accessJwt>`. 78 78 - - Response JSON (envelope): 79 79 - - `{ "repos": [{ "name": string, "knot": string, "private": bool, ... }] }` 80 80 - 81 81 - If method name or response shape differs, adapt the client code; keep CLI interface stable. 82 82 - 83 83 - -------------------------------------------------------------------------------- 84 84 - 85 85 - ## 4) Implementation Plan 86 86 - 87 87 - ### 4.1 Add XRPC helpers and methods in `tangled-api` 88 88 - 89 89 - File: `tangled/crates/tangled-api/src/client.rs` 90 90 - 91 91 - - Extend `TangledClient` with: 92 92 - - `fn xrpc_url(&self, method: &str) -> String` → combines `base_url` + `/xrpc/` + `method`. 93 93 - - `async fn post_json<TReq: Serialize, TRes: DeserializeOwned>(&self, method, req, bearer) -> Result<TRes>`. 94 94 - - `async fn get_json<TRes: DeserializeOwned>(&self, method, params, bearer) -> Result<TRes>`. 95 95 - - Include `Authorization: Bearer <token>` when `bearer` is provided. 96 96 - 97 97 - - Implement: 98 98 - - `pub async fn login_with_password(&self, handle: &str, password: &str, pds: &str) -> Result<Session>` 99 99 - - POST to `com.atproto.server.createSession` at `self.base_url` (which should be the PDS base). 100 100 - - Map response to `tangled_config::session::Session` and return it (caller will persist). 101 101 - - `pub async fn list_repos(&self, user: Option<&str>, knot: Option<&str>, starred: bool, bearer: Option<&str>) -> Result<Vec<Repository>>` 102 102 - - GET `sh.tangled.repo.list` with params present only if set. 103 103 - - Return parsed `Vec<Repository>` from an envelope `{ repos: [...] }`. 104 104 - 105 105 - Error handling: For non-2xx, read the response body, return `anyhow!("{status}: {body}")`. 61 61 + ## Architecture Overview 106 62 107 107 - ### 4.2 Wire CLI auth commands 63 63 + ### Workspace Structure 108 64 109 109 - File: `tangled/crates/tangled-cli/src/commands/auth.rs` 65 65 + - `crates/tangled-cli` - CLI binary with clap-based argument parsing 66 66 + - `crates/tangled-config` - Configuration and keyring-backed session management 67 67 + - `crates/tangled-api` - XRPC client wrapper for AT Protocol and Tangled APIs 68 68 + - `crates/tangled-git` - Git operation helpers (currently unused) 110 69 111 111 - - `login`: 112 112 - - Determine PDS: use `--pds` arg if provided, else default `https://bsky.social` (later from config/env). 113 113 - - Prompt for missing handle/password. 114 114 - - `let client = tangled_api::TangledClient::new(&pds);` 115 115 - - `let session = client.login_with_password(&handle, &password, &pds).await?;` 116 116 - - `tangled_config::session::SessionManager::default().save(&session)?;` 117 117 - - Print: `Logged in as '{handle}' ({did})`. 70 70 + ### Key Patterns 118 71 119 119 - - `status`: 120 120 - - Load `SessionManager::default().load()?`. 121 121 - - If Some: print `Logged in as '{handle}' ({did})`. 122 122 - - Else: print `Not logged in. Run: tangled auth login`. 72 72 + #### ServiceAuth Flow 73 73 + Many Tangled API operations require ServiceAuth tokens: 74 74 + 1. Obtain token via `com.atproto.server.getServiceAuth` from PDS 75 75 + - `aud` parameter must be `did:web:<target-host>` 76 76 + - `exp` parameter should be Unix timestamp + 600 seconds 77 77 + 2. Use token as `Authorization: Bearer <serviceAuth>` for Tangled API calls 123 78 124 124 - - `logout`: 125 125 - - `SessionManager::default().clear()?`. 126 126 - - Print `Logged out` if something was cleared; otherwise `No session found` is acceptable. 79 79 + #### Repository Creation Flow 80 80 + Two-step process: 81 81 + 1. **PDS**: Create `sh.tangled.repo` record via `com.atproto.repo.createRecord` 82 82 + 2. **Tangled API**: Initialize bare repo via `sh.tangled.repo.create` with ServiceAuth 127 83 128 128 - ### 4.3 Wire CLI repo list 84 84 + #### Repository Listing 85 85 + Done entirely via PDS (not Tangled API): 86 86 + 1. Resolve handle → DID if needed via `com.atproto.identity.resolveHandle` 87 87 + 2. List records via `com.atproto.repo.listRecords` with `collection=sh.tangled.repo` 88 88 + 3. Filter client-side (e.g., by knot) 129 89 130 130 - File: `tangled/crates/tangled-cli/src/commands/repo.rs` 90 90 + #### Pull Request Merging 91 91 + 1. Fetch PR record to get patch and target branch 92 92 + 2. Obtain ServiceAuth token 93 93 + 3. Call `sh.tangled.repo.merge` with `{did, name, patch, branch, commitMessage, commitBody}` 131 94 132 132 - - Load session; if absent, print `Please login first: tangled auth login` and exit 1 (or 0 with friendly message; choose one and be consistent). 133 133 - - Build a client for Tangled API base (for now, default to `https://tangled.org` or allow `TANGLED_API_BASE` env var to override): 134 134 - - `let base = std::env::var("TANGLED_API_BASE").unwrap_or_else(|_| "https://tangled.org".into());` 135 135 - - `let client = tangled_api::TangledClient::new(base);` 136 136 - - Call `client.list_repos(args.user.as_deref(), args.knot.as_deref(), args.starred, Some(session.access_jwt.as_str())).await?`. 137 137 - - Print: 138 138 - - If `Cli.format == OutputFormat::Json`: `serde_json::to_string_pretty(&repos)`. 139 139 - - Else: simple columns `NAME KNOT PRIVATE` using `println!` formatting for now. 95 95 + ### Base URLs and Defaults 140 96 141 141 - -------------------------------------------------------------------------------- 97 97 + - **PDS Base** (auth + record operations): Default `https://bsky.social`, stored in session 98 98 + - **Tangled API Base** (server operations): Default `https://tngl.sh`, can override via `TANGLED_API_BASE` 99 99 + - **Spindle Base** (CI/CD): Default `wss://spindle.tangled.sh` for WebSocket logs, can override via `TANGLED_SPINDLE_BASE` 142 100 143 143 - ## 5) Code Snippets (Copy/Paste Friendly) 101 101 + ### Session Management 144 102 145 145 - ### 5.1 In `tangled-api/src/client.rs` 103 103 + Sessions are stored in the system keyring: 104 104 + - Linux: GNOME Keyring / KWallet via Secret Service API 105 105 + - macOS: macOS Keychain 106 106 + - Windows: Windows Credential Manager 146 107 108 108 + Session includes: 147 109 ```rust 148 148 - use anyhow::{anyhow, bail, Result}; 149 149 - use serde::{de::DeserializeOwned, Deserialize, Serialize}; 150 150 - use tangled_config::session::Session; 151 151 - 152 152 - #[derive(Clone, Debug)] 153 153 - pub struct TangledClient { pub(crate) base_url: String } 154 154 - 155 155 - impl TangledClient { 156 156 - pub fn new(base_url: impl Into<String>) -> Self { Self { base_url: base_url.into() } } 157 157 - pub fn default() -> Self { Self::new("https://tangled.org") } 158 158 - 159 159 - fn xrpc_url(&self, method: &str) -> String { 160 160 - format!("{}/xrpc/{}", self.base_url.trim_end_matches('/'), method) 161 161 - } 162 162 - 163 163 - async fn post_json<TReq: Serialize, TRes: DeserializeOwned>( 164 164 - &self, 165 165 - method: &str, 166 166 - req: &TReq, 167 167 - bearer: Option<&str>, 168 168 - ) -> Result<TRes> { 169 169 - let url = self.xrpc_url(method); 170 170 - let client = reqwest::Client::new(); 171 171 - let mut reqb = client.post(url).header(reqwest::header::CONTENT_TYPE, "application/json"); 172 172 - if let Some(token) = bearer { reqb = reqb.header(reqwest::header::AUTHORIZATION, format!("Bearer {}", token)); } 173 173 - let res = reqb.json(req).send().await?; 174 174 - let status = res.status(); 175 175 - if !status.is_success() { 176 176 - let body = res.text().await.unwrap_or_default(); 177 177 - return Err(anyhow!("{}: {}", status, body)); 178 178 - } 179 179 - Ok(res.json::<TRes>().await?) 180 180 - } 181 181 - 182 182 - async fn get_json<TRes: DeserializeOwned>( 183 183 - &self, 184 184 - method: &str, 185 185 - params: &[(&str, String)], 186 186 - bearer: Option<&str>, 187 187 - ) -> Result<TRes> { 188 188 - let url = self.xrpc_url(method); 189 189 - let client = reqwest::Client::new(); 190 190 - let mut reqb = client.get(url).query(&params); 191 191 - if let Some(token) = bearer { reqb = reqb.header(reqwest::header::AUTHORIZATION, format!("Bearer {}", token)); } 192 192 - let res = reqb.send().await?; 193 193 - let status = res.status(); 194 194 - if !status.is_success() { 195 195 - let body = res.text().await.unwrap_or_default(); 196 196 - return Err(anyhow!("{}: {}", status, body)); 197 197 - } 198 198 - Ok(res.json::<TRes>().await?) 199 199 - } 200 200 - 201 201 - pub async fn login_with_password(&self, handle: &str, password: &str, _pds: &str) -> Result<Session> { 202 202 - #[derive(Serialize)] 203 203 - struct Req<'a> { #[serde(rename = "identifier")] identifier: &'a str, #[serde(rename = "password")] password: &'a str } 204 204 - #[derive(Deserialize)] 205 205 - struct Res { #[serde(rename = "accessJwt")] access_jwt: String, #[serde(rename = "refreshJwt")] refresh_jwt: String, did: String, handle: String } 206 206 - let body = Req { identifier: handle, password }; 207 207 - let res: Res = self.post_json("com.atproto.server.createSession", &body, None).await?; 208 208 - Ok(Session { access_jwt: res.access_jwt, refresh_jwt: res.refresh_jwt, did: res.did, handle: res.handle, ..Default::default() }) 209 209 - } 210 210 - 211 211 - pub async fn list_repos(&self, user: Option<&str>, knot: Option<&str>, starred: bool, bearer: Option<&str>) -> Result<Vec<Repository>> { 212 212 - #[derive(Deserialize)] 213 213 - struct Envelope { repos: Vec<Repository> } 214 214 - let mut q = vec![]; 215 215 - if let Some(u) = user { q.push(("user", u.to_string())); } 216 216 - if let Some(k) = knot { q.push(("knot", k.to_string())); } 217 217 - if starred { q.push(("starred", true.to_string())); } 218 218 - let env: Envelope = self.get_json("sh.tangled.repo.list", &q, bearer).await?; 219 219 - Ok(env.repos) 220 220 - } 110 110 + struct Session { 111 111 + access_jwt: String, 112 112 + refresh_jwt: String, 113 113 + did: String, 114 114 + handle: String, 115 115 + pds: Option<String>, // PDS base URL 221 116 } 222 222 - 223 223 - #[derive(Debug, Clone, Serialize, Deserialize, Default)] 224 224 - pub struct Repository { pub did: Option<String>, pub rkey: Option<String>, pub name: String, pub knot: Option<String>, pub description: Option<String>, pub private: bool } 225 117 ``` 226 118 227 227 - ### 5.2 In `tangled-cli/src/commands/auth.rs` 119 119 + ## Working with tangled-core 228 120 229 229 - ```rust 230 230 - use anyhow::Result; 231 231 - use dialoguer::{Input, Password}; 232 232 - use tangled_config::session::SessionManager; 233 233 - use crate::cli::{AuthCommand, AuthLoginArgs, Cli}; 121 121 + The `../tangled-core` repository contains the server implementation and lexicon definitions. 234 122 235 235 - pub async fn run(_cli: &Cli, cmd: AuthCommand) -> Result<()> { 236 236 - match cmd { 237 237 - AuthCommand::Login(args) => login(args).await, 238 238 - AuthCommand::Status => status().await, 239 239 - AuthCommand::Logout => logout().await, 240 240 - } 241 241 - } 123 123 + ### Key Files to Check 242 124 243 243 - async fn login(mut args: AuthLoginArgs) -> Result<()> { 244 244 - let handle: String = match args.handle.take() { Some(h) => h, None => Input::new().with_prompt("Handle").interact_text()? }; 245 245 - let password: String = match args.password.take() { Some(p) => p, None => Password::new().with_prompt("Password").interact()? }; 246 246 - let pds = args.pds.unwrap_or_else(|| "https://bsky.social".to_string()); 247 247 - let client = tangled_api::TangledClient::new(&pds); 248 248 - let mut session = match client.login_with_password(&handle, &password, &pds).await { 249 249 - Ok(sess) => sess, 250 250 - Err(e) => { 251 251 - println!("\x1b[93mIf you're on your own PDS, make sure to pass the --pds flag\x1b[0m"); 252 252 - return Err(e); 253 253 - } 254 254 - }; 255 255 - SessionManager::default().save(&session)?; 256 256 - println!("Logged in as '{}' ({})", session.handle, session.did); 257 257 - Ok(()) 258 258 - } 125 125 + - **Lexicons**: `../tangled-core/lexicons/**/*.json` 126 126 + - Defines XRPC method schemas (NSIDs, parameters, responses) 127 127 + - Example: `sh.tangled.repo.create`, `sh.tangled.repo.merge` 259 128 260 260 - async fn status() -> Result<()> { 261 261 - let mgr = SessionManager::default(); 262 262 - match mgr.load()? { 263 263 - Some(s) => println!("Logged in as '{}' ({})", s.handle, s.did), 264 264 - None => println!("Not logged in. Run: tangled auth login"), 265 265 - } 266 266 - Ok(()) 267 267 - } 129 129 + - **XRPC Routes**: `../tangled-core/knotserver/xrpc/xrpc.go` 130 130 + - Shows which endpoints require ServiceAuth 131 131 + - Maps NSIDs to handler functions 268 132 269 269 - async fn logout() -> Result<()> { 270 270 - let mgr = SessionManager::default(); 271 271 - if mgr.load()?.is_some() { mgr.clear()?; println!("Logged out"); } else { println!("No session found"); } 272 272 - Ok(()) 273 273 - } 274 274 - ``` 133 133 + - **API Handlers**: `../tangled-core/knotserver/xrpc/*.go` 134 134 + - Implementation details for server-side operations 135 135 + - Example: `create_repo.go`, `merge.go` 275 136 276 276 - ### 5.3 In `tangled-cli/src/commands/repo.rs` 137 137 + ### Useful Search Commands 277 138 278 278 - ```rust 279 279 - use anyhow::{anyhow, Result}; 280 280 - use tangled_config::session::SessionManager; 281 281 - use crate::cli::{Cli, RepoCommand, RepoListArgs}; 139 139 + ```bash 140 140 + # Find a specific NSID 141 141 + rg -n "sh\.tangled\.repo\.create" ../tangled-core 282 142 283 283 - pub async fn run(_cli: &Cli, cmd: RepoCommand) -> Result<()> { 284 284 - match cmd { RepoCommand::List(args) => list(args).await, _ => Ok(println!("not implemented")) } 285 285 - } 143 143 + # List all lexicons 144 144 + ls ../tangled-core/lexicons/repo 286 145 287 287 - async fn list(args: RepoListArgs) -> Result<()> { 288 288 - let mgr = SessionManager::default(); 289 289 - let session = mgr.load()?.ok_or_else(|| anyhow!("Please login first: tangled auth login"))?; 290 290 - let base = std::env::var("TANGLED_API_BASE").unwrap_or_else(|_| "https://tangled.org".into()); 291 291 - let client = tangled_api::TangledClient::new(base); 292 292 - let repos = client.list_repos(args.user.as_deref(), args.knot.as_deref(), args.starred, Some(session.access_jwt.as_str())).await?; 293 293 - // Simple output: table or JSON to be improved later 294 294 - println!("NAME\tKNOT\tPRIVATE"); 295 295 - for r in repos { println!("{}\t{}\t{}", r.name, r.knot.unwrap_or_default(), r.private); } 296 296 - Ok(()) 297 297 - } 146 146 + # Check ServiceAuth usage 147 147 + rg -n "ServiceAuth|VerifyServiceAuth" ../tangled-core 298 148 ``` 299 149 300 300 - -------------------------------------------------------------------------------- 150 150 + ## Next Steps for Contributors 301 151 302 302 - ## 6) Configuration, Env Vars, and Security 152 152 + ### Priority: Implement `spindle run` 303 153 304 304 - - PDS base (auth): default `https://bsky.social`. Accept CLI flag `--pds`; later read from config. 305 305 - - Tangled API base (repo list): default `https://tangled.org`; allow override via `TANGLED_API_BASE` env var. 306 306 - - Do not log passwords or tokens. 307 307 - - Store tokens only in keyring (already implemented). 154 154 + The only remaining stub is `spindle run` for manually triggering workflows. Implementation plan: 308 155 309 309 - -------------------------------------------------------------------------------- 156 156 + 1. **Parse `.tangled.yml`** in the current repository to extract workflow definitions 157 157 + - Look for workflow names, triggers, and manual trigger inputs 310 158 311 311 - ## 7) Testing Plan (MVP) 159 159 + 2. **Create pipeline record** on PDS via `com.atproto.repo.createRecord`: 160 160 + ```rust 161 161 + collection: "sh.tangled.pipeline" 162 162 + record: { 163 163 + triggerMetadata: { 164 164 + kind: "manual", 165 165 + repo: { knot, did, repo, defaultBranch }, 166 166 + manual: { inputs: [...] } 167 167 + }, 168 168 + workflows: [{ name, engine, clone, raw }] 169 169 + } 170 170 + ``` 312 171 313 313 - - Client unit tests with `mockito` for `createSession` and `repo list` endpoints; simulate expected JSON. 314 314 - - CLI smoke tests optional for this pass. If added, use `assert_cmd` to check printed output strings. 315 315 - - Avoid live network calls in tests. 172 172 + 3. **Notify spindle** (if needed) or let the ingester pick up the new record 316 173 317 317 - -------------------------------------------------------------------------------- 174 174 + 4. **Support workflow selection** when multiple workflows exist: 175 175 + - `--workflow <name>` flag to select specific workflow 176 176 + - Default to first workflow if not specified 318 177 319 319 - ## 8) Acceptance Criteria 178 178 + 5. **Support manual inputs** (if workflow defines them): 179 179 + - Prompt for input values or accept via flags 320 180 321 321 - - `tangled auth login`: 322 322 - - Prompts or uses flags; successful call saves session and prints `Logged in as ...`. 323 323 - - On failure, shows HTTP status and error message, plus helpful hint about --pds flag for users on their own PDS. 324 324 - - `tangled auth status`: 325 325 - - Shows handle + did if session exists; otherwise says not logged in. 326 326 - - `tangled auth logout`: 327 327 - - Clears keyring; prints confirmation. 328 328 - - `tangled repo list`: 329 329 - - Performs authenticated GET and prints a list (even if empty) without panicking. 330 330 - - JSON output possible later; table output acceptable for now. 181 181 + ### Code Quality Tasks 331 182 332 332 - -------------------------------------------------------------------------------- 183 183 + - Add more comprehensive error messages for common failure cases 184 184 + - Improve table formatting for list commands (consider using `tabled` crate features) 185 185 + - Add shell completion generation (bash, zsh, fish) 186 186 + - Add more unit tests with `mockito` for API client methods 187 187 + - Add integration tests with `assert_cmd` for CLI commands 333 188 334 334 - ## 9) Troubleshooting Notes 335 335 - 336 336 - - Keyring errors on Linux may indicate no secret service running; suggest enabling GNOME Keyring or KWallet. 337 337 - - If `repo list` returns 404, the method name or base URL may be wrong; adjust `sh.tangled.repo.list` or `TANGLED_API_BASE`. 338 338 - - If 401, session may be missing/expired; run `auth login` again. 339 339 - 340 340 - -------------------------------------------------------------------------------- 341 341 - 342 342 - ## 10) Non‑Goals for This Pass 189 189 + ### Documentation Tasks 343 190 344 344 - - Refresh token flow, device code, OAuth. 345 345 - - PRs, issues, knots, spindle implementation. 346 346 - - Advanced formatting, paging, completions. 347 347 - 348 348 - -------------------------------------------------------------------------------- 191 191 + - Add man pages for all commands 192 192 + - Create video tutorials for common workflows 193 193 + - Add troubleshooting guide for common issues 349 194 350 350 - ## 11) Future Follow‑ups 351 351 - 352 352 - - Refresh flow (`com.atproto.server.refreshSession`) and retry once on 401. 353 353 - - Persist base URLs and profiles in config; add `tangled config` commands. 354 354 - - Proper table/json formatting and shell completions. 355 355 - 356 356 - -------------------------------------------------------------------------------- 357 357 - 358 358 - ## 12) Quick Operator Commands 359 359 - 360 360 - - Build CLI: `cargo build -p tangled-cli` 361 361 - - Help: `cargo run -p tangled-cli -- --help` 362 362 - - Login: `cargo run -p tangled-cli -- auth login --handle <handle>` 363 363 - - Status: `cargo run -p tangled-cli -- auth status` 364 364 - - Repo list: `TANGLED_API_BASE=https://tangled.org cargo run -p tangled-cli -- repo list --user <handle>` 365 365 - 366 366 - -------------------------------------------------------------------------------- 195 195 + ## Development Workflow 367 196 368 368 - End of handoff. Implement auth login and repo list as described, keeping changes focused and testable. 197 197 + ### Building 369 198 199 199 + ```sh 200 200 + cargo build # Debug build 201 201 + cargo build --release # Release build 202 202 + ``` 370 203 371 371 - -------------------------------------------------------------------------------- 204 204 + ### Running 372 205 373 373 - ## 13) Tangled Core (../tangled-core) – Practical Notes 206 206 + ```sh 207 207 + cargo run -p tangled-cli -- <command> 208 208 + ``` 374 209 375 375 - This workspace often needs to peek at the Tangled monorepo to confirm XRPC endpoints and shapes. Here are concise tips and findings that informed this CLI implementation. 210 210 + ### Testing 376 211 377 377 - ### Where To Look 212 212 + ```sh 213 213 + cargo test # Run all tests 214 214 + cargo test -- --nocapture # Show println output 215 215 + ``` 378 216 379 379 - - Lexicons (authoritative NSIDs and shapes): `../tangled-core/lexicons/**` 380 380 - - Repo create: `../tangled-core/lexicons/repo/create.json` → `sh.tangled.repo.create` 381 381 - - Repo record schema: `../tangled-core/lexicons/repo/repo.json` → `sh.tangled.repo` 382 382 - - Misc repo queries (tree, log, tags, etc.) under `../tangled-core/lexicons/repo/` 383 383 - - Note: there is no `sh.tangled.repo.list` lexicon in the core right now; listing is done via ATproto records. 384 384 - - Knotserver XRPC routes (what requires auth vs open): `../tangled-core/knotserver/xrpc/xrpc.go` 385 385 - - Mutating repo ops (e.g., `sh.tangled.repo.create`) are behind ServiceAuth middleware. 386 386 - - Read-only repo queries (tree, log, etc.) are open. 387 387 - - Create repo handler (server-side flow): `../tangled-core/knotserver/xrpc/create_repo.go` 388 388 - - Validates ServiceAuth; expects rkey for the `sh.tangled.repo` record that already exists on the user's PDS. 389 389 - - ServiceAuth middleware (how Bearer is validated): `../tangled-core/xrpc/serviceauth/service_auth.go` 390 390 - - Validates a ServiceAuth token with Audience = `did:web:<knot-or-service-host>`. 391 391 - - Appview client for ServiceAuth: `../tangled-core/appview/xrpcclient/xrpc.go` (method: `ServerGetServiceAuth`). 217 217 + ### Code Quality 392 218 393 393 - ### How To Search Quickly (rg examples) 219 219 + ```sh 220 220 + cargo fmt # Format code 221 221 + cargo clippy # Run linter 222 222 + cargo clippy -- -W clippy::all # Strict linting 223 223 + ``` 394 224 395 395 - - Find a specific NSID across the repo: 396 396 - - `rg -n "sh\.tangled\.repo\.create" ../tangled-core` 397 397 - - See which endpoints are routed and whether they’re behind ServiceAuth: 398 398 - - `rg -n "chi\..*Get\(|chi\..*Post\(" ../tangled-core/knotserver/xrpc` 399 399 - - Then open `xrpc.go` and respective handlers. 400 400 - - Discover ServiceAuth usage and audience DID: 401 401 - - `rg -n "ServerGetServiceAuth|VerifyServiceAuth|serviceauth" ../tangled-core` 402 402 - - List lexicons by area: 403 403 - - `ls ../tangled-core/lexicons/repo` or `rg -n "\bid\": \"sh\.tangled\..*\"" ../tangled-core/lexicons` 225 225 + ## Troubleshooting Common Issues 404 226 405 405 - ### Repo Listing (client-side pattern) 227 227 + ### Keyring Errors on Linux 406 228 407 407 - - There is no `sh.tangled.repo.list` in core. To list a user’s repos: 408 408 - 1) Resolve handle → DID if needed via PDS: `GET com.atproto.identity.resolveHandle`. 409 409 - 2) List records from the user’s PDS: `GET com.atproto.repo.listRecords` with `collection=sh.tangled.repo`. 410 410 - 3) Filter client-side (e.g., by `knot`). “Starred” filtering is not currently defined in core. 229 229 + Ensure a secret service is running: 230 230 + ```sh 231 231 + systemctl --user enable --now gnome-keyring-daemon 232 232 + ``` 411 233 412 412 - ### Repo Creation (two-step flow) 234 234 + ### Invalid Token Errors 413 235 414 414 - - Step 1 (PDS): create the `sh.tangled.repo` record in the user’s repo: 415 415 - - `POST com.atproto.repo.createRecord` with `{ repo: <did>, collection: "sh.tangled.repo", record: { name, knot, description?, createdAt } }`. 416 416 - - Extract `rkey` from the returned `uri` (`at://<did>/<collection>/<rkey>`). 417 417 - - Step 2 (Tangled API base): call the server to initialize the bare repo on the knot: 418 418 - - Obtain ServiceAuth: `GET com.atproto.server.getServiceAuth` from PDS with `aud=did:web:<tngl.sh or target-host>`. 419 419 - - `POST sh.tangled.repo.create` on the Tangled API base with `{ rkey, defaultBranch?, source? }` and `Authorization: Bearer <serviceAuth>`. 420 420 - - Server validates token via `xrpc/serviceauth`, confirms actor permissions, and creates the git repo. 236 236 + - For record operations: Use PDS client, not Tangled API client 237 237 + - For server operations: Ensure ServiceAuth audience DID matches target host 421 238 422 422 - ### Base URLs, DIDs, and Defaults 239 239 + ### Repository Not Found 423 240 424 424 - - Tangled API base (server): default is `https://tngl.sh`. Do not use the marketing/landing site. 425 425 - - PDS base (auth + record ops): default `https://bsky.social` unless a different PDS was chosen on login. 426 426 - - ServiceAuth audience DID is `did:web:<host>` where `<host>` is the Tangled API base hostname. 427 427 - - CLI stores the PDS URL in the session to keep the CLI stateful. 241 241 + - Verify repo exists: `tangled repo info owner/name` 242 242 + - Check you're using the correct owner (handle or DID) 243 243 + - Ensure you have access permissions 428 244 429 429 - ### Common Errors and Fixes 245 245 + ### WebSocket Connection Failures 430 246 431 431 - - `InvalidToken` when listing repos: listing should use the PDS (`com.atproto.repo.listRecords`), not the Tangled API base. 432 432 - - 404 on `repo.create`: verify ServiceAuth audience matches the target host and that the rkey exists on the PDS. 433 433 - - Keychain issues on Linux: ensure a Secret Service (e.g., GNOME Keyring or KWallet) is running. 247 247 + - Check spindle base URL is correct (default: `wss://spindle.tangled.sh`) 248 248 + - Verify the job_id format: `knot:rkey:name` 249 249 + - Ensure the workflow has actually run and has logs 434 250 435 435 - ### Implementation Pointers (CLI) 251 251 + ## Additional Resources 436 252 437 437 - - Auth 438 438 - - `com.atproto.server.createSession` against the PDS, save `{accessJwt, refreshJwt, did, handle, pds}` in keyring. 439 439 - - List repos 440 440 - - Use session.handle by default; resolve to DID, then `com.atproto.repo.listRecords` on PDS. 441 441 - - Create repo 442 442 - - Build the PDS record first; then ServiceAuth → `sh.tangled.repo.create` on `tngl.sh`. 253 253 + - Main README: `README.md` - User-facing documentation 254 254 + - Getting Started Guide: `docs/getting-started.md` - Tutorial for new users 255 255 + - Lexicons: `../tangled-core/lexicons/` - XRPC method definitions 256 256 + - Server Implementation: `../tangled-core/knotserver/` - Server-side code 443 257 444 444 - ### Testing Hints 258 258 + --- 445 259 446 446 - - Avoid live calls; use `mockito` to stub both PDS and Tangled API base endpoints. 447 447 - - Unit test decoding with minimal JSON envelopes: record lists, createRecord `uri`, and repo.create (empty body or simple ack). 260 260 + Last updated: 2025-10-14

+154 -4

Cargo.lock

··· 204 204 checksum = "2261d10cca569e4643e526d8dc2e62e433cc8aba21ab764233731f8d369bf394" 205 205 206 206 [[package]] 207 207 + name = "block-buffer" 208 208 + version = "0.10.4" 209 209 + source = "registry+https://github.com/rust-lang/crates.io-index" 210 210 + checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71" 211 211 + dependencies = [ 212 212 + "generic-array", 213 213 + ] 214 214 + 215 215 + [[package]] 207 216 name = "bumpalo" 208 217 version = "3.19.0" 209 218 source = "registry+https://github.com/rust-lang/crates.io-index" 210 219 checksum = "46c5e41b57b8bba42a04676d81cb89e9ee8e859a1a66f80a5a72e1cb76b34d43" 220 220 + 221 221 + [[package]] 222 222 + name = "byteorder" 223 223 + version = "1.5.0" 224 224 + source = "registry+https://github.com/rust-lang/crates.io-index" 225 225 + checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b" 211 226 212 227 [[package]] 213 228 name = "bytes" ··· 388 403 ] 389 404 390 405 [[package]] 406 406 + name = "cpufeatures" 407 407 + version = "0.2.17" 408 408 + source = "registry+https://github.com/rust-lang/crates.io-index" 409 409 + checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280" 410 410 + dependencies = [ 411 411 + "libc", 412 412 + ] 413 413 + 414 414 + [[package]] 391 415 name = "crc32fast" 392 416 version = "1.5.0" 393 417 source = "registry+https://github.com/rust-lang/crates.io-index" ··· 397 421 ] 398 422 399 423 [[package]] 424 424 + name = "crypto-common" 425 425 + version = "0.1.6" 426 426 + source = "registry+https://github.com/rust-lang/crates.io-index" 427 427 + checksum = "1bfb12502f3fc46cca1bb51ac28df9d618d813cdc3d2f25b9fe775a34af26bb3" 428 428 + dependencies = [ 429 429 + "generic-array", 430 430 + "typenum", 431 431 + ] 432 432 + 433 433 + [[package]] 400 434 name = "data-encoding" 401 435 version = "2.9.0" 402 436 source = "registry+https://github.com/rust-lang/crates.io-index" ··· 455 489 "tempfile", 456 490 "thiserror 1.0.69", 457 491 "zeroize", 492 492 + ] 493 493 + 494 494 + [[package]] 495 495 + name = "digest" 496 496 + version = "0.10.7" 497 497 + source = "registry+https://github.com/rust-lang/crates.io-index" 498 498 + checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292" 499 499 + dependencies = [ 500 500 + "block-buffer", 501 501 + "crypto-common", 458 502 ] 459 503 460 504 [[package]] ··· 631 675 "pin-project-lite", 632 676 "pin-utils", 633 677 "slab", 678 678 + ] 679 679 + 680 680 + [[package]] 681 681 + name = "generic-array" 682 682 + version = "0.14.9" 683 683 + source = "registry+https://github.com/rust-lang/crates.io-index" 684 684 + checksum = "4bb6743198531e02858aeaea5398fcc883e71851fcbcb5a2f773e2fb6cb1edf2" 685 685 + dependencies = [ 686 686 + "typenum", 687 687 + "version_check", 634 688 ] 635 689 636 690 [[package]] ··· 1472 1526 "bytes", 1473 1527 "getrandom 0.3.3", 1474 1528 "lru-slab", 1475 1475 - "rand", 1529 1529 + "rand 0.9.2", 1476 1530 "ring", 1477 1531 "rustc-hash", 1478 1532 "rustls", ··· 1515 1569 1516 1570 [[package]] 1517 1571 name = "rand" 1572 1572 + version = "0.8.5" 1573 1573 + source = "registry+https://github.com/rust-lang/crates.io-index" 1574 1574 + checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404" 1575 1575 + dependencies = [ 1576 1576 + "libc", 1577 1577 + "rand_chacha 0.3.1", 1578 1578 + "rand_core 0.6.4", 1579 1579 + ] 1580 1580 + 1581 1581 + [[package]] 1582 1582 + name = "rand" 1518 1583 version = "0.9.2" 1519 1584 source = "registry+https://github.com/rust-lang/crates.io-index" 1520 1585 checksum = "6db2770f06117d490610c7488547d543617b21bfa07796d7a12f6f1bd53850d1" 1521 1586 dependencies = [ 1522 1522 - "rand_chacha", 1523 1523 - "rand_core", 1587 1587 + "rand_chacha 0.9.0", 1588 1588 + "rand_core 0.9.3", 1589 1589 + ] 1590 1590 + 1591 1591 + [[package]] 1592 1592 + name = "rand_chacha" 1593 1593 + version = "0.3.1" 1594 1594 + source = "registry+https://github.com/rust-lang/crates.io-index" 1595 1595 + checksum = "e6c10a63a0fa32252be49d21e7709d4d4baf8d231c2dbce1eaa8141b9b127d88" 1596 1596 + dependencies = [ 1597 1597 + "ppv-lite86", 1598 1598 + "rand_core 0.6.4", 1524 1599 ] 1525 1600 1526 1601 [[package]] ··· 1530 1605 checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb" 1531 1606 dependencies = [ 1532 1607 "ppv-lite86", 1533 1533 - "rand_core", 1608 1608 + "rand_core 0.9.3", 1609 1609 + ] 1610 1610 + 1611 1611 + [[package]] 1612 1612 + name = "rand_core" 1613 1613 + version = "0.6.4" 1614 1614 + source = "registry+https://github.com/rust-lang/crates.io-index" 1615 1615 + checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c" 1616 1616 + dependencies = [ 1617 1617 + "getrandom 0.2.16", 1534 1618 ] 1535 1619 1536 1620 [[package]] ··· 1851 1935 ] 1852 1936 1853 1937 [[package]] 1938 1938 + name = "sha1" 1939 1939 + version = "0.10.6" 1940 1940 + source = "registry+https://github.com/rust-lang/crates.io-index" 1941 1941 + checksum = "e3bf829a2d51ab4a5ddf1352d8470c140cadc8301b2ae1789db023f01cedd6ba" 1942 1942 + dependencies = [ 1943 1943 + "cfg-if", 1944 1944 + "cpufeatures", 1945 1945 + "digest", 1946 1946 + ] 1947 1947 + 1948 1948 + [[package]] 1854 1949 name = "shell-words" 1855 1950 version = "1.1.0" 1856 1951 source = "registry+https://github.com/rust-lang/crates.io-index" ··· 1994 2089 version = "0.1.0" 1995 2090 dependencies = [ 1996 2091 "anyhow", 2092 2092 + "chrono", 1997 2093 "clap", 1998 2094 "colored", 1999 2095 "dialoguer", 2096 2096 + "futures-util", 2000 2097 "git2", 2001 2098 "indicatif", 2002 2099 "serde", ··· 2005 2102 "tangled-config", 2006 2103 "tangled-git", 2007 2104 "tokio", 2105 2105 + "tokio-tungstenite", 2008 2106 "url", 2009 2107 ] 2010 2108 ··· 2169 2267 ] 2170 2268 2171 2269 [[package]] 2270 2270 + name = "tokio-tungstenite" 2271 2271 + version = "0.21.0" 2272 2272 + source = "registry+https://github.com/rust-lang/crates.io-index" 2273 2273 + checksum = "c83b561d025642014097b66e6c1bb422783339e0909e4429cde4749d1990bc38" 2274 2274 + dependencies = [ 2275 2275 + "futures-util", 2276 2276 + "log", 2277 2277 + "native-tls", 2278 2278 + "tokio", 2279 2279 + "tokio-native-tls", 2280 2280 + "tungstenite", 2281 2281 + ] 2282 2282 + 2283 2283 + [[package]] 2172 2284 name = "tokio-util" 2173 2285 version = "0.7.16" 2174 2286 source = "registry+https://github.com/rust-lang/crates.io-index" ··· 2304 2416 checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b" 2305 2417 2306 2418 [[package]] 2419 2419 + name = "tungstenite" 2420 2420 + version = "0.21.0" 2421 2421 + source = "registry+https://github.com/rust-lang/crates.io-index" 2422 2422 + checksum = "9ef1a641ea34f399a848dea702823bbecfb4c486f911735368f1f137cb8257e1" 2423 2423 + dependencies = [ 2424 2424 + "byteorder", 2425 2425 + "bytes", 2426 2426 + "data-encoding", 2427 2427 + "http", 2428 2428 + "httparse", 2429 2429 + "log", 2430 2430 + "native-tls", 2431 2431 + "rand 0.8.5", 2432 2432 + "sha1", 2433 2433 + "thiserror 1.0.69", 2434 2434 + "url", 2435 2435 + "utf-8", 2436 2436 + ] 2437 2437 + 2438 2438 + [[package]] 2439 2439 + name = "typenum" 2440 2440 + version = "1.19.0" 2441 2441 + source = "registry+https://github.com/rust-lang/crates.io-index" 2442 2442 + checksum = "562d481066bde0658276a35467c4af00bdc6ee726305698a55b86e61d7ad82bb" 2443 2443 + 2444 2444 + [[package]] 2307 2445 name = "unicase" 2308 2446 version = "2.8.1" 2309 2447 source = "registry+https://github.com/rust-lang/crates.io-index" ··· 2346 2484 ] 2347 2485 2348 2486 [[package]] 2487 2487 + name = "utf-8" 2488 2488 + version = "0.7.6" 2489 2489 + source = "registry+https://github.com/rust-lang/crates.io-index" 2490 2490 + checksum = "09cc8ee72d2a9becf2f2febe0205bbed8fc6615b7cb429ad062dc7b7ddd036a9" 2491 2491 + 2492 2492 + [[package]] 2349 2493 name = "utf8_iter" 2350 2494 version = "1.0.4" 2351 2495 source = "registry+https://github.com/rust-lang/crates.io-index" ··· 2362 2506 version = "0.2.15" 2363 2507 source = "registry+https://github.com/rust-lang/crates.io-index" 2364 2508 checksum = "accd4ea62f7bb7a82fe23066fb0957d48ef677f6eeb8215f372f52e48bb32426" 2509 2509 + 2510 2510 + [[package]] 2511 2511 + name = "version_check" 2512 2512 + version = "0.9.5" 2513 2513 + source = "registry+https://github.com/rust-lang/crates.io-index" 2514 2514 + checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a" 2365 2515 2366 2516 [[package]] 2367 2517 name = "want"

+4

Cargo.toml

··· 53 53 base64 = "0.22" 54 54 regex = "1.10" 55 55 56 56 + # WebSocket 57 57 + tokio-tungstenite = { version = "0.21", features = ["native-tls"] } 58 58 + futures-util = "0.3" 59 59 + 56 60 # Testing 57 61 mockito = "1.4" 58 62 tempfile = "3.10"

+168 -17

README.md

··· 1 1 - # Tangled CLI (Rust) 1 1 + # Tangled CLI 2 2 3 3 A Rust CLI for Tangled, a decentralized git collaboration platform built on the AT Protocol. 4 4 5 5 - Status: project scaffold with CLI, config, API and git crates. Commands are stubs pending endpoint wiring. 5 5 + ## Features 6 6 + 7 7 + Tangled CLI is a fully functional tool for managing repositories, issues, pull requests, and CI/CD workflows on the Tangled platform. 8 8 + 9 9 + ### Implemented Commands 10 10 + 11 11 + - **Authentication** (`auth`) 12 12 + - `login` - Authenticate with AT Protocol credentials 13 13 + - `status` - Show current authentication status 14 14 + - `logout` - Clear stored session 15 15 + 16 16 + - **Repositories** (`repo`) 17 17 + - `list` - List your repositories or another user's repos 18 18 + - `create` - Create a new repository on a knot 19 19 + - `clone` - Clone a repository to your local machine 20 20 + - `info` - Show detailed repository information 21 21 + - `delete` - Delete a repository 22 22 + - `star` / `unstar` - Star or unstar repositories 23 23 + 24 24 + - **Issues** (`issue`) 25 25 + - `list` - List issues for a repository 26 26 + - `create` - Create a new issue 27 27 + - `show` - Show issue details and comments 28 28 + - `edit` - Edit issue title, body, or state 29 29 + - `comment` - Add a comment to an issue 30 30 + 31 31 + - **Pull Requests** (`pr`) 32 32 + - `list` - List pull requests for a repository 33 33 + - `create` - Create a pull request from a branch 34 34 + - `show` - Show pull request details and diff 35 35 + - `review` - Review a pull request (approve/request changes) 36 36 + - `merge` - Merge a pull request 37 37 + 38 38 + - **Knot Management** (`knot`) 39 39 + - `migrate` - Migrate a repository to another knot 40 40 + 41 41 + - **CI/CD with Spindle** (`spindle`) 42 42 + - `config` - Enable/disable or configure spindle for a repository 43 43 + - `list` - List pipeline runs for a repository 44 44 + - `logs` - Stream logs from a workflow execution 45 45 + - `secret` - Manage secrets for CI/CD workflows 46 46 + - `list` - List secrets for a repository 47 47 + - `add` - Add or update a secret 48 48 + - `remove` - Remove a secret 49 49 + - `run` - Manually trigger a workflow (not yet implemented) 6 50 7 7 - ## Workspace 51 51 + ## Installation 8 52 9 9 - - `crates/tangled-cli`: CLI binary (clap-based) 10 10 - - `crates/tangled-config`: Config + session management 11 11 - - `crates/tangled-api`: XRPC client wrapper (stubs) 12 12 - - `crates/tangled-git`: Git helpers (stubs) 13 13 - - `lexicons/sh.tangled`: Placeholder lexicons 53 53 + ### Build from Source 14 54 15 15 - ## Quick start 55 55 + Requires Rust toolchain (1.70+) and network access to fetch dependencies. 16 56 17 57 ```sh 18 18 - cargo run -p tangled-cli -- --help 58 58 + cargo build --release 19 59 ``` 20 60 21 21 - ### Install from AUR (community maintained) 61 61 + The binary will be available at `target/release/tangled-cli`. 62 62 + 63 63 + ### Install from AUR (Arch Linux) 64 64 + 65 65 + Community-maintained package: 22 66 23 67 ```sh 24 68 yay -S tangled-cli-git 25 69 ``` 26 70 27 27 - Building requires network to fetch crates. 71 71 + ## Quick Start 72 72 + 73 73 + 1. **Login to Tangled**: 74 74 + ```sh 75 75 + tangled auth login --handle your.handle.bsky.social 76 76 + ``` 77 77 + 78 78 + 2. **List your repositories**: 79 79 + ```sh 80 80 + tangled repo list 81 81 + ``` 82 82 + 83 83 + 3. **Create a new repository**: 84 84 + ```sh 85 85 + tangled repo create myproject --description "My cool project" 86 86 + ``` 87 87 + 88 88 + 4. **Clone a repository**: 89 89 + ```sh 90 90 + tangled repo clone username/reponame 91 91 + ``` 92 92 + 93 93 + ## Workspace Structure 94 94 + 95 95 + - `crates/tangled-cli` - CLI binary with clap-based argument parsing 96 96 + - `crates/tangled-config` - Configuration and session management (keyring-backed) 97 97 + - `crates/tangled-api` - XRPC client wrapper for AT Protocol and Tangled APIs 98 98 + - `crates/tangled-git` - Git operation helpers 99 99 + 100 100 + ## Configuration 101 101 + 102 102 + The CLI stores session credentials securely in your system keyring and configuration in: 103 103 + - Linux: `~/.config/tangled/config.toml` 104 104 + - macOS: `~/Library/Application Support/tangled/config.toml` 105 105 + - Windows: `%APPDATA%\tangled\config.toml` 106 106 + 107 107 + ### Environment Variables 108 108 + 109 109 + - `TANGLED_PDS_BASE` - Override the PDS base URL (default: `https://bsky.social`) 110 110 + - `TANGLED_API_BASE` - Override the Tangled API base URL (default: `https://tngl.sh`) 111 111 + - `TANGLED_SPINDLE_BASE` - Override the Spindle base URL (default: `wss://spindle.tangled.sh`) 28 112 29 29 - ## Next steps 113 113 + ## Examples 114 114 + 115 115 + ### Working with Issues 30 116 31 31 - - Implement `com.atproto.server.createSession` for auth 32 32 - - Wire repo list/create endpoints under `sh.tangled.*` 33 33 - - Persist sessions via keyring and load in CLI 34 34 - - Add output formatting (table/json) 117 117 + ```sh 118 118 + # Create an issue 119 119 + tangled issue create --repo myrepo --title "Bug: Fix login" --body "Description here" 120 120 + 121 121 + # List issues 122 122 + tangled issue list --repo myrepo 123 123 + 124 124 + # Comment on an issue 125 125 + tangled issue comment <issue-id> --body "I'll fix this" 126 126 + ``` 127 127 + 128 128 + ### Working with Pull Requests 129 129 + 130 130 + ```sh 131 131 + # Create a PR from a branch 132 132 + tangled pr create --repo myrepo --base main --head feature-branch --title "Add new feature" 133 133 + 134 134 + # Review a PR 135 135 + tangled pr review <pr-id> --approve --comment "LGTM!" 136 136 + 137 137 + # Merge a PR 138 138 + tangled pr merge <pr-id> 139 139 + ``` 35 140 141 141 + ### CI/CD with Spindle 142 142 + 143 143 + ```sh 144 144 + # Enable spindle for your repo 145 145 + tangled spindle config --repo myrepo --enable 146 146 + 147 147 + # List pipeline runs 148 148 + tangled spindle list --repo myrepo 149 149 + 150 150 + # Stream logs from a workflow 151 151 + tangled spindle logs knot:rkey:workflow-name --follow 152 152 + 153 153 + # Manage secrets 154 154 + tangled spindle secret add --repo myrepo --key API_KEY --value "secret-value" 155 155 + tangled spindle secret list --repo myrepo 156 156 + ``` 157 157 + 158 158 + ## Development 159 159 + 160 160 + Run tests: 161 161 + ```sh 162 162 + cargo test 163 163 + ``` 164 164 + 165 165 + Run with debug output: 166 166 + ```sh 167 167 + cargo run -p tangled-cli -- --verbose <command> 168 168 + ``` 169 169 + 170 170 + Format code: 171 171 + ```sh 172 172 + cargo fmt 173 173 + ``` 174 174 + 175 175 + Check for issues: 176 176 + ```sh 177 177 + cargo clippy 178 178 + ``` 179 179 + 180 180 + ## Contributing 181 181 + 182 182 + Contributions are welcome! Please feel free to submit issues or pull requests. 183 183 + 184 184 + ## License 185 185 + 186 186 + MIT OR Apache-2.0

+36

TODO.md

··· 1 1 + # TODO - Tech Debt 2 2 + 3 3 + ## Pull Request Support 4 4 + 5 5 + ### Branch-Based PR Merge 6 6 + - [ ] Implement branch-based PR merge support in CLI 7 7 + - **Issue**: Currently only patch-based PRs can be merged via `tangled pr merge` 8 8 + - **Location**: `crates/tangled-api/src/client.rs:1250-1253` 9 9 + - **Current behavior**: Returns error: "Cannot merge branch-based PR via CLI. Please use the web interface." 10 10 + - **Required**: Add support for merging PRs that have a `source` field with SHA/branch info instead of a `patch` field 11 11 + - **Related**: Server-side merge API may need updates to support branch merges 12 12 + 13 13 + ### PR Comments Display 14 14 + - [ ] Implement `--comments` flag functionality in `pr show` command 15 15 + - **Issue**: Flag is defined but not implemented 16 16 + - **Location**: `crates/tangled-cli/src/commands/pr.rs:145-180` 17 17 + - **Current behavior**: `tangled pr show <id> --comments` doesn't display any comments 18 18 + - **Required**: 19 19 + - Fetch comments from the API 20 20 + - Display comment author, timestamp, and content 21 21 + - Handle threaded/nested comments if supported 22 22 + - **API**: Need to determine correct endpoint for fetching PR comments 23 23 + 24 24 + ### PR Format Compatibility 25 25 + - [x] Support both patch-based and branch-based PR formats 26 26 + - **Completed**: Added `PullSource` struct and made `patch` field optional 27 27 + - **Location**: `crates/tangled-api/src/client.rs:1392-1413` 28 28 + - **Details**: PRs can now have either: 29 29 + - `patch: String` (legacy format) 30 30 + - `source: { sha, repo?, branch? }` (new format) 31 31 + 32 32 + ## Related Issues 33 33 + 34 34 + - Consider adding `--format json` output for programmatic access to PR data 35 35 + - Add better error messages when operations aren't supported for certain PR types 36 36 + - Document the differences between patch-based and branch-based PRs in user docs

+315 -19

crates/tangled-api/src/client.rs

··· 23 23 } 24 24 25 25 fn xrpc_url(&self, method: &str) -> String { 26 26 - format!("{}/xrpc/{}", self.base_url.trim_end_matches('/'), method) 26 26 + let base = self.base_url.trim_end_matches('/'); 27 27 + // Add https:// if no protocol is present 28 28 + let base_with_protocol = if base.starts_with("http://") || base.starts_with("https://") { 29 29 + base.to_string() 30 30 + } else { 31 31 + format!("https://{}", base) 32 32 + }; 33 33 + format!("{}/xrpc/{}", base_with_protocol, method) 27 34 } 28 35 29 36 async fn post_json<TReq: Serialize, TRes: DeserializeOwned>( ··· 49 56 Ok(res.json::<TRes>().await?) 50 57 } 51 58 52 52 - async fn get_json<TRes: DeserializeOwned>( 59 59 + async fn post<TReq: Serialize>( 60 60 + &self, 61 61 + method: &str, 62 62 + req: &TReq, 63 63 + bearer: Option<&str>, 64 64 + ) -> Result<()> { 65 65 + let url = self.xrpc_url(method); 66 66 + let client = reqwest::Client::new(); 67 67 + let mut reqb = client 68 68 + .post(url) 69 69 + .header(reqwest::header::CONTENT_TYPE, "application/json"); 70 70 + if let Some(token) = bearer { 71 71 + reqb = reqb.header(reqwest::header::AUTHORIZATION, format!("Bearer {}", token)); 72 72 + } 73 73 + let res = reqb.json(req).send().await?; 74 74 + let status = res.status(); 75 75 + if !status.is_success() { 76 76 + let body = res.text().await.unwrap_or_default(); 77 77 + return Err(anyhow!("{}: {}", status, body)); 78 78 + } 79 79 + Ok(()) 80 80 + } 81 81 + 82 82 + pub async fn get_json<TRes: DeserializeOwned>( 53 83 &self, 54 84 method: &str, 55 85 params: &[(&str, String)], ··· 119 149 }) 120 150 } 121 151 152 152 + pub async fn refresh_session(&self, refresh_jwt: &str) -> Result<Session> { 153 153 + #[derive(Deserialize)] 154 154 + struct Res { 155 155 + #[serde(rename = "accessJwt")] 156 156 + access_jwt: String, 157 157 + #[serde(rename = "refreshJwt")] 158 158 + refresh_jwt: String, 159 159 + did: String, 160 160 + handle: String, 161 161 + } 162 162 + let url = self.xrpc_url("com.atproto.server.refreshSession"); 163 163 + let client = reqwest::Client::new(); 164 164 + let res = client 165 165 + .post(url) 166 166 + .header(reqwest::header::AUTHORIZATION, format!("Bearer {}", refresh_jwt)) 167 167 + .send() 168 168 + .await?; 169 169 + let status = res.status(); 170 170 + if !status.is_success() { 171 171 + let body = res.text().await.unwrap_or_default(); 172 172 + return Err(anyhow!("{}: {}", status, body)); 173 173 + } 174 174 + let res_data: Res = res.json().await?; 175 175 + Ok(Session { 176 176 + access_jwt: res_data.access_jwt, 177 177 + refresh_jwt: res_data.refresh_jwt, 178 178 + did: res_data.did, 179 179 + handle: res_data.handle, 180 180 + ..Default::default() 181 181 + }) 182 182 + } 183 183 + 122 184 pub async fn list_repos( 123 185 &self, 124 186 user: Option<&str>, ··· 264 326 struct GetSARes { 265 327 token: String, 266 328 } 329 329 + // Method-less ServiceAuth tokens must expire within 60 seconds per AT Protocol spec 267 330 let params = [ 268 331 ("aud", audience), 269 269 - ("exp", (chrono::Utc::now().timestamp() + 600).to_string()), 332 332 + ("exp", (chrono::Utc::now().timestamp() + 60).to_string()), 270 333 ]; 271 334 let sa: GetSARes = pds_client 272 335 .get_json( ··· 345 408 rkey, 346 409 knot, 347 410 description: item.value.description, 411 411 + spindle: item.value.spindle, 348 412 }); 349 413 } 350 414 } ··· 389 453 struct GetSARes { 390 454 token: String, 391 455 } 456 456 + // Method-less ServiceAuth tokens must expire within 60 seconds per AT Protocol spec 392 457 let params = [ 393 458 ("aud", audience), 394 394 - ("exp", (chrono::Utc::now().timestamp() + 600).to_string()), 459 459 + ("exp", (chrono::Utc::now().timestamp() + 60).to_string()), 395 460 ]; 396 461 let sa: GetSARes = pds_client 397 462 .get_json( ··· 922 987 Ok(out) 923 988 } 924 989 990 990 + pub async fn list_repo_pulls( 991 991 + &self, 992 992 + repo_at: &str, 993 993 + state: Option<&str>, 994 994 + pds_base: &str, 995 995 + access_jwt: &str, 996 996 + ) -> Result<Vec<RepoPull>> { 997 997 + let sa = self.service_auth_token(pds_base, access_jwt).await?; 998 998 + 999 999 + #[derive(Deserialize)] 1000 1000 + struct Res { 1001 1001 + pulls: Vec<RepoPull>, 1002 1002 + } 1003 1003 + 1004 1004 + let mut params = vec![("repo", repo_at.to_string())]; 1005 1005 + if let Some(s) = state { 1006 1006 + params.push(("state", s.to_string())); 1007 1007 + } 1008 1008 + 1009 1009 + let res: Res = self 1010 1010 + .get_json("sh.tangled.repo.listPulls", &params, Some(&sa)) 1011 1011 + .await?; 1012 1012 + Ok(res.pulls) 1013 1013 + } 1014 1014 + 925 1015 #[allow(clippy::too_many_arguments)] 926 1016 pub async fn create_pull( 927 1017 &self, ··· 1025 1115 key, 1026 1116 value, 1027 1117 }; 1028 1028 - let _: serde_json::Value = self 1029 1029 - .post_json("sh.tangled.repo.addSecret", &body, Some(&sa)) 1030 1030 - .await?; 1031 1031 - Ok(()) 1118 1118 + self.post("sh.tangled.repo.addSecret", &body, Some(&sa)) 1119 1119 + .await 1032 1120 } 1033 1121 1034 1122 pub async fn remove_repo_secret( ··· 1045 1133 key: &'a str, 1046 1134 } 1047 1135 let body = Req { repo: repo_at, key }; 1048 1048 - let _: serde_json::Value = self 1049 1049 - .post_json("sh.tangled.repo.removeSecret", &body, Some(&sa)) 1050 1050 - .await?; 1051 1051 - Ok(()) 1136 1136 + self.post("sh.tangled.repo.removeSecret", &body, Some(&sa)) 1137 1137 + .await 1052 1138 } 1053 1139 1054 1140 async fn service_auth_token(&self, pds_base: &str, access_jwt: &str) -> Result<String> { 1055 1055 - let host = self 1056 1056 - .base_url 1057 1057 - .trim_end_matches('/') 1141 1141 + let base_trimmed = self.base_url.trim_end_matches('/'); 1142 1142 + let host = base_trimmed 1058 1143 .strip_prefix("https://") 1059 1059 - .or_else(|| self.base_url.trim_end_matches('/').strip_prefix("http://")) 1060 1060 - .ok_or_else(|| anyhow!("invalid base_url"))?; 1144 1144 + .or_else(|| base_trimmed.strip_prefix("http://")) 1145 1145 + .unwrap_or(base_trimmed); // If no protocol, use the URL as-is 1061 1146 let audience = format!("did:web:{}", host); 1062 1147 #[derive(Deserialize)] 1063 1148 struct GetSARes { 1064 1149 token: String, 1065 1150 } 1066 1151 let pds = TangledClient::new(pds_base); 1152 1152 + // Method-less ServiceAuth tokens must expire within 60 seconds per AT Protocol spec 1067 1153 let params = [ 1068 1154 ("aud", audience), 1069 1069 - ("exp", (chrono::Utc::now().timestamp() + 600).to_string()), 1155 1155 + ("exp", (chrono::Utc::now().timestamp() + 60).to_string()), 1070 1156 ]; 1071 1157 let sa: GetSARes = pds 1072 1158 .get_json( ··· 1122 1208 .await?; 1123 1209 Self::uri_rkey(&res.uri).ok_or_else(|| anyhow!("missing rkey in pull comment uri")) 1124 1210 } 1211 1211 + 1212 1212 + pub async fn merge_pull( 1213 1213 + &self, 1214 1214 + pull_did: &str, 1215 1215 + pull_rkey: &str, 1216 1216 + repo_did: &str, 1217 1217 + repo_name: &str, 1218 1218 + pds_base: &str, 1219 1219 + access_jwt: &str, 1220 1220 + ) -> Result<()> { 1221 1221 + // Fetch the pull request to get patch and target branch 1222 1222 + let pds_client = TangledClient::new(pds_base); 1223 1223 + let pull = pds_client 1224 1224 + .get_pull_record(pull_did, pull_rkey, Some(access_jwt)) 1225 1225 + .await?; 1226 1226 + 1227 1227 + // Get service auth token for the knot 1228 1228 + let sa = self.service_auth_token(pds_base, access_jwt).await?; 1229 1229 + 1230 1230 + #[derive(Serialize)] 1231 1231 + struct MergeReq<'a> { 1232 1232 + did: &'a str, 1233 1233 + name: &'a str, 1234 1234 + patch: &'a str, 1235 1235 + branch: &'a str, 1236 1236 + #[serde(skip_serializing_if = "Option::is_none")] 1237 1237 + #[serde(rename = "commitMessage")] 1238 1238 + commit_message: Option<&'a str>, 1239 1239 + #[serde(skip_serializing_if = "Option::is_none")] 1240 1240 + #[serde(rename = "commitBody")] 1241 1241 + commit_body: Option<&'a str>, 1242 1242 + } 1243 1243 + 1244 1244 + let commit_body = if pull.body.is_empty() { 1245 1245 + None 1246 1246 + } else { 1247 1247 + Some(pull.body.as_str()) 1248 1248 + }; 1249 1249 + 1250 1250 + // For now, only patch-based PRs can be merged via CLI 1251 1251 + // Branch-based PRs need to be merged via the web interface 1252 1252 + let patch_str = pull.patch.as_deref() 1253 1253 + .ok_or_else(|| anyhow!("Cannot merge branch-based PR via CLI. Please use the web interface."))?; 1254 1254 + 1255 1255 + let req = MergeReq { 1256 1256 + did: repo_did, 1257 1257 + name: repo_name, 1258 1258 + patch: patch_str, 1259 1259 + branch: &pull.target.branch, 1260 1260 + commit_message: Some(&pull.title), 1261 1261 + commit_body, 1262 1262 + }; 1263 1263 + 1264 1264 + let _: serde_json::Value = self 1265 1265 + .post_json("sh.tangled.repo.merge", &req, Some(&sa)) 1266 1266 + .await?; 1267 1267 + Ok(()) 1268 1268 + } 1269 1269 + 1270 1270 + pub async fn update_repo_spindle( 1271 1271 + &self, 1272 1272 + did: &str, 1273 1273 + rkey: &str, 1274 1274 + new_spindle: Option<&str>, 1275 1275 + pds_base: &str, 1276 1276 + access_jwt: &str, 1277 1277 + ) -> Result<()> { 1278 1278 + let pds_client = TangledClient::new(pds_base); 1279 1279 + #[derive(Deserialize, Serialize, Clone)] 1280 1280 + struct Rec { 1281 1281 + name: String, 1282 1282 + knot: String, 1283 1283 + #[serde(skip_serializing_if = "Option::is_none")] 1284 1284 + description: Option<String>, 1285 1285 + #[serde(skip_serializing_if = "Option::is_none")] 1286 1286 + spindle: Option<String>, 1287 1287 + #[serde(rename = "createdAt")] 1288 1288 + created_at: String, 1289 1289 + } 1290 1290 + #[derive(Deserialize)] 1291 1291 + struct GetRes { 1292 1292 + value: Rec, 1293 1293 + } 1294 1294 + let params = [ 1295 1295 + ("repo", did.to_string()), 1296 1296 + ("collection", "sh.tangled.repo".to_string()), 1297 1297 + ("rkey", rkey.to_string()), 1298 1298 + ]; 1299 1299 + let got: GetRes = pds_client 1300 1300 + .get_json("com.atproto.repo.getRecord", &params, Some(access_jwt)) 1301 1301 + .await?; 1302 1302 + let mut rec = got.value; 1303 1303 + rec.spindle = new_spindle.map(|s| s.to_string()); 1304 1304 + #[derive(Serialize)] 1305 1305 + struct PutReq<'a> { 1306 1306 + repo: &'a str, 1307 1307 + collection: &'a str, 1308 1308 + rkey: &'a str, 1309 1309 + validate: bool, 1310 1310 + record: Rec, 1311 1311 + } 1312 1312 + let req = PutReq { 1313 1313 + repo: did, 1314 1314 + collection: "sh.tangled.repo", 1315 1315 + rkey, 1316 1316 + validate: true, 1317 1317 + record: rec, 1318 1318 + }; 1319 1319 + let _: serde_json::Value = pds_client 1320 1320 + .post_json("com.atproto.repo.putRecord", &req, Some(access_jwt)) 1321 1321 + .await?; 1322 1322 + Ok(()) 1323 1323 + } 1324 1324 + 1325 1325 + pub async fn list_pipelines( 1326 1326 + &self, 1327 1327 + repo_did: &str, 1328 1328 + bearer: Option<&str>, 1329 1329 + ) -> Result<Vec<PipelineRecord>> { 1330 1330 + #[derive(Deserialize)] 1331 1331 + struct Item { 1332 1332 + uri: String, 1333 1333 + value: Pipeline, 1334 1334 + } 1335 1335 + #[derive(Deserialize)] 1336 1336 + struct ListRes { 1337 1337 + #[serde(default)] 1338 1338 + records: Vec<Item>, 1339 1339 + } 1340 1340 + let params = vec![ 1341 1341 + ("repo", repo_did.to_string()), 1342 1342 + ("collection", "sh.tangled.pipeline".to_string()), 1343 1343 + ("limit", "100".to_string()), 1344 1344 + ]; 1345 1345 + let res: ListRes = self 1346 1346 + .get_json("com.atproto.repo.listRecords", &params, bearer) 1347 1347 + .await?; 1348 1348 + let mut out = vec![]; 1349 1349 + for it in res.records { 1350 1350 + let rkey = Self::uri_rkey(&it.uri).unwrap_or_default(); 1351 1351 + out.push(PipelineRecord { 1352 1352 + rkey, 1353 1353 + pipeline: it.value, 1354 1354 + }); 1355 1355 + } 1356 1356 + Ok(out) 1357 1357 + } 1125 1358 } 1126 1359 1127 1360 #[derive(Debug, Clone, Serialize, Deserialize, Default)] ··· 1131 1364 pub name: String, 1132 1365 pub knot: Option<String>, 1133 1366 pub description: Option<String>, 1367 1367 + pub spindle: Option<String>, 1134 1368 #[serde(default)] 1135 1369 pub private: bool, 1136 1370 } ··· 1161 1395 } 1162 1396 1163 1397 #[derive(Debug, Clone, Serialize, Deserialize)] 1398 1398 + pub struct PullSource { 1399 1399 + pub sha: String, 1400 1400 + #[serde(default)] 1401 1401 + pub repo: Option<String>, 1402 1402 + #[serde(default)] 1403 1403 + pub branch: Option<String>, 1404 1404 + } 1405 1405 + 1406 1406 + #[derive(Debug, Clone, Serialize, Deserialize)] 1164 1407 pub struct Pull { 1165 1408 pub target: PullTarget, 1166 1409 pub title: String, 1167 1410 #[serde(default)] 1168 1411 pub body: String, 1169 1169 - pub patch: String, 1412 1412 + #[serde(default)] 1413 1413 + pub patch: Option<String>, 1414 1414 + #[serde(default)] 1415 1415 + pub source: Option<PullSource>, 1170 1416 #[serde(rename = "createdAt")] 1171 1417 pub created_at: String, 1172 1418 } ··· 1178 1424 pub pull: Pull, 1179 1425 } 1180 1426 1427 1427 + #[derive(Debug, Clone, Deserialize)] 1428 1428 + pub struct RepoPull { 1429 1429 + pub rkey: String, 1430 1430 + #[serde(rename = "ownerDid")] 1431 1431 + pub owner_did: String, 1432 1432 + #[serde(rename = "pullId")] 1433 1433 + pub pull_id: i32, 1434 1434 + pub title: String, 1435 1435 + pub state: i32, 1436 1436 + #[serde(rename = "targetBranch")] 1437 1437 + pub target_branch: String, 1438 1438 + #[serde(rename = "createdAt")] 1439 1439 + pub created_at: String, 1440 1440 + } 1441 1441 + 1181 1442 #[derive(Debug, Clone)] 1182 1443 pub struct RepoRecord { 1183 1444 pub did: String, ··· 1185 1446 pub rkey: String, 1186 1447 pub knot: String, 1187 1448 pub description: Option<String>, 1449 1449 + pub spindle: Option<String>, 1188 1450 } 1189 1451 1190 1452 #[derive(Debug, Clone, Serialize, Deserialize)] ··· 1242 1504 pub pds_base: &'a str, 1243 1505 pub access_jwt: &'a str, 1244 1506 } 1507 1507 + 1508 1508 + #[derive(Debug, Clone, Serialize, Deserialize)] 1509 1509 + pub struct TriggerMetadata { 1510 1510 + pub kind: String, 1511 1511 + pub repo: TriggerRepo, 1512 1512 + } 1513 1513 + 1514 1514 + #[derive(Debug, Clone, Serialize, Deserialize)] 1515 1515 + pub struct TriggerRepo { 1516 1516 + pub knot: String, 1517 1517 + pub did: String, 1518 1518 + pub repo: String, 1519 1519 + #[serde(rename = "defaultBranch")] 1520 1520 + pub default_branch: String, 1521 1521 + } 1522 1522 + 1523 1523 + #[derive(Debug, Clone, Serialize, Deserialize)] 1524 1524 + pub struct Workflow { 1525 1525 + pub name: String, 1526 1526 + pub engine: String, 1527 1527 + } 1528 1528 + 1529 1529 + #[derive(Debug, Clone, Serialize, Deserialize)] 1530 1530 + pub struct Pipeline { 1531 1531 + #[serde(rename = "triggerMetadata")] 1532 1532 + pub trigger_metadata: TriggerMetadata, 1533 1533 + pub workflows: Vec<Workflow>, 1534 1534 + } 1535 1535 + 1536 1536 + #[derive(Debug, Clone)] 1537 1537 + pub struct PipelineRecord { 1538 1538 + pub rkey: String, 1539 1539 + pub pipeline: Pipeline, 1540 1540 + }

+3

crates/tangled-cli/Cargo.toml

··· 16 16 tokio = { workspace = true, features = ["full"] } 17 17 git2 = { workspace = true } 18 18 url = { workspace = true } 19 19 + tokio-tungstenite = { workspace = true } 20 20 + futures-util = { workspace = true } 21 21 + chrono = { workspace = true } 19 22 20 23 # Internal crates 21 24 tangled-config = { path = "../tangled-config" }

+1 -41

crates/tangled-cli/src/cli.rs

··· 284 284 #[derive(Args, Debug, Clone)] 285 285 pub struct PrMergeArgs { 286 286 pub id: String, 287 287 - #[arg(long, default_value_t = false)] 288 288 - pub squash: bool, 289 289 - #[arg(long, default_value_t = false)] 290 290 - pub rebase: bool, 291 291 - #[arg(long, default_value_t = false)] 292 292 - pub no_ff: bool, 293 287 } 294 288 295 289 #[derive(Subcommand, Debug, Clone)] 296 290 pub enum KnotCommand { 297 297 - List(KnotListArgs), 298 298 - Add(KnotAddArgs), 299 299 - Verify(KnotVerifyArgs), 300 300 - SetDefault(KnotRefArgs), 301 301 - Remove(KnotRefArgs), 302 291 /// Migrate a repository to another knot 303 292 Migrate(KnotMigrateArgs), 304 304 - } 305 305 - 306 306 - #[derive(Args, Debug, Clone)] 307 307 - pub struct KnotListArgs { 308 308 - #[arg(long, default_value_t = false)] 309 309 - pub public: bool, 310 310 - #[arg(long, default_value_t = false)] 311 311 - pub owned: bool, 312 312 - } 313 313 - 314 314 - #[derive(Args, Debug, Clone)] 315 315 - pub struct KnotAddArgs { 316 316 - pub url: String, 317 317 - #[arg(long)] 318 318 - pub did: Option<String>, 319 319 - #[arg(long)] 320 320 - pub name: Option<String>, 321 321 - #[arg(long, default_value_t = false)] 322 322 - pub verify: bool, 323 323 - } 324 324 - 325 325 - #[derive(Args, Debug, Clone)] 326 326 - pub struct KnotVerifyArgs { 327 327 - pub url: String, 328 328 - } 329 329 - 330 330 - #[derive(Args, Debug, Clone)] 331 331 - pub struct KnotRefArgs { 332 332 - pub url: String, 333 293 } 334 294 335 295 #[derive(Args, Debug, Clone)] ··· 421 381 /// Secret key 422 382 #[arg(long)] 423 383 pub key: String, 424 424 - /// Secret value 384 384 + /// Secret value (use '@filename' to read from file, '-' to read from stdin) 425 385 #[arg(long)] 426 386 pub value: String, 427 387 }

+5 -21

crates/tangled-cli/src/commands/issue.rs

··· 4 4 }; 5 5 use anyhow::{anyhow, Result}; 6 6 use tangled_api::Issue; 7 7 - use tangled_config::session::SessionManager; 8 7 9 8 pub async fn run(_cli: &Cli, cmd: IssueCommand) -> Result<()> { 10 9 match cmd { ··· 17 16 } 18 17 19 18 async fn list(args: IssueListArgs) -> Result<()> { 20 20 - let mgr = SessionManager::default(); 21 21 - let session = mgr 22 22 - .load()? 23 23 - .ok_or_else(|| anyhow!("Please login first: tangled auth login"))?; 19 19 + let session = crate::util::load_session_with_refresh().await?; 24 20 let pds = session 25 21 .pds 26 22 .clone() ··· 57 53 } 58 54 59 55 async fn create(args: IssueCreateArgs) -> Result<()> { 60 60 - let mgr = SessionManager::default(); 61 61 - let session = mgr 62 62 - .load()? 63 63 - .ok_or_else(|| anyhow!("Please login first: tangled auth login"))?; 56 56 + let session = crate::util::load_session_with_refresh().await?; 64 57 let pds = session 65 58 .pds 66 59 .clone() ··· 97 90 98 91 async fn show(args: IssueShowArgs) -> Result<()> { 99 92 // For now, show only accepts at-uri or did:rkey or rkey (for your DID) 100 100 - let mgr = SessionManager::default(); 101 101 - let session = mgr 102 102 - .load()? 103 103 - .ok_or_else(|| anyhow!("Please login first: tangled auth login"))?; 93 93 + let session = crate::util::load_session_with_refresh().await?; 104 94 let id = args.id; 105 95 let (did, rkey) = parse_record_id(&id, &session.did)?; 106 96 let pds = session ··· 129 119 130 120 async fn edit(args: IssueEditArgs) -> Result<()> { 131 121 // Simple edit: fetch existing record and putRecord with new title/body 132 132 - let mgr = SessionManager::default(); 133 133 - let session = mgr 134 134 - .load()? 135 135 - .ok_or_else(|| anyhow!("Please login first: tangled auth login"))?; 122 122 + let session = crate::util::load_session_with_refresh().await?; 136 123 let (did, rkey) = parse_record_id(&args.id, &session.did)?; 137 124 let pds = session 138 125 .pds ··· 183 170 } 184 171 185 172 async fn comment(args: IssueCommentArgs) -> Result<()> { 186 186 - let mgr = SessionManager::default(); 187 187 - let session = mgr 188 188 - .load()? 189 189 - .ok_or_else(|| anyhow!("Please login first: tangled auth login"))?; 173 173 + let session = crate::util::load_session_with_refresh().await?; 190 174 let (did, rkey) = parse_record_id(&args.id, &session.did)?; 191 175 let pds = session 192 176 .pds

+2 -44

crates/tangled-cli/src/commands/knot.rs

··· 1 1 - use crate::cli::{ 2 2 - Cli, KnotAddArgs, KnotCommand, KnotListArgs, KnotMigrateArgs, KnotRefArgs, KnotVerifyArgs, 3 3 - }; 1 1 + use crate::cli::{Cli, KnotCommand, KnotMigrateArgs}; 4 2 use anyhow::anyhow; 5 3 use anyhow::Result; 6 4 use git2::{Direction, Repository as GitRepository, StatusOptions}; 7 5 use std::path::Path; 8 8 - use tangled_config::session::SessionManager; 9 6 10 7 pub async fn run(_cli: &Cli, cmd: KnotCommand) -> Result<()> { 11 8 match cmd { 12 12 - KnotCommand::List(args) => list(args).await, 13 13 - KnotCommand::Add(args) => add(args).await, 14 14 - KnotCommand::Verify(args) => verify(args).await, 15 15 - KnotCommand::SetDefault(args) => set_default(args).await, 16 16 - KnotCommand::Remove(args) => remove(args).await, 17 9 KnotCommand::Migrate(args) => migrate(args).await, 18 10 } 19 11 } 20 12 21 21 - async fn list(args: KnotListArgs) -> Result<()> { 22 22 - println!( 23 23 - "Knot list (stub) public={} owned={}", 24 24 - args.public, args.owned 25 25 - ); 26 26 - Ok(()) 27 27 - } 28 28 - 29 29 - async fn add(args: KnotAddArgs) -> Result<()> { 30 30 - println!( 31 31 - "Knot add (stub) url={} did={:?} name={:?} verify={}", 32 32 - args.url, args.did, args.name, args.verify 33 33 - ); 34 34 - Ok(()) 35 35 - } 36 36 - 37 37 - async fn verify(args: KnotVerifyArgs) -> Result<()> { 38 38 - println!("Knot verify (stub) url={}", args.url); 39 39 - Ok(()) 40 40 - } 41 41 - 42 42 - async fn set_default(args: KnotRefArgs) -> Result<()> { 43 43 - println!("Knot set-default (stub) url={}", args.url); 44 44 - Ok(()) 45 45 - } 46 46 - 47 47 - async fn remove(args: KnotRefArgs) -> Result<()> { 48 48 - println!("Knot remove (stub) url={}", args.url); 49 49 - Ok(()) 50 50 - } 51 51 - 52 13 async fn migrate(args: KnotMigrateArgs) -> Result<()> { 53 53 - let mgr = SessionManager::default(); 54 54 - let session = mgr 55 55 - .load()? 56 56 - .ok_or_else(|| anyhow!("Please login first: tangled auth login"))?; 14 14 + let session = crate::util::load_session_with_refresh().await?; 57 15 // 1) Ensure we're inside a git repository and working tree is clean 58 16 let repo = GitRepository::discover(Path::new("."))?; 59 17 let mut status_opts = StatusOptions::new();

+122 -38

crates/tangled-cli/src/commands/pr.rs

··· 2 2 use anyhow::{anyhow, Result}; 3 3 use std::path::Path; 4 4 use std::process::Command; 5 5 - use tangled_config::session::SessionManager; 6 5 7 6 pub async fn run(_cli: &Cli, cmd: PrCommand) -> Result<()> { 8 7 match cmd { ··· 15 14 } 16 15 17 16 async fn list(args: PrListArgs) -> Result<()> { 18 18 - let mgr = SessionManager::default(); 19 19 - let session = mgr 20 20 - .load()? 21 21 - .ok_or_else(|| anyhow!("Please login first: tangled auth login"))?; 17 17 + let session = crate::util::load_session_with_refresh().await?; 22 18 let pds = session 23 19 .pds 24 20 .clone() 25 21 .or_else(|| std::env::var("TANGLED_PDS_BASE").ok()) 26 22 .unwrap_or_else(|| "https://bsky.social".into()); 27 23 let client = tangled_api::TangledClient::new(&pds); 28 28 - let target_repo_at = if let Some(repo) = &args.repo { 24 24 + 25 25 + // NEW: If --repo is specified, use the new API to list all PRs for that repo 26 26 + if let Some(repo) = &args.repo { 29 27 let (owner, name) = parse_repo_ref(repo, &session.handle); 30 28 let info = client 31 29 .get_repo_info(owner, name, Some(session.access_jwt.as_str())) 32 30 .await?; 33 33 - Some(format!("at://{}/sh.tangled.repo/{}", info.did, info.rkey)) 34 34 - } else { 35 35 - None 36 36 - }; 37 37 - let pulls = client 38 38 - .list_pulls( 39 39 - &session.did, 40 40 - target_repo_at.as_deref(), 41 41 - Some(session.access_jwt.as_str()), 42 42 - ) 43 43 - .await?; 44 44 - if pulls.is_empty() { 45 45 - println!("No pull requests found (showing only those you created)"); 31 31 + let repo_at = format!("at://{}/sh.tangled.repo/{}", info.did, info.rkey); 32 32 + 33 33 + // Use Tangled API (tngl.sh) instead of PDS for aggregated query 34 34 + let api_client = tangled_api::TangledClient::default(); 35 35 + let state = args.state.as_deref(); 36 36 + let pulls = api_client 37 37 + .list_repo_pulls(&repo_at, state, &pds, &session.access_jwt) 38 38 + .await?; 39 39 + 40 40 + if pulls.is_empty() { 41 41 + println!("No pull requests found for this repository"); 42 42 + } else { 43 43 + println!("OWNER\tID\tTITLE\tSTATE"); 44 44 + for pr in pulls { 45 45 + let state_str = match pr.state { 46 46 + 1 => "open", 47 47 + 0 => "closed", 48 48 + 2 => "merged", 49 49 + _ => "unknown", 50 50 + }; 51 51 + println!("{}\t{}\t{}\t{}", pr.owner_did, pr.pull_id, pr.title, state_str); 52 52 + } 53 53 + } 46 54 } else { 47 47 - println!("RKEY\tTITLE\tTARGET"); 48 48 - for pr in pulls { 49 49 - println!("{}\t{}\t{}", pr.rkey, pr.pull.title, pr.pull.target.repo); 55 55 + // OLD: Without --repo, show only user's PRs (existing behavior) 56 56 + let pulls = client 57 57 + .list_pulls( 58 58 + &session.did, 59 59 + None, 60 60 + Some(session.access_jwt.as_str()), 61 61 + ) 62 62 + .await?; 63 63 + if pulls.is_empty() { 64 64 + println!("No pull requests found (showing only those you created)"); 65 65 + } else { 66 66 + println!("RKEY\tTITLE\tTARGET"); 67 67 + for pr in pulls { 68 68 + println!("{}\t{}\t{}", pr.rkey, pr.pull.title, pr.pull.target.repo); 69 69 + } 50 70 } 51 71 } 52 72 Ok(()) ··· 54 74 55 75 async fn create(args: PrCreateArgs) -> Result<()> { 56 76 // Must be run inside the repo checkout; we will use git format-patch to build the patch 57 57 - let mgr = SessionManager::default(); 58 58 - let session = mgr 59 59 - .load()? 60 60 - .ok_or_else(|| anyhow!("Please login first: tangled auth login"))?; 77 77 + let session = crate::util::load_session_with_refresh().await?; 61 78 let pds = session 62 79 .pds 63 80 .clone() ··· 126 143 } 127 144 128 145 async fn show(args: PrShowArgs) -> Result<()> { 129 129 - let mgr = SessionManager::default(); 130 130 - let session = mgr 131 131 - .load()? 132 132 - .ok_or_else(|| anyhow!("Please login first: tangled auth login"))?; 146 146 + let session = crate::util::load_session_with_refresh().await?; 133 147 let (did, rkey) = parse_record_id(&args.id, &session.did)?; 134 148 let pds = session 135 149 .pds ··· 145 159 println!("BODY:\n{}", pr.body); 146 160 } 147 161 println!("TARGET: {} @ {}", pr.target.repo, pr.target.branch); 162 162 + 163 163 + // Display source info if it's a branch-based PR 164 164 + if let Some(source) = &pr.source { 165 165 + println!("SOURCE: {} ({})", source.sha, 166 166 + source.branch.as_deref().unwrap_or("detached")); 167 167 + if let Some(repo) = &source.repo { 168 168 + println!("SOURCE REPO: {}", repo); 169 169 + } 170 170 + } 171 171 + 148 172 if args.diff { 149 149 - println!("PATCH:\n{}", pr.patch); 173 173 + if let Some(patch) = &pr.patch { 174 174 + println!("PATCH:\n{}", patch); 175 175 + } else { 176 176 + println!("(No patch available - this is a branch-based PR)"); 177 177 + } 150 178 } 151 179 Ok(()) 152 180 } 153 181 154 182 async fn review(args: PrReviewArgs) -> Result<()> { 155 155 - let mgr = SessionManager::default(); 156 156 - let session = mgr 157 157 - .load()? 158 158 - .ok_or_else(|| anyhow!("Please login first: tangled auth login"))?; 183 183 + let session = crate::util::load_session_with_refresh().await?; 159 184 let (did, rkey) = parse_record_id(&args.id, &session.did)?; 160 185 let pds = session 161 186 .pds ··· 183 208 Ok(()) 184 209 } 185 210 186 186 - async fn merge(_args: PrMergeArgs) -> Result<()> { 187 187 - // Placeholder: merging requires server-side merge call with the patch and target branch. 188 188 - println!("Merge via CLI is not implemented yet. Use the web UI for now."); 211 211 + async fn merge(args: PrMergeArgs) -> Result<()> { 212 212 + let session = crate::util::load_session_with_refresh().await?; 213 213 + let (did, rkey) = parse_record_id(&args.id, &session.did)?; 214 214 + let pds = session 215 215 + .pds 216 216 + .clone() 217 217 + .or_else(|| std::env::var("TANGLED_PDS_BASE").ok()) 218 218 + .unwrap_or_else(|| "https://bsky.social".into()); 219 219 + 220 220 + // Get the PR to find the target repo 221 221 + let pds_client = tangled_api::TangledClient::new(&pds); 222 222 + let pull = pds_client 223 223 + .get_pull_record(&did, &rkey, Some(session.access_jwt.as_str())) 224 224 + .await?; 225 225 + 226 226 + // Parse the target repo AT-URI to get did and name 227 227 + let target_repo = &pull.target.repo; 228 228 + // Format: at://did:plc:.../sh.tangled.repo/rkey 229 229 + let parts: Vec<&str> = target_repo.strip_prefix("at://").unwrap_or(target_repo).split('/').collect(); 230 230 + if parts.len() < 2 { 231 231 + return Err(anyhow!("Invalid target repo AT-URI: {}", target_repo)); 232 232 + } 233 233 + let repo_did = parts[0]; 234 234 + 235 235 + // Get repo info to find the name 236 236 + // Parse rkey from target repo AT-URI 237 237 + let repo_rkey = if parts.len() >= 4 { 238 238 + parts[3] 239 239 + } else { 240 240 + return Err(anyhow!("Invalid target repo AT-URI: {}", target_repo)); 241 241 + }; 242 242 + 243 243 + #[derive(serde::Deserialize)] 244 244 + struct Rec { 245 245 + name: String, 246 246 + } 247 247 + #[derive(serde::Deserialize)] 248 248 + struct GetRes { 249 249 + value: Rec, 250 250 + } 251 251 + let params = [ 252 252 + ("repo", repo_did.to_string()), 253 253 + ("collection", "sh.tangled.repo".to_string()), 254 254 + ("rkey", repo_rkey.to_string()), 255 255 + ]; 256 256 + let repo_rec: GetRes = pds_client 257 257 + .get_json("com.atproto.repo.getRecord", &params, Some(session.access_jwt.as_str())) 258 258 + .await?; 259 259 + 260 260 + // Call merge on the default Tangled API base (tngl.sh) 261 261 + let api = tangled_api::TangledClient::default(); 262 262 + api.merge_pull( 263 263 + &did, 264 264 + &rkey, 265 265 + repo_did, 266 266 + &repo_rec.value.name, 267 267 + &pds, 268 268 + &session.access_jwt, 269 269 + ) 270 270 + .await?; 271 271 + 272 272 + println!("Merged PR {}:{}", did, rkey); 189 273 Ok(()) 190 274 } 191 275

+12 -31

crates/tangled-cli/src/commands/repo.rs

··· 2 2 use git2::{build::RepoBuilder, Cred, FetchOptions, RemoteCallbacks}; 3 3 use serde_json; 4 4 use std::path::PathBuf; 5 5 - use tangled_config::session::SessionManager; 6 5 7 6 use crate::cli::{ 8 7 Cli, OutputFormat, RepoCloneArgs, RepoCommand, RepoCreateArgs, RepoDeleteArgs, RepoInfoArgs, ··· 22 21 } 23 22 24 23 async fn list(cli: &Cli, args: RepoListArgs) -> Result<()> { 25 25 - let mgr = SessionManager::default(); 26 26 - let session = match mgr.load()? { 27 27 - Some(s) => s, 28 28 - None => return Err(anyhow!("Please login first: tangled auth login")), 29 29 - }; 24 24 + let session = crate::util::load_session_with_refresh().await?; 30 25 31 26 // Use the PDS to list repo records for the user 32 27 let pds = session ··· 63 58 } 64 59 65 60 async fn create(args: RepoCreateArgs) -> Result<()> { 66 66 - let mgr = SessionManager::default(); 67 67 - let session = match mgr.load()? { 68 68 - Some(s) => s, 69 69 - None => return Err(anyhow!("Please login first: tangled auth login")), 70 70 - }; 61 61 + let session = crate::util::load_session_with_refresh().await?; 71 62 72 63 let base = std::env::var("TANGLED_API_BASE").unwrap_or_else(|_| "https://tngl.sh".into()); 73 64 let client = tangled_api::TangledClient::new(base); ··· 97 88 } 98 89 99 90 async fn clone(args: RepoCloneArgs) -> Result<()> { 100 100 - let mgr = SessionManager::default(); 101 101 - let session = mgr 102 102 - .load()? 103 103 - .ok_or_else(|| anyhow!("Please login first: tangled auth login"))?; 91 91 + let session = crate::util::load_session_with_refresh().await?; 104 92 105 93 let (owner, name) = parse_repo_ref(&args.repo, &session.handle); 106 94 let pds = session ··· 164 152 } 165 153 166 154 async fn info(args: RepoInfoArgs) -> Result<()> { 167 167 - let mgr = SessionManager::default(); 168 168 - let session = mgr 169 169 - .load()? 170 170 - .ok_or_else(|| anyhow!("Please login first: tangled auth login"))?; 155 155 + let session = crate::util::load_session_with_refresh().await?; 171 156 let (owner, name) = parse_repo_ref(&args.repo, &session.handle); 172 157 let pds = session 173 158 .pds ··· 182 167 println!("NAME: {}", info.name); 183 168 println!("OWNER DID: {}", info.did); 184 169 println!("KNOT: {}", info.knot); 170 170 + if let Some(spindle) = info.spindle.as_deref() { 171 171 + if !spindle.is_empty() { 172 172 + println!("SPINDLE: {}", spindle); 173 173 + } 174 174 + } 185 175 if let Some(desc) = info.description.as_deref() { 186 176 if !desc.is_empty() { 187 177 println!("DESCRIPTION: {}", desc); ··· 230 220 } 231 221 232 222 async fn delete(args: RepoDeleteArgs) -> Result<()> { 233 233 - let mgr = SessionManager::default(); 234 234 - let session = mgr 235 235 - .load()? 236 236 - .ok_or_else(|| anyhow!("Please login first: tangled auth login"))?; 223 223 + let session = crate::util::load_session_with_refresh().await?; 237 224 let (owner, name) = parse_repo_ref(&args.repo, &session.handle); 238 225 let pds = session 239 226 .pds ··· 253 240 } 254 241 255 242 async fn star(args: RepoRefArgs) -> Result<()> { 256 256 - let mgr = SessionManager::default(); 257 257 - let session = mgr 258 258 - .load()? 259 259 - .ok_or_else(|| anyhow!("Please login first: tangled auth login"))?; 243 243 + let session = crate::util::load_session_with_refresh().await?; 260 244 let (owner, name) = parse_repo_ref(&args.repo, &session.handle); 261 245 let pds = session 262 246 .pds ··· 276 260 } 277 261 278 262 async fn unstar(args: RepoRefArgs) -> Result<()> { 279 279 - let mgr = SessionManager::default(); 280 280 - let session = mgr 281 281 - .load()? 282 282 - .ok_or_else(|| anyhow!("Please login first: tangled auth login"))?; 263 263 + let session = crate::util::load_session_with_refresh().await?; 283 264 let (owner, name) = parse_repo_ref(&args.repo, &session.handle); 284 265 let pds = session 285 266 .pds

+204 -25

crates/tangled-cli/src/commands/spindle.rs

··· 3 3 SpindleSecretAddArgs, SpindleSecretCommand, SpindleSecretListArgs, SpindleSecretRemoveArgs, 4 4 }; 5 5 use anyhow::{anyhow, Result}; 6 6 - use tangled_config::session::SessionManager; 6 6 + use futures_util::StreamExt; 7 7 + use tokio_tungstenite::{connect_async, tungstenite::Message}; 7 8 8 9 pub async fn run(_cli: &Cli, cmd: SpindleCommand) -> Result<()> { 9 10 match cmd { ··· 16 17 } 17 18 18 19 async fn list(args: SpindleListArgs) -> Result<()> { 19 19 - println!("Spindle list (stub) repo={:?}", args.repo); 20 20 + let session = crate::util::load_session_with_refresh().await?; 21 21 + 22 22 + let pds = session 23 23 + .pds 24 24 + .clone() 25 25 + .or_else(|| std::env::var("TANGLED_PDS_BASE").ok()) 26 26 + .unwrap_or_else(|| "https://bsky.social".into()); 27 27 + let pds_client = tangled_api::TangledClient::new(&pds); 28 28 + 29 29 + let (owner, name) = parse_repo_ref( 30 30 + args.repo.as_deref().unwrap_or(&session.handle), 31 31 + &session.handle 32 32 + ); 33 33 + let info = pds_client 34 34 + .get_repo_info(owner, name, Some(session.access_jwt.as_str())) 35 35 + .await?; 36 36 + 37 37 + let pipelines = pds_client 38 38 + .list_pipelines(&info.did, Some(session.access_jwt.as_str())) 39 39 + .await?; 40 40 + 41 41 + if pipelines.is_empty() { 42 42 + println!("No pipelines found for {}/{}", owner, name); 43 43 + } else { 44 44 + println!("RKEY\tKIND\tREPO\tWORKFLOWS"); 45 45 + for p in pipelines { 46 46 + let workflows = p.pipeline.workflows 47 47 + .iter() 48 48 + .map(|w| w.name.as_str()) 49 49 + .collect::<Vec<_>>() 50 50 + .join(","); 51 51 + println!( 52 52 + "{}\t{}\t{}\t{}", 53 53 + p.rkey, 54 54 + p.pipeline.trigger_metadata.kind, 55 55 + p.pipeline.trigger_metadata.repo.repo, 56 56 + workflows 57 57 + ); 58 58 + } 59 59 + } 20 60 Ok(()) 21 61 } 22 62 23 63 async fn config(args: SpindleConfigArgs) -> Result<()> { 24 24 - println!( 25 25 - "Spindle config (stub) repo={:?} url={:?} enable={} disable={}", 26 26 - args.repo, args.url, args.enable, args.disable 64 64 + let session = crate::util::load_session_with_refresh().await?; 65 65 + 66 66 + if args.enable && args.disable { 67 67 + return Err(anyhow!("Cannot use --enable and --disable together")); 68 68 + } 69 69 + 70 70 + if !args.enable && !args.disable && args.url.is_none() { 71 71 + return Err(anyhow!( 72 72 + "Must provide --enable, --disable, or --url" 73 73 + )); 74 74 + } 75 75 + 76 76 + let pds = session 77 77 + .pds 78 78 + .clone() 79 79 + .or_else(|| std::env::var("TANGLED_PDS_BASE").ok()) 80 80 + .unwrap_or_else(|| "https://bsky.social".into()); 81 81 + let pds_client = tangled_api::TangledClient::new(&pds); 82 82 + 83 83 + let (owner, name) = parse_repo_ref( 84 84 + args.repo.as_deref().unwrap_or(&session.handle), 85 85 + &session.handle 27 86 ); 87 87 + let info = pds_client 88 88 + .get_repo_info(owner, name, Some(session.access_jwt.as_str())) 89 89 + .await?; 90 90 + 91 91 + let new_spindle = if args.disable { 92 92 + None 93 93 + } else if let Some(url) = args.url.as_deref() { 94 94 + Some(url) 95 95 + } else if args.enable { 96 96 + // Default spindle URL 97 97 + Some("https://spindle.tangled.sh") 98 98 + } else { 99 99 + return Err(anyhow!("Invalid flags combination")); 100 100 + }; 101 101 + 102 102 + pds_client 103 103 + .update_repo_spindle(&info.did, &info.rkey, new_spindle, &pds, &session.access_jwt) 104 104 + .await?; 105 105 + 106 106 + if args.disable { 107 107 + println!("Disabled spindle for {}/{}", owner, name); 108 108 + } else { 109 109 + println!( 110 110 + "Enabled spindle for {}/{} ({})", 111 111 + owner, 112 112 + name, 113 113 + new_spindle.unwrap_or_default() 114 114 + ); 115 115 + } 28 116 Ok(()) 29 117 } 30 118 ··· 37 125 } 38 126 39 127 async fn logs(args: SpindleLogsArgs) -> Result<()> { 40 40 - println!( 41 41 - "Spindle logs (stub) job_id={} follow={} lines={:?}", 42 42 - args.job_id, args.follow, args.lines 43 43 - ); 128 128 + // Parse job_id: format is "knot:rkey:name" or just "name" (use repo context) 129 129 + let parts: Vec<&str> = args.job_id.split(':').collect(); 130 130 + let (knot, rkey, name) = if parts.len() == 3 { 131 131 + (parts[0].to_string(), parts[1].to_string(), parts[2].to_string()) 132 132 + } else if parts.len() == 1 { 133 133 + // Use repo context - need to get repo info 134 134 + let session = crate::util::load_session_with_refresh().await?; 135 135 + let pds = session 136 136 + .pds 137 137 + .clone() 138 138 + .or_else(|| std::env::var("TANGLED_PDS_BASE").ok()) 139 139 + .unwrap_or_else(|| "https://bsky.social".into()); 140 140 + let pds_client = tangled_api::TangledClient::new(&pds); 141 141 + // Get repo info from current directory context or default to user's handle 142 142 + let info = pds_client 143 143 + .get_repo_info(&session.handle, &session.handle, Some(session.access_jwt.as_str())) 144 144 + .await?; 145 145 + (info.knot, info.rkey, parts[0].to_string()) 146 146 + } else { 147 147 + return Err(anyhow!("Invalid job_id format. Expected 'knot:rkey:name' or 'name'")); 148 148 + }; 149 149 + 150 150 + // Build WebSocket URL - spindle base is typically https://spindle.tangled.sh 151 151 + let spindle_base = std::env::var("TANGLED_SPINDLE_BASE") 152 152 + .unwrap_or_else(|_| "wss://spindle.tangled.sh".to_string()); 153 153 + let ws_url = format!("{}/spindle/logs/{}/{}/{}", spindle_base, knot, rkey, name); 154 154 + 155 155 + println!("Connecting to logs stream for {}:{}:{}...", knot, rkey, name); 156 156 + 157 157 + // Connect to WebSocket 158 158 + let (ws_stream, _) = connect_async(&ws_url).await 159 159 + .map_err(|e| anyhow!("Failed to connect to log stream: {}", e))?; 160 160 + 161 161 + let (mut _write, mut read) = ws_stream.split(); 162 162 + 163 163 + // Stream log messages 164 164 + let mut line_count = 0; 165 165 + let max_lines = args.lines.unwrap_or(usize::MAX); 166 166 + 167 167 + while let Some(msg) = read.next().await { 168 168 + match msg { 169 169 + Ok(Message::Text(text)) => { 170 170 + println!("{}", text); 171 171 + line_count += 1; 172 172 + if line_count >= max_lines { 173 173 + break; 174 174 + } 175 175 + } 176 176 + Ok(Message::Close(_)) => { 177 177 + break; 178 178 + } 179 179 + Err(e) => { 180 180 + return Err(anyhow!("WebSocket error: {}", e)); 181 181 + } 182 182 + _ => {} 183 183 + } 184 184 + } 185 185 + 44 186 Ok(()) 45 187 } 46 188 ··· 53 195 } 54 196 55 197 async fn secret_list(args: SpindleSecretListArgs) -> Result<()> { 56 56 - let mgr = SessionManager::default(); 57 57 - let session = mgr 58 58 - .load()? 59 59 - .ok_or_else(|| anyhow!("Please login first: tangled auth login"))?; 198 198 + let session = crate::util::load_session_with_refresh().await?; 60 199 let pds = session 61 200 .pds 62 201 .clone() ··· 68 207 .get_repo_info(owner, name, Some(session.access_jwt.as_str())) 69 208 .await?; 70 209 let repo_at = format!("at://{}/sh.tangled.repo/{}", info.did, info.rkey); 71 71 - let api = tangled_api::TangledClient::default(); // base tngl.sh 210 210 + 211 211 + // Get spindle base from repo config or use default 212 212 + let spindle_base = info.spindle 213 213 + .clone() 214 214 + .or_else(|| std::env::var("TANGLED_SPINDLE_BASE").ok()) 215 215 + .unwrap_or_else(|| "https://spindle.tangled.sh".to_string()); 216 216 + let api = tangled_api::TangledClient::new(&spindle_base); 217 217 + 72 218 let secrets = api 73 219 .list_repo_secrets(&pds, &session.access_jwt, &repo_at) 74 220 .await?; ··· 84 230 } 85 231 86 232 async fn secret_add(args: SpindleSecretAddArgs) -> Result<()> { 87 87 - let mgr = SessionManager::default(); 88 88 - let session = mgr 89 89 - .load()? 90 90 - .ok_or_else(|| anyhow!("Please login first: tangled auth login"))?; 233 233 + let session = crate::util::load_session_with_refresh().await?; 91 234 let pds = session 92 235 .pds 93 236 .clone() ··· 99 242 .get_repo_info(owner, name, Some(session.access_jwt.as_str())) 100 243 .await?; 101 244 let repo_at = format!("at://{}/sh.tangled.repo/{}", info.did, info.rkey); 102 102 - let api = tangled_api::TangledClient::default(); 103 103 - api.add_repo_secret(&pds, &session.access_jwt, &repo_at, &args.key, &args.value) 245 245 + 246 246 + // Get spindle base from repo config or use default 247 247 + let spindle_base = info.spindle 248 248 + .clone() 249 249 + .or_else(|| std::env::var("TANGLED_SPINDLE_BASE").ok()) 250 250 + .unwrap_or_else(|| "https://spindle.tangled.sh".to_string()); 251 251 + let api = tangled_api::TangledClient::new(&spindle_base); 252 252 + 253 253 + // Handle special value patterns: @file or - (stdin) 254 254 + let value = if args.value == "-" { 255 255 + // Read from stdin 256 256 + use std::io::Read; 257 257 + let mut buffer = String::new(); 258 258 + std::io::stdin().read_to_string(&mut buffer)?; 259 259 + buffer 260 260 + } else if let Some(path) = args.value.strip_prefix('@') { 261 261 + // Read from file, expand ~ if needed 262 262 + let expanded_path = if path.starts_with("~/") { 263 263 + if let Some(home) = std::env::var("HOME").ok() { 264 264 + path.replacen("~/", &format!("{}/", home), 1) 265 265 + } else { 266 266 + path.to_string() 267 267 + } 268 268 + } else { 269 269 + path.to_string() 270 270 + }; 271 271 + std::fs::read_to_string(&expanded_path) 272 272 + .map_err(|e| anyhow!("Failed to read file '{}': {}", expanded_path, e))? 273 273 + } else { 274 274 + // Use value as-is 275 275 + args.value 276 276 + }; 277 277 + 278 278 + api.add_repo_secret(&pds, &session.access_jwt, &repo_at, &args.key, &value) 104 279 .await?; 105 280 println!("Added secret '{}' to {}", args.key, args.repo); 106 281 Ok(()) 107 282 } 108 283 109 284 async fn secret_remove(args: SpindleSecretRemoveArgs) -> Result<()> { 110 110 - let mgr = SessionManager::default(); 111 111 - let session = mgr 112 112 - .load()? 113 113 - .ok_or_else(|| anyhow!("Please login first: tangled auth login"))?; 285 285 + let session = crate::util::load_session_with_refresh().await?; 114 286 let pds = session 115 287 .pds 116 288 .clone() ··· 122 294 .get_repo_info(owner, name, Some(session.access_jwt.as_str())) 123 295 .await?; 124 296 let repo_at = format!("at://{}/sh.tangled.repo/{}", info.did, info.rkey); 125 125 - let api = tangled_api::TangledClient::default(); 297 297 + 298 298 + // Get spindle base from repo config or use default 299 299 + let spindle_base = info.spindle 300 300 + .clone() 301 301 + .or_else(|| std::env::var("TANGLED_SPINDLE_BASE").ok()) 302 302 + .unwrap_or_else(|| "https://spindle.tangled.sh".to_string()); 303 303 + let api = tangled_api::TangledClient::new(&spindle_base); 304 304 + 126 305 api.remove_repo_secret(&pds, &session.access_jwt, &repo_at, &args.key) 127 306 .await?; 128 307 println!("Removed secret '{}' from {}", args.key, args.repo);

+1

crates/tangled-cli/src/main.rs

··· 1 1 mod cli; 2 2 mod commands; 3 3 + mod util; 3 4 4 5 use anyhow::Result; 5 6 use clap::Parser;

+55

crates/tangled-cli/src/util.rs

··· 1 1 + use anyhow::{anyhow, Result}; 2 2 + use tangled_config::session::{Session, SessionManager}; 3 3 + 4 4 + /// Load session and automatically refresh if expired 5 5 + pub async fn load_session() -> Result<Session> { 6 6 + let mgr = SessionManager::default(); 7 7 + let session = mgr 8 8 + .load()? 9 9 + .ok_or_else(|| anyhow!("Please login first: tangled auth login"))?; 10 10 + 11 11 + Ok(session) 12 12 + } 13 13 + 14 14 + /// Refresh the session using the refresh token 15 15 + pub async fn refresh_session(session: &Session) -> Result<Session> { 16 16 + let pds = session 17 17 + .pds 18 18 + .clone() 19 19 + .unwrap_or_else(|| "https://bsky.social".to_string()); 20 20 + 21 21 + let client = tangled_api::TangledClient::new(&pds); 22 22 + let mut new_session = client.refresh_session(&session.refresh_jwt).await?; 23 23 + 24 24 + // Preserve PDS from old session 25 25 + new_session.pds = session.pds.clone(); 26 26 + 27 27 + // Save the refreshed session 28 28 + let mgr = SessionManager::default(); 29 29 + mgr.save(&new_session)?; 30 30 + 31 31 + Ok(new_session) 32 32 + } 33 33 + 34 34 + /// Load session with automatic refresh on ExpiredToken 35 35 + pub async fn load_session_with_refresh() -> Result<Session> { 36 36 + let session = load_session().await?; 37 37 + 38 38 + // Check if session is older than 30 minutes - if so, proactively refresh 39 39 + let age = chrono::Utc::now() 40 40 + .signed_duration_since(session.created_at) 41 41 + .num_minutes(); 42 42 + 43 43 + if age > 30 { 44 44 + // Session is old, proactively refresh 45 45 + match refresh_session(&session).await { 46 46 + Ok(new_session) => return Ok(new_session), 47 47 + Err(_) => { 48 48 + // If refresh fails, try with the old session anyway 49 49 + // It might still work 50 50 + } 51 51 + } 52 52 + } 53 53 + 54 54 + Ok(session) 55 55 + }

+303 -7

docs/getting-started.md

··· 1 1 - # Getting Started 1 1 + # Getting Started with Tangled CLI 2 2 + 3 3 + This guide will help you get up and running with the Tangled CLI. 4 4 + 5 5 + ## Installation 6 6 + 7 7 + ### Prerequisites 8 8 + 9 9 + - Rust toolchain 1.70 or later 10 10 + - Git 11 11 + - A Bluesky/AT Protocol account 12 12 + 13 13 + ### Build from Source 14 14 + 15 15 + 1. Clone the repository: 16 16 + ```sh 17 17 + git clone https://tangled.org/tangled/tangled-cli 18 18 + cd tangled-cli 19 19 + ``` 20 20 + 21 21 + 2. Build the project: 22 22 + ```sh 23 23 + cargo build --release 24 24 + ``` 25 25 + 26 26 + 3. The binary will be available at `target/release/tangled-cli`. Optionally, add it to your PATH or create an alias: 27 27 + ```sh 28 28 + alias tangled='./target/release/tangled-cli' 29 29 + ``` 30 30 + 31 31 + ### Install from AUR (Arch Linux) 32 32 + 33 33 + If you're on Arch Linux, you can install from the AUR: 34 34 + 35 35 + ```sh 36 36 + yay -S tangled-cli-git 37 37 + ``` 38 38 + 39 39 + ## First Steps 40 40 + 41 41 + ### 1. Authenticate 42 42 + 43 43 + Login with your AT Protocol credentials (your Bluesky account): 44 44 + 45 45 + ```sh 46 46 + tangled auth login 47 47 + ``` 48 48 + 49 49 + You'll be prompted for your handle (e.g., `alice.bsky.social`) and password. If you're using a custom PDS, specify it with the `--pds` flag: 50 50 + 51 51 + ```sh 52 52 + tangled auth login --pds https://your-pds.example.com 53 53 + ``` 54 54 + 55 55 + Your credentials are stored securely in your system keyring. 56 56 + 57 57 + ### 2. Check Your Status 58 58 + 59 59 + Verify you're logged in: 60 60 + 61 61 + ```sh 62 62 + tangled auth status 63 63 + ``` 64 64 + 65 65 + ### 3. List Your Repositories 66 66 + 67 67 + See all your repositories: 68 68 + 69 69 + ```sh 70 70 + tangled repo list 71 71 + ``` 72 72 + 73 73 + Or view someone else's public repositories: 74 74 + 75 75 + ```sh 76 76 + tangled repo list --user alice.bsky.social 77 77 + ``` 78 78 + 79 79 + ### 4. Create a Repository 80 80 + 81 81 + Create a new repository on Tangled: 82 82 + 83 83 + ```sh 84 84 + tangled repo create my-project --description "My awesome project" 85 85 + ``` 86 86 + 87 87 + By default, repositories are created on the default knot (`tngl.sh`). You can specify a different knot: 88 88 + 89 89 + ```sh 90 90 + tangled repo create my-project --knot knot1.tangled.sh 91 91 + ``` 92 92 + 93 93 + ### 5. Clone a Repository 94 94 + 95 95 + Clone a repository to start working on it: 96 96 + 97 97 + ```sh 98 98 + tangled repo clone alice/my-project 99 99 + ``` 100 100 + 101 101 + This uses SSH by default. For HTTPS: 102 102 + 103 103 + ```sh 104 104 + tangled repo clone alice/my-project --https 105 105 + ``` 106 106 + 107 107 + ## Working with Issues 108 108 + 109 109 + ### Create an Issue 110 110 + 111 111 + ```sh 112 112 + tangled issue create --repo my-project --title "Add new feature" --body "We should add feature X" 113 113 + ``` 114 114 + 115 115 + ### List Issues 116 116 + 117 117 + ```sh 118 118 + tangled issue list --repo my-project 119 119 + ``` 2 120 3 3 - This project is a scaffold of a Tangled CLI in Rust. The commands are present as stubs and will be wired to XRPC endpoints iteratively. 121 121 + ### View Issue Details 4 122 5 5 - ## Build 123 123 + ```sh 124 124 + tangled issue show <issue-id> 125 125 + ``` 6 126 7 7 - Requires Rust toolchain and network access to fetch dependencies. 127 127 + ### Comment on an Issue 8 128 129 129 + ```sh 130 130 + tangled issue comment <issue-id> --body "I'm working on this!" 9 131 ``` 10 10 - cargo build 132 132 + 133 133 + ## Working with Pull Requests 134 134 + 135 135 + ### Create a Pull Request 136 136 + 137 137 + ```sh 138 138 + tangled pr create --repo my-project --base main --head feature-branch --title "Add feature X" 11 139 ``` 12 140 13 13 - ## Run 141 141 + The CLI will use `git format-patch` to create a patch from your branch. 14 142 143 143 + ### List Pull Requests 144 144 + 145 145 + ```sh 146 146 + tangled pr list --repo my-project 15 147 ``` 16 16 - cargo run -p tangled-cli -- --help 148 148 + 149 149 + ### Review a Pull Request 150 150 + 151 151 + ```sh 152 152 + tangled pr review <pr-id> --approve --comment "Looks good!" 17 153 ``` 18 154 155 155 + Or request changes: 156 156 + 157 157 + ```sh 158 158 + tangled pr review <pr-id> --request-changes --comment "Please fix the tests" 159 159 + ``` 160 160 + 161 161 + ### Merge a Pull Request 162 162 + 163 163 + ```sh 164 164 + tangled pr merge <pr-id> 165 165 + ``` 166 166 + 167 167 + ## CI/CD with Spindle 168 168 + 169 169 + Spindle is Tangled's integrated CI/CD system. 170 170 + 171 171 + ### Enable Spindle for Your Repository 172 172 + 173 173 + ```sh 174 174 + tangled spindle config --repo my-project --enable 175 175 + ``` 176 176 + 177 177 + Or use a custom spindle URL: 178 178 + 179 179 + ```sh 180 180 + tangled spindle config --repo my-project --url https://my-spindle.example.com 181 181 + ``` 182 182 + 183 183 + ### View Pipeline Runs 184 184 + 185 185 + ```sh 186 186 + tangled spindle list --repo my-project 187 187 + ``` 188 188 + 189 189 + ### Stream Workflow Logs 190 190 + 191 191 + ```sh 192 192 + tangled spindle logs knot:rkey:workflow-name 193 193 + ``` 194 194 + 195 195 + Add `--follow` to tail the logs in real-time. 196 196 + 197 197 + ### Manage Secrets 198 198 + 199 199 + Add secrets for your CI/CD workflows: 200 200 + 201 201 + ```sh 202 202 + tangled spindle secret add --repo my-project --key API_KEY --value "my-secret-value" 203 203 + ``` 204 204 + 205 205 + List secrets: 206 206 + 207 207 + ```sh 208 208 + tangled spindle secret list --repo my-project 209 209 + ``` 210 210 + 211 211 + Remove a secret: 212 212 + 213 213 + ```sh 214 214 + tangled spindle secret remove --repo my-project --key API_KEY 215 215 + ``` 216 216 + 217 217 + ## Advanced Topics 218 218 + 219 219 + ### Repository Migration 220 220 + 221 221 + Move a repository to a different knot: 222 222 + 223 223 + ```sh 224 224 + tangled knot migrate --repo my-project --to knot2.tangled.sh 225 225 + ``` 226 226 + 227 227 + This command must be run from within the repository's working directory, and your working tree must be clean and pushed. 228 228 + 229 229 + ### Output Formats 230 230 + 231 231 + Most commands support JSON output: 232 232 + 233 233 + ```sh 234 234 + tangled repo list --format json 235 235 + ``` 236 236 + 237 237 + ### Quiet and Verbose Modes 238 238 + 239 239 + Reduce output: 240 240 + 241 241 + ```sh 242 242 + tangled --quiet repo list 243 243 + ``` 244 244 + 245 245 + Increase verbosity for debugging: 246 246 + 247 247 + ```sh 248 248 + tangled --verbose repo list 249 249 + ``` 250 250 + 251 251 + ## Configuration 252 252 + 253 253 + The CLI stores configuration in: 254 254 + - Linux: `~/.config/tangled/config.toml` 255 255 + - macOS: `~/Library/Application Support/tangled/config.toml` 256 256 + - Windows: `%APPDATA%\tangled\config.toml` 257 257 + 258 258 + Session credentials are stored securely in your system keyring (GNOME Keyring, KWallet, macOS Keychain, or Windows Credential Manager). 259 259 + 260 260 + ### Environment Variables 261 261 + 262 262 + - `TANGLED_PDS_BASE` - Override the default PDS (default: `https://bsky.social`) 263 263 + - `TANGLED_API_BASE` - Override the Tangled API base (default: `https://tngl.sh`) 264 264 + - `TANGLED_SPINDLE_BASE` - Override the Spindle base (default: `wss://spindle.tangled.sh`) 265 265 + 266 266 + ## Troubleshooting 267 267 + 268 268 + ### Keyring Issues on Linux 269 269 + 270 270 + If you see keyring errors on Linux, ensure you have a secret service running: 271 271 + 272 272 + ```sh 273 273 + # For GNOME 274 274 + systemctl --user enable --now gnome-keyring-daemon 275 275 + 276 276 + # For KDE 277 277 + # KWallet should start automatically with Plasma 278 278 + ``` 279 279 + 280 280 + ### Authentication Failures 281 281 + 282 282 + If authentication fails with your custom PDS: 283 283 + 284 284 + ```sh 285 285 + tangled auth login --pds https://your-pds.example.com 286 286 + ``` 287 287 + 288 288 + Make sure the PDS URL is correct and accessible. 289 289 + 290 290 + ### "Repository not found" Errors 291 291 + 292 292 + Verify the repository exists and you have access: 293 293 + 294 294 + ```sh 295 295 + tangled repo info owner/reponame 296 296 + ``` 297 297 + 298 298 + ## Getting Help 299 299 + 300 300 + For command-specific help, use the `--help` flag: 301 301 + 302 302 + ```sh 303 303 + tangled --help 304 304 + tangled repo --help 305 305 + tangled repo create --help 306 306 + ``` 307 307 + 308 308 + ## Next Steps 309 309 + 310 310 + - Explore all available commands with `tangled --help` 311 311 + - Set up CI/CD workflows with `.tangled.yml` in your repository 312 312 + - Check out the main README for more examples and advanced usage 313 313 + 314 314 + Happy collaborating! 🧶