agent-composer 0.3.1 → 0.4.1

package/dist/util/oracleLock.d.ts

@@ -0,0 +1,38 @@
+export declare const ORACLE_LOCK_DIR = "oracle-locks";
+export declare const COMPOSER_ORACLE_LOCK_TTL_MS_ENV = "COMPOSER_ORACLE_LOCK_TTL_MS";
+export declare const DEFAULT_ORACLE_LOCK_TTL_MS: number;
+type OracleLockHolder = {
+    pid: number;
+    token: string;
+    jobId?: string;
+    label?: string;
+    startedAt: string;
+};
+export interface OracleLockHandle {
+    release(): void;
+}
+export type OracleLockRecovery = {
+    reasonCode: "stale_lock_recovery";
+    stage: "oracle_lock_acquire";
+    elapsedWallMs: number;
+    lockAgeMs: number;
+    holder: OracleLockHolder;
+};
+export type OracleLockAcquireOptions = {
+    ttlMs?: number;
+    nowMs?: () => number;
+};
+export type OracleLockResult = {
+    acquired: true;
+    handle: OracleLockHandle;
+    recovery?: OracleLockRecovery;
+} | {
+    acquired: false;
+    holder: OracleLockHolder;
+    recovery?: undefined;
+};
+export declare function acquireOracleLock(root: string, info: {
+    jobId?: string;
+    label?: string;
+}, opts?: OracleLockAcquireOptions): OracleLockResult;
+export {};

package/dist/util/oracleLock.js

@@ -0,0 +1,182 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync, } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { COMPOSER_STATE_DIR_ENV } from "./codexLifecycleJob.js";
+export const ORACLE_LOCK_DIR = "oracle-locks";
+export const COMPOSER_ORACLE_LOCK_TTL_MS_ENV = "COMPOSER_ORACLE_LOCK_TTL_MS";
+export const DEFAULT_ORACLE_LOCK_TTL_MS = 30 * 60 * 1000; // generous: longer than any Oracle run
+const ORACLE_LOCK_CLOCK_SKEW_GRACE_MS = 5 * 60 * 1000;
+export function acquireOracleLock(root, info, opts = {}) {
+    const startedMs = (opts.nowMs ?? Date.now)();
+    const ttlMs = resolveOracleLockTtlMs(opts.ttlMs);
+    const lockPath = oracleLockPath(root);
+    const token = randomUUID();
+    const holder = {
+        pid: process.pid,
+        token,
+        jobId: info.jobId,
+        label: info.label,
+        startedAt: new Date().toISOString(),
+    };
+    try {
+        return writeLock(lockPath, holder, token);
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    const existing = readLockHolder(lockPath);
+    const staleRecovery = existing
+        ? staleLockRecovery(lockPath, existing, ttlMs, (opts.nowMs ?? Date.now)(), startedMs)
+        : null;
+    // Steal ONLY a malformed lock, a dead-process lock, or a stale lock.
+    // A live holder (including the SAME process) is a real concurrent holder.
+    if (!existing || !isProcessAlive(existing.pid) || staleRecovery) {
+        rmSync(lockPath, { force: true });
+        try {
+            return writeLock(lockPath, holder, token, staleRecovery ?? undefined);
+        }
+        catch (error) {
+            if (error.code === "EEXIST") {
+                const racer = readLockHolder(lockPath);
+                if (racer)
+                    return { acquired: false, holder: racer };
+            }
+            throw error;
+        }
+    }
+    return { acquired: false, holder: existing };
+}
+function oracleLockPath(root) {
+    const rootReal = realpathSync(root);
+    const stateRoot = oracleStateRoot();
+    const lockRoot = path.join(stateRoot, ORACLE_LOCK_DIR);
+    ensureDirectory(stateRoot, "Composer state root");
+    ensureDirectory(lockRoot, "Oracle lock state root");
+    return path.join(lockRoot, `${projectStateKey(rootReal)}.lock`);
+}
+function writeLock(lockPath, holder, token, recovery) {
+    writeFileSync(lockPath, JSON.stringify(holder), {
+        encoding: "utf8",
+        mode: 0o600,
+        flag: "wx",
+    });
+    return {
+        acquired: true,
+        handle: {
+            release: () => {
+                try {
+                    const current = readLockHolder(lockPath);
+                    if (current?.pid === process.pid && current.token === token) {
+                        rmSync(lockPath, { force: true });
+                    }
+                }
+                catch {
+                    // Best-effort cleanup only.
+                }
+            },
+        },
+        ...(recovery ? { recovery } : {}),
+    };
+}
+function readLockHolder(lockPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(lockPath, "utf8"));
+        if (typeof parsed.pid !== "number" ||
+            !Number.isInteger(parsed.pid) ||
+            typeof parsed.token !== "string" ||
+            typeof parsed.startedAt !== "string") {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function oracleStateRoot() {
+    const override = process.env[COMPOSER_STATE_DIR_ENV]?.trim();
+    if (override)
+        return path.resolve(override);
+    return path.join(os.homedir(), ".local", "state", "composer");
+}
+function projectStateKey(rootReal) {
+    const basename = path.basename(rootReal).replace(/[^A-Za-z0-9._-]+/g, "-") || "project";
+    const slug = basename.slice(0, 48);
+    const digest = createHash("sha256").update(rootReal).digest("hex").slice(0, 24);
+    return `${slug}-${digest}`;
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM = process exists but not signalable by us -> alive.
+        return error.code === "EPERM";
+    }
+}
+function resolveOracleLockTtlMs(override) {
+    if (override !== undefined && Number.isFinite(override) && override > 0) {
+        return Math.floor(override);
+    }
+    const raw = process.env[COMPOSER_ORACLE_LOCK_TTL_MS_ENV]?.trim();
+    if (raw) {
+        const parsed = Number(raw);
+        if (Number.isFinite(parsed) && parsed > 0)
+            return Math.floor(parsed);
+    }
+    return DEFAULT_ORACLE_LOCK_TTL_MS;
+}
+function staleLockRecovery(lockPath, holder, ttlMs, nowMs, acquiredStartedMs) {
+    const startedAtMs = Date.parse(holder.startedAt);
+    const fileAgeMs = lockFileAgeMs(lockPath, nowMs);
+    if (Number.isNaN(startedAtMs)) {
+        return {
+            reasonCode: "stale_lock_recovery",
+            stage: "oracle_lock_acquire",
+            elapsedWallMs: Math.max(0, nowMs - acquiredStartedMs),
+            lockAgeMs: Math.max(0, fileAgeMs ?? 0),
+            holder,
+        };
+    }
+    const startedAgeMs = nowMs - startedAtMs;
+    const effectiveAgeMs = Math.max(0, startedAgeMs, fileAgeMs ?? 0);
+    const clockSkewedFuture = startedAgeMs < -ORACLE_LOCK_CLOCK_SKEW_GRACE_MS;
+    const staleByStartedAt = startedAgeMs > ttlMs;
+    const staleByMtime = fileAgeMs !== null && fileAgeMs > ttlMs;
+    if (!staleByStartedAt && !staleByMtime)
+        return null;
+    return {
+        reasonCode: "stale_lock_recovery",
+        stage: "oracle_lock_acquire",
+        elapsedWallMs: Math.max(0, nowMs - acquiredStartedMs),
+        lockAgeMs: clockSkewedFuture ? Math.max(0, fileAgeMs ?? 0) : effectiveAgeMs,
+        holder,
+    };
+}
+function lockFileAgeMs(lockPath, nowMs) {
+    try {
+        return Math.max(0, nowMs - lstatSync(lockPath).mtimeMs);
+    }
+    catch {
+        return null;
+    }
+}
+function ensureDirectory(dir, label) {
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    assertUsableDirectory(dir, label);
+}
+function assertUsableDirectory(dir, label) {
+    const stat = lstatSync(dir);
+    if (stat.isSymbolicLink()) {
+        throw new Error(`Oracle lock directory must not be a symlink: ${label}`);
+    }
+    if (!stat.isDirectory()) {
+        throw new Error(`Oracle lock path must be a directory: ${label}`);
+    }
+}
+//# sourceMappingURL=oracleLock.js.map

package/dist/util/oracleLock.js.map

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

package/dist/util/reviewDiff.d.ts

@@ -0,0 +1,8 @@
+export type ReviewScope = "staged" | "unstaged" | "working-tree" | "branch";
+export interface ReviewDiffOptions {
+    base?: string;
+    files?: string[];
+}
+/** Compute a git diff for the requested scope, rooted at `root`. Throws on git
+ *  failure or when the scope yields no changes. `files` narrows any scope to a pathspec. */
+export declare function computeReviewDiff(root: string, scope: ReviewScope, opts?: ReviewDiffOptions): string;

package/dist/util/reviewDiff.js

@@ -0,0 +1,29 @@
+import { spawnSync } from "node:child_process";
+/** Compute a git diff for the requested scope, rooted at `root`. Throws on git
+ *  failure or when the scope yields no changes. `files` narrows any scope to a pathspec. */
+export function computeReviewDiff(root, scope, opts = {}) {
+    const args = ["-C", root, "--no-pager", "diff", "--no-ext-diff"];
+    if (scope === "staged")
+        args.push("--cached");
+    else if (scope === "working-tree")
+        args.push("HEAD");
+    else if (scope === "branch")
+        args.push(`${opts.base ?? "main"}...HEAD`);
+    // "unstaged" => plain `git diff`
+    if (opts.files && opts.files.length > 0) {
+        args.push("--", ...opts.files);
+    }
+    const result = spawnSync("git", args, { encoding: "utf8", timeout: 15000, maxBuffer: 32 * 1024 * 1024 });
+    if (result.error) {
+        throw new Error(`composer review: git diff failed: ${result.error.message}`);
+    }
+    if (typeof result.status === "number" && result.status !== 0) {
+        throw new Error(`composer review: git diff exited ${result.status}: ${(result.stderr ?? "").slice(0, 300)}`);
+    }
+    const diff = result.stdout ?? "";
+    if (diff.trim().length === 0) {
+        throw new Error(`composer review: no changes for scope "${scope}"${opts.files?.length ? ` (files: ${opts.files.join(", ")})` : ""}`);
+    }
+    return diff;
+}
+//# sourceMappingURL=reviewDiff.js.map

package/dist/util/reviewDiff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reviewDiff.js","sourceRoot":"","sources":["../../src/util/reviewDiff.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAS/C;4FAC4F;AAC5F,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,KAAkB,EAAE,OAA0B,EAAE;IAC9F,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC;IACjE,IAAI,KAAK,KAAK,QAAQ;QAAE,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;SACzC,IAAI,KAAK,KAAK,cAAc;QAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;SAChD,IAAI,KAAK,KAAK,QAAQ;QAAE,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,IAAI,MAAM,SAAS,CAAC,CAAC;IACxE,iCAAiC;IACjC,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;IACD,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI,EAAE,CAAC,CAAC;IACzG,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,qCAAqC,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IAC/E,CAAC;IACD,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7D,MAAM,IAAI,KAAK,CAAC,oCAAoC,MAAM,CAAC,MAAM,KAAK,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;IAC/G,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC;IACjC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,0CAA0C,KAAK,IAAI,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,YAAY,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACvI,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/util/reviewJob.d.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+export declare const REVIEW_JOB_DIR = "review-jobs";
+export declare const ReviewJobStatusSchema: z.ZodEnum<{
+    queued: "queued";
+    running: "running";
+    succeeded: "succeeded";
+    failed: "failed";
+}>;
+export type ReviewJobStatus = z.infer<typeof ReviewJobStatusSchema>;
+export declare const ReviewJobScopeSchema: z.ZodEnum<{
+    "working-tree": "working-tree";
+    branch: "branch";
+    staged: "staged";
+    unstaged: "unstaged";
+}>;
+export type ReviewJobScope = z.infer<typeof ReviewJobScopeSchema>;
+export declare const ReviewJobSchema: z.ZodObject<{
+    jobId: z.ZodString;
+    status: z.ZodEnum<{
+        queued: "queued";
+        running: "running";
+        succeeded: "succeeded";
+        failed: "failed";
+    }>;
+    scope: z.ZodOptional<z.ZodEnum<{
+        "working-tree": "working-tree";
+        branch: "branch";
+        staged: "staged";
+        unstaged: "unstaged";
+    }>>;
+    base: z.ZodOptional<z.ZodString>;
+    reviewFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    promptPreview: z.ZodString;
+    claude: z.ZodOptional<z.ZodBoolean>;
+    result: z.ZodOptional<z.ZodObject<{
+        verdict: z.ZodOptional<z.ZodString>;
+        summary: z.ZodOptional<z.ZodString>;
+        text: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    error: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodString;
+    startedAt: z.ZodOptional<z.ZodString>;
+    completedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ReviewJob = z.infer<typeof ReviewJobSchema>;
+export declare function newReviewJob(input: {
+    scope?: ReviewJobScope;
+    base?: string;
+    reviewFiles?: string[];
+    promptPreview: string;
+    claude?: boolean;
+}): ReviewJob;
+export declare function writeReviewJob(root: string, job: ReviewJob): ReviewJob;
+export declare function updateReviewJob(root: string, job: ReviewJob, patch: Partial<Omit<ReviewJob, "jobId" | "createdAt">>): ReviewJob;
+export declare function readReviewJob(root: string, jobId: string): ReviewJob | null;
+export declare function readLatestReviewJob(root: string): ReviewJob | null;
+export declare function failInFlightReviewJobs(root: string, error: string): number;

package/dist/util/reviewJob.js

@@ -0,0 +1,207 @@
+import { randomUUID } from "node:crypto";
+import { chmodSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+export const REVIEW_JOB_DIR = "review-jobs";
+const LATEST_REVIEW_JOB_POINTER = ".latest";
+export const ReviewJobStatusSchema = z.enum(["queued", "running", "succeeded", "failed"]);
+export const ReviewJobScopeSchema = z.enum(["staged", "unstaged", "working-tree", "branch"]);
+export const ReviewJobSchema = z
+    .object({
+    jobId: z.string().uuid(),
+    status: ReviewJobStatusSchema,
+    scope: ReviewJobScopeSchema.optional(),
+    base: z.string().optional(),
+    reviewFiles: z.array(z.string()).optional(),
+    promptPreview: z.string(),
+    claude: z.boolean().optional(),
+    result: z
+        .object({
+        verdict: z.string().optional(),
+        summary: z.string().optional(),
+        text: z.string().optional(),
+    })
+        .optional(),
+    error: z.string().optional(),
+    createdAt: z.string().datetime(),
+    startedAt: z.string().datetime().optional(),
+    completedAt: z.string().datetime().optional(),
+})
+    .strict();
+export function newReviewJob(input) {
+    return ReviewJobSchema.parse({
+        jobId: randomUUID(),
+        status: "queued",
+        scope: input.scope,
+        base: input.base,
+        reviewFiles: input.reviewFiles,
+        promptPreview: input.promptPreview,
+        claude: input.claude,
+        createdAt: new Date().toISOString(),
+    });
+}
+export function writeReviewJob(root, job) {
+    const next = ReviewJobSchema.parse(job);
+    const dir = ensureReviewJobDir(root);
+    const resultPath = path.join(dir, `${next.jobId}.json`);
+    writeFileAtomically(resultPath, `${JSON.stringify(next, null, 2)}\n`);
+    writeFileAtomically(path.join(dir, LATEST_REVIEW_JOB_POINTER), `${next.jobId}\n`);
+    return next;
+}
+export function updateReviewJob(root, job, patch) {
+    return writeReviewJob(root, ReviewJobSchema.parse({
+        ...job,
+        ...patch,
+    }));
+}
+export function readReviewJob(root, jobId) {
+    const parsed = z.string().uuid().safeParse(jobId);
+    if (!parsed.success)
+        return null;
+    const dir = existingReviewJobDir(root);
+    if (!dir)
+        return null;
+    const filePath = path.join(dir, `${parsed.data}.json`);
+    try {
+        if (!existsSync(filePath))
+            return null;
+        if (lstatSync(filePath).isSymbolicLink())
+            return null;
+        const raw = readFileSync(filePath, "utf8");
+        return ReviewJobSchema.parse(JSON.parse(raw));
+    }
+    catch {
+        return null;
+    }
+}
+export function readLatestReviewJob(root) {
+    const dir = existingReviewJobDir(root);
+    if (!dir)
+        return null;
+    const pointed = readLatestReviewJobPointer(root, dir);
+    if (pointed)
+        return pointed;
+    const candidates = readdirSync(dir)
+        .filter((name) => name.endsWith(".json"))
+        .map((name) => path.join(dir, name))
+        .filter((filePath) => {
+        try {
+            return !lstatSync(filePath).isSymbolicLink() && statSync(filePath).isFile();
+        }
+        catch {
+            return false;
+        }
+    })
+        .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+    for (const filePath of candidates) {
+        try {
+            const raw = readFileSync(filePath, "utf8");
+            return ReviewJobSchema.parse(JSON.parse(raw));
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+export function failInFlightReviewJobs(root, error) {
+    const dir = existingReviewJobDir(root);
+    if (!dir)
+        return 0;
+    let failed = 0;
+    for (const name of readdirSync(dir)) {
+        if (!name.endsWith(".json"))
+            continue;
+        const filePath = path.join(dir, name);
+        try {
+            if (lstatSync(filePath).isSymbolicLink() || !statSync(filePath).isFile())
+                continue;
+            const job = ReviewJobSchema.parse(JSON.parse(readFileSync(filePath, "utf8")));
+            if (job.status !== "queued" && job.status !== "running")
+                continue;
+            const next = ReviewJobSchema.parse({
+                ...job,
+                status: "failed",
+                completedAt: new Date().toISOString(),
+                error,
+            });
+            writeFileAtomically(filePath, `${JSON.stringify(next, null, 2)}\n`);
+            failed++;
+        }
+        catch {
+            continue;
+        }
+    }
+    return failed;
+}
+function readLatestReviewJobPointer(root, dir) {
+    const pointerPath = path.join(dir, LATEST_REVIEW_JOB_POINTER);
+    try {
+        if (!existsSync(pointerPath))
+            return null;
+        if (lstatSync(pointerPath).isSymbolicLink())
+            return null;
+        const jobId = readFileSync(pointerPath, "utf8").trim();
+        const parsed = z.string().uuid().safeParse(jobId);
+        if (!parsed.success)
+            return null;
+        const job = readReviewJob(root, parsed.data);
+        if (!job || job.jobId !== parsed.data)
+            return null;
+        return job;
+    }
+    catch {
+        return null;
+    }
+}
+function reviewJobDir(root) {
+    return path.join(realpathSync(root), ".composer", REVIEW_JOB_DIR);
+}
+function ensureReviewJobDir(root) {
+    const composerDir = path.join(realpathSync(root), ".composer");
+    const dir = path.join(composerDir, REVIEW_JOB_DIR);
+    ensureDirectory(composerDir, "Composer project state");
+    ensureDirectory(dir, "Review job state");
+    return realpathSync(dir);
+}
+function existingReviewJobDir(root) {
+    if (!existsSync(reviewJobDir(root)))
+        return null;
+    try {
+        const dir = reviewJobDir(root);
+        assertUsableDirectory(dir, "Review job state");
+        return realpathSync(dir);
+    }
+    catch {
+        return null;
+    }
+}
+function ensureDirectory(dir, label) {
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    assertUsableDirectory(dir, label);
+}
+function assertUsableDirectory(dir, label) {
+    const stat = lstatSync(dir);
+    if (stat.isSymbolicLink()) {
+        throw new Error(`Review job directory must not be a symlink: ${label}`);
+    }
+    if (!stat.isDirectory()) {
+        throw new Error(`Review job path must be a directory: ${label}`);
+    }
+}
+function writeFileAtomically(filePath, content) {
+    const dir = path.dirname(filePath);
+    const tmp = path.join(dir, `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
+    try {
+        writeFileSync(tmp, content, { encoding: "utf8", mode: 0o600, flag: "wx" });
+        renameSync(tmp, filePath);
+        chmodSync(filePath, 0o600);
+    }
+    catch (error) {
+        rmSync(tmp, { force: true });
+        throw error;
+    }
+}
+//# sourceMappingURL=reviewJob.js.map

package/dist/util/reviewJob.js.map

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

package/dist/util/workflowPlan.d.ts

@@ -0,0 +1,24 @@
+export type WorkflowKind = "feature" | "debug" | "review" | "research";
+export type WorkflowMode = "fast" | "balanced" | "strict";
+export type WorkflowRisk = "low" | "medium" | "high";
+export interface WorkflowPlanInput {
+    goal: string;
+    workflow?: WorkflowKind;
+    mode?: WorkflowMode;
+    risk?: WorkflowRisk;
+    needsCurrentDocs?: boolean;
+}
+export interface WorkflowStep {
+    tool: string;
+    why: string;
+    optional?: boolean;
+}
+export interface WorkflowPlan {
+    goal: string;
+    workflow: WorkflowKind;
+    mode: WorkflowMode;
+    risk: WorkflowRisk;
+    steps: WorkflowStep[];
+    notes: string[];
+}
+export declare function planWorkflow(input: WorkflowPlanInput): WorkflowPlan;

package/dist/util/workflowPlan.js

@@ -0,0 +1,49 @@
+export function planWorkflow(input) {
+    const workflow = input.workflow ?? "feature";
+    const mode = input.mode ?? "balanced";
+    const risk = input.risk ?? "medium";
+    const steps = [];
+    const includeReview = mode !== "fast";
+    const includeOracle = risk === "high";
+    const includeResearch = input.needsCurrentDocs === true;
+    switch (workflow) {
+        case "feature":
+            steps.push({ tool: "composer_handoff_create", why: "Capture a compact, provider-neutral brief for the workers." });
+            if (includeResearch)
+                steps.push({ tool: "composer_research", why: "Fetch current docs/API shape before implementing.", optional: true });
+            if (includeOracle)
+                steps.push({ tool: "composer_oracle_plan", why: "High risk / architecture uncertainty — get an extended-reasoning plan (sync).", optional: true });
+            steps.push({ tool: "composer_code_cli", why: "Apply the implementation off the main session." });
+            if (includeReview)
+                steps.push({ tool: "composer_review", why: "Review the scoped diff (reviewScope: staged|branch) before commit." });
+            steps.push({ tool: "composer_audit_record", why: "Record the route + outcome for evidence.", optional: true });
+            break;
+        case "debug":
+            if (includeOracle)
+                steps.push({ tool: "composer_oracle_plan", why: "Hard root-cause — extended reasoning (sync).", optional: true });
+            if (includeResearch)
+                steps.push({ tool: "composer_research", why: "Look up error/API specifics.", optional: true });
+            steps.push({ tool: "composer_code_cli", why: "Apply the fix off the main session." });
+            if (includeReview)
+                steps.push({ tool: "composer_review", why: "Review the fix diff." });
+            steps.push({ tool: "composer_audit_record", why: "Record the outcome.", optional: true });
+            break;
+        case "review":
+            steps.push({ tool: "composer_review", why: "Review the scoped diff (use reviewScope to avoid pasting)." });
+            steps.push({ tool: "composer_audit_record", why: "Record the verdict.", optional: true });
+            break;
+        case "research":
+            steps.push({ tool: "composer_research", why: "Gather external context/docs." });
+            steps.push({ tool: "composer_handoff_create", why: "Persist findings for the implementing step.", optional: true });
+            break;
+    }
+    const notes = [];
+    if (mode === "fast")
+        notes.push("fast mode: review + lifecycle gates skipped — use for tiny, low-risk changes.");
+    if (mode === "strict")
+        notes.push("strict mode: review gate + fail-closed pre-commit expected.");
+    if (!includeOracle && (workflow === "feature" || workflow === "debug"))
+        notes.push("Oracle skipped (risk<high). Tag [oracle:plan] explicitly if architecture is uncertain.");
+    return { goal: input.goal, workflow, mode, risk, steps, notes };
+}
+//# sourceMappingURL=workflowPlan.js.map

package/dist/util/workflowPlan.js.map

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