@thxgg/steward 0.1.7 → 0.1.11

package/.output/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thxgg/steward-prod",
-  "version": "0.1.7",
+  "version": "0.1.11",
   "type": "module",
   "private": true,
   "dependencies": {

package/README.md

@@ -41,6 +41,15 @@ Add to your MCP client config:
 }
 ```
 
+Steward MCP requires a Node runtime with built-in sqlite support (`node:sqlite`) for `repos`, `prds`, and `state` APIs.
+If you see `ERR_UNKNOWN_BUILTIN_MODULE: node:sqlite`, run with sqlite enabled:
+
+```bash
+NODE_OPTIONS=--experimental-sqlite npx -y @thxgg/steward mcp
+```
+
+Note: `execute` runs in a VM sandbox by design, so globals like `process` are intentionally not exposed.
+
 ### CLI
 
 ```bash
@@ -77,9 +86,7 @@ prd mcp
 Steward exposes one MCP tool: `execute`.
 
 ```js
-const reposList = await repos.list()
-const repo = reposList[0]
-if (!repo) return { error: 'No repos configured' }
+const repo = await repos.current()
 
 const prdList = await prds.list(repo.id)
 if (prdList.length === 0) return { repo: repo.name, prds: 0 }
@@ -92,6 +99,26 @@ return {
 }
 ```
 
+Every call returns a structured envelope:
+
+```json
+{
+  "ok": true,
+  "result": {},
+  "logs": [],
+  "error": null,
+  "meta": {
+    "timeoutMs": 30000,
+    "durationMs": 10,
+    "truncatedResult": false,
+    "truncatedLogs": false,
+    "resultWasUndefined": false
+  }
+}
+```
+
+Use `steward.help()` inside `execute` for runtime API signatures and examples.
+
 ## APIs
 
 Inside `execute`, these APIs are available:
@@ -99,7 +126,7 @@ Inside `execute`, these APIs are available:
 - `repos` - register/list/remove repos and refresh discovered git repos
 - `prds` - list/read PRD docs, tasks, progress, and task commit refs
 - `git` - commit metadata, diffs, file diffs, and file contents
-- `state` - direct PRD state get/upsert by repo id or path
+- `state` - direct PRD state get/upsert by repo id, path, or current repo
 
 Detailed API docs and examples: `docs/MCP.md`
 

package/bin/prd

@@ -1,11 +1,128 @@
 #!/usr/bin/env node
+import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 
+const SQLITE_ENABLE_FLAG = '--experimental-sqlite'
+const SQLITE_DISABLE_FLAG = '--no-experimental-sqlite'
+const SQLITE_REEXEC_ENV = 'STEWARD_SQLITE_REEXEC'
+
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
 const entryPath = resolve(packageRoot, 'dist', 'host', 'src', 'index.js')
 
+function requiresSqliteRuntime(command) {
+  return command === 'mcp' || command === 'ui'
+}
+
+function isSqliteRuntimeError(error) {
+  if (!(error instanceof Error)) {
+    return false
+  }
+
+  const code = error.code
+  return typeof code === 'string'
+    && code === 'ERR_UNKNOWN_BUILTIN_MODULE'
+    && error.message.includes('node:sqlite')
+}
+
+function sanitizeNodeOptions(rawNodeOptions = '') {
+  const options = rawNodeOptions
+    .split(/\s+/)
+    .filter(Boolean)
+    .filter((option) => option !== SQLITE_ENABLE_FLAG && option !== SQLITE_DISABLE_FLAG)
+
+  return options.join(' ')
+}
+
+function buildReexecEnv() {
+  const env = { ...process.env }
+  const sanitizedNodeOptions = sanitizeNodeOptions(env.NODE_OPTIONS)
+
+  if (sanitizedNodeOptions.length > 0) {
+    env.NODE_OPTIONS = sanitizedNodeOptions
+  } else {
+    delete env.NODE_OPTIONS
+  }
+
+  env[SQLITE_REEXEC_ENV] = '1'
+  return env
+}
+
+function canEnableSqliteWithFlag() {
+  const probe = spawnSync(
+    process.execPath,
+    [SQLITE_ENABLE_FLAG, '-e', "import('node:sqlite').then(() => process.exit(0)).catch(() => process.exit(1))"],
+    {
+      stdio: 'ignore',
+      env: buildReexecEnv()
+    }
+  )
+
+  return probe.status === 0
+}
+
+function reexecWithSqliteFlag() {
+  const result = spawnSync(
+    process.execPath,
+    [SQLITE_ENABLE_FLAG, fileURLToPath(import.meta.url), ...process.argv.slice(2)],
+    {
+      stdio: 'inherit',
+      env: buildReexecEnv()
+    }
+  )
+
+  if (result.error) {
+    throw result.error
+  }
+
+  process.exit(result.status ?? 1)
+}
+
+async function ensureSqliteRuntime(command) {
+  if (!requiresSqliteRuntime(command)) {
+    return
+  }
+
+  try {
+    await import('node:sqlite')
+    return
+  } catch (error) {
+    if (!isSqliteRuntimeError(error)) {
+      throw error
+    }
+
+    const alreadyReexecuted = process.env[SQLITE_REEXEC_ENV] === '1'
+    if (!alreadyReexecuted && canEnableSqliteWithFlag()) {
+      reexecWithSqliteFlag()
+      return
+    }
+
+    const message = error instanceof Error ? error.message : String(error)
+    const nodeOptions = process.env.NODE_OPTIONS || ''
+    const hasDisableFlag = process.execArgv.includes(SQLITE_DISABLE_FLAG)
+      || nodeOptions.includes(SQLITE_DISABLE_FLAG)
+
+    console.error('Steward requires SQLite runtime support for repos/prds/state APIs.')
+    console.error(`Runtime: ${process.version} (${process.execPath})`)
+    if (nodeOptions) {
+      console.error(`NODE_OPTIONS: ${nodeOptions}`)
+    }
+    console.error(`Cause: ${message}`)
+
+    if (hasDisableFlag) {
+      console.error(`Hint: remove ${SQLITE_DISABLE_FLAG} from NODE_OPTIONS or runtime args and retry.`)
+    } else {
+      console.error(`Hint: use a Node runtime with sqlite support or launch with ${SQLITE_ENABLE_FLAG}.`)
+    }
+
+    process.exit(1)
+  }
+}
+
+const command = process.argv[2] || ''
+await ensureSqliteRuntime(command)
+
 if (!existsSync(entryPath)) {
   console.error('Steward host runtime is not built.')
   console.error('Run `npm run build:host` in this package before invoking `prd`.')

package/dist/host/src/api/git.js

@@ -1,12 +1,5 @@
 import { getCommitDiff, getCommitInfo, getFileContent, getFileDiff, isGitRepo, validatePathInRepo } from '../../../server/utils/git.js';
-import { getRepoById } from '../../../server/utils/repos.js';
-async function requireRepo(repoId) {
-    const repo = await getRepoById(repoId);
-    if (!repo) {
-        throw new Error('Repository not found');
-    }
-    return repo;
-}
+import { requireRepo } from './repo-context.js';
 function resolveGitRepoPath(repo, repoPath) {
     if (!repoPath) {
         return repo.path;

package/dist/host/src/api/prds.js

@@ -1,8 +1,9 @@
 import { promises as fs } from 'node:fs';
 import { basename, join } from 'node:path';
 import { resolveCommitRepo } from '../../../server/utils/git.js';
-import { discoverGitRepos, getRepoById, getRepos, saveRepos } from '../../../server/utils/repos.js';
+import { discoverGitRepos, getRepos, saveRepos } from '../../../server/utils/repos.js';
 import { getPrdState, getPrdStateSummaries, migrateLegacyStateForRepo } from '../../../server/utils/prd-state.js';
+import { requireRepo } from './repo-context.js';
 function parseMetadata(content) {
     const metadata = {};
     const authorMatch = content.match(/\*{0,2}Author\*{0,2}:\*{0,2}\s*(.+?)(?:\n|$)/i);
@@ -30,13 +31,6 @@ function parseMetadata(content) {
     }
     return metadata;
 }
-async function requireRepo(repoId) {
-    const repo = await getRepoById(repoId);
-    if (!repo) {
-        throw new Error('Repository not found');
-    }
-    return repo;
-}
 async function readPrdFile(repo, prdSlug) {
     const prdPath = join(repo.path, 'docs', 'prd', `${prdSlug}.md`);
     try {

package/dist/host/src/api/repo-context.js

@@ -0,0 +1,60 @@
+import { resolve } from 'node:path';
+import { getRepoById, getRepos } from '../../../server/utils/repos.js';
+export class RepoLookupError extends Error {
+    code;
+    details;
+    constructor(message, code, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'RepoLookupError';
+    }
+}
+function summarizeRepos(repos) {
+    return repos.map((repo) => ({
+        id: repo.id,
+        name: repo.name,
+        path: repo.path
+    }));
+}
+function formatKnownRepos(knownRepos) {
+    return knownRepos
+        .map((repo) => `${repo.id} (${repo.name}) ${repo.path}`)
+        .join('; ');
+}
+export async function requireRepo(repoId) {
+    const repo = await getRepoById(repoId);
+    if (repo) {
+        return repo;
+    }
+    const allRepos = await getRepos();
+    const knownRepos = summarizeRepos(allRepos);
+    if (knownRepos.length === 0) {
+        throw new RepoLookupError(`Unknown repoId "${repoId}". No repositories are registered. Use repos.add(path) first.`, 'NO_REPOS', { repoId, knownRepos });
+    }
+    throw new RepoLookupError(`Unknown repoId "${repoId}". Known repositories: ${formatKnownRepos(knownRepos)}`, 'REPO_NOT_FOUND', { repoId, knownRepos });
+}
+export async function requireRepoByPath(repoPath) {
+    const absolutePath = resolve(repoPath);
+    const allRepos = await getRepos();
+    const repo = allRepos.find((candidate) => resolve(candidate.path) === absolutePath);
+    if (repo) {
+        return repo;
+    }
+    const knownRepos = summarizeRepos(allRepos);
+    if (knownRepos.length === 0) {
+        throw new RepoLookupError(`No registered repository found for path: ${absolutePath}. No repositories are registered. Use repos.add(path) first.`, 'NO_REPOS', { repoPath: absolutePath, knownRepos });
+    }
+    throw new RepoLookupError(`No registered repository found for path: ${absolutePath}. Known repositories: ${formatKnownRepos(knownRepos)}`, 'REPO_PATH_NOT_FOUND', { repoPath: absolutePath, knownRepos });
+}
+export async function requireCurrentRepo() {
+    const allRepos = await getRepos();
+    if (allRepos.length === 1) {
+        return allRepos[0];
+    }
+    const knownRepos = summarizeRepos(allRepos);
+    if (knownRepos.length === 0) {
+        throw new RepoLookupError('No repositories are registered. Use repos.add(path) first.', 'NO_REPOS', { knownRepos });
+    }
+    throw new RepoLookupError(`Cannot resolve a current repository because ${knownRepos.length} repositories are registered. Use an explicit repoId or by-path API. Known repositories: ${formatKnownRepos(knownRepos)}`, 'AMBIGUOUS_REPO', { knownRepos });
+}

package/dist/host/src/api/repos.js

@@ -1,5 +1,6 @@
 import { addRepo, discoverGitRepos, getRepoById, getRepos, removeRepo, saveRepos, validateRepoPath } from '../../../server/utils/repos.js';
 import { migrateLegacyStateForRepo } from '../../../server/utils/prd-state.js';
+import { requireCurrentRepo, requireRepo } from './repo-context.js';
 export const repos = {
     async list() {
         return await getRepos();
@@ -7,6 +8,9 @@ export const repos = {
     async get(repoId) {
         return await getRepoById(repoId) ?? null;
     },
+    async current() {
+        return await requireCurrentRepo();
+    },
     async add(path, name) {
         const validation = await validateRepoPath(path);
         if (!validation.valid) {
@@ -17,6 +21,7 @@ export const repos = {
         return repo;
     },
     async remove(repoId) {
+        await requireRepo(repoId);
         const removed = await removeRepo(repoId);
         if (!removed) {
             throw new Error('Repository not found');
@@ -24,6 +29,7 @@ export const repos = {
         return { removed: true };
     },
     async refreshGitRepos(repoId) {
+        await requireRepo(repoId);
         const allRepos = await getRepos();
         const repoIndex = allRepos.findIndex((repo) => repo.id === repoId);
         if (repoIndex === -1) {

package/dist/host/src/api/state.js

@@ -1,22 +1,5 @@
-import { resolve } from 'node:path';
 import { getPrdState, getPrdStateSummaries, migrateLegacyStateForRepo, upsertPrdState } from '../../../server/utils/prd-state.js';
-import { getRepoById, getRepos } from '../../../server/utils/repos.js';
-async function requireRepo(repoId) {
-    const repo = await getRepoById(repoId);
-    if (!repo) {
-        throw new Error('Repository not found');
-    }
-    return repo;
-}
-async function findRepoByPath(repoPath) {
-    const absolutePath = resolve(repoPath);
-    const repos = await getRepos();
-    const repo = repos.find((candidate) => resolve(candidate.path) === absolutePath);
-    if (!repo) {
-        throw new Error(`No registered repository found for path: ${absolutePath}`);
-    }
-    return repo;
-}
+import { requireCurrentRepo, requireRepo, requireRepoByPath } from './repo-context.js';
 function mapStateUpdate(payload) {
     return {
         ...(payload.tasks !== undefined && { tasks: payload.tasks }),
@@ -34,7 +17,12 @@ export const state = {
         return await getPrdState(repo.id, slug);
     },
     async getByPath(repoPath, slug) {
-        const repo = await findRepoByPath(repoPath);
+        const repo = await requireRepoByPath(repoPath);
+        await migrateLegacyStateForRepo(repo);
+        return await getPrdState(repo.id, slug);
+    },
+    async getCurrent(slug) {
+        const repo = await requireCurrentRepo();
         await migrateLegacyStateForRepo(repo);
         return await getPrdState(repo.id, slug);
     },
@@ -45,7 +33,13 @@ export const state = {
         return mapSummaryMap(summaries);
     },
     async summariesByPath(repoPath) {
-        const repo = await findRepoByPath(repoPath);
+        const repo = await requireRepoByPath(repoPath);
+        await migrateLegacyStateForRepo(repo);
+        const summaries = await getPrdStateSummaries(repo.id);
+        return mapSummaryMap(summaries);
+    },
+    async summariesCurrent() {
+        const repo = await requireCurrentRepo();
         await migrateLegacyStateForRepo(repo);
         const summaries = await getPrdStateSummaries(repo.id);
         return mapSummaryMap(summaries);
@@ -56,7 +50,12 @@ export const state = {
         return { saved: true };
     },
     async upsertByPath(repoPath, slug, payload) {
-        const repo = await findRepoByPath(repoPath);
+        const repo = await requireRepoByPath(repoPath);
+        await upsertPrdState(repo.id, slug, mapStateUpdate(payload));
+        return { saved: true };
+    },
+    async upsertCurrent(slug, payload) {
+        const repo = await requireCurrentRepo();
         await upsertPrdState(repo.id, slug, mapStateUpdate(payload));
         return { saved: true };
     }