@thxgg/steward 0.1.7 → 0.1.11

package/dist/host/src/executor.js

@@ -1,61 +1,215 @@
 import vm from 'node:vm';
 import { git, prds, repos, state } from './api/index.js';
+import { getStewardHelp } from './help.js';
 const MAX_OUTPUT_SIZE = 50_000;
 const EXECUTION_TIMEOUT_MS = 30_000;
 const MAX_TIMERS = 100;
+const MAX_LOG_ENTRIES = 200;
+const MAX_LOG_OUTPUT_SIZE = 20_000;
+const MAX_LOG_ENTRY_SIZE = 2_000;
 export class ExecutionError extends Error {
-    stackTrace;
-    constructor(message, stackTrace) {
+    options;
+    constructor(message, options) {
         super(message);
-        this.stackTrace = stackTrace;
+        this.options = options;
         this.name = 'ExecutionError';
     }
 }
-function truncateOutput(result) {
-    if (result === undefined) {
-        return undefined;
-    }
-    let json;
+function safeJsonStringify(value) {
+    const seen = new WeakSet();
     try {
-        json = JSON.stringify(result, null, 2);
+        return JSON.stringify(value, (_key, currentValue) => {
+            if (typeof currentValue === 'bigint') {
+                return `${currentValue}n`;
+            }
+            if (typeof currentValue === 'function') {
+                const functionName = currentValue.name ? ` ${currentValue.name}` : '';
+                return `[Function${functionName}]`;
+            }
+            if (typeof currentValue === 'symbol') {
+                return currentValue.toString();
+            }
+            if (typeof currentValue === 'object' && currentValue !== null) {
+                if (seen.has(currentValue)) {
+                    return '[Circular]';
+                }
+                seen.add(currentValue);
+            }
+            return currentValue;
+        });
     }
     catch {
+        return undefined;
+    }
+}
+function formatLogValue(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    const json = safeJsonStringify(value);
+    if (json !== undefined) {
+        return json;
+    }
+    return String(value);
+}
+function truncateResult(result) {
+    if (result === undefined) {
         return {
-            _unserializable: true,
-            preview: String(result)
+            result: null,
+            truncatedResult: false,
+            resultWasUndefined: true
+        };
+    }
+    const json = safeJsonStringify(result);
+    if (json === undefined) {
+        return {
+            result: {
+                _unserializable: true,
+                preview: String(result)
+            },
+            truncatedResult: false,
+            resultWasUndefined: false
         };
     }
     if (json.length <= MAX_OUTPUT_SIZE) {
-        return result;
+        return {
+            result,
+            truncatedResult: false,
+            resultWasUndefined: false
+        };
     }
     return {
-        _truncated: true,
-        size: json.length,
-        preview: json.slice(0, MAX_OUTPUT_SIZE),
-        message: `Output truncated (${json.length} chars, showing first ${MAX_OUTPUT_SIZE})`
+        result: {
+            _truncated: true,
+            size: json.length,
+            preview: json.slice(0, MAX_OUTPUT_SIZE),
+            message: `Output truncated (${json.length} chars, showing first ${MAX_OUTPUT_SIZE})`
+        },
+        truncatedResult: true,
+        resultWasUndefined: false
+    };
+}
+function normalizeFailure(error) {
+    if (error instanceof ExecutionError) {
+        return {
+            code: error.options?.code || 'EXECUTION_ERROR',
+            message: error.message,
+            ...(error.options?.stackTrace && { stack: error.options.stackTrace }),
+            ...(error.options?.details !== undefined && { details: error.options.details })
+        };
+    }
+    if (error instanceof Error) {
+        const { code, details } = error;
+        return {
+            code: typeof code === 'string' ? code : 'EXECUTION_ERROR',
+            message: error.message,
+            ...(error.stack && { stack: error.stack }),
+            ...(details !== undefined && { details })
+        };
+    }
+    return {
+        code: 'EXECUTION_ERROR',
+        message: String(error)
     };
 }
 export async function execute(code) {
+    const startedAt = Date.now();
+    const logs = [];
+    let totalLogChars = 0;
+    let logsTruncated = false;
+    const appendLog = (level, args) => {
+        if (logs.length >= MAX_LOG_ENTRIES) {
+            logsTruncated = true;
+            return;
+        }
+        let message = args.map(formatLogValue).join(' ');
+        if (message.length > MAX_LOG_ENTRY_SIZE) {
+            message = `${message.slice(0, MAX_LOG_ENTRY_SIZE)}...`;
+            logsTruncated = true;
+        }
+        if (totalLogChars + message.length > MAX_LOG_OUTPUT_SIZE) {
+            logsTruncated = true;
+            return;
+        }
+        totalLogChars += message.length;
+        logs.push({
+            level,
+            message,
+            timestamp: new Date().toISOString()
+        });
+    };
+    const buildEnvelope = (params) => ({
+        ok: params.ok,
+        result: params.result,
+        logs,
+        error: params.error,
+        meta: {
+            timeoutMs: EXECUTION_TIMEOUT_MS,
+            durationMs: Date.now() - startedAt,
+            truncatedResult: params.truncatedResult,
+            truncatedLogs: logsTruncated,
+            resultWasUndefined: params.resultWasUndefined
+        }
+    });
     if (!code || !code.trim()) {
-        throw new ExecutionError('Code cannot be empty');
+        const error = normalizeFailure(new ExecutionError('Code cannot be empty', { code: 'EMPTY_CODE' }));
+        return buildEnvelope({
+            ok: false,
+            result: null,
+            error,
+            truncatedResult: false,
+            resultWasUndefined: false
+        });
     }
     const timers = new Set();
+    let executionTimeout = null;
+    let asyncCallbackError = null;
+    const wrapTimerHandler = (handler) => {
+        return () => {
+            try {
+                handler();
+            }
+            catch (error) {
+                const normalizedError = error instanceof Error
+                    ? error
+                    : new Error(String(error));
+                asyncCallbackError = normalizedError;
+                appendLog('error', ['Timer callback error:', normalizedError.message]);
+            }
+        };
+    };
+    const ensureTimerHandler = (handler) => {
+        if (typeof handler !== 'function') {
+            throw new ExecutionError('Timer handler must be a function', {
+                code: 'INVALID_TIMER_HANDLER'
+            });
+        }
+        return wrapTimerHandler(handler);
+    };
     const sandbox = {
         repos,
         prds,
         git,
         state,
+        steward: {
+            help: () => getStewardHelp()
+        },
         console: {
-            log: (...args) => console.log('[codemode]', ...args),
-            error: (...args) => console.error('[codemode]', ...args)
+            log: (...args) => appendLog('log', args),
+            info: (...args) => appendLog('info', args),
+            warn: (...args) => appendLog('warn', args),
+            error: (...args) => appendLog('error', args)
         },
         setTimeout: (handler, timeout) => {
             if (timers.size >= MAX_TIMERS) {
-                throw new Error(`Timer limit exceeded (max ${MAX_TIMERS})`);
+                throw new ExecutionError(`Timer limit exceeded (max ${MAX_TIMERS})`, {
+                    code: 'TIMER_LIMIT'
+                });
             }
+            const wrappedHandler = ensureTimerHandler(handler);
             const timer = setTimeout(() => {
                 timers.delete(timer);
-                handler();
+                wrappedHandler();
             }, timeout);
             timers.add(timer);
             return timer;
@@ -66,9 +220,12 @@ export async function execute(code) {
         },
         setInterval: (handler, timeout) => {
             if (timers.size >= MAX_TIMERS) {
-                throw new Error(`Timer limit exceeded (max ${MAX_TIMERS})`);
+                throw new ExecutionError(`Timer limit exceeded (max ${MAX_TIMERS})`, {
+                    code: 'TIMER_LIMIT'
+                });
             }
-            const timer = setInterval(handler, timeout);
+            const wrappedHandler = ensureTimerHandler(handler);
+            const timer = setInterval(wrappedHandler, timeout);
             timers.add(timer);
             return timer;
         },
@@ -88,18 +245,47 @@ export async function execute(code) {
             filename: 'codemode.js'
         });
         const context = vm.createContext(sandbox);
-        const result = await script.runInContext(context, {
+        const executionPromise = Promise.resolve(script.runInContext(context, {
             timeout: EXECUTION_TIMEOUT_MS
+        }));
+        const timeoutPromise = new Promise((_resolve, reject) => {
+            executionTimeout = setTimeout(() => {
+                reject(new ExecutionError(`Execution timed out after ${EXECUTION_TIMEOUT_MS}ms`, {
+                    code: 'TIMEOUT'
+                }));
+            }, EXECUTION_TIMEOUT_MS);
+        });
+        const rawResult = await Promise.race([executionPromise, timeoutPromise]);
+        if (asyncCallbackError instanceof Error) {
+            throw new ExecutionError(asyncCallbackError.message, {
+                code: 'ASYNC_CALLBACK_ERROR',
+                stackTrace: asyncCallbackError.stack
+            });
+        }
+        const truncated = truncateResult(rawResult);
+        return buildEnvelope({
+            ok: true,
+            result: truncated.result,
+            error: null,
+            truncatedResult: truncated.truncatedResult,
+            resultWasUndefined: truncated.resultWasUndefined
         });
-        return truncateOutput(result);
     }
     catch (error) {
-        if (error instanceof Error) {
-            throw new ExecutionError(error.message, error.stack);
-        }
-        throw new ExecutionError(String(error));
+        const failure = normalizeFailure(error);
+        appendLog('error', [`${failure.code}: ${failure.message}`]);
+        return buildEnvelope({
+            ok: false,
+            result: null,
+            error: failure,
+            truncatedResult: false,
+            resultWasUndefined: false
+        });
     }
     finally {
+        if (executionTimeout) {
+            clearTimeout(executionTimeout);
+        }
         timers.forEach((timer) => {
             clearTimeout(timer);
             clearInterval(timer);

package/dist/host/src/help.js

@@ -0,0 +1,124 @@
+const HELP = {
+    version: 1,
+    envelope: {
+        ok: 'true on success, false on failure',
+        result: 'returned value from your code, or null when no return value exists',
+        logs: 'captured console output entries from this execution',
+        error: 'null on success, otherwise { code, message, stack?, details? }',
+        meta: {
+            timeoutMs: 'execution timeout limit in milliseconds',
+            durationMs: 'elapsed runtime in milliseconds',
+            truncatedResult: 'true when result is truncated to output limit',
+            truncatedLogs: 'true when logs are truncated to output limit',
+            resultWasUndefined: 'true when code finished without an explicit return value'
+        }
+    },
+    apis: {
+        repos: [
+            { signature: 'repos.list()', description: 'List registered repositories' },
+            { signature: 'repos.get(repoId)', description: 'Get one repository by id' },
+            {
+                signature: 'repos.current()',
+                description: 'Resolve current repository when exactly one is registered'
+            },
+            { signature: 'repos.add(path, name?)', description: 'Register repository path' },
+            { signature: 'repos.remove(repoId)', description: 'Remove repository by id' },
+            {
+                signature: 'repos.refreshGitRepos(repoId)',
+                description: 'Refresh discovered nested git repositories'
+            }
+        ],
+        prds: [
+            { signature: 'prds.list(repoId)', description: 'List PRDs for repository' },
+            { signature: 'prds.getDocument(repoId, prdSlug)', description: 'Load PRD markdown document' },
+            { signature: 'prds.getTasks(repoId, prdSlug)', description: 'Load tasks state for PRD' },
+            { signature: 'prds.getProgress(repoId, prdSlug)', description: 'Load progress state for PRD' },
+            {
+                signature: 'prds.getTaskCommits(repoId, prdSlug, taskId)',
+                description: 'Resolve task commit references'
+            }
+        ],
+        git: [
+            { signature: 'git.getCommits(repoId, shas, repoPath?)', description: 'Load commit metadata' },
+            { signature: 'git.getDiff(repoId, commit, repoPath?)', description: 'Load full commit diff' },
+            {
+                signature: 'git.getFileDiff(repoId, commit, file, repoPath?)',
+                description: 'Load diff hunks for one file'
+            },
+            {
+                signature: 'git.getFileContent(repoId, commit, file, repoPath?)',
+                description: 'Load file content at commit'
+            }
+        ],
+        state: [
+            { signature: 'state.get(repoId, slug)', description: 'Load stored state by repo id' },
+            { signature: 'state.getByPath(repoPath, slug)', description: 'Load stored state by repo path' },
+            {
+                signature: 'state.getCurrent(slug)',
+                description: 'Load state for current repository when unambiguous'
+            },
+            { signature: 'state.summaries(repoId)', description: 'Load PRD state summaries by repo id' },
+            { signature: 'state.summariesByPath(repoPath)', description: 'Load PRD state summaries by path' },
+            {
+                signature: 'state.summariesCurrent()',
+                description: 'Load state summaries for current repository when unambiguous'
+            },
+            { signature: 'state.upsert(repoId, slug, payload)', description: 'Save tasks/progress/notes by repo id' },
+            {
+                signature: 'state.upsertByPath(repoPath, slug, payload)',
+                description: 'Save tasks/progress/notes by repo path'
+            },
+            {
+                signature: 'state.upsertCurrent(slug, payload)',
+                description: 'Save state in current repository when unambiguous'
+            }
+        ]
+    },
+    examples: [
+        {
+            title: 'List repos and PRDs',
+            code: `const allRepos = await repos.list()\n\nreturn await Promise.all(allRepos.map(async (repo) => ({\n  id: repo.id,\n  name: repo.name,\n  prds: await prds.list(repo.id)\n})))`
+        },
+        {
+            title: 'Use current repo helper',
+            code: `const repo = await repos.current()\nconst slug = 'prd-viewer'\n\nreturn {\n  repo,\n  tasks: await prds.getTasks(repo.id, slug),\n  progress: await prds.getProgress(repo.id, slug)\n}`
+        },
+        {
+            title: 'Upsert without repoId',
+            code: `await state.upsertCurrent('prd-viewer', {\n  notes: '# Updated from MCP'\n})\n\nreturn { saved: true }`
+        }
+    ]
+};
+function formatMethodList(methods) {
+    return methods
+        .map((method) => `- \`${method.signature}\` - ${method.description}`)
+        .join('\n');
+}
+export function getStewardHelp() {
+    return JSON.parse(JSON.stringify(HELP));
+}
+export function getExecuteToolDescription() {
+    return [
+        'Run codemode JavaScript with repos, prds, git, and state APIs.',
+        '',
+        'Execution always returns a structured JSON envelope:',
+        '`{ ok, result, logs, error, meta }`',
+        '',
+        'In-sandbox discovery helper:',
+        '- `steward.help()`',
+        '',
+        'Repository APIs:',
+        formatMethodList(HELP.apis.repos),
+        '',
+        'PRD APIs:',
+        formatMethodList(HELP.apis.prds),
+        '',
+        'Git APIs:',
+        formatMethodList(HELP.apis.git),
+        '',
+        'State APIs:',
+        formatMethodList(HELP.apis.state),
+        '',
+        'Use `return` in your code to set the envelope `result` field.'
+    ].join('\n');
+}

package/dist/host/src/mcp.js

@@ -1,57 +1,83 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
-import { execute, ExecutionError } from './executor.js';
-function formatError(error) {
-    if (error instanceof ExecutionError) {
-        return error.stackTrace
-            ? `${error.message}\n\n${error.stackTrace}`
-            : error.message;
-    }
-    if (error instanceof Error) {
-        return error.stack
-            ? `${error.message}\n\n${error.stack}`
-            : error.message;
-    }
-    return String(error);
-}
-function serializeResult(result) {
-    if (result === undefined) {
-        return 'undefined';
-    }
+import { assertSqliteRuntimeSupport } from '../../server/utils/db.js';
+import { execute } from './executor.js';
+import { getExecuteToolDescription } from './help.js';
+function serializeEnvelope(envelope) {
     try {
-        return JSON.stringify(result, null, 2);
+        return JSON.stringify(envelope, null, 2);
     }
     catch {
-        return String(result);
+        const fallback = {
+            ok: false,
+            result: null,
+            logs: [],
+            error: {
+                code: 'SERIALIZATION_ERROR',
+                message: 'Failed to serialize execution envelope'
+            },
+            meta: {
+                timeoutMs: 30_000,
+                durationMs: 0,
+                truncatedResult: false,
+                truncatedLogs: false,
+                resultWasUndefined: false
+            }
+        };
+        return JSON.stringify(fallback, null, 2);
     }
 }
+function buildUnexpectedErrorEnvelope(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const stack = error instanceof Error ? error.stack : undefined;
+    return {
+        ok: false,
+        result: null,
+        logs: [],
+        error: {
+            code: 'MCP_EXECUTION_FAILURE',
+            message,
+            ...(stack && { stack })
+        },
+        meta: {
+            timeoutMs: 30_000,
+            durationMs: 0,
+            truncatedResult: false,
+            truncatedLogs: false,
+            resultWasUndefined: false
+        }
+    };
+}
 export async function runMcpServer() {
+    await assertSqliteRuntimeSupport();
     const server = new McpServer({
         name: 'steward',
         version: '0.1.0'
     });
-    server.tool('execute', 'Run codemode JavaScript with repos, prds, git, and state APIs.', {
-        code: z.string().min(1)
+    server.tool('execute', getExecuteToolDescription(), {
+        code: z.string().optional()
     }, async ({ code }) => {
         try {
-            const result = await execute(code);
+            const envelope = await execute(code || '');
             return {
+                isError: !envelope.ok,
                 content: [
                     {
                         type: 'text',
-                        text: serializeResult(result)
+                        text: serializeEnvelope(envelope)
                     }
                 ]
             };
         }
         catch (error) {
+            const envelope = buildUnexpectedErrorEnvelope(error);
             return {
                 isError: true,
                 content: [
                     {
                         type: 'text',
-                        text: formatError(error)
+                        text: serializeEnvelope(envelope)
                     }
                 ]
             };

package/dist/server/utils/db.js

@@ -3,7 +3,19 @@ import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 const DEFAULT_DATA_HOME = process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share');
 const DEFAULT_DB_PATH = join(DEFAULT_DATA_HOME, 'prd', 'state.db');
+const SQLITE_ENABLE_FLAG = '--experimental-sqlite';
+const SQLITE_DISABLE_FLAG = '--no-experimental-sqlite';
 let adapterPromise = null;
+export class SqliteRuntimeError extends Error {
+    code;
+    details;
+    constructor(message, details) {
+        super(message);
+        this.name = 'SqliteRuntimeError';
+        this.code = 'SQLITE_RUNTIME_UNSUPPORTED';
+        this.details = details;
+    }
+}
 function coerceChanges(result) {
     if (!result || typeof result !== 'object') {
         return 0;
@@ -22,11 +34,84 @@ function resolveDbPath() {
     }
     return DEFAULT_DB_PATH;
 }
+function formatNodeRuntimeHint() {
+    const nodeOptions = process.env.NODE_OPTIONS || '';
+    const hasDisableFlag = process.execArgv.includes(SQLITE_DISABLE_FLAG)
+        || nodeOptions.includes(SQLITE_DISABLE_FLAG);
+    if (hasDisableFlag) {
+        return `Remove ${SQLITE_DISABLE_FLAG} from NODE_OPTIONS or Node arguments.`;
+    }
+    return `Use Node.js with built-in sqlite support, or launch with ${SQLITE_ENABLE_FLAG}.`;
+}
+function mapSqliteImportError(error, dbPath) {
+    if (!(error instanceof Error)) {
+        return new SqliteRuntimeError('SQLite runtime support is unavailable in this process.', {
+            runtime: 'node',
+            dbPath,
+            nodeVersion: process.version,
+            execPath: process.execPath,
+            execArgv: [...process.execArgv],
+            nodeOptions: process.env.NODE_OPTIONS || '',
+            originalMessage: String(error)
+        });
+    }
+    const code = error.code;
+    const isMissingBuiltin = typeof code === 'string'
+        && code === 'ERR_UNKNOWN_BUILTIN_MODULE'
+        && error.message.includes('node:sqlite');
+    const isMissingModule = typeof code === 'string'
+        && code === 'ERR_MODULE_NOT_FOUND'
+        && error.message.includes('node:sqlite');
+    if (!isMissingBuiltin && !isMissingModule) {
+        return error;
+    }
+    return new SqliteRuntimeError(`SQLite runtime support is unavailable for Steward (${process.version}). ${formatNodeRuntimeHint()}`, {
+        runtime: 'node',
+        dbPath,
+        nodeVersion: process.version,
+        execPath: process.execPath,
+        execArgv: [...process.execArgv],
+        nodeOptions: process.env.NODE_OPTIONS || '',
+        originalCode: typeof code === 'string' ? code : undefined,
+        originalMessage: error.message
+    });
+}
+async function loadNodeSqlite(dbPath) {
+    try {
+        return await import('node:sqlite');
+    }
+    catch (error) {
+        throw mapSqliteImportError(error, dbPath);
+    }
+}
 export function getDbPath() {
     return resolveDbPath();
 }
+export async function assertSqliteRuntimeSupport() {
+    const dbPath = resolveDbPath();
+    const isBunRuntime = typeof globalThis.Bun !== 'undefined';
+    if (isBunRuntime) {
+        try {
+            const bunModuleName = 'bun:sqlite';
+            await import(bunModuleName);
+            return;
+        }
+        catch (error) {
+            const code = error instanceof Error
+                ? error.code
+                : undefined;
+            throw new SqliteRuntimeError('SQLite runtime support is unavailable in Bun runtime.', {
+                runtime: 'bun',
+                dbPath,
+                originalCode: typeof code === 'string' ? code : undefined,
+                originalMessage: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+    await loadNodeSqlite(dbPath);
+}
 async function createNodeAdapter(dbPath) {
-    const sqliteModule = await import('node:sqlite');
+    const sqliteModule = await loadNodeSqlite(dbPath);
     const db = new sqliteModule.DatabaseSync(dbPath);
     return {
         exec(sql) {