@pugi/cli 0.1.0-beta.8 → 0.1.0-beta.88

package/dist/core/skills/sources.js

@@ -12,29 +12,29 @@ import { validateHostnameForFetch } from '../../tools/web-fetch.js';
  *
  * Supported source schemes:
  *
- *   1. `gh:owner/repo[/subdir][@ref]`
- *      → `gh:anthropics/skills/python-coding-standards@main`
- *      Fetches the GitHub tarball via the public codeload endpoint,
- *      extracts the requested subtree.
+ *  1. `gh:owner/repo[/subdir][@ref]`
+ *     → `gh:anthropics/skills/python-coding-standards@main`
+ *     Fetches the GitHub tarball via the public codeload endpoint,
+ *     extracts the requested subtree.
  *
- *   2. `https://github.com/<owner>/<repo>/tree/<ref>/<subdir>` (or `/blob/`)
- *      Normalised to the gh: form above.
+ *  2. `https://github.com/<owner>/<repo>/tree/<ref>/<subdir>` (or `/blob/`)
+ *     Normalised to the gh: form above.
  *
- *   3. `anthropic:<slug>` — convenience alias for
- *      `gh:anthropics/skills/<slug>@main`. Hard-coded base; the only
- *      reason this exists is so operators can copy a slug from the
- *      Anthropic docs without remembering the org name.
+ *  3. `anthropic:<slug>` — convenience alias for
+ *     `gh:anthropics/skills/<slug>@main`. Hard-coded base; the only
+ *     reason this exists is so operators can copy a slug from the
+ *     Anthropic docs without remembering the org name.
  *
- *   4. `npm:<package>` — fetches a tarball from the npm registry,
- *      extracts, looks for `SKILL.md` at the package root.
+ *  4. `npm:<package>` — fetches a tarball from the npm registry,
+ *     extracts, looks for `SKILL.md` at the package root.
  *
- *   5. Local path — `./relative` or `/abs/path`. Copied to tmp so the
- *      caller can mutate the original without affecting install.
+ *  5. Local path — `./relative` or `/abs/path`. Copied to tmp so the
+ *     caller can mutate the original without affecting install.
  *
- *   6. Catalog name — bare slug, queried against
- *      `https://catalog.pugi.dev/api/skills/<name>`. Returns a 404 →
- *      we surface a hint pointing at the `gh:anthropics/skills/<name>`
- *      form rather than crashing.
+ *  6. Catalog name — bare slug, queried against
+ *     `https://catalog.pugi.dev/api/skills/<name>`. Returns a 404 →
+ *     we surface a hint pointing at the `gh:anthropics/skills/<name>`
+ *     form rather than crashing.
  *
  * Every resolver writes the payload into a fresh temp dir under
  * `/tmp/pugi-skill-XXXXXX/` (caller cleans up after install completes).
@@ -58,7 +58,7 @@ export async function fetchSource(source) {
             throw new Error(`SOURCE_PARSE: anthropic: source needs a bare slug (got "${source}"). Example: anthropic:algorithmic-art`);
         }
         // Real layout is `anthropics/skills` repo → `skills/<slug>/SKILL.md`.
-        // Verified 2026-05-25 against the live repo tarball.
+        // Verified against the live repo tarball.
         return fetchGitHub(`${ANTHROPIC_REPO}/skills/${slug}@main`.slice(3));
     }
     if (source.startsWith('npm:')) {
@@ -113,7 +113,7 @@ async function fetchGitHub(raw) {
     const spec = parseGithubSpec(raw);
     // Use codeload.github.com — the public tarball endpoint requires no
     // auth for public repos and returns a single .tar.gz of the requested
-    // ref's tree. Private repos are out of scope for α7.0.
+    // ref's tree. Private repos are out of scope for .
     const tarUrl = `https://codeload.github.com/${spec.owner}/${spec.repo}/tar.gz/${spec.ref}`;
     const tmpRoot = mkdtempSync(join(tmpdir(), 'pugi-skill-gh-'));
     const tarPath = join(tmpRoot, 'payload.tar.gz');
@@ -268,9 +268,9 @@ async function requestFollow(url) {
     // future: webhook delivery). Drift between two copies of that block
     // list would be a real footgun — the SSRF cheat-sheet covers ~10
     // ranges and missing one (e.g. SIIT/NAT64) is exactly the class of
-    // bug Codex caught in PR #349.
+    // bug Codex caught in PR.
     // Initial scheme — locked for entire redirect chain. Codex P2 review
-    // (PR #362 v2): an HTTPS source that 302s к public http:// URL would
+    // (PR v2): an HTTPS source that 302s к public http:// URL would
     // otherwise be fetched cleartext, MITM tampers payload. Stay TLS.
     const initialScheme = new URL(currentUrl).protocol;
     await guardOutboundUrl(currentUrl, 'initial request', initialScheme);
@@ -321,7 +321,7 @@ async function guardOutboundUrl(rawUrl, label, initialScheme) {
     if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
         throw new Error(`SOURCE_SSRF: ${label} uses unsupported scheme ${parsed.protocol} (only http/https).`);
     }
-    // Codex P2 PR #362 v2: HTTPS source MUST NOT downgrade к HTTP across
+    // Codex P2 PR v2: HTTPS source MUST NOT downgrade к HTTP across
     // redirect chain — would let MITM tamper с payload after the initial
     // TLS hop. Once we started TLS, stay TLS.
     if (initialScheme === 'https:' && parsed.protocol === 'http:') {
@@ -405,20 +405,20 @@ async function extractTarball(tarPath, destDir) {
         // violations and throw AFTER extraction completes (see below).
         filter: (path, entry) => {
             // 1. Block any symlink or hardlink — these are the tar-slip
-            //    vectors. A symlink to ../../home/user/.ssh + a follow-up
-            //    write to that symlink would exfil secrets.
+            //   vectors. A symlink to ../../home/user/.ssh + a follow-up
+            //   write to that symlink would exfil secrets.
             if (entry.type === 'SymbolicLink' || entry.type === 'Link') {
                 violations.push(`SOURCE_TAR_SYMLINK: tarball contains ${entry.type} entry (${path} → ${entry.linkpath ?? '?'}). Refusing extraction.`);
                 return false;
             }
             // 2. Block absolute paths — `tar` strips the leading "/" in
-            //    permissive mode and writes anyway. We refuse such entries.
+            //   permissive mode and writes anyway. We refuse such entries.
             if (path.startsWith('/')) {
                 violations.push(`SOURCE_TAR_ABSOLUTE: tarball entry has absolute path: ${path}`);
                 return false;
             }
             // 3. Block parent-traversal segments. `..` as a path segment
-            //    cannot be present in any legitimate skill/agent payload.
+            //   cannot be present in any legitimate skill/agent payload.
             const segments = path.split(/[\\/]+/);
             if (segments.includes('..')) {
                 violations.push(`SOURCE_TAR_TRAVERSAL: tarball entry has parent-traversal segment: ${path}`);

package/dist/core/smoke/headless-driver.js

@@ -0,0 +1,174 @@
+/**
+ * Headless subprocess driver for the smoke harness (Phase 1).
+ *
+ * Spawns `pugi --headless`, feeds the scenario's user-input lines one
+ * at a time, and collects every JSON envelope written to stdout. The
+ * driver is the bridge between the in-process scenario parser and the
+ * real CLI binary — running scenarios via subprocess is what lets
+ * `pugi smoke` validate the AS-PUBLISHED CLI, not just the in-process
+ * code path.
+ *
+ * Phase 1 invariants:
+ *
+ *  - One scenario = one subprocess. We do NOT reuse processes across
+ *    scenarios; each run starts in a fresh temp workspace so file
+ *    assertions are deterministic.
+ *
+ *  - Stdin is fed line-by-line on a timer (default 200ms gap). We
+ *    could fire all lines at once, but spacing them out gives the
+ *    engine a chance to emit `persona-turn` envelopes between user
+ *    turns. Mirrors real-operator typing cadence — feeds a more
+ *    realistic test signal than a burst write.
+ *
+ *  - Hard timeout per scenario (default 30s). The driver kills the
+ *    subprocess on timeout and surfaces a clean executor-error so the
+ *    report still shows the row instead of hanging CI.
+ *
+ *  - Stderr is captured but NOT parsed. We forward it to the optional
+ *    `onStderr` sink so the operator can see what the headless CLI
+ *    wrote to stderr (banners, MCP load notices) — handy for
+ *    debugging a failing scenario locally.
+ */
+import { spawn } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+/**
+ * Run a parsed scenario through the headless CLI. Returns the captured
+ * envelope stream + the workspace root the process ran in so the
+ * runner can resolve `EXPECT_FILE` paths.
+ */
+export async function runHeadlessScenario(scenario, opts = {}) {
+    const pugiBin = opts.pugiBin ?? 'pugi';
+    const extraArgs = opts.extraArgs ?? [];
+    const timeoutMs = opts.timeoutMs ?? 30_000;
+    const lineGapMs = opts.lineGapMs ?? 200;
+    const onStderr = opts.onStderr ?? noopChunk;
+    const spawner = opts.spawner ?? defaultSpawner;
+    const workspaceRoot = mkdtempSync(resolve(tmpdir(), 'pugi-smoke-'));
+    let cleanedUp = false;
+    const args = ['--headless', ...extraArgs];
+    const child = spawner(pugiBin, args, {
+        cwd: workspaceRoot,
+        env: { ...process.env, PUGI_HEADLESS: '1' },
+    });
+    const envelopes = [];
+    let stdoutBuffer = '';
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+        stdoutBuffer += chunk;
+        let newlineIndex = stdoutBuffer.indexOf('\n');
+        while (newlineIndex !== -1) {
+            const line = stdoutBuffer.slice(0, newlineIndex);
+            stdoutBuffer = stdoutBuffer.slice(newlineIndex + 1);
+            const parsed = parseEnvelopeLine(line);
+            if (parsed)
+                envelopes.push(parsed);
+            newlineIndex = stdoutBuffer.indexOf('\n');
+        }
+    });
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk) => onStderr(chunk));
+    const userInputs = scenario.steps
+        .filter((s) => s.kind === 'user-input')
+        .map((s) => s.body);
+    // Feed inputs serially with a small gap. We don't await the engine's
+    // response — Phase 1 evaluates the WHOLE envelope stream after the
+    // process closes, so the gap is purely to give the engine room to
+    // emit between turns. A future phase can swap this for a barrier
+    // ("wait for `persona-turn` before sending the next `user-turn`")
+    // once envelope ordering is sealed.
+    const feedPromise = (async () => {
+        for (const line of userInputs) {
+            child.stdin.write(`${line}\n`);
+            await delay(lineGapMs);
+        }
+        child.stdin.end();
+    })();
+    const timeoutHandle = setTimeout(() => {
+        child.kill('SIGTERM');
+    }, timeoutMs);
+    // Don't keep node alive purely for the timeout — the spawned child
+    // already holds the loop via its IPC pipe.
+    timeoutHandle.unref?.();
+    await new Promise((resolvePromise) => {
+        child.on('close', () => resolvePromise());
+    });
+    clearTimeout(timeoutHandle);
+    // Flush any tail bytes that did not end with a newline.
+    if (stdoutBuffer.length > 0) {
+        const parsed = parseEnvelopeLine(stdoutBuffer);
+        if (parsed)
+            envelopes.push(parsed);
+        stdoutBuffer = '';
+    }
+    await feedPromise.catch(() => {
+        /* feed promise rejects when the child closes early — ignore */
+    });
+    // Cleanup the temp workspace lazily — the orchestrator may want to
+    // inspect it after the run. Callers that need a fresh dir per scenario
+    // should pass a custom workspaceRoot in a future phase; for now the
+    // runner resolves EXPECT_FILE paths against this directory and the
+    // OS reaps the tmp tree on reboot.
+    // (Explicit cleanup helper exposed for tests that want determinism.)
+    void cleanedUp;
+    return { envelopes, workspaceRoot };
+}
+/**
+ * Tear down a workspace created by `runHeadlessScenario`. Exposed
+ * separately because the orchestrator wants the directory to survive
+ * the run for EXPECT_FILE evaluation.
+ */
+export function cleanupWorkspace(workspaceRoot) {
+    try {
+        rmSync(workspaceRoot, { recursive: true, force: true });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/**
+ * Parse one line of headless stdout into an envelope. Returns null
+ * when the line is empty or unparseable — non-fatal so the runner can
+ * tolerate stray banner output.
+ */
+export function parseEnvelopeLine(raw) {
+    const line = raw.trim();
+    if (line.length === 0)
+        return null;
+    if (!line.startsWith('{'))
+        return null;
+    try {
+        const parsed = JSON.parse(line);
+        if (typeof parsed['kind'] !== 'string')
+            return null;
+        if (typeof parsed['body'] !== 'string')
+            return null;
+        const ts = typeof parsed['ts'] === 'number'
+            ? parsed['ts']
+            : Number(parsed['ts'] ?? Date.now());
+        return {
+            kind: parsed['kind'],
+            body: parsed['body'],
+            ts: Number.isFinite(ts) ? ts : Date.now(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function defaultSpawner(bin, args, options) {
+    return spawn(bin, args, {
+        cwd: options.cwd,
+        env: options.env,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+}
+function delay(ms) {
+    return new Promise((resolve) => {
+        const handle = setTimeout(resolve, ms);
+        handle.unref?.();
+    });
+}
+function noopChunk(_chunk) { }
+//# sourceMappingURL=headless-driver.js.map

package/dist/core/smoke/orchestrator.js

@@ -0,0 +1,194 @@
+/**
+ * Smoke orchestrator — glues the scenario parser, the headless
+ * subprocess driver, and the runner into a single "load → run → report"
+ * pipeline. The CLI surface (`pugi smoke`) and the standalone script
+ * (`scripts/run-scenarios.ts`) both call into this module so the two
+ * entry points share one code path.
+ *
+ * Phase 1 boundary — `runSmoke` is responsible for:
+ *
+ *  1. Discovering scenario files under `scenariosDir` (glob match on
+ *     `*.scenario.txt`).
+ *  2. Parsing each file via `parseScenario`. Parse errors are surfaced
+ *     via the report but do not stop the run — every scenario gets a
+ *     chance to fail with a clean diagnostic.
+ *  3. Driving each scenario through the headless executor (the
+ *     executor is injected so tests can swap it for a deterministic
+ *     stub; production wires `runHeadlessScenario` from
+ *     `headless-driver.ts`).
+ *  4. Filtering by `--filter <pattern>` (compiles to fnmatch-lite).
+ *  5. Computing pass/fail/summary numbers.
+ *
+ * The orchestrator is intentionally synchronous (apart from the
+ * per-scenario `await`) — running scenarios in parallel is a Phase 2
+ * concern. The corpus is small and sequential output is easier to read.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseScenario, } from './scenario-parser.js';
+import { runScenario, } from './runner.js';
+/**
+ * Top-level smoke entry. Returns the report so the CLI can pretty-print
+ * it AND set `process.exitCode` deterministically.
+ */
+export async function runSmoke(opts) {
+    const log = opts.log ?? noopLog;
+    const now = opts.now ?? Date.now;
+    const allScenarios = loadScenariosFromDir(opts.scenariosDir);
+    const visible = opts.filter && opts.filter.length > 0
+        ? filterByPattern(allScenarios, opts.filter)
+        : allScenarios;
+    const results = [];
+    let passed = 0;
+    let failed = 0;
+    for (const item of visible) {
+        log(`pugi smoke: running ${item.scenario.id}`);
+        if (item.parseErrors.length > 0) {
+            results.push({
+                id: item.scenario.id,
+                filePath: item.scenario.filePath,
+                status: 'parse-error',
+                durationMs: 0,
+                assertionCount: 0,
+                failures: [],
+                parseErrors: item.parseErrors,
+            });
+            failed += 1;
+            continue;
+        }
+        let envelopes = [];
+        let workspaceRoot = '.';
+        try {
+            const out = await opts.executor(item.scenario);
+            envelopes = out.envelopes;
+            workspaceRoot = out.workspaceRoot;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            results.push({
+                id: item.scenario.id,
+                filePath: item.scenario.filePath,
+                status: 'executor-error',
+                durationMs: 0,
+                assertionCount: 0,
+                failures: [],
+                executorError: message,
+            });
+            failed += 1;
+            continue;
+        }
+        const result = runScenario({
+            scenario: item.scenario,
+            envelopes,
+            workspaceRoot,
+            now,
+        });
+        results.push({
+            id: result.id,
+            filePath: item.scenario.filePath,
+            status: result.passed ? 'passed' : 'failed',
+            durationMs: result.durationMs,
+            assertionCount: result.assertionCount,
+            failures: result.failures,
+        });
+        if (result.passed)
+            passed += 1;
+        else
+            failed += 1;
+    }
+    const total = visible.length;
+    const skipped = allScenarios.length - visible.length;
+    const exitCode = failed === 0 ? 0 : 1;
+    return { total, passed, failed, skipped, results, exitCode };
+}
+/**
+ * Walk `dir` for `*.scenario.txt` files (non-recursive). Returns each
+ * file's parsed scenario + collected parse errors so the orchestrator
+ * can surface malformed files as failed runs rather than skipping them.
+ */
+export function loadScenariosFromDir(dir) {
+    let names = [];
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        if (!name.endsWith('.scenario.txt'))
+            continue;
+        const filePath = resolve(dir, name);
+        let stat;
+        try {
+            stat = statSync(filePath);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile())
+            continue;
+        const body = readFileSync(filePath, 'utf8');
+        const parsed = parseScenario(filePath, body);
+        if (parsed.scenario) {
+            out.push({ scenario: parsed.scenario, parseErrors: parsed.errors });
+        }
+    }
+    // Stable sort by id so report output is deterministic across
+    // filesystems with different readdir order.
+    out.sort((a, b) => a.scenario.id.localeCompare(b.scenario.id));
+    return out;
+}
+/**
+ * Render a SmokeReport into a multi-line human-readable string. Kept
+ * separate from `runSmoke` so the CLI can pick its own format (text vs
+ * JSON). The default text format mirrors `node:test`'s tap-lite output:
+ *
+ *  ok 1 - identity (12ms)
+ *  not ok 2 - codegen-create-file (8ms)
+ *    line 5: EXPECT failed — no envelope matched ...
+ *
+ *  pugi smoke: 1 passed, 1 failed
+ */
+export function renderReportText(report) {
+    const lines = [];
+    for (let i = 0; i < report.results.length; i += 1) {
+        const r = report.results[i];
+        if (!r)
+            continue;
+        const ordinal = i + 1;
+        if (r.status === 'passed') {
+            lines.push(`ok ${ordinal} - ${r.id} (${r.durationMs}ms)`);
+        }
+        else if (r.status === 'failed') {
+            lines.push(`not ok ${ordinal} - ${r.id} (${r.durationMs}ms)`);
+            for (const f of r.failures) {
+                lines.push(` line ${f.line}: ${f.message}`);
+            }
+        }
+        else if (r.status === 'parse-error') {
+            lines.push(`not ok ${ordinal} - ${r.id} (parse error)`);
+            for (const e of r.parseErrors ?? []) {
+                lines.push(` line ${e.line}: ${e.message}`);
+            }
+        }
+        else if (r.status === 'executor-error') {
+            lines.push(`not ok ${ordinal} - ${r.id} (executor error)`);
+            lines.push(` ${r.executorError ?? 'unknown executor failure'}`);
+        }
+    }
+    lines.push('');
+    const skippedSuffix = report.skipped > 0 ? `, ${report.skipped} skipped` : '';
+    lines.push(`pugi smoke: ${report.passed} passed, ${report.failed} failed${skippedSuffix}`);
+    return lines.join('\n');
+}
+function filterByPattern(scenarios, pattern) {
+    if (!pattern.includes('*')) {
+        return scenarios.filter((s) => s.scenario.id.includes(pattern));
+    }
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`^${escaped.replace(/\*/g, '.*')}$`);
+    return scenarios.filter((s) => re.test(s.scenario.id));
+}
+function noopLog(_line) { }
+//# sourceMappingURL=orchestrator.js.map