@spexcode/spec-cli 0.6.5

package/dist/pi-headless.js

@@ -0,0 +1,196 @@
+import { createServer } from 'node:net';
+import { spawn } from 'node:child_process';
+import { mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { controlRequest, withTimeout } from './headless-controller.js';
+import { shQuote } from './sh.js';
+const PKG = fileURLToPath(new URL('..', import.meta.url));
+const SPEX = join(PKG, 'bin', 'spex.mjs');
+const CONTROL_TIMEOUT_MS = 30_000;
+const START_TIMEOUT_MS = 30_000;
+const TERM_EXIT_GRACE_MS = 500;
+const KILL_EXIT_GRACE_MS = 2_000;
+/** The resident controller socket is distinct from pi's per-turn rendezvous socket. */
+export const piHeadlessSock = (id) => join(tmpdir(), `spexcode-ph-${id}.sock`);
+export function piHeadlessLaunchCommand(id, runtimeDir, piCmd) {
+    return [shQuote(SPEX), 'internal', 'pi-headless-run', shQuote(id), shQuote(runtimeDir), shQuote(piCmd), '--'].join(' ');
+}
+export const deliverViaPiHeadless = (rec, text) => controlRequest(piHeadlessSock(rec.session), { type: 'deliver', text, mid: rec.mid }, {
+    name: 'pi-headless', session: rec.session, timeoutMs: CONTROL_TIMEOUT_MS,
+    rejected: 'pi-headless controller rejected the request',
+});
+// The resident controller and a running pi turn own two per-session listeners. The generic lifecycle
+// teardown has already proved and removed the exact controller leaf before this runs; cold filing is valid
+// only once neither listener can still accept work for this session.
+export async function piHeadlessColdRuntime(rec) {
+    const { listenerAt, rvSock } = await import('./harness.js');
+    const paths = [piHeadlessSock(rec.session), rvSock(rec.session)];
+    const probes = await Promise.all(paths.map((path) => listenerAt(path)));
+    const pending = paths.filter((_, index) => probes[index] !== 'dead');
+    return pending.length
+        ? { ok: false, error: `pi-headless runtime is still ${probes.some((probe) => probe === 'live') ? 'live' : 'unproven'} (${pending.join(', ')})` }
+        : { ok: true };
+}
+export class PiHeadlessController {
+    id;
+    piCmd;
+    cwd;
+    server = null;
+    child = null;
+    controlQueue = Promise.resolve();
+    closing = false;
+    socketPath;
+    constructor(id, _runtimeDir, piCmd, cwd = process.cwd()) {
+        this.id = id;
+        this.piCmd = piCmd;
+        this.cwd = cwd;
+        this.socketPath = piHeadlessSock(id);
+    }
+    async start(initialPrompt) {
+        try {
+            rmSync(this.socketPath, { force: true });
+        }
+        catch { /* stale control socket is replaced at startup */ }
+        this.server = createServer((socket) => this.accept(socket));
+        await new Promise((resolve, reject) => {
+            const onError = (error) => { this.server?.off('listening', onListening); reject(error); };
+            const onListening = () => { this.server?.off('error', onError); resolve(); };
+            this.server.once('error', onError);
+            this.server.once('listening', onListening);
+            this.server.listen(this.socketPath);
+        });
+        if (initialPrompt)
+            void this.spawnTurn(initialPrompt, false).catch((error) => {
+                console.error(`[spex pi-headless] initial turn failed: ${error.message}`);
+            });
+    }
+    async close() {
+        if (this.closing)
+            return;
+        this.closing = true;
+        const child = this.child;
+        try {
+            if (child)
+                await this.terminateTurn(child);
+        }
+        finally {
+            await new Promise((resolve) => {
+                if (!this.server)
+                    return resolve();
+                this.server.close(() => resolve());
+            });
+            // same proof-before-removal rule as every other teardown (harness.ts unlinkSocks): a socket path is keyed
+            // by session id alone, so only a listener PROVEN dead is ours to unlink.
+            const { rvSock, unlinkSocks } = await import('./harness.js');
+            await unlinkSocks(this.socketPath, rvSock(this.id));
+        }
+    }
+    async terminateTurn(turn) {
+        if (turn.process.exitCode !== null)
+            return;
+        try {
+            turn.process.kill('SIGTERM');
+        }
+        catch { /* the child can leave between the exit check and signal */ }
+        if (await this.waitForExit(turn, TERM_EXIT_GRACE_MS))
+            return;
+        try {
+            turn.process.kill('SIGKILL');
+        }
+        catch { /* already gone */ }
+        await withTimeout(turn.exited, KILL_EXIT_GRACE_MS, `pi-headless turn did not exit for session ${this.id}`);
+    }
+    async waitForExit(turn, timeoutMs) {
+        try {
+            await withTimeout(turn.exited, timeoutMs, 'turn exit grace elapsed');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    accept(socket) {
+        socket.setEncoding('utf8');
+        let buffer = '';
+        let handled = false;
+        socket.on('data', (chunk) => {
+            if (handled)
+                return;
+            buffer += chunk;
+            const nl = buffer.indexOf('\n');
+            if (nl < 0)
+                return;
+            handled = true;
+            let request;
+            try {
+                request = JSON.parse(buffer.slice(0, nl));
+            }
+            catch (error) {
+                socket.end(`${JSON.stringify({ ok: false, error: `invalid control request: ${error.message}` })}\n`);
+                return;
+            }
+            this.controlQueue = this.controlQueue.then(async () => {
+                const result = await this.handle(request).catch((error) => ({ ok: false, error: error.message }));
+                socket.end(`${JSON.stringify(result)}\n`);
+            });
+        });
+    }
+    async handle(request) {
+        if (request.type !== 'deliver')
+            return { ok: false, error: 'unknown pi-headless control request' };
+        if (!request.text)
+            return { ok: false, error: 'empty prompt - nothing to deliver' };
+        // A live extension listener is an in-flight pi turn. Only a proven absent listener may cold-wake a saved
+        // session; an inconclusive probe must not start a duplicate turn.
+        const { deliverViaSocketOrWake } = await import('./harness.js');
+        return deliverViaSocketOrWake(this.id, request.text, request.mid, async () => {
+            if (this.child)
+                await withTimeout(this.child.exited, 5_000, `previous pi-headless turn did not exit for session ${this.id}`);
+            await this.spawnTurn(request.text, true);
+            return { ok: true };
+        }, `could not determine whether pi turn ${this.id} is live — prompt NOT delivered`);
+    }
+    async spawnTurn(text, resume) {
+        if (this.closing)
+            throw new Error('pi-headless controller is closing');
+        const mode = resume ? ['--session', this.id] : ['--session-id', this.id];
+        // Keep pi's default text mode. `--mode json` is intentionally omitted: it can hang in this runtime.
+        const args = ['-p', ...mode, text];
+        const command = `exec ${this.piCmd} ${args.map(shQuote).join(' ')}`;
+        const childProcess = spawn('/bin/sh', ['-lc', command], { cwd: this.cwd, env: process.env, stdio: ['ignore', 'pipe', 'pipe'] });
+        let resolveExit;
+        const exited = new Promise((resolve) => { resolveExit = resolve; });
+        const turn = { process: childProcess, exited };
+        this.child = turn;
+        childProcess.stdout?.pipe(process.stdout);
+        childProcess.stderr?.pipe(process.stderr);
+        childProcess.once('error', (error) => console.error(`[spex pi-headless] child spawn failed: ${error.message}`));
+        childProcess.once('close', (code) => {
+            if (this.child === turn)
+                this.child = null;
+            resolveExit(code);
+            if (code !== 0 && !this.closing)
+                void import('./harness.js').then(({ reportHeadlessTurnExit }) => reportHeadlessTurnExit(this.id, 'pi-headless', code, this.cwd));
+        });
+        await withTimeout(new Promise((resolve, reject) => {
+            childProcess.once('spawn', () => resolve());
+            childProcess.once('error', reject);
+        }), START_TIMEOUT_MS, `pi-headless child did not start for session ${this.id}`);
+    }
+}
+export async function runPiHeadlessController(id, runtimeDir, piCmd, tail) {
+    // runtimeDir is retained in the command shape for parity with claude-headless and future per-session output.
+    mkdirSync(join(runtimeDir, 'sessions', id), { recursive: true });
+    const controller = new PiHeadlessController(id, runtimeDir, piCmd);
+    const resume = tail[0] === '--session';
+    const prompt = resume ? undefined : tail[0] === '--session-id' ? tail.slice(2).join(' ') : tail.join(' ');
+    await controller.start(prompt);
+    await new Promise((resolve) => {
+        const stop = () => void controller.close().finally(resolve);
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+        process.once('SIGHUP', stop);
+    });
+}

package/dist/plugin-harness.d.ts

@@ -0,0 +1,21 @@
+export type PluginBundle = {
+    contract: string;
+    skills: {
+        name: string;
+        content: string;
+    }[];
+    agents: {
+        name: string;
+        content: string;
+    }[];
+    commands: {
+        name: string;
+        content: string;
+    }[];
+    spex: string;
+    version: string;
+};
+export declare function pluginBundleDir(proj: string, folder: string): string;
+export declare function emitPlugin(proj: string, folder: string, r: PluginBundle): void;
+export declare function cleanPlugin(proj: string, folder: string): void;
+export declare function pluginVersion(): string;

package/dist/plugin-harness.js

@@ -0,0 +1,146 @@
+import { mkdirSync, readFileSync, existsSync, readdirSync, rmSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { copyFileIfChanged, writeFileIfChanged } from './file-write.js';
+// @@@ plugin-harness - the PLUGIN BUNDLE emitter: materialize the whole SpexCode system into ONE self-contained
+// Claude-plugin bundle dropped into the host-agent-scanned folder [[harness-select]] resolved (e.g. `.adopter-a` /
+// `.claude` → <folder>/plugins/spexcode/). It is the plugin-target counterpart of the native per-harness
+// write [[harness-adapter]] does — chosen INSTEAD of the natives (plugin exclusivity), so [[harness-delivery]]'s
+// materialize prunes every native first, then emits this. The bundle follows the de-facto Claude-plugin schema
+// (a `.claude-plugin/plugin.json` pointing at hooks/skills/commands/agents); the host's discovery order is
+// `.adopter-a-plugin > .claude-plugin > .codex-plugin` and adopter-a/Claude both read a `.claude-plugin` directly, so
+// the ONE `.claude-plugin` bundle reaches AdopterA, Claude, and (future) Codex from a single emit.
+//
+// The contract is NOT delivered by an always-on CLAUDE.md block here (the bundle never touches the repo's own
+// files) — it maps to a SessionStart hook that emits hookSpecificOutput.additionalContext (the harness-neutral
+// injection Claude/adopter-a normalize, the superpowers pattern), so a plugin host gets the contract with no
+// --append-system-prompt. The hooks reuse the SAME dispatch.sh wiring as the natives, located via the host's
+// ${CLAUDE_PLUGIN_ROOT} variable; dispatch.sh's first arg is the harness id `plugin`, so its shell mirror
+// (harness.sh) parses payloads as the claude family (adopter-a/Claude share Claude's tool names + file_path).
+const PKG = fileURLToPath(new URL('..', import.meta.url)); // installed spec-cli root
+const HOOKS_SRC = join(PKG, 'hooks'); // the canonical dispatch.sh + harness.sh source
+const PLUGIN_NAME = 'spexcode';
+// the host substitutes ${CLAUDE_PLUGIN_ROOT} with the bundle's own absolute path before running a hook command
+// (the same variable adopter-a's hook-compat honours), so dispatch.sh/inject-contract.sh resolve regardless of
+// where the host scanned the bundle from.
+const PLUGIN_ROOT = '${CLAUDE_PLUGIN_ROOT}';
+// the lifecycle events the bundle binds — the Claude/adopter-a superset; a host that fires fewer (Codex) simply
+// never invokes the extras, so binding all is harmless and one emit serves every host.
+const PLUGIN_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop', 'StopFailure', 'Notification'];
+// the bundle dir for a plugin folder: <proj>/<folder>/plugins/spexcode — `<folder>` is the host's plugins-scan
+// root ([[harness-select]] requires it explicit), `plugins/<name>` the conventional bundle location under it.
+export function pluginBundleDir(proj, folder) {
+    return join(proj, folder, 'plugins', PLUGIN_NAME);
+}
+// the de-facto Claude-plugin manifest: name (the bundle identity clean() gates on), version, description, and
+// the component pointers Claude/adopter-a discover (hooks.json + the skills/commands/agents dirs).
+function pluginManifest(version) {
+    return JSON.stringify({
+        name: PLUGIN_NAME,
+        version,
+        description: 'SpexCode — spec-driven dev-flow contract, hooks, skills, commands & agents as one self-contained plugin.',
+        hooks: './hooks/hooks.json',
+        commands: './commands',
+        agents: './agents',
+        skills: './skills',
+    }, null, 2);
+}
+// hooks.json in the Claude/adopter-a-compatible shape { "hooks": { "<Event>": [{ "hooks": [command…] }] } }. Every
+// event → the SHARED dispatch.sh (`plugin` baked as its harness id, SPEX inherited by handlers); SessionStart
+// ALSO runs inject-contract.sh first, so the contract additionalContext lands alongside the normal dispatch.
+function pluginHooksJson(spex) {
+    const dispatch = (e) => `SPEX='${spex}' bash "${PLUGIN_ROOT}/hooks/dispatch.sh" plugin ${e}`;
+    const inject = `bash "${PLUGIN_ROOT}/hooks/inject-contract.sh"`;
+    const hooks = {};
+    for (const e of PLUGIN_EVENTS) {
+        const cmds = e === 'SessionStart'
+            ? [{ type: 'command', command: inject }, { type: 'command', command: dispatch(e) }]
+            : [{ type: 'command', command: dispatch(e) }];
+        hooks[e] = [{ hooks: cmds }];
+    }
+    return JSON.stringify({ hooks }, null, 2);
+}
+// the SessionStart hook OUTPUT carrying the contract as additionalContext. JSON-encoded HERE, at materialize time,
+// so the runtime hook is a trivial `cat` — never a fragile shell escaping of arbitrary contract prose.
+function contractContextJson(contract) {
+    return JSON.stringify({ hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: contract } }, null, 2);
+}
+// the SessionStart contract injector: print the pre-encoded additionalContext payload (the harness-neutral
+// stand-in for --append-system-prompt). A bare cat — all the encoding happened at materialize time.
+const INJECT_SH = `#!/usr/bin/env bash
+# Emit the SpexCode contract as SessionStart additionalContext — the harness-neutral contract injection (the
+# superpowers pattern; Claude/adopter-a normalize hookSpecificOutput.additionalContext) that replaces a plugin
+# host's missing --append-system-prompt. The JSON was written at materialize time, so this is a trivial cat.
+here="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+[ -f "$here/contract-context.json" ] && cat "$here/contract-context.json"
+exit 0
+`;
+// emit (or idempotently re-emit) the whole bundle into <folder>/plugins/spexcode.
+export function emitPlugin(proj, folder, r) {
+    const bundle = pluginBundleDir(proj, folder);
+    const meta = join(bundle, '.claude-plugin');
+    const hooksDir = join(bundle, 'hooks');
+    mkdirSync(meta, { recursive: true });
+    mkdirSync(hooksDir, { recursive: true });
+    writeFileIfChanged(join(meta, 'plugin.json'), pluginManifest(r.version));
+    // hooks: the SHARED dispatcher + its shell mirror (copied verbatim — the exact native wiring), the contract
+    // injector + its pre-encoded payload, and the event→dispatch binding.
+    copyFileIfChanged(join(HOOKS_SRC, 'dispatch.sh'), join(hooksDir, 'dispatch.sh'));
+    copyFileIfChanged(join(HOOKS_SRC, 'harness.sh'), join(hooksDir, 'harness.sh'));
+    writeFileIfChanged(join(hooksDir, 'inject-contract.sh'), INJECT_SH);
+    writeFileIfChanged(join(hooksDir, 'contract-context.json'), contractContextJson(r.contract));
+    writeFileIfChanged(join(hooksDir, 'hooks.json'), pluginHooksJson(r.spex));
+    // skills / agents / commands — the Claude-plugin layout, the SAME materialized contents as the native dirs.
+    reconcileBundleDirectory(join(bundle, 'skills'), new Set(r.skills.map((s) => s.name)));
+    reconcileBundleDirectory(join(bundle, 'agents'), new Set(r.agents.map((a) => `${a.name}.md`)));
+    reconcileBundleDirectory(join(bundle, 'commands'), new Set(r.commands.map((c) => `${c.name}.md`)));
+    for (const s of r.skills)
+        writeBundleFile(join(bundle, 'skills', s.name, 'SKILL.md'), s.content);
+    for (const a of r.agents)
+        writeBundleFile(join(bundle, 'agents', `${a.name}.md`), a.content);
+    for (const c of r.commands)
+        writeBundleFile(join(bundle, 'commands', `${c.name}.md`), c.content);
+}
+function reconcileBundleDirectory(dir, expectedNames) {
+    if (!existsSync(dir))
+        return;
+    for (const entry of readdirSync(dir)) {
+        if (!expectedNames.has(entry))
+            rmSync(join(dir, entry), { recursive: true, force: true });
+    }
+}
+function writeBundleFile(f, content) {
+    mkdirSync(dirname(f), { recursive: true });
+    writeFileIfChanged(f, content);
+}
+// the INVERSE of emitPlugin — prune the bundle when its folder is DESELECTED ([[harness-delivery]] tracks the
+// previously-emitted folders and cleans any the current set dropped, e.g. switching plugin→native or folder A→B).
+// Identity-gated on the bundle's own plugin.json `name`, so it removes ONLY a spexcode bundle, never a folder
+// the user populated with another plugin.
+export function cleanPlugin(proj, folder) {
+    const bundle = pluginBundleDir(proj, folder);
+    const manifest = join(bundle, '.claude-plugin', 'plugin.json');
+    if (!existsSync(manifest))
+        return;
+    try {
+        if (String(JSON.parse(readFileSync(manifest, 'utf8'))?.name) !== PLUGIN_NAME)
+            return;
+    }
+    catch {
+        return;
+    }
+    rmSync(bundle, { recursive: true, force: true });
+}
+// the bundle version stamped into plugin.json — the monorepo root `spexcode` package version (the published
+// artifact's version), falling back to the spec-cli package, then 0.0.0.
+export function pluginVersion() {
+    for (const p of [join(PKG, '..', 'package.json'), join(PKG, 'package.json')]) {
+        try {
+            const v = JSON.parse(readFileSync(p, 'utf8'))?.version;
+            if (v)
+                return String(v);
+        }
+        catch { /* keep trying */ }
+    }
+    return '0.0.0';
+}

package/dist/pty-bridge.d.ts

@@ -0,0 +1,10 @@
+export type Viewer = {
+    send: (data: Buffer) => void;
+    commitSize?: (cols: number, rows: number) => void;
+};
+export declare function attachViewer(id: string, viewer: Viewer): void;
+export declare function hideViewer(id: string, viewer: Viewer): void;
+export declare function detachViewer(id: string, viewer: Viewer): void;
+export declare function resizeBridge(id: string, viewer: Viewer, colsValue: number, rowsValue: number): void;
+export declare function forwardInput(id: string, viewer: Viewer, data: string): boolean;
+export declare function superviseBridges(intervalMs?: number): void;