@repo-os/repoos 0.5.46 → 0.5.48

package/README.md

@@ -11,7 +11,7 @@ It is **not** a Jira/Linear replacement bolted onto your repo. It is the
 connective tissue for an AI-native workflow: humans define and review work,
 agents read the same files as full context and execute against the repo.
 RepoOS directly spawns and manages coding agents in isolated worktrees,
-streams their output, and keeps humans as the sign-off gate.
+streams their output, and leaves merge decisions with humans.
 
 ```
 the repo  ──▶  source of truth (markdown + git)
@@ -33,8 +33,8 @@ RepoOS doesn't just host tasks that agents read — it spawns and manages the
 agents themselves. You configure a coding agent on the Agents page, click Start
 on a task, and RepoOS launches the agent in a dedicated git worktree, streams
 its output live, and lets you resume the conversation at any point. When the
-agent finishes, the task moves to review for human sign-off. Agents are
-first-class participants, but humans always hold the gate.
+agent finishes, the task moves to review for human approval. Agents are
+first-class participants, but people decide what merges.
 
 ## Install
 
@@ -46,12 +46,18 @@ Install the standalone `repoos` command. This is the quickest option when you
 want a self-contained release build:
 
 ```bash
-curl -fsSL https://repoos.org/install.sh | bash
+curl -fsSL https://repoos.org/install | bash
 ```
 
 It runs on Bun when available (recommended), otherwise requires Node.js >=
 20.6.0. It installs to `~/.repoos` and links `repoos` into `~/.local/bin`.
 
+### Homebrew
+
+```bash
+brew install repo-os/tap/repoos
+```
+
 ### npm
 
 ```bash
@@ -82,8 +88,10 @@ is enabled so its `repoos` shim is on your PATH.
 
 Use the same tool to update a package-manager install: `npm update -g
 @repo-os/repoos`, `bun update -g @repo-os/repoos`, `pnpm update -g
-@repo-os/repoos`, or `mise upgrade npm:@repo-os/repoos`. A standalone install
-updates with `repoos upgrade` and removes with `repoos uninstall`.
+@repo-os/repoos`, `mise upgrade npm:@repo-os/repoos`, or `brew update && brew
+upgrade repo-os/tap/repoos`. A standalone install updates with `repoos upgrade`
+and removes with `repoos uninstall`. When run from a recognised package-manager
+install, `repoos upgrade` prints the matching package-manager command instead.
 
 Then in any repo:
 
@@ -117,7 +125,7 @@ repoos mv <id> <status>        Move a task (inbox|ready|active|review|done)
 repoos new "<title>" [flags]   Create a task
 repoos index [--json]          Rebuild the derived index (--json for agents/tools)
 repoos serve [--port N]        Start the local server: live API + SSE event stream
-repoos check                   Definition-of-done gate (build, typecheck, tests, UI smoke)
+repoos check                   Pre-merge checks (build, typecheck, tests, UI smoke)
 repoos tunnel [subcommand]     Cloudflare Tunnel + Zero Trust publishing
 ```
 
@@ -280,7 +288,7 @@ RepoOS can spawn and manage coding agents (opencode, Claude Code, Qwen, Codex)
 to execute tasks. Agents run in isolated git worktrees per task so parallel work
 never collides. Output streams over SSE in real time, and the per-task chat tab
 lets you resume a session mid-flight. When the agent finishes, the task moves to
-review — human sign-off is always the gate.
+review — a human decides whether it is ready to merge.
 
 Configure agents on the Agents page: choose the CLI, pick a model (sourced live
 from `opencode models`), add custom instructions, and set up PM and reviewer

package/dist/.build-info.json

@@ -1,4 +1,4 @@
 {
-  "hash": "40cbf1a936a6c7d01b3c026edb4c1f0e467ccde03cf750787fb59239f65ad2e2",
-  "version": "0.5.46"
+  "hash": "f5bc7080896e6462e45fb88aeecb10c9c2f675395207b58c11bc29b2b5524aa7",
+  "version": "0.5.48"
 }

package/dist/.build-stamp.json

@@ -1,3 +1,3 @@
 {
-  "generatedAt": "2026-09-17T10:50:35.067Z"
+  "generatedAt": "2026-09-20T04:04:09.017Z"
 }

package/dist/cli/index.js

@@ -14,6 +14,9 @@ import { cmdTunnel } from "../commands/tunnel.js";
 import { cmdUpgrade } from "../commands/upgrade.js";
 import { cmdUninstall } from "../commands/uninstall.js";
 import { cmdStatus } from "../commands/status.js";
+import { cmdDoctor } from "../commands/doctor.js";
+import { cmdSupport } from "../commands/support.js";
+import { cmdService } from "../commands/service.js";
 import { checkBuild } from "../core/build.js";
 import { loadConfig } from "../core/config.js";
 import { reexecUnderBunIfRequested } from "../core/runtime.js";
@@ -49,7 +52,77 @@ function readVersion() {
     return "0.0.0-dev";
 }
 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("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]", "Read-only readiness preflight: identity, config, layout, tools, check plan, server, secrets"),
+        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)"),
+        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 --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'),
+        exRow("repoos list ready"),
+        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
 
@@ -57,40 +130,10 @@ function help() {
     repoos <command> [args]
 
   ${c.bold("COMMANDS")}
-    ${c.cyan("check")}               Full definition-of-done: build, typecheck, tests, UI smoke check
-    ${c.cyan("init")} [name]           Scaffold work/, repoos.toml, AGENTS.md; outside a git repo runs a guided flow that can launch the web console
-    ${c.cyan("list")} [status]        Show the board (or one column: ${c.dim("inbox|ready|active|review|done")})
-    ${c.cyan("status")} [--json]      One-screen health snapshot: server, build freshness, board, worktrees, tunnel, git
-    ${c.cyan("show")} <id>            Show a task's full spec
-    ${c.cyan("mv")} <id> <status>     Move a task to a new status   ${c.dim('flags: --note "..."')}
-    ${c.cyan("note")} <id> "<text>"   Append a free-form note to a task's activity log
-    ${c.cyan("update")} <id>           Edit a task's metadata/body   ${c.dim("flags: --title --area --priority --type --body --branch --assigned-to")}
-    ${c.cyan("new")} "<title>"        Create a task   ${c.dim("flags: --ai --type --area --priority --body")}
-    ${c.cyan("new-doc")} "<desc>"     Create a document from a description via PM agent
-    ${c.cyan("index")} [--json]       Rebuild the derived index cache
-    ${c.cyan("gc")} [--yes|--dry-run] Collect leaked task worktrees/branches (done/absent tasks, integrate candidates)
-    ${c.cyan("serve")} [--port N]     Start the local server (live API + SSE stream)
-    ${c.cyan("stop")} [--port N]      Stop this repo's serve process (by its own lockfile)
-    ${c.cyan("tunnel")} <sub>         Publish local apps via Cloudflare Tunnel + Zero Trust ${c.dim("(setup|create|allow|deny|rename|destroy|start|install|stop|list|status)")}
-    ${c.cyan("upgrade")} [--channel beta|canary|rc]
-                          Self-update a standalone (curl-installed) repoos to the latest release
-                          (stable by default; --channel tracks a prerelease line instead)
-    ${c.cyan("uninstall")} [--yes]     Remove the standalone (curl-installed) repoos from this machine
+    ${commandLines}
 
   ${c.bold("EXAMPLES")}
-    ${c.dim("$")} repoos init
-    ${c.dim("$")} repoos init myproject   # guided new-project flow outside a git repo
-    ${c.dim("$")} repoos new "Add company dashboard" --ai --type feature --area web --priority p1
-    ${c.dim("$")} repoos new-doc "API design doc for the payment system"
-    ${c.dim("$")} repoos mv 0012 active
-    ${c.dim("$")} repoos mv 0012 active --note "Fix the regression in checkout; see review"
-    ${c.dim("$")} repoos note 0012 "Handle the reviewer's suggestions before the next review"
-    ${c.dim("$")} repoos update 0012 --title "New title" --area web
-    ${c.dim("$")} repoos list ready
-    ${c.dim("$")} repoos status             ${c.dim("# one-screen health snapshot")}
-    ${c.dim("$")} repoos status --json      ${c.dim("# machine-readable, for agents/tools")}
-    ${c.dim("$")} repoos index --json   ${c.dim("# machine-readable, for agents/tools")}
-    ${c.dim("$")} repoos serve          ${c.dim("# live API + SSE at http://127.0.0.1:7171")}
+    ${exampleLines}
 `);
 }
 function main() {
@@ -119,6 +162,8 @@ function main() {
         undefined,
         "check",
         "status",
+        "doctor",
+        "support",
         "help",
         "--help",
         "-h",
@@ -153,6 +198,12 @@ function main() {
         case "status":
             void cmdStatus(rest);
             break;
+        case "doctor":
+            void cmdDoctor(rest);
+            break;
+        case "support":
+            void cmdSupport(rest);
+            break;
         case "show":
         case "cat":
             cmdShow(rest[0]);
@@ -160,12 +211,15 @@ function main() {
         case "mv":
         case "move": {
             let note;
+            let force = false;
             const args = rest.slice();
             for (let i = 0; i < args.length; i++) {
                 if (args[i] === "--note")
                     note = args[++i];
+                else if (args[i] === "--force-not-merged")
+                    force = true;
             }
-            cmdMv(args[0], args[1], note);
+            cmdMv(args[0], args[1], note, { force });
             break;
         }
         case "note":
@@ -195,8 +249,11 @@ function main() {
         case "stop":
             cmdStop(rest);
             break;
+        case "service":
+            void cmdService(rest);
+            break;
         case "check":
-            void cmdCheck();
+            void cmdCheck(rest);
             break;
         case "tunnel":
             void cmdTunnel(rest);

package/dist/commands/check.d.ts

@@ -1,4 +1,6 @@
-import type { CheckContrastPair, CheckThemeScope } from "../core/types.js";
+import type { CheckContrastPair, CheckThemeScope, RepoOSConfig } from "../core/types.js";
+import { type CheckPlan, type CheckStep } from "../core/check-plan.js";
+import { type StepRunResult } from "../core/check-runner.js";
 /**
  * Bare `require(...)` calls guard (#0271 follow-up): this package is
  * `"type": "module"` (ESM) — a bare, un-shadowed `require` is undefined at
@@ -167,4 +169,49 @@ export declare function resolveSmokeCommand(configured: string | undefined, pkgS
  * floor via `undefined`.
  */
 export declare function testPoolSize(env: NodeJS.ProcessEnv): number | undefined;
-export declare function cmdCheck(): Promise<void>;
+/** `repoos check` CLI flags (#0446). */
+export interface CheckOptions {
+    /** Profile to select. Defaults to `[check] defaultProfile`, else `default`. */
+    profile?: string;
+    /** Git ref for changed-path mode. Also read from `REPOOS_CHECK_CHANGED`. */
+    changed?: string;
+    /** Print the resolved plan as `[[check.steps]]` TOML and exit 0. */
+    printPlan?: boolean;
+}
+/** Parse `repoos check` flags. Unknown flags are ignored, never fatal. */
+export declare function parseCheckArgs(argv?: string[]): CheckOptions;
+/**
+ * Repo-relative paths that differ from `ref`, plus anything uncommitted or
+ * untracked — the working tree an agent actually hands over, not just what is
+ * committed on the branch.
+ *
+ * Returns `null` when `ref` itself can't be resolved. That has to be
+ * distinguishable from "nothing changed": a typo'd ref with an empty result
+ * would silently scope every `whenChanged` step away and let the gate go green
+ * having verified nothing at all.
+ */
+export declare function changedPathsSince(repoRoot: string, ref: string): string[] | null;
+export interface RunPlanOptions {
+    repoRoot: string;
+    /** Config for the repo; loaded here when not supplied. */
+    cfg?: RepoOSConfig;
+    profile?: string;
+    /** Changed paths for changed-path mode; absent means a full run. */
+    changedPaths?: string[];
+    /** Git ref the changed paths came from — the Tests step scopes itself to it. */
+    changedRef?: string;
+    onStart?: (step: CheckStep) => void;
+    onResult?: (result: StepRunResult) => void;
+}
+/**
+ * Run a resolved plan, in declaration order, and return one structured result
+ * per step. Pure with respect to the caller's output: printing happens through
+ * the callbacks, so this is unit-testable end to end (see
+ * ui-app/tests/check-plan.test.ts).
+ *
+ * Every step ends in exactly one of: passed, failed, timeout, missing
+ * prerequisite, or an explicit skip that says why. Nothing here can "pass" by
+ * not running.
+ */
+export declare function runCheckPlan(plan: CheckPlan, opts: RunPlanOptions): Promise<StepRunResult[]>;
+export declare function cmdCheck(argv?: string[]): Promise<void>;