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
tangled-cli / TODO.md
at pull-request-format-testing 5.5 kB view raw view code
markbennett.ca Add --json output with field filtering to issue commands
1b804d29

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