@webpresso/agent-kit 3.1.28 → 3.2.0

package/dist/esm/cli/commands/init/untracked-collision.d.ts

@@ -0,0 +1,14 @@
+import type { ConvergeUnit } from "./convergence.js";
+export type CollisionResolution = "none" | "tracked" | "removed-identical" | "removed-owned";
+export interface CollisionResult {
+    readonly ok: boolean;
+    readonly resolution?: CollisionResolution;
+    readonly error?: string;
+}
+export interface ResolveCollisionOptions {
+    readonly unit: ConvergeUnit;
+    readonly desiredContent: string | Uint8Array;
+    /** Compatibility input only. Unknown content remains protected when true. */
+    readonly force?: boolean;
+}
+export declare function resolveUntrackedCollision(options: ResolveCollisionOptions): CollisionResult;

package/dist/esm/cli/commands/init/untracked-collision.js

@@ -0,0 +1,42 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, lstatSync, readFileSync, rmSync } from "node:fs";
+const GIT_TIMEOUT_MS = 15_000;
+const OWNERSHIP_MARKER = /^\uFEFF?[ \t]*(?:#|\/\/|\/\*|<!--|")?[ \t]*(?:>>> managed by webpresso\b|Generated by webpresso\b)/iu;
+function git(repoRoot, args) {
+    const result = spawnSync("git", [...args], {
+        cwd: repoRoot,
+        encoding: "utf8",
+        timeout: GIT_TIMEOUT_MS,
+        maxBuffer: 1024 * 1024,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    return { ok: result.status === 0 && !result.error };
+}
+export function resolveUntrackedCollision(options) {
+    const { unit } = options;
+    if (!existsSync(unit.targetPath))
+        return { ok: true, resolution: "none" };
+    if (git(unit.repoRoot, ["ls-files", "--error-unmatch", "--", unit.gitPath]).ok) {
+        return { ok: true, resolution: "tracked" };
+    }
+    if (!lstatSync(unit.targetPath).isFile()) {
+        return {
+            ok: false,
+            error: `Untracked collision at ${unit.gitPath} is not a regular file; move it aside and rerun wp setup.`,
+        };
+    }
+    const current = readFileSync(unit.targetPath);
+    if (current.equals(Buffer.from(options.desiredContent))) {
+        rmSync(unit.targetPath);
+        return { ok: true, resolution: "removed-identical" };
+    }
+    if (OWNERSHIP_MARKER.test(current.toString("utf8"))) {
+        rmSync(unit.targetPath);
+        return { ok: true, resolution: "removed-owned" };
+    }
+    return {
+        ok: false,
+        error: `Unknown untracked content blocks ${unit.gitPath}; it was preserved${options.force ? " despite --force" : ""}. ` +
+            "Move or commit the file, then rerun wp setup.",
+    };
+}

package/dist/esm/cli/commands/logs.d.ts

@@ -1,3 +1,18 @@
 import type { CAC } from "cac";
+interface LogsCommandOptions {
+    readonly follow?: boolean;
+    readonly tail?: string | number | boolean;
+    readonly watch?: boolean;
+}
+interface FollowLogFileOptions {
+    readonly pollIntervalMs?: number;
+    readonly signal?: AbortSignal;
+    readonly write?: (chunk: string) => void;
+}
 export declare const LOGS_COMMAND_HELP: string;
 export declare function registerLogsCommand(cli: CAC): void;
+export declare function parseTailLineCount(value: LogsCommandOptions["tail"]): number | null;
+export declare function tailLogContent(content: string, lineCount: number): string;
+export declare function readTailLogContent(logPath: string, lineCount: number, chunkSize?: number): string;
+export declare function followLogFile(logPath: string, startOffset: number, options?: FollowLogFileOptions): Promise<number>;
+export {};

package/dist/esm/cli/commands/logs.js

@@ -1,16 +1,22 @@
-import { readFileSync } from "node:fs";
+import { closeSync, createReadStream, openSync, readFileSync, readSync, statSync, unwatchFile, watchFile, } from "node:fs";
 import { CLI_LOG_COMMANDS, isCliLogCommandName, readCliLogEntry } from "./quality-log-store.js";
+const TAIL_READ_CHUNK_BYTES = 64 * 1024;
 export const LOGS_COMMAND_HELP = [
     "Print persisted raw output for a recent summary-first quality command run.",
     "",
     "Examples:",
     "  wp logs test",
     "  wp logs qa 2",
+    "  wp logs test --tail 200",
+    "  wp logs test --tail 200 --follow",
 ].join("\n");
 export function registerLogsCommand(cli) {
     cli
         .command("logs <command> [n]", LOGS_COMMAND_HELP)
-        .action((command, n) => {
+        .option("--follow", "Keep printing appended output from the selected log")
+        .option("--tail <lines>", "Print only the last N lines from the selected log")
+        .option("--watch", "Alias for --follow")
+        .action((command, n, options = {}) => {
         if (!isCliLogCommandName(command)) {
             console.error(`Unknown logs command: ${command}. Expected one of: ${CLI_LOG_COMMANDS.join(", ")}`);
             return 1;
@@ -20,12 +26,195 @@ export function registerLogsCommand(cli) {
             console.error("Usage: wp logs <command> [n]\n`n` must be an integer in the range 1..10.");
             return 1;
         }
+        const tailLines = parseTailLineCount(options.tail);
+        if (tailLines !== null && tailLines < 1) {
+            console.error("Usage: wp logs <command> [n] [--tail <lines>]\n`tail` must be a positive integer.");
+            return 1;
+        }
         const entry = readCliLogEntry(command, ordinal);
         if (!entry) {
             console.log(`No logs yet for ${command}.`);
             return 0;
         }
-        process.stdout.write(readFileSync(entry.logPath, "utf8"));
+        const snapshot = tailLines === null
+            ? readFullLogSnapshot(entry.logPath)
+            : readTailLogSnapshot(entry.logPath, tailLines);
+        const printed = snapshot.content;
+        process.stdout.write(printed);
+        if (options.follow === true || options.watch === true) {
+            return followLogFile(entry.logPath, snapshot.offset);
+        }
         return 0;
     });
 }
+export function parseTailLineCount(value) {
+    if (value === undefined || value === null || value === false)
+        return null;
+    if (value === true)
+        return 0;
+    const count = typeof value === "number" ? value : Number(value);
+    if (!Number.isInteger(count) || count < 1)
+        return 0;
+    return count;
+}
+export function tailLogContent(content, lineCount) {
+    const lines = content.split("\n");
+    const trailingNewline = lines.at(-1) === "";
+    const body = trailingNewline ? lines.slice(0, -1) : lines;
+    const selected = body.slice(-lineCount);
+    if (selected.length === 0)
+        return "";
+    return `${selected.join("\n")}${trailingNewline ? "\n" : ""}`;
+}
+export function readTailLogContent(logPath, lineCount, chunkSize = TAIL_READ_CHUNK_BYTES) {
+    return readTailLogSnapshot(logPath, lineCount, chunkSize).content;
+}
+function readFullLogSnapshot(logPath) {
+    const content = readFileSync(logPath, "utf8");
+    return { content, offset: Buffer.byteLength(content) };
+}
+function readTailLogSnapshot(logPath, lineCount, chunkSize = TAIL_READ_CHUNK_BYTES) {
+    const fileSize = statSync(logPath).size;
+    if (fileSize === 0 || lineCount < 1)
+        return { content: "", offset: fileSize };
+    const fd = openSync(logPath, "r");
+    try {
+        const hasTrailingNewline = readLastByte(fd, fileSize) === 0x0a;
+        const targetNewlines = hasTrailingNewline ? lineCount + 1 : lineCount;
+        const chunks = [];
+        let position = fileSize;
+        let newlineCount = 0;
+        while (position > 0 && newlineCount < targetNewlines) {
+            const bytesToRead = Math.min(chunkSize, position);
+            position -= bytesToRead;
+            const buffer = Buffer.allocUnsafe(bytesToRead);
+            const bytesRead = readSync(fd, buffer, 0, bytesToRead, position);
+            const chunk = buffer.subarray(0, bytesRead);
+            chunks.unshift(chunk);
+            newlineCount += countNewlines(chunk);
+        }
+        return {
+            content: tailLogContent(Buffer.concat(chunks).toString("utf8"), lineCount),
+            offset: fileSize,
+        };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function readLastByte(fd, fileSize) {
+    if (fileSize < 1)
+        return null;
+    const buffer = Buffer.allocUnsafe(1);
+    const bytesRead = readSync(fd, buffer, 0, 1, fileSize - 1);
+    return bytesRead === 1 ? buffer.readUInt8(0) : null;
+}
+function countNewlines(buffer) {
+    let count = 0;
+    for (const byte of buffer) {
+        if (byte === 0x0a)
+            count++;
+    }
+    return count;
+}
+export function followLogFile(logPath, startOffset, options = {}) {
+    if (options.signal?.aborted === true)
+        return Promise.resolve(0);
+    let offset = startOffset;
+    let pendingSize = startOffset;
+    let reading = false;
+    let readGeneration = 0;
+    let settled = false;
+    let activeStream = null;
+    let poll = null;
+    const write = options.write ??
+        ((chunk) => {
+            process.stdout.write(chunk);
+        });
+    let resolvePromise = null;
+    const settle = () => {
+        if (settled)
+            return;
+        settled = true;
+        unwatchFile(logPath, onChange);
+        activeStream?.destroy();
+        if (poll !== null)
+            clearInterval(poll);
+        process.off("SIGINT", onSignal);
+        process.off("SIGTERM", onSignal);
+        options.signal?.removeEventListener("abort", onSignal);
+        resolvePromise?.(0);
+    };
+    const onSignal = () => {
+        settle();
+    };
+    const drain = () => {
+        if (settled || reading || pendingSize <= offset)
+            return;
+        reading = true;
+        const nextOffset = pendingSize;
+        const generation = readGeneration;
+        const stream = createReadStream(logPath, {
+            encoding: "utf8",
+            start: offset,
+            end: nextOffset - 1,
+        });
+        activeStream = stream;
+        stream.on("data", (chunk) => {
+            if (settled)
+                return;
+            write(String(chunk));
+        });
+        stream.on("close", () => {
+            if (activeStream === stream)
+                activeStream = null;
+            if (settled || generation !== readGeneration)
+                return;
+            offset = nextOffset;
+            reading = false;
+            drain();
+        });
+        stream.on("error", onSignal);
+    };
+    const onChange = (current) => {
+        if (settled)
+            return;
+        if (current.size < pendingSize) {
+            readGeneration++;
+            activeStream?.destroy();
+            activeStream = null;
+            reading = false;
+            offset = 0;
+            pendingSize = current.size;
+            drain();
+            return;
+        }
+        if (current.size <= pendingSize)
+            return;
+        pendingSize = current.size;
+        drain();
+    };
+    return new Promise((resolve) => {
+        resolvePromise = resolve;
+        process.once("SIGINT", onSignal);
+        process.once("SIGTERM", onSignal);
+        options.signal?.addEventListener("abort", onSignal, { once: true });
+        watchFile(logPath, { interval: options.pollIntervalMs ?? 250 }, onChange);
+        poll = setInterval(() => {
+            if (settled)
+                return;
+            try {
+                onChange(statSync(logPath));
+            }
+            catch (error) {
+                if (isMissingFileError(error))
+                    return;
+                onSignal();
+            }
+        }, options.pollIntervalMs ?? 250);
+        onChange(statSync(logPath));
+    });
+}
+function isMissingFileError(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}

package/dist/esm/cli/commands/opencode-rotate.d.ts

@@ -0,0 +1,49 @@
+import { resolveOpencodeAccountsGracefully } from "#runtime/opencode-account-materializer.js";
+/** The `--wp-rotate` flag, namespaced like `--wp-permission-mode`. */
+export declare const OPENCODE_ROTATE_FLAG = "--wp-rotate";
+export type OpencodeRotateOutcome = 
+/** The previously-active account was cooled and a different one is now active. */
+{
+    readonly kind: "rotated";
+    readonly cooledAccountId: string;
+    readonly activeAccountId: string;
+    readonly activeIsCooled: boolean;
+    readonly waitMs?: number;
+}
+/** The on-disk key matched no known account, so nothing was cooled. */
+ | {
+    readonly kind: "reselected";
+    readonly activeAccountId: string;
+    readonly activeIsCooled: boolean;
+}
+/** Fewer than two accounts are provisioned — there is nowhere to rotate to. */
+ | {
+    readonly kind: "single-account";
+}
+/** Secrets could not be resolved; the caller must still launch normally. */
+ | {
+    readonly kind: "unavailable";
+    readonly reason: string;
+};
+export interface OpencodeRotateDeps {
+    readonly resolveOpencodeAccounts?: typeof resolveOpencodeAccountsGracefully;
+    readonly readActiveKey?: () => string | undefined;
+    readonly materializeGlobalOpencodeAuth?: (key: string) => void;
+    readonly recordCooldown?: (canonicalId: string) => Promise<unknown>;
+}
+/**
+ * Cool the currently-materialized opencode-go account and materialize the next
+ * usable one into the global `auth.json`.
+ *
+ * The active account is identified by reading the global store back and matching
+ * its key against the resolved accounts — `wp` wrote that value itself, so this
+ * stays correct without persisting a separate "last launched" record. When the
+ * key matches nothing (a hand-edited store, or a fresh machine), the rotation
+ * degrades to a plain reselect and cools nothing, because cooling an account we
+ * cannot identify would suppress the wrong one.
+ *
+ * Never throws: the caller launches the TUI regardless of the outcome.
+ */
+export declare function rotateActiveOpencodeAccount(cwd: string, secretProfile: string, deps?: OpencodeRotateDeps): Promise<OpencodeRotateOutcome>;
+/** Human-readable lines describing a rotation outcome, in print order. */
+export declare function describeOpencodeRotate(outcome: OpencodeRotateOutcome): readonly string[];

package/dist/esm/cli/commands/opencode-rotate.js

@@ -0,0 +1,135 @@
+import { loadOpencodeAccountAvailability, pruneExpiredOpencodeAccountSuppressions, recordOpencodeAccountAvailabilityWithLock, } from "#review/availability.js";
+import { opencodeAccountCanonicalId, selectActiveOpencodeAccount, } from "#review/opencode-account.js";
+import { materializeOpencodeGoAuth, readOpencodeGoKey } from "#review/opencode-auth.js";
+import { resolveOpencodeAccountsGracefully } from "#runtime/opencode-account-materializer.js";
+/** The `--wp-rotate` flag, namespaced like `--wp-permission-mode`. */
+export const OPENCODE_ROTATE_FLAG = "--wp-rotate";
+/**
+ * A manual rotation has no provider response to parse a reset window from, so it
+ * assumes the shortest real OpenCode Go window (5 hours). Recording no window at
+ * all would leave the record permanently suppressed — `suppressionExpired` only
+ * clears a record that carries `retryAfterMs` — so every rotated account would
+ * be cooled forever and selection would degrade to "first account" again. A
+ * too-short guess is self-correcting: the account is retried, and if it is still
+ * capped the gate (or the next rotation) simply cools it again.
+ */
+const MANUAL_ROTATION_COOLDOWN_MS = 5 * 60 * 60 * 1_000;
+function coolActiveAccount(canonicalId, deps) {
+    if (deps.recordCooldown)
+        return deps.recordCooldown(canonicalId);
+    // Same event shape the review gate records on an in-flight usage limit, so
+    // both writers produce identical, mutually-readable cooldown records.
+    return recordOpencodeAccountAvailabilityWithLock(canonicalId, {
+        failureCode: "opencode-go-usage-limit",
+        terminalClassification: "provider-limit-reached",
+        limitWindow: "unknown",
+        retryAfterMs: MANUAL_ROTATION_COOLDOWN_MS,
+    });
+}
+/**
+ * Pick the account to make active next.
+ *
+ * `excludeId` is the account we just cooled. It is filtered out here rather
+ * than relied upon coming back suppressed from the store: that keeps rotation
+ * correct even if the cooldown write is slow, contended, or fails outright, and
+ * removes a read-after-write dependency from the hot path.
+ */
+function selectNextAccount(accounts, excludeId) {
+    const pruned = pruneExpiredOpencodeAccountSuppressions(loadOpencodeAccountAvailability());
+    const candidates = excludeId === undefined ? accounts : accounts.filter((account) => account.id !== excludeId);
+    // Callers guarantee at least one candidate: rotation needs >= 2 accounts, and
+    // the no-exclude path is only reached with a non-empty list.
+    const pool = candidates.length > 0 ? candidates : accounts;
+    const selection = selectActiveOpencodeAccount(pool, pruned.state);
+    return selection ?? { account: pool[0], cooled: false };
+}
+/**
+ * Cool the currently-materialized opencode-go account and materialize the next
+ * usable one into the global `auth.json`.
+ *
+ * The active account is identified by reading the global store back and matching
+ * its key against the resolved accounts — `wp` wrote that value itself, so this
+ * stays correct without persisting a separate "last launched" record. When the
+ * key matches nothing (a hand-edited store, or a fresh machine), the rotation
+ * degrades to a plain reselect and cools nothing, because cooling an account we
+ * cannot identify would suppress the wrong one.
+ *
+ * Never throws: the caller launches the TUI regardless of the outcome.
+ */
+export async function rotateActiveOpencodeAccount(cwd, secretProfile, deps = {}) {
+    try {
+        return await rotateOrThrow(cwd, secretProfile, deps);
+    }
+    catch (error) {
+        // The cooldown write takes the user-scope lock the review gate also holds
+        // (contention rejects after a few short retries) and the auth write can fail
+        // with EACCES/ENOSPC. Neither may abort the launch, so both degrade to the
+        // same "carry on and launch" outcome the sibling select path uses.
+        return { kind: "unavailable", reason: error instanceof Error ? error.message : String(error) };
+    }
+}
+async function rotateOrThrow(cwd, secretProfile, deps) {
+    const resolution = (deps.resolveOpencodeAccounts ?? resolveOpencodeAccountsGracefully)({
+        cwd,
+        secretProfile,
+    });
+    if (!resolution.ok)
+        return { kind: "unavailable", reason: resolution.reason };
+    const accounts = resolution.accounts;
+    if (accounts.length < 2)
+        return { kind: "single-account" };
+    const activeKey = (deps.readActiveKey ?? (() => readOpencodeGoKey()))();
+    const current = accounts.find((account) => account.key === activeKey);
+    const materialize = deps.materializeGlobalOpencodeAuth ?? ((key) => void materializeOpencodeGoAuth(key));
+    if (!current) {
+        const next = selectNextAccount(accounts);
+        materialize(next.account.key);
+        return { kind: "reselected", activeAccountId: next.account.id, activeIsCooled: next.cooled };
+    }
+    await coolActiveAccount(opencodeAccountCanonicalId(current.id), deps);
+    const next = selectNextAccount(accounts, current.id);
+    materialize(next.account.key);
+    return {
+        kind: "rotated",
+        cooledAccountId: current.id,
+        activeAccountId: next.account.id,
+        activeIsCooled: next.cooled,
+        ...(next.waitMs === undefined ? {} : { waitMs: next.waitMs }),
+    };
+}
+function formatWait(waitMs) {
+    if (waitMs === undefined)
+        return "";
+    const hours = waitMs / 3_600_000;
+    if (hours >= 24)
+        return ` (resets in ~${Math.ceil(hours / 24)}d)`;
+    if (hours >= 1)
+        return ` (resets in ~${Math.ceil(hours)}h)`;
+    return ` (resets in ~${Math.max(1, Math.ceil(waitMs / 60_000))}m)`;
+}
+/** Human-readable lines describing a rotation outcome, in print order. */
+export function describeOpencodeRotate(outcome) {
+    switch (outcome.kind) {
+        case "unavailable":
+            return [`wp opencode: could not resolve OpenCode Go accounts (${outcome.reason}).`];
+        case "single-account":
+            return [
+                "wp opencode: only one OpenCode Go account is configured; nothing to rotate to. Add OPENCODE_GO_KEY_<ID> secrets to enable rotation.",
+            ];
+        case "reselected":
+            return [
+                "wp opencode: the active key matches no configured account, so nothing was cooled.",
+                `wp opencode: now active -> opencode-go:${outcome.activeAccountId}`,
+            ];
+        case "rotated": {
+            const lines = [
+                `wp opencode: cooled opencode-go:${outcome.cooledAccountId} (usage limit)`,
+                `wp opencode: now active -> opencode-go:${outcome.activeAccountId}`,
+            ];
+            if (outcome.activeIsCooled) {
+                lines.push(`wp opencode: every account is within its cooldown; using the soonest-expiring one${formatWait(outcome.waitMs)}. Run again after it resets, or add another OPENCODE_GO_KEY_<ID>.`);
+            }
+            return lines;
+        }
+    }
+}

package/dist/esm/cli/commands/public-readiness.d.ts

@@ -0,0 +1,11 @@
+import type { CAC } from "cac";
+export declare const PUBLIC_READINESS_COMMAND_HELP: string;
+export interface PublicReadinessDeps {
+    readonly cwd?: string;
+    readonly resolveRepoRoot?: (cwd: string) => string | null;
+    readonly hasReadinessScript?: (repoRoot: string) => boolean;
+    readonly run?: (repoRoot: string) => number;
+    readonly stderr?: Pick<typeof process.stderr, "write">;
+}
+export declare function runPublicReadiness(deps?: PublicReadinessDeps): number;
+export declare function registerPublicReadinessCommand(cli: CAC): void;

package/dist/esm/cli/commands/public-readiness.js

@@ -0,0 +1,42 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { getGitTopLevel } from "#git/changed-files";
+export const PUBLIC_READINESS_COMMAND_HELP = [
+    "Run the public package readiness gate.",
+    "",
+    "Delegates to scripts/public-readiness.ts, preserving that script as the",
+    "single owner of package and repository visibility readiness checks.",
+    "",
+    "Examples:",
+    "  wp public:readiness",
+].join("\n");
+function defaultRunPublicReadiness(repoRoot) {
+    const result = spawnSync("bun", ["scripts/public-readiness.ts"], {
+        cwd: repoRoot,
+        stdio: "inherit",
+        env: process.env,
+    });
+    if (result.error) {
+        process.stderr.write(`${result.error.message}\n`);
+        return 1;
+    }
+    return typeof result.status === "number" ? result.status : 1;
+}
+export function runPublicReadiness(deps = {}) {
+    const cwd = deps.cwd ?? process.cwd();
+    const stderr = deps.stderr ?? process.stderr;
+    const resolveRepoRoot = deps.resolveRepoRoot ?? ((current) => getGitTopLevel(current));
+    const hasReadinessScript = deps.hasReadinessScript ??
+        ((repoRoot) => existsSync(path.join(repoRoot, "scripts", "public-readiness.ts")));
+    const run = deps.run ?? defaultRunPublicReadiness;
+    const repoRoot = resolveRepoRoot(cwd) ?? cwd;
+    if (!hasReadinessScript(repoRoot)) {
+        stderr.write(`wp public:readiness: scripts/public-readiness.ts is missing at ${repoRoot}.\n`);
+        return 1;
+    }
+    return run(repoRoot);
+}
+export function registerPublicReadinessCommand(cli) {
+    cli.command("public:readiness", PUBLIC_READINESS_COMMAND_HELP).action(() => runPublicReadiness());
+}

package/dist/esm/cli/commands/quality-log-store.d.ts

@@ -6,6 +6,7 @@ export interface CliLogEntry {
     readonly timestamp: string;
     readonly exitCode: number;
     readonly logPath: string;
+    readonly active?: boolean;
     readonly options?: Record<string, unknown>;
     readonly summary?: string;
 }