markbennett.ca / tangled-cli
WIP: A simple cli for daily tangled use cases and AI integration. This is for my personal use right now, but happy if others get mileage from it! :)
fork atom

Add notes from Tangled.org API analysis.

markbennett.ca f871ba3b a80b5b1b

verified
+94
+94
API_ANALYSIS.md
··· 1 + # Tangled CLI: API Analysis and Implementation Feasibility 2 + 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 + 5 + ## 1. API Structure Overview 6 + 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 + 9 + ## 2. Feasibility of `TODO.md` Commands 10 + 11 + All commands currently outlined in `TODO.md` appear to be implementable with the existing API structure. 12 + 13 + ### 2.1. Authentication (`tangled auth login`) 14 + 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 + 17 + ### 2.2. Git SSH Key Management 18 + 19 + * **`tangled ssh-key add <public-key-path>`**: 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. 21 + * **`tangled ssh-key verify`**: 22 + * **Feasible.** This command can be implemented by: 23 + 1. Executing `ssh -T git@tangled.org` to capture the authenticated user's DID from the server response. 24 + 2. Using the `sh.tangled.knot.listKeys` query (defined in `core/lexicons/knot/listKeys.json`) to fetch a list of public keys known to the knot server. This query returns objects that include the `did` associated with each key. 25 + 3. Comparing the DID obtained from the SSH output with the DIDs returned by `listKeys` to confirm the key's association. 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 + 28 + ### 2.3. Repository Management 29 + 30 + * **`tangled repo create <repo-name>`**: 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 + * **`tangled repo view [--json <fields>]`**: 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 + 35 + ### 2.4. Issue Management 36 + 37 + * **`tangled issue create "<title>" [--body "<body>" | --body-file <file> | -F -]`**: 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 + * **`tangled issue list [--json "id,title"]`**: 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 + 42 + ## 3. API Resources and Actions Missing from Current CLI Plan 43 + 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 + 46 + ### 3.1. Pull Requests 47 + 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 + * **Potential CLI Commands:** `tangled pulls list`, `tangled pulls view <id>`, `tangled pulls create`, `tangled pulls merge`, `tangled pulls close`, `tangled pulls comment`. 50 + 51 + ### 3.2. CI/CD Pipelines 52 + 53 + Lexicons such as `pipeline/pipeline.json`, `pipeline/status.json`, and `pipeline/cancelPipeline.json` suggest integration with a CI/CD system. 54 + * **Potential CLI Commands:** `tangled pipeline status`, `tangled pipeline cancel <id>`. 55 + 56 + ### 3.3. Repository Secrets 57 + 58 + The `repo/addSecret.json`, `repo/listSecrets.json`, and `repo/removeSecret.json` lexicons allow for managing CI/CD secrets specific to a repository. 59 + * **Potential CLI Commands:** `tangled repo secret add <key> <value>`, `tangled repo secret list`, `tangled repo secret remove <key>`. 60 + 61 + ### 3.4. Advanced Git Operations 62 + 63 + Several lexicons expose finer-grained Git operations directly via XRPC, potentially allowing for more integrated Git functionality beyond simple cloning/pushing: 64 + * `repo/log.json` (view commit history) 65 + * `repo/diff.json` (view changes between commits/branches) 66 + * `repo/branches.json`, `repo/branch.json`, `repo/deleteBranch.json` (manage branches) 67 + * `repo/tags.json`, `repo/tag.json` (manage tags) 68 + * `repo/compare.json` (compare two refs) 69 + * `git/refUpdate.json` (update Git references) 70 + * **Potential CLI Commands:** `tangled repo log`, `tangled repo diff`, `tangled branch list`, etc. 71 + 72 + ### 3.5. Social & Feed Interactions 73 + 74 + Lexicons like `graph/follow.json`, `feed/star.json`, and `feed/reaction.json` suggest social networking features common in ATProto applications. 75 + * **Potential CLI Commands:** `tangled follow <did>`, `tangled star <uri>`, `tangled react <uri>`. 76 + 77 + ### 3.6. Labels 78 + 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 + * **Potential CLI Commands:** `tangled label add`, `tangled label list`. 81 + 82 + ### 3.7. Repository Collaboration 83 + 84 + The `repo/collaborator.json` lexicon suggests managing collaborators on a repository. 85 + * **Potential CLI Commands:** `tangled repo collaborator add`, `tangled repo collaborator list`. 86 + 87 + ### 3.8. Forking and Syncing 88 + 89 + `repo/forkSync.json` and `repo/forkStatus.json` point to specific API support for managing repository forks and their synchronization status. 90 + * **Potential CLI Commands:** `tangled repo fork`, `tangled repo fork-sync`. 91 + 92 + ## 4. Conclusion 93 + 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.