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! :)
Draft project plan
+65
+65
TODO.md
+65
TODO.md
···
1
+
# TODO.md: Tangled CLI Development Plan
2
+
3
+
This document outlines the development tasks for the Tangled CLI, based on the `README.md` and project goals.
4
+
5
+
## 1. Project Setup & Core Structure (Commander.js)
6
+
- [ ] Initialize Node.js project.
7
+
- [ ] Install `commander` for CLI routing.
8
+
- [ ] Implement basic CLI command structure (e.g., `tangled --version`, `tangled --help`).
9
+
- [ ] Set up TypeScript configuration.
10
+
- [ ] Configure linting and formatting (ESLint, Prettier).
11
+
12
+
## 2. Authentication (Auth)
13
+
- [ ] Implement `tangled auth login` command.
14
+
- [ ] Explore methods for secure AT Proto session storage (OS keychain consideration across platforms: Windows, macOS, Linux).
15
+
- [ ] Integrate `@atproto/api` for XRPC client and session management.
16
+
- [ ] Investigate web browser authentication flow.
17
+
- [ ] Implement `tangled auth logout` command.
18
+
19
+
## 3. Git SSH Key Management
20
+
- [ ] Implement `tangled ssh-key add <public-key-path>` command.
21
+
- [ ] 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.
22
+
- [ ] The CLI is not responsible for generating SSH keys or managing the local ssh-agent; users are expected to handle these steps externally.
23
+
- [ ] Implement `tangled ssh-key verify` command.
24
+
- [ ] 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.
25
+
- [ ] Ensure all Git operations leverage SSH keys for authentication, as `tangled.org` exclusively supports SSH for Git.
26
+
27
+
## 4. Context Engine (Git Integration)
28
+
- [ ] Integrate `git-url-parse` to resolve Tangled DID/NSID from `.git/config` remote URLs.
29
+
- [ ] Develop a "Context Resolver" module to infer repository context (DID) from the current working directory.
30
+
- [ ] Implement fallback mechanisms if no git remote is found or DID cannot be resolved (error handling).
31
+
- [ ] Integrate `simple-git` for safe local git operations.
32
+
- [ ] Implement logic to parse the DID from `ssh -T git@tangled.org` output (will be reused by `tangled ssh-key verify`).
33
+
- [ ] 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`).
34
+
35
+
## 5. Repository Management
36
+
- [ ] Implement `tangled repo create <repo-name>` command.
37
+
- [ ] Implement `tangled repo view` command (display repo details).
38
+
- [ ] Support `--json` output with field filtering (e.g., `--json name,cloneUrl,description`) using `lodash/pick`).
39
+
40
+
## 6. Issue Management
41
+
- [ ] Implement `tangled issue create "<title>" [--body "<body>" | --body-file <file> | -F -]` command.
42
+
- [ ] Implement `tangled issue list [--json "id,title"]` command.
43
+
- [ ] Support `--json` output with field filtering.
44
+
45
+
## 7. Output & LLM Integration
46
+
- [ ] Implement output formatting based on `is-interactive` check.
47
+
- [ ] "Human Mode" (TTY): Use `cli-table3` for pretty tables.
48
+
- [ ] "Machine Mode" (Pipe/`--json`): Plain text or JSON output.
49
+
- [ ] Implement `--json` flag for structured output.
50
+
- [ ] Implement `--no-input` flag to force CLI to error on unresolved context or missing flags (Fail Fast, Fail Loud principle).
51
+
52
+
## 8. Testing
53
+
- [ ] Set up a testing framework (e.g., Jest, Vitest).
54
+
- [ ] Write unit tests for core modules (Auth, Context Resolver, API client).
55
+
- [ ] Write integration tests for CLI commands.
56
+
57
+
## 9. Documentation & Deployment
58
+
- [ ] Generate CLI help documentation (`commander` usually handles this).
59
+
- [ ] Consider packaging/distribution strategy (npm, standalone binary).
60
+
61
+
## 10. Outstanding Issues / Future Considerations (from README)
62
+
- [ ] Secure cross-platform AT Proto session storage (OS keychain).
63
+
- [ ] Git authentication management similar to GitHub CLI (SSH keys, 1Password integration).
64
+
- [ ] Define clear precedence order for settings resolution (local config, home folder, CLI flags).
65
+
- [ ] Consider adding extensions/plugins (Out of Scope for V1, but keep in mind).