@repo-os/repoos 0.5.45

package/dist/core/build.js

@@ -0,0 +1,249 @@
+/**
+ * Build-staleness detection for linked dev builds.
+ *
+ * When `repoos` is run from a linked dev install (both `src/` and `dist/`
+ * exist beside the running binary), compares a hash of `src/` against the
+ * marker written by the build pipeline. Stale builds produce a warning or
+ * error; published installs (no `src/`) are a silent no-op.
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
+/**
+ * Resolve the package root relative to the running binary.
+ * Same resolution pattern as findUiHtml in server.ts.
+ */
+export function findPackageRoot() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // compiled: dist/core/build.js -> repo root is ../..
+    // dev:      src/core/build.ts   -> repo root is ../..
+    const parent = dirname(here);
+    const grandparent = dirname(parent);
+    if (existsSync(join(grandparent, "package.json")))
+        return grandparent;
+    // fallback: try one more level up
+    const great = dirname(grandparent);
+    if (existsSync(join(great, "package.json")))
+        return great;
+    return null;
+}
+/** Compute a sha256 hash of every file under src/. Returns null if src/ absent. */
+function hashSrcDir(root) {
+    const srcDir = join(root, "src");
+    if (!existsSync(srcDir))
+        return null;
+    const hash = createHash("sha256");
+    const files = [];
+    function walk(dir) {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const full = join(dir, e.name);
+            if (e.isDirectory()) {
+                if (e.name === "node_modules")
+                    continue;
+                walk(full);
+            }
+            else if (e.isFile()) {
+                files.push(full);
+            }
+        }
+    }
+    walk(srcDir);
+    files.sort();
+    for (const f of files) {
+        hash.update(f.slice(root.length + 1));
+        hash.update(readFileSync(f));
+    }
+    return hash.digest("hex");
+}
+/**
+ * Staleness check against an explicit repo root — used for a task's worktree
+ * before previewing it. A worktree is stale when its `src/` hash no longer
+ * matches its own `dist/.build-info.json` (or the marker is missing). A
+ * checkout with no `src/` is treated as published (nothing to check).
+ */
+export function checkBuildForRoot(root) {
+    if (!root) {
+        return { stale: false, message: null, code: "published", applicable: false };
+    }
+    const distDir = join(root, "dist");
+    const srcDir = join(root, "src");
+    if (!existsSync(srcDir)) {
+        return { stale: false, message: null, code: "published", applicable: false };
+    }
+    if (!existsSync(distDir)) {
+        return {
+            stale: true,
+            message: "No dist/ build — this checkout isn't using RepoOS's build pipeline; skipping staleness check.",
+            code: "no-build",
+            applicable: false,
+        };
+    }
+    const marker = join(distDir, ".build-info.json");
+    if (!existsSync(marker)) {
+        return {
+            stale: true,
+            message: "No .build-info.json marker — this checkout isn't using RepoOS's build pipeline; skipping staleness check.",
+            code: "no-marker",
+            applicable: false,
+        };
+    }
+    let recorded;
+    try {
+        recorded = JSON.parse(readFileSync(marker, "utf8"));
+    }
+    catch {
+        return {
+            stale: true,
+            message: "Build marker is corrupt. Run `bun run build` to regenerate.",
+            code: "corrupt",
+            applicable: true,
+        };
+    }
+    const currentHash = hashSrcDir(root);
+    if (!currentHash) {
+        return { stale: false, message: null, code: "published", applicable: false };
+    }
+    if (recorded.hash !== currentHash) {
+        return {
+            stale: true,
+            message: "Stale build: src/ has changed since the last `bun run build`.\n" +
+                "  You are running OLD compiled code, and `repoos serve` serves the OLD UI.\n" +
+                "  Run `bun run build` to update.",
+            code: "stale",
+            applicable: true,
+        };
+    }
+    return { stale: false, message: null, code: "fresh", applicable: true };
+}
+/**
+ * Whether a build invocation may skip its work entirely. Only a checkout whose
+ * marker proves `src/` is unchanged (`code: "fresh"`) may skip; every other
+ * outcome — a missing or mismatched marker, a missing `dist/`, a published
+ * install — must build. `force` (the `--force` flag / `REPOOS_FORCE_BUILD=1`)
+ * always builds, even when the marker says fresh.
+ *
+ * This is the single decision every build caller shares. `scripts/build.mjs`
+ * turns it into the skip; `repoos check` calls `bun run build` and inherits it,
+ * so staleness is never silently absorbed (check reports staleness first in its
+ * own step, then the build step repairs).
+ */
+export function shouldSkipBuild(result, force = false) {
+    return !force && result.code === "fresh";
+}
+export function checkBuild() {
+    const root = findPackageRoot();
+    if (!root) {
+        return { stale: false, message: null, code: "published", applicable: false };
+    }
+    const distDir = join(root, "dist");
+    const srcDir = join(root, "src");
+    const marker = join(distDir, ".build-info.json");
+    // Detect dev mode: running from src/, not from compiled dist/
+    const binPath = fileURLToPath(import.meta.url);
+    if (binPath.includes(`${pathSep}src${pathSep}`)) {
+        return { stale: false, message: null, code: "dev-mode", applicable: false };
+    }
+    return checkBuildForRoot(root);
+}
+/**
+ * Read the build timestamp for a checkout. The timestamp lives in
+ * `dist/.build-stamp.json` (gitignored) rather than `dist/.build-info.json`,
+ * so the marker that staleness and reload compare stays byte-identical across
+ * rebuilds of identical source. Falls back to a legacy inline `generatedAt` in
+ * the marker so installs built before the split still report a build age.
+ * Best-effort: null when neither file is readable.
+ */
+export function readBuildStamp(root) {
+    const read = (file) => {
+        try {
+            const info = JSON.parse(readFileSync(file, "utf8"));
+            return typeof info.generatedAt === "string" && info.generatedAt ? info.generatedAt : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    return (read(join(root, "dist", ".build-stamp.json")) ?? read(join(root, "dist", ".build-info.json")));
+}
+function readGeneratedAt(file) {
+    try {
+        const info = JSON.parse(readFileSync(file, "utf8"));
+        return typeof info.generatedAt === "string" && info.generatedAt ? info.generatedAt : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build version + timestamp for the running install, resolved relative to THIS
+ * module so it works for every layout:
+ *
+ *   - standalone (curl / `repoos upgrade`):  <installRoot>/core/build.js
+ *       → `.build-info.json` + `.build-stamp.json` sit at <installRoot>
+ *   - linked dev build (compiled):           <repo>/dist/core/build.js
+ *       → both files sit at <repo>/dist
+ *   - source run (`bun src/cli/index.ts`):   <repo>/src/core/build.ts
+ *       → no marker beside it; fall back to <repo>/dist, then package.json
+ *
+ * The old path read `package.json` only — but the release tarball
+ * (`tar -C dist .`) ships `.build-info.json` (`{ hash, version }`) and
+ * `.build-stamp.json`, NOT `package.json`, so every standalone install
+ * reported its version as "unknown". `.build-info.json` is the source of truth
+ * here; `package.json` is just the last-resort fallback for a source checkout.
+ */
+export function readBuildMeta() {
+    const here = dirname(fileURLToPath(import.meta.url)); // <x>/core
+    return readBuildMetaFrom(dirname(here)); // <x>: installRoot | repo/dist | repo/src
+}
+/**
+ * The dir-relative core of {@link readBuildMeta}, split out so it can be tested
+ * against synthetic layouts. `markerDir` is where `.build-info.json` /
+ * `.build-stamp.json` are expected to sit (with `<markerDir>/../dist` tried as
+ * the source-checkout fallback).
+ */
+export function readBuildMetaFrom(markerDir) {
+    const dirs = [markerDir, join(markerDir, "..", "dist")];
+    let version = null;
+    let buildAt = null;
+    for (const dir of dirs) {
+        if (version === null) {
+            try {
+                const info = JSON.parse(readFileSync(join(dir, ".build-info.json"), "utf8"));
+                if (typeof info.version === "string" && info.version)
+                    version = info.version;
+            }
+            catch {
+                /* no marker in this dir */
+            }
+        }
+        if (buildAt === null) {
+            buildAt =
+                readGeneratedAt(join(dir, ".build-stamp.json")) ??
+                    readGeneratedAt(join(dir, ".build-info.json"));
+        }
+    }
+    if (version === null) {
+        const root = findPackageRoot();
+        if (root) {
+            try {
+                const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+                if (typeof pkg.version === "string" && pkg.version)
+                    version = pkg.version;
+            }
+            catch {
+                /* package.json unreadable */
+            }
+        }
+    }
+    return { version, buildAt };
+}
+/** Platform path separator pattern for import.meta.url detection. */
+const pathSep = process.platform === "win32" ? "\\\\" : "/";

package/dist/core/canary.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Canary counter for the end-to-end flow smoke test (draft → inbox → ready →
+ * active → review → merge → done). The only thing a canary task does is bump
+ * this number, wrapping 9 back to 0 — see CANARY_PROMPT below, which is the
+ * exact, unchanging freeform explanation used to create that task every time.
+ * A trivial, single-line diff means any failure surfaced by the run is the
+ * pipeline's fault, not the change's.
+ */
+export declare const CANARY_COUNTER = 2;
+export declare const CANARY_PROMPT: string;

package/dist/core/canary.js

@@ -0,0 +1,14 @@
+/**
+ * Canary counter for the end-to-end flow smoke test (draft → inbox → ready →
+ * active → review → merge → done). The only thing a canary task does is bump
+ * this number, wrapping 9 back to 0 — see CANARY_PROMPT below, which is the
+ * exact, unchanging freeform explanation used to create that task every time.
+ * A trivial, single-line diff means any failure surfaced by the run is the
+ * pipeline's fault, not the change's.
+ */
+export const CANARY_COUNTER = 2;
+export const CANARY_PROMPT = "This is the repoos canary task: a deliberately trivial change used to smoke-test the full flow " +
+    "(draft, inbox, ready, active, review, merge, done) end to end. The only change to make is in " +
+    "src/core/canary.ts: increment the exported CANARY_COUNTER constant by 1, wrapping from 9 back to 0. " +
+    "Do not touch anything else, do not add tests or comments beyond what's already there, and do not " +
+    "change CANARY_PROMPT itself.";

package/dist/core/check-failure-summary.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Pull the useful, human-readable diagnosis out of a Vitest failure block.
+ *
+ * Full check output can be large and often ends with a coloured received-vs-
+ * expected diff. That diff is valuable in the expandable log, but it makes a
+ * poor headline: it can begin halfway through a JSON object and hide the test
+ * that actually failed. Keep the test name, source location, and error kind
+ * together for compact status surfaces.
+ */
+export declare function summarizeCheckFailure(output: string): string | null;

package/dist/core/check-failure-summary.js

@@ -0,0 +1,34 @@
+/**
+ * Pull the useful, human-readable diagnosis out of a Vitest failure block.
+ *
+ * Full check output can be large and often ends with a coloured received-vs-
+ * expected diff. That diff is valuable in the expandable log, but it makes a
+ * poor headline: it can begin halfway through a JSON object and hide the test
+ * that actually failed. Keep the test name, source location, and error kind
+ * together for compact status surfaces.
+ */
+export function summarizeCheckFailure(output) {
+    const lines = output
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+    let failureIndex = -1;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        if (/^(?:[❯×]\s*)?FAIL\s+/.test(lines[i])) {
+            failureIndex = i;
+            break;
+        }
+    }
+    if (failureIndex === -1)
+        return null;
+    const heading = lines[failureIndex].replace(/^(?:[❯×]\s*)?FAIL\s+/, "");
+    const block = lines.slice(failureIndex + 1);
+    const location = block.find((line) => /(?:^|\s)(?:[^\s:]+\/)?[^\s:]+\.(?:test|spec)\.[cm]?[jt]sx?:\d+:\d+/.test(line));
+    const error = block.find((line) => /^(?:[A-Za-z]*Error|Error):/.test(line));
+    const parts = [heading];
+    if (location)
+        parts.push(`at ${location.replace(/^[❯×]\s*/, "")}`);
+    if (error)
+        parts.push(error);
+    return parts.join(" — ");
+}

package/dist/core/config.d.ts

@@ -0,0 +1,160 @@
+import type { Agent, BuiltInAgentConfig, PreviewConfig, RepoOSConfig } from "./types.js";
+/** Coding agents an Agent can run under. */
+export declare const AGENT_CLIS: readonly ["opencode", "claude code", "qwen code", "kiro", "codex", "github copilot"];
+/** Models an Agent can pin (or "default" for the coding agent's default). */
+export declare const AGENT_MODELS: readonly ["default", "big pickle", "deepseek v4"];
+/** Built-in agents, seeded at runtime when the config has none. */
+export declare const DEFAULT_AGENTS: Agent[];
+/** Default agent names — these are seeded and cannot be removed. */
+export declare const DEFAULT_AGENT_NAMES: string[];
+/**
+ * Add Ross to an existing stored agent list without replacing user edits.
+ * When the stored config has the legacy "RepoOS Guide" name, rename it to "Ross"
+ * so the chat continues working. The other defaults deliberately are not
+ * re-seeded: a user may have removed one of those roles from an older configuration.
+ */
+export declare function agentsForConfig(config: Pick<RepoOSConfig, "agents">): Agent[];
+/**
+ * "Auto" default for `maxConcurrentAgents`. An agent's own test pool
+ * is capped separately (vite.config.ts `test.poolOptions.forks.maxForks: 2`),
+ * so one agent's worst-case footprint is bounded rather than "the whole
+ * machine" — this can size off total cores directly instead of dividing them
+ * away defensively. `cores / 2` leaves headroom for that ~2-worker pool plus
+ * the agent process's own overhead per concurrent agent; capped at 8 so a
+ * many-core desktop doesn't queue dozens of agents whose non-test work (tool
+ * calls, I/O) still contends over shared resources like the git index.
+ */
+export declare function defaultMaxConcurrentAgents(): number;
+export declare const DEFAULT_CONFIG: Omit<RepoOSConfig, "root">;
+/**
+ * Sibling directory that holds per-task agent worktrees, e.g.
+ * `/path/to/repoos` -> `/path/to/repoos-worktrees/`. Kept OUTSIDE the repo
+ * root so a linked worktree can never dirty the main checkout or confuse
+ * `repoos check` staleness. `<branch>` path segments are kept so a worktree
+ * for `feat/123-x` lives at `<dir>/feat/123-x`.
+ */
+export declare function worktreesDir(root: string): string;
+/**
+ * A stable default serve port for a repo, derived from its canonical root
+ * path (djb2 hash → `${DERIVED_PORT_BASE}`..`${DERIVED_PORT_BASE + DERIVED_PORT_SPAN - 1}`).
+ * Deterministic per checkout, so two repos on one machine don't both default
+ * to 7171 and reap each other. Exported for tests.
+ */
+export declare function deriveServePort(root: string): number;
+/**
+ * Resolve the port `repoos serve` should bind: an explicit `--port` flag wins,
+ * then `servePort` in repoos.toml, then a stable per-repo derived port.
+ */
+export declare function resolveServePort(root: string, config: {
+    servePort?: number;
+}, portFlag?: number): number;
+/**
+ * Load `.env` from the repo root into `process.env`, if present. Zero
+ * runtime deps (no dotenv package) — a minimal `KEY=value` parser, one line
+ * per variable. Real env vars already set take precedence over the file, so
+ * e.g. a systemd unit's `Environment=` still wins. Safe to call more than
+ * once; safe when `.env` doesn't exist.
+ */
+export declare function loadDotEnv(root?: string): void;
+/**
+ * Persist a local secret to the gitignored `.env` at the repo root, keeping
+ * the same env-var-secret convention `loadDotEnv` reads back (dev backdoor
+ * code, auth provider keys, model-provider API keys). An empty `value`
+ * removes the line entirely so a cleared secret can't linger as `KEY=`.
+ * Also updates `process.env` directly: `loadDotEnv` skips keys already
+ * present in the environment, so a re-`loadConfig` alone would never refresh
+ * a value the booting process had already seen.
+ *
+ * Only ever called with the fixed secret names this codebase owns (the
+ * model-provider keys today) — callers validate that before calling. The
+ * value is written raw, one `KEY=value` line, exactly what `loadDotEnv`
+ * parses back.
+ */
+export declare function setDotEnvSecret(root: string, key: string, value: string): void;
+/** Walk upward from `start` to find the repo root (nearest .git or repoos.toml). */
+export declare function findRepoRoot(start?: string): string;
+/**
+ * True when `dir` is a LINKED WORKTREE root rather than a real repo root: a
+ * worktree's `.git` is a FILE reading `gitdir: …`, while a real root's `.git`
+ * is a directory. Cheap — one stat, no git subprocess.
+ *
+ * `findRepoRoot` does not make this distinction (it matches any `.git`), which
+ * is exactly why board reads run from inside a worktree used to silently
+ * resolve to the worktree's own copy of the task files instead of the live
+ * board's main checkout (the #0068 false-positive).
+ */
+export declare function isLinkedWorktreeRoot(dir: string): boolean;
+/**
+ * The MAIN checkout root for a linked worktree, or null when `dir` is not a
+ * linked worktree root. A worktree's `.git` file points at
+ * `<main>/.git/worktrees/<name>` (absolute, or relative to the worktree); the
+ * main root is the first ancestor of that pointer whose own `.git` is a
+ * directory. Fail-soft: any anomaly yields null and callers fall back to the
+ * resolved root.
+ */
+export declare function mainCheckoutRoot(dir: string): string | null;
+/**
+ * The root LIVE-BOARD reads (`repoos show`/`list`/`index`) should resolve to:
+ * the MAIN checkout even when the CLI runs inside a task worktree, so a
+ * readback can never false-positive on the worktree's own copy. `fromWorktree`
+ * signals that resolution jumped the main checkout — callers surface it so the
+ * behavior is never silent. Mutating commands keep `findRepoRoot` semantics
+ * (they must act on the directory they run in).
+ */
+export declare function boardRoot(start?: string): {
+    root: string;
+    fromWorktree: boolean;
+};
+/**
+ * Parse the `[preview]` section (plus `[[preview.targets]]` tables) from flat
+ * TOML. Exported for tests; `loadConfig` merges the result into the config.
+ * Rows without a usable `command` are dropped rather than poisoning resolution.
+ */
+export declare function parsePreviewConfig(parsed: Record<string, unknown>): PreviewConfig | undefined;
+export declare function loadConfig(rootArg?: string): RepoOSConfig;
+/** Metadata describing a single config field for the Settings UI. */
+export interface ConfigFieldMeta {
+    key: string;
+    label: string;
+    type: "string" | "boolean" | "select" | "array";
+    tier: "live" | "restart" | "guarded";
+    /**
+     * Which primary Settings section a field belongs to. Defaults to "general"
+     * for non-guarded fields and "advanced" for guarded ones. "voice" carves out
+     * a dedicated, always-visible "Voice transcription" section so the feature
+     * is discoverable without opening Advanced.
+     */
+    group?: "general" | "voice";
+    restartRequired: boolean;
+    default: unknown;
+    options?: {
+        value: string;
+        label: string;
+    }[];
+    description: string;
+}
+export declare function getConfigSchema(): ConfigFieldMeta[];
+/**
+ * Patch a repoos.toml file with the given key-value pairs, preserving all
+ * other lines (comments, formatting, unknown keys).
+ */
+export declare function patchTomlConfig(tomlPath: string, patch: Record<string, unknown>): void;
+/**
+ * Absolute path of the built-in agent state sidecar (a JSON file living next
+ * to the cache dir). It holds runtime state — enabled/schedule/last run — that
+ * the Tech Debt Agent's server-side scheduler reads and the Agents page
+ * writes; it is deliberately NOT part of repoos.toml.
+ */
+export declare function builtInAgentsPath(root: string, cacheDir?: string): string;
+/** Coerce an unknown PATCH/read value into a sane BuiltInAgentConfig. */
+export declare function sanitizeBuiltInAgent(value: unknown): BuiltInAgentConfig | null;
+/**
+ * Coerce a whole record of built-in agent state (as read from the sidecar or
+ * sent via PATCH) into a safe shape. Invalid entries are dropped; a valid
+ * entry with no recognized fields is dropped too.
+ */
+export declare function sanitizeBuiltInAgents(value: unknown): Record<string, BuiltInAgentConfig>;
+/** Read the built-in agent state sidecar, or undefined when absent/unreadable. */
+export declare function loadBuiltInAgentsConfig(root: string, cacheDir?: string): Record<string, BuiltInAgentConfig> | undefined;
+/** Persist the built-in agent state sidecar, creating the cache dir as needed. */
+export declare function saveBuiltInAgentsConfig(root: string, state: Record<string, BuiltInAgentConfig>, cacheDir?: string): void;