@repo-os/repoos 0.5.59 → 0.5.61

package/dist/.build-info.json

@@ -1,5 +1,5 @@
 {
-  "hash": "54bb7cbb6f6758af0e4594f62905c10fa0aa98c53e313ec47f2d21da7c028692",
-  "version": "0.5.59",
+  "hash": "d8f2fd84b0323805456be5ae097bb68374f6464ff9c4a181f08c8a64066807ab",
+  "version": "0.5.61",
   "devUi": false
 }

package/dist/.build-stamp.json

@@ -1,3 +1,3 @@
 {
-  "generatedAt": "2026-09-29T23:17:06.252Z"
+  "generatedAt": "2026-09-30T16:02:14.887Z"
 }

package/dist/cli/help.d.ts

@@ -0,0 +1,17 @@
+/** Commands whose own argument parser already handles `--help`. */
+export declare const SELF_HELP_COMMANDS: Set<string>;
+/** Resolve an alias to its canonical command name (identity when not an alias). */
+export declare function canonicalCommand(name: string): string;
+/** Full usage for a command (or alias), without the leading `repoos`, or null. */
+export declare function commandUsage(name: string): string | null;
+/**
+ * The full `repoos help` text at `width` — grouped command table plus
+ * examples. Returns a string so it is unit-testable at fixed widths.
+ */
+export declare function renderHelp(width?: number): string;
+export declare function printHelp(width?: number): void;
+/**
+ * Print `repoos <name> --help`. Returns false when `name` is not a known
+ * command (so the caller can fall through to its normal dispatch).
+ */
+export declare function printCommandHelp(name: string, width?: number): boolean;

package/dist/cli/help.js

@@ -0,0 +1,270 @@
+/**
+ * `repoos help` and per-command `repoos <cmd> --help` (#0591).
+ *
+ * The single command table below drives both surfaces, so the top-level help
+ * and a command's own usage can never drift apart. Top-level help groups
+ * commands under headings and shows the command name only in the left column;
+ * flags get their own dim wrapped line under the description, and the full
+ * usage line lives in per-command help rather than inline.
+ */
+import { readVersion } from "../core/version.js";
+import { c } from "./colors.js";
+import { table, termWidth, visibleWidth, wrap } from "./layout.js";
+/** Commands whose own argument parser already handles `--help`. */
+export const SELF_HELP_COMMANDS = new Set(["support", "tunnel", "shot", "uninstall"]);
+const GROUPS = [
+    {
+        name: "Setup",
+        commands: [
+            {
+                name: "init",
+                usage: "init [name]",
+                desc: "Scaffold work/, repoos.toml, AGENTS.md; guided flow for a new project",
+            },
+            {
+                name: "upgrade",
+                usage: "upgrade [--channel beta|canary|rc]",
+                desc: "Self-update a standalone (curl-installed) repoos",
+                flags: "--channel beta|canary|rc",
+            },
+            {
+                name: "uninstall",
+                usage: "uninstall [--yes]",
+                desc: "Remove the standalone (curl-installed) repoos from this machine",
+                flags: "--yes",
+            },
+        ],
+    },
+    {
+        name: "Tasks",
+        commands: [
+            {
+                name: "list",
+                usage: "list [status]",
+                desc: "Show the board, or one status column (inbox|ready|active|review|done)",
+            },
+            { name: "show", usage: "show <id>", desc: "Show a task's full spec" },
+            {
+                name: "new",
+                usage: 'new "<title>" [--ai --type <t> --area <a> --priority <p> --body <b>]',
+                desc: "Create a task",
+                flags: "--ai --type --area --priority --body",
+            },
+            {
+                name: "new-doc",
+                usage: 'new-doc "<desc>"',
+                desc: "Create a document from a description via the PM agent",
+            },
+            {
+                name: "note",
+                usage: 'note <id> "<text>"',
+                desc: "Append a note to a task's activity log",
+            },
+            {
+                name: "mv",
+                usage: "mv <id> <status> [--note <text>] [--force-not-merged]",
+                desc: "Move a task to a new status — never merges code",
+                flags: '--note "..." · --force-not-merged',
+            },
+            {
+                name: "update",
+                usage: "update <id> [flags]",
+                desc: "Edit a task's metadata or body",
+                flags: "--title --area --priority --type --body --branch --assigned-to",
+            },
+            {
+                name: "index",
+                usage: "index [--json]",
+                desc: "Rebuild the derived index cache",
+                flags: "--json",
+            },
+            {
+                name: "gc",
+                usage: "gc [--yes|--dry-run]",
+                desc: "Collect leaked task worktrees and branches",
+                flags: "--yes · --dry-run",
+            },
+        ],
+    },
+    {
+        name: "Health",
+        commands: [
+            {
+                name: "status",
+                usage: "status [--json]",
+                desc: "One-screen health snapshot: server, build, board, worktrees, tunnel, git",
+                flags: "--json",
+            },
+            {
+                name: "check",
+                usage: "check [--profile <name>] [--changed <ref>] [--print-plan] [--local-tests]",
+                desc: "Definition-of-done gate: runs the plan declared in repoos.toml",
+                flags: "--profile <name> · --changed <ref> · --print-plan · --local-tests",
+            },
+            {
+                name: "doctor",
+                usage: "doctor [--json] [--verbose] [--probe <cli>] [--binary <path>]",
+                desc: "Readiness preflight: config, layout, tools, server and secrets",
+                flags: "--json · --verbose · --probe <cli> · --binary <path>",
+            },
+            {
+                name: "certify",
+                usage: "certify <cli> [--yes] [--json] [--binary <path>]",
+                desc: "Run the adapter contract suite and record certification evidence",
+                flags: "--yes · --json · --binary <path>",
+            },
+            {
+                name: "support",
+                usage: "support [bundle|inspect] [--dry-run|--out <path>|--json]",
+                desc: "Write or inspect a redacted diagnostic bundle",
+                flags: "bundle: --dry-run --out <path> · inspect: --json",
+            },
+        ],
+    },
+    {
+        name: "Server",
+        commands: [
+            {
+                name: "serve",
+                usage: "serve [--port N] [--host <h>] [--no-tailscale-https] [--quiet]",
+                desc: "Start the local server (live API + SSE stream)",
+                flags: "--port N · --host <h> · --no-tailscale-https · --preview-overrides · --no-preview-overrides · --quiet",
+            },
+            {
+                name: "stop",
+                usage: "stop [--port N]",
+                desc: "Stop this repo's serve process (by its own lockfile)",
+                flags: "--port N",
+            },
+            {
+                name: "service",
+                usage: "service <sub>",
+                desc: "Manage background services",
+                flags: "list|status|install|start|stop|restart|enable|disable|remove|health",
+            },
+            {
+                name: "tunnel",
+                usage: "tunnel <sub>",
+                desc: "Publish local apps via Cloudflare Tunnel + Zero Trust",
+                flags: "setup|create|destroy|rename|allow|deny|start|install|stop|list|status · create: --port --domain --allow --no-access",
+            },
+            {
+                name: "shot",
+                usage: "shot [<route|url>] [--target <t>] [--selector <css>] [--task <id>]",
+                desc: "Capture preview screenshots into the task's shots folder",
+                flags: "--target --selector --task --base --wait --viewport --full-page",
+            },
+        ],
+    },
+];
+const EXAMPLES = [
+    { cmd: "repoos init" },
+    { cmd: "repoos init myproject", comment: "guided new-project flow outside a git repo" },
+    {
+        cmd: 'repoos new "Add company dashboard" --ai --type feature --area web,server --priority p1',
+    },
+    { cmd: 'repoos new-doc "API design doc for the payment system"' },
+    { cmd: "repoos mv 0012 active" },
+    { cmd: 'repoos mv 0012 active --note "Fix the regression in checkout; see review"' },
+    { cmd: 'repoos note 0012 "Handle the reviewer\'s suggestions before the next review"' },
+    { cmd: 'repoos update 0012 --title "New title" --area web,core' },
+    { cmd: "repoos list ready" },
+    { cmd: "repoos doctor", comment: "passing checks are hidden; --verbose shows all" },
+    { cmd: "repoos shot", comment: "screenshot the task preview for the current worktree" },
+    { cmd: "repoos shot /repo/commits/abc123", comment: "capture one route" },
+    { cmd: "repoos shot --target 'Docs site' --selector '.sidebar'" },
+    { cmd: "repoos status", comment: "one-screen health snapshot" },
+    { cmd: "repoos status --json", comment: "machine-readable, for agents/tools" },
+    { cmd: "repoos index --json", comment: "machine-readable, for agents/tools" },
+    { cmd: "repoos serve", comment: "live API + SSE at http://127.0.0.1:7171" },
+];
+/** Command aliases accepted by the dispatcher (`src/cli/index.ts`). */
+const ALIASES = {
+    ls: "list",
+    cat: "show",
+    move: "mv",
+    add: "new",
+    reindex: "index",
+    server: "serve",
+};
+/** Resolve an alias to its canonical command name (identity when not an alias). */
+export function canonicalCommand(name) {
+    return ALIASES[name] ?? name;
+}
+/** Full usage for a command (or alias), without the leading `repoos`, or null. */
+export function commandUsage(name) {
+    const canonical = canonicalCommand(name);
+    for (const group of GROUPS) {
+        for (const cmd of group.commands)
+            if (cmd.name === canonical)
+                return cmd.usage;
+    }
+    return null;
+}
+/** One EXAMPLES row, wrapping the command and moving its comment down if needed. */
+function renderExample(ex, width) {
+    const indent = "  ";
+    const base = c.dim("$") + " " + ex.cmd;
+    const comment = ex.comment ? c.dim("# " + ex.comment) : "";
+    const fitsOnOneLine = !ex.comment || visibleWidth(indent) + visibleWidth(base) + 2 + visibleWidth(comment) <= width;
+    if (fitsOnOneLine) {
+        return wrap(base + (comment ? "  " + comment : ""), width - indent.length, indent);
+    }
+    const commentIndent = "      ";
+    return [
+        wrap(base, width - indent.length, indent),
+        wrap(comment, width - commentIndent.length, commentIndent),
+    ].join("\n");
+}
+/**
+ * The full `repoos help` text at `width` — grouped command table plus
+ * examples. Returns a string so it is unit-testable at fixed widths.
+ */
+export function renderHelp(width = termWidth()) {
+    const lines = [""];
+    lines.push(wrap(`${c.bold(c.cyan("RepoOS"))} ${c.dim("v" + readVersion())} — the repo is the operating system`, width - 2, "  "));
+    lines.push("");
+    lines.push("  " + c.bold("USAGE"));
+    lines.push("    repoos <command> [args]");
+    lines.push("    repoos <command> --help");
+    lines.push(...wrap(c.dim("full usage and flags for one command"), Math.max(1, width - 6), "      ").split("\n"));
+    for (const group of GROUPS) {
+        lines.push("");
+        lines.push("  " + c.bold(group.name));
+        lines.push(table(group.commands.map((cmd) => ({
+            label: c.cyan(cmd.name),
+            description: cmd.desc + (cmd.flags ? "\n" + c.dim("flags: " + cmd.flags) : ""),
+        })), { indent: 4, gap: 2, width }));
+    }
+    lines.push("");
+    lines.push("  " + c.bold("EXAMPLES"));
+    for (const ex of EXAMPLES)
+        lines.push(renderExample(ex, width));
+    lines.push("");
+    return lines.join("\n");
+}
+export function printHelp(width = termWidth()) {
+    console.log(renderHelp(width));
+}
+/**
+ * Print `repoos <name> --help`. Returns false when `name` is not a known
+ * command (so the caller can fall through to its normal dispatch).
+ */
+export function printCommandHelp(name, width = termWidth()) {
+    const canonical = canonicalCommand(name);
+    for (const group of GROUPS) {
+        const cmd = group.commands.find((entry) => entry.name === canonical);
+        if (!cmd)
+            continue;
+        const lines = [""];
+        lines.push(...wrap(c.bold("repoos") + " " + cmd.usage, width - 2, "  ").split("\n"));
+        lines.push(...wrap(cmd.desc, width - 2, "  ").split("\n"));
+        if (cmd.flags) {
+            lines.push(...wrap(c.dim("flags: " + cmd.flags), width - 2, "  ").split("\n"));
+        }
+        lines.push("");
+        console.log(lines.join("\n"));
+        return true;
+    }
+    return false;
+}

package/dist/cli/index.js

@@ -23,6 +23,7 @@ import { checkBuild } from "../core/build.js";
 import { loadConfig } from "../core/config.js";
 import { reexecAfterStaleBuild, reexecUnderBunIfRequested } from "../core/runtime.js";
 import { c } from "./colors.js";
+import { commandUsage, printCommandHelp, printHelp, SELF_HELP_COMMANDS } from "./help.js";
 import { readVersion } from "../core/version.js";
 // node:sqlite (used by db.ts/auth-store.ts) is still marked experimental on
 // supported Node versions and prints a warning the first time it's loaded.
@@ -39,95 +40,6 @@ process.on("warning", (warning) => {
     console.warn(warning);
 });
 const VERSION = readVersion();
-// Column where COMMANDS descriptions start, measured from the start of the
-// command text (not counting the leading 4-space indent). Wide enough for
-// the longest single-line entry ("gc [--yes|--dry-run]", 21 chars) plus a
-// 2-space gap. Kept as one constant (rather than hand-counted spaces per
-// line) so every row stays aligned when an entry is added or renamed.
-const CMD_COL = 23;
-const CMD_INDENT = " ".repeat(4 + CMD_COL);
-/**
- * A COMMANDS row: `cmd` is plain text (for width math), `desc` may contain
- * ANSI codes. Callers join rows with `"\n    "` — the 4-space indent lives
- * in the join separator (and the template literal for the first row), not
- * here, so a row must not add its own leading indent.
- */
-function cmdRow(cmd, desc) {
-    if (cmd.length >= CMD_COL) {
-        // Too long to share a line with its description — command on its own
-        // line, description indented to the same column as every other row.
-        return `${c.cyan(cmd)}\n${CMD_INDENT}${desc}`;
-    }
-    return `${c.cyan(cmd)}${" ".repeat(CMD_COL - cmd.length)}${desc}`;
-}
-// Column where trailing `# comment`s line up in the EXAMPLES block below.
-const EX_COL = 28;
-/** An EXAMPLES row; see cmdRow's doc comment re: indentation living in the join. */
-function exRow(cmd, comment) {
-    if (!comment)
-        return `${c.dim("$")} ${cmd}`;
-    const pad = " ".repeat(Math.max(1, EX_COL - cmd.length));
-    return `${c.dim("$")} ${cmd}${pad}${c.dim("# " + comment)}`;
-}
-function help() {
-    const commandLines = [
-        cmdRow("check", "Definition-of-done gate: runs the check plan declared in repoos.toml"),
-        cmdRow("check --profile full", "Run every declared step, including ones held back from a routine run"),
-        cmdRow("check --changed main", "Fast pre-review pass over steps affected by changed paths"),
-        cmdRow("check --print-plan", "Print the resolved plan as [[check.steps]] TOML to commit"),
-        cmdRow("shot [<route|url>]", `Capture preview screenshots into the task's shots folder   ${c.dim("flags: --target --selector --task --base --wait --full-page")}`),
-        cmdRow("init [name]", "Scaffold work/, repoos.toml, AGENTS.md; outside a git repo runs a guided flow that can launch the web console"),
-        cmdRow("list [status]", `Show the board (or one column: ${c.dim("inbox|ready|active|review|done")})`),
-        cmdRow("status [--json]", "One-screen health snapshot: server, build freshness, board, worktrees, tunnel, git"),
-        cmdRow("doctor [--json] [--probe <cli>] [--binary <path>]", "Readiness preflight: identity, config, layout, tools, check plan, server, secrets (--probe runs a live contract check; --binary overrides PATH resolution)"),
-        cmdRow("certify <cli> [--yes] [--binary <path>]", "Run the adapter contract suite and write certification evidence into agent-compatibility.json (--binary probes a specific binary)"),
-        cmdRow("support bundle", "Write a redacted, inspectable diagnostic bundle for failed setups"),
-        cmdRow("show <id>", "Show a task's full spec"),
-        cmdRow("mv <id> <status>", `Move a task to a new status — never merges code   ${c.dim('flags: --note "...", --force-not-merged')}`),
-        cmdRow('note <id> "<text>"', "Append a free-form note to a task's activity log"),
-        cmdRow("update <id>", `Edit a task's metadata/body   ${c.dim("flags: --title --area --priority --type --body --branch --assigned-to")}`),
-        cmdRow('new "<title>"', `Create a task   ${c.dim("flags: --ai --type --area --priority --body")}`),
-        cmdRow('new-doc "<desc>"', "Create a document from a description via PM agent"),
-        cmdRow("index [--json]", "Rebuild the derived index cache"),
-        cmdRow("gc [--yes|--dry-run]", "Collect leaked task worktrees/branches (done/absent tasks, integrate candidates)"),
-        cmdRow("serve [--port N]", `Start the local server (live API + SSE stream)   ${c.dim("flags: --host, --no-tailscale-https, --preview-overrides, --no-preview-overrides")}`),
-        cmdRow("stop [--port N]", "Stop this repo's serve process (by its own lockfile)"),
-        cmdRow("service [sub]", `Manage background services ${c.dim("list|status|install|start|stop|restart|enable|disable|remove")}`),
-        cmdRow("tunnel <sub>", `Publish local apps via Cloudflare Tunnel + Zero Trust ${c.dim("(setup|create|allow|deny|rename|destroy|start|install|stop|list|status)")}`),
-        cmdRow("upgrade [--channel beta|canary|rc]", `Self-update a standalone (curl-installed) repoos to the latest release\n${CMD_INDENT}(stable by default; --channel tracks a prerelease line instead)`),
-        cmdRow("uninstall [--yes]", "Remove the standalone (curl-installed) repoos from this machine"),
-    ].join("\n    ");
-    const exampleLines = [
-        exRow("repoos init"),
-        exRow("repoos init myproject", "guided new-project flow outside a git repo"),
-        exRow('repoos new "Add company dashboard" --ai --type feature --area web,server --priority p1'),
-        exRow('repoos new-doc "API design doc for the payment system"'),
-        exRow("repoos mv 0012 active"),
-        exRow('repoos mv 0012 active --note "Fix the regression in checkout; see review"'),
-        exRow('repoos note 0012 "Handle the reviewer\'s suggestions before the next review"'),
-        exRow('repoos update 0012 --title "New title" --area web,core'),
-        exRow("repoos list ready"),
-        exRow("repoos shot", "screenshot the task preview for the current worktree"),
-        exRow("repoos shot /repo/commits/abc123", "capture one route"),
-        exRow("repoos shot --target 'Docs site' --selector '.sidebar'"),
-        exRow("repoos status", "one-screen health snapshot"),
-        exRow("repoos status --json", "machine-readable, for agents/tools"),
-        exRow("repoos index --json", "machine-readable, for agents/tools"),
-        exRow("repoos serve", "live API + SSE at http://127.0.0.1:7171"),
-    ].join("\n    ");
-    console.log(`
-  ${c.bold(c.cyan("RepoOS"))} ${c.dim("v" + VERSION)} — the repo is the operating system
-
-  ${c.bold("USAGE")}
-    repoos <command> [args]
-
-  ${c.bold("COMMANDS")}
-    ${commandLines}
-
-  ${c.bold("EXAMPLES")}
-    ${exampleLines}
-`);
-}
 function main() {
     const [cmd, ...rest] = process.argv.slice(2);
     // Run every command under Bun when it's available (opt out with
@@ -147,6 +59,18 @@ function main() {
     // where a re-exec would restart the whole guided flow). Display-only.
     if (cmd === "serve" || cmd === "server")
         setServeProcessTitle(serveProcessTitle());
+    // Per-command help (#0591): `repoos <cmd> --help` prints that command's full
+    // usage instead of running it. Only the *first* argument counts, so a literal
+    // value like `repoos mv 0012 active --note "--help"` still runs the command.
+    // Commands that already implement `--help` themselves keep their own, richer
+    // output; aliases (`ls`, `server`, …) resolve to their canonical entry.
+    if (cmd &&
+        (rest[0] === "--help" || rest[0] === "-h") &&
+        !SELF_HELP_COMMANDS.has(cmd) &&
+        commandUsage(cmd) !== null) {
+        printCommandHelp(cmd);
+        return;
+    }
     // Staleness check — skip for version/help since those read no source, and
     // for `status`/`check` which report staleness themselves as first-class
     // output (a second, louder warning above their own would be noise).
@@ -283,11 +207,11 @@ function main() {
         case "help":
         case "--help":
         case "-h":
-            help();
+            printHelp();
             break;
         default:
             console.error(c.red(`  Unknown command: ${cmd}`));
-            help();
+            printHelp();
             process.exitCode = 1;
     }
 }

package/dist/cli/layout.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Width-aware terminal layout helpers (#0591).
+ *
+ * The CLI prints with fixed `padEnd` columns and no knowledge of the terminal
+ * width, so long text wraps back to column 0 under the terminal's own,
+ * unaware line wrapping and breaks hanging indents (`repoos help`,
+ * `repoos doctor`, the serve banner). These helpers are the shared,
+ * dependency-free fix: `visibleWidth` and `wrap` measure and break text while
+ * ignoring ANSI SGR codes, and `table`/`kv` lay out a label column with a
+ * wrapped description column.
+ *
+ * Pure functions (width is a parameter, never read from the terminal inside
+ * them), so they are unit-testable at fixed widths. Zero runtime deps: no
+ * chalk, wrap-ansi or cli-table3.
+ */
+/** Visible width of `s` in display columns, ignoring ANSI SGR codes. */
+export declare function visibleWidth(s: string): number;
+/**
+ * The width to lay out for. `$COLUMNS` wins when it is set and positive — so
+ * `COLUMNS=60 repoos help` works even under a TTY, which is how the layout is
+ * verified at fixed widths — then the terminal's own columns, then 80. Capped
+ * at 100 so a very wide terminal doesn't stretch descriptions into unreadable
+ * lines.
+ */
+export declare function termWidth(env?: NodeJS.ProcessEnv, columns?: number | undefined): number;
+/**
+ * ANSI-aware word wrap with a hanging indent. `text` may contain explicit
+ * newlines (they start a new wrapped line); `width` is the visible budget for
+ * each line *excluding* `indent`, so every returned line is at most
+ * `visibleWidth(indent) + width` visible characters wide. Pass the indentation
+ * as `indent` rather than embedding it in `text` — leading whitespace is a
+ * word separator and would be collapsed.
+ */
+export declare function wrap(text: string, width: number, indent?: string): string;
+export interface TableRow {
+    /** Left column — command name or check title. May contain ANSI. */
+    label: string;
+    /** Right column — wrapped at the remaining width. May contain ANSI. */
+    description: string;
+}
+export interface TableOptions {
+    /** Spaces between the label column and the description (default 2). */
+    gap?: number;
+    /** Leading spaces before the label column (default 0). */
+    indent?: number;
+    /** Total width to lay out for (default `termWidth()`). */
+    width?: number;
+    /** Force the label column width instead of sizing to the widest row. */
+    labelWidth?: number;
+}
+/**
+ * A two-column table: a label column sized to its widest entry, then a
+ * description column that word-wraps to the remaining width with a hanging
+ * indent. Every line stays within `width`.
+ */
+export declare function table(rows: readonly TableRow[], opts?: TableOptions): string;
+export interface KVRow {
+    label: string;
+    value: string;
+}
+/** `table` for a label/value listing — the shared shape serve/status/doctor use. */
+export declare function kv(rows: readonly KVRow[], opts?: TableOptions): string;