Remove doc heading numbers · markbennett.ca/tangled-cli@a7489ae

+16 -16

API_ANALYSIS.md

··· 2 2 3 3 This document details the analysis of the `tangled.org` API, based on the lexicon files found in the `tangled.org/core` repository, and assesses the feasibility of implementing the commands outlined in `TODO.md`. 4 4 5 - ## 1. API Structure Overview 5 + ## API Structure Overview 6 6 7 7 The `tangled.org` API leverages the AT Protocol (ATProto), combining custom lexicons (schemas) for specific data types with generic ATProto repository operations (`com.atproto.repo.*`) for fundamental record management (create, get, list). This approach is common in ATProto-based services. 8 8 9 - ## 2. Feasibility of `TODO.md` Commands 9 + ## Feasibility of `TODO.md` Commands 10 10 11 11 All commands currently outlined in `TODO.md` appear to be implementable with the existing API structure. 12 12 13 - ### 2.1. Authentication (`tangled auth login`) 13 + ### Authentication (`tangled auth login`) 14 14 15 15 * **Feasible.** This will utilize the standard AT Protocol `com.atproto.server.createSession` procedure. This procedure is part of the core ATProto specification and would be handled by the `@atproto/api` library, not requiring a specific `tangled.org` lexicon. 16 16 17 - ### 2.2. Git SSH Key Management 17 + ### Git SSH Key Management 18 18 19 19 * **`tangled ssh-key add <public-key-path>`**: 20 20 * **Feasible (using generic ATProto record creation).** The `core/lexicons/publicKey.json` defines the `sh.tangled.publicKey` record type. To add a user's global SSH public key, the CLI would use the generic ATProto `com.atproto.repo.createRecord` procedure. The `collection` parameter would be set to `sh.tangled.publicKey`, and the public key content (`key`) and a human-readable name (`name`) would be provided as the record data. ··· 25 25 3. Comparing the DID obtained from the SSH output with the DIDs returned by `listKeys` to confirm the key's association. 26 26 4. Resolving the DID to a human-readable Bluesky handle using the standard AT Protocol `com.atproto.identity.resolveHandle` procedure (part of `@atproto/api`). 27 27 28 - ### 2.3. Repository Management 28 + ### Repository Management 29 29 30 30 * **`tangled repo create <repo-name>`**: 31 31 * **Feasible.** The `sh.tangled.repo.create` procedure (defined in `core/lexicons/repo/create.json`) directly supports this. It requires an `rkey` (repository key/name) and can optionally accept a `defaultBranch` and a `source` URL for forking/importing. 32 32 * **`tangled repo view [--json <fields>]`**: 33 33 * **Feasible (using generic ATProto record retrieval).** The `core/lexicons/repo/repo.json` defines the `sh.tangled.repo` record type. To view details of a specific repository, the CLI would use the generic ATProto `com.atproto.repo.getRecord` procedure, specifying `collection: "sh.tangled.repo"` and the appropriate record key (`rkey`). 34 34 35 - ### 2.4. Issue Management 35 + ### Issue Management 36 36 37 37 * **`tangled issue create "<title>" [--body "<body>" | --body-file <file> | -F -]`**: 38 38 * **Feasible (using generic ATProto record creation).** The `core/lexicons/issue/issue.json` defines the `sh.tangled.repo.issue` record type. To create a new issue, the CLI would use the generic ATProto `com.atproto.repo.createRecord` procedure. The `collection` would be `sh.tangled.repo.issue`, and the `record` data would include the `repo` (AT-URI of the repository), `title`, and `body` (if provided). 39 39 * **`tangled issue list [--json "id,title"]`**: 40 40 * **Feasible (using generic ATProto record listing).** To list issues for a repository, the CLI would use the generic ATProto `com.atproto.repo.listRecords` procedure, specifying `collection: "sh.tangled.repo.issue"`. Client-side filtering by the `repo` field (which is an AT-URI to the parent repository) might be necessary if the API does not offer server-side filtering for this specific collection. 41 41 42 - ## 3. API Resources and Actions Missing from Current CLI Plan 42 + ## API Resources and Actions Missing from Current CLI Plan 43 43 44 44 The `tangled.org` API, as revealed by its lexicons, exposes numerous capabilities beyond the current scope of the `TODO.md`. These represent potential future enhancements for the CLI: 45 45 46 - ### 3.1. Pull Requests 46 + ### Pull Requests 47 47 48 48 A comprehensive set of lexicons (`pulls/pull.json`, `pulls/open.json`, `pulls/merged.json`, `pulls/comment.json`, `pulls/closed.json`, `pulls/state.json`) indicates a fully-fledged Pull Request system. 49 49 * **Potential CLI Commands:** `tangled pulls list`, `tangled pulls view <id>`, `tangled pulls create`, `tangled pulls merge`, `tangled pulls close`, `tangled pulls comment`. 50 50 51 - ### 3.2. CI/CD Pipelines 51 + ### CI/CD Pipelines 52 52 53 53 Lexicons such as `pipeline/pipeline.json`, `pipeline/status.json`, and `pipeline/cancelPipeline.json` suggest integration with a CI/CD system. 54 54 * **Potential CLI Commands:** `tangled pipeline status`, `tangled pipeline cancel <id>`. 55 55 56 - ### 3.3. Repository Secrets 56 + ### Repository Secrets 57 57 58 58 The `repo/addSecret.json`, `repo/listSecrets.json`, and `repo/removeSecret.json` lexicons allow for managing CI/CD secrets specific to a repository. 59 59 * **Potential CLI Commands:** `tangled repo secret add <key> <value>`, `tangled repo secret list`, `tangled repo secret remove <key>`. 60 60 61 - ### 3.4. Advanced Git Operations 61 + ### Advanced Git Operations 62 62 63 63 Several lexicons expose finer-grained Git operations directly via XRPC, potentially allowing for more integrated Git functionality beyond simple cloning/pushing: 64 64 * `repo/log.json` (view commit history) ··· 69 69 * `git/refUpdate.json` (update Git references) 70 70 * **Potential CLI Commands:** `tangled repo log`, `tangled repo diff`, `tangled branch list`, etc. 71 71 72 - ### 3.5. Social & Feed Interactions 72 + ### Social & Feed Interactions 73 73 74 74 Lexicons like `graph/follow.json`, `feed/star.json`, and `feed/reaction.json` suggest social networking features common in ATProto applications. 75 75 * **Potential CLI Commands:** `tangled follow <did>`, `tangled star <uri>`, `tangled react <uri>`. 76 76 77 - ### 3.6. Labels 77 + ### Labels 78 78 79 79 The `label/definition.json` and `label/op.json` lexicons provide mechanisms for defining and applying labels to various resources (e.g., issues, pull requests). 80 80 * **Potential CLI Commands:** `tangled label add`, `tangled label list`. 81 81 82 - ### 3.7. Repository Collaboration 82 + ### Repository Collaboration 83 83 84 84 The `repo/collaborator.json` lexicon suggests managing collaborators on a repository. 85 85 * **Potential CLI Commands:** `tangled repo collaborator add`, `tangled repo collaborator list`. 86 86 87 - ### 3.8. Forking and Syncing 87 + ### Forking and Syncing 88 88 89 89 `repo/forkSync.json` and `repo/forkStatus.json` point to specific API support for managing repository forks and their synchronization status. 90 90 * **Potential CLI Commands:** `tangled repo fork`, `tangled repo fork-sync`. 91 91 92 - ## 4. Conclusion 92 + ## Conclusion 93 93 94 94 The `tangled.org` API provides a solid foundation for building the planned CLI. All current `TODO.md` items are implementable, primarily by leveraging the `@atproto/api` library's generic record operations in conjunction with `tangled.org`'s custom record definitions and specific procedures. The API also offers a rich set of additional functionalities that can significantly extend the CLI's capabilities in future iterations, particularly around pull requests, CI/CD, and advanced Git management.

+15 -15

README.md

··· 1 1 # Tangled CLI: Architecture & Implementation Plan 2 2 3 - ## 1. Project Overview 3 + ## Project Overview 4 4 5 5 **Goal:** Create a context-aware CLI for tangled.org that bridges the gap between the AT Protocol (XRPC) and standard Git. **Philosophy:** Follow the **GitHub CLI (gh)** standard: act as a wrapper that creates a seamless experience where the API and local Git repo feel like one unified tool. 6 6 7 - ## 2. Prior Art Analysis: GitHub CLI (gh) vs. Tangled CLI 7 + ## Prior Art Analysis: GitHub CLI (gh) vs. Tangled CLI 8 8 9 9 | Feature | GitHub CLI (gh) Approach | Tangled CLI Strategy | 10 10 | :------------- | :--------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------- | ··· 14 14 | **Filtering** | \--json name,url (filters fields). | **Plan:** Support basic \--json flag first. Add field filtering (--json "cloneUrl,did") to save LLM context window tokens. | 15 15 | **Extensions** | Allows custom subcommands. | _Out of Scope for V1._ | 16 16 17 - ## 3. High-Level Architecture (Refined) 17 + ## High-Level Architecture (Refined) 18 18 19 19 The CLI acts as a "Context Engine" before it even hits the API. 20 20 `graph TD` ··· 33 33 `API --> Output` 34 34 `Shell --> Output` 35 35 36 - ## 4. Tech Stack (TypeScript) 36 + ## Tech Stack (TypeScript) 37 37 38 38 | Component | Library | Purpose | 39 39 | :---------------- | :-------------------- | :------------------------------------------------------------ | ··· 46 46 | **Formatting** | **cli-table3** | **New:** For gh-style pretty tables in Human Mode. | 47 47 | **OS Keychain** | **keytar** | **New:** To securely store session tokens in the OS keychain. | 48 48 49 - ## 5. Agent Integration (The "LLM Friendly" Layer) 49 + ## Agent Integration (The "LLM Friendly" Layer) 50 50 51 51 To make this tool accessible to Claude Code/Gemini, we adopt gh's best patterns: 52 52 ··· 83 83 - **Git Config Integration:** Treats the local .git folder as a database of configuration, reducing the need for environment variables or complex flags. 84 84 - **Flexible Issue Body Input:** Improves usability for both humans and LLMs by allowing diverse input methods for issue descriptions. 85 85 86 - ## 6. Examples Tangled CLI Usage 86 + ## Examples Tangled CLI Usage 87 87 88 88 ```bash 89 89 tangled auth login (opens a browser for auth) ··· 97 97 tangled pr comment 123 --body "Looks good, small change needed." 98 98 ``` 99 99 100 - ## 7. Basic Commands 100 + ## Basic Commands 101 101 102 102 Basic commands include auth, key management, repo creation, issue management, and pull request management. 103 103 ··· 127 127 `tangled pr review <id> --comment <comment> [--approve | --request-changes]` 128 128 - Submits a review for a pull request, with optional approval or request for changes. 129 129 130 - ## 8. Design Decisions & Outstanding Issues 130 + ## Design Decisions & Outstanding Issues 131 131 132 132 This section documents key design decisions and tracks outstanding architectural questions. 133 133 134 - ### 1. (Resolved) SSH Key Management (`gh` Compatibility) 134 + ### (Resolved) SSH Key Management (`gh` Compatibility) 135 135 136 136 - **Original Question:** How does `gh` manage SSH keys, and can we follow that pattern? 137 137 - **Resolution:** Analysis shows that `gh` does _not_ manage private keys. It facilitates uploading the user's _public_ key to their GitHub account. The local SSH agent handles the private key. 138 138 - **Our Approach:** The `tangled ssh-key add` command follows this exact pattern. It provides a user-friendly way to upload a public key to `tangled.org`. This resolves the core of this issue, as it is compatible with external key managers like 1Password's SSH agent. 139 139 140 - ### 2. (Decided) Secure Session Storage 140 + ### (Decided) Secure Session Storage 141 141 142 142 - **Original Question:** How should we securely store the AT Proto session token? 143 143 - **Resolution:** Storing sensitive tokens in plaintext files is not secure. 144 144 - **Our Approach:** The CLI will use the operating system's native keychain for secure storage (e.g., macOS Keychain, Windows Credential Manager, or Secret Service on Linux). A library like `keytar` will be used to abstract the platform differences. 145 145 146 - ### 3. (Decided) Configuration Resolution Order 146 + ### (Decided) Configuration Resolution Order 147 147 148 148 - **Original Question:** How should settings be resolved from different sources? 149 149 - **Resolution:** A clear precedence order is necessary. ··· 153 153 3. Project-specific config file (e.g., `.tangled/config.yml` in the current directory) 154 154 4. Global user config file (e.g., `~/.config/tangled/config.yml`) 155 155 156 - ### 4. (Decided for V1) Authentication Flow: App Passwords (PDS) 156 + ### (Decided for V1) Authentication Flow: App Passwords (PDS) 157 157 158 158 - **Original Question:** Can we allow auth through a web browser? 159 159 - **Resolution:** For the initial version, the CLI will use **App Passwords** for authentication. This is the standard and simplest method for third-party AT Protocol clients and aligns with existing practices. ··· 162 162 - **Session Management:** The session established is with the user's PDS, and this authenticated session is then used to interact with `tangled.org`'s App View/Service. 163 163 - **OAuth Support:** Implementing a web-based OAuth flow (similar to `gh`'s approach) is more complex and not a standard part of the AT Protocol client authentication flow. This approach is deferred for future consideration. 164 164 165 - ## 9. Future Expansion Opportunities 165 + ## Future Expansion Opportunities 166 166 167 167 The analysis of the `tangled.org` API revealed a rich set of features that are not yet part of the initial CLI plan but represent significant opportunities for future expansion. These include: 168 168 ··· 174 174 - **Collaboration:** Commands to manage repository collaborators. 175 175 - **Fork Management:** Commands for forking repositories and managing the sync status of forks. 176 176 177 - ## 10. Task Management 177 + ## Task Management 178 178 179 179 We're bootstrapping task tracking with TODO.md, but will migrate all tasks into Tangled issues and dog food the product as soon as we have basic issue creation and listing working. 180 180 181 - ## 11. Development 181 + ## Development 182 182 183 183 ### Prerequisites 184 184

+11 -11

TODO.md

··· 2 2 3 3 This document outlines the development tasks for the Tangled CLI, based on the `README.md` and project goals. 4 4 5 - ## 1. Project Setup & Core Structure (Commander.js) 5 + ## Project Setup & Core Structure (Commander.js) 6 6 7 7 - [x] Initialize Node.js project. 8 8 - [x] Install `commander` for CLI routing. ··· 11 11 - [x] Configure linting and formatting (Biome). 12 12 - [x] Configure vitest for testing. 13 13 14 - ## 2. Authentication (Auth) 14 + ## Authentication (Auth) 15 15 16 16 - [ ] Implement `tangled auth login` command. 17 17 - [ ] Collect user's PDS handle and app password. ··· 19 19 - [ ] Integrate `@atproto/api` for XRPC client and session management. 20 20 - [ ] Implement `tangled auth logout` command. 21 21 22 - ## 3. Git SSH Key Management 22 + ## Git SSH Key Management 23 23 24 24 - [ ] Implement `tangled ssh-key add <public-key-path>` command. 25 25 - [ ] This command should upload the provided public SSH key to the user's tangled.org account via the API, similar to how `gh ssh-key add` works. ··· 28 28 - [ ] This command should execute `ssh -T git@tangled.org`, parse the DID from its output, and then resolve that DID to a Bluesky handle, displaying the result to the user. 29 29 - [ ] Ensure all Git operations leverage SSH keys for authentication, as `tangled.org` exclusively supports SSH for Git. 30 30 31 - ## 4. Context Engine (Git Integration) 31 + ## Context Engine (Git Integration) 32 32 33 33 - [ ] Integrate `git-url-parse` to resolve Tangled DID/NSID from `.git/config` remote URLs. 34 34 - [ ] Develop a "Context Resolver" module to infer repository context (DID) from the current working directory. ··· 37 37 - [ ] Implement logic to parse the DID from `ssh -T git@tangled.org` output (will be reused by `tangled ssh-key verify`). 38 38 - [ ] Implement functionality to resolve a DID (e.g., `did:plc:b2mcbcamkwyznc5fkplwlxbf`) into a human-readable Bluesky handle (will be reused by `tangled ssh-key verify`). 39 39 40 - ## 5. Repository Management 40 + ## Repository Management 41 41 42 42 - [ ] Implement `tangled repo create <repo-name>` command. 43 43 - [ ] Implement `tangled repo view` command (display repo details). 44 44 - [ ] Support `--json` output with field filtering (e.g., `--json name,cloneUrl,description`) using `lodash/pick`). 45 45 46 - ## 6. Issue Management 46 + ## Issue Management 47 47 48 48 - [ ] Implement `tangled issue create "<title>" [--body "<body>" | --body-file <file> | -F -]` command. 49 49 - [ ] Implement `tangled issue list [--json "id,title"]` command. 50 50 - [ ] Support `--json` output with field filtering. 51 51 52 - ## 7. Pull Request Management 52 + ## Pull Request Management 53 53 54 54 This section outlines the phased implementation for Pull Request (PR) support, following `gh` CLI patterns. 55 55 ··· 77 77 78 78 - [ ] This phase primarily involves local Git operations (pushing new commits) and using `tangled pr comment` for clarifications, which are covered by existing or planned commands. 79 79 80 - ## 8. Output & LLM Integration 80 + ## Output & LLM Integration 81 81 82 82 - [ ] Implement output formatting based on `is-interactive` check. 83 83 - [ ] "Human Mode" (TTY): Use `cli-table3` for pretty tables. ··· 85 85 - [ ] Implement `--json` flag for structured output. 86 86 - [ ] Implement `--no-input` flag to force CLI to error on unresolved context or missing flags (Fail Fast, Fail Loud principle). 87 87 88 - ## 9. Testing 88 + ## Testing 89 89 90 90 - [ ] Set up a testing framework (e.g., Jest, Vitest). 91 91 - [ ] Write unit tests for core modules (Auth, Context Resolver, API client). 92 92 - [ ] Write integration tests for CLI commands. 93 93 94 - ## 10. Documentation & Deployment 94 + ## Documentation & Deployment 95 95 96 96 - [ ] Generate CLI help documentation (`commander` usually handles this). 97 97 - [ ] Consider packaging/distribution strategy (npm, standalone binary). 98 98 99 - ## 11. Outstanding Issues / Future Considerations (from README) 99 + ## Outstanding Issues / Future Considerations (from README) 100 100 101 101 - [ ] Secure cross-platform AT Proto session storage (OS keychain). 102 102 - [ ] Git authentication management similar to GitHub CLI (SSH keys, 1Password integration).