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

package/dist/runtime/headless-repl.js

@@ -0,0 +1,195 @@
+/**
+ * Headless REPL — `pugi --headless` .
+ *
+ * Long-form rationale lives in the spec PR; the short version: every
+ * CLI publish gets manually smoke-tested today (CEO directive
+ * `feedback_live_console_test_every_publish`) and that toil must be
+ * automated. `pugi --headless` is the I/O surface that lets a scripted
+ * harness drive Pugi multi-turn — one stdin line in, one or more JSON
+ * envelopes out on stdout, exit when stdin closes. This is the
+ * machine-facing peer to the human-facing Ink REPL.
+ *
+ * Envelope shape (Phase 1):
+ *
+ *  { "kind": "user-turn"  | "persona-turn" | "tool-call" | "error"
+ *          | "session-start" | "session-end" | "system",
+ *    "body": "<string>",
+ *    "ts":  <epoch ms> }
+ *
+ * One JSON object per line. Stdout stays pure envelopes; stderr gets
+ * any human-readable trace. Discipline mirrors the existing
+ * `runHeadlessPrint` in `headless.ts`.
+ *
+ * Phase 1 engine wiring — the headless REPL emits the user-turn
+ * envelope verbatim, then asks the engine adapter for ONE turn, then
+ * emits the persona-turn / tool-call envelopes. Multi-turn state is
+ * accumulated in a single in-process session so consecutive lines see
+ * the same persona history. When a credential is absent (a common CI
+ * state) we fall through to a deterministic stub responder so the
+ * smoke harness can still exercise the I/O contract WITHOUT requiring
+ * an api.pugi.io reachability dependency.
+ */
+import { createInterface } from 'node:readline';
+import { resolve as resolvePath } from 'node:path';
+import { resolveActiveCredential } from '../core/credentials.js';
+/**
+ * Run the headless REPL loop. Returns the desired process exit code:
+ *
+ *  0 Stdin closed cleanly after at least one successful turn.
+ *  0 Stdin closed with no input (empty pipe — harmless, exit clean).
+ *  1 Fatal error from the turn handler.
+ *
+ * The caller (cli.ts) sets `process.exitCode`; we never call
+ * `process.exit` so an embedded driver can reuse the function.
+ */
+export async function runHeadlessRepl(opts) {
+    const cwd = resolvePath(opts.cwd);
+    const stdoutWrite = opts.stdoutWrite ?? ((chunk) => process.stdout.write(chunk));
+    const stderrWrite = opts.stderrWrite ?? ((chunk) => process.stderr.write(chunk));
+    const now = opts.now ?? Date.now;
+    const turnHandler = opts.turnHandler ?? buildDefaultTurnHandler();
+    const stdin = opts.stdin ?? process.stdin;
+    emit(stdoutWrite, {
+        kind: 'session-start',
+        body: JSON.stringify({ cwd, cliVersion: 'phase1' }),
+        ts: now(),
+    });
+    const rl = createInterface({
+        input: stdin,
+        crlfDelay: Infinity,
+        terminal: false,
+    });
+    let turnIndex = 0;
+    let fatal = false;
+    for await (const rawLine of rl) {
+        const line = rawLine.replace(/\r$/, '');
+        if (line.length === 0)
+            continue;
+        emit(stdoutWrite, {
+            kind: 'user-turn',
+            body: line,
+            ts: now(),
+        });
+        try {
+            const out = await turnHandler({ line, turnIndex, cwd });
+            for (const env of out) {
+                emit(stdoutWrite, { kind: env.kind, body: env.body, ts: now() });
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            emit(stdoutWrite, {
+                kind: 'error',
+                body: JSON.stringify({ message }),
+                ts: now(),
+            });
+            stderrWrite(`pugi --headless: turn handler threw: ${message}\n`);
+            fatal = true;
+            break;
+        }
+        turnIndex += 1;
+    }
+    emit(stdoutWrite, {
+        kind: 'session-end',
+        body: JSON.stringify({ turns: turnIndex }),
+        ts: now(),
+    });
+    return fatal ? 1 : 0;
+}
+/**
+ * Emit a single envelope to stdout. Always terminates with `\n` so a
+ * line-buffered reader (the smoke runner, jq, etc.) sees each
+ * envelope atomically.
+ */
+function emit(write, envelope) {
+    write(`${JSON.stringify(envelope)}\n`);
+}
+/**
+ * Build the default turn handler. When a Pugi credential is resolvable
+ * we'll plumb to the engine adapter in Phase 2; for Phase 1 the
+ * default responder is a deterministic stub. Smoke scenarios that
+ * exercise the engine path use a Phase-2-only flag (`PUGI_HEADLESS_LIVE=1`)
+ * to opt into the real engine; the default keeps CI offline-safe.
+ */
+function buildDefaultTurnHandler() {
+    const credential = resolveActiveCredential();
+    if (credential && process.env.PUGI_HEADLESS_LIVE === '1') {
+        // Phase 2: route through `NativePugiEngineAdapter` here. Left as a
+        // stub so the Phase 1 PR stays narrowly scoped to the I/O surface.
+        // The smoke corpus does NOT exercise this branch in Phase 1.
+        return stubResponder('live engine path not yet wired (Phase 2)');
+    }
+    return stubResponder('pugi headless stub: no credential or PUGI_HEADLESS_LIVE!=1; echoing input');
+}
+/**
+ * Tiny deterministic responder used by Phase 1 smoke tests. Echoes the
+ * input back as a `persona-turn` envelope with a stable prefix so
+ * scenarios can author assertions against it. The contract is:
+ *
+ *  - Input "ты кто?"               → persona-turn "Pugi: ты кто? (stub)"
+ *  - Input "create FILE with content X"
+ *                                   → tool-call Write file=FILE +
+ *                                     persona-turn "Pugi: wrote FILE"
+ *  - Any other input               → persona-turn "Pugi: ...(stub)"
+ *
+ * Real engine routing is Phase 2. The stub exists to validate the
+ * envelope contract end-to-end in CI without depending on api.pugi.io.
+ */
+function stubResponder(banner) {
+    return async (input) => {
+        const text = input.line.trim();
+        const envelopes = [];
+        const createMatch = /^create\s+(\S+)\s+with\s+content\s+['"]([^'"]+)['"]\s*$/i.exec(text);
+        if (createMatch) {
+            const file = createMatch[1] ?? 'unknown';
+            const body = createMatch[2] ?? '';
+            const { writeFileSync, mkdirSync } = await import('node:fs');
+            const { dirname } = await import('node:path');
+            const absolute = resolvePath(input.cwd, file);
+            try {
+                mkdirSync(dirname(absolute), { recursive: true });
+                writeFileSync(absolute, body, 'utf8');
+            }
+            catch (error) {
+                envelopes.push({
+                    kind: 'error',
+                    body: JSON.stringify({
+                        message: `write failed: ${error.message}`,
+                    }),
+                });
+                return envelopes;
+            }
+            envelopes.push({
+                kind: 'tool-call',
+                body: JSON.stringify({
+                    tool: 'Write',
+                    args: { file, content: body },
+                }),
+            });
+            envelopes.push({
+                kind: 'persona-turn',
+                body: `Pugi: wrote ${file}`,
+            });
+            return envelopes;
+        }
+        if (/^ты\s+кто/i.test(text) || /^who\s+are\s+you/i.test(text)) {
+            envelopes.push({
+                kind: 'persona-turn',
+                body: 'Pugi: я Pugi, твой co-pilot. (Пуджи, stub)',
+            });
+            return envelopes;
+        }
+        envelopes.push({
+            kind: 'persona-turn',
+            body: `Pugi: ${text} (stub)`,
+        });
+        // One-time banner on the first turn so operators see why the stub
+        // is firing. Suppressed on subsequent turns to keep the envelope
+        // stream noise-free.
+        if (input.turnIndex === 0) {
+            envelopes.push({ kind: 'system', body: banner });
+        }
+        return envelopes;
+    };
+}
+//# sourceMappingURL=headless-repl.js.map