@webpresso/agent-kit 3.1.30 → 3.3.0

package/dist/esm/cli/commands/init/scaffolders/file-transaction.js

@@ -0,0 +1,230 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { dirname } from "node:path";
+import { isProcessAlive } from "#cli/auto-update/install-lock.js";
+import { writeFileAtomicStrict } from "#shared-utils/write-json-file.js";
+const LOCK_TIMEOUT_MS = 5_000;
+const LOCK_POLL_MS = 25;
+const LOCK_STALE_MS = 30_000;
+/**
+ * Hard-age backstop: past this, a stale lock is reclaimed regardless of owner
+ * liveness. Prevents a recycled pid — or a `kill(pid,0)` that fails safe to
+ * "alive" (EPERM / unknown / cross-PID-namespace) — from wedging the lock
+ * forever. Mirrors `isInstallLockActive`, which likewise pairs liveness with an
+ * age bound rather than trusting liveness alone. Also serves as the reaper's own
+ * stale bound. Not a new deadline: it replaces the prior reaper-stale constant.
+ */
+const LOCK_STALE_HARD_MS = 5 * 60_000;
+const LOCK_OWNER_FILE = "owner";
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function isErrno(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+/** Directory age in ms, or `undefined` when the directory is gone (ENOENT). */
+function directoryAgeMs(path, now) {
+    try {
+        return now - statSync(path).mtime.getTime();
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT"))
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * Read the lock's owner record. The token is the full `"<pid>:<uuid>"` string
+ * (identical to what release compares); `pid` is its leading integer. Returns
+ * `undefined` for a missing/empty/unparseable owner — i.e. a crash that never
+ * finished writing the record, which is reclaimable once age-stale.
+ */
+function readLockOwner(lockPath) {
+    let token;
+    try {
+        token = readFileSync(`${lockPath}/${LOCK_OWNER_FILE}`, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const separator = token.indexOf(":");
+    if (separator <= 0)
+        return undefined;
+    const pid = Number(token.slice(0, separator));
+    if (!Number.isInteger(pid) || pid <= 0)
+        return undefined;
+    return { pid, token };
+}
+function tryAcquireDirectory(path) {
+    try {
+        mkdirSync(path);
+        return true;
+    }
+    catch (error) {
+        if (isErrno(error, "EEXIST"))
+            return false;
+        throw error;
+    }
+}
+/**
+ * Serialize stale reclaim across contenders. A crashed reaper holder is itself
+ * reclaimed race-free: exactly one waiter's atomic rename of the reaper carcass
+ * succeeds; losers observe ENOENT and retry the mkdir. This is what stops two
+ * reclaimers from deleting each other's fresh lock — the original lost-update.
+ *
+ * Release is owner-token-checked, exactly like the main lock: if a paused reaper
+ * holder is stolen and replaced while it sleeps, its release sees a mismatched
+ * owner token and no-ops, so it cannot delete the successor's reaper and let a
+ * third reclaimer in behind it.
+ */
+function acquireReaperLock(path, deadline, now) {
+    const ownerPath = `${path}/${LOCK_OWNER_FILE}`;
+    const ownerToken = `${process.pid}:${randomUUID()}`;
+    while (!tryAcquireDirectory(path)) {
+        const ageMs = directoryAgeMs(path, now());
+        if (ageMs !== undefined && ageMs >= LOCK_STALE_HARD_MS) {
+            const carcass = `${path}.stale-${process.pid}-${randomUUID()}`;
+            try {
+                renameSync(path, carcass);
+                rmSync(carcass, { recursive: true, force: true });
+            }
+            catch (error) {
+                // A concurrent waiter won the atomic rename; retry the mkdir.
+                if (!isErrno(error, "ENOENT"))
+                    throw error;
+            }
+            continue;
+        }
+        if (now() >= deadline) {
+            throw new Error(`Timed out waiting for stale host config lock reaper: ${path}`);
+        }
+        sleepSync(LOCK_POLL_MS);
+    }
+    try {
+        writeFileSync(ownerPath, ownerToken, "utf8");
+    }
+    catch (error) {
+        // Mirror the main lock: don't leave a reaper others must wait out on an
+        // owner-write failure.
+        rmSync(path, { recursive: true, force: true });
+        throw error;
+    }
+    return () => {
+        try {
+            if (readFileSync(ownerPath, "utf8") !== ownerToken)
+                return;
+            rmSync(path, { recursive: true, force: true });
+        }
+        catch (error) {
+            if (!isErrno(error, "ENOENT"))
+                throw error;
+        }
+    };
+}
+/**
+ * Remove a stale lock while holding the reaper, so at most one reclaimer acts at
+ * a time. Re-checks under the reaper: only a lock that is still age-stale AND
+ * whose owner is absent, dead, or past the hard-age bound is deleted. A live
+ * owner within the hard-age window is never reclaimed, so a slow-but-alive
+ * writer cannot lose its lock to a successor.
+ */
+function reclaimStaleLock(lockPath, reaperPath, deadline, now, isAlive, seams) {
+    const releaseReaper = acquireReaperLock(reaperPath, deadline, now);
+    try {
+        const ageMs = directoryAgeMs(lockPath, now());
+        if (ageMs === undefined || ageMs < LOCK_STALE_MS)
+            return;
+        const owner = readLockOwner(lockPath);
+        // Reclaim an absent owner record (a crash before the owner write) or a dead
+        // owner at the soft-stale age — recovering an abandoned lock fast is the whole
+        // point. A live owner waits for the hard-age backstop. The residual: a writer
+        // OS-suspended for 30s inside the two-statement mkdir/owner-write gap could be
+        // reclaimed and overlap; that window is a strict subset of the documented
+        // advisory-lock boundary (a suspended holder past the reclaim age), so it is
+        // accepted, not silently ignored.
+        const reclaimable = owner === undefined || !isAlive(owner.pid) || ageMs >= LOCK_STALE_HARD_MS;
+        if (!reclaimable)
+            return;
+        seams?.onBeforeReclaimDelete?.();
+        rmSync(lockPath, { recursive: true, force: true });
+    }
+    finally {
+        releaseReaper();
+    }
+}
+function acquireScaffolderFileLock(path, seams) {
+    const lockPath = `${path}.lock`;
+    const reaperPath = `${lockPath}.reaper`;
+    const ownerToken = `${process.pid}:${randomUUID()}`;
+    const ownerPath = `${lockPath}/${LOCK_OWNER_FILE}`;
+    const now = seams?.now ?? Date.now;
+    const isAlive = seams?.isAlive ?? isProcessAlive;
+    const deadline = now() + LOCK_TIMEOUT_MS;
+    for (;;) {
+        if (tryAcquireDirectory(lockPath)) {
+            try {
+                writeFileSync(ownerPath, ownerToken, "utf8");
+            }
+            catch (error) {
+                rmSync(lockPath, { recursive: true, force: true });
+                throw error;
+            }
+            return () => {
+                try {
+                    if (readFileSync(ownerPath, "utf8") !== ownerToken)
+                        return;
+                    rmSync(lockPath, { recursive: true, force: true });
+                }
+                catch (error) {
+                    if (!isErrno(error, "ENOENT"))
+                        throw error;
+                }
+            };
+        }
+        const ageMs = directoryAgeMs(lockPath, now());
+        if (ageMs !== undefined && ageMs >= LOCK_STALE_MS) {
+            // Reclaim may be a no-op (owner still alive within the hard-age window);
+            // fall through to the deadline check so a live holder can't spin us
+            // forever, then retry the mkdir on the next iteration.
+            reclaimStaleLock(lockPath, reaperPath, deadline, now, isAlive, seams);
+        }
+        if (now() >= deadline) {
+            throw new Error(`Timed out waiting for host config lock: ${path}`);
+        }
+        sleepSync(LOCK_POLL_MS);
+    }
+}
+/**
+ * Serialize a complete read/modify/write transaction for a host config file.
+ * These are local single-machine home-config locks (`~/.codex`, `~/.grok`), so
+ * owner-pid liveness is meaningful; this is not a shared-filesystem lock.
+ */
+export function withScaffolderFileLock(path, action, seams) {
+    mkdirSync(dirname(path), { recursive: true });
+    const release = acquireScaffolderFileLock(path, seams);
+    try {
+        return action();
+    }
+    finally {
+        release();
+    }
+}
+/**
+ * Serialize a text-file read/modify/write and install the replacement strictly
+ * atomically without weakening an existing file's permissions.
+ */
+export function updateScaffolderTextFile(path, transform) {
+    return withScaffolderFileLock(path, () => {
+        const existed = existsSync(path);
+        if (existed && lstatSync(path).isSymbolicLink()) {
+            throw new Error(`Refusing to replace symlinked host config: ${path}`);
+        }
+        const existing = existed ? readFileSync(path, "utf8") : "";
+        const next = transform(existing);
+        if (next === existing)
+            return "unchanged";
+        const mode = existed ? lstatSync(path).mode & 0o777 : 0o600;
+        writeFileAtomicStrict(path, next, { encoding: "utf8", mode });
+        return "written";
+    });
+}

package/dist/esm/cli/commands/init/scaffolders/grok-mcp/index.d.ts

@@ -0,0 +1,38 @@
+import type { MergeOptions } from "#cli/commands/init/merge";
+import { type WebpressoInstallProbe } from "#cli/commands/init/mcp-spec.js";
+export declare const GROK_CONFIG_RELATIVE_PATH = ".grok/config.toml";
+/** Render the managed `[mcp_servers.webpresso]` TOML block for Grok. */
+export declare function grokWebpressoMcpBlock(entryPath: string): string;
+export declare function upsertGrokWebpressoMcp(raw: string, entryPath: string): string;
+export interface EnsureGrokWebpressoMcpInput {
+    readonly options: MergeOptions;
+    /** Project root whose `.grok/config.toml` is managed. */
+    readonly repoRoot: string;
+    /** Test seam — override the resolved MCP entry path. */
+    readonly entryPath?: string;
+    /** Test seam — override `<repoRoot>/.grok/config.toml`. */
+    readonly configPath?: string;
+    /** Test seam — override the install-discovery probe. */
+    readonly probe?: WebpressoInstallProbe;
+}
+export type EnsureGrokWebpressoMcpResult = {
+    kind: "grok-webpresso-mcp-written";
+    path: string;
+    entryPath: string;
+} | {
+    kind: "grok-webpresso-mcp-unchanged";
+    path: string;
+    entryPath: string;
+} | {
+    kind: "grok-webpresso-mcp-ambiguous";
+    path: string;
+    entryPath: string;
+} | {
+    kind: "grok-webpresso-mcp-skipped-dry-run";
+    path: string;
+} | {
+    kind: "grok-webpresso-mcp-not-installed";
+    path: string;
+    checked: readonly string[];
+};
+export declare function ensureGrokWebpressoMcp(input: EnsureGrokWebpressoMcpInput): EnsureGrokWebpressoMcpResult;

package/dist/esm/cli/commands/init/scaffolders/grok-mcp/index.js

@@ -0,0 +1,73 @@
+/**
+ * `grok-mcp` scaffolder preset.
+ *
+ * Grok Build reads persistent MCP servers from a project-local
+ * `.grok/config.toml`. A project entry *replaces the user entry whole, by
+ * name*, so the managed `[mcp_servers.webpresso]` block owns the webpresso
+ * alias for the repo. The schema mirrors Codex TOML (command/args/env inline
+ * table); we reuse Codex's deterministic per-server upsert so unrelated
+ * `[mcp_servers.*]`, `[plugins]`, and `[permission]` sections are preserved.
+ *
+ * The launcher is resolved to an absolute `bin/wp` path at scaffold time via
+ * the shared {@link resolveWebpressoMcpEntry}; startup only spawns a verified
+ * binary. Env is projected from the one canonical {@link WEBPRESSO_MCP_SPEC}.
+ */
+import { join } from "node:path";
+import { updateScaffolderTextFile } from "#cli/commands/init/scaffolders/file-transaction.js";
+import { agentKitMcpLaunchCommand, resolveWebpressoMcpEntry, WEBPRESSO_MCP_SPEC, } from "#cli/commands/init/mcp-spec.js";
+import { commandMcpHeader, hasAmbiguousMcpServerDottedDefinition, hasManagedMcpServerTableConflict, upsertMcpServerBlock, } from "#cli/commands/init/scaffolders/codex-mcp/index.js";
+export const GROK_CONFIG_RELATIVE_PATH = ".grok/config.toml";
+function tomlString(value) {
+    return JSON.stringify(value);
+}
+function tomlStringArray(values) {
+    return `[${values.map(tomlString).join(", ")}]`;
+}
+function tomlEnvInlineTable(env) {
+    const pairs = Object.entries(env).map(([key, value]) => `${key} = ${tomlString(value)}`);
+    return pairs.length > 0 ? `{ ${pairs.join(", ")} }` : "{}";
+}
+/** Render the managed `[mcp_servers.webpresso]` TOML block for Grok. */
+export function grokWebpressoMcpBlock(entryPath) {
+    const launch = agentKitMcpLaunchCommand(entryPath);
+    const lines = [
+        commandMcpHeader(WEBPRESSO_MCP_SPEC.name),
+        `command = ${tomlString(launch.command)}`,
+        `args = ${tomlStringArray(launch.args)}`,
+        `env = ${tomlEnvInlineTable(WEBPRESSO_MCP_SPEC.env)}`,
+        "enabled = true",
+    ];
+    return `${lines.join("\n")}\n`;
+}
+export function upsertGrokWebpressoMcp(raw, entryPath) {
+    return upsertMcpServerBlock(raw, WEBPRESSO_MCP_SPEC.name, grokWebpressoMcpBlock(entryPath));
+}
+export function ensureGrokWebpressoMcp(input) {
+    const configPath = input.configPath ?? join(input.repoRoot, ".grok", "config.toml");
+    if (input.options.dryRun) {
+        return { kind: "grok-webpresso-mcp-skipped-dry-run", path: configPath };
+    }
+    const resolution = input.entryPath === undefined ? resolveWebpressoMcpEntry(input.probe) : undefined;
+    const entryPath = input.entryPath ?? resolution?.entryPath;
+    if (!entryPath) {
+        const checked = resolution?.checked ?? [];
+        return { kind: "grok-webpresso-mcp-not-installed", path: configPath, checked };
+    }
+    let ambiguous = false;
+    const outcome = updateScaffolderTextFile(configPath, (existing) => {
+        if (hasAmbiguousMcpServerDottedDefinition(existing, WEBPRESSO_MCP_SPEC.name) ||
+            hasManagedMcpServerTableConflict(existing, WEBPRESSO_MCP_SPEC.name)) {
+            ambiguous = true;
+            return existing;
+        }
+        return upsertGrokWebpressoMcp(existing, entryPath);
+    });
+    if (ambiguous) {
+        return { kind: "grok-webpresso-mcp-ambiguous", path: configPath, entryPath };
+    }
+    return {
+        kind: outcome === "written" ? "grok-webpresso-mcp-written" : "grok-webpresso-mcp-unchanged",
+        path: configPath,
+        entryPath,
+    };
+}

package/dist/esm/cli/commands/init/scaffolders/opencode-plugin/index.d.ts

@@ -1,11 +1,29 @@
 import type { MergeOptions } from "#cli/commands/init/merge";
+import { type WebpressoInstallProbe } from "#cli/commands/init/mcp-spec.js";
 export declare const STALE_OPENCODE_HOOK_PLUGIN_RELATIVE_PATH: string;
 export declare const OPENCODE_PLUGIN_SUPPORT_LEVEL = "native-npm";
 export declare const OPENCODE_PLUGIN_PACKAGE = "@webpresso/opencode-plugin";
+export declare const OPENCODE_MCP_SERVER_NAME: "webpresso";
+/**
+ * The canonical OpenCode `mcp.webpresso` entry. OpenCode's local-server shape
+ * folds the launcher and its args into a single `command` array, keys env
+ * under `environment`, and gates activation with `enabled`. Projected from the
+ * one canonical {@link WEBPRESSO_MCP_SPEC}.
+ */
+export declare function opencodeWebpressoMcpEntry(entryPath: string): {
+    type: "local";
+    command: string[];
+    enabled: true;
+    environment: Record<string, string>;
+};
 export interface EnsureOpenCodeWebpressoPluginInput {
     readonly repoRoot: string;
     readonly options: MergeOptions;
     readonly configPath?: string;
+    /** Test seam — override the resolved MCP entry path. */
+    readonly entryPath?: string;
+    /** Test seam — override the install-discovery probe. */
+    readonly probe?: WebpressoInstallProbe;
 }
 export type EnsureOpenCodeWebpressoPluginResult = {
     kind: "opencode-webpresso-plugin-written";
@@ -13,12 +31,15 @@ export type EnsureOpenCodeWebpressoPluginResult = {
     pluginPackage: string;
     removed: readonly string[];
     preserved: readonly string[];
+    /** Absolute wp launcher wired into `mcp.webpresso`, or null when unresolved. */
+    mcpEntryPath: string | null;
 } | {
     kind: "opencode-webpresso-plugin-unchanged";
     path: string;
     pluginPackage: string;
     removed: readonly string[];
     preserved: readonly string[];
+    mcpEntryPath: string | null;
 } | {
     kind: "opencode-webpresso-plugin-skipped-dry-run";
     path: string;