@spexcode/spec-cli 0.6.5

package/dist/execution-trace.js

@@ -0,0 +1,475 @@
+import { execFileSync } from 'node:child_process';
+import { closeSync, openSync, readFileSync, readSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const cache = new Map();
+const sessionJsonlPaths = new Map();
+const localStoreCache = new Map();
+const emptyTrace = (turn, revision = '0') => ({
+    revision: `${turn?.token ?? '0'}:${revision}`,
+    turnId: turn?.token ?? null,
+    workingNote: null,
+    steps: [],
+});
+const object = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+const items = (value) => Array.isArray(value) ? value : [];
+const text = (value) => typeof value === 'string' && value.trim() ? value.trim() : null;
+const field = (value, ...names) => {
+    for (const name of names) {
+        const found = text(value[name]);
+        if (found)
+            return found;
+    }
+    return null;
+};
+const children = (dir) => { try {
+    return readdirSync(dir).sort().reverse();
+}
+catch {
+    return [];
+} };
+const sensitive = /(token|secret|password|authorization|bearer|cookie|credential|api[_-]?key|private[ _-]?key)/i;
+const detailFields = [
+    ['cmd', 'cmd'], ['command', 'command'], ['path', 'path'], ['file_path', 'path'],
+    ['query', 'query'], ['pattern', 'pattern'], ['url', 'url'], ['workdir', 'in'],
+];
+function toolKind(name) {
+    const normalized = name.toLowerCase();
+    if (/(search|browse|web)/.test(normalized))
+        return 'search';
+    if (/(read|list|find|grep|glob|stat)/.test(normalized))
+        return 'read';
+    if (/(write|edit|patch|create|delete|move|rename)/.test(normalized))
+        return 'write';
+    if (/(exec|shell|command|terminal|bash|npm|git)/.test(normalized))
+        return 'command';
+    return 'tool';
+}
+function toolLabel(name, kind) {
+    const labels = {
+        command: 'Run command', read: 'Read files', write: 'Update files', search: 'Search', tool: 'Use tool',
+    };
+    return name.trim() || labels[kind];
+}
+function recordInput(value) {
+    if (value && typeof value === 'object' && !Array.isArray(value))
+        return value;
+    if (typeof value !== 'string')
+        return null;
+    try {
+        const parsed = JSON.parse(value);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function sensitiveInput(value) {
+    if (typeof value === 'string')
+        return sensitive.test(value);
+    if (Array.isArray(value))
+        return value.some(sensitiveInput);
+    if (value && typeof value === 'object')
+        return Object.entries(value)
+            .some(([key, entry]) => sensitive.test(key) || sensitiveInput(entry));
+    return false;
+}
+function compactValue(key, value) {
+    const compact = String(value).trim().replace(/\s+/g, ' ');
+    if (key === 'path' || key === 'file_path' || key === 'workdir') {
+        const parts = compact.replace(/\\/g, '/').split('/').filter(Boolean);
+        return parts.slice(-2).join('/') || compact;
+    }
+    return compact.length > 96 ? `${compact.slice(0, 95)}...` : compact;
+}
+function detailFromInput(value) {
+    const input = recordInput(value);
+    if (!input || sensitiveInput(input))
+        return undefined;
+    const details = [];
+    for (const [key, title] of detailFields) {
+        const value = input[key];
+        if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean')
+            continue;
+        details.push(`${title}: ${compactValue(key, value)}`);
+        if (details.length === 2)
+            break;
+    }
+    const lineStart = input.line_start;
+    const lineEnd = input.line_end;
+    if (details.length < 2 && (typeof lineStart === 'number' || typeof lineEnd === 'number')) {
+        details.push(`lines: ${typeof lineStart === 'number' ? lineStart : 1}-${typeof lineEnd === 'number' ? lineEnd : lineStart}`);
+    }
+    return details.length ? details.join(' · ') : undefined;
+}
+function displayableNote(value) {
+    const note = text(value)?.replace(/\s+/g, ' ');
+    return note ? (note.length > 240 ? `${note.slice(0, 239)}...` : note) : null;
+}
+function stepFromInput(id, name, input, state) {
+    const kind = toolKind(name);
+    const detail = detailFromInput(input);
+    return { id, kind, label: toolLabel(name, kind), ...(detail ? { detail } : {}), state };
+}
+function timestamp(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value !== 'string' || !value.trim())
+        return null;
+    const number = Number(value);
+    if (Number.isFinite(number))
+        return number;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function identities(...values) {
+    const result = new Set();
+    for (const value of values)
+        for (const key of ['id', 'uuid', 'message_id', 'messageId', 'client_id', 'clientId', 'client_user_message_id', 'clientUserMessageId', 'promptId']) {
+            const id = field(value || {}, key);
+            if (id)
+                result.add(id);
+        }
+    return [...result];
+}
+function at(value) {
+    for (const key of ['timestamp', 'created_at', 'createdAt', 'created', 'time']) {
+        const found = timestamp(value[key]);
+        if (found !== null)
+            return found;
+    }
+    return null;
+}
+function isPrompt(content) {
+    if (typeof content === 'string')
+        return !!content.trim();
+    const blocks = items(content);
+    return blocks.some((block) => object(block)?.type !== 'tool_result');
+}
+function project(events, sourceRevision, turn) {
+    let start = -1;
+    if (!turn) {
+        for (const [index, event] of events.entries())
+            if (event.type === 'boundary')
+                start = index;
+    }
+    else {
+        const acceptedAt = timestamp(turn.acceptedAt);
+        const exact = events.flatMap((event, index) => event.type === 'boundary' && event.ids.includes(turn.token) ? [index] : []);
+        start = exact.length === 1 ? exact[0] : -1;
+        if (start < 0 && exact.length === 0 && acceptedAt !== null) {
+            const candidates = events.flatMap((event, index) => event.type === 'boundary' && event.at !== null && event.at >= acceptedAt
+                ? [{ index, at: event.at }] : []);
+            const earliest = candidates.reduce((value, candidate) => value === null || candidate.at < value ? candidate.at : value, null);
+            const matches = earliest === null ? [] : candidates.filter((candidate) => candidate.at === earliest);
+            if (matches.length === 1)
+                start = matches[0].index;
+        }
+    }
+    if (turn && start < 0)
+        return emptyTrace(turn, sourceRevision);
+    let note = null;
+    let steps = [];
+    for (let index = start + 1; index < events.length; index++) {
+        const event = events[index];
+        if (event.type === 'boundary')
+            return emptyTrace(turn, sourceRevision);
+        if (event.type === 'note') {
+            note = event.text;
+            steps = [];
+            continue;
+        }
+        if (event.type === 'call') {
+            if (note)
+                steps.push(event.step);
+            continue;
+        }
+        const step = steps.find((value) => value.id === event.id);
+        if (step)
+            steps[steps.indexOf(step)] = { ...step, state: 'done' };
+    }
+    return note
+        ? { revision: `${turn?.token ?? '0'}:${sourceRevision}`, turnId: turn?.token ?? null, workingNote: note, steps }
+        : emptyTrace(turn, sourceRevision);
+}
+function applyRolloutEvent(value, ordinal) {
+    const event = object(value);
+    const payload = object(event?.payload);
+    if (!event || !payload)
+        return [];
+    const result = [];
+    const type = field(payload, 'type');
+    if ((event.type === 'event_msg' && type === 'user_message')
+        || (event.type === 'response_item' && (type === 'message' || type === 'input_message') && payload.role === 'user')) {
+        result.push({ type: 'boundary', ids: identities(payload, event), at: at(payload) ?? at(event) });
+    }
+    if (event.type === 'event_msg' && type === 'agent_message' && payload.phase === 'commentary') {
+        const note = displayableNote(payload.message ?? payload.text);
+        if (note)
+            result.push({ type: 'note', text: note });
+    }
+    if (event.type === 'response_item' && (type === 'custom_tool_call' || type === 'function_call')) {
+        const name = field(payload, 'name', 'tool_name') || 'tool';
+        const id = field(payload, 'call_id', 'id') || `tool-${ordinal}`;
+        result.push({ type: 'call', step: stepFromInput(id, name, payload.input ?? payload.arguments ?? payload.args, 'running') });
+    }
+    if (event.type === 'response_item' && (type === 'custom_tool_call_output' || type === 'function_call_output')) {
+        const id = field(payload, 'call_id', 'id');
+        if (id)
+            result.push({ type: 'done', id });
+    }
+    if (event.type === 'event_msg' && type === 'web_search_end') {
+        result.push({ type: 'call', step: stepFromInput(field(payload, 'id', 'call_id') || `search-${ordinal}`, 'Search', payload, 'done') });
+    }
+    return result;
+}
+function applyProjectJsonlEvent(value, ordinal) {
+    const entry = object(value);
+    const message = object(entry?.message);
+    if (!entry || !message)
+        return [];
+    const result = [];
+    if (entry.type === 'user' && message.role === 'user' && isPrompt(message.content))
+        result.push({ type: 'boundary', ids: identities(entry, message), at: at(entry) ?? at(message) });
+    if (entry.type === 'assistant' && message.role === 'assistant')
+        for (const blockValue of items(message.content)) {
+            const block = object(blockValue);
+            if (block?.type === 'text') {
+                const note = displayableNote(block.text);
+                if (note)
+                    result.push({ type: 'note', text: note });
+            }
+            if (block?.type === 'tool_use') {
+                const id = field(block, 'id') || `tool-${ordinal}`;
+                result.push({ type: 'call', step: stepFromInput(id, field(block, 'name') || 'tool', block.input, 'running') });
+            }
+        }
+    if (entry.type === 'user' && message.role === 'user')
+        for (const blockValue of items(message.content)) {
+            const block = object(blockValue);
+            if (block?.type === 'tool_result') {
+                const id = field(block, 'tool_use_id');
+                if (id)
+                    result.push({ type: 'done', id });
+            }
+        }
+    return result;
+}
+function applySessionJsonlEvent(value, ordinal) {
+    const entry = object(value);
+    const message = object(entry?.message);
+    if (!entry || entry.type !== 'message' || !message)
+        return [];
+    const result = [];
+    if (message.role === 'user' && isPrompt(message.content))
+        result.push({ type: 'boundary', ids: identities(entry, message), at: at(entry) ?? at(message) });
+    if (message.role === 'assistant')
+        for (const blockValue of items(message.content)) {
+            const block = object(blockValue);
+            if (block?.type === 'text') {
+                const note = displayableNote(block.text);
+                if (note)
+                    result.push({ type: 'note', text: note });
+            }
+            if (block?.type === 'toolCall') {
+                const id = field(block, 'id') || `tool-${ordinal}`;
+                result.push({ type: 'call', step: stepFromInput(id, field(block, 'name') || 'tool', block.arguments, 'running') });
+            }
+        }
+    if (message.role === 'toolResult') {
+        const id = field(message, 'toolCallId');
+        if (id)
+            result.push({ type: 'done', id });
+    }
+    return result;
+}
+function completeLines(buffer) {
+    const lines = [];
+    let start = 0;
+    for (let index = 0; index < buffer.length; index++) {
+        if (buffer[index] !== 10)
+            continue;
+        if (index > start)
+            lines.push(buffer.subarray(start, index));
+        start = index + 1;
+    }
+    return { lines, remainder: buffer.subarray(start) };
+}
+function readFrom(path, start) {
+    let fd = null;
+    try {
+        const size = statSync(path).size;
+        if (size <= start)
+            return Buffer.alloc(0);
+        const chunk = Buffer.allocUnsafe(size - start);
+        fd = openSync(path, 'r');
+        readSync(fd, chunk, 0, chunk.length, start);
+        return chunk;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== null)
+            closeSync(fd);
+    }
+}
+function readIncremental(path, apply, turn) {
+    if (!path)
+        return emptyTrace(turn);
+    let size;
+    try {
+        size = statSync(path).size;
+    }
+    catch {
+        return emptyTrace(turn);
+    }
+    const prior = cache.get(path);
+    const trace = prior && prior.size <= size
+        ? { ...prior, events: [...prior.events] }
+        : { size: 0, remainder: Buffer.alloc(0), events: [] };
+    const appended = readFrom(path, trace.size);
+    if (appended === null)
+        return emptyTrace(turn);
+    const { lines, remainder } = completeLines(Buffer.concat([trace.remainder, appended]));
+    for (const [index, line] of lines.entries()) {
+        try {
+            trace.events.push(...apply(JSON.parse(line.toString('utf8')), trace.size + index));
+        }
+        catch { /* malformed native data is ignored */ }
+    }
+    trace.size = size;
+    trace.remainder = remainder;
+    cache.set(path, trace);
+    return project(trace.events, String(size), turn);
+}
+const codexSessionsDir = () => join(process.env.CODEX_HOME || join(homedir(), '.codex'), 'sessions');
+export function codexRolloutPath(threadId, root = codexSessionsDir()) {
+    for (const year of children(root))
+        for (const month of children(join(root, year)))
+            for (const day of children(join(root, year, month))) {
+                const dir = join(root, year, month, day);
+                const file = children(dir).find((name) => name.includes(threadId));
+                if (file)
+                    return join(dir, file);
+            }
+    return null;
+}
+export function readCodexExecutionTrace(threadId, turn, root = codexSessionsDir()) {
+    return readIncremental(codexRolloutPath(threadId, root), applyRolloutEvent, turn);
+}
+const projectTranscriptRoot = () => join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'), 'projects');
+function projectJsonlPath(threadId, root = projectTranscriptRoot()) {
+    for (const project of children(root)) {
+        const path = join(root, project, `${threadId}.jsonl`);
+        try {
+            if (statSync(path).isFile())
+                return path;
+        }
+        catch { /* try next */ }
+    }
+    return null;
+}
+export function readProjectJsonlExecutionTrace(threadId, turn, root = projectTranscriptRoot()) {
+    return readIncremental(projectJsonlPath(threadId, root), applyProjectJsonlEvent, turn);
+}
+const sessionJsonlRoot = () => join(process.env.SPEXCODE_PI_AGENT_DIR || join(homedir(), '.pi', 'agent'), 'sessions');
+function sessionJsonlPath(threadId, root = sessionJsonlRoot()) {
+    const key = `${root}:${threadId}`;
+    const cached = sessionJsonlPaths.get(key);
+    if (cached) {
+        try {
+            if (statSync(cached).isFile())
+                return cached;
+        }
+        catch {
+            sessionJsonlPaths.delete(key);
+        }
+    }
+    for (const directory of children(root))
+        for (const file of children(join(root, directory))) {
+            if (!file.endsWith('.jsonl'))
+                continue;
+            const path = join(root, directory, file);
+            try {
+                const header = object(JSON.parse(readFileSync(path, 'utf8').split('\n', 1)[0]));
+                if (header?.type === 'session' && header.id === threadId) {
+                    sessionJsonlPaths.set(key, path);
+                    return path;
+                }
+            }
+            catch { /* unreadable entries are not a match */ }
+        }
+    return null;
+}
+export function readSessionJsonlExecutionTrace(threadId, turn, root = sessionJsonlRoot()) {
+    return readIncremental(sessionJsonlPath(threadId, root), applySessionJsonlEvent, turn);
+}
+const localStoreRoot = () => process.env.SPEXCODE_OPENCODE_DATA_DIR
+    || join(process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share'), 'opencode');
+function readLocalExport(threadId) {
+    return execFileSync(process.env.SPEXCODE_OPENCODE_CMD || 'opencode', ['export', threadId, '--sanitize'], {
+        encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    });
+}
+function localStoreRevision(root) {
+    try {
+        const database = statSync(join(root, 'opencode.db'));
+        let writeAheadLog = '0:0';
+        try {
+            const stat = statSync(join(root, 'opencode.db-wal'));
+            writeAheadLog = `${stat.size}:${Math.floor(stat.mtimeMs)}`;
+        }
+        catch { /* a checkpointed database has no separate write-ahead log */ }
+        return `${database.size}:${Math.floor(database.mtimeMs)}:${writeAheadLog}`;
+    }
+    catch {
+        return null;
+    }
+}
+function localStoreEvents(value) {
+    const events = [];
+    for (const messageValue of items(object(value)?.messages)) {
+        const message = object(messageValue);
+        const info = object(message?.info);
+        if (!message || !info)
+            continue;
+        if (info.role === 'user')
+            events.push({ type: 'boundary', ids: identities(info, message), at: at(object(info.time) || info) });
+        if (info.role !== 'assistant')
+            continue;
+        for (const partValue of items(message.parts)) {
+            const part = object(partValue);
+            if (part?.type === 'text') {
+                const note = displayableNote(part.text);
+                if (note)
+                    events.push({ type: 'note', text: note });
+            }
+            if (part?.type === 'tool') {
+                const state = object(part.state);
+                const status = field(state || {}, 'status')?.toLowerCase() || '';
+                const id = field(part, 'callID', 'id') || `tool-${events.length}`;
+                events.push({ type: 'call', step: stepFromInput(id, field(part, 'tool') || 'tool', state?.input, /completed|error|cancelled/.test(status) ? 'done' : 'running') });
+            }
+        }
+    }
+    return events;
+}
+export function readLocalStoreExecutionTrace(threadId, turn, root = localStoreRoot(), load = readLocalExport) {
+    const revision = localStoreRevision(root);
+    if (!revision)
+        return emptyTrace(turn);
+    const key = `${root}:${threadId}`;
+    let cached = localStoreCache.get(key);
+    if (!cached || cached.revision !== revision) {
+        try {
+            cached = { revision, events: localStoreEvents(JSON.parse(load(threadId))) };
+            localStoreCache.set(key, cached);
+        }
+        catch {
+            return emptyTrace(turn, revision);
+        }
+    }
+    return project(cached.events, revision, turn);
+}
+export const noExecutionTrace = (_threadId, _turn) => null;

package/dist/file-write.d.ts

@@ -0,0 +1,2 @@
+export declare function writeFileIfChanged(path: string, content: string | Uint8Array): boolean;
+export declare function copyFileIfChanged(source: string, target: string): boolean;

package/dist/file-write.js

@@ -0,0 +1,26 @@
+import { copyFileSync, readFileSync, writeFileSync } from 'node:fs';
+export function writeFileIfChanged(path, content) {
+    const next = Buffer.from(content);
+    try {
+        if (readFileSync(path).equals(next))
+            return false;
+    }
+    catch (error) {
+        if (error?.code !== 'ENOENT')
+            throw error;
+    }
+    writeFileSync(path, content);
+    return true;
+}
+export function copyFileIfChanged(source, target) {
+    try {
+        if (readFileSync(target).equals(readFileSync(source)))
+            return false;
+    }
+    catch (error) {
+        if (error?.code !== 'ENOENT')
+            throw error;
+    }
+    copyFileSync(source, target);
+    return true;
+}

package/dist/flat.d.ts

@@ -0,0 +1,89 @@
+import { type Harness } from './harness.js';
+export declare const FLAT_BRANCH = "flatcode";
+export declare const FLAT_AGENT_CHOICES: readonly [{
+    readonly name: "claude";
+    readonly label: "Claude Code";
+    readonly harness: "claude";
+    readonly cmd: "claude";
+}, {
+    readonly name: "codex";
+    readonly label: "Codex";
+    readonly harness: "codex";
+    readonly cmd: "codex";
+}, {
+    readonly name: "opencode";
+    readonly label: "OpenCode";
+    readonly harness: "opencode";
+    readonly cmd: "opencode";
+}, {
+    readonly name: "pi";
+    readonly label: "Pi";
+    readonly harness: "pi";
+    readonly cmd: "pi";
+}];
+export declare const languageName: (code: string) => string;
+export type FlatGate = {
+    errors: number;
+    governed: number;
+    uncovered: number;
+    coverage: number;
+    errorFindings: readonly string[];
+    uncoveredFiles: readonly string[];
+    sourceFiles: readonly string[];
+};
+export type FlatProfile = {
+    sourceExtensions: readonly string[];
+    governedRoots: readonly string[];
+    languages: readonly string[];
+    fileCount: number;
+};
+export declare function profileFiles(files: readonly string[]): FlatProfile;
+export declare function readGate(payload: string): FlatGate;
+export declare const gatePassed: (gate: FlatGate, coverageFloor: number) => boolean;
+export declare function confirmProfile(proposed: FlatProfile, sourceFiles: readonly string[]): FlatProfile;
+type FlatTurnHarness = {
+    harness: Harness;
+    cmd: string;
+    name: string;
+    harnessId: string;
+};
+export type FlatOptions = {
+    target: string;
+    out?: string;
+    launcher?: string;
+    rounds?: number;
+    coverage?: number;
+    lang?: string;
+};
+export type FlatResult = {
+    out: string;
+    repo: string;
+    source: string;
+    revision: string;
+    rounds: number;
+    gate: FlatGate;
+    passed: boolean;
+    profile: FlatProfile;
+};
+export declare function flatNew(options: FlatOptions, log?: (line: string) => void, choose?: (root: string) => Promise<FlatTurnHarness>): Promise<FlatResult>;
+export declare function publicShellDir(): string;
+export declare function flatSite(flatDir: string, log?: (line: string) => void): Promise<{
+    site: string;
+    nodes: number;
+}>;
+export declare function gallerySlug(source: string): string;
+export type GalleryEntry = {
+    slug: string;
+    source: string;
+    revision: string;
+    coverage: number;
+    governed: number;
+    nodes: number;
+    passed: boolean;
+    languages: readonly string[];
+    lang: string;
+};
+export declare function galleryIndexHtml(entries: readonly GalleryEntry[]): string;
+export declare function flatGallery(out: string, flatDirs: readonly string[], log?: (line: string) => void): Promise<GalleryEntry[]>;
+export declare function runFlat(argv: readonly string[]): Promise<number>;
+export {};