@pugi/cli 0.1.0-beta.7 → 0.1.0-beta.87

package/dist/core/smoke/runner.js

@@ -0,0 +1,238 @@
+/**
+ * Scenario runner for the Pugi MCP test harness (
+ *).
+ *
+ * Drives a parsed scenario against a stream of `HeadlessEnvelope`
+ * objects (the same shape `pugi --headless` emits on stdout) and a
+ * filesystem checker for `EXPECT_FILE` directives. The runner is
+ * deliberately decoupled from the subprocess spawn so the spec file
+ * can inject deterministic envelope arrays without spawning a real
+ * `pugi` binary — that strategy keeps the test cycle under 200ms while
+ * still exercising the matching semantics every CI run depends on.
+ *
+ * Matching semantics (the rules the corpus authors care about):
+ *
+ *  - `EXPECT:` after a `>` user-input line scans envelopes that
+ *    arrived AFTER that user-input. The cursor resets on each new
+ *    `>`. If no envelope satisfies the pattern, the assertion fails.
+ *
+ *  - `EXPECT_NOT:` runs the inverse — passes if NO envelope in the
+ *    post-`>` window satisfies the pattern. A negative assertion that
+ *    fires on every input line gives the operator a clean signal when
+ *    a forbidden phrase ("Pugi") shows up.
+ *
+ *  - `EXPECT_FILE:` runs once at the END of the scenario, against the
+ *    final filesystem snapshot. The runner does not race the
+ *    subprocess — by the time we evaluate file assertions the
+ *    headless process has exited (or been terminated).
+ *
+ * Result shape mirrors `node:test` style: top-level pass/fail plus an
+ * array of per-assertion records so the CLI can print a grouped
+ * summary. Each failure carries the originating line number so the
+ * operator can jump straight to the scenario source.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+/**
+ * Run the assertions in `scenario` against the given envelope stream
+ * and filesystem snapshot. Pure function — no I/O outside the filesystem
+ * stat that `EXPECT_FILE` performs, and even that is gated by a step
+ * actually existing.
+ */
+export function runScenario(inputs) {
+    const now = inputs.now ?? Date.now;
+    const startedAt = now();
+    const failures = [];
+    let assertionCount = 0;
+    // Group steps into runs anchored by `>` user-input lines. Each run
+    // owns the EXPECT/EXPECT_NOT assertions that follow it until the
+    // next `>`. EXPECT_FILE is collected globally and evaluated after
+    // every user-input run is processed.
+    const runs = [];
+    const fileChecks = [];
+    for (const step of inputs.scenario.steps) {
+        if (step.kind === 'user-input') {
+            runs.push({ userStep: step, expects: [] });
+            continue;
+        }
+        if (step.kind === 'expect') {
+            // Assertions that appear BEFORE any `>` attach to a synthetic
+            // pre-run so the matching pass still sees them. Rare in practice,
+            // but the parser allows it and the runner should not silently
+            // drop them.
+            if (runs.length === 0)
+                runs.push({ userStep: null, expects: [] });
+            const current = runs[runs.length - 1];
+            if (current)
+                current.expects.push(step);
+            continue;
+        }
+        if (step.kind === 'expect-file') {
+            fileChecks.push(step);
+        }
+    }
+    // Build a per-run envelope window. We walk the envelope stream once,
+    // assigning each envelope to the most recent user-turn we have seen.
+    // The first `user-turn` envelope after a `>` is the marker for that
+    // run; assertions match within the slice up to (but not including)
+    // the NEXT `user-turn` envelope.
+    const userTurnIndices = [];
+    for (let i = 0; i < inputs.envelopes.length; i += 1) {
+        const env = inputs.envelopes[i];
+        if (env && env.kind === 'user-turn')
+            userTurnIndices.push(i);
+    }
+    for (let runIdx = 0; runIdx < runs.length; runIdx += 1) {
+        const run = runs[runIdx];
+        if (!run)
+            continue;
+        let start = 0;
+        let end = inputs.envelopes.length;
+        if (run.userStep && userTurnIndices[runIdx] !== undefined) {
+            start = (userTurnIndices[runIdx] ?? 0) + 1;
+            const nextUserTurn = userTurnIndices[runIdx + 1];
+            end = nextUserTurn ?? inputs.envelopes.length;
+        }
+        const window = inputs.envelopes.slice(start, end);
+        for (const expectation of run.expects) {
+            assertionCount += 1;
+            const matched = window.some((env) => matchesEnvelope(env, expectation.pattern));
+            if (expectation.polarity === 'positive' && !matched) {
+                failures.push({
+                    line: expectation.line,
+                    message: `EXPECT failed — no envelope matched ${describePattern(expectation.pattern)}`,
+                });
+            }
+            else if (expectation.polarity === 'negative' && matched) {
+                failures.push({
+                    line: expectation.line,
+                    message: `EXPECT_NOT failed — envelope matched ${describePattern(expectation.pattern)}`,
+                });
+            }
+        }
+    }
+    for (const check of fileChecks) {
+        assertionCount += 1;
+        const absolute = resolve(inputs.workspaceRoot, check.file);
+        if (!existsSync(absolute)) {
+            failures.push({
+                line: check.line,
+                message: `EXPECT_FILE failed — ${check.file} does not exist`,
+            });
+            continue;
+        }
+        if (check.content !== undefined) {
+            const body = readFileSync(absolute, 'utf8');
+            if (!body.includes(check.content)) {
+                failures.push({
+                    line: check.line,
+                    message: `EXPECT_FILE failed — ${check.file} does not contain "${check.content}"`,
+                });
+            }
+        }
+    }
+    const durationMs = Math.max(0, now() - startedAt);
+    return {
+        id: inputs.scenario.id,
+        passed: failures.length === 0,
+        failures,
+        durationMs,
+        assertionCount,
+    };
+}
+/**
+ * Filter parsed scenarios by a simple glob-ish substring matcher.
+ * `*` matches any run of characters; otherwise we fall back to plain
+ * substring containment so `pugi smoke --filter identity` works as
+ * the operator expects. The matcher is intentionally NOT a full RegExp
+ * (no anchors, no character classes) because scenarios are addressed
+ * by short ids — a `--filter "id*"` form is the maximum complexity
+ * the corpus needs.
+ */
+export function filterScenarios(scenarios, pattern) {
+    if (!pattern || pattern.length === 0)
+        return scenarios;
+    const matcher = compileFilterPattern(pattern);
+    return scenarios.filter((s) => matcher(s.id));
+}
+function compileFilterPattern(pattern) {
+    if (!pattern.includes('*')) {
+        return (id) => id.includes(pattern);
+    }
+    // Escape RegExp metacharacters except `*`, then translate `*` to
+    // `.*`. This is the dropbox/glob "fnmatch lite" approach — predictable
+    // and small.
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`^${escaped.replace(/\*/g, '.*')}$`);
+    return (id) => re.test(id);
+}
+/**
+ * Decide whether a single envelope satisfies a pattern. Exported for
+ * tests that want to probe the matching logic without building a full
+ * scenario object.
+ */
+export function matchesEnvelope(env, pattern) {
+    if (pattern.kind === 'persona-turn-contains') {
+        if (env.kind !== 'persona-turn')
+            return false;
+        return pattern.substrings.some((s) => env.body.includes(s));
+    }
+    if (pattern.kind === 'tool-call') {
+        if (env.kind !== 'tool-call')
+            return false;
+        // The body is JSON. Tool calls that don't parse as JSON cannot
+        // match — surface a clean fail instead of crashing.
+        let parsed;
+        try {
+            parsed = JSON.parse(env.body);
+        }
+        catch {
+            return false;
+        }
+        if (!isRecord(parsed))
+            return false;
+        if (pattern.tool !== undefined && parsed['tool'] !== pattern.tool) {
+            return false;
+        }
+        if (pattern.argsSubset !== undefined) {
+            const args = parsed['args'];
+            if (!isRecord(args))
+                return false;
+            for (const [k, v] of Object.entries(pattern.argsSubset)) {
+                if (String(args[k]) !== v)
+                    return false;
+            }
+        }
+        return true;
+    }
+    if (pattern.kind === 'envelope-kind') {
+        return env.kind === pattern.envelopeKind;
+    }
+    return false;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function describePattern(pattern) {
+    if (pattern.kind === 'persona-turn-contains') {
+        return `persona-turn containing one of [${pattern.substrings
+            .map((s) => `"${s}"`)
+            .join(', ')}]`;
+    }
+    if (pattern.kind === 'tool-call') {
+        const parts = [];
+        if (pattern.tool)
+            parts.push(`tool=${pattern.tool}`);
+        if (pattern.argsSubset) {
+            for (const [k, v] of Object.entries(pattern.argsSubset)) {
+                parts.push(`${k}=${v}`);
+            }
+        }
+        return `tool-call ${parts.join(' ')}`.trim();
+    }
+    if (pattern.kind === 'envelope-kind') {
+        return `envelope kind=${pattern.envelopeKind}`;
+    }
+    return 'unknown pattern';
+}
+//# sourceMappingURL=runner.js.map

package/dist/core/smoke/scenario-parser.js

@@ -0,0 +1,316 @@
+/**
+ * Scenario DSL parser for the Pugi MCP test harness (
+ * Phase 1).
+ *
+ * Background — CEO directive `feedback_live_console_test_every_publish`:
+ * every CLI publish must be smoke-tested against a fixed corpus of
+ * scripted dialogs before it is announced to the operator. The manual
+ * routine ("npm i -g + pugi --version + run identity prompt + verify
+ * Pugi self-id") is exactly the kind of toil a deterministic harness
+ * should automate. Phase 1 lays the foundation; the corpus + headless
+ * runner + CI gate.
+ *
+ * Format — one scenario per file, line-based, intentionally minimal so
+ * non-engineers can author cases. The grammar:
+ *
+ *  # comment       — ignored
+ *  # scenario: <id> — optional metadata
+ *  > "<input>"     — single user turn (the engine sees this verbatim)
+ *  EXPECT: <pred>  — positive assertion against the next persona-turn
+ *                     envelope OR a tool-call envelope. Multiple stack
+ *                     against the SAME prior `>` turn until the next
+ *                     `>` resets the cursor.
+ *  EXPECT_NOT:<pred>— negative assertion (same cursor semantics).
+ *  EXPECT_FILE:<file> exists [with content "<text>"]
+ *                   — filesystem assertion fired AFTER the scenario
+ *                     finishes. Matches both `exists` literal and a
+ *                     content substring check.
+ *
+ * The DSL parser is deliberately a pure function over the file contents:
+ * the runner module is the thing that spawns `pugi --headless` and
+ * matches assertions against the emitted envelope stream. Keeping the
+ * parser pure is what lets us spec it with no fixtures.
+ *
+ * Anti-design — we did NOT use YAML/JSON. The line-based form survives
+ * copy-paste from a chat transcript ("> 'ты кто?'" maps 1:1 to the way
+ * an operator sees a Pugi dialog), and prevents drift between scenario
+ * authoring style and how the operator actually drives the CLI.
+ */
+/**
+ * Parse a scenario file body into a `ParsedScenario`. Returns errors
+ * alongside the partial scenario so the runner can surface every issue
+ * in one pass rather than failing on the first malformed line. The
+ * shape mirrors what TypeScript's diagnostics array looks like —
+ * familiar pattern for any operator who has read a tsc error.
+ *
+ * `filePath` is informational; we ALSO consume it to derive the
+ * default scenario id when the file body does not declare one.
+ */
+export function parseScenario(filePath, body) {
+    const errors = [];
+    const steps = [];
+    let title;
+    let explicitId;
+    const lines = body.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i += 1) {
+        const raw = lines[i] ?? '';
+        const lineNo = i + 1;
+        const trimmed = raw.trim();
+        if (trimmed.length === 0)
+            continue;
+        if (trimmed.startsWith('#')) {
+            // Metadata comments. `# scenario: <id>` populates the explicit
+            // id; `# title: <text>` populates the title. Plain `# anything`
+            // is a free-form comment.
+            const meta = /^#\s*(scenario|title)\s*:\s*(.+?)\s*$/i.exec(trimmed);
+            if (meta) {
+                const key = (meta[1] ?? '').toLowerCase();
+                const value = meta[2] ?? '';
+                if (key === 'scenario')
+                    explicitId = value;
+                else if (key === 'title')
+                    title = value;
+            }
+            continue;
+        }
+        if (trimmed.startsWith('>')) {
+            const body = parseQuotedInput(trimmed.slice(1).trim());
+            if (body === null) {
+                errors.push({
+                    line: lineNo,
+                    message: 'user input line must be quoted (e.g. > "hello")',
+                });
+                continue;
+            }
+            steps.push({ kind: 'user-input', body, line: lineNo });
+            continue;
+        }
+        if (trimmed.startsWith('EXPECT_FILE:')) {
+            const payload = trimmed.slice('EXPECT_FILE:'.length).trim();
+            const fileStep = parseExpectFile(payload, lineNo);
+            if (fileStep.errors.length > 0) {
+                errors.push(...fileStep.errors);
+                continue;
+            }
+            if (fileStep.step)
+                steps.push(fileStep.step);
+            continue;
+        }
+        if (trimmed.startsWith('EXPECT_NOT:')) {
+            const payload = trimmed.slice('EXPECT_NOT:'.length).trim();
+            const parsed = parseAssertion(payload, lineNo);
+            if (parsed.errors.length > 0) {
+                errors.push(...parsed.errors);
+                continue;
+            }
+            if (parsed.pattern) {
+                steps.push({
+                    kind: 'expect',
+                    polarity: 'negative',
+                    pattern: parsed.pattern,
+                    anchor: 'last-user',
+                    line: lineNo,
+                });
+            }
+            continue;
+        }
+        if (trimmed.startsWith('EXPECT:')) {
+            const payload = trimmed.slice('EXPECT:'.length).trim();
+            const parsed = parseAssertion(payload, lineNo);
+            if (parsed.errors.length > 0) {
+                errors.push(...parsed.errors);
+                continue;
+            }
+            if (parsed.pattern) {
+                steps.push({
+                    kind: 'expect',
+                    polarity: 'positive',
+                    pattern: parsed.pattern,
+                    anchor: 'last-user',
+                    line: lineNo,
+                });
+            }
+            continue;
+        }
+        errors.push({
+            line: lineNo,
+            message: `unrecognized directive (expected one of: > "...", EXPECT:, EXPECT_NOT:, EXPECT_FILE:, # comment): ${trimmed}`,
+        });
+    }
+    const id = explicitId ?? deriveDefaultId(filePath);
+    const scenario = {
+        id,
+        ...(title !== undefined ? { title } : {}),
+        filePath,
+        steps,
+    };
+    return { scenario, errors };
+}
+/**
+ * Strip the wrapping quotes from a `> "..."` user line. Returns the
+ * inner string when the input is properly quoted (single OR double),
+ * otherwise null so the parser can surface a diagnostic. Allowing both
+ * quote styles is a thoughtful nicety — Russian scenarios frequently
+ * embed double quotes inside a Cyrillic phrase, e.g. `> 'ты "сделай"
+ * хорошо'`.
+ */
+function parseQuotedInput(raw) {
+    if (raw.length < 2)
+        return null;
+    const first = raw[0];
+    const last = raw[raw.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+        return raw.slice(1, -1);
+    }
+    // Permissive fallback — a bare unquoted line is still parsed as the
+    // user input (lets quick prototypes work). The runner does not
+    // distinguish between quoted and unquoted forms.
+    return raw;
+}
+/**
+ * Parse the right-hand side of an `EXPECT:` / `EXPECT_NOT:` directive.
+ * Discriminates between the three pattern kinds by looking at the
+ * leading keyword. Errors collect rather than throw so the runner can
+ * report multiple parse problems in one pass.
+ */
+function parseAssertion(payload, line) {
+    const errors = [];
+    if (payload.length === 0) {
+        return {
+            pattern: null,
+            errors: [{ line, message: 'EXPECT directive requires a pattern' }],
+        };
+    }
+    const personaMatch = /^persona-turn\s+contains\s+(.+)$/i.exec(payload);
+    if (personaMatch) {
+        const substrings = parseOrList(personaMatch[1] ?? '');
+        if (substrings.length === 0) {
+            errors.push({
+                line,
+                message: 'persona-turn contains requires one or more quoted substrings',
+            });
+            return { pattern: null, errors };
+        }
+        return {
+            pattern: { kind: 'persona-turn-contains', substrings },
+            errors,
+        };
+    }
+    const toolMatch = /^tool-call(?:\s+(.+))?$/i.exec(payload);
+    if (toolMatch) {
+        const remainder = (toolMatch[1] ?? '').trim();
+        const kv = parseKeyValuePairs(remainder);
+        const result = { kind: 'tool-call' };
+        if (kv.kind !== undefined)
+            result.tool = kv.kind;
+        const argsSubset = {};
+        for (const [k, v] of Object.entries(kv)) {
+            if (k === 'kind')
+                continue;
+            argsSubset[k] = v;
+        }
+        if (Object.keys(argsSubset).length > 0)
+            result.argsSubset = argsSubset;
+        return { pattern: result, errors };
+    }
+    const envelopeMatch = /^envelope\s+kind=([\w-]+)$/i.exec(payload);
+    if (envelopeMatch) {
+        return {
+            pattern: {
+                kind: 'envelope-kind',
+                envelopeKind: envelopeMatch[1] ?? '',
+            },
+            errors,
+        };
+    }
+    errors.push({
+        line,
+        message: `unrecognized EXPECT pattern: ${payload}`,
+    });
+    return { pattern: null, errors };
+}
+/**
+ * Parse the EXPECT_FILE payload. Grammar:
+ *
+ *  <relative path> exists
+ *  <relative path> exists with content "<text>"
+ *
+ * The path is unquoted (everything up to `exists`); the content phrase
+ * is double-quoted so it can include whitespace.
+ */
+function parseExpectFile(payload, line) {
+    const errors = [];
+    const match = /^(\S+)\s+exists(?:\s+with\s+content\s+"([^"]*)")?\s*$/.exec(payload);
+    if (!match) {
+        errors.push({
+            line,
+            message: 'EXPECT_FILE expects: <path> exists [with content "<text>"]',
+        });
+        return { step: null, errors };
+    }
+    const file = match[1];
+    if (!file) {
+        errors.push({ line, message: 'EXPECT_FILE missing file path' });
+        return { step: null, errors };
+    }
+    const content = match[2];
+    const step = content !== undefined
+        ? { kind: 'expect-file', file, content, line }
+        : { kind: 'expect-file', file, line };
+    return { step, errors };
+}
+/**
+ * Split a `"..." OR "..." OR "..."` list into the inner strings.
+ * Whitespace tolerant; the `OR` is case-insensitive so authors who
+ * type `or` lowercase are not punished.
+ */
+function parseOrList(raw) {
+    const parts = raw.split(/\s+OR\s+/i);
+    const result = [];
+    for (const part of parts) {
+        const trimmed = part.trim();
+        if (trimmed.length === 0)
+            continue;
+        if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+            (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+            result.push(trimmed.slice(1, -1));
+        }
+        else {
+            // Permissive — accept unquoted token as a single substring. The
+            // parser does not enforce quotes here because scenario authors
+            // type Cyrillic without delimiters all the time.
+            result.push(trimmed);
+        }
+    }
+    return result;
+}
+/**
+ * Parse a whitespace-separated `key=value` list (e.g.
+ * `kind=Write file=hello.txt`) into a flat record. Values may be
+ * double-quoted to embed whitespace, though the corpus today uses bare
+ * tokens.
+ */
+function parseKeyValuePairs(raw) {
+    const out = {};
+    if (raw.length === 0)
+        return out;
+    const re = /(\w+)=(?:"([^"]*)"|(\S+))/g;
+    let match;
+    while ((match = re.exec(raw)) !== null) {
+        const key = match[1];
+        if (!key)
+            continue;
+        const value = match[2] !== undefined ? match[2] : (match[3] ?? '');
+        out[key] = value;
+    }
+    return out;
+}
+/**
+ * Derive a default scenario id from the file path: strip the directory,
+ * drop the trailing `.scenario.txt` (or `.txt`) suffix.
+ */
+function deriveDefaultId(filePath) {
+    const base = filePath.split(/[/\\]/).pop() ?? filePath;
+    return base.replace(/\.scenario\.txt$/i, '').replace(/\.txt$/i, '');
+}
+//# sourceMappingURL=scenario-parser.js.map

package/dist/core/statusline.js

@@ -0,0 +1,99 @@
+import { spawn } from 'node:child_process';
+import { resolve as pathResolve } from 'node:path';
+const DEFAULT_TIMEOUT_MS = 500;
+const MAX_OUTPUT_LINE_CHARS = 240;
+/**
+ * Execute the configured status-line command and return the rendered
+ * footer text. Never throws — every failure path resolves to `''`
+ * and the caller decides what default to show.
+ *
+ * `cwd` parameter is the workspace root the spawned process should
+ * inherit. Caller already validates the workspace bounds; this
+ * function trusts it.
+ */
+export async function executeStatusLine(config, input, cwd) {
+    const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const command = config.command.trim();
+    if (command.length === 0)
+        return '';
+    return new Promise((resolveFn) => {
+        let settled = false;
+        const finish = (s) => {
+            if (settled)
+                return;
+            settled = true;
+            resolveFn(s);
+        };
+        let child;
+        try {
+            child = spawn(command, {
+                shell: true,
+                cwd: pathResolve(cwd),
+                env: { ...process.env, PUGI_STATUSLINE: '1' },
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+        }
+        catch {
+            finish('');
+            return;
+        }
+        const chunks = [];
+        child.stdout?.on('data', (c) => {
+            chunks.push(c);
+            const joined = Buffer.concat(chunks).toString('utf8');
+            if (joined.length > 8192) {
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch {
+                    // swallow — process may have already exited
+                }
+            }
+        });
+        child.stderr?.on('data', () => {
+            // Discard stderr to keep the contract stdout-only and the
+            // session log readable; future telemetry can capture it.
+        });
+        const timer = setTimeout(() => {
+            try {
+                child.kill('SIGKILL');
+            }
+            catch {
+                // swallow
+            }
+            finish('');
+        }, Math.max(1, Math.min(5000, timeoutMs)));
+        child.on('error', () => {
+            clearTimeout(timer);
+            finish('');
+        });
+        child.on('close', () => {
+            clearTimeout(timer);
+            const out = Buffer.concat(chunks).toString('utf8');
+            finish(extractFirstLine(out));
+        });
+        try {
+            child.stdin?.end(JSON.stringify(input));
+        }
+        catch {
+            clearTimeout(timer);
+            finish('');
+        }
+    });
+}
+function extractFirstLine(raw) {
+    if (raw.length === 0)
+        return '';
+    const lines = raw.split(/\r?\n/);
+    for (const ln of lines) {
+        const trimmed = ln.trim();
+        if (trimmed.length === 0)
+            continue;
+        return trimmed.slice(0, MAX_OUTPUT_LINE_CHARS);
+    }
+    return '';
+}
+// Exposed for tests — extractFirstLine has subtle splitter behaviour
+// (CRLF vs LF, multiple blank leaders) worth locking.
+export const __test = { extractFirstLine };
+//# sourceMappingURL=statusline.js.map