TODO.md: Tangled CLI Development Plan #

This document outlines the development tasks for the Tangled CLI, based on the README.md and project goals.

Project Setup & Core Structure (Commander.js) #

• Initialize Node.js project.
• Install commander for CLI routing.
• Implement basic CLI command structure (e.g., tangled --version, tangled --help).
• Set up TypeScript configuration.
• Configure linting and formatting (Biome).
• Configure vitest for testing.

Authentication (Auth) #

• Implement tangled auth login command.
  • Collect user's PDS handle and app password.
  • Implement session storage using an OS keychain library (e.g., keytar) for secure, cross-platform token management.
  • Integrate @atproto/api for XRPC client and session management.
• Implement tangled auth logout command.

Git SSH Key Management #

• Implement tangled ssh-key verify command.
  • This command executes ssh -T git@tangled.org, parses the DID from its output, and displays it to the user.
  • If the user is logged in with the CLI and their DID matches the SSH DID, their handle is also displayed.

Context Engine (Git Integration) #

• Develop a "Context Resolver" module to infer repository context (DID) from the current working directory.
  • Start by using the current Git repository context.
    • Integrate git-url-parse to resolve Tangled DID/NSID from .git/config remote URLs. Using simple-git if needed.
    • If multiple remotes exist, look for one at tangled.org, then prompt the user to select remote if ambiguity remains.
    • Fallback to prompting the user to add a remote for their Tangled repository if none are found.
  • Avoid creating a config file in V1; rely on Git remotes and CLI flags for context.
    • 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).

Issue Management #

• Implement tangled issue create "<title>" [--body "<body>" | --body-file <file> | -F -] command.
• Implement tangled issue list [--json "id,title"] command.
  • Support --json output with field filtering.
• Migrate this TODO list into Tangled issues once issue creation is implemented. (note defects and address blocking features as needed).
  • Create phases in this todo list, and then use - [ ] tasks in the issue descriptions.
  • Remove TODO.md once all tasks are migrated to issues.
  • Update README.md to link to the issue board for contribution guidelines and project status instead of this TODO list.
  • 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.

Pull Request Management #

This section outlines the phased implementation for Pull Request (PR) support, following gh CLI patterns.

Phase 1: Creating a Pull Request from a Branch (Author Workflow) #

• Implement tangled pr create --base <base-branch> --head <head-branch> --title <title> [--body <body> | --body-file <file> | -F -] command.
  • Generate the git diff patch between the --head and --base branches.
  • Upload the generated patch as a blob using com.atproto.repo.uploadBlob (or equivalent).
  • 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.
• Implement tangled pr list [--json <fields>] command to list pull requests for the current repository.
  • Use com.atproto.repo.listRecords with collection: "sh.tangled.repo.pull".
• Implement tangled pr view <id> [--json <fields>] command to display detailed information about a specific pull request.
  • Use com.atproto.repo.getRecord for the sh.tangled.repo.pull record.
  • Fetch associated comments using com.atproto.repo.listRecords with collection: "sh.tangled.repo.pull.comment".
  • 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.

Phase 2: Working as a Reviewer (Commenting) #

• Implement tangled pr comment <id> [--body <body> | --body-file <file> | -F -] command.
  • Create a sh.tangled.repo.pull.comment record using com.atproto.repo.createRecord, linking it to the pull request's AT-URI.
• Implement tangled pr review <id> --comment <comment> [--approve | --request-changes] command.
  • Create a sh.tangled.repo.pull.comment record.
  • 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).

Phase 3: Responding to a Review (Author Workflow) #

• 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.

Repository Management #

• Implement tangled repo create <repo-name> command.
• Implement tangled repo view command (display repo details).
  • Support --json output with field filtering (e.g., --json name,cloneUrl,description) using lodash/pick).