jjhub 0.1.1

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "jjhub",
+  "version": "0.1.1",
+  "description": "jjh — 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": {
+    "jjh": "./dist/cli/jjh.mjs"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.6.0"
+  },
+  "license": "UNLICENSED",
+  "homepage": "https://jjhub.johnhenry.me",
+  "keywords": [
+    "jujutsu",
+    "jj",
+    "github",
+    "cli",
+    "stacked-prs",
+    "undo",
+    "vcs"
+  ],
+  "author": "John Henry"
+}

package/skills/jjhub-cli/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: jjhub-cli
+description: Drive a running JJHub instance from the command line with the `jjh` 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.
+---
+
+# jjh — the JJHub CLI
+
+`jjh` 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
+server, the same server backing the web UI. Repo context is inferred from the current
+directory's git `origin` remote (override with `--repo`), and any top-level command that
+isn't one of `jjh`'s own nouns is passed straight through to the real `gh` binary.
+
+## 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.
+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`. (`jjh auth login` persists these to a config file
+   instead of needing them exported every shell — see "Server connection" below.)
+3. **Invoke commands**: `npm run jjh -- <command> [args]` in development, or `jjh <command>`
+   directly if installed as a binary (`bin/jjh.mjs`).
+4. **Initialize the overlay** for a repo before using any other command:
+   `jjh repo init [owner/name]` (infers `owner/name` from the cwd's git origin if omitted).
+
+The same JJHub server also backs a web UI (`npm run web:dev` from the repo root, in a
+second terminal — see [`web/README.md`](../../web/README.md)); the CLI and the web UI are
+two interchangeable clients over the same state, not separate systems.
+
+## Global flags
+
+- `--repo <owner/name|repoId>` — override the inferred repository context.
+- `--json` — emit machine-readable JSON instead of a human-readable table.
+- `--url <baseUrl>` — override the server URL for this invocation (same as `JJHUB_URL`).
+
+## Commands
+
+```
+repo init [owner/name] [--github-token pat]
+                                        create the JJHub overlay for this repo
+repo list                              list repositories you can access
+                                        (permissions come live from GitHub)
+repo archive | unarchive               retire/reactivate (archived = read-only, sync skipped)
+repo delete                            hard-delete incl. op log (ops credential only)
+
+user list                              list known users (identity is GitHub-federated)
+
+change new <title> [--parent CHG-x] [--stack id]
+change list
+change show <changeId>
+change describe <changeId> [--title t] [--description d]
+change amend <changeId>
+change squash <changeId>
+change abandon <changeId>
+change restack <changeId>              rebase a needs-restack change onto its rewritten ancestor
+change commit <changeId> <file...> [-m msg]
+                                        commit working-tree files onto the change's branch
+change diff <changeId>                 per-file diffs of what the change contains
+change files <changeId>                list locally-stored files (contentMode "local" repos only)
+change land <changeId> [--force]       waits for real CI triggered by its own ready flip,
+                                        re-syncs a behind branch, then merges; --force bypasses
+change split <changeId> <newTitle>
+change checks <changeId>               list GitHub check runs for a change
+
+stack create <title> [--id x] [--changes CHG-1,CHG-2]
+stack list
+stack land <stackId> [--force]         same check-run gate as change land
+stack delete <stackId>                 disband — members become loose changes (undoable)
+stack reorder <stackId> <changeId,changeId,...>
+stack checks <stackId>                 every member's GitHub check runs, one batched round trip
+
+bookmark list
+bookmark delete <name> [--force]       --force required for the default (trunk) bookmark
+bookmark set <name> <tracked|view> [--target CHG-x]
+
+op log                                 "@" marks the current head operation
+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 resolve <conflictId> <state>
+    state: unresolved | left | right | edited | preserve_unresolved
+
+sync                                   push overlay state to GitHub
+
+auth login [--url <baseUrl>] [--scope read|write] [--repos o/a,o/b]
+                                        sign in with GitHub via the device flow (saves an
+                                        OAuth token to ~/.config/jjhub). --scope read mints
+                                        a read-only token; --repos fences it to specific
+                                        repositories. --api-key <key> instead saves the
+                                        legacy ops shared secret
+auth sessions                          list your live sessions; auth revoke <id> kills one
+auth logout                            forget the saved connection/token
+auth status                            who the saved credential authenticates as
+
+mcp serve                              MCP server over stdio (50 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
+agents-md                              print an AGENTS.md section teaching coding agents to
+                                       prefer jjh over raw git/gh (jjh agents-md >> AGENTS.md)
+
+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]
+    spawn the same sync as a detached background process
+daemon stop [alias] | daemon status [alias]
+```
+
+Anything else (`pr`, `issue`, ...) is passed through to `gh` — e.g. `jjh pr view 7`. `jjh auth`
+is jjh's own command (it manages the *JJHub server* connection); use `gh auth` for GitHub auth.
+
+### 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 `jjh auth login`). Run `jjh 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. `jjh auth status` confirms what's currently in effect.
+
+### Identity & permissions (issue #43: GitHub-federated)
+
+A JJHub user IS a GitHub account. `jjh auth login` runs an OAuth device flow against the
+JJHub server's own authorization server: open the printed URL, sign in with GitHub, confirm
+the code, and the CLI saves a JJHub-issued OAuth token. Every mutation is attributed to that
+identity (visible in `jjh op log`).
+
+What you can do on a repo is asked of GitHub LIVE at request time (cached ~60s):
+GitHub `admin` → owner, `maintain`/`write` → writer, `triage`/`read` → reader. There is no
+internal membership table and nothing to manage in JJHub — manage collaborators on GitHub.
+
+The legacy shared secret (`--api-key` / `JJHUB_API_KEY`) still exists as an ops/emergency
+credential: full access, RBAC bypassed, no attribution. Anonymous requests (no server-side
+`JJHUB_API_KEY` configured at all) remain fully open — dev mode, unchanged.
+
+### GitHub admin verification (optional, separate mode)
+
+This RBAC is entirely JJHub-internal — a JJHub "owner" isn't checked against real GitHub
+permissions at all. If the server has `JJHUB_REQUIRE_GITHUB_VERIFICATION=1` set,
+`jjh repo init` requires `--github-token <pat>` (or falls back to `$GITHUB_TOKEN`): the
+server verifies that token has real `admin` access to the exact `owner/name` being created
+via a live GitHub API call, rejecting creation (403) otherwise. The verified token also
+becomes the new repo's GitHub connection automatically. See the top-level README's "GitHub
+admin verification (optional mode)" section.
+
+For exact, always-current syntax straight from the CLI binary, run `jjh 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 jjh)
+
+[`agents-snippet.md`](./agents-snippet.md) is a short, imperative AGENTS.md
+section — "version control in this repo goes through JJHub; prefer `jjh
+change/stack/undo` over raw git/gh mutations" — the same pattern as GitHub's
+`gh skill install github/gh-stack`. Append it to a tracked repo's own
+AGENTS.md so any AGENTS.md-aware coding agent (Claude Code, Copilot, Cursor,
+Codex, ...) picks up the workflow automatically:
+
+```bash
+jjh 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
+```
+
+## Example workflows
+
+### Create and land a change
+
+```bash
+npm run jjh -- repo init owner/name
+npm run jjh -- change new "Fix: add user validation"
+npm run jjh -- change list                              # note the CHG-n id
+npm run jjh -- stack create "Fix bundle" --changes CHG-1
+npm run jjh -- stack land "Fix bundle"
+```
+
+A single change not part of a stack lands directly: `npm run jjh -- change land CHG-1`.
+
+### Sync a local jj working copy into JJHub
+
+```bash
+cd /path/to/local/jj/repo
+jj bookmark track main --remote=origin   # REQUIRED once per clone (issue #28):
+                                         # without it, already-landed commits look
+                                         # like new local work and the daemon could
+                                         # try to re-project them
+npm run jjh -- repo init alice/my-project
+jj new -m "Implement feature X" && jj commit
+npm run jjh -- daemon . --once      # one-shot sync; omit --once to loop every 5s
+npm run jjh -- op log               # verify the sync landed as a new operation
+```
+
+### Resolve a conflict
+
+```bash
+npm run jjh -- conflict list                              # note the conflict id
+npm run jjh -- conflict resolve CONFLICT-abc123 left       # or: right | edited | preserve_unresolved
+npm run jjh -- conflict list                               # confirm it now reads Resolved
+```
+
+## Undo/redo caution
+
+`jjh undo` and `jjh redo` move the repository's operation-log head pointer — they affect
+*all* state (changes, stacks, bookmarks, conflicts), not just the last command's target.
+Run `jjh op log` first if you're not sure what the current head operation is before undoing.

package/skills/jjhub-cli/agents-snippet.md

@@ -0,0 +1,28 @@
+# Version control in this repo goes through JJHub
+
+This repository is tracked by JJHub (a change/stack/operation overlay on
+GitHub). Use the `jjh` CLI for version-control mutations instead of raw
+`git`/`gh` — every `jjh` action is attributed in an operation log and
+reversible with `jjh undo`, and landing is CI-gated.
+
+- Start work: `jjh change new "<title>"` (not a git branch).
+- Describe/retitle: `jjh change describe CHG-N --title t --description d`.
+- Amend after edits: `jjh change amend CHG-N` (descendants get flagged and
+  restack with one command — no force-push ceremony).
+- Stacked work: `jjh stack create "<title>" --changes CHG-1,CHG-2`;
+  reorder with `jjh stack reorder`; land root-to-tip with
+  `jjh stack land <stackId>` (all-or-nothing, CI-gated).
+- Ship a single change: `jjh change land CHG-N`. Do NOT merge the PR with
+  `gh pr merge` — that bypasses the gate and the op log.
+- Made a mistake: `jjh undo` (works across changes, stacks, bookmarks, and
+  conflicts; `jjh op log` shows what would be undone).
+- Conflicts: `jjh conflict list` / `jjh conflict resolve <id> <state>` —
+  conflicts are durable objects; you can defer them and keep working.
+- Machine output: append `--json` to any command.
+- Repo context is inferred from the git `origin` remote; `--repo owner/name`
+  overrides.
+
+Reads are fine with either tool. Any `jjh` command it doesn't recognize
+(`pr`, `issue`, ...) passes through to the real `gh` unchanged. Full command
+reference: run `jjh help`, or see the served skill at
+`/.well-known/skills/jjhub-cli/SKILL.md` on your JJHub server.