agent-bober 0.18.0 → 0.19.0

package/dist/cli/commands/research.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"research.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/research.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIzC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAgB1D,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAaxE;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,gFAAgF;IAChF,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;CAC1E;AAID,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,OAAO,EAChB,SAAS,CAAC,EAAE,oBAAoB,GAC/B,IAAI,CAqWN"}

package/dist/cli/commands/research.js

@@ -0,0 +1,313 @@
+/**
+ * `agent-bober research job add|list|remove` — manage recurring multi-model research jobs.
+ * `agent-bober research run <jobId>`         — execute a stored research job.
+ * `agent-bober research tick [--watch]`      — run every due job (idempotent).
+ *
+ * Subcommands:
+ *   research job add --question "..." [--cadence daily|weekly|monthly] [--tier <t>]
+ *                    [--domain <d>] [--target-repo <r>] [--online-research]
+ *   research job list
+ *   research job remove <jobId>
+ *   research run <jobId>
+ *   research tick [--watch] [--interval <ms>]
+ *
+ * Error handling: CLI handlers MUST NOT throw. They set process.exitCode=1 and
+ * return on all errors. Pattern mirrors src/cli/commands/task.ts:360-367.
+ *
+ * Clock discipline: new Date().toISOString() is called ONLY at the .action()
+ * boundary — never inside the store (mirrors task.ts:352 "stamp wall-clock time
+ * at handler boundary").
+ *
+ * fs boundary: ALL direct fs work (ensureDir, writeFile) happens inside runner.ts
+ * and note-writer.ts. This file only calls readJob (JSON read) and opens FactStore.
+ * This keeps the utils/fs.js import surface minimal (only findProjectRoot) so that
+ * the research.test.ts whole-module vi.mock of utils/fs.js stays stable.
+ */
+import chalk from "chalk";
+import { join } from "node:path";
+import { findProjectRoot } from "../../utils/fs.js";
+import { buildDigest, collectRunsFromVault } from "../../research/digest.js";
+import { addJob, listJobs, removeJob, jobId, readJob, } from "../../research/job-store.js";
+import { ResearchJobSchema } from "../../research/types.js";
+import { FactStore, factsDbPath, ensureFactsDir, } from "../../state/facts.js";
+import { ingestFinding } from "../../hub/finding-store.js";
+import { runResearchJob } from "../../research/runner.js";
+import { tick } from "../../research/scheduler.js";
+import { createClient } from "../../providers/factory.js";
+// ── Root resolver ─────────────────────────────────────────────────────
+async function resolveRoot() {
+    const root = await findProjectRoot();
+    return root ?? process.cwd();
+}
+// ── registerResearchCommand ───────────────────────────────────────────
+export function registerResearchCommand(program, overrides) {
+    const researchCmd = program
+        .command("research")
+        .description("Recurring multi-model research jobs");
+    const jobCmd = researchCmd
+        .command("job")
+        .description("Define and manage recurring research jobs (JSON store under .bober/research/jobs)");
+    // ── research job add ─────────────────────────────────────────────
+    jobCmd
+        .command("add")
+        .description("Add a recurring research job")
+        .requiredOption("--question <q>", "The research question (non-empty)")
+        .option("--cadence <c>", "Recurrence cadence: daily | weekly | monthly", "weekly")
+        .option("--tier <t>", "Difficulty tier hint (e.g. hard) — used by executor (Sprint 2)")
+        .option("--domain <d>", "Domain tag (e.g. medical, coding)")
+        .option("--target-repo <r>", "Repository slug to scope the research against")
+        .option("--online-research", "Store onlineResearch=true (egress is not active until Sprint 3)")
+        .action(async (opts) => {
+        const projectRoot = await resolveRoot();
+        try {
+            // Stamp wall-clock time ONLY here — never inside the store
+            const now = new Date().toISOString();
+            const id = jobId(opts.question, now);
+            const job = ResearchJobSchema.parse({
+                id,
+                question: opts.question,
+                cadence: opts.cadence ?? "weekly",
+                tier: opts.tier,
+                domain: opts.domain,
+                targetRepo: opts.targetRepo,
+                onlineResearch: opts.onlineResearch ?? false,
+                createdAt: now,
+            });
+            await addJob(projectRoot, job);
+            process.stdout.write(chalk.green(`Added research job ${chalk.bold(job.id)}\n`) +
+                `  question: ${job.question}\n` +
+                `  cadence:  ${job.cadence}\n`);
+        }
+        catch (err) {
+            process.stderr.write(chalk.red(`research job add failed: ${err instanceof Error ? err.message : String(err)}\n`));
+            process.exitCode = 1;
+        }
+    });
+    // ── research job list ────────────────────────────────────────────
+    jobCmd
+        .command("list")
+        .description("List all recurring research jobs")
+        .action(async () => {
+        const projectRoot = await resolveRoot();
+        try {
+            const jobs = await listJobs(projectRoot);
+            if (jobs.length === 0) {
+                process.stdout.write("No research jobs defined.\n");
+                return;
+            }
+            for (const job of jobs) {
+                process.stdout.write(`${chalk.bold(job.id)}  ${job.cadence}  ${job.question}` +
+                    (job.domain ? `  [${job.domain}]` : "") +
+                    "\n");
+            }
+        }
+        catch (err) {
+            process.stderr.write(chalk.red(`research job list failed: ${err instanceof Error ? err.message : String(err)}\n`));
+            process.exitCode = 1;
+        }
+    });
+    // ── research job remove ──────────────────────────────────────────
+    jobCmd
+        .command("remove <jobId>")
+        .description("Remove a recurring research job by id")
+        .action(async (id) => {
+        const projectRoot = await resolveRoot();
+        try {
+            const removed = await removeJob(projectRoot, id);
+            if (removed) {
+                process.stdout.write(chalk.green(`Removed research job ${chalk.bold(id)}\n`));
+            }
+            else {
+                process.stderr.write(chalk.yellow(`Research job not found: ${id}\n`));
+                process.exitCode = 1;
+            }
+        }
+        catch (err) {
+            process.stderr.write(chalk.red(`research job remove failed: ${err instanceof Error ? err.message : String(err)}\n`));
+            process.exitCode = 1;
+        }
+    });
+    // ── research run <jobId> ─────────────────────────────────────────
+    researchCmd
+        .command("run <jobId>")
+        .description("Execute a stored research job: query >=2 model blocks, write a vault note, emit a hub Finding")
+        .action(async (id) => {
+        const projectRoot = await resolveRoot();
+        try {
+            const job = await readJob(projectRoot, id);
+            if (job === null) {
+                process.stderr.write(chalk.red(`Research job not found: ${id}\n`));
+                process.exitCode = 1;
+                return;
+            }
+            // Stamp wall-clock time ONLY at the handler boundary (principles L31)
+            const now = new Date().toISOString();
+            // Vault root: default to projectRoot (same pattern as `bober vault reindex`)
+            const vaultRoot = projectRoot;
+            // -- queryModel binding --
+            // Use override (tests) or build a real provider-agnostic client binding.
+            // createClient is the ONLY place where provider SDKs are imported — never here.
+            const qm = overrides?.queryModel ??
+                ((block, prompt) => {
+                    const client = createClient(block.provider, block.endpoint ?? null, undefined, block.model, "research");
+                    return client
+                        .chat({
+                        model: block.model,
+                        system: "You are a research assistant. Answer concisely and accurately.",
+                        messages: [{ role: "user", content: prompt }],
+                    })
+                        .then((r) => r.text);
+                });
+            // -- findingSink binding --
+            // Use override (tests) or bind to the real hub ingestFinding.
+            let store = null;
+            const fs = overrides?.findingSink ??
+                (async (finding) => {
+                    if (store === null) {
+                        throw new Error("FactStore was closed before findingSink was called");
+                    }
+                    await ingestFinding(store, finding, { now });
+                });
+            if (overrides?.findingSink === undefined) {
+                await ensureFactsDir(projectRoot);
+                store = new FactStore(factsDbPath(projectRoot));
+            }
+            try {
+                const res = await runResearchJob(job, {
+                    queryModel: qm,
+                    findingSink: fs,
+                    now,
+                    vaultRoot,
+                });
+                process.stdout.write(res.notePath + "\n");
+            }
+            finally {
+                store?.close();
+            }
+        }
+        catch (err) {
+            process.stderr.write(chalk.red(`research run failed: ${err instanceof Error ? err.message : String(err)}\n`));
+            process.exitCode = 1;
+        }
+    });
+    // ── research tick [--watch] ──────────────────────────────────────────
+    researchCmd
+        .command("tick")
+        .description("Run every research job that is due as of now (idempotent).\n\n" +
+        "Scheduling mechanism tradeoff:\n" +
+        "  --watch        in-process setInterval loop — simple, but DIES with the\n" +
+        "                 process (not suitable for unattended production use).\n" +
+        "  OS cron/launchd calling `agent-bober research tick` — survives reboots;\n" +
+        "                 RECOMMENDED for unattended runs. Example crontab entry:\n" +
+        "                   0 * * * * /usr/local/bin/agent-bober research tick\n" +
+        "  harness scheduler (/schedule) — fires the CLI on a cadence inside the\n" +
+        "                 agent harness.\n\n" +
+        "Note: hosted-OAuth schedulers are unfit for unattended runs (research\n" +
+        "doc L135) — use OS cron/launchd for unattended scheduling.")
+        .option("--watch", "Run tick on an in-process interval (loop keeps process alive)")
+        .option("--interval <ms>", "Watch interval in milliseconds (default: 3600000 = 1 hour)", "3600000")
+        .action(async (opts) => {
+        const projectRoot = await resolveRoot();
+        const vaultRoot = projectRoot;
+        // Build one runOnce closure that captures the injected deps.
+        // clock is stamped ONLY inside runOnce at the .action boundary.
+        const runOnce = async () => {
+            // Wall-clock read happens ONLY here (principles L31 / research.ts clock discipline).
+            const now = new Date().toISOString();
+            // -- queryModel binding (mirrors research run above) --
+            const qm = overrides?.queryModel ??
+                ((block, prompt) => {
+                    const client = createClient(block.provider, block.endpoint ?? null, undefined, block.model, "research");
+                    return client
+                        .chat({
+                        model: block.model,
+                        system: "You are a research assistant. Answer concisely and accurately.",
+                        messages: [{ role: "user", content: prompt }],
+                    })
+                        .then((r) => r.text);
+                });
+            // -- findingSink binding (open/close FactStore per runOnce for --watch) --
+            let store = null;
+            const fs = overrides?.findingSink ??
+                (async (finding) => {
+                    if (store === null) {
+                        throw new Error("FactStore was closed before findingSink was called");
+                    }
+                    await ingestFinding(store, finding, { now });
+                });
+            if (overrides?.findingSink === undefined) {
+                await ensureFactsDir(projectRoot);
+                store = new FactStore(factsDbPath(projectRoot));
+            }
+            try {
+                const result = await tick({
+                    now,
+                    listJobs: () => listJobs(projectRoot),
+                    saveJob: (j) => addJob(projectRoot, j),
+                    runJob: (job) => runResearchJob(job, {
+                        queryModel: qm,
+                        findingSink: fs,
+                        now,
+                        vaultRoot,
+                    }).then(() => undefined),
+                });
+                if (result.ran.length > 0) {
+                    process.stdout.write(chalk.green(`research tick: ran ${result.ran.length} job(s): ${result.ran.join(", ")}\n`));
+                }
+                else {
+                    process.stdout.write("research tick: no jobs due.\n");
+                }
+            }
+            finally {
+                // Always close the store — prevents SQLite lock across interval iterations.
+                store?.close();
+            }
+        };
+        try {
+            await runOnce();
+            if (opts.watch === true) {
+                const ms = Math.max(1000, Number(opts.interval ?? "3600000"));
+                // Do NOT .unref() — the watch loop must keep the process alive.
+                // bober: in-memory setInterval; replace with OS cron if the process must
+                //        survive reboots or system sleep (contract nonGoal L4 / briefing §9).
+                setInterval(() => {
+                    void runOnce();
+                }, ms);
+            }
+        }
+        catch (err) {
+            process.stderr.write(chalk.red(`research tick failed: ${err instanceof Error ? err.message : String(err)}\n`));
+            process.exitCode = 1;
+        }
+    });
+    // ── research digest [--since <iso>] ─────────────────────────────────
+    researchCmd
+        .command("digest")
+        .description("Aggregate research runs in [since, now] into a dual md+json digest artifact.\n\n" +
+        "Writes .bober/research/digests/<YYYY-MM-DD>.{md,json} under the project root.\n" +
+        "Empty window: emits an explicit no-new-research digest — never throws.\n" +
+        "Consumer: the Telegram bot (sibling spec) reads the JSON for silent scheduled messages.")
+        .option("--since <iso>", "Window start ISO string (default: 24h before now)")
+        .action(async (opts) => {
+        const projectRoot = await resolveRoot();
+        try {
+            // Stamp wall-clock ONLY here — never inside digest.ts (clock discipline)
+            const now = new Date().toISOString();
+            const since = opts.since ?? new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+            const vaultRoot = projectRoot; // same default as `research run`
+            const digestsDir = join(projectRoot, ".bober", "research", "digests");
+            const res = await buildDigest(since, now, {
+                // Use injected collector (tests) or real vault-note reader (production)
+                collectRuns: overrides?.digestCollectRuns ??
+                    ((s, n) => collectRunsFromVault(vaultRoot, s, n)),
+                digestsDir,
+            });
+            process.stdout.write(res.mdPath + "\n" + res.jsonPath + "\n");
+        }
+        catch (err) {
+            process.stderr.write(chalk.red(`research digest failed: ${err instanceof Error ? err.message : String(err)}\n`));
+            process.exitCode = 1;
+        }
+    });
+}
+//# sourceMappingURL=research.js.map

package/dist/cli/commands/research.js.map

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

package/dist/cli/commands/security-audit.d.ts

@@ -0,0 +1,89 @@
+/**
+ * `agent-bober security-audit [target]` — on-demand stack-aware security audit.
+ *
+ * Synthesizes a lightweight SprintContract-shaped descriptor from the target
+ * path (or the working tree when omitted), runs the same `runSecurityAudit`
+ * core the in-pipeline gate uses (with `evaluation=null` for standalone
+ * mode), persists the artifact via `saveSecurityAudit` (called internally by
+ * the core), prints a human-readable findings summary, and exits with a
+ * CI-friendly code driven by `security.standaloneBlockOn`.
+ *
+ * Threshold semantics (sc-4-2) are CLI-local by design: `thresholdVerdict`
+ * lives HERE, never in `security-gate.ts`. The pipeline gate's critical-only
+ * veto (ADR-2) stays structurally untouched — this command reads
+ * `security.standaloneBlockOn` to decide its OWN exit code only.
+ *
+ * Exit codes: 0 = pass, 2 = blocked-by-threshold OR fail-closed (audit threw,
+ * or the auditor's output could not be parsed). 1 is reserved for Commander's
+ * own usage errors and for unexpected errors resolving config/project root.
+ *
+ * Clock discipline: `new Date().toISOString()` is called ONLY at the
+ * `.action()` boundary — never inside `runStandaloneSecurityAudit` — mirrors
+ * `research.ts`'s "stamp wall-clock time at handler boundary" convention.
+ * Hub emission (sprint 6) reuses `deps.now` for the same reason — it is
+ * never re-stamped inside this module.
+ *
+ * Error handling: CLI handlers MUST NOT throw. They set `process.exitCode`
+ * and return on all errors (mirrors `research.ts` / `do.ts`).
+ */
+import type { Command } from "commander";
+import type { BoberConfig } from "../../config/schema.js";
+import type { SprintContract } from "../../contracts/sprint-contract.js";
+import type { ReviewResult } from "../../orchestrator/code-reviewer-agent.js";
+import type { SecurityAuditResult } from "../../orchestrator/security-audit-types.js";
+import { runSecurityAudit } from "../../orchestrator/security-auditor-agent.js";
+import type { SecurityFindingSink } from "../../orchestrator/security-hub.js";
+/**
+ * Decide whether the standalone CLI should block (exit 2) given a review and
+ * the configured `standaloneBlockOn` threshold. Pure function — no I/O.
+ *
+ * `critical` findings always block, regardless of threshold. `important`
+ * findings only block when `standaloneBlockOn === "important"`. `minor`
+ * findings never block. This is intentionally a *superset* of the pipeline
+ * gate's critical-only veto (`deriveVerdict`) — it must never be imported
+ * into `security-gate.ts` or `pipeline.ts` (sc-4-4 is verified structurally).
+ */
+export declare function thresholdVerdict(review: ReviewResult, standaloneBlockOn: "critical" | "important"): boolean;
+/**
+ * Build a synthetic SprintContract-shaped descriptor for the standalone
+ * audit. The `contractId` is timestamped (`security-audit-<slug>`) so it can
+ * never collide with a pipeline sprint's `sprint-*` contractId, and so the
+ * fs-safe sanitization in `security-audit-state.ts` produces a stable,
+ * readable artifact filename.
+ */
+export declare function buildAuditDescriptor(target: string | undefined, now: string): SprintContract;
+/** Injectable deps so tests never spawn a process or hit a real provider. */
+export interface StandaloneAuditDeps {
+    projectRoot: string;
+    config: BoberConfig;
+    target?: string;
+    /** ISO timestamp, stamped ONCE at the `.action` boundary. */
+    now: string;
+    /** Default = the real `runSecurityAudit` core; tests inject a fake. */
+    runAudit?: typeof runSecurityAudit;
+    /** Injected hub sink (tests only) — default binds ingestFinding to a real FactStore. */
+    findingSink?: SecurityFindingSink;
+}
+export interface StandaloneAuditOutcome {
+    result?: SecurityAuditResult;
+    exitCode: 0 | 2;
+}
+/**
+ * Run a standalone security audit and compute the CI exit code.
+ *
+ * `config.security` may be absent — that is legal for standalone mode (the
+ * explicit CLI invocation IS the opt-in; nonGoals[0]). When absent, the
+ * section is synthesized via `SecuritySectionSchema.parse({})` so the audit
+ * still runs with schema defaults (sc-4-3).
+ *
+ * Fail-closed (sc-4-2): a thrown audit error, or `result.parsed === false`,
+ * always exits 2 — checked BEFORE the threshold, so an empty fallback review
+ * (which `thresholdVerdict` alone would read as "clean") never yields a
+ * false pass.
+ */
+export declare function runStandaloneSecurityAudit(deps: StandaloneAuditDeps): Promise<StandaloneAuditOutcome>;
+export interface SecurityAuditOverrides {
+    runAudit?: typeof runSecurityAudit;
+}
+export declare function registerSecurityAuditCommand(program: Command, overrides?: SecurityAuditOverrides): void;
+//# sourceMappingURL=security-audit.d.ts.map

package/dist/cli/commands/security-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security-audit.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/security-audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKzC,OAAO,KAAK,EAAE,WAAW,EAAmB,MAAM,wBAAwB,CAAC;AAC3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2CAA2C,CAAC;AAC9E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4CAA4C,CAAC;AACtF,OAAO,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAC;AAChF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAQ9E;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,YAAY,EACpB,iBAAiB,EAAE,UAAU,GAAG,WAAW,GAC1C,OAAO,CAIT;AAID;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,cAAc,CA6B5F;AAID,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,GAAG,EAAE,MAAM,CAAC;IACZ,uEAAuE;IACvE,QAAQ,CAAC,EAAE,OAAO,gBAAgB,CAAC;IACnC,wFAAwF;IACxF,WAAW,CAAC,EAAE,mBAAmB,CAAC;CACnC;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC;CACjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,sBAAsB,CAAC,CAqCjC;AAyGD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,OAAO,gBAAgB,CAAC;CACpC;AAED,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,OAAO,EAChB,SAAS,CAAC,EAAE,sBAAsB,GACjC,IAAI,CA8BN"}