@repo-os/repoos 0.5.45 → 0.5.47

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,18 +33,64 @@ 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
 
-Install a standalone `repoos` command straight from GitHub Releases:
+Choose one installation method:
+
+### curl
+
+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 | 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
+npm install -g @repo-os/repoos
+```
+
+### Bun
+
+```bash
+bun add -g @repo-os/repoos
+```
+
+### pnpm
+
+```bash
+pnpm add -g @repo-os/repoos
+```
+
+### mise
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/repo-os/repoos/main/install.sh | bash
+mise use --global npm:@repo-os/repoos
 ```
 
-Runs on Bun when it's installed (recommended); otherwise requires Node.js >= 20.6.0. Installs to `~/.repoos` and links `repoos` into `~/.local/bin`.
+This uses mise's built-in npm backend and records RepoOS in your global mise
+configuration. Make sure [mise shell activation](https://mise.jdx.dev/getting-started.html)
+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`, `mise upgrade npm:@repo-os/repoos`, or `brew upgrade
+repo-os/tap/repoos`. A standalone install updates with `repoos upgrade` and
+removes with `repoos uninstall`.
 
 Then in any repo:
 
@@ -78,7 +124,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
 ```
 
@@ -241,7 +287,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": "e49c2d85116e21cce445444e46ba4c7961583ce35dcf49707db0d41c623126d2",
-  "version": "0.5.44"
+  "hash": "9b6f7f703e729021650ce8768748ad02cc51078cfee42e1c4cc328f5ea177dad",
+  "version": "0.5.47"
 }

package/dist/.build-stamp.json

@@ -1,3 +1,3 @@
 {
-  "generatedAt": "2026-09-17T08:36:35.890Z"
+  "generatedAt": "2026-09-19T09:11:14.500Z"
 }

package/dist/cli/index.js

@@ -12,7 +12,9 @@ import { cmdServe, serveProcessTitle, setServeProcessTitle } from "../commands/s
 import { cmdStop } from "../commands/stop.js";
 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 { cmdService } from "../commands/service.js";
 import { checkBuild } from "../core/build.js";
 import { loadConfig } from "../core/config.js";
 import { reexecUnderBunIfRequested } from "../core/runtime.js";
@@ -48,7 +50,72 @@ 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", "Full definition-of-done: build, typecheck, tests, UI smoke check"),
+        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("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
 
@@ -56,39 +123,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)
+    ${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() {
@@ -121,6 +159,7 @@ function main() {
         "--help",
         "-h",
         "upgrade",
+        "uninstall",
     ]);
     if (!skipCheck.has(cmd)) {
         const result = checkBuild();
@@ -157,12 +196,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":
@@ -192,6 +234,9 @@ function main() {
         case "stop":
             cmdStop(rest);
             break;
+        case "service":
+            void cmdService(rest);
+            break;
         case "check":
             void cmdCheck();
             break;
@@ -201,6 +246,9 @@ function main() {
         case "upgrade":
             void cmdUpgrade(rest);
             break;
+        case "uninstall":
+            void cmdUninstall(rest);
+            break;
         case "version":
         case "--version":
         case "-v":

package/dist/commands/check.js

@@ -1114,7 +1114,11 @@ export async function cmdCheck() {
     // `bun run test` off this machine — and then invoke the LOCAL `repoos check`
     // with REPOOS_SKIP_TESTS=1 for only the cheap static guards + UI smoke.
     // Standalone `repoos check` never sets it, so the CLI gate is unchanged.
-    if (process.env.REPOOS_SKIP_TESTS === "1") {
+    if (fmtLintFailed) {
+        console.log(c.dim("  · Skipped — formatting/lint failed above, so build was skipped too"));
+        results.push(pass("tests", "skipped — formatting/lint failed, fix and rerun"));
+    }
+    else if (process.env.REPOOS_SKIP_TESTS === "1") {
         console.log(c.dim("  · Skipped — test suite ran on the remote validation runner (REPOOS_SKIP_TESTS=1)"));
         results.push(pass("tests", "skipped — ran on the remote validation runner"));
     }

package/dist/commands/init.d.ts

@@ -1,9 +1,34 @@
-type ScaffoldLayout = "root" | "repoos";
+/** Marker makes the optional existing-repo addition safe to offer repeatedly. */
+export declare const REPOOS_AGENTS_SECTION_MARKER = "<!-- repoos:managed-instructions -->";
+/**
+ * A deliberately small appendix for a repository that already owns its agent
+ * instructions. RepoOS supplies its managed-runner instructions itself; this
+ * only documents the project-level contract that a human or external agent
+ * should see in the repo.
+ */
+export declare const REPOOS_AGENTS_SECTION: (workDir: string) => string;
+/**
+ * Return the exact addition that `repoos init` may offer for an existing
+ * AGENTS.md, or null when this repository already documents RepoOS.
+ */
+export declare function repoOSAgentsSectionAddition(existing: string, workDir?: string): string | null;
+/**
+ * A namespace string: empty string or "/" means repo root; anything else is a
+ * repo-relative subdirectory (e.g. "repoos", ".meta/repoos").
+ */
+type ScaffoldLayout = string;
 /** Which starter task to seed beyond 0001 — a blank project or an existing repo. */
 type ScaffoldKind = "new" | "existing";
 export declare function scaffoldInto(root: string, description: string, layout?: ScaffoldLayout, kind?: ScaffoldKind): {
     created: string[];
     skipped: string[];
 };
+/**
+ * Validate a user-supplied namespace string. Returns null when the input means
+ * "repo root" (the special `/` or empty), a normalized repo-relative path when
+ * valid, or an error message prefixed with `!` when invalid. The caller
+ * distinguishes valid from error by checking `result.startsWith("!")`.
+ */
+export declare function validateNamespace(input: string): string;
 export declare function cmdInit(args: string[]): Promise<void>;
 export {};