@thxgg/steward 0.1.0

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

@@ -0,0 +1,96 @@
+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;
+}
+function resolveGitRepoPath(repo, repoPath) {
+    if (!repoPath) {
+        return repo.path;
+    }
+    if (!repo.gitRepos || repo.gitRepos.length === 0) {
+        throw new Error('repo parameter provided but no git repos discovered in this repository');
+    }
+    const matchedRepo = repo.gitRepos.find((gitRepo) => gitRepo.relativePath === repoPath);
+    if (!matchedRepo) {
+        const available = repo.gitRepos.map((gitRepo) => gitRepo.relativePath).join(', ');
+        throw new Error(`repo "${repoPath}" is not a discovered git repo. Available: ${available}`);
+    }
+    return matchedRepo.absolutePath;
+}
+export const git = {
+    async getCommits(repoId, shas, repoPath) {
+        if (!Array.isArray(shas) || shas.length === 0) {
+            throw new Error('At least one SHA is required');
+        }
+        const repo = await requireRepo(repoId);
+        const gitRepoPath = resolveGitRepoPath(repo, repoPath);
+        if (!await isGitRepo(gitRepoPath)) {
+            throw new Error('Resolved path is not a git repository');
+        }
+        const commits = [];
+        const errors = [];
+        for (const sha of shas) {
+            try {
+                const commit = await getCommitInfo(gitRepoPath, sha);
+                commits.push({
+                    ...commit,
+                    repoPath: repoPath || ''
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                errors.push(`${sha}: ${message}`);
+            }
+        }
+        if (commits.length === 0 && errors.length > 0) {
+            throw new Error(`No valid commits found: ${errors.join('; ')}`);
+        }
+        return commits;
+    },
+    async getDiff(repoId, commit, repoPath) {
+        if (!commit) {
+            throw new Error('commit is required');
+        }
+        const repo = await requireRepo(repoId);
+        const gitRepoPath = resolveGitRepoPath(repo, repoPath);
+        if (!await isGitRepo(gitRepoPath)) {
+            throw new Error('Resolved path is not a git repository');
+        }
+        return await getCommitDiff(gitRepoPath, commit);
+    },
+    async getFileDiff(repoId, commit, file, repoPath) {
+        if (!commit) {
+            throw new Error('commit is required');
+        }
+        if (!file) {
+            throw new Error('file is required');
+        }
+        const repo = await requireRepo(repoId);
+        const gitRepoPath = resolveGitRepoPath(repo, repoPath);
+        if (!await isGitRepo(gitRepoPath)) {
+            throw new Error('Resolved path is not a git repository');
+        }
+        if (!validatePathInRepo(gitRepoPath, file)) {
+            throw new Error('Invalid file path: path traversal not allowed');
+        }
+        return await getFileDiff(gitRepoPath, commit, file);
+    },
+    async getFileContent(repoId, commit, file, repoPath) {
+        if (!commit) {
+            throw new Error('commit is required');
+        }
+        if (!file) {
+            throw new Error('file is required');
+        }
+        const repo = await requireRepo(repoId);
+        const gitRepoPath = resolveGitRepoPath(repo, repoPath);
+        if (!await isGitRepo(gitRepoPath)) {
+            throw new Error('Resolved path is not a git repository');
+        }
+        return await getFileContent(gitRepoPath, commit, file);
+    }
+};

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

@@ -0,0 +1,4 @@
+export { repos } from './repos.js';
+export { prds } from './prds.js';
+export { git } from './git.js';
+export { state } from './state.js';

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

@@ -0,0 +1,195 @@
+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 { getPrdState, getPrdStateSummaries, migrateLegacyStateForRepo } from '../../../server/utils/prd-state.js';
+function parseMetadata(content) {
+    const metadata = {};
+    const authorMatch = content.match(/\*{0,2}Author\*{0,2}:\*{0,2}\s*(.+?)(?:\n|$)/i);
+    if (authorMatch && authorMatch[1]) {
+        metadata.author = authorMatch[1].trim();
+    }
+    const dateMatch = content.match(/\*{0,2}Date\*{0,2}:\*{0,2}\s*(.+?)(?:\n|$)/i);
+    if (dateMatch && dateMatch[1]) {
+        metadata.date = dateMatch[1].trim();
+    }
+    const statusMatch = content.match(/\*{0,2}Status\*{0,2}:\*{0,2}\s*(.+?)(?:\n|$)/i);
+    if (statusMatch && statusMatch[1]) {
+        metadata.status = statusMatch[1].trim();
+    }
+    const shortcutLinkMatch = content.match(/\[([Ss][Cc]-\d+)\]\(([^)]+)\)/);
+    if (shortcutLinkMatch && shortcutLinkMatch[1] && shortcutLinkMatch[2]) {
+        metadata.shortcutStory = shortcutLinkMatch[1];
+        metadata.shortcutUrl = shortcutLinkMatch[2];
+    }
+    else {
+        const shortcutIdMatch = content.match(/\*{0,2}Shortcut(?:\s+Story)?\*{0,2}:\*{0,2}\s*([Ss][Cc]-\d+)/i);
+        if (shortcutIdMatch && shortcutIdMatch[1]) {
+            metadata.shortcutStory = shortcutIdMatch[1];
+        }
+    }
+    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 {
+        return await fs.readFile(prdPath, 'utf-8');
+    }
+    catch {
+        throw new Error('PRD not found');
+    }
+}
+export const prds = {
+    async list(repoId) {
+        const repo = await requireRepo(repoId);
+        await migrateLegacyStateForRepo(repo);
+        const prdDir = join(repo.path, 'docs', 'prd');
+        let prdFiles = [];
+        try {
+            const files = await fs.readdir(prdDir);
+            prdFiles = files.filter((file) => file.endsWith('.md'));
+        }
+        catch {
+            return [];
+        }
+        const stateSummaries = await getPrdStateSummaries(repo.id);
+        const items = await Promise.all(prdFiles.map(async (filename) => {
+            const slug = basename(filename, '.md');
+            const filePath = join(prdDir, filename);
+            let name = slug;
+            let modifiedAt = 0;
+            try {
+                const [content, stat] = await Promise.all([
+                    fs.readFile(filePath, 'utf-8'),
+                    fs.stat(filePath)
+                ]);
+                modifiedAt = stat.mtime.getTime();
+                const h1Match = content.match(/^#\s+(.+)$/m);
+                if (h1Match && h1Match[1]) {
+                    name = h1Match[1].trim();
+                }
+            }
+            catch {
+                // Keep default values when a file cannot be read.
+            }
+            const stateSummary = stateSummaries.get(slug);
+            return {
+                slug,
+                name,
+                source: `docs/prd/${filename}`,
+                hasState: !!stateSummary?.hasState,
+                modifiedAt,
+                ...(stateSummary?.taskCount !== undefined && { taskCount: stateSummary.taskCount }),
+                ...(stateSummary?.completedCount !== undefined && { completedCount: stateSummary.completedCount })
+            };
+        }));
+        items.sort((a, b) => b.modifiedAt - a.modifiedAt);
+        return items;
+    },
+    async getDocument(repoId, prdSlug) {
+        const repo = await requireRepo(repoId);
+        const content = await readPrdFile(repo, prdSlug);
+        let name = prdSlug;
+        const h1Match = content.match(/^#\s+(.+)$/m);
+        if (h1Match && h1Match[1]) {
+            name = h1Match[1].trim();
+        }
+        return {
+            slug: prdSlug,
+            name,
+            content,
+            metadata: parseMetadata(content)
+        };
+    },
+    async getTasks(repoId, prdSlug) {
+        const repo = await requireRepo(repoId);
+        await migrateLegacyStateForRepo(repo);
+        const state = await getPrdState(repo.id, prdSlug);
+        return state?.tasks ?? null;
+    },
+    async getProgress(repoId, prdSlug) {
+        const repo = await requireRepo(repoId);
+        await migrateLegacyStateForRepo(repo);
+        const state = await getPrdState(repo.id, prdSlug);
+        return state?.progress ?? null;
+    },
+    async getTaskCommits(repoId, prdSlug, taskId) {
+        const repo = await requireRepo(repoId);
+        await migrateLegacyStateForRepo(repo);
+        const state = await getPrdState(repo.id, prdSlug);
+        const progress = state?.progress ?? null;
+        if (!progress) {
+            return [];
+        }
+        const taskLog = progress.taskLogs.find((log) => log.taskId === taskId);
+        if (!taskLog) {
+            throw new Error(`Task "${taskId}" not found in progress state`);
+        }
+        if (!taskLog.commits || taskLog.commits.length === 0) {
+            return [];
+        }
+        const resolvedCommits = [];
+        const failedEntries = [];
+        for (const commitEntry of taskLog.commits) {
+            try {
+                const resolved = await resolveCommitRepo(repo, commitEntry);
+                resolvedCommits.push({
+                    sha: resolved.sha,
+                    repo: resolved.repoPath
+                });
+            }
+            catch {
+                failedEntries.push(commitEntry);
+            }
+        }
+        if (failedEntries.length > 0) {
+            const newGitRepos = await discoverGitRepos(repo.path);
+            const existingPaths = new Set((repo.gitRepos || []).map((gitRepo) => gitRepo.relativePath));
+            const hasNewRepos = newGitRepos.some((gitRepo) => !existingPaths.has(gitRepo.relativePath));
+            let resolvedWithUpdatedRepo = false;
+            if (hasNewRepos) {
+                const allRepos = await getRepos();
+                const repoIndex = allRepos.findIndex((candidate) => candidate.id === repoId);
+                if (repoIndex !== -1) {
+                    const updatedRepo = {
+                        ...allRepos[repoIndex],
+                        gitRepos: newGitRepos.length > 0 ? newGitRepos : undefined
+                    };
+                    allRepos[repoIndex] = updatedRepo;
+                    await saveRepos(allRepos);
+                    resolvedWithUpdatedRepo = true;
+                    for (const commitEntry of failedEntries) {
+                        try {
+                            const resolved = await resolveCommitRepo(updatedRepo, commitEntry);
+                            resolvedCommits.push({
+                                sha: resolved.sha,
+                                repo: resolved.repoPath
+                            });
+                        }
+                        catch {
+                            const sha = typeof commitEntry === 'string' ? commitEntry : commitEntry.sha;
+                            resolvedCommits.push({ sha, repo: '' });
+                        }
+                    }
+                }
+            }
+            if (!resolvedWithUpdatedRepo) {
+                for (const commitEntry of failedEntries) {
+                    const sha = typeof commitEntry === 'string' ? commitEntry : commitEntry.sha;
+                    resolvedCommits.push({
+                        sha,
+                        repo: ''
+                    });
+                }
+            }
+        }
+        return resolvedCommits;
+    }
+};

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

@@ -0,0 +1,47 @@
+import { addRepo, discoverGitRepos, getRepoById, getRepos, removeRepo, saveRepos, validateRepoPath } from '../../../server/utils/repos.js';
+import { migrateLegacyStateForRepo } from '../../../server/utils/prd-state.js';
+export const repos = {
+    async list() {
+        return await getRepos();
+    },
+    async get(repoId) {
+        return await getRepoById(repoId) ?? null;
+    },
+    async add(path, name) {
+        const validation = await validateRepoPath(path);
+        if (!validation.valid) {
+            throw new Error(validation.error || 'Invalid repository path');
+        }
+        const repo = await addRepo(path, name);
+        await migrateLegacyStateForRepo(repo);
+        return repo;
+    },
+    async remove(repoId) {
+        const removed = await removeRepo(repoId);
+        if (!removed) {
+            throw new Error('Repository not found');
+        }
+        return { removed: true };
+    },
+    async refreshGitRepos(repoId) {
+        const allRepos = await getRepos();
+        const repoIndex = allRepos.findIndex((repo) => repo.id === repoId);
+        if (repoIndex === -1) {
+            throw new Error('Repository not found');
+        }
+        const repo = allRepos[repoIndex];
+        const gitRepos = await discoverGitRepos(repo.path);
+        if (gitRepos.length > 0) {
+            repo.gitRepos = gitRepos;
+        }
+        else {
+            delete repo.gitRepos;
+        }
+        allRepos[repoIndex] = repo;
+        await saveRepos(allRepos);
+        return {
+            discovered: gitRepos.length,
+            gitRepos
+        };
+    }
+};

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

@@ -0,0 +1,63 @@
+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;
+}
+function mapStateUpdate(payload) {
+    return {
+        ...(payload.tasks !== undefined && { tasks: payload.tasks }),
+        ...(payload.progress !== undefined && { progress: payload.progress }),
+        ...(payload.notes !== undefined && { notes: payload.notes })
+    };
+}
+function mapSummaryMap(summaries) {
+    return Object.fromEntries(summaries.entries());
+}
+export const state = {
+    async get(repoId, slug) {
+        const repo = await requireRepo(repoId);
+        await migrateLegacyStateForRepo(repo);
+        return await getPrdState(repo.id, slug);
+    },
+    async getByPath(repoPath, slug) {
+        const repo = await findRepoByPath(repoPath);
+        await migrateLegacyStateForRepo(repo);
+        return await getPrdState(repo.id, slug);
+    },
+    async summaries(repoId) {
+        const repo = await requireRepo(repoId);
+        await migrateLegacyStateForRepo(repo);
+        const summaries = await getPrdStateSummaries(repo.id);
+        return mapSummaryMap(summaries);
+    },
+    async summariesByPath(repoPath) {
+        const repo = await findRepoByPath(repoPath);
+        await migrateLegacyStateForRepo(repo);
+        const summaries = await getPrdStateSummaries(repo.id);
+        return mapSummaryMap(summaries);
+    },
+    async upsert(repoId, slug, payload) {
+        const repo = await requireRepo(repoId);
+        await upsertPrdState(repo.id, slug, mapStateUpdate(payload));
+        return { saved: true };
+    },
+    async upsertByPath(repoPath, slug, payload) {
+        const repo = await findRepoByPath(repoPath);
+        await upsertPrdState(repo.id, slug, mapStateUpdate(payload));
+        return { saved: true };
+    }
+};

package/dist/host/src/executor.js

@@ -0,0 +1,109 @@
+import vm from 'node:vm';
+import { git, prds, repos, state } from './api/index.js';
+const MAX_OUTPUT_SIZE = 50_000;
+const EXECUTION_TIMEOUT_MS = 30_000;
+const MAX_TIMERS = 100;
+export class ExecutionError extends Error {
+    stackTrace;
+    constructor(message, stackTrace) {
+        super(message);
+        this.stackTrace = stackTrace;
+        this.name = 'ExecutionError';
+    }
+}
+function truncateOutput(result) {
+    if (result === undefined) {
+        return undefined;
+    }
+    let json;
+    try {
+        json = JSON.stringify(result, null, 2);
+    }
+    catch {
+        return {
+            _unserializable: true,
+            preview: String(result)
+        };
+    }
+    if (json.length <= MAX_OUTPUT_SIZE) {
+        return result;
+    }
+    return {
+        _truncated: true,
+        size: json.length,
+        preview: json.slice(0, MAX_OUTPUT_SIZE),
+        message: `Output truncated (${json.length} chars, showing first ${MAX_OUTPUT_SIZE})`
+    };
+}
+export async function execute(code) {
+    if (!code || !code.trim()) {
+        throw new ExecutionError('Code cannot be empty');
+    }
+    const timers = new Set();
+    const sandbox = {
+        repos,
+        prds,
+        git,
+        state,
+        console: {
+            log: (...args) => console.log('[codemode]', ...args),
+            error: (...args) => console.error('[codemode]', ...args)
+        },
+        setTimeout: (handler, timeout) => {
+            if (timers.size >= MAX_TIMERS) {
+                throw new Error(`Timer limit exceeded (max ${MAX_TIMERS})`);
+            }
+            const timer = setTimeout(() => {
+                timers.delete(timer);
+                handler();
+            }, timeout);
+            timers.add(timer);
+            return timer;
+        },
+        clearTimeout: (timer) => {
+            timers.delete(timer);
+            clearTimeout(timer);
+        },
+        setInterval: (handler, timeout) => {
+            if (timers.size >= MAX_TIMERS) {
+                throw new Error(`Timer limit exceeded (max ${MAX_TIMERS})`);
+            }
+            const timer = setInterval(handler, timeout);
+            timers.add(timer);
+            return timer;
+        },
+        clearInterval: (timer) => {
+            timers.delete(timer);
+            clearInterval(timer);
+        },
+        Promise
+    };
+    const wrappedCode = `
+    (async () => {
+      ${code}
+    })()
+  `;
+    try {
+        const script = new vm.Script(wrappedCode, {
+            filename: 'codemode.js'
+        });
+        const context = vm.createContext(sandbox);
+        const result = await script.runInContext(context, {
+            timeout: EXECUTION_TIMEOUT_MS
+        });
+        return truncateOutput(result);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw new ExecutionError(error.message, error.stack);
+        }
+        throw new ExecutionError(String(error));
+    }
+    finally {
+        timers.forEach((timer) => {
+            clearTimeout(timer);
+            clearInterval(timer);
+        });
+        timers.clear();
+    }
+}

package/dist/host/src/index.js

@@ -0,0 +1,95 @@
+import { runMcpServer } from './mcp.js';
+import { runUi } from './ui.js';
+function printUsage() {
+    console.log(`prd - Steward CLI
+
+Usage:
+  prd ui [--preview] [--port <port>] [--host <host>]
+  prd mcp
+
+Commands:
+  ui         Launch the PRD web UI (dev mode by default)
+  mcp        Start MCP server over stdio (codemode)
+
+Options:
+  --preview      Run Nuxt preview server instead of dev server
+  --port <port>  Port for ui mode
+  --host <host>  Host for ui mode
+  -h, --help     Show this help message
+`);
+}
+function parsePort(value) {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`Invalid port: ${value}`);
+    }
+    return parsed;
+}
+function parseUiArgs(args) {
+    const options = { preview: false };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--preview') {
+            options.preview = true;
+            continue;
+        }
+        if (arg === '--port') {
+            const next = args[i + 1];
+            if (!next) {
+                throw new Error('--port requires a value');
+            }
+            options.port = parsePort(next);
+            i += 1;
+            continue;
+        }
+        if (arg === '--host') {
+            const next = args[i + 1];
+            if (!next) {
+                throw new Error('--host requires a value');
+            }
+            options.host = next;
+            i += 1;
+            continue;
+        }
+        throw new Error(`Unknown option for ui: ${arg}`);
+    }
+    return options;
+}
+export async function main(argv = process.argv.slice(2)) {
+    const [command, ...rest] = argv;
+    if (!command || command === '-h' || command === '--help') {
+        printUsage();
+        return;
+    }
+    if (command === 'mcp') {
+        if (rest.includes('-h') || rest.includes('--help')) {
+            printUsage();
+            return;
+        }
+        if (rest.length > 0) {
+            throw new Error(`Unexpected arguments for mcp: ${rest.join(' ')}`);
+        }
+        await runMcpServer();
+        return;
+    }
+    if (command === 'ui') {
+        if (rest.includes('-h') || rest.includes('--help')) {
+            printUsage();
+            return;
+        }
+        const options = parseUiArgs(rest);
+        const exitCode = await runUi(options);
+        if (exitCode !== 0) {
+            process.exitCode = exitCode;
+        }
+        return;
+    }
+    throw new Error(`Unknown command: ${command}`);
+}
+if (import.meta.main) {
+    await main().catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Error: ${message}`);
+        process.exit(1);
+    });
+}

package/dist/host/src/mcp.js

@@ -0,0 +1,62 @@
+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';
+    }
+    try {
+        return JSON.stringify(result, null, 2);
+    }
+    catch {
+        return String(result);
+    }
+}
+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)
+    }, async ({ code }) => {
+        try {
+            const result = await execute(code);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: serializeResult(result)
+                    }
+                ]
+            };
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: formatError(error)
+                    }
+                ]
+            };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}