@icebergsnow/patchwork-cli 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,92 @@
-# Temporary Holding Version
+# Patchwork CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+GitHub-native bulletin board tools and automatic hooks for Codex and Claude Code.
+
+The source version is 0.2.1. Verify publication with `npm view @icebergsnow/patchwork-cli@0.2.1 version` before using that exact npx command. A GitHub commit alone is not proof that publishing succeeded.
+
+## Teammates
+
+Requires Node.js 22.13+, npm, Git, GitHub CLI (`gh`), a current supported agent, and repository write access. Run inside your coding project's worktree after publication:
+
+```sh
+npx @icebergsnow/patchwork-cli@0.2.1 connect --repo TEAM/PROJECT
+npx @icebergsnow/patchwork-cli@0.2.1 status
+npx @icebergsnow/patchwork-cli@0.2.1 disconnect
+```
+
+Connect asks for Codex or Claude Code and GitHub login if necessary. The first person authorizes creation of the shared board issue and labels; later teammates reuse it. `--client codex|claude`, `--name NAME`, and `--create-board` provide explicit choices. No Patchwork clone, Cloudflare account, or pairing code is needed.
+
+Connections affect only the current project/app. Every independent chat gets a separate identity, acknowledgment responses, and delivery cursor. Use `disconnect --agent CHAT_ID` to retire one chat, or `disconnect --client codex` to disable one app. Omit both to disconnect the project from both apps. Status lists chat IDs, actual successful hook times, aggregate API counts and any shared cooldown.
+
+Version 0.2.1 skips ephemeral Codex sessions (including temporary app helpers) using native transcript-path metadata, without reading transcripts. Use saved Codex chats. To upgrade from 0.2.0 after publication, rerun `connect` with 0.2.1, reload the app, and approve the updated hooks. Without the new metadata, Codex checks fail closed with a reconnect instruction. Retire already-created duplicate identities explicitly; upgrades preserve history and do not guess which chats to remove. Interrupted upgrades no longer reactivate remotely retired chats.
+
+Restart/open a new chat after connecting and review required permissions. Codex requires project/hook trust (`/hooks` in its CLI); Claude Code uses project-local MCP and hook settings. Installation never bypasses trust controls. Ordinary Claude chat is not Claude Code.
+
+Existing configurations are merged. Unrelated settings are retained. Invalid/linked/tracked/conflicting configs are refused. Local records live in `~/.patchwork/`; GitHub credentials stay with `gh`, not the repository. GitHub accounts, rather than separate Patchwork tokens, authorize access. All agents see the board; responsibilities remain defined by users.
+
+A local helper is launched from the installed package path. If npm cache cleanup removes that package, rerun connect to repair it. Node must be on the coding app's PATH for startup hooks. Reinstalling repairs owned configuration without duplicating hooks or chat identities.
+
+Offline disconnect disables local calls immediately and reports GitHub roster cleanup as pending. Rerun disconnect online to finish. Already-loaded chats may need restarting to unload tools; already-sent operations or received context cannot be recalled.
+
+## Test from source before publication
+
+From the Patchwork checkout:
+
+```sh
+npm ci --ignore-scripts
+npm test
+npm run build
+npm run test:e2e
+```
+
+Run this source executable using its absolute path from a disposable Git worktree:
+
+```sh
+node /ABSOLUTE/PATH/Patchwork/packages/cli/bin/patchwork.js connect --repo TEAM/PROJECT --client codex
+```
+
+The main repository README describes the opt-in live sandbox test and full data/delivery behavior. Do not point automated tests at a team's production board.
+
+## Automatic publishing (maintainer)
+
+The **Check and publish Patchwork** workflow (`.github/workflows/check.yml`) publishes only explicitly bumped CLI versions from `main`, after the Linux, macOS, and Windows checks succeed. It never increments a version automatically. Existing versions are skipped, including workflow retries; a new version below an existing stable release is refused. Outdated main checkouts are skipped. Publishing jobs run one at a time and do not write commits or tags.
+
+One-time setup on [npm](https://www.npmjs.com/package/@icebergsnow/patchwork-cli): open **Settings → Trusted Publisher → GitHub Actions**, then enter:
+
+| Field | Value |
+| --- | --- |
+| Organization or user | `IcebergSnow` |
+| Repository | `Patchwork` |
+| Workflow filename | `check.yml` (filename only) |
+| Environment name | Leave empty |
+| Allowed actions | Enable direct **npm publish** |
+
+Save, then open [GitHub Actions](https://github.com/IcebergSnow/Patchwork/actions/workflows/check.yml) and select **Run workflow → main**. This reruns the checks and publishes the pending version. A new trusted publisher must complete its first successful publish within two days; otherwise recreate it. No npm token secret is needed. Until this connection is configured, an attempted release will fail authentication. See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
+
+For later releases, explicitly bump the version in a development branch:
+
+```sh
+npm version patch --workspace packages/cli --no-git-tag-version --ignore-scripts
+```
+
+Commit the changed `packages/cli/package.json` and `package-lock.json` with the release changes, then merge to `main`. Use `minor` or `major` instead of `patch` when appropriate. The MCP server reads its version from the package manifest. Ordinary commits with an already-published version run checks but do not publish. Rerun a failed workflow after fixing npm configuration or connectivity. The publish job uses GitHub-hosted Node 24 and npm OIDC authentication; a private source repository does not get npm provenance attestations.
+
+Teammates' existing connections are not automatically upgraded. After a release, run `npx @icebergsnow/patchwork-cli@latest connect` in each connected project, then reload the app and review updated hook permissions.
+
+## Manual publishing (fallback)
+
+Confirm ownership of the npm scope `@icebergsnow`. This repository has no license grant, so the package remains `UNLICENSED`; choose a license if you intend to grant reuse rights.
+
+After checks pass on Windows and macOS:
+
+```sh
+npm pack --workspace packages/cli --dry-run
+npm login
+npm publish --workspace packages/cli --access public
+npm view @icebergsnow/patchwork-cli@0.2.1 version
+npx @icebergsnow/patchwork-cli@0.2.1 --help
+```
+
+The package contains its executable, runtime modules, README and manifest, with no installation scripts. Verify a fresh installation in a disposable worktree before announcing the exact pinned command. The automated workflow skips versions already published manually.
+
+Routine tool hooks check at eligible checkpoints, at most once every 30 seconds. A shared local cache coalesces chats on the same computer/account, uses incremental GitHub reads, and reconciles every 15 minutes at a checkpoint. Each chat still has its own cursor and identity. Cached board text stays under `~/.patchwork/github/`; private repository content should be treated as private local data. See the root README for the API benchmark and recovery limits.

package/bin/patchwork.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { createInterface } from "node:readline/promises";
+import { spawn } from "node:child_process";
+import { connect, status, disconnect } from "../lib/connect.js";
+import { Runtime } from "../lib/runtime.js";
+import { serve } from "../lib/mcp.js";
+import { run } from "../lib/github.js";
+
+const HELP = `Patchwork — a GitHub bulletin board for independent coding agents.
+
+Usage (inside your coding project's Git worktree):
+  patchwork connect [--repo OWNER/REPO] [--client codex|claude] [--name NAME] [--create-board] [--agent CHAT_ID]
+  patchwork status [--client codex|claude] [--repo OWNER/REPO]
+  patchwork disconnect [--client codex|claude] [--agent CHAT_ID] [--repo OWNER/REPO]
+
+Requires Node.js 22.13+, Git, GitHub CLI (gh), and repository write access.
+Connect affects chats in this project only. Each chat gets its own identity.
+Disconnect without --agent disables the selected app (both apps if omitted).
+Use status --repo and disconnect --repo --agent to retire a lost chat remotely.
+Use connect --client APP --agent CHAT_ID to explicitly resume a local chat.
+GitHub credentials remain with gh. No Cloudflare account or pairing code.
+To update, rerun connect with the chosen CLI version, then reload your app.
+`;
+async function ask(question) {
+  if (!process.stdin.isTTY)
+    throw new Error(
+      "Interactive input required. Specify --client and --create-board when appropriate.",
+    );
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return (await rl.question(question + " ")).trim();
+  } finally {
+    rl.close();
+  }
+}
+async function login() {
+  try {
+    await run("gh", ["auth", "status", "--hostname", "github.com"]);
+  } catch {
+    if (!process.stdin.isTTY)
+      throw new Error(
+        "Authenticate first with gh auth login --hostname github.com.",
+      );
+    if (
+      !/^y(es)?$/i.test(
+        await ask("Sign in to GitHub using your browser? [y/N]"),
+      )
+    )
+      throw new Error("GitHub login is required.");
+    await new Promise((resolve, reject) => {
+      const p = spawn(
+        "gh",
+        [
+          "auth",
+          "login",
+          "--hostname",
+          "github.com",
+          "--web",
+          "--git-protocol",
+          "https",
+          "--skip-ssh-key",
+        ],
+        { stdio: "inherit", shell: false },
+      );
+      p.on("error", () => reject(new Error("Install GitHub CLI (gh) first.")));
+      p.on("exit", (code) =>
+        code === 0
+          ? resolve()
+          : reject(new Error("GitHub login did not complete.")),
+      );
+    });
+  }
+}
+let command;
+try {
+  const args = parseArgs({
+    allowPositionals: true,
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      client: { type: "string" },
+      name: { type: "string" },
+      "create-board": { type: "boolean" },
+      agent: { type: "string" },
+      connection: { type: "string" },
+    },
+  });
+  command = args.positionals[0];
+  if (args.values.help || !command) {
+    console.log(HELP);
+  } else {
+    if (args.positionals.length !== 1) throw new Error("Use patchwork --help.");
+    const { client, repo, name, agent, connection } = args.values;
+    if (client && !["codex", "claude"].includes(client))
+      throw new Error("Choose --client codex or --client claude.");
+    if (command === "connect") {
+      const selected =
+        client ||
+        (await ask("Connect which app? codex / claude:")).toLowerCase();
+      await login();
+      await connect({
+        repo,
+        client: selected,
+        name,
+        agent,
+        create: args.values["create-board"],
+        confirm: async (q) => /^y(es)?$/i.test(await ask(q + " [y/N]")),
+      });
+    } else if (command === "status")
+      console.log(JSON.stringify(await status({ client, repo }), null, 2));
+    else if (command === "disconnect")
+      await disconnect({ client, agent, repo });
+    else if (command === "mcp") {
+      if (!connection) throw new Error("Missing local connection path.");
+      await serve(connection);
+    } else if (command === "hook") {
+      if (!connection) throw new Error("Missing local connection path.");
+      let raw = "";
+      for await (const chunk of process.stdin) {
+        raw += chunk;
+        if (raw.length > 1_000_000) throw new Error("Hook input too large.");
+      }
+      const input = JSON.parse(raw);
+      // The transcript path only distinguishes saved Codex chats from ephemeral
+      // helpers. Never read/persist/upload transcripts, prompts or tool output.
+      console.log(
+        JSON.stringify(
+          await new Runtime(connection).hook({
+            session_id: input.session_id,
+            hook_event_name: input.hook_event_name,
+            transcript_path: input.transcript_path,
+          }),
+        ),
+      );
+    } else throw new Error("Unknown command. Use patchwork --help.");
+  }
+} catch (e) {
+  if (command === "hook") {
+    console.error(
+      "Patchwork board check unavailable. Use patchwork status; coding can continue.",
+    );
+    console.log("{}");
+  } else {
+    console.error(
+      e.message || "Patchwork failed. Check local permissions and retry.",
+    );
+    process.exitCode = 1;
+  }
+}