@pugi/cli 0.1.0-beta.9 → 0.1.0-beta.91

package/dist/skills/bundled/verify.js

@@ -0,0 +1,439 @@
+/**
+ * `pugi verify` — post-execution claim verification.
+ *
+ * Bundled skill, batch 2 (backlog). The operator runs `pugi verify
+ * <claims.json>` after an agent or batch reports "done"; the skill
+ * walks the claim list, runs each assertion, and prints a
+ * pass/fail ledger. This is the anti-fake-dispatch primitive — Hiroshi
+ * can promise "tic-tac-toe shipped, snake.html written, tests added"
+ * but `pugi verify` is the only thing that can prove it.
+ *
+ * # Claim shapes
+ *
+ *  - `file_exists` — `target` is a path. Pass when the file exists +
+ *                     is non-empty (a 0-byte placeholder is a fake).
+ *  - `grep_match`  — `target` is a path, `expected` is a literal
+ *                     substring OR `/regex/flags`. Pass when at least
+ *                     one match is found.
+ *  - `cmd_zero_exit`— `target` is a command line (one program + args,
+ *                     no shell metacharacters). Pass when the process
+ *                     exits 0 inside a 30-second wall clock.
+ *
+ * # Output
+ *
+ *  - Human-readable table with `[ok]` / `[FAIL]` per claim.
+ *  - JSON envelope on `--json`.
+ *
+ * # Exit codes
+ *
+ *  - 0 — every claim passed (or `--strict` was off + only soft fails).
+ *  - 1 — at least one claim failed.
+ *  - 2 — CLI / input error (missing file, bad JSON, malformed claim).
+ *
+ * # Strict mode
+ *
+ * `--strict` (default ON) treats ANY failure as the exit-code-1 trigger.
+ * `--no-strict` flips to "report-only" — useful when the operator wants
+ * the ledger printed for analysis but is iterating on a known-broken
+ * snapshot and does not want the wrapper script to bail.
+ *
+ * # Provenance
+ *
+ * Inspired by the external bundled-skills pattern (intel from
+ * leak-research memos, independent implementation TS). No upstream code reused.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+const DEFAULT_CMD_TIMEOUT_MS = 30_000;
+function parseFlags(args) {
+    const flags = {
+        json: false,
+        strict: true,
+        claimsPath: null,
+    };
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === undefined)
+            continue;
+        if (arg === '--json') {
+            flags.json = true;
+            continue;
+        }
+        if (arg === '--strict') {
+            flags.strict = true;
+            continue;
+        }
+        if (arg === '--no-strict') {
+            flags.strict = false;
+            continue;
+        }
+        if (arg === '--help' || arg === '-h') {
+            return { flags, error: 'help' };
+        }
+        if (arg.startsWith('--')) {
+            return { flags, error: `unknown flag: ${arg}` };
+        }
+        if (flags.claimsPath === null) {
+            flags.claimsPath = arg;
+            continue;
+        }
+        return { flags, error: `unexpected positional argument: ${arg}` };
+    }
+    return { flags, error: null };
+}
+/**
+ * Parse a JSON document into a typed claim list. The grammar is
+ * intentionally strict — any unknown `kind`, missing field, or extra
+ * top-level type produces a parse error so the operator does not get
+ * a silent green check for a malformed claim.
+ *
+ * Public for test coverage.
+ */
+export function parseClaimsDocument(raw) {
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `invalid JSON: ${message}` };
+    }
+    const items = Array.isArray(json)
+        ? json
+        : isPlainObject(json) && Array.isArray(json.claims)
+            ? json.claims
+            : [];
+    if (!Array.isArray(items)) {
+        return { ok: false, error: 'top-level value must be an array or { claims: [...] }' };
+    }
+    if (items.length === 0) {
+        return { ok: false, error: 'claims list is empty' };
+    }
+    const claims = [];
+    for (let i = 0; i < items.length; i += 1) {
+        const item = items[i];
+        if (!isPlainObject(item)) {
+            return { ok: false, error: `claims[${i}] must be an object` };
+        }
+        const claim = item.claim;
+        const kind = item.kind;
+        const target = item.target;
+        const expected = item.expected;
+        if (typeof claim !== 'string' || claim.length === 0) {
+            return { ok: false, error: `claims[${i}].claim must be a non-empty string` };
+        }
+        if (kind !== 'file_exists' &&
+            kind !== 'grep_match' &&
+            kind !== 'cmd_zero_exit') {
+            return {
+                ok: false,
+                error: `claims[${i}].kind must be one of file_exists | grep_match | cmd_zero_exit`,
+            };
+        }
+        if (typeof target !== 'string' || target.length === 0) {
+            return { ok: false, error: `claims[${i}].target must be a non-empty string` };
+        }
+        if (kind === 'grep_match') {
+            if (typeof expected !== 'string' || expected.length === 0) {
+                return {
+                    ok: false,
+                    error: `claims[${i}].expected required for grep_match (substring or /regex/)`,
+                };
+            }
+        }
+        if (kind === 'cmd_zero_exit') {
+            // Reject shell metacharacters so we cannot accidentally
+            // open an injection seam — the runner uses spawnSync without a
+            // shell, but a heavy quote in the target string still indicates
+            // operator intent we should refuse.
+            if (/[;&|`$<>]/.test(target)) {
+                return {
+                    ok: false,
+                    error: `claims[${i}].target rejects shell metacharacters (; & | $\` < >)`,
+                };
+            }
+        }
+        const built = {
+            claim,
+            kind,
+            target,
+            ...(typeof expected === 'string' ? { expected } : {}),
+        };
+        claims.push(built);
+    }
+    return { ok: true, claims };
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Resolve a claim target to an absolute path. Public so tests can pin
+ * the resolution without spinning up a fake filesystem.
+ */
+export function resolveTargetPath(target, cwd) {
+    return isAbsolute(target) ? target : resolve(cwd, target);
+}
+function evaluateFileExists(claim, resolvePath) {
+    const path = resolvePath(claim.target);
+    if (!existsSync(path)) {
+        return { ok: false, detail: `missing: ${path}` };
+    }
+    try {
+        const stats = statSync(path);
+        if (!stats.isFile()) {
+            return { ok: false, detail: `not a regular file: ${path}` };
+        }
+        if (stats.size === 0) {
+            return { ok: false, detail: `empty file (0 bytes): ${path}` };
+        }
+        return { ok: true, detail: `present, ${stats.size} bytes: ${path}` };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, detail: `stat failed for ${path}: ${message}` };
+    }
+}
+function evaluateGrepMatch(claim, resolvePath) {
+    const path = resolvePath(claim.target);
+    if (!existsSync(path)) {
+        return { ok: false, detail: `missing: ${path}` };
+    }
+    if (claim.expected === undefined) {
+        return { ok: false, detail: `expected pattern is required for grep_match` };
+    }
+    let body;
+    try {
+        body = readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, detail: `read failed for ${path}: ${message}` };
+    }
+    const regex = parseExpectedPattern(claim.expected);
+    if (regex === null) {
+        return {
+            ok: false,
+            detail: `invalid expected pattern: ${claim.expected}`,
+        };
+    }
+    if (typeof regex === 'string') {
+        return body.includes(regex)
+            ? { ok: true, detail: `substring matched in ${path}` }
+            : { ok: false, detail: `substring '${regex}' not found in ${path}` };
+    }
+    return regex.test(body)
+        ? { ok: true, detail: `regex matched in ${path}` }
+        : { ok: false, detail: `regex ${String(regex)} not found in ${path}` };
+}
+/**
+ * Parse the `expected` field. `/pattern/flags` → RegExp; anything else
+ * is a literal substring. Returns `null` on a malformed regex syntax.
+ * Public so the test suite can exercise the surface directly.
+ */
+export function parseExpectedPattern(expected) {
+    const trimmed = expected;
+    // Detect /pattern/flags shape; the pattern must end with the same
+    // slash and only allow a small flag set so a bare path with slashes
+    // does NOT get mistaken for a regex.
+    if (trimmed.length >= 2 &&
+        trimmed.startsWith('/') &&
+        /\/[gimsuy]*$/.test(trimmed.slice(1))) {
+        const lastSlash = trimmed.lastIndexOf('/');
+        const pattern = trimmed.slice(1, lastSlash);
+        const flags = trimmed.slice(lastSlash + 1);
+        try {
+            return new RegExp(pattern, flags);
+        }
+        catch {
+            return null;
+        }
+    }
+    return trimmed;
+}
+function evaluateCmdZeroExit(claim, ctx) {
+    const tokens = tokenizeCommand(claim.target);
+    if (tokens.length === 0) {
+        return { ok: false, detail: 'empty command' };
+    }
+    const runCommand = ctx.runCommand ?? defaultRunCommand;
+    const result = runCommand(tokens, {
+        cwd: ctx.cwd,
+        env: ctx.env,
+        timeoutMs: DEFAULT_CMD_TIMEOUT_MS,
+    });
+    if (result.exitCode === 0) {
+        return { ok: true, detail: `exit 0 (${tokens.join(' ')})` };
+    }
+    const head = (result.stderr || result.stdout).split('\n', 1)[0] ?? '';
+    return {
+        ok: false,
+        detail: `exit ${result.exitCode ?? 'null'} (${tokens.join(' ')}) — ${head.slice(0, 200)}`,
+    };
+}
+/**
+ * Naive whitespace + quoted-string tokenizer. Sufficient for the
+ * cmd_zero_exit surface (operators commonly hand us `pnpm typecheck`
+ * or `node -e "..."`); rejects shell metas at parse time so the
+ * lexer never needs to handle pipes or redirects.
+ *
+ * Public for test coverage of edge cases like quoted args with spaces.
+ */
+export function tokenizeCommand(input) {
+    const out = [];
+    let cur = '';
+    let quote = null;
+    for (let i = 0; i < input.length; i += 1) {
+        const ch = input.charAt(i);
+        if (quote !== null) {
+            if (ch === quote) {
+                quote = null;
+                continue;
+            }
+            cur += ch;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            continue;
+        }
+        if (ch === ' ' || ch === '\t') {
+            if (cur !== '') {
+                out.push(cur);
+                cur = '';
+            }
+            continue;
+        }
+        cur += ch;
+    }
+    if (cur !== '')
+        out.push(cur);
+    return out;
+}
+function defaultRunCommand(args, ctx) {
+    const [bin, ...rest] = args;
+    if (bin === undefined) {
+        return { exitCode: null, stdout: '', stderr: 'empty command' };
+    }
+    try {
+        const result = spawnSync(bin, rest, {
+            cwd: ctx.cwd,
+            env: ctx.env,
+            encoding: 'utf8',
+            timeout: ctx.timeoutMs,
+            maxBuffer: 8 * 1024 * 1024,
+        });
+        return {
+            exitCode: result.status,
+            stdout: result.stdout ?? '',
+            stderr: result.stderr ?? '',
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { exitCode: null, stdout: '', stderr: message };
+    }
+}
+function renderHumanReport(result, strict) {
+    const lines = [];
+    lines.push(`pugi verify — ${result.results.length} claim(s)`);
+    lines.push(`passed: ${result.passed} failed: ${result.failed.length} strict: ${strict ? 'on' : 'off'}`);
+    lines.push('');
+    for (const r of result.results) {
+        const tag = r.ok ? '[ok] ' : '[FAIL]';
+        lines.push(`${tag} ${r.claim.claim} (${r.claim.kind})`);
+        lines.push(`       ${r.detail}`);
+    }
+    return lines.join('\n');
+}
+export async function runVerifyCommand(args, ctx) {
+    const { flags, error } = parseFlags(args);
+    if (error === 'help') {
+        ctx.writeOutput({ ok: true, command: 'verify', usage: VERIFY_USAGE }, VERIFY_USAGE);
+        return { results: [], passed: 0, failed: [], exitCode: 0 };
+    }
+    if (error !== null) {
+        ctx.writeOutput({ ok: false, command: 'verify', error }, `pugi verify: ${error}`);
+        return { results: [], passed: 0, failed: [], exitCode: 2 };
+    }
+    if (flags.claimsPath === null) {
+        const msg = 'claims path is required';
+        ctx.writeOutput({ ok: false, command: 'verify', error: msg }, `pugi verify: ${msg}\n\n${VERIFY_USAGE}`);
+        return { results: [], passed: 0, failed: [], exitCode: 2 };
+    }
+    const claimsPath = isAbsolute(flags.claimsPath)
+        ? flags.claimsPath
+        : resolve(ctx.cwd, flags.claimsPath);
+    if (!existsSync(claimsPath)) {
+        const msg = `claims file not found: ${claimsPath}`;
+        ctx.writeOutput({ ok: false, command: 'verify', error: msg }, `pugi verify: ${msg}`);
+        return { results: [], passed: 0, failed: [], exitCode: 2 };
+    }
+    let raw;
+    try {
+        raw = readFileSync(claimsPath, 'utf8');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.writeOutput({ ok: false, command: 'verify', error: message }, `pugi verify: cannot read ${claimsPath}: ${message}`);
+        return { results: [], passed: 0, failed: [], exitCode: 2 };
+    }
+    const parsed = parseClaimsDocument(raw);
+    if (!parsed.ok) {
+        ctx.writeOutput({ ok: false, command: 'verify', error: parsed.error }, `pugi verify: ${parsed.error}`);
+        return { results: [], passed: 0, failed: [], exitCode: 2 };
+    }
+    const resolvePath = ctx.resolvePath
+        ?? ((t) => resolveTargetPath(t, ctx.cwd));
+    const results = [];
+    for (const claim of parsed.claims) {
+        const startedAt = Date.now();
+        let outcome;
+        if (claim.kind === 'file_exists') {
+            outcome = evaluateFileExists(claim, resolvePath);
+        }
+        else if (claim.kind === 'grep_match') {
+            outcome = evaluateGrepMatch(claim, resolvePath);
+        }
+        else {
+            outcome = evaluateCmdZeroExit(claim, ctx);
+        }
+        const durationMs = Date.now() - startedAt;
+        results.push({
+            claim,
+            ok: outcome.ok,
+            detail: outcome.detail,
+            durationMs,
+        });
+    }
+    const failed = results.filter((r) => !r.ok);
+    const passed = results.length - failed.length;
+    const exitCode = flags.strict && failed.length > 0 ? 1 : 0;
+    const result = { results, passed, failed, exitCode };
+    ctx.writeOutput({ ok: true, command: 'verify', result }, renderHumanReport(result, flags.strict));
+    return result;
+}
+const VERIFY_USAGE = [
+    'pugi verify — post-execution claim verification.',
+    '',
+    'Usage:',
+    ' pugi verify <claims.json> [--json] [--strict | --no-strict]',
+    '',
+    'Flags:',
+    ' --json       Emit a JSON envelope instead of human text.',
+    ' --strict     Any failed claim → exit 1 (default).',
+    ' --no-strict  Print the ledger but always exit 0 on hard claim failures.',
+    '',
+    'Claim shapes (kind):',
+    ' file_exists      target = path (pass when file present + non-empty)',
+    ' grep_match       target = path expected = substring or /regex/flags',
+    ' cmd_zero_exit    target = command line (no shell metas)',
+    '',
+    'Sample claims.json:',
+    ' [',
+    '   { "claim": "snake.html shipped", "kind": "file_exists",  "target": "snake.html" },',
+    '   { "claim": "Hiroshi authored",  "kind": "grep_match",   "target": "CHANGELOG.md", "expected": "Hiroshi" },',
+    '   { "claim": "types compile",     "kind": "cmd_zero_exit", "target": "pnpm typecheck" }',
+    ' ]',
+].join('\n');
+//# sourceMappingURL=verify.js.map