@webpresso/agent-kit 3.1.28 → 3.2.0

package/dist/esm/cli/commands/init/convergence-apply.js

@@ -0,0 +1,221 @@
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { convergeUnitFromTarget, deriveCommitAllowlist } from "./convergence.js";
+export { resolveUntrackedCollision } from "./untracked-collision.js";
+const GIT_TIMEOUT_MS = 15_000;
+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,
+        stdout: result.stdout.trim(),
+        stderr: result.stderr.trim(),
+    };
+}
+function lines(value) {
+    return value.length === 0 ? [] : value.split("\n").filter(Boolean).sort();
+}
+function readPorcelainStatus(repoRoot, gitPath) {
+    const result = spawnSync("git", [
+        "status",
+        "--porcelain=v1",
+        "-z",
+        "--untracked-files=all",
+        "--ignored=matching",
+        "--",
+        gitPath,
+    ], {
+        cwd: repoRoot,
+        encoding: "utf8",
+        timeout: GIT_TIMEOUT_MS,
+        maxBuffer: 1024 * 1024,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (result.status !== 0 || result.error)
+        return null;
+    const fields = result.stdout.split("\0");
+    const entries = [];
+    for (let index = 0; index < fields.length; index += 1) {
+        const record = fields[index];
+        if (!record || record.length < 4)
+            continue;
+        const code = record.slice(0, 2);
+        entries.push({ code, gitPath: record.slice(3) });
+        if (code.includes("R") || code.includes("C"))
+            index += 1;
+    }
+    return entries;
+}
+function isIgnored(repoRoot, gitPath) {
+    return git(repoRoot, ["check-ignore", "--no-index", "-q", "--", gitPath]).ok;
+}
+export function collectAppliedConvergeUnits(repoRoot, candidates) {
+    const units = [];
+    const seen = new Set();
+    for (const candidate of candidates) {
+        let candidateUnit;
+        try {
+            candidateUnit = convergeUnitFromTarget(repoRoot, candidate.targetPath, {
+                action: "modify",
+                scope: "repo-committed",
+                reason: candidate.reason,
+            });
+        }
+        catch {
+            continue;
+        }
+        const statuses = readPorcelainStatus(repoRoot, candidateUnit.gitPath);
+        if (!statuses)
+            continue;
+        for (const { code, gitPath } of statuses) {
+            if (seen.has(gitPath))
+                continue;
+            let unit;
+            try {
+                unit = convergeUnitFromTarget(repoRoot, join(repoRoot, gitPath), {
+                    action: code === "??" || code === "!!" || code.includes("A")
+                        ? "create"
+                        : code.includes("D")
+                            ? "delete"
+                            : "modify",
+                    scope: "repo-committed",
+                    reason: candidate.reason,
+                });
+            }
+            catch {
+                continue;
+            }
+            units.push({
+                ...unit,
+                scope: code === "!!" || (code === "??" && isIgnored(repoRoot, gitPath))
+                    ? "repo-ignored"
+                    : "repo-committed",
+            });
+            seen.add(gitPath);
+        }
+    }
+    return units;
+}
+export function authorConvergenceCommit(options) {
+    const allowlist = deriveCommitAllowlist(options.appliedUnits);
+    if (options.isCi)
+        return { status: "skipped-ci", ok: true, allowlist };
+    if (allowlist.length === 0)
+        return { status: "no-change", ok: true, allowlist };
+    const before = git(options.repoRoot, ["rev-parse", "--verify", "HEAD"]);
+    if (!before.ok) {
+        return { status: "failed", ok: false, allowlist, error: before.stderr || "Missing HEAD." };
+    }
+    const add = git(options.repoRoot, ["add", "--", ...allowlist]);
+    if (!add.ok) {
+        return { status: "failed", ok: false, allowlist, error: add.stderr || "git add failed." };
+    }
+    const staged = git(options.repoRoot, ["diff", "--cached", "--name-only"]);
+    if (!staged.ok) {
+        return { status: "failed", ok: false, allowlist, error: staged.stderr || "git diff failed." };
+    }
+    if (lines(staged.stdout).length === 0) {
+        return { status: "no-change", ok: true, allowlist };
+    }
+    const commit = git(options.repoRoot, ["commit", "-m", options.message]);
+    if (!commit.ok) {
+        return {
+            status: "failed",
+            ok: false,
+            allowlist,
+            error: commit.stderr || commit.stdout || "git commit failed; hook changes were preserved.",
+        };
+    }
+    const committedHead = git(options.repoRoot, ["rev-parse", "--verify", "HEAD"]);
+    if (!committedHead.ok) {
+        return {
+            status: "failed",
+            ok: false,
+            allowlist,
+            error: committedHead.stderr || "Unable to validate the authored commit.",
+        };
+    }
+    const committedParent = git(options.repoRoot, [
+        "rev-parse",
+        "--verify",
+        `${committedHead.stdout}^`,
+    ]);
+    if (!committedParent.ok || committedParent.stdout !== before.stdout) {
+        return {
+            status: "failed",
+            ok: false,
+            allowlist,
+            commit: committedHead.stdout,
+            error: "The observed commit does not directly follow the recorded HEAD; no rollback was attempted. Inspect Git history and recover manually.",
+        };
+    }
+    const committedPathsResult = git(options.repoRoot, [
+        "diff-tree",
+        "--root",
+        "--no-commit-id",
+        "--name-only",
+        "-r",
+        committedHead.stdout,
+    ]);
+    if (!committedPathsResult.ok) {
+        return {
+            status: "failed",
+            ok: false,
+            allowlist,
+            commit: committedHead.stdout,
+            error: committedPathsResult.stderr || "Unable to inspect the authored commit.",
+        };
+    }
+    const committedPaths = lines(committedPathsResult.stdout);
+    const allowed = new Set(allowlist);
+    const committed = new Set(committedPaths);
+    const unexpectedPaths = committedPaths.filter((path) => !allowed.has(path));
+    const missingPaths = allowlist.filter((path) => !committed.has(path));
+    if (unexpectedPaths.length === 0 && missingPaths.length === 0) {
+        return {
+            status: "committed",
+            ok: true,
+            allowlist,
+            commit: committedHead.stdout,
+        };
+    }
+    const currentHead = git(options.repoRoot, ["rev-parse", "--verify", "HEAD"]);
+    if (!currentHead.ok || currentHead.stdout !== committedHead.stdout) {
+        return {
+            status: "failed",
+            ok: false,
+            allowlist,
+            commit: committedHead.stdout,
+            unexpectedPaths,
+            missingPaths,
+            error: "The setup-authored commit changed before validation; no rollback was attempted. Inspect Git history and recover manually.",
+        };
+    }
+    const rollback = git(options.repoRoot, ["reset", "--mixed", before.stdout]);
+    if (!rollback.ok) {
+        return {
+            status: "failed",
+            ok: false,
+            allowlist,
+            commit: committedHead.stdout,
+            unexpectedPaths,
+            missingPaths,
+            error: rollback.stderr || "Failed to undo the path-invalid setup commit.",
+        };
+    }
+    return {
+        status: "rolled-back",
+        ok: false,
+        allowlist,
+        commit: committedHead.stdout,
+        unexpectedPaths,
+        missingPaths,
+        error: `A commit hook changed setup commit scope (unexpected: ${unexpectedPaths.join(", ") || "none"}; missing: ${missingPaths.join(", ") || "none"}). ` +
+            "The setup commit was undone and all worktree changes were retained. Update the hook so it does not stage unrelated paths, then stage or discard those paths and rerun wp setup.",
+    };
+}

package/dist/esm/cli/commands/init/convergence-state.d.ts

@@ -0,0 +1,13 @@
+export declare const CONVERGENCE_STATE_SCHEMA_VERSION: 1;
+export declare const CONVERGENCE_STATE_PATH = ".webpresso/converged.json";
+export interface ConvergenceState {
+    readonly schemaVersion: typeof CONVERGENCE_STATE_SCHEMA_VERSION;
+    readonly agentKitVersion: string;
+    readonly host: string;
+    readonly sentinels: Readonly<Record<string, string>>;
+    readonly writtenAt: string;
+}
+export declare function parseConvergenceState(value: unknown): ConvergenceState | null;
+export declare function readConvergenceState(repoRoot: string): ConvergenceState | null;
+export declare function isConvergenceStateCurrent(state: ConvergenceState | null, expected: Pick<ConvergenceState, "agentKitVersion" | "host" | "sentinels">): boolean;
+export declare function writeConvergenceState(repoRoot: string, state: ConvergenceState): void;

package/dist/esm/cli/commands/init/convergence-state.js

@@ -0,0 +1,54 @@
+import { mkdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { writeJsonFile } from "#shared-utils/write-json-file.js";
+export const CONVERGENCE_STATE_SCHEMA_VERSION = 1;
+export const CONVERGENCE_STATE_PATH = ".webpresso/converged.json";
+function isStringRecord(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        Object.values(value).every((entry) => typeof entry === "string"));
+}
+export function parseConvergenceState(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    if (record.schemaVersion !== CONVERGENCE_STATE_SCHEMA_VERSION ||
+        typeof record.agentKitVersion !== "string" ||
+        typeof record.host !== "string" ||
+        typeof record.writtenAt !== "string" ||
+        !isStringRecord(record.sentinels)) {
+        return null;
+    }
+    return {
+        schemaVersion: CONVERGENCE_STATE_SCHEMA_VERSION,
+        agentKitVersion: record.agentKitVersion,
+        host: record.host,
+        sentinels: record.sentinels,
+        writtenAt: record.writtenAt,
+    };
+}
+export function readConvergenceState(repoRoot) {
+    try {
+        return parseConvergenceState(JSON.parse(readFileSync(join(resolve(repoRoot), CONVERGENCE_STATE_PATH), "utf8")));
+    }
+    catch {
+        return null;
+    }
+}
+export function isConvergenceStateCurrent(state, expected) {
+    if (!state ||
+        state.agentKitVersion !== expected.agentKitVersion ||
+        state.host !== expected.host) {
+        return false;
+    }
+    return Object.entries(expected.sentinels).every(([name, value]) => state.sentinels[name] === value);
+}
+export function writeConvergenceState(repoRoot, state) {
+    const statePath = join(resolve(repoRoot), CONVERGENCE_STATE_PATH);
+    mkdirSync(dirname(statePath), { recursive: true });
+    writeJsonFile(statePath, state, {
+        atomic: true,
+        indent: 2,
+    });
+}

package/dist/esm/cli/commands/init/convergence.d.ts

@@ -0,0 +1,23 @@
+import type { WriteAction } from "./write-plan.js";
+export declare const CONVERGE_SCOPES: readonly ["repo-committed", "repo-ignored"];
+export type ConvergeScope = (typeof CONVERGE_SCOPES)[number];
+export interface ConvergeUnit {
+    readonly repoRoot: string;
+    readonly targetPath: string;
+    readonly gitPath: string;
+    readonly action: WriteAction;
+    readonly scope: ConvergeScope;
+    readonly reason: string;
+}
+export interface CreateConvergeUnitInput {
+    readonly repoRoot: string;
+    readonly targetPath: string;
+    readonly gitPath: string;
+    readonly action: WriteAction;
+    readonly scope: ConvergeScope;
+    readonly reason: string;
+}
+export declare function createConvergeUnit(input: CreateConvergeUnitInput): ConvergeUnit;
+export declare function convergeUnitFromTarget(repoRoot: string, targetPath: string, input: Pick<CreateConvergeUnitInput, "action" | "scope" | "reason">): ConvergeUnit;
+/** Applied units are the sole authority for authored commit scope. */
+export declare function deriveCommitAllowlist(appliedUnits: readonly ConvergeUnit[]): string[];

package/dist/esm/cli/commands/init/convergence.js

@@ -0,0 +1,57 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+export const CONVERGE_SCOPES = ["repo-committed", "repo-ignored"];
+function normalizeGitPath(value) {
+    return value.replaceAll("\\", "/").replace(/^\.\//u, "");
+}
+function assertInsideRepo(repoRoot, targetPath) {
+    const relativePath = relative(repoRoot, targetPath);
+    if (relativePath.length === 0 ||
+        relativePath === ".." ||
+        relativePath.startsWith(`..${sep}`) ||
+        isAbsolute(relativePath)) {
+        throw new Error(`Convergence target must be a file inside the repository: ${targetPath}`);
+    }
+    return normalizeGitPath(relativePath);
+}
+export function createConvergeUnit(input) {
+    if (!isAbsolute(input.repoRoot)) {
+        throw new Error(`Convergence repo root must be absolute: ${input.repoRoot}`);
+    }
+    if (!isAbsolute(input.targetPath)) {
+        throw new Error(`Convergence target must be absolute: ${input.targetPath}`);
+    }
+    if (!CONVERGE_SCOPES.includes(input.scope)) {
+        throw new Error(`Unsupported convergence scope: ${input.scope}`);
+    }
+    const repoRoot = resolve(input.repoRoot);
+    const targetPath = resolve(input.targetPath);
+    const derivedGitPath = assertInsideRepo(repoRoot, targetPath);
+    const gitPath = normalizeGitPath(input.gitPath);
+    if (gitPath.length === 0 || isAbsolute(gitPath) || gitPath !== derivedGitPath) {
+        throw new Error(`Convergence git path must match its repo-anchored target: expected ${derivedGitPath}, received ${input.gitPath}`);
+    }
+    return {
+        repoRoot,
+        targetPath,
+        gitPath,
+        action: input.action,
+        scope: input.scope,
+        reason: input.reason,
+    };
+}
+export function convergeUnitFromTarget(repoRoot, targetPath, input) {
+    const anchoredRoot = resolve(repoRoot);
+    const anchoredTarget = resolve(targetPath);
+    return createConvergeUnit({
+        ...input,
+        repoRoot: anchoredRoot,
+        targetPath: anchoredTarget,
+        gitPath: assertInsideRepo(anchoredRoot, anchoredTarget),
+    });
+}
+/** Applied units are the sole authority for authored commit scope. */
+export function deriveCommitAllowlist(appliedUnits) {
+    return [
+        ...new Set(appliedUnits.filter((unit) => unit.scope === "repo-committed").map((unit) => unit.gitPath)),
+    ].sort();
+}

package/dist/esm/cli/commands/init/git-convergence.d.ts

@@ -0,0 +1,19 @@
+export type GitConvergenceStatus = "ready" | "fast-forwarded" | "not-git" | "unborn" | "detached" | "dirty" | "diverged" | "failed";
+export interface GitConvergenceResult {
+    readonly status: GitConvergenceStatus;
+    readonly ok: boolean;
+    readonly repoRoot: string;
+    readonly head?: string;
+    readonly upstream?: string;
+    readonly shouldReplan: boolean;
+    readonly canCommit: boolean;
+    readonly warnings: readonly string[];
+    readonly error?: string;
+}
+export interface PrepareGitConvergenceOptions {
+    readonly repoRoot: string;
+    readonly isCi?: boolean;
+    readonly fetchTimeoutMs?: number;
+    readonly gitCommand?: string;
+}
+export declare function prepareRepositoryForConvergence(options: PrepareGitConvergenceOptions): GitConvergenceResult;

package/dist/esm/cli/commands/init/git-convergence.js

@@ -0,0 +1,168 @@
+import { spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+const DEFAULT_GIT_TIMEOUT_MS = 5_000;
+const GIT_MAX_BUFFER = 1024 * 1024;
+function git(repoRoot, args, timeoutMs, command = "git") {
+    const result = spawnSync(command, [...args], {
+        cwd: repoRoot,
+        encoding: "utf8",
+        timeout: timeoutMs,
+        maxBuffer: GIT_MAX_BUFFER,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    return {
+        ok: result.status === 0 && !result.error,
+        stdout: result.stdout.trim(),
+        stderr: result.stderr.trim(),
+        timedOut: result.error !== undefined && "code" in result.error && result.error.code === "ETIMEDOUT",
+    };
+}
+function failed(repoRoot, status, error) {
+    return {
+        status,
+        ok: false,
+        repoRoot,
+        shouldReplan: false,
+        canCommit: false,
+        warnings: [],
+        error,
+    };
+}
+function parseAheadBehindCounts(stdout) {
+    const parts = stdout.trim().split(/\s+/u);
+    if (parts.length !== 2)
+        return null;
+    if (!parts.every((part) => /^\d+$/u.test(part)))
+        return null;
+    const [ahead, behind] = parts.map((part) => Number.parseInt(part, 10));
+    if (ahead === undefined ||
+        behind === undefined ||
+        !Number.isSafeInteger(ahead) ||
+        !Number.isSafeInteger(behind) ||
+        ahead < 0 ||
+        behind < 0) {
+        return null;
+    }
+    return { ahead, behind };
+}
+export function prepareRepositoryForConvergence(options) {
+    const repoRoot = resolve(options.repoRoot);
+    const timeoutMs = options.fetchTimeoutMs ?? DEFAULT_GIT_TIMEOUT_MS;
+    const gitCommand = options.gitCommand ?? "git";
+    const runGit = (args) => git(repoRoot, args, timeoutMs, gitCommand);
+    const inside = runGit(["rev-parse", "--is-inside-work-tree"]);
+    if (!inside.ok || inside.stdout !== "true") {
+        return failed(repoRoot, "not-git", "Repository convergence requires a Git worktree.");
+    }
+    const headResult = runGit(["rev-parse", "--verify", "HEAD"]);
+    if (!headResult.ok) {
+        return failed(repoRoot, "unborn", "Repository convergence requires an existing HEAD commit.");
+    }
+    const head = headResult.stdout;
+    const branch = runGit(["symbolic-ref", "--quiet", "--short", "HEAD"]);
+    const detached = !branch.ok;
+    if (detached && !options.isCi) {
+        return failed(repoRoot, "detached", "Repository convergence refuses a detached HEAD.");
+    }
+    const trackedStatus = runGit(["status", "--porcelain=v1", "--untracked-files=no"]);
+    if (!trackedStatus.ok) {
+        return failed(repoRoot, "failed", trackedStatus.stderr || "Unable to inspect Git status.");
+    }
+    if (trackedStatus.stdout.length > 0) {
+        return failed(repoRoot, "dirty", "Repository convergence requires a clean tracked index and worktree.");
+    }
+    const warnings = [];
+    if (detached) {
+        warnings.push("Detached HEAD accepted in CI; skipped upstream update and authored commit.");
+        return {
+            status: "ready",
+            ok: true,
+            repoRoot,
+            head,
+            shouldReplan: false,
+            canCommit: false,
+            warnings,
+        };
+    }
+    const upstreamResult = runGit(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"]);
+    if (!upstreamResult.ok) {
+        warnings.push("No upstream is configured; skipped fetch and fast-forward.");
+        return {
+            status: "ready",
+            ok: true,
+            repoRoot,
+            head,
+            shouldReplan: false,
+            canCommit: !options.isCi,
+            warnings,
+        };
+    }
+    const upstream = upstreamResult.stdout;
+    const remoteSeparator = upstream.indexOf("/");
+    const remote = remoteSeparator === -1 ? upstream : upstream.slice(0, remoteSeparator);
+    const fetch = runGit(["fetch", "--quiet", "--no-tags", remote]);
+    if (!fetch.ok) {
+        warnings.push(fetch.timedOut
+            ? `Upstream fetch timed out after ${timeoutMs}ms; continuing from local refs.`
+            : `Upstream fetch unavailable; continuing from local refs${fetch.stderr ? `: ${fetch.stderr}` : "."}`);
+    }
+    const counts = runGit(["rev-list", "--left-right", "--count", `HEAD...${upstream}`]);
+    if (!counts.ok) {
+        return {
+            ...failed(repoRoot, "failed", counts.stderr || "Unable to compare HEAD with upstream."),
+            head,
+            upstream,
+            warnings,
+        };
+    }
+    const parsedCounts = parseAheadBehindCounts(counts.stdout);
+    if (!parsedCounts) {
+        return {
+            ...failed(repoRoot, "failed", `Unable to parse HEAD/upstream divergence counts from git rev-list output: ${JSON.stringify(counts.stdout)}.`),
+            head,
+            upstream,
+            warnings,
+        };
+    }
+    const { ahead, behind } = parsedCounts;
+    if (ahead > 0 && behind > 0) {
+        return {
+            ...failed(repoRoot, "diverged", `HEAD has diverged from ${upstream}; reconcile it manually.`),
+            head,
+            upstream,
+            warnings,
+        };
+    }
+    if (behind > 0) {
+        const merge = runGit(["merge", "--ff-only", upstream]);
+        if (!merge.ok) {
+            return {
+                ...failed(repoRoot, "failed", merge.stderr || `Unable to fast-forward from ${upstream}.`),
+                head,
+                upstream,
+                warnings,
+            };
+        }
+        const nextHead = runGit(["rev-parse", "--verify", "HEAD"]);
+        return {
+            status: "fast-forwarded",
+            ok: true,
+            repoRoot,
+            head: nextHead.ok ? nextHead.stdout : undefined,
+            upstream,
+            shouldReplan: true,
+            canCommit: !options.isCi,
+            warnings,
+        };
+    }
+    return {
+        status: "ready",
+        ok: true,
+        repoRoot,
+        head,
+        upstream,
+        shouldReplan: false,
+        canCommit: !options.isCi,
+        warnings,
+    };
+}

package/dist/esm/cli/commands/init/gitignore-patcher.js

@@ -55,8 +55,10 @@ export const GENERATED_PATHS_BLOCK = {
         ".runtime/",
         ".opencode/",
         ".codex/",
+        ".grok/",
         "_worktrees/",
         ".webpresso/hooks-manifest.json",
+        ".webpresso/converged.json",
         ".claude/settings.json",
         ".claude/settings.local.json",
         ".claude/agents/",

package/dist/esm/cli/commands/init/grok-privacy-smoke.d.ts

@@ -0,0 +1,52 @@
+export interface GrokPrivacyFlow {
+    readonly hostname: string;
+    readonly method: string;
+    readonly requestCount: number;
+    readonly requestBytes: number;
+    readonly responseBytes: number;
+}
+export interface GrokPrivacyBaseline {
+    readonly schemaVersion: 1;
+    readonly cliVersion: string;
+    readonly authMode: "local-session";
+    readonly transportVarianceBytes: number;
+    readonly maxAggregateRequestBytes: number;
+    readonly flows: readonly {
+        readonly hostname: string;
+        readonly method: string;
+        readonly maxRequestCount: number;
+        readonly maxRequestBytes: number;
+    }[];
+}
+export interface GrokPrivacyEvidence {
+    readonly schemaVersion: 1;
+    readonly host: "grok";
+    readonly cliVersion: string;
+    readonly authMode: "local-session";
+    readonly reviewedSha: string;
+    readonly traceSha256: string;
+    readonly sentinelObserved: false;
+    readonly native: {
+        readonly hooksTrusted: true;
+        readonly hookDenial: true;
+        readonly inspect: true;
+        readonly mcpList: true;
+        readonly mcpDoctor: true;
+        readonly localInference: true;
+    };
+    readonly flows: readonly GrokPrivacyFlow[];
+}
+export declare function buildGrokPrivacyEvidence(input: {
+    baseline: GrokPrivacyBaseline;
+    cliVersion: string;
+    reviewedSha: string;
+    sentinelObserved: boolean;
+    hooksTrusted: boolean;
+    hookDenialPassed: boolean;
+    inspectPassed: boolean;
+    mcpListPassed: boolean;
+    mcpDoctorPassed: boolean;
+    localInferencePassed: boolean;
+    flows: readonly GrokPrivacyFlow[];
+}): GrokPrivacyEvidence;
+export declare function serializeGrokPrivacyEvidence(evidence: GrokPrivacyEvidence): string;