@njeybe/nativ 2.4.1 → 2.5.0

package/dist/scanner/detectors/workspace-detector.js

@@ -0,0 +1,266 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export function detectWorkspacesAndServices(resolvedTarget, fileExists, readFileSafe) {
+    const monorepoIndicators = [];
+    const monorepoWorkspaces = [];
+    const keyDirectories = [];
+    const ecosystemManifests = [];
+    let detectedSubpackagesCount = 0;
+    if (fileExists('pnpm-workspace.yaml')) {
+        ecosystemManifests.push('pnpm-workspace.yaml');
+        monorepoIndicators.push('pnpm workspaces');
+        const pnpmWorkspace = readFileSafe(path.join(resolvedTarget, 'pnpm-workspace.yaml'));
+        const packageLines = pnpmWorkspace
+            .split('\n')
+            .map((l) => l.trim())
+            .filter((l) => l.startsWith('-'))
+            .map((l) => l.replace(/^-\s*['"]?/, '').replace(/['"]?$/, '').trim());
+        if (packageLines.length > 0) {
+            monorepoWorkspaces.push(...packageLines);
+        }
+    }
+    if (fileExists('turbo.json')) {
+        ecosystemManifests.push('turbo.json');
+        monorepoIndicators.push('Turborepo');
+    }
+    if (fileExists('nx.json')) {
+        ecosystemManifests.push('nx.json');
+        monorepoIndicators.push('Nx');
+    }
+    if (fileExists('lerna.json')) {
+        ecosystemManifests.push('lerna.json');
+        monorepoIndicators.push('Lerna');
+    }
+    const candidateWorkspaceDirs = ['apps', 'packages', 'services', 'libs', 'modules'];
+    for (const wDir of candidateWorkspaceDirs) {
+        const fullWDir = path.join(resolvedTarget, wDir);
+        if (fs.existsSync(fullWDir) && fs.statSync(fullWDir).isDirectory()) {
+            keyDirectories.push(wDir);
+            if (!monorepoWorkspaces.includes(`${wDir}/*`)) {
+                monorepoWorkspaces.push(`${wDir}/*`);
+            }
+            try {
+                const children = fs.readdirSync(fullWDir);
+                for (const child of children) {
+                    const childPath = path.join(fullWDir, child);
+                    if (fs.statSync(childPath).isDirectory()) {
+                        if (fs.existsSync(path.join(childPath, 'package.json')) ||
+                            fs.existsSync(path.join(childPath, 'go.mod')) ||
+                            fs.existsSync(path.join(childPath, 'pom.xml')) ||
+                            fs.existsSync(path.join(childPath, 'composer.json'))) {
+                            detectedSubpackagesCount++;
+                        }
+                    }
+                }
+            }
+            catch {
+                // ignore read error
+            }
+        }
+    }
+    const independentServices = [];
+    try {
+        const rootItems = fs.readdirSync(resolvedTarget);
+        for (const item of rootItems) {
+            if (item.startsWith('.') ||
+                item === 'node_modules' ||
+                item === 'vendor' ||
+                item === 'dist' ||
+                item === 'build' ||
+                item === 'templates' ||
+                item === 'bin' ||
+                item === 'public') {
+                continue;
+            }
+            const itemPath = path.join(resolvedTarget, item);
+            if (fs.existsSync(itemPath) && fs.statSync(itemPath).isDirectory()) {
+                const subPathItem = (filename) => fs.existsSync(path.join(itemPath, filename));
+                const subManifests = [];
+                if (subPathItem('package.json'))
+                    subManifests.push('package.json');
+                if (subPathItem('composer.json'))
+                    subManifests.push('composer.json');
+                if (subPathItem('go.mod'))
+                    subManifests.push('go.mod');
+                if (subPathItem('Cargo.toml'))
+                    subManifests.push('Cargo.toml');
+                if (subPathItem('pom.xml'))
+                    subManifests.push('pom.xml');
+                if (subPathItem('build.gradle'))
+                    subManifests.push('build.gradle');
+                if (subPathItem('build.gradle.kts'))
+                    subManifests.push('build.gradle.kts');
+                if (subPathItem('pyproject.toml'))
+                    subManifests.push('pyproject.toml');
+                if (subPathItem('requirements.txt'))
+                    subManifests.push('requirements.txt');
+                if (subPathItem('pubspec.yaml'))
+                    subManifests.push('pubspec.yaml');
+                if (subPathItem('Podfile'))
+                    subManifests.push('Podfile');
+                if (subPathItem('AndroidManifest.xml'))
+                    subManifests.push('AndroidManifest.xml');
+                if (subManifests.length > 0) {
+                    if (!keyDirectories.includes(item)) {
+                        keyDirectories.push(item);
+                    }
+                    let subTech = 'Service';
+                    let subRuntime = '';
+                    let subFramework = '';
+                    let subOrm = '';
+                    let subOrmConfig = '';
+                    if (subPathItem('pubspec.yaml')) {
+                        subTech = 'Flutter Mobile App';
+                        subRuntime = 'Dart / Flutter';
+                        subFramework = 'Flutter';
+                    }
+                    else if (subPathItem('Podfile') || subPathItem('Info.plist') || fs.existsSync(path.join(itemPath, 'ios'))) {
+                        subTech = 'Native iOS App (Swift/Obj-C)';
+                        subRuntime = 'Swift / Objective-C';
+                        subFramework = 'iOS Native';
+                    }
+                    else if (subPathItem('AndroidManifest.xml') || (subPathItem('build.gradle') && !subPathItem('package.json'))) {
+                        subTech = 'Native Android App (Kotlin/Java)';
+                        subRuntime = 'Kotlin / Java (Android)';
+                        subFramework = 'Android Native';
+                    }
+                    else if (subPathItem('composer.json')) {
+                        subRuntime = 'PHP';
+                        subTech = 'PHP Backend';
+                        try {
+                            const subComposer = JSON.parse(readFileSafe(path.join(itemPath, 'composer.json')));
+                            const allReq = { ...subComposer.require, ...subComposer['require-dev'] };
+                            if (allReq['laravel/framework']) {
+                                subFramework = 'Laravel';
+                                subTech = 'Laravel Backend (PHP)';
+                                subOrm = 'Eloquent ORM';
+                            }
+                            else if (allReq['symfony/framework-bundle']) {
+                                subFramework = 'Symfony';
+                                subTech = 'Symfony Backend (PHP)';
+                                subOrm = 'Doctrine ORM';
+                            }
+                        }
+                        catch { }
+                        if (fs.existsSync(path.join(itemPath, 'database/migrations'))) {
+                            subOrmConfig = `${item}/database/migrations`;
+                            if (!subOrm)
+                                subOrm = 'SQL Migrations';
+                        }
+                    }
+                    else if (subPathItem('pyproject.toml') || subPathItem('requirements.txt')) {
+                        subRuntime = 'Python';
+                        subTech = 'Python Backend';
+                        const pyStr = readFileSafe(path.join(itemPath, 'requirements.txt')) + readFileSafe(path.join(itemPath, 'pyproject.toml'));
+                        if (pyStr.includes('fastapi')) {
+                            subFramework = 'FastAPI';
+                            subTech = 'FastAPI Backend (Python)';
+                        }
+                        else if (pyStr.includes('django')) {
+                            subFramework = 'Django';
+                            subTech = 'Django Backend (Python)';
+                            subOrm = 'Django ORM';
+                        }
+                        else if (pyStr.includes('flask')) {
+                            subFramework = 'Flask';
+                            subTech = 'Flask Backend (Python)';
+                        }
+                        if (pyStr.includes('sqlalchemy') || fs.existsSync(path.join(itemPath, 'alembic.ini'))) {
+                            subOrm = 'SQLAlchemy';
+                            if (fs.existsSync(path.join(itemPath, 'alembic.ini'))) {
+                                subOrmConfig = `${item}/alembic.ini`;
+                            }
+                        }
+                    }
+                    else if (subPathItem('go.mod')) {
+                        subRuntime = 'Go';
+                        subTech = 'Go Backend';
+                        const goStr = readFileSafe(path.join(itemPath, 'go.mod'));
+                        if (goStr.includes('gin-gonic/gin')) {
+                            subFramework = 'Gin';
+                            subTech = 'Gin Backend (Go)';
+                        }
+                        else if (goStr.includes('gofiber/fiber')) {
+                            subFramework = 'Fiber';
+                            subTech = 'Fiber Backend (Go)';
+                        }
+                        if (goStr.includes('gorm.io/gorm'))
+                            subOrm = 'GORM';
+                    }
+                    else if (subPathItem('package.json')) {
+                        subRuntime = 'Node.js';
+                        subTech = 'Node.js Service';
+                        try {
+                            const subPkg = JSON.parse(readFileSafe(path.join(itemPath, 'package.json')));
+                            const subDeps = { ...subPkg.dependencies, ...subPkg.devDependencies };
+                            if (subDeps.typescript || fs.existsSync(path.join(itemPath, 'tsconfig.json'))) {
+                                subRuntime = 'Node.js (TypeScript)';
+                            }
+                            if (subDeps['react-native'] || subDeps['expo']) {
+                                subTech = 'React Native / Expo Mobile App';
+                                subFramework = subDeps.expo ? 'Expo Mobile App' : 'React Native';
+                            }
+                            else if (subDeps.next) {
+                                subTech = 'Next.js Web App';
+                                subFramework = 'Next.js';
+                            }
+                            else if (subDeps.nuxt) {
+                                subTech = 'Nuxt Web App';
+                                subFramework = 'Nuxt';
+                            }
+                            else if (subDeps.vite || subDeps.react || subDeps.vue) {
+                                subTech = 'React / Web Frontend';
+                                subFramework = subDeps.vite ? 'Vite Frontend' : (subDeps.react ? 'React SPA' : 'Vue SPA');
+                            }
+                            else if (subDeps.express || subDeps['@nestjs/core'] || subDeps.fastify) {
+                                subTech = 'Node.js Backend';
+                                subFramework = subDeps['@nestjs/core'] ? 'NestJS' : (subDeps.fastify ? 'Fastify' : 'Express.js');
+                            }
+                            if (subDeps.prisma || fs.existsSync(path.join(itemPath, 'prisma/schema.prisma'))) {
+                                subOrm = 'Prisma ORM';
+                                subOrmConfig = `${item}/prisma/schema.prisma`;
+                            }
+                            else if (subDeps['drizzle-orm'] || fs.existsSync(path.join(itemPath, 'drizzle.config.ts'))) {
+                                subOrm = 'Drizzle ORM';
+                                subOrmConfig = `${item}/drizzle.config.ts`;
+                            }
+                            else if (subDeps.typeorm) {
+                                subOrm = 'TypeORM';
+                            }
+                            else if (subDeps.mongoose) {
+                                subOrm = 'Mongoose';
+                            }
+                        }
+                        catch {
+                            subTech = 'Node.js / Web App';
+                        }
+                    }
+                    independentServices.push({
+                        name: item,
+                        dirPath: itemPath,
+                        manifests: subManifests,
+                        tech: subTech,
+                        runtime: subRuntime,
+                        framework: subFramework,
+                        orm: subOrm,
+                        ormConfig: subOrmConfig,
+                    });
+                    if (!monorepoWorkspaces.includes(`${item}/*`) && !candidateWorkspaceDirs.includes(item)) {
+                        monorepoWorkspaces.push(`${item}/*`);
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        // ignore read error
+    }
+    return {
+        monorepoIndicators,
+        monorepoWorkspaces,
+        keyDirectories,
+        detectedSubpackagesCount,
+        independentServices,
+        ecosystemManifests,
+    };
+}

package/dist/server/cli-runner.d.ts

@@ -0,0 +1,15 @@
+export declare function truncateOutput(text: string): string;
+export interface CapturedRun<T> {
+    result: T;
+    /** Console output with ANSI colors stripped. */
+    output: string;
+    /** True when the handler set a non-zero process.exitCode. */
+    failed: boolean;
+}
+/**
+ * The CLI command handlers report through console.* and process.exitCode, which are process-global,
+ * so captured runs are serialized (same approach as the MCP server).
+ */
+export declare function runCaptured<T>(fn: () => Promise<T>): Promise<CapturedRun<T>>;
+/** `--json` CLI handlers print `{ success: false, error }` on failure. */
+export declare function jsonErrorMessage(output: string): string | null;

package/dist/server/cli-runner.js

@@ -0,0 +1,43 @@
+const MAX_ERROR_OUTPUT_CHARS = 4000;
+const ANSI_PATTERN = /\x1b\[[0-9;]*m/g;
+export function truncateOutput(text) {
+    return text.length > MAX_ERROR_OUTPUT_CHARS ? `${text.slice(0, MAX_ERROR_OUTPUT_CHARS)}…` : text;
+}
+let captureQueue = Promise.resolve();
+/**
+ * The CLI command handlers report through console.* and process.exitCode, which are process-global,
+ * so captured runs are serialized (same approach as the MCP server).
+ */
+export function runCaptured(fn) {
+    const run = async () => {
+        const lines = [];
+        const original = { log: console.log, error: console.error, warn: console.warn, info: console.info };
+        const previousExitCode = process.exitCode;
+        process.exitCode = undefined;
+        console.log = console.error = console.warn = console.info = (...args) => {
+            lines.push(args.map((a) => (typeof a === 'string' ? a : JSON.stringify(a))).join(' '));
+        };
+        try {
+            const result = await fn();
+            const failed = process.exitCode !== undefined && process.exitCode !== 0;
+            return { result, failed, output: lines.join('\n').replace(ANSI_PATTERN, '').trim() };
+        }
+        finally {
+            Object.assign(console, original);
+            process.exitCode = previousExitCode;
+        }
+    };
+    const result = captureQueue.then(run, run);
+    captureQueue = result.catch(() => undefined);
+    return result;
+}
+/** `--json` CLI handlers print `{ success: false, error }` on failure. */
+export function jsonErrorMessage(output) {
+    try {
+        const parsed = JSON.parse(output);
+        return typeof parsed?.error === 'string' ? parsed.error : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/server/event-hub.d.ts

@@ -0,0 +1,42 @@
+import type http from 'node:http';
+export declare const DEFAULT_HEARTBEAT_MS = 15000;
+export declare const EVENT_DEBOUNCE_MS = 100;
+export declare const WATCH_POLL_INTERVAL_MS = 1000;
+export type PipelineEventName = 'plan_change' | 'telemetry_change';
+/** Files in .ai/ that drive /api/events, mapped to the event a change emits. Anything else (tmp/lock files) is ignored. */
+export declare const WATCHED_FILES: Map<string, PipelineEventName>;
+/**
+ * Fan-out for GET /api/events. Watches .ai/ only while a client is connected, coalesces write bursts
+ * (tmp file + atomic rename + lock files) into one event per type, and sends heartbeats so idle
+ * streams survive proxies and sleep/wake.
+ *
+ * Frames: `event: plan_change` / `event: telemetry_change` with `data: {"files":[...],"at":"<ISO>"}`,
+ * and `event: heartbeat` with `data: {"at":"<ISO>"}`.
+ */
+export declare class PipelineEventHub {
+    private readonly aiDir;
+    private readonly heartbeatMs;
+    private readonly onFileChange?;
+    private readonly clients;
+    private readonly pending;
+    private watcher;
+    private pollers;
+    private heartbeat;
+    private flushTimer;
+    private closed;
+    constructor(aiDir: string, heartbeatMs: number, onFileChange?: ((file: string) => void) | undefined);
+    subscribe(res: http.ServerResponse): void;
+    /** Pushes an agent-supervisor event (`runner_status`, `runner_log`, `runner_token_usage`) to every connected client. */
+    publish(event: 'runner_status' | 'runner_log' | 'runner_token_usage', data: unknown): void;
+    publishPlanChange(files?: string[]): void;
+    /** SSE responses never finish on their own; drop them so http.Server#close() can complete. */
+    close(): void;
+    private start;
+    private startWatcher;
+    private startPolling;
+    private stop;
+    private closeWatcher;
+    private queue;
+    private flush;
+    private broadcast;
+}

package/dist/server/event-hub.js

@@ -0,0 +1,169 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { sendPipelineError } from './http-utils.js';
+export const DEFAULT_HEARTBEAT_MS = 15_000;
+export const EVENT_DEBOUNCE_MS = 100;
+export const WATCH_POLL_INTERVAL_MS = 1000;
+/** Files in .ai/ that drive /api/events, mapped to the event a change emits. Anything else (tmp/lock files) is ignored. */
+export const WATCHED_FILES = new Map([
+    ['master_plan.json', 'plan_change'],
+    ['escalation.json', 'plan_change'],
+    ['.governor_ledger.json', 'plan_change'],
+    ['context.md', 'plan_change'],
+    ['db_schema.json', 'plan_change'],
+    ['api_contracts.json', 'plan_change'],
+    ['ui_specs.md', 'plan_change'],
+    ['telemetry.json', 'telemetry_change'],
+    ['benchmark_report.json', 'telemetry_change'],
+]);
+/**
+ * Fan-out for GET /api/events. Watches .ai/ only while a client is connected, coalesces write bursts
+ * (tmp file + atomic rename + lock files) into one event per type, and sends heartbeats so idle
+ * streams survive proxies and sleep/wake.
+ *
+ * Frames: `event: plan_change` / `event: telemetry_change` with `data: {"files":[...],"at":"<ISO>"}`,
+ * and `event: heartbeat` with `data: {"at":"<ISO>"}`.
+ */
+export class PipelineEventHub {
+    aiDir;
+    heartbeatMs;
+    onFileChange;
+    clients = new Set();
+    pending = new Map();
+    watcher = null;
+    pollers = [];
+    heartbeat = null;
+    flushTimer = null;
+    closed = false;
+    constructor(aiDir, heartbeatMs, onFileChange) {
+        this.aiDir = aiDir;
+        this.heartbeatMs = heartbeatMs;
+        this.onFileChange = onFileChange;
+        this.startWatcher();
+    }
+    subscribe(res) {
+        if (this.closed) {
+            sendPipelineError(res, 503, 'SHUTTING_DOWN', 'Studio server is shutting down');
+            return;
+        }
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream; charset=utf-8',
+            'Cache-Control': 'no-store',
+            Connection: 'keep-alive',
+            'X-Accel-Buffering': 'no',
+            'X-Content-Type-Options': 'nosniff',
+        });
+        res.socket?.setNoDelay(true);
+        // Reconnect delay for EventSource; the comment line flushes the headers right away.
+        res.write('retry: 3000\n: connected\n\n');
+        this.clients.add(res);
+        res.on('close', () => {
+            this.clients.delete(res);
+            if (this.clients.size === 0 && this.heartbeat) {
+                clearInterval(this.heartbeat);
+                this.heartbeat = null;
+            }
+        });
+        if (!this.heartbeat) {
+            this.heartbeat = setInterval(() => this.broadcast('heartbeat', { at: new Date().toISOString() }), this.heartbeatMs);
+            this.heartbeat.unref();
+        }
+        this.startWatcher();
+    }
+    /** Pushes an agent-supervisor event (`runner_status`, `runner_log`, `runner_token_usage`) to every connected client. */
+    publish(event, data) {
+        if (this.closed || this.clients.size === 0)
+            return;
+        this.broadcast(event, data);
+    }
+    publishPlanChange(files = ['escalation.json']) {
+        if (this.closed || this.clients.size === 0)
+            return;
+        this.broadcast('plan_change', { files, at: new Date().toISOString() });
+    }
+    /** SSE responses never finish on their own; drop them so http.Server#close() can complete. */
+    close() {
+        this.closed = true;
+        for (const res of this.clients)
+            res.destroy();
+        this.clients.clear();
+        this.stop();
+    }
+    start() {
+        this.startWatcher();
+    }
+    startWatcher() {
+        if (this.watcher || this.pollers.length)
+            return;
+        try {
+            this.watcher = fs.watch(this.aiDir, { persistent: false }, (_event, filename) => {
+                if (filename)
+                    this.queue(String(filename));
+            });
+            this.watcher.on('error', () => {
+                this.closeWatcher();
+                this.startPolling();
+            });
+        }
+        catch {
+            // .ai/ is missing (studio started before `nativ init`) or not watchable: poll the files instead.
+            this.startPolling();
+        }
+    }
+    startPolling() {
+        if (this.pollers.length)
+            return;
+        for (const file of WATCHED_FILES.keys()) {
+            // Missing files report zeroed stats, so an unchanged mtime means nothing happened.
+            const listener = (curr, prev) => {
+                if (curr.mtimeMs !== prev.mtimeMs)
+                    this.queue(file);
+            };
+            fs.watchFile(path.join(this.aiDir, file), { interval: WATCH_POLL_INTERVAL_MS, persistent: false }, listener);
+            this.pollers.push({ file, listener });
+        }
+    }
+    stop() {
+        if (this.heartbeat)
+            clearInterval(this.heartbeat);
+        if (this.flushTimer)
+            clearTimeout(this.flushTimer);
+        this.heartbeat = this.flushTimer = null;
+        this.pending.clear();
+        this.closeWatcher();
+        for (const { file, listener } of this.pollers)
+            fs.unwatchFile(path.join(this.aiDir, file), listener);
+        this.pollers = [];
+    }
+    closeWatcher() {
+        this.watcher?.close();
+        this.watcher = null;
+    }
+    queue(file) {
+        try {
+            this.onFileChange?.(file);
+        }
+        catch {
+            // Ignore consumer callback error
+        }
+        const event = WATCHED_FILES.get(file);
+        if (!event)
+            return;
+        const files = this.pending.get(event) ?? new Set();
+        files.add(file);
+        this.pending.set(event, files);
+        this.flushTimer ??= setTimeout(() => this.flush(), EVENT_DEBOUNCE_MS);
+    }
+    flush() {
+        this.flushTimer = null;
+        const at = new Date().toISOString();
+        for (const [event, files] of this.pending)
+            this.broadcast(event, { files: [...files], at });
+        this.pending.clear();
+    }
+    broadcast(event, data) {
+        const frame = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+        for (const res of this.clients)
+            res.write(frame);
+    }
+}

package/dist/server/http-utils.d.ts

@@ -0,0 +1,15 @@
+import type http from 'node:http';
+import type { DatabaseEnv } from '../db/types.js';
+export declare const MAX_BODY_BYTES: number;
+export declare const LOOPBACK_HOSTS: Set<string>;
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+export declare function sendJson(res: http.ServerResponse, status: number, body: unknown): void;
+export declare function sendError(res: http.ServerResponse, status: number, code: string, message: string): void;
+/** /api/pipeline/* errors use the contract's `{ ok: false, error }` envelope. */
+export declare function sendPipelineError(res: http.ServerResponse, status: number, code: string, message: string): void;
+export declare function readJsonBody(req: http.IncomingMessage): Promise<Record<string, unknown>>;
+export declare function parseEnv(value: unknown, field: string): DatabaseEnv;

package/dist/server/http-utils.js

@@ -0,0 +1,56 @@
+export const MAX_BODY_BYTES = 64 * 1024;
+export const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
+export class HttpError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+export function sendJson(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Content-Length': Buffer.byteLength(payload),
+        'Cache-Control': 'no-store',
+        'X-Content-Type-Options': 'nosniff',
+    });
+    res.end(payload);
+}
+export function sendError(res, status, code, message) {
+    sendJson(res, status, { error: { code, message } });
+}
+/** /api/pipeline/* errors use the contract's `{ ok: false, error }` envelope. */
+export function sendPipelineError(res, status, code, message) {
+    sendJson(res, status, { ok: false, error: message, code });
+}
+export async function readJsonBody(req) {
+    const contentType = String(req.headers['content-type'] ?? '');
+    if (!contentType.toLowerCase().startsWith('application/json')) {
+        throw new HttpError(415, 'UNSUPPORTED_MEDIA_TYPE', 'Content-Type must be application/json');
+    }
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES)
+            throw new HttpError(413, 'PAYLOAD_TOO_LARGE', 'Request body exceeds 64KB');
+        chunks.push(chunk);
+    }
+    try {
+        const parsed = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            throw new Error('not an object');
+        return parsed;
+    }
+    catch {
+        throw new HttpError(400, 'INVALID_JSON', 'Request body must be a JSON object');
+    }
+}
+export function parseEnv(value, field) {
+    if (value === 'dev' || value === 'prod')
+        return value;
+    throw new HttpError(400, 'VALIDATION_ERROR', `"${field}" must be 'dev' or 'prod'`);
+}

package/dist/server/plan-utils.d.ts

@@ -0,0 +1,9 @@
+import type { MasterPlan, MasterPlanMilestone, MasterPlanTask } from '../scanner/types.js';
+export declare const AI_DIR = ".ai";
+export declare const TASK_ID_PATTERN: RegExp;
+export declare function readPlan(root: string): MasterPlan | null;
+/** Milestones with a usable task list; tolerates hand-edited or half-written plans. */
+export declare function planMilestones(plan: MasterPlan | null): MasterPlanMilestone[];
+export declare function findTask(plan: MasterPlan | null, taskId: string): MasterPlanTask | null;
+/** Task ids reach git branch names and shell commands in the worktree handlers, so the charset is strict. */
+export declare function parseTaskId(value: unknown): string;

package/dist/server/plan-utils.js

@@ -0,0 +1,31 @@
+import path from 'node:path';
+import { loadPlan } from '../core/lock-manager.js';
+import { HttpError } from './http-utils.js';
+export const AI_DIR = '.ai';
+export const TASK_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+export function readPlan(root) {
+    return loadPlan(path.join(root, AI_DIR, 'master_plan.json'), { silent: true, retries: 3 });
+}
+/** Milestones with a usable task list; tolerates hand-edited or half-written plans. */
+export function planMilestones(plan) {
+    const milestones = plan?.milestones;
+    if (!Array.isArray(milestones))
+        return [];
+    return milestones.filter((m) => m && Array.isArray(m.tasks));
+}
+export function findTask(plan, taskId) {
+    for (const m of planMilestones(plan)) {
+        const task = m.tasks.find((t) => t.id === taskId);
+        if (task)
+            return task;
+    }
+    return null;
+}
+/** Task ids reach git branch names and shell commands in the worktree handlers, so the charset is strict. */
+export function parseTaskId(value) {
+    const taskId = typeof value === 'string' ? value.trim() : '';
+    if (!TASK_ID_PATTERN.test(taskId)) {
+        throw new HttpError(400, 'VALIDATION_ERROR', '"taskId" must be a task id (letters, digits, ".", "_" or "-")');
+    }
+    return taskId;
+}