@thxgg/steward 0.1.15 → 0.1.17

package/dist/server/utils/prd-service.js

@@ -0,0 +1,235 @@
+import { promises as fs } from 'node:fs';
+import { basename, isAbsolute, join, relative, resolve } from 'node:path';
+import { resolveCommitRepo } from './git.js';
+import { getPrdState, getPrdStateSummaries, migrateLegacyStateForRepo } from './prd-state.js';
+import { discoverGitRepos, updateRepoGitRepos } from './repos.js';
+const PRD_SLUG_PATTERN = /^[A-Za-z0-9][A-Za-z0-9-]*$/;
+function normalizePathSlashes(path) {
+    return path.replaceAll('\\', '/');
+}
+function normalizeGitRepos(gitRepos) {
+    if (!gitRepos || gitRepos.length === 0) {
+        return undefined;
+    }
+    return gitRepos.map((gitRepo) => ({
+        ...gitRepo,
+        relativePath: normalizePathSlashes(gitRepo.relativePath)
+    }));
+}
+function hasPathTraversal(basePath, candidatePath) {
+    const relativePath = relative(resolve(basePath), resolve(candidatePath));
+    return relativePath.startsWith('..') || isAbsolute(relativePath);
+}
+function extractCommitSha(entry) {
+    return typeof entry === 'string' ? entry : entry.sha;
+}
+function parseMetadata(content) {
+    const metadata = {};
+    const authorMatch = content.match(/\*{0,2}Author\*{0,2}:\*{0,2}\s*(.+?)(?:\n|$)/i);
+    if (authorMatch?.[1]) {
+        metadata.author = authorMatch[1].trim();
+    }
+    const dateMatch = content.match(/\*{0,2}Date\*{0,2}:\*{0,2}\s*(.+?)(?:\n|$)/i);
+    if (dateMatch?.[1]) {
+        metadata.date = dateMatch[1].trim();
+    }
+    const statusMatch = content.match(/\*{0,2}Status\*{0,2}:\*{0,2}\s*(.+?)(?:\n|$)/i);
+    if (statusMatch?.[1]) {
+        metadata.status = statusMatch[1].trim();
+    }
+    const shortcutLinkMatch = content.match(/\[([Ss][Cc]-\d+)\]\(([^)]+)\)/);
+    if (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?.[1]) {
+            metadata.shortcutStory = shortcutIdMatch[1];
+        }
+    }
+    return metadata;
+}
+export function isValidPrdSlug(prdSlug) {
+    return PRD_SLUG_PATTERN.test(prdSlug);
+}
+export function assertValidPrdSlug(prdSlug) {
+    if (!isValidPrdSlug(prdSlug)) {
+        throw new Error('Invalid PRD slug format');
+    }
+}
+export function resolvePrdMarkdownPath(repoPath, prdSlug) {
+    assertValidPrdSlug(prdSlug);
+    const prdDir = resolve(repoPath, 'docs', 'prd');
+    const prdPath = resolve(prdDir, `${prdSlug}.md`);
+    if (hasPathTraversal(prdDir, prdPath)) {
+        throw new Error('Invalid PRD slug path traversal');
+    }
+    return prdPath;
+}
+export function extractPrdTitle(content, fallbackSlug) {
+    const h1Match = content.match(/^#\s+(.+)$/m);
+    if (h1Match?.[1]) {
+        return h1Match[1].trim();
+    }
+    return fallbackSlug;
+}
+export async function readPrdDocument(repo, prdSlug) {
+    const prdPath = resolvePrdMarkdownPath(repo.path, prdSlug);
+    let content;
+    try {
+        content = await fs.readFile(prdPath, 'utf-8');
+    }
+    catch {
+        throw new Error('PRD not found');
+    }
+    return {
+        slug: prdSlug,
+        name: extractPrdTitle(content, prdSlug),
+        content,
+        metadata: parseMetadata(content)
+    };
+}
+export async function listPrdDocuments(repo) {
+    await migrateLegacyStateForRepo(repo);
+    const prdDir = join(repo.path, 'docs', 'prd');
+    let prdFiles = [];
+    try {
+        const files = await fs.readdir(prdDir);
+        prdFiles = files.filter((file) => {
+            if (!file.endsWith('.md')) {
+                return false;
+            }
+            const slug = basename(file, '.md');
+            return isValidPrdSlug(slug);
+        });
+    }
+    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();
+            name = extractPrdTitle(content, slug);
+        }
+        catch {
+            // Keep fallback values when 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;
+}
+export async function readPrdTasks(repo, prdSlug) {
+    assertValidPrdSlug(prdSlug);
+    await migrateLegacyStateForRepo(repo);
+    const state = await getPrdState(repo.id, prdSlug);
+    return state?.tasks ?? null;
+}
+export async function readPrdProgress(repo, prdSlug) {
+    assertValidPrdSlug(prdSlug);
+    await migrateLegacyStateForRepo(repo);
+    const state = await getPrdState(repo.id, prdSlug);
+    return state?.progress ?? null;
+}
+function hasDiscoveredRepoChanges(repo, discoveredRepos) {
+    const normalizedExisting = normalizeGitRepos(repo.gitRepos) || [];
+    const normalizedDiscovered = normalizeGitRepos(discoveredRepos) || [];
+    if (normalizedExisting.length !== normalizedDiscovered.length) {
+        return true;
+    }
+    const existingPaths = new Set(normalizedExisting.map((gitRepo) => gitRepo.relativePath));
+    for (const gitRepo of normalizedDiscovered) {
+        if (!existingPaths.has(gitRepo.relativePath)) {
+            return true;
+        }
+    }
+    return false;
+}
+async function refreshDiscoveredGitRepos(repo) {
+    const discoveredRepos = normalizeGitRepos(await discoverGitRepos(repo.path));
+    if (!hasDiscoveredRepoChanges(repo, discoveredRepos)) {
+        return null;
+    }
+    const updated = await updateRepoGitRepos(repo.id, discoveredRepos);
+    if (!updated) {
+        return null;
+    }
+    return {
+        ...repo,
+        gitRepos: discoveredRepos
+    };
+}
+export async function resolveTaskCommits(repo, prdSlug, taskId) {
+    assertValidPrdSlug(prdSlug);
+    await migrateLegacyStateForRepo(repo);
+    const state = await getPrdState(repo.id, prdSlug);
+    const progress = state?.progress ?? null;
+    if (!progress) {
+        return [];
+    }
+    const taskLogs = Array.isArray(progress.taskLogs) ? progress.taskLogs : [];
+    const taskLog = taskLogs.find((log) => log.taskId === taskId);
+    if (!taskLog || !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) {
+        return resolvedCommits;
+    }
+    const refreshedRepo = await refreshDiscoveredGitRepos(repo);
+    for (const commitEntry of failedEntries) {
+        if (!refreshedRepo) {
+            resolvedCommits.push({
+                sha: extractCommitSha(commitEntry),
+                repo: ''
+            });
+            continue;
+        }
+        try {
+            const resolved = await resolveCommitRepo(refreshedRepo, commitEntry);
+            resolvedCommits.push({
+                sha: resolved.sha,
+                repo: resolved.repoPath
+            });
+        }
+        catch {
+            resolvedCommits.push({
+                sha: extractCommitSha(commitEntry),
+                repo: ''
+            });
+        }
+    }
+    return resolvedCommits;
+}

package/dist/server/utils/prd-state.js

@@ -1,15 +1,18 @@
 import { promises as fs } from 'node:fs';
 import { join } from 'node:path';
+import { emitChange } from './change-events.js';
 import { dbAll, dbGet, dbRun } from './db.js';
+import { parseProgressFile, parseTasksFile } from './state-schema.js';
 const LEGACY_STATE_STABLE_MS = 0;
 const migrationInFlight = new Map();
 const cleanupCompletedRepoIds = new Set();
-function parseStoredJson(raw, fieldName) {
+function parseStoredJson(raw, fieldName, parseValue) {
     if (!raw) {
         return null;
     }
     try {
-        return JSON.parse(raw);
+        const parsed = JSON.parse(raw);
+        return parseValue(parsed);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -24,25 +27,6 @@ function getTaskCounts(tasksFile) {
     const completedCount = tasksFile.tasks.filter(task => task.status === 'completed').length;
     return { taskCount, completedCount };
 }
-function normalizeLegacyTasksFile(tasksFile) {
-    if (!tasksFile || !Array.isArray(tasksFile.tasks)) {
-        return tasksFile;
-    }
-    const tasks = tasksFile.tasks.map((task) => {
-        const passes = task.passes;
-        if (Array.isArray(passes)) {
-            return task;
-        }
-        return {
-            ...task,
-            passes: []
-        };
-    });
-    return {
-        ...tasksFile,
-        tasks
-    };
-}
 export async function getPrdState(repoId, slug) {
     const row = await dbGet(`
       SELECT repo_id, slug, tasks_json, progress_json, notes_md, updated_at
@@ -52,11 +36,12 @@ export async function getPrdState(repoId, slug) {
     if (!row) {
         return null;
     }
-    const tasks = normalizeLegacyTasksFile(parseStoredJson(row.tasks_json, 'prd_states.tasks_json'));
+    const tasks = parseStoredJson(row.tasks_json, 'prd_states.tasks_json', parseTasksFile);
+    const progress = parseStoredJson(row.progress_json, 'prd_states.progress_json', parseProgressFile);
     return {
         slug: row.slug,
         tasks,
-        progress: parseStoredJson(row.progress_json, 'prd_states.progress_json'),
+        progress,
         notes: row.notes_md,
         updatedAt: row.updated_at
     };
@@ -68,7 +53,7 @@ export async function getPrdStateSummaries(repoId) {
         const summary = { hasState: true };
         if (row.tasks_json) {
             try {
-                const tasksFile = JSON.parse(row.tasks_json);
+                const tasksFile = parseTasksFile(JSON.parse(row.tasks_json));
                 const counts = getTaskCounts(tasksFile);
                 if (counts) {
                     summary.taskCount = counts.taskCount;
@@ -84,33 +69,60 @@ export async function getPrdStateSummaries(repoId) {
     return summaries;
 }
 export async function upsertPrdState(repoId, slug, update) {
-    const existing = await dbGet(`
-      SELECT repo_id, slug, tasks_json, progress_json, notes_md, updated_at
-      FROM prd_states
-      WHERE repo_id = ? AND slug = ?
-    `, [repoId, slug]);
-    const tasksJson = update.tasks === undefined
-        ? existing?.tasks_json ?? null
-        : (update.tasks === null ? null : JSON.stringify(update.tasks));
-    const progressJson = update.progress === undefined
-        ? existing?.progress_json ?? null
-        : (update.progress === null ? null : JSON.stringify(update.progress));
+    const validatedTasks = update.tasks === undefined
+        ? undefined
+        : (update.tasks === null ? null : parseTasksFile(update.tasks));
+    const validatedProgress = update.progress === undefined
+        ? undefined
+        : (update.progress === null ? null : parseProgressFile(update.progress));
+    const updateTasks = validatedTasks !== undefined;
+    const updateProgress = validatedProgress !== undefined;
+    const updateNotes = update.notes !== undefined;
+    const tasksJson = validatedTasks === undefined
+        ? null
+        : (validatedTasks === null ? null : JSON.stringify(validatedTasks));
+    const progressJson = validatedProgress === undefined
+        ? null
+        : (validatedProgress === null ? null : JSON.stringify(validatedProgress));
     const notesMd = update.notes === undefined
-        ? existing?.notes_md ?? null
+        ? null
         : update.notes;
     const updatedAt = new Date().toISOString();
-    if (existing) {
-        await dbRun(`
-        UPDATE prd_states
-        SET tasks_json = ?, progress_json = ?, notes_md = ?, updated_at = ?
-        WHERE repo_id = ? AND slug = ?
-      `, [tasksJson, progressJson, notesMd, updatedAt, repoId, slug]);
-        return;
-    }
     await dbRun(`
       INSERT INTO prd_states (repo_id, slug, tasks_json, progress_json, notes_md, updated_at)
       VALUES (?, ?, ?, ?, ?, ?)
-    `, [repoId, slug, tasksJson, progressJson, notesMd, updatedAt]);
+      ON CONFLICT(repo_id, slug) DO UPDATE SET
+        tasks_json = CASE WHEN ? THEN excluded.tasks_json ELSE prd_states.tasks_json END,
+        progress_json = CASE WHEN ? THEN excluded.progress_json ELSE prd_states.progress_json END,
+        notes_md = CASE WHEN ? THEN excluded.notes_md ELSE prd_states.notes_md END,
+        updated_at = excluded.updated_at
+    `, [
+        repoId,
+        slug,
+        tasksJson,
+        progressJson,
+        notesMd,
+        updatedAt,
+        updateTasks ? 1 : 0,
+        updateProgress ? 1 : 0,
+        updateNotes ? 1 : 0
+    ]);
+    if (validatedTasks !== undefined) {
+        emitChange({
+            type: 'change',
+            path: `state://${repoId}/${slug}/tasks.json`,
+            repoId,
+            category: 'tasks'
+        });
+    }
+    if (validatedProgress !== undefined) {
+        emitChange({
+            type: 'change',
+            path: `state://${repoId}/${slug}/progress.json`,
+            repoId,
+            category: 'progress'
+        });
+    }
 }
 async function readStableLegacyFile(filePath, minFileAgeMs) {
     try {

package/dist/server/utils/repos.js

@@ -1,13 +1,35 @@
-import { promises as fs } from 'node:fs';
-import { join, basename, resolve, relative } from 'node:path';
+import { existsSync, promises as fs } from 'node:fs';
+import { join, basename, dirname, resolve, relative, isAbsolute } from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
 import { dbAll, dbGet, dbRun } from './db.js';
-const LEGACY_REPOS_FILE = join(process.cwd(), 'server', 'data', 'repos.json');
+function findPackageRoot(startDir) {
+    let currentDir = startDir;
+    while (true) {
+        if (existsSync(join(currentDir, 'package.json'))) {
+            return currentDir;
+        }
+        const parentDir = dirname(currentDir);
+        if (parentDir === currentDir) {
+            return startDir;
+        }
+        currentDir = parentDir;
+    }
+}
+function normalizePathSlashes(path) {
+    return path.replaceAll('\\', '/');
+}
+function isPathWithin(basePath, candidatePath) {
+    const relativePath = relative(resolve(basePath), resolve(candidatePath));
+    return relativePath === '' || (!relativePath.startsWith('..') && !isAbsolute(relativePath));
+}
+const PACKAGE_ROOT = findPackageRoot(dirname(fileURLToPath(import.meta.url)));
+const LEGACY_REPOS_FILE = join(PACKAGE_ROOT, 'server', 'data', 'repos.json');
 let legacyImportPromise = null;
 function serializeGitRepos(gitRepos) {
     return gitRepos && gitRepos.length > 0 ? JSON.stringify(gitRepos) : null;
 }
-function parseGitRepos(gitReposJson) {
+function parseGitRepos(repoPath, gitReposJson) {
     if (!gitReposJson) {
         return undefined;
     }
@@ -16,21 +38,39 @@ function parseGitRepos(gitReposJson) {
         if (!Array.isArray(parsed)) {
             return undefined;
         }
-        const validRepos = parsed.filter((item) => {
-            return !!item
-                && typeof item === 'object'
-                && typeof item.relativePath === 'string'
-                && typeof item.absolutePath === 'string'
-                && typeof item.name === 'string';
-        });
-        return validRepos.length > 0 ? validRepos : undefined;
+        const repoRoot = resolve(repoPath);
+        const validRepos = new Map();
+        for (const item of parsed) {
+            if (!item || typeof item !== 'object') {
+                continue;
+            }
+            const relativePath = item.relativePath;
+            const name = item.name;
+            if (!relativePath || !name) {
+                continue;
+            }
+            const normalizedRelativePath = normalizePathSlashes(relativePath).replace(/^\.\//, '');
+            if (!normalizedRelativePath || normalizedRelativePath === '.') {
+                continue;
+            }
+            const absolutePath = resolve(repoRoot, normalizedRelativePath);
+            if (!isPathWithin(repoRoot, absolutePath)) {
+                continue;
+            }
+            validRepos.set(normalizedRelativePath, {
+                relativePath: normalizedRelativePath,
+                absolutePath,
+                name
+            });
+        }
+        return validRepos.size > 0 ? Array.from(validRepos.values()) : undefined;
     }
     catch {
         return undefined;
     }
 }
 function rowToRepo(row) {
-    const gitRepos = parseGitRepos(row.git_repos_json);
+    const gitRepos = parseGitRepos(row.path, row.git_repos_json);
     return {
         id: row.id,
         name: row.name,
@@ -145,6 +185,11 @@ export async function getRepoById(id) {
     const row = await dbGet('SELECT id, name, path, added_at, git_repos_json FROM repos WHERE id = ?', [id]);
     return row ? rowToRepo(row) : undefined;
 }
+export async function updateRepoGitRepos(id, gitRepos) {
+    await importLegacyReposIfNeeded();
+    const result = await dbRun('UPDATE repos SET git_repos_json = ? WHERE id = ?', [serializeGitRepos(gitRepos), id]);
+    return result.changes > 0;
+}
 export async function removeRepo(id) {
     await importLegacyReposIfNeeded();
     const result = await dbRun('DELETE FROM repos WHERE id = ?', [id]);

package/dist/server/utils/state-schema.js

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+const taskStatusSchema = z.enum(['pending', 'in_progress', 'completed']);
+const taskCategorySchema = z.enum(['setup', 'feature', 'integration', 'testing', 'documentation']);
+const taskPrioritySchema = z.enum(['critical', 'high', 'medium', 'low']);
+const commitRefSchema = z.object({
+    sha: z.string().min(1),
+    repo: z.string()
+});
+const taskSchema = z.object({
+    id: z.string().min(1),
+    category: taskCategorySchema,
+    title: z.string(),
+    description: z.string(),
+    steps: z.array(z.string()).default([]),
+    passes: z.array(z.string()).default([]),
+    dependencies: z.array(z.string()).default([]),
+    priority: taskPrioritySchema,
+    status: taskStatusSchema,
+    startedAt: z.string().optional(),
+    completedAt: z.string().optional()
+});
+const tasksFileSchema = z.object({
+    prd: z.object({
+        name: z.string(),
+        source: z.string(),
+        shortcutStory: z.string().optional(),
+        createdAt: z.string()
+    }),
+    tasks: z.array(taskSchema)
+});
+const taskLogSchema = z.object({
+    taskId: z.string().min(1),
+    status: taskStatusSchema,
+    startedAt: z.string(),
+    completedAt: z.string().optional(),
+    implemented: z.string().optional(),
+    filesChanged: z.array(z.string()).optional(),
+    learnings: z.string().optional(),
+    commits: z.array(z.union([z.string().min(1), commitRefSchema])).optional()
+});
+const progressFileSchema = z.object({
+    prdName: z.string(),
+    shortcutStory: z.string().optional(),
+    totalTasks: z.number(),
+    completed: z.number(),
+    inProgress: z.number(),
+    blocked: z.number(),
+    startedAt: z.string().nullable(),
+    lastUpdated: z.string(),
+    patterns: z.array(z.object({
+        name: z.string(),
+        description: z.string()
+    })),
+    taskLogs: z.array(taskLogSchema)
+});
+export function parseTasksFile(value) {
+    return tasksFileSchema.parse(value);
+}
+export function parseProgressFile(value) {
+    return progressFileSchema.parse(value);
+}

package/dist/server/utils/task-graph.js

@@ -1,6 +1,6 @@
 import { promises as fs } from 'node:fs';
-import { join } from 'node:path';
 import { getPrdState, getPrdStateSummaries, migrateLegacyStateForRepo } from './prd-state.js';
+import { resolvePrdMarkdownPath } from './prd-service.js';
 const NODE_SEPARATOR = '::';
 const MISSING_PREFIX = 'missing';
 export function createTaskNodeId(prdSlug, taskId) {
@@ -39,8 +39,8 @@ function parseDependency(rawDependency, currentPrdSlug) {
     };
 }
 async function resolvePrdName(repo, prdSlug) {
-    const prdPath = join(repo.path, 'docs', 'prd', `${prdSlug}.md`);
     try {
+        const prdPath = resolvePrdMarkdownPath(repo.path, prdSlug);
         const content = await fs.readFile(prdPath, 'utf-8');
         const h1Match = content.match(/^#\s+(.+)$/m);
         return h1Match?.[1]?.trim() || prdSlug;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thxgg/steward",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Local-first PRD workflow steward with codemode MCP and web UI.",
   "type": "module",
   "author": "thxgg",
@@ -49,6 +49,7 @@
     "preview": "nuxt preview",
     "mcp": "npm run build:host && node ./bin/prd mcp",
     "ui": "npm run build && node ./bin/prd ui",
+    "test": "npm run build:host && node --test \"tests/**/*.test.mjs\"",
     "typecheck": "nuxt typecheck && npm run typecheck:host",
     "typecheck:host": "tsc -p tsconfig.host.json",
     "prepack": "npm run build"