@thxgg/steward 0.1.7 → 0.1.10

package/dist/host/src/mcp.js

@@ -1,57 +1,81 @@
 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 { 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() {
     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/docs/MCP.md

@@ -58,7 +58,31 @@ Example MCP client config:
 
 Your code is wrapped in an async function, so you can use `await` directly.
 
-Return values are JSON-stringified in the MCP response.
+Each call returns a JSON envelope:
+
+```json
+{
+  "ok": true,
+  "result": {},
+  "logs": [],
+  "error": null,
+  "meta": {
+    "timeoutMs": 30000,
+    "durationMs": 12,
+    "truncatedResult": false,
+    "truncatedLogs": false,
+    "resultWasUndefined": false
+  }
+}
+```
+
+- `result` is `null` when your code does not explicitly return a value.
+- `logs` contains captured `console.log/info/warn/error` output from sandbox code.
+- `error` is populated with `{ code, message, stack?, details? }` on failure.
+
+In-sandbox discovery helper:
+
+- `steward.help()`
 
 ## Available APIs
 
@@ -66,6 +90,7 @@ Return values are JSON-stringified in the MCP response.
 
 - `repos.list()`
 - `repos.get(repoId)`
+- `repos.current()`
 - `repos.add(path, name?)`
 - `repos.remove(repoId)`
 - `repos.refreshGitRepos(repoId)`
@@ -89,10 +114,13 @@ Return values are JSON-stringified in the MCP response.
 
 - `state.get(repoId, slug)`
 - `state.getByPath(repoPath, slug)`
+- `state.getCurrent(slug)`
 - `state.summaries(repoId)`
 - `state.summariesByPath(repoPath)`
+- `state.summariesCurrent()`
 - `state.upsert(repoId, slug, payload)`
 - `state.upsertByPath(repoPath, slug, payload)`
+- `state.upsertCurrent(slug, payload)`
 
 `payload` supports any combination of:
 
@@ -116,7 +144,7 @@ return await Promise.all(reposList.map(async (repo) => ({
 Load one PRD with state:
 
 ```js
-const repo = (await repos.list())[0]
+const repo = await repos.current()
 const slug = 'prd-viewer'
 
 return {
@@ -139,6 +167,24 @@ return await Promise.all(commits.map(async (entry) => ({
 })))
 ```
 
+Inspect signatures at runtime:
+
+```js
+return steward.help()
+```
+
+Update state in the current repo (no repoId required):
+
+```js
+const slug = 'prd-viewer'
+
+await state.upsertCurrent(slug, {
+  notes: '# Updated from codemode'
+})
+
+return { saved: true }
+```
+
 Update state directly by path (replacement for shell helpers):
 
 ```js
@@ -170,7 +216,8 @@ return { saved: true }
 ## Limits
 
 - Execution timeout: 30 seconds
-- Output preview limit: 50,000 characters
+- Result preview limit: 50,000 characters
+- Captured log limit: 20,000 characters (max 200 log entries)
 - Timer limit: 100 active timers in sandbox
 
 ## Safety Notes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thxgg/steward",
-  "version": "0.1.7",
+  "version": "0.1.10",
   "description": "Local-first PRD workflow steward with codemode MCP and web UI.",
   "type": "module",
   "author": "thxgg",

package/.output/public/_nuxt/builds/meta/6683a0d9-9c02-4098-b750-bbbc0305261e.json

@@ -1 +0,0 @@
-{"id":"6683a0d9-9c02-4098-b750-bbbc0305261e","timestamp":1771766521897,"prerendered":[]}

package/.output/server/chunks/build/_prd_-CnwhMRyf.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"_prd_-CnwhMRyf.mjs","sources":["../../../../node_modules/.cache/nuxt/.nuxt/dist/server/_nuxt/_prd_-CnwhMRyf.js"],"names":[],"mappings":"","x_google_ignoreList":[0]}