@phamvuhoang/otto-core 0.1.0

package/README.md

@@ -0,0 +1,53 @@
+# @phamvuhoang/otto-core
+
+Library half of **[Otto](https://github.com/phamvuhoang/otto)** — a harness that drives the
+[Claude Code](https://docs.anthropic.com/claude/docs/claude-code) CLI against a target
+repository in an iterating implementer → reviewer loop, running directly on the host OS.
+
+This package is the engine: the iteration loop driver, the runner + NDJSON stream
+renderer, the prompt-template renderer, and the stage registry. The user-facing CLI lives in
+**[`@phamvuhoang/otto`](https://www.npmjs.com/package/@phamvuhoang/otto)** (`otto-afk` / `otto-ghafk`).
+
+> **Security:** Otto runs Claude with `--permission-mode bypassPermissions`. Point it
+> only at repositories and prompts you trust. See the repo's
+> [SECURITY.md](https://github.com/phamvuhoang/otto/blob/main/SECURITY.md).
+
+## Install
+
+```bash
+npm i @phamvuhoang/otto-core
+```
+
+## Use
+
+```ts
+import {
+  runAfk,
+  runGhAfk,
+  runLoop,
+  STAGES,
+  renderTemplate,
+} from "@phamvuhoang/otto-core";
+
+// Drive the plan/PRD loop from argv (same entry the otto-afk bin uses):
+await runAfk(["<plan-and-prd>", "5"]);
+```
+
+Public surface: `runAfk`, `runGhAfk`, `runLoop`, `STAGES`, `Stage`, `renderTemplate`,
+`runStage`. Subpath exports: `./loop`, `./runner`, `./stages`.
+
+`runStage` spawns `claude` directly on the host with `cwd` set to the workspace directory.
+By default (`OTTO_RUNNER=sandbox`) it writes a transient `--settings` JSON that enables
+the native OS sandbox, confining writes to the workspace. Set `OTTO_RUNNER=host` to run
+unsandboxed. Credentials (`~/.claude`, `~/.config/gh`) are read natively — no bind-mounts
+required. The `templates/` directory (prompt playbooks) ships in the tarball.
+
+## Docs
+
+Full usage, setup, environment variables, and architecture are in the
+**[main README](https://github.com/phamvuhoang/otto#readme)** and
+**[docs/ARCHITECTURE.md](https://github.com/phamvuhoang/otto/blob/main/docs/ARCHITECTURE.md)**.
+
+## License
+
+[MIT](https://github.com/phamvuhoang/otto/blob/main/LICENSE) © Henry Pham.

package/dist/branch.d.ts

@@ -0,0 +1,61 @@
+export type BranchStrategy = "current" | "branch" | "worktree";
+export type BranchConfig = {
+    branchStrategy?: BranchStrategy;
+    branchPrefix?: string;
+};
+export type ResolvedBranch = {
+    strategy: BranchStrategy;
+    branchName: string | null;
+    effectiveWorkspaceDir: string;
+    worktreePath?: string;
+    summaryLine: string;
+};
+export type BranchPromptResult = {
+    strategy: BranchStrategy;
+    remember: boolean;
+};
+export type ResolveBranchOptions = {
+    workspaceDir: string;
+    inputs: string;
+    isTTY: boolean;
+    flagStrategy?: BranchStrategy;
+    flagPrefix?: string;
+    /** Injectable for tests; defaults to a readline prompt. Only called when isTTY && unresolved. */
+    prompt?: () => Promise<BranchPromptResult>;
+    /** Injectable clock for the timestamp slug (test seam). */
+    now?: () => string;
+};
+/**
+ * Derive a branch slug from an inputs string. Uses the basename (sans extension)
+ * of the first whitespace-separated token, lowercased, with non-alphanumerics
+ * collapsed to single dashes and capped at 40 chars. "" when there is nothing usable.
+ */
+export declare function slugify(inputs: string): string;
+/** Read .otto/config.json. Absent or malformed → {} (never throws). */
+export declare function readBranchConfig(workspaceDir: string): BranchConfig;
+/** Merge `patch` into .otto/config.json, preserving unknown keys. Creates .otto/ if needed. */
+export declare function writeBranchConfig(workspaceDir: string, patch: BranchConfig): void;
+/**
+ * Resolve the branch strategy once at startup and perform its one-time git side
+ * effect. Precedence: flagStrategy → .otto/config.json → TTY prompt → "current".
+ * Returns the effective workspace dir the loop should run in (the worktree path
+ * in worktree mode, else the original workspaceDir).
+ */
+export declare function resolveBranch(opts: ResolveBranchOptions): Promise<ResolvedBranch>;
+/**
+ * Ensure `.otto-tmp/` is gitignored in the workspace. No-op outside a git repo
+ * or when a `.otto-tmp` entry already exists. Creates .gitignore if absent.
+ * Never ignores `.otto/` (LEARNINGS.md + config.json are durable, git-tracked
+ * memory).
+ *
+ * Idempotency is checked by scanning .gitignore text — NOT `git check-ignore`,
+ * which only matches a trailing-slash dir pattern once the dir exists on disk.
+ */
+export declare function ensureTmpIgnored(workspaceDir: string): void;
+/**
+ * Returns a warning string if `strategy` keeps work in the current checkout AND
+ * the tree has uncommitted tracked changes (which disables the review panel's
+ * read-only reset enforcement). null when there is nothing to warn about.
+ */
+export declare function dirtyTreeWarning(workspaceDir: string, strategy: BranchStrategy): string | null;
+//# sourceMappingURL=branch.d.ts.map

package/dist/branch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch.d.ts","sourceRoot":"","sources":["../src/branch.ts"],"names":[],"mappings":"AAgBA,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE/D,MAAM,MAAM,YAAY,GAAG;IACzB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,EAAE,cAAc,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,cAAc,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,YAAY,CAAC,EAAE,cAAc,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iGAAiG;IACjG,MAAM,CAAC,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC3C,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB,CAAC;AAKF;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAU9C;AAED,uEAAuE;AACvE,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,YAAY,CAmBnE;AAED,+FAA+F;AAC/F,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,YAAY,GAClB,IAAI,CAgBN;AA0CD;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,cAAc,CAAC,CAmFzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAgB3D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,cAAc,GACvB,MAAM,GAAG,IAAI,CAKf"}

package/dist/branch.js

@@ -0,0 +1,215 @@
+import { execFileSync } from "node:child_process";
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { basename, join } from "node:path";
+import { git, hasUncommittedTrackedChanges, isGitRepo, refExists, } from "./git.js";
+const DEFAULT_PREFIX = "otto/";
+const CONFIG_REL = join(".otto", "config.json");
+/**
+ * Derive a branch slug from an inputs string. Uses the basename (sans extension)
+ * of the first whitespace-separated token, lowercased, with non-alphanumerics
+ * collapsed to single dashes and capped at 40 chars. "" when there is nothing usable.
+ */
+export function slugify(inputs) {
+    const first = inputs.trim().split(/\s+/)[0] ?? "";
+    if (!first)
+        return "";
+    const baseName = basename(first).replace(/\.[^.]+$/, "");
+    return baseName
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40)
+        .replace(/-+$/g, "");
+}
+/** Read .otto/config.json. Absent or malformed → {} (never throws). */
+export function readBranchConfig(workspaceDir) {
+    try {
+        const raw = JSON.parse(readFileSync(join(workspaceDir, CONFIG_REL), "utf8"));
+        const out = {};
+        if (raw.branchStrategy === "current" ||
+            raw.branchStrategy === "branch" ||
+            raw.branchStrategy === "worktree") {
+            out.branchStrategy = raw.branchStrategy;
+        }
+        if (typeof raw.branchPrefix === "string")
+            out.branchPrefix = raw.branchPrefix;
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+/** Merge `patch` into .otto/config.json, preserving unknown keys. Creates .otto/ if needed. */
+export function writeBranchConfig(workspaceDir, patch) {
+    const path = join(workspaceDir, CONFIG_REL);
+    let existing = {};
+    try {
+        existing = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        existing = {};
+    }
+    mkdirSync(join(workspaceDir, ".otto"), { recursive: true });
+    writeFileSync(path, JSON.stringify({ ...existing, ...patch }, null, 2) + "\n");
+}
+/** Default readline prompt (only used in a TTY). */
+async function defaultPrompt() {
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const ans = (await rl.question("Branch strategy [current/branch/worktree] (current): "))
+            .trim()
+            .toLowerCase();
+        const strategy = ans === "branch" || ans === "worktree" ? ans : "current";
+        let remember = false;
+        if (strategy !== "current") {
+            const r = (await rl.question("Remember for this repo? [y/N]: "))
+                .trim()
+                .toLowerCase();
+            remember = r === "y" || r === "yes";
+        }
+        return { strategy, remember };
+    }
+    finally {
+        rl.close();
+    }
+}
+function defaultNow() {
+    const d = new Date();
+    const p = (x) => String(x).padStart(2, "0");
+    return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}`;
+}
+/** Append -2, -3, … until the branch name is free. */
+function uniqueBranchName(workspaceDir, name) {
+    if (!refExists(workspaceDir, name))
+        return name;
+    for (let n = 2;; n++) {
+        const candidate = `${name}-${n}`;
+        if (!refExists(workspaceDir, candidate))
+            return candidate;
+    }
+}
+/**
+ * Resolve the branch strategy once at startup and perform its one-time git side
+ * effect. Precedence: flagStrategy → .otto/config.json → TTY prompt → "current".
+ * Returns the effective workspace dir the loop should run in (the worktree path
+ * in worktree mode, else the original workspaceDir).
+ */
+export async function resolveBranch(opts) {
+    const { workspaceDir, inputs, isTTY } = opts;
+    const now = opts.now ?? defaultNow;
+    const config = readBranchConfig(workspaceDir);
+    const prefix = opts.flagPrefix ?? config.branchPrefix ?? DEFAULT_PREFIX;
+    let strategy;
+    if (opts.flagStrategy) {
+        strategy = opts.flagStrategy;
+    }
+    else if (config.branchStrategy) {
+        strategy = config.branchStrategy;
+    }
+    else if (isTTY) {
+        const res = await (opts.prompt ?? defaultPrompt)();
+        strategy = res.strategy;
+        if (res.remember && strategy !== "current") {
+            writeBranchConfig(workspaceDir, {
+                branchStrategy: strategy,
+                branchPrefix: prefix,
+            });
+        }
+    }
+    else {
+        strategy = "current";
+    }
+    if (strategy === "current") {
+        return {
+            strategy,
+            branchName: null,
+            effectiveWorkspaceDir: workspaceDir,
+            summaryLine: "branch strategy: current (committing on the current branch)",
+        };
+    }
+    if (!isGitRepo(workspaceDir)) {
+        throw new Error(`branch strategy "${strategy}" requires a git repo, but ${workspaceDir} is not a git work tree`);
+    }
+    const slug = slugify(inputs) || now();
+    const branchName = uniqueBranchName(workspaceDir, prefix + slug);
+    if (strategy === "branch") {
+        const current = git(["branch", "--show-current"], workspaceDir);
+        if (current === branchName) {
+            return {
+                strategy,
+                branchName,
+                effectiveWorkspaceDir: workspaceDir,
+                summaryLine: `branch strategy: branch (already on ${branchName})`,
+            };
+        }
+        execFileSync("git", ["switch", "-c", branchName], {
+            cwd: workspaceDir,
+            stdio: "ignore",
+        });
+        return {
+            strategy,
+            branchName,
+            effectiveWorkspaceDir: workspaceDir,
+            summaryLine: `branch strategy: branch (created + switched to ${branchName})`,
+        };
+    }
+    // worktree
+    const worktreePath = join(workspaceDir, ".otto-tmp", "worktrees", slug);
+    mkdirSync(join(workspaceDir, ".otto-tmp", "worktrees"), { recursive: true });
+    execFileSync("git", ["worktree", "add", "-b", branchName, worktreePath, "HEAD"], { cwd: workspaceDir, stdio: "ignore" });
+    const dirtyNote = hasUncommittedTrackedChanges(workspaceDir)
+        ? " (uncommitted changes left in the main checkout)"
+        : "";
+    return {
+        strategy,
+        branchName,
+        effectiveWorkspaceDir: worktreePath,
+        worktreePath,
+        summaryLine: `branch strategy: worktree (${branchName} at ${worktreePath})${dirtyNote}`,
+    };
+}
+/**
+ * Ensure `.otto-tmp/` is gitignored in the workspace. No-op outside a git repo
+ * or when a `.otto-tmp` entry already exists. Creates .gitignore if absent.
+ * Never ignores `.otto/` (LEARNINGS.md + config.json are durable, git-tracked
+ * memory).
+ *
+ * Idempotency is checked by scanning .gitignore text — NOT `git check-ignore`,
+ * which only matches a trailing-slash dir pattern once the dir exists on disk.
+ */
+export function ensureTmpIgnored(workspaceDir) {
+    if (!isGitRepo(workspaceDir))
+        return;
+    const path = join(workspaceDir, ".gitignore");
+    let text = "";
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch {
+        text = "";
+    }
+    const already = text
+        .split("\n")
+        .map((l) => l.trim())
+        .some((l) => l === ".otto-tmp" || l === ".otto-tmp/");
+    if (already)
+        return;
+    const needsNl = text.length > 0 && !text.endsWith("\n");
+    appendFileSync(path, `${needsNl ? "\n" : ""}.otto-tmp/\n`);
+}
+/**
+ * Returns a warning string if `strategy` keeps work in the current checkout AND
+ * the tree has uncommitted tracked changes (which disables the review panel's
+ * read-only reset enforcement). null when there is nothing to warn about.
+ */
+export function dirtyTreeWarning(workspaceDir, strategy) {
+    if (strategy === "worktree")
+        return null; // worktree starts clean by construction
+    if (!isGitRepo(workspaceDir))
+        return null;
+    if (!hasUncommittedTrackedChanges(workspaceDir))
+        return null;
+    return "working tree has uncommitted changes — review-panel read-only enforcement will be disabled; consider committing/stashing or using --branch worktree";
+}
+//# sourceMappingURL=branch.js.map

package/dist/branch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch.js","sourceRoot":"","sources":["../src/branch.ts"],"names":[],"mappings":"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"}

package/dist/cli-help.d.ts

@@ -0,0 +1,68 @@
+export type CliFlags = {
+    help: boolean;
+    version: boolean;
+    printConfig: boolean;
+    noKeepAlive: boolean;
+    maxRetries?: number;
+    detach: boolean;
+    log?: string;
+    notify: boolean;
+    budget?: number;
+    cooldownMs?: number;
+    reviewPanel: boolean;
+    watch: boolean;
+    watchIntervalSec?: number;
+    issue?: number;
+    maxWaitMs?: number;
+    fresh: boolean;
+    verify: boolean;
+    applyReview?: string;
+    branch?: "current" | "branch" | "worktree";
+    branchPrefix?: string;
+    rest: string[];
+};
+/** Parse a duration: bare integer = seconds; suffix s/m/h supported. Throws on invalid. */
+export declare function parseDurationMs(raw: string): number;
+/**
+ * Normalize a user-supplied issue reference to a positive integer.
+ * Accepts: `42`, `#42`, `owner/repo#42`, and GitHub issue URLs
+ * (`https://github.com/owner/repo/issues/42[#anchor]`). A repo component is
+ * ignored — only the number is used (gh resolves the repo from the workspace).
+ * Throws on anything that is not a positive integer.
+ *
+ * SECURITY: the returned integer is the ONLY part of the ref that may reach a
+ * shell (via the OTTO_ISSUE env var read by a static template command). Never
+ * pass the raw ref to a shell. See render.ts security invariant.
+ */
+export declare function parseIssueRef(raw: string): number;
+export declare function parseFlags(argv: string[]): CliFlags;
+/**
+ * Resolve the @phamvuhoang/otto-core version by reading the package.json that
+ * sits two levels up from the compiled cli-help.js (packages/core/dist/ →
+ * packages/core/package.json). Returns "?" if unreadable so version reporting
+ * never crashes the bin.
+ */
+export declare function readCoreVersion(): string;
+export declare function printVersion(bin: string, cliVersion?: string): void;
+export declare function printHelp(bin: string, usage: string, description: string): void;
+export type PrintConfigOptions = {
+    cliVersion?: string;
+    noKeepAlive?: boolean;
+    maxRetries?: number;
+    detach?: boolean;
+    detachLogPath?: string;
+    notify?: boolean;
+    budget?: number;
+    cooldownMs?: number;
+    /** Resolved review lenses (empty array = single reviewer). */
+    reviewLenses?: string[];
+    watch?: boolean;
+    watchIntervalSec?: number;
+    issue?: number;
+    maxWaitMs?: number;
+    mode?: string;
+    branchStrategy?: "current" | "branch" | "worktree";
+    branchPrefix?: string;
+};
+export declare function printConfig(bin: string, workspaceDir: string, packageDir: string, opts?: PrintConfigOptions): void;
+//# sourceMappingURL=cli-help.d.ts.map

package/dist/cli-help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-help.d.ts","sourceRoot":"","sources":["../src/cli-help.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,QAAQ,GAAG;IACrB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,KAAK,EAAE,OAAO,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAAC;AAEF,2FAA2F;AAC3F,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAWnD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAmBjD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,CA2LnD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAWxC;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAInE;AAED,wBAAgB,SAAS,CACvB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAClB,IAAI,CA+CN;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,kBAAuB,GAC5B,IAAI,CA0EN"}