jjhub 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jjhub",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "jjhub — GitHub CLI with Jujutsu-native superpowers: stable change IDs, stacks, platform-wide undo, and conflicts that wait, layered over plain GitHub repos by a JJHub server.",
   "bin": {
     "jjhub": "./dist/cli/jjhub.mjs"

package/skills/jjhub-cli/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: jjhub-cli
-description: Drive a running JJHub instance from the command line with the `jjhub` CLI — create and land changes, manage stacks and bookmarks, resolve conflicts, and undo/redo via the operation log. Use when scripting or automating repository operations against a JJHub server instead of the web UI.
+description: Drive a running JJHub instance (a Jujutsu-native change/stack/operation overlay on GitHub) from the command line with the `jjhub` CLI, or as an agent over MCP, ACP, A2A, or WebMCP — create and land changes, manage stacks and bookmarks, resolve conflicts, coordinate local jj workspaces, and undo/redo via the operation log. Use when scripting or automating repository operations against a JJHub server, or wiring an agent client (Claude Code, Zed, a Claude/ChatGPT connector, an A2A peer) up to one.
 ---
 
-# jjhub — the JJHub CLI
+License: MIT (see the public mirror erisera-code/jjhub-skills, LICENSE).
+
+# jjhub — the JJHub CLI and agent surfaces
 
 `jjhub` is a GitHub CLI (`gh`)-like wrapper with Jujutsu-native superpowers. It is a thin
 client over JJHub's HTTP API: every command reads or mutates state on a running JJHub
@@ -11,21 +13,47 @@ server, the same server backing the web UI. Repo context is inferred from the cu
 directory's git `origin` remote (override with `--repo`), and any top-level command that
 isn't one of `jjhub`'s own nouns is passed straight through to the real `gh` binary.
 
+The CLI is one of five interchangeable surfaces over the same server state and the same
+op log — pick whichever fits the client:
+
+| Surface | What it is | Entry point |
+|---|---|---|
+| CLI | `jjhub`, a `gh`-alike | `npx jjhub@latest <command>`, or `jjhub` once installed |
+| MCP | 133 structured tools | remote: `<server>/mcp` (OAuth 2.1, RFC 9728 auto-discovery); local: `npx jjhub@latest mcp serve` (stdio) or `--http <port>` |
+| ACP | Agent Client Protocol v1, slash-command style | `npx jjhub@latest acp serve` (stdio) — Zed's agent panel and friends |
+| A2A | Agent2Agent v1.0, one skill per registry command | agent card `<server>/.well-known/agent-card.json`; JSON-RPC `POST <server>/a2a`; REST `<server>/a2a/v1` |
+| WebMCP | 133 tools, progressively loaded | in-browser only, from an open JJHub tab — no separate connection |
+
+This file documents the CLI in depth (it is the most complete reference for every verb,
+since ACP/A2A commands are the same verbs under the same names) and points at each other
+surface's own guide for its protocol-specific mechanics. See "Install this skill" below
+for how to wire any of these into an agent client.
+
 ## Setup
 
 See the [top-level README](../../README.md) for full project setup (`npm install`,
 tests, requirements). This section covers just the CLI.
 
-1. **Start the JJHub server** (if not already running): `npm start` from the repo root.
-   Defaults to `http://localhost:3000`; set `PORT` to change it, `JJHUB_DB` to point at a
-   different SQLite file.
+0. **No install needed**: `npx jjhub@latest <command>` fetches and runs the CLI on demand.
+   `npm i -g jjhub` gives a standalone `jjhub` binary if you'd rather not re-fetch every
+   invocation.
+1. **Start the JJHub server** (if not already running, and you're not pointing at a
+   deployment): `npm start` from the repo root. Defaults to `http://localhost:3000`; set
+   `PORT` to change it, `JJHUB_DB` to point at a different SQLite file.
 2. **Point the CLI at it**: `export JJHUB_URL=http://localhost:3000` (this is the default,
-   so only needed if the server is elsewhere). If the server was started with
-   `JJHUB_API_KEY` set, also `export JJHUB_API_KEY=<the same key>` — every request will
-   otherwise get a `401 unauthorized`. (`jjhub auth login` persists these to a config file
-   instead of needing them exported every shell — see "Server connection" below.)
-3. **Invoke commands**: `npm run jjhub -- <command> [args]` in development, or `jjhub <command>`
-   directly if installed as a binary (`bin/jjhub.mjs`).
+   so only needed if the server is elsewhere). Against a real deployment, sign in first —
+   `jjhub auth login --url https://<your-jjhub>` (GitHub device flow) saves a bearer token
+   to `~/.config/jjhub/config.json`, and every subsequent command picks it up with no env
+   vars needed. For a local dev server started with `JJHUB_API_KEY` set, instead
+   `export JJHUB_API_KEY=<the same key>` — every request otherwise gets `401 unauthorized`.
+   Precedence when both a token and a key are present: `JJHUB_TOKEN` (bearer, e.g. from
+   `auth login`) beats `JJHUB_API_KEY` (operator key, sent as `x-api-key`) beats the saved
+   config file. Exporting a login token as `JJHUB_API_KEY` does NOT work — the server
+   rejects it (401). `JJHUB_CONFIG_DIR` overrides `~/.config/jjhub` for the CLI and every
+   agent surface below, if you need an isolated config (a scratch credential, a test
+   harness, a second identity).
+3. **Invoke commands**: `npx jjhub@latest <command> [args]` or `jjhub <command>` once
+   installed; from inside this repo in development, `npm run jjhub -- <command> [args]`.
 4. **Initialize the overlay** for a repo before using any other command:
    `jjhub repo init [owner/name]` (infers `owner/name` from the cwd's git origin if omitted).
 
@@ -44,6 +72,9 @@ two interchangeable clients over the same state, not separate systems.
 ```
 repo init [owner/name] [--github-token pat]
                                         create the JJHub overlay for this repo
+repo create owner/name --public|--private [--description text] [--default-branch name]
+                                        create a NEW repo on GitHub (via the GitHub App) then
+                                        overlay it — --public/--private is required, no default
 repo list                              list repositories you can access
                                         (permissions come live from GitHub)
 repo archive | unarchive               retire/reactivate (archived = read-only, sync skipped)
@@ -63,6 +94,10 @@ change amend <changeId>
 change squash <changeId>
 change abandon <changeId>
 change restack <changeId>              rebase a needs-restack change onto its rewritten ancestor
+change request-review <changeId>       move a draft change into review and mark its PR ready for review
+change return-to-draft <changeId>      return an in-review change and its PR to draft
+change context <changeId>              compact orientation snapshot: status, diff stat, landability,
+                                        checks, conflicts, review health, and derived nextActions in one call
 change commit <changeId> [<file...>] [-m msg] [--delete <path>]... [--expect-head <sha>]
                                         commit working-tree files onto the change's branch;
                                         --delete removes a path in the same commit (repeatable);
@@ -161,6 +196,15 @@ bookmark list
 bookmark delete <name> [--force]       --force required for the default (trunk) bookmark
 bookmark set <name> <tracked|view> [--target CHG-x]
 
+workspace list                         live local jj workspace agents reporting into this repo
+                                        (see "jjhub daemon"), with their last-seen topology observation
+workspace status                       agents, which is primary, and any active lease holder
+workspace primary <workspaceId>        mark a workspace as this repository's primary
+workspace route [<workspaceId>|clear]  show/set/clear the suggested local-write target — a SUGGESTION
+                                        only, never applied implicitly
+workspace connect [aliasOrPath]        start a local daemon for a workspace (= "daemon start")
+workspace disconnect [aliasOrPath]     stop a local daemon for a workspace (= "daemon stop")
+
 view save <name> <revsetExpression>    save a named jj revset expression for later reuse (storage
                                         only — evaluate it with "jjhub revset")
 view list                              list saved views in this repo
@@ -173,9 +217,11 @@ op diff <fromOpId> <toOpId>            structural diff between two operations' i
 undo [--force]                         refused when the head op is a "land" (real merge can't be unwound); --force reverts local state anyway
 redo
 
-conflict list
+conflict list                          ACTIONS column: the states each conflict can still take;
+                                        "historical" = its change already landed, nothing to resolve
 conflict resolve <conflictId> <state>
     state: unresolved | left | right | edited | preserve_unresolved
+    ("superseded" is set by JJHub itself when the change lands; it cannot be chosen)
 
 sync                                   push overlay state to GitHub
 
@@ -200,13 +246,19 @@ ai models --provider <p> [--api-key <key>] [--base-url <url>]
 ai status                               where AI is coming from for you: your own saved connection,
                                         the server operator's default, or not configured at all
 
-mcp serve                              MCP server over stdio (125 tools) for agent clients
+mcp serve                              MCP server over stdio (133 tools) for agent clients
 mcp serve --http <port>                the same tools over Streamable HTTP (POST /)
-acp serve                              Agent Client Protocol agent over stdio (Zed's agent
-                                       panel, ...) — every operation as a slash command
+acp serve                              Agent Client Protocol v1 agent over stdio (Zed's agent
+                                       panel, ...) — modes (read-only/ask/auto), a working-
+                                       repository + dry-run config option, persistent sessions,
+                                       plans and diffs — every operation as a slash command
 agents-md                              print an AGENTS.md section teaching coding agents to
                                        prefer jjhub over raw git/gh (jjhub agents-md >> AGENTS.md)
 
+telemetry flows [--since <ISO8601>] [--surface webmcp|cli|browser|mcp|acp|a2a|api] [--limit N]
+    ongoing telemetry for the read -> patch -> verify -> land -> disconnect -> recover flow
+    across every client surface — per-step p50/p95 duration and error rate
+
 daemon <localRepoPath> [--once] [--interval 5] [--engine auto|subprocess|isomorphic] [--two-way]
     sync a local jj working copy into JJHub (inbound; --two-way mirrors JJHub edits back)
 daemon start [alias|localRepoPath] [--interval 5] [--engine ...] [--two-way]
@@ -249,10 +301,65 @@ content receipts [--repo owner/name|repoId]
 Anything else (`pr`, `issue`, ...) is passed through to `gh` — e.g. `jjhub pr view 7`. `jjhub auth`
 is jjhub's own command (it manages the *JJHub server* connection); use `gh auth` for GitHub auth.
 
+### The other agent surfaces: ACP and A2A
+
+`jjhub acp serve` and the server's A2A endpoint are not CLI subcommands (A2A has no CLI
+entry point at all — it's always part of the running server), but they run the exact same
+verbs as the table above, through a shared command registry
+(`src/agents/commands.ts`, 139 commands: every operation, the hand-written extras `whoami`,
+`land_change`, `land_stack`, `get_land_job`, `delete_bookmark`, `sync_github`,
+`raise_conflict`, plus registry-only composites `stack_status`, `get_conflict`,
+`get_landability`, `land_when_ready`, `watch_change`, `watch_stack`, `get_skill`, `ask`) — so
+anything documented above as a CLI command is also an ACP slash command and an A2A skill
+under the same snake_case name.
+
+**`ask` / `ask_jjhub` (issue #586)** — free text mapped onto ONE command from this same
+registry (deterministic `/command args` parse first, else the caller's own AI connection,
+resolved SERVER-SIDE via `POST /ai/interpret-command` so the process calling it needs no local
+AI env of its own): `jjhub ask "<free text>"`, the A2A skill `ask`, and the MCP tool
+`ask_jjhub` all wrap the exact same interpretation. Prefer it when a caller (an editor agent
+speaking MCP, in particular) only has free text to work with and can't first call
+`list_repositories`/`list_changes`/etc. itself to build a structured call — e.g. an end user
+typed "land CHG-3 in the payments repo" into a chat and the agent should map that onto
+`land_change` without hand-rolling its own NL parsing. Prefer the DIRECT command/tool instead
+whenever the caller already knows exactly which verb and arguments it wants — `ask` adds an
+extra round trip (interpret, then execute) and, for a command needing confirmation (e.g.
+force-land), never bypasses it: it returns the resolved invocation unexecuted and says to call
+the command directly, EXCEPT `ask_jjhub` itself over MCP, which carries the identical
+SEP-2322/elicitation confirmation seam `land_change`/`land_stack`/`delete_bookmark` use, so a
+force-land asked for in free text still asks before it runs. Without an AI provider configured
+for the caller, only a direct `/command args` prompt resolves; the response says so
+(`interpreted: false`, a `reason`) rather than failing.
+
+- **ACP** (`jjhub acp serve`, stdio, Agent Client Protocol v1): sessions have modes
+  (`read-only` refuses mutations; `ask`, the default, confirms force-land/trunk-deletion/
+  force-undo through `session/request_permission` or `elicitation/create`; `auto`
+  auto-approves everything else), a `repository` config option so `/get_change CHG-3` works
+  without repeating the repository id, a `dry_run` config option, and persistent sessions
+  (`session/load`/`list`/`resume`/`close`/`delete`, stored in
+  `~/.config/jjhub/acp-sessions.json` — `JJHUB_ACP_SESSIONS_PATH` overrides the file,
+  `JJHUB_CONFIG_DIR` moves the whole config dir). A dev server with no `JJHUB_API_KEY` needs
+  `JJHUB_ACP_ALLOW_ANONYMOUS=1` on the agent process. Full Zed setup and everything the
+  session exposes: [`docs/guides/COMMON-TASKS.md`](../../docs/guides/COMMON-TASKS.md#drive-jjhub-from-an-editor-agent-panel-acp-eg-zed).
+- **A2A** (spec v1.0 only — the v0.3 compatibility layer was removed; no v0.3 clients):
+  agent card at `/.well-known/agent-card.json` (optionally signed via
+  `JJHUB_A2A_CARD_SIGNING_JWK`, verifiable against `/.well-known/a2a-jwks.json`), JSON-RPC at
+  `POST /a2a`, REST at `/a2a/v1` — one task store shared by both bindings, so a task started
+  on one can be fetched/listed/cancelled on the other. Call a command as a text part
+  (`/list_changes <repositoryId> status=in_review`) or a data part
+  (`{"command": "commit_files", "args": {...}}`); confirmable mutations pause the task in
+  `input-required` (a `confirm` message resumes it), plans stream as `working` updates, and
+  `CancelTask` can interrupt an in-flight skill at its next safe checkpoint. Full detail and
+  the `npm run a2a:exercise` / `npm run acp:exercise` client harnesses (including the shared
+  `--mutate --stress N --land` scratch-repository stress scenario):
+  [`docs/guides/COMMON-TASKS.md`](../../docs/guides/COMMON-TASKS.md#drive-jjhub-agent-to-agent-a2a).
+
 ### Server connection: flags, env vars, or a config file
 
-Precedence is `--flag` > env var (`JJHUB_URL`/`JJHUB_API_KEY`) > `~/.config/jjhub/config.json`
-(written by `jjhub auth login`). Run `jjhub auth login --url http://localhost:3000 --api-key <key>`
+Precedence is `--url` > `JJHUB_URL` > `~/.config/jjhub/config.json` for the server, and
+`JJHUB_TOKEN` (bearer token from `jjhub auth login`) > `JJHUB_API_KEY` (operator key, sent as
+`x-api-key`) > the saved config (token, then apiKey) for the credential; the config file is
+written by `jjhub auth login`. Run `jjhub auth login --url http://localhost:3000 --api-key <key>`
 once and every subsequent command in that shell (any shell, any day) picks it up with no env
 vars needed. `jjhub auth status` confirms what's currently in effect.
 
@@ -284,7 +391,14 @@ admin verification (optional mode)" section.
 For exact, always-current syntax straight from the CLI binary, run `jjhub help` — this file is
 an expanded, example-rich companion to that output, not a replacement for it.
 
-### Install into your repo (teach YOUR coding agents to prefer jjhub)
+## Install this skill
+
+Three independent ways to pick this skill up — use whichever fits the agent you're
+configuring. `GET /.well-known/skills/` on any running JJHub server (including the live
+instance) returns all three as an `installation` object, e.g.
+`curl https://jjhub.erisera.com/.well-known/skills/ | jq .installation`.
+
+### (a) Teach a repo's coding agents to prefer jjhub (AGENTS.md)
 
 [`agents-snippet.md`](./agents-snippet.md) is a short, imperative AGENTS.md
 section — "version control in this repo goes through JJHub; prefer `jjhub
@@ -294,11 +408,82 @@ AGENTS.md so any AGENTS.md-aware coding agent (Claude Code, Copilot, Cursor,
 Codex, ...) picks up the workflow automatically:
 
 ```bash
-jjhub agents-md >> AGENTS.md     # from the CLI
-# or fetch it from a running server:
-curl https://<your-jjhub>/.well-known/skills/jjhub-cli/agents-snippet.md >> AGENTS.md
+npx jjhub@latest agents-md >> AGENTS.md
+```
+
+### (b) Fetch this skill directly (`skills.sh`, or a plain curl/`.well-known` fetch)
+
+The skill content itself (this file plus `agents-snippet.md`) is mirrored, read-only, to the
+public repo [`erisera-code/jjhub-skills`](https://github.com/erisera-code/jjhub-skills) on
+every change (`.github/workflows/publish-skills.yml`, built by
+`scripts/build-skills-dist.ts` — `npm run build:skills` reproduces it locally). Install from
+there with the [skills.sh](https://skills.sh) installer:
+
+```bash
+npx skills add erisera-code/jjhub-skills
+```
+
+Or mirror it by hand into a local `skills/` directory — the same shape either the live
+server's `GET /.well-known/skills/` or the mirror's own `index.json` returns:
+
+```json
+{
+  "skills": [
+    { "name": "jjhub-cli", "url": "/.well-known/skills/jjhub-cli/SKILL.md", "agentsSnippet": "/.well-known/skills/jjhub-cli/agents-snippet.md" }
+  ],
+  "installation": {
+    "skillsCli": "npx skills add erisera-code/jjhub-skills",
+    "claudeCodeMarketplace": "/plugin marketplace add erisera-code/jjhub-skills",
+    "agentsMd": "npx jjhub@latest agents-md >> AGENTS.md",
+    "wellKnown": "https://jjhub.erisera.com/.well-known/skills/",
+    "repository": "https://github.com/erisera-code/jjhub-skills"
+  }
+}
+```
+
+```bash
+mkdir -p skills/jjhub-cli
+curl -s https://jjhub.erisera.com/.well-known/skills/jjhub-cli/SKILL.md -o skills/jjhub-cli/SKILL.md
+curl -s https://jjhub.erisera.com/.well-known/skills/jjhub-cli/agents-snippet.md -o skills/jjhub-cli/agents-snippet.md
+```
+
+`erisera-code/jjhub-skills` also carries a `.claude-plugin/marketplace.json`, so Claude Code
+can add it directly as a plugin marketplace:
+
+```
+/plugin marketplace add erisera-code/jjhub-skills
+/plugin install jjhub-cli@jjhub-skills
 ```
 
+### (c) Wire up an MCP/ACP client, or an A2A peer
+
+- **Claude Code** (MCP): `claude mcp add jjhub --http https://jjhub.erisera.com/mcp`
+  against a deployment (OAuth 2.1 discovered automatically via RFC 9728 — the CLI walks you
+  through sign-in), or point at a local stdio server:
+  ```json
+  { "mcpServers": { "jjhub": { "command": "npx", "args": ["jjhub@latest", "mcp", "serve"] } } }
+  ```
+- **Zed** (ACP), `~/.config/zed/settings.json`:
+  ```json
+  {
+    "agent_servers": {
+      "jjhub": {
+        "command": "npx",
+        "args": ["jjhub@latest", "acp", "serve"],
+        "env": { "JJHUB_URL": "https://jjhub.erisera.com", "JJHUB_TOKEN": "<token from jjhub auth login>" }
+      }
+    }
+  }
+  ```
+  (Running `jjhub auth login` on the same machine first means the `env` block can be
+  omitted entirely — the agent picks up the saved credential from `~/.config/jjhub`.)
+- **A Claude.ai or ChatGPT connector** (remote MCP): add a custom connector pointing at
+  `https://<your-jjhub>/mcp` — both discover the OAuth 2.1 flow automatically (RFC 9728
+  protected-resource metadata); no manual token entry.
+- **An A2A peer**: fetch `https://<your-jjhub>/.well-known/agent-card.json` for the skill
+  list and the two binding URLs (JSON-RPC `/a2a`, REST `/a2a/v1`); see "The other agent
+  surfaces: ACP and A2A" above for the auth model and confirmation flow.
+
 ## Example workflows
 
 ### Create and land a change