markbennett.ca
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! :)
1# Tangled CLI: API Analysis and Implementation Feasibility
2
3This 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## API Structure Overview
6
7The `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## Feasibility of `TODO.md` Commands
10
11All commands currently outlined in `TODO.md` appear to be implementable with the existing API structure.
12
13### 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### Git SSH Key Management
18
19#### Lexicon Details
20
21**`sh.tangled.publicKey` Record Schema** (from `core/lexicons/publicKey.json`):
22```json
23{
24 "lexicon": 1,
25 "id": "sh.tangled.publicKey",
26 "key": "tid",
27 "record": {
28 "required": ["key", "name", "createdAt"],
29 "properties": {
30 "key": {
31 "type": "string",
32 "maxLength": 4096,
33 "description": "public key contents"
34 },
35 "name": {
36 "type": "string",
37 "description": "human-readable name for this key"
38 },
39 "createdAt": {
40 "type": "string",
41 "format": "datetime",
42 "description": "key upload timestamp"
43 }
44 }
45 }
46}
47```
48
49**`sh.tangled.knot.listKeys` Query** (from `core/lexicons/knot/listKeys.json`):
50- Query endpoint for listing public keys stored on the knot server
51- Returns: Array of `{ did, key, createdAt }`
52- Supports pagination with `limit` and `cursor` parameters
53
54#### Implementation Approach
55
56* **`tangled ssh-key add <public-key-path>`**:
57 * **Feasible (using generic ATProto record creation).**
58 * Uses `AtpAgent.com.atproto.repo.createRecord()` with:
59 - `collection: "sh.tangled.publicKey"`
60 - `record: { key, name, createdAt }`
61 * The record will be stored on the user's PDS (Personal Data Server)
62 * The CLI reads the public key file, validates the format, and creates the record
63
64* **`tangled ssh-key verify`**:
65 * **Feasible.** This command can be implemented by:
66 1. Executing `ssh -T git@tangled.org` to capture the authenticated user's DID from the server response
67 2. Parsing the DID from the SSH output
68 3. Resolving the DID to a human-readable Bluesky handle using `com.atproto.identity.resolveHandle`
69 * Note: The `sh.tangled.knot.listKeys` query is available but may require knot server access
70
71#### TypeScript/JavaScript Tools
72
73- **`@atproto/api`**: Main SDK for AT Protocol operations
74 - `AtpAgent` class handles authentication and API calls
75 - Built-in methods for `com.atproto.repo.createRecord`, `getRecord`, `listRecords`
76
77- **`@atproto/lexicon`**: Schema validation library
78 - `Lexicons` class for loading and validating custom schemas
79 - Provides `assertValidRecord()` for validating record data against lexicons
80
81- **Direct Record Creation**: No code generation needed
82 ```typescript
83 await agent.com.atproto.repo.createRecord({
84 repo: agent.session.did,
85 collection: 'sh.tangled.publicKey',
86 record: {
87 key: publicKeyContent,
88 name: keyName,
89 createdAt: new Date().toISOString()
90 }
91 })
92 ```
93
94### Repository Management
95
96* **`tangled repo create <repo-name>`**:
97 * **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.
98* **`tangled repo view [--json <fields>]`**:
99 * **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`).
100
101### Issue Management
102
103* **`tangled issue create "<title>" [--body "<body>" | --body-file <file> | -F -]`**:
104 * **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).
105* **`tangled issue list [--json "id,title"]`**:
106 * **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.
107
108## API Resources and Actions Missing from Current CLI Plan
109
110The `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:
111
112### Pull Requests
113
114A 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.
115* **Potential CLI Commands:** `tangled pulls list`, `tangled pulls view <id>`, `tangled pulls create`, `tangled pulls merge`, `tangled pulls close`, `tangled pulls comment`.
116
117### CI/CD Pipelines
118
119Lexicons such as `pipeline/pipeline.json`, `pipeline/status.json`, and `pipeline/cancelPipeline.json` suggest integration with a CI/CD system.
120* **Potential CLI Commands:** `tangled pipeline status`, `tangled pipeline cancel <id>`.
121
122### Repository Secrets
123
124The `repo/addSecret.json`, `repo/listSecrets.json`, and `repo/removeSecret.json` lexicons allow for managing CI/CD secrets specific to a repository.
125* **Potential CLI Commands:** `tangled repo secret add <key> <value>`, `tangled repo secret list`, `tangled repo secret remove <key>`.
126
127### Advanced Git Operations
128
129Several lexicons expose finer-grained Git operations directly via XRPC, potentially allowing for more integrated Git functionality beyond simple cloning/pushing:
130* `repo/log.json` (view commit history)
131* `repo/diff.json` (view changes between commits/branches)
132* `repo/branches.json`, `repo/branch.json`, `repo/deleteBranch.json` (manage branches)
133* `repo/tags.json`, `repo/tag.json` (manage tags)
134* `repo/compare.json` (compare two refs)
135* `git/refUpdate.json` (update Git references)
136* **Potential CLI Commands:** `tangled repo log`, `tangled repo diff`, `tangled branch list`, etc.
137
138### Social & Feed Interactions
139
140Lexicons like `graph/follow.json`, `feed/star.json`, and `feed/reaction.json` suggest social networking features common in ATProto applications.
141* **Potential CLI Commands:** `tangled follow <did>`, `tangled star <uri>`, `tangled react <uri>`.
142
143### Labels
144
145The `label/definition.json` and `label/op.json` lexicons provide mechanisms for defining and applying labels to various resources (e.g., issues, pull requests).
146* **Potential CLI Commands:** `tangled label add`, `tangled label list`.
147
148### Repository Collaboration
149
150The `repo/collaborator.json` lexicon suggests managing collaborators on a repository.
151* **Potential CLI Commands:** `tangled repo collaborator add`, `tangled repo collaborator list`.
152
153### Forking and Syncing
154
155`repo/forkSync.json` and `repo/forkStatus.json` point to specific API support for managing repository forks and their synchronization status.
156* **Potential CLI Commands:** `tangled repo fork`, `tangled repo fork-sync`.
157
158## Conclusion
159
160The `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.