@pugi/cli 0.1.0-beta.99 → 1.0.0-alpha.1

package/dist/skills/bundled/verify.js

@@ -1,439 +0,0 @@
-/**
- * `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