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# TODO.md: Tangled CLI Development Plan
2
3This document outlines the development tasks for the Tangled CLI, based on the `README.md` and project goals.
4
5## Project Setup & Core Structure (Commander.js)
6
7- [x] Initialize Node.js project.
8- [x] Install `commander` for CLI routing.
9- [x] Implement basic CLI command structure (e.g., `tangled --version`, `tangled --help`).
10- [x] Set up TypeScript configuration.
11- [x] Configure linting and formatting (Biome).
12- [x] Configure vitest for testing.
13
14## Authentication (Auth)
15
16- [x] Implement `tangled auth login` command.
17 - [x] Collect user's PDS handle and app password.
18 - [x] Implement session storage using an OS keychain library (e.g., `keytar`) for secure, cross-platform token management.
19 - [x] Integrate `@atproto/api` for XRPC client and session management.
20- [x] Implement `tangled auth logout` command.
21
22## Git SSH Key Management
23
24- [x] Implement `tangled ssh-key verify` command.
25 - [x] This command executes `ssh -T git@tangled.org`, parses the DID from its output, and displays it to the user.
26 - [x] If the user is logged in with the CLI and their DID matches the SSH DID, their handle is also displayed.
27
28## Context Engine (Git Integration)
29
30- [x] Develop a "Context Resolver" module to infer repository context (DID) from the current working directory.
31 - [x] Start by using the current Git repository context.
32 - [x] Integrate `git-url-parse` to resolve Tangled DID/NSID from `.git/config` remote URLs. Using `simple-git` if needed.
33 - [x] If multiple remotes exist, look for one at tangled.org, then prompt the user to select remote if ambiguity remains.
34 - [x] Fallback to prompting the user to add a remote for their Tangled repository if none are found.
35 - [x] Avoid creating a config file in V1; rely on Git remotes and CLI flags for context.
36 - [x] If a config is needed remember that the precedence order should be: CLI flags > local config > home folder config. Users may prefer different settings per repo (such as unique remote names, etc).
37
38## Issue Management
39
40- [x] Implement `tangled issue create "<title>" [--body "<body>" | --body-file <file> | -F -]` command.
41- [x] Implement `tangled issue list [--json "id,title"]` command.
42 - [x] Support `--json` output with field filtering.
43- [ ] Migrate this TODO list into Tangled issues once issue creation is implemented. (note defects and address blocking features as needed).
44 - [ ] Create phases in this todo list, and then use `- [ ]` tasks in the issue descriptions.
45 - [ ] Remove TODO.md once all tasks are migrated to issues.
46 - [ ] Update README.md to link to the issue board for contribution guidelines and project status instead of this TODO list.
47 - [ ] Create CLI_FEEDBACK.md with learnings from using the CLI and complete the issue creation process and close the loop on dogfooding the CLI for this project.
48
49## Pull Request Management
50
51This section outlines the phased implementation for Pull Request (PR) support, following `gh` CLI patterns.
52
53### Phase 1: Creating a Pull Request from a Branch (Author Workflow)
54
55- [ ] Implement `tangled pr create --base <base-branch> --head <head-branch> --title <title> [--body <body> | --body-file <file> | -F -]` command.
56 - [ ] Generate the `git diff` patch between the `--head` and `--base` branches.
57 - [ ] Upload the generated patch as a blob using `com.atproto.repo.uploadBlob` (or equivalent).
58 - [ ] Create a `sh.tangled.repo.pull` record using `com.atproto.repo.createRecord`, including `target` (repo and base branch), `source` (head branch and SHA), `title`, `body`, and the `patchBlob` reference.
59- [ ] Implement `tangled pr list [--json <fields>]` command to list pull requests for the current repository.
60 - [ ] Use `com.atproto.repo.listRecords` with `collection: "sh.tangled.repo.pull"`.
61- [ ] Implement `tangled pr view <id> [--json <fields>]` command to display detailed information about a specific pull request.
62 - [ ] Use `com.atproto.repo.getRecord` for the `sh.tangled.repo.pull` record.
63 - [ ] Fetch associated comments using `com.atproto.repo.listRecords` with `collection: "sh.tangled.repo.pull.comment"`.
64 - [ ] Dogfood the CLI by using it to create a pull request for these changes, and then view the created PR to ensure all data is correctly stored and retrieved.
65
66### Phase 2: Working as a Reviewer (Commenting)
67
68- [ ] Implement `tangled pr comment <id> [--body <body> | --body-file <file> | -F -]` command.
69 - [ ] Create a `sh.tangled.repo.pull.comment` record using `com.atproto.repo.createRecord`, linking it to the pull request's AT-URI.
70- [ ] Implement `tangled pr review <id> --comment <comment> [--approve | --request-changes]` command.
71 - [ ] Create a `sh.tangled.repo.pull.comment` record.
72 - [ ] Update the `sh.tangled.repo.pull.status` record (if applicable) to reflect approval or requested changes. (Further API research might be needed to map approve/request-changes to status updates).
73
74### Phase 3: Responding to a Review (Author Workflow)
75
76- [ ] 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.
77
78## Repository Management
79
80- [ ] Implement `tangled repo create <repo-name>` command.
81- [ ] Implement `tangled repo view` command (display repo details).
82 - [ ] Support `--json` output with field filtering (e.g., `--json name,cloneUrl,description`) using `lodash/pick`).