diff --git a/README.md b/README.md index 65764c4..9ad7534 100644 --- a/README.md +++ b/README.md @@ -35,15 +35,15 @@ The CLI acts as a "Context Engine" before it even hits the API. ## 4. Tech Stack (TypeScript) -| Component | Library | Purpose | -| :---------------- | :-------------------- | :----------------------------------------------------------- | -| **Framework** | **commander** | Routing (tangled repo create). | -| **API Client** | **@atproto/api** | Official XRPC client & session management. | -| **Git Context** | **git-url-parse** | **New:** Parses remote URLs to extract the Tangled DID/NSID. | -| **Git Ops** | **simple-git** | Wraps local git operations safely. | -| **Validation** | **zod** | Validates inputs & generates schemas for LLMs. | -| **Interactivity** | **@inquirer/prompts** | Modern prompts for humans. | -| **Formatting** | **cli-table3** | **New:** For gh-style pretty tables in Human Mode. | +| Component | Library | Purpose | +| :---------------- | :-------------------- | :------------------------------------------------------------ | +| **Framework** | **commander** | Routing (tangled repo create). | +| **API Client** | **@atproto/api** | Official XRPC client & session management. | +| **Git Context** | **git-url-parse** | **New:** Parses remote URLs to extract the Tangled DID/NSID. | +| **Git Ops** | **simple-git** | Wraps local git operations safely. | +| **Validation** | **zod** | Validates inputs & generates schemas for LLMs. | +| **Interactivity** | **@inquirer/prompts** | Modern prompts for humans. | +| **Formatting** | **cli-table3** | **New:** For gh-style pretty tables in Human Mode. | | **OS Keychain** | **keytar** | **New:** To securely store session tokens in the OS keychain. | ## 5. Agent Integration (The "LLM Friendly" Layer) @@ -71,9 +71,10 @@ LLMs can't read error messages buried in HTML or long stack traces. Provide a `- ### Rule 4: Flexible Input for Issue Bodies Following `gh`'s pattern, `tangled issue create` will support various ways to provide the issue body, making it LLM-friendly and flexible for scripting. It will accept: -- `--body "Text"` or `-b "Text"` for a direct string. -- `--body-file ./file.md` or `-F ./file.md` to read from a file. -- `--body-file -` or `-F -` to read from standard input (stdin). + +- `--body "Text"` or `-b "Text"` for a direct string. +- `--body-file ./file.md` or `-F ./file.md` to read from a file. +- `--body-file -` or `-F -` to read from standard input (stdin). ### Summary of Improvements @@ -132,44 +133,47 @@ This section documents key design decisions and tracks outstanding architectural ### 1. (Resolved) SSH Key Management (`gh` Compatibility) -* **Original Question:** How does `gh` manage SSH keys, and can we follow that pattern? -* **Resolution:** Analysis shows that `gh` does *not* manage private keys. It facilitates uploading the user's *public* key to their GitHub account. The local SSH agent handles the private key. -* **Our Approach:** The `tangled ssh-key add` command follows this exact pattern. It provides a user-friendly way to upload a public key to `tangled.org`. This resolves the core of this issue, as it is compatible with external key managers like 1Password's SSH agent. +- **Original Question:** How does `gh` manage SSH keys, and can we follow that pattern? +- **Resolution:** Analysis shows that `gh` does _not_ manage private keys. It facilitates uploading the user's _public_ key to their GitHub account. The local SSH agent handles the private key. +- **Our Approach:** The `tangled ssh-key add` command follows this exact pattern. It provides a user-friendly way to upload a public key to `tangled.org`. This resolves the core of this issue, as it is compatible with external key managers like 1Password's SSH agent. ### 2. (Decided) Secure Session Storage -* **Original Question:** How should we securely store the AT Proto session token? -* **Resolution:** Storing sensitive tokens in plaintext files is not secure. -* **Our Approach:** The CLI will use the operating system's native keychain for secure storage (e.g., macOS Keychain, Windows Credential Manager, or Secret Service on Linux). A library like `keytar` will be used to abstract the platform differences. +- **Original Question:** How should we securely store the AT Proto session token? +- **Resolution:** Storing sensitive tokens in plaintext files is not secure. +- **Our Approach:** The CLI will use the operating system's native keychain for secure storage (e.g., macOS Keychain, Windows Credential Manager, or Secret Service on Linux). A library like `keytar` will be used to abstract the platform differences. ### 3. (Decided) Configuration Resolution Order -* **Original Question:** How should settings be resolved from different sources? -* **Resolution:** A clear precedence order is necessary. -* **Our Approach:** The CLI will resolve settings in the following order of precedence (highest first): - 1. Command-line flags (e.g., `--repo-did ...`) - 2. Environment variables (e.g., `TANGLED_REPO_DID=...`) - 3. Project-specific config file (e.g., `.tangled/config.yml` in the current directory) - 4. Global user config file (e.g., `~/.config/tangled/config.yml`) +- **Original Question:** How should settings be resolved from different sources? +- **Resolution:** A clear precedence order is necessary. +- **Our Approach:** The CLI will resolve settings in the following order of precedence (highest first): + 1. Command-line flags (e.g., `--repo-did ...`) + 2. Environment variables (e.g., `TANGLED_REPO_DID=...`) + 3. Project-specific config file (e.g., `.tangled/config.yml` in the current directory) + 4. Global user config file (e.g., `~/.config/tangled/config.yml`) -### 4. (Outstanding) Web-based Authentication Flow +### 4. (Decided for V1) Authentication Flow: App Passwords (PDS) -* **Original Question:** Can we allow auth through a web browser? -* **Status:** This remains an outstanding issue. The standard AT Protocol authentication flow is based on user handles and app passwords, not a third-party OAuth2 flow like GitHub CLI uses. -* **Path Forward:** Implementing a web-based auth flow would require custom development on the `tangled.org` service itself to securely generate and transmit a session token back to the CLI. This is out of scope for the initial version of the CLI. +- **Original Question:** Can we allow auth through a web browser? +- **Resolution:** For the initial version, the CLI will use **App Passwords** for authentication. This is the standard and simplest method for third-party AT Protocol clients and aligns with existing practices. +- **`tangled auth login` Flow:** When running `tangled auth login`, the CLI will prompt the user for their **PDS handle** (e.g., `@mark.bsky.social`) and an **App Password**. +- **Generating an App Password:** Users typically generate App Passwords from their PDS's settings (e.g., in the official Bluesky app under "Settings -> App Passwords", or on their self-hosted PDS web interface). The CLI **does not** generate app passwords. +- **Session Management:** The session established is with the user's PDS, and this authenticated session is then used to interact with `tangled.org`'s App View/Service. +- **OAuth Support:** Implementing a web-based OAuth flow (similar to `gh`'s approach) is more complex and not a standard part of the AT Protocol client authentication flow. This approach is deferred for future consideration. ## 9. Future Expansion Opportunities The analysis of the `tangled.org` API revealed a rich set of features that are not yet part of the initial CLI plan but represent significant opportunities for future expansion. These include: -* **CI/CD Pipelines:** Commands to view pipeline status and manage CI/CD jobs. -* **Repository Secrets:** A dedicated command set for managing CI/CD secrets within a repository (`tangled repo secret ...`). -* **Advanced Git Operations:** Commands to interact with the commit log, diffs, branches, and tags directly via the API, augmenting local `git` commands. -* **Social & Feed Interactions:** Commands for starring repositories, reacting to feed items, and managing the user's social graph (following/unfollowing). -* **Label Management:** Commands to create, apply, and remove labels from issues and pull requests. -* **Collaboration:** Commands to manage repository collaborators. -* **Fork Management:** Commands for forking repositories and managing the sync status of forks. +- **CI/CD Pipelines:** Commands to view pipeline status and manage CI/CD jobs. +- **Repository Secrets:** A dedicated command set for managing CI/CD secrets within a repository (`tangled repo secret ...`). +- **Advanced Git Operations:** Commands to interact with the commit log, diffs, branches, and tags directly via the API, augmenting local `git` commands. +- **Social & Feed Interactions:** Commands for starring repositories, reacting to feed items, and managing the user's social graph (following/unfollowing). +- **Label Management:** Commands to create, apply, and remove labels from issues and pull requests. +- **Collaboration:** Commands to manage repository collaborators. +- **Fork Management:** Commands for forking repositories and managing the sync status of forks. ## 10. Task Management -We're bootstrapping task tracking with TODO.md, but will migrate all tasks into Tangled issues and dog food the product as soon as we have basic issue creation and listing working. \ No newline at end of file +We're bootstrapping task tracking with TODO.md, but will migrate all tasks into Tangled issues and dog food the product as soon as we have basic issue creation and listing working. diff --git a/TODO.md b/TODO.md index 0caed27..bc6d8b0 100644 --- a/TODO.md +++ b/TODO.md @@ -3,6 +3,7 @@ This document outlines the development tasks for the Tangled CLI, based on the `README.md` and project goals. ## 1. 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`). @@ -10,21 +11,24 @@ This document outlines the development tasks for the Tangled CLI, based on the ` - [ ] Configure linting and formatting (ESLint, Prettier). ## 2. Authentication (Auth) + - [ ] Implement `tangled auth login` command. - - [ ] 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. - - [ ] Investigate web browser authentication flow. + - [ ] 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. ## 3. Git SSH Key Management + - [ ] Implement `tangled ssh-key add ` command. - - [ ] 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. - - [ ] The CLI is not responsible for generating SSH keys or managing the local ssh-agent; users are expected to handle these steps externally. + - [ ] 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. + - [ ] The CLI is not responsible for generating SSH keys or managing the local ssh-agent; users are expected to handle these steps externally. - [ ] Implement `tangled ssh-key verify` command. - - [ ] 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. + - [ ] 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. - [ ] Ensure all Git operations leverage SSH keys for authentication, as `tangled.org` exclusively supports SSH for Git. ## 4. Context Engine (Git Integration) + - [ ] Integrate `git-url-parse` to resolve Tangled DID/NSID from `.git/config` remote URLs. - [ ] Develop a "Context Resolver" module to infer repository context (DID) from the current working directory. - [ ] Implement fallback mechanisms if no git remote is found or DID cannot be resolved (error handling). @@ -33,58 +37,67 @@ This document outlines the development tasks for the Tangled CLI, based on the ` - [ ] 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`). ## 5. Repository Management + - [ ] Implement `tangled repo create ` command. - [ ] Implement `tangled repo view` command (display repo details). - - [ ] Support `--json` output with field filtering (e.g., `--json name,cloneUrl,description`) using `lodash/pick`). + - [ ] Support `--json` output with field filtering (e.g., `--json name,cloneUrl,description`) using `lodash/pick`). ## 6. Issue Management + - [ ] Implement `tangled issue create "" [--body "<body>" | --body-file <file> | -F -]` command. - [ ] Implement `tangled issue list [--json "id,title"]` command. - - [ ] Support `--json` output with field filtering. + - [ ] Support `--json` output with field filtering. ## 7. 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. + - [ ] 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"`. + - [ ] 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"`. + - [ ] 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"`. ### 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. + - [ ] 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). + - [ ] 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. ## 8. Output & LLM Integration + - [ ] Implement output formatting based on `is-interactive` check. - - [ ] "Human Mode" (TTY): Use `cli-table3` for pretty tables. - - [ ] "Machine Mode" (Pipe/`--json`): Plain text or JSON output. + - [ ] "Human Mode" (TTY): Use `cli-table3` for pretty tables. + - [ ] "Machine Mode" (Pipe/`--json`): Plain text or JSON output. - [ ] Implement `--json` flag for structured output. - [ ] Implement `--no-input` flag to force CLI to error on unresolved context or missing flags (Fail Fast, Fail Loud principle). ## 9. Testing + - [ ] Set up a testing framework (e.g., Jest, Vitest). - [ ] Write unit tests for core modules (Auth, Context Resolver, API client). - [ ] Write integration tests for CLI commands. ## 10. Documentation & Deployment + - [ ] Generate CLI help documentation (`commander` usually handles this). - [ ] Consider packaging/distribution strategy (npm, standalone binary). ## 11. Outstanding Issues / Future Considerations (from README) + - [ ] Secure cross-platform AT Proto session storage (OS keychain). - [ ] Git authentication management similar to GitHub CLI (SSH keys, 1Password integration). - [ ] Define clear precedence order for settings resolution (local config, home folder, CLI flags). -- [ ] Consider adding extensions/plugins (Out of Scope for V1, but keep in mind). \ No newline at end of file +- [ ] Consider adding extensions/plugins (Out of Scope for V1, but keep in mind).