@webpresso/agent-kit 3.1.30 → 3.3.0

package/dist/esm/blueprint/service/BlueprintCreationService.js

@@ -42,12 +42,38 @@ function sentenceCase(value) {
     }
     return value.slice(0, 1).toUpperCase() + value.slice(1);
 }
+// A slug becomes a branch name, worktree directory, and repeated CLI argument,
+// so an unbounded goal string must not produce an unbounded slug. Cap it at a
+// word AND a character ceiling (whichever binds first), truncating on a word
+// boundary. The full goal survives as the human-readable title; only the slug
+// is bounded. Collision suffixing runs AFTER this cap, so `-2` is never counted
+// against the ceiling.
+const MAX_SLUG_WORDS = 6;
+const MAX_SLUG_CHARS = 50;
+// Bound on atomic slug-folder reservation retries under concurrent creation.
+const MAX_SLUG_RESERVATION_ATTEMPTS = 50;
+function capSlug(slug) {
+    const [firstWord, ...rest] = slug.split("-").filter(Boolean).slice(0, MAX_SLUG_WORDS);
+    if (firstWord === undefined)
+        return slug;
+    let capped = firstWord;
+    for (const word of rest) {
+        const candidate = `${capped}-${word}`;
+        if (candidate.length > MAX_SLUG_CHARS)
+            break;
+        capped = candidate;
+    }
+    // A single first word longer than the ceiling is hard-trimmed; drop any
+    // trailing hyphen the trim could expose.
+    return capped.slice(0, MAX_SLUG_CHARS).replace(/-+$/u, "");
+}
 function deriveSlug(goal) {
-    return goal
+    const slug = goal
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, "-")
         .replace(/^-+|-+$/g, "")
         .replace(/-{2,}/g, "-");
+    return capSlug(slug);
 }
 function assertGoalProducesUsableSlug(goal, slug) {
     if (slug.length === 0) {
@@ -223,11 +249,16 @@ export class BlueprintCreationService {
     async create(input) {
         // H-009: refuse primary-like roots so drafts never leak onto main checkouts.
         assertDraftAuthoringAllowed(this.projectRoot);
-        const draft = await this.compileDraft(input);
         const draftRoot = path.join(this.blueprintsRoot, "draft");
-        const finalPath = draft.outputPath;
         await mkdir(draftRoot, { recursive: true });
-        await mkdir(path.dirname(finalPath), { recursive: true });
+        // Atomically RESERVE the slug folder. Two concurrent creations (CLI *and*
+        // MCP) can each resolve the same collision-safe slug before either writes;
+        // a plain recursive mkdir + rename would then let the later writer silently
+        // overwrite the earlier draft. `mkdir(..., { recursive: false })` is atomic:
+        // exactly one racer creates the folder, the loser gets EEXIST and re-resolves
+        // to the next `-N` suffix (compileDraft re-scans and sees the reservation).
+        const draft = await this.reserveDraftSlugFolder(input);
+        const finalPath = draft.outputPath;
         const tempDir = await mkdtemp(path.join(draftRoot, `${draft.slug}.tmp-`));
         const tempPath = path.join(tempDir, `${draft.slug}.md`);
         try {
@@ -252,6 +283,24 @@ export class BlueprintCreationService {
             throw error;
         }
     }
+    // Compile a draft and atomically claim its slug folder, retrying with the next
+    // collision-safe slug when a concurrent creator wins the folder first.
+    async reserveDraftSlugFolder(input) {
+        for (let attempt = 0; attempt < MAX_SLUG_RESERVATION_ATTEMPTS; attempt += 1) {
+            const candidate = await this.compileDraft(input);
+            try {
+                await mkdir(path.dirname(candidate.outputPath), { recursive: false });
+                return candidate;
+            }
+            catch (error) {
+                // Folder already reserved by a concurrent creator — re-resolve the slug.
+                if (error instanceof Error && error.code === "EEXIST")
+                    continue;
+                throw error;
+            }
+        }
+        throw new Error(`Could not reserve a unique blueprint slug after ${MAX_SLUG_RESERVATION_ATTEMPTS} attempts.`);
+    }
     resolveCollisionSafeSlug(baseSlug) {
         const blueprintsRoot = this.blueprintsRoot;
         const existing = new Set(scanBlueprintDirectory({

package/dist/esm/blueprint/service/blueprint-tech-debt-links.js

@@ -1,15 +1,29 @@
 import matter from "gray-matter";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { getBlueprintDocumentCandidates } from "#utils/document-paths.js";
 import { resolveTechDebtRoot } from "#utils/tech-debt-root";
+async function resolveBlueprintDocumentPath(baseDir, bpSlug) {
+    const candidates = getBlueprintDocumentCandidates(baseDir, bpSlug);
+    for (const candidate of candidates) {
+        try {
+            await fs.access(candidate);
+            return candidate;
+        }
+        catch {
+            // Keep trying the other canonical shape.
+        }
+    }
+    return candidates.at(-1) ?? path.join(baseDir, bpSlug, "_overview.md");
+}
 export async function linkBlueprintToTechDebt(baseDir, projectPath, bpSlug, tdSlug) {
-    const blueprintPath = path.join(baseDir, bpSlug, "_overview.md");
+    const blueprintPath = await resolveBlueprintDocumentPath(baseDir, bpSlug);
     await updateLinkedSlugs(blueprintPath, "linked_tech_debt_slugs", (linked) => [...linked, tdSlug]);
     const tdPath = path.join(resolveTechDebtRoot(projectPath), tdSlug, "README.md");
     await updateLinkedSlugs(tdPath, "linked_blueprints", (linked) => [...linked, bpSlug]);
 }
 export async function unlinkBlueprintFromTechDebt(baseDir, projectPath, bpSlug, tdSlug) {
-    const blueprintPath = path.join(baseDir, bpSlug, "_overview.md");
+    const blueprintPath = await resolveBlueprintDocumentPath(baseDir, bpSlug);
     await updateLinkedSlugs(blueprintPath, "linked_tech_debt_slugs", (linked) => linked.filter((slug) => slug !== tdSlug));
     const tdPath = path.join(resolveTechDebtRoot(projectPath), tdSlug, "README.md");
     try {

package/dist/esm/blueprint/sync/client.d.ts

@@ -5,6 +5,7 @@
  * platform requests share the strict origin, redirect, body, redaction, abort,
  * and retry boundary in src/platform/client.ts.
  */
+import { type FetchLike } from "#platform/client.js";
 import type { SyncCredentials } from "./auth.js";
 import type { BlueprintPlatformClient, BlueprintPlatformEvent, BlueprintSnapshot, BlueprintTemplateEntry } from "./types.js";
 export declare class AuthError extends Error {
@@ -22,7 +23,7 @@ export declare class BlueprintSyncClient implements BlueprintPlatformClient {
     private readonly fetchFn;
     private platformClient;
     private readonly retry;
-    constructor(creds: SyncCredentials, fetchFn?: typeof globalThis.fetch, retryOptions?: RetryOptions);
+    constructor(creds: SyncCredentials, fetchFn?: FetchLike, retryOptions?: RetryOptions);
     pushEvent(payload: BlueprintPlatformEvent): Promise<void>;
     getSnapshot(opts?: {
         readonly slug?: string;

package/dist/esm/blueprint/sync/client.js

@@ -6,7 +6,7 @@
  * and retry boundary in src/platform/client.ts.
  */
 import { randomUUID } from "node:crypto";
-import { PlatformClient, PlatformHttpError } from "#platform/client.js";
+import { PlatformClient, PlatformHttpError, } from "#platform/client.js";
 export class AuthError extends Error {
     constructor(message) {
         super(message);

package/dist/esm/blueprint/trust/command-runner.d.ts

@@ -0,0 +1,26 @@
+import { spawnSync } from "node:child_process";
+export declare const ALLOWED_WP_COMMAND_TIMEOUT_MS = 30000;
+export declare const ALLOWED_WP_COMMAND_STDIO_TAIL_LIMIT = 500;
+export type AllowedWpCommandOutcome = "passed" | "failed" | "timed-out";
+export interface AllowedWpCommandResult {
+    readonly command: string;
+    readonly outcome: AllowedWpCommandOutcome;
+    readonly durationMs: number;
+    readonly exitCode: number | null;
+    readonly signal?: string;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly logPath?: string;
+    readonly failureCode?: string;
+    readonly errorMessage?: string;
+}
+export interface ExecuteAllowedWpCommandInput {
+    readonly command: string;
+    readonly executionRoot: string;
+    readonly logRoot: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly spawn?: typeof spawnSync;
+}
+export declare function executeAllowedWpCommand(input: ExecuteAllowedWpCommandInput): AllowedWpCommandResult;
+export declare function tailBounded(text: string): string;
+export declare function relativeCommandLogPath(root: string, logPath: string | undefined): string | undefined;

package/dist/esm/blueprint/trust/command-runner.js

@@ -0,0 +1,148 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { parseAllowedWpCommand } from "./gates.js";
+import { resolvePackageAssetPreferred } from "#utils/package-assets.js";
+export const ALLOWED_WP_COMMAND_TIMEOUT_MS = 30_000;
+export const ALLOWED_WP_COMMAND_STDIO_TAIL_LIMIT = 500;
+export function executeAllowedWpCommand(input) {
+    const started = Date.now();
+    let invocation;
+    try {
+        const argv = parseAllowedWpCommand(input.command);
+        const [binary, ...args] = argv;
+        if (binary === undefined)
+            throw new Error(`Promotion gate command is empty: ${input.command}`);
+        invocation = resolveAllowedWpInvocation(input.executionRoot, binary, args, input.env);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const result = {
+            command: input.command,
+            outcome: "failed",
+            durationMs: Date.now() - started,
+            exitCode: null,
+            stdout: "",
+            stderr: message,
+            failureCode: "command-policy-rejected",
+            errorMessage: message,
+        };
+        return {
+            ...result,
+            logPath: writeAllowedWpCommandLog(input.logRoot, input.command, null, result),
+        };
+    }
+    const spawn = input.spawn ?? spawnSync;
+    const result = spawn(invocation.command, invocation.args, {
+        cwd: input.executionRoot,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: ALLOWED_WP_COMMAND_TIMEOUT_MS,
+        env: invocation.env,
+    });
+    const durationMs = Date.now() - started;
+    const stdout = typeof result.stdout === "string" ? result.stdout : "";
+    const stderr = typeof result.stderr === "string" ? result.stderr : "";
+    const timedOut = result.error ? errorCode(result.error) === "ETIMEDOUT" : false;
+    const output = {
+        command: input.command,
+        outcome: result.status === 0 && !result.error && result.signal === null
+            ? "passed"
+            : timedOut
+                ? "timed-out"
+                : "failed",
+        durationMs,
+        exitCode: typeof result.status === "number" ? result.status : null,
+        ...(result.signal ? { signal: result.signal } : {}),
+        stdout,
+        stderr,
+        ...(timedOut ? { failureCode: "command-timed-out" } : {}),
+        ...(result.error ? { errorMessage: result.error.message } : {}),
+    };
+    if (output.outcome === "passed")
+        return output;
+    return {
+        ...output,
+        logPath: writeAllowedWpCommandLog(input.logRoot, input.command, invocation, output),
+    };
+}
+export function tailBounded(text) {
+    if (text.length <= ALLOWED_WP_COMMAND_STDIO_TAIL_LIMIT)
+        return text.trim();
+    return text.slice(-ALLOWED_WP_COMMAND_STDIO_TAIL_LIMIT).trim();
+}
+export function relativeCommandLogPath(root, logPath) {
+    if (!logPath)
+        return undefined;
+    const rel = relative(root, logPath).replace(/\\/gu, "/");
+    return rel === "" || rel.startsWith("../") ? logPath : rel;
+}
+function resolveAllowedWpInvocation(executionRoot, binary, args, extraEnv) {
+    const baseEnv = { ...process.env, ...extraEnv };
+    if (binary === "./bin/wp" || binary === "wp") {
+        const localLauncher = resolveRepoWpLauncher(executionRoot);
+        if (localLauncher !== null) {
+            return {
+                command: localLauncher,
+                args: [...args],
+                env: { ...baseEnv, PATH: `${executionRoot}/bin:${baseEnv["PATH"] ?? ""}` },
+            };
+        }
+        if (binary === "./bin/wp") {
+            return {
+                command: join(executionRoot, "bin", process.platform === "win32" ? "wp.cmd" : "wp"),
+                args: [...args],
+                env: { ...baseEnv, PATH: `${executionRoot}/bin:${baseEnv["PATH"] ?? ""}` },
+            };
+        }
+        const packagedLauncher = resolvePackagedWpLauncher();
+        return {
+            command: process.execPath,
+            args: [packagedLauncher, ...args],
+            env: baseEnv,
+        };
+    }
+    return {
+        command: binary,
+        args: [...args],
+        env: { ...baseEnv, PATH: `${executionRoot}/bin:${baseEnv["PATH"] ?? ""}` },
+    };
+}
+function resolveRepoWpLauncher(repoRoot) {
+    const launcher = join(repoRoot, "bin", process.platform === "win32" ? "wp.cmd" : "wp");
+    return existsSync(launcher) ? launcher : null;
+}
+function resolvePackagedWpLauncher() {
+    const launcher = resolvePackageAssetPreferred([
+        process.platform === "win32" ? "bin/wp.cmd" : "bin/wp",
+        "bin/wp",
+    ]);
+    if (!existsSync(launcher)) {
+        throw new Error(`Promotion gate failed: packaged wp launcher is unavailable at ${launcher}`);
+    }
+    return launcher;
+}
+function writeAllowedWpCommandLog(logRoot, command, invocation, result) {
+    mkdirSync(logRoot, { recursive: true });
+    const logPath = join(logRoot, `${Date.now()}-wp-command.log`);
+    writeFileSync(logPath, [
+        `command: ${command}`,
+        `invocation: ${invocation ? `${invocation.command} ${invocation.args.join(" ")}` : "not-run"}`,
+        `outcome: ${result.outcome}`,
+        `exit: ${result.exitCode ?? "null"}`,
+        `signal: ${result.signal ?? "null"}`,
+        `timeout_ms: ${ALLOWED_WP_COMMAND_TIMEOUT_MS}`,
+        `error: ${result.errorMessage ?? "none"}`,
+        "--- stderr ---",
+        result.stderr,
+        "--- stdout ---",
+        result.stdout,
+        "",
+    ].join("\n"), "utf8");
+    return logPath;
+}
+function errorCode(error) {
+    return "code" in error && typeof error.code === "string"
+        ? error.code
+        : null;
+}

package/dist/esm/blueprint/trust/dossier.d.ts

@@ -22,6 +22,7 @@ export type TrustPromotionGate = {
     command: string;
     expectedOutcome: string;
     lastResult: string;
+    defer: string;
 };
 export type TrustDossier = {
     readiness: TrustReadinessVerdict;

package/dist/esm/blueprint/trust/dossier.js

@@ -36,12 +36,7 @@ export function parseTrustDossier(markdown) {
         rejectedAlternatives,
         rationale,
     }), violations);
-    const gates = parseTable(requiredBlock(blocks, "Promotion Gates"), "Promotion Gates", ["Gate", "Command", "Expected outcome", "Last result"], ([gate = "", command = "", expectedOutcome = "", lastResult = ""]) => ({
-        gate,
-        command,
-        expectedOutcome,
-        lastResult,
-    }), violations);
+    const gates = parsePromotionGatesTable(requiredBlock(blocks, "Promotion Gates"), violations);
     const residualUnknowns = requiredBlock(blocks, "Residual Unknowns").trim();
     for (const [section, block] of blocks) {
         if (containsPlaceholder(block))
@@ -126,6 +121,45 @@ function parseTable(block, section, expectedHeader, build, violations) {
     }
     return result;
 }
+const PROMOTION_GATES_HEADER_LEGACY = ["Gate", "Command", "Expected outcome", "Last result"];
+const PROMOTION_GATES_HEADER_WITH_DEFER = [...PROMOTION_GATES_HEADER_LEGACY, "Defer"];
+// Bespoke (not parseTable()) so the header/row width can be EITHER the
+// legacy 4-column shape (every Promotion Gates table committed before this
+// fix, and the common case going forward) OR the 5-column shape with a
+// trailing Defer column (opt-in, see TrustPromotionGate.defer). A committed
+// blueprint's table must have every row match its own header's width -- a
+// row can't silently be short one cell.
+function parsePromotionGatesTable(block, violations) {
+    const section = "Promotion Gates";
+    const rows = block
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith("|") && line.endsWith("|"));
+    if (rows.length < 2) {
+        violations.push({ section, message: "missing markdown table" });
+        return [];
+    }
+    const header = splitRow(rows[0] ?? "").map((cell) => cell.toLowerCase());
+    const legacyHeader = PROMOTION_GATES_HEADER_LEGACY.map((cell) => cell.toLowerCase());
+    const deferHeader = PROMOTION_GATES_HEADER_WITH_DEFER.map((cell) => cell.toLowerCase());
+    const hasDeferColumn = header.join("|") === deferHeader.join("|");
+    if (!hasDeferColumn && header.join("|") !== legacyHeader.join("|")) {
+        violations.push({ section, message: `malformed table header for ${section}` });
+        return [];
+    }
+    const expectedWidth = hasDeferColumn ? 5 : 4;
+    const result = [];
+    for (const row of rows.slice(2)) {
+        const cells = splitRow(row);
+        if (cells.length !== expectedWidth) {
+            violations.push({ section, message: `malformed table row in ${section}` });
+            continue;
+        }
+        const [gate = "", command = "", expectedOutcome = "", lastResult = "", defer = ""] = cells;
+        result.push({ gate, command, expectedOutcome, lastResult, defer });
+    }
+    return result;
+}
 function requiredBlock(blocks, key) {
     const value = blocks.get(key);
     if (value === undefined)

package/dist/esm/blueprint/trust/gates.d.ts

@@ -1 +1,8 @@
 export declare function parseAllowedWpCommand(command: string): string[];
+/**
+ * Extracts the `--file` targets from an argv already parsed by
+ * `parseAllowedWpCommand`. Returns an empty array for any non-`wp test` argv.
+ * `parseAllowedWpCommand` guarantees `wp test` args are only `--file <target>`
+ * pairs, so no shell/flag validation is needed here.
+ */
+export declare function wpTestFileTargets(argv: readonly string[]): string[];

package/dist/esm/blueprint/trust/gates.js

@@ -54,3 +54,23 @@ export function parseAllowedWpCommand(command) {
     }
     throw new Error(`Unsupported promotion gate wp subcommand: ${sub ?? ""}`);
 }
+/**
+ * Extracts the `--file` targets from an argv already parsed by
+ * `parseAllowedWpCommand`. Returns an empty array for any non-`wp test` argv.
+ * `parseAllowedWpCommand` guarantees `wp test` args are only `--file <target>`
+ * pairs, so no shell/flag validation is needed here.
+ */
+export function wpTestFileTargets(argv) {
+    if (argv[1] !== "test")
+        return [];
+    const targets = [];
+    const rest = argv.slice(2);
+    for (let i = 0; i < rest.length; i++) {
+        const target = rest[i + 1];
+        if (rest[i] === "--file" && target !== undefined) {
+            targets.push(target);
+            i += 1;
+        }
+    }
+    return targets;
+}

package/dist/esm/blueprint/trust/promotion.d.ts

@@ -7,7 +7,15 @@ export type PromotionTrustInput = {
     markdown: string;
     now?: Date;
 };
+export type PromotionTrustProof = {
+    readonly file: string;
+    readonly sourceMarkdown: string;
+    readonly verifiedHead: string;
+    readonly trustedMarkdown: string;
+};
+export declare function preparePromotionTrustGate(input: PromotionTrustInput): PromotionTrustProof;
 export declare function applyPromotionTrustGate(input: PromotionTrustInput): string;
+export declare function assertPromotionTrustProofCurrent(input: Pick<PromotionTrustInput, "repoRoot" | "file" | "markdown">, proof: PromotionTrustProof): void;
 export declare function runPromotionCommand(repoRoot: string, command: string, deps?: {
     spawn?: typeof spawnSync;
 }): void;