@cherishxn/agent-scaffold 0.0.0-stage → 1.1.0

package/dist/verify.js

@@ -0,0 +1,278 @@
+import { diagnose } from './diagnostics.js';
+import { spawn } from 'node:child_process';
+import { mkdir, readFile, writeFile, readdir, lstat } from 'node:fs/promises';
+import { resolve, join, relative } from 'node:path';
+import { randomBytes, randomUUID } from 'node:crypto';
+import { createServer } from 'node:net';
+import { platform, arch } from 'node:os';
+import { jsonFile, specFrom } from './generate.js';
+import { CLI_VERSION, digest, canonical, ScaffoldError } from './model.js';
+const envKeys = ['PATH', 'HOME', 'TMPDIR', 'TMP', 'TEMP', 'JAVA_HOME', 'PNPM_HOME', 'UV_CACHE_DIR', 'COREPACK_HOME', 'DOCKER_HOST', 'DOCKER_CONTEXT', 'XDG_CACHE_HOME'];
+function cleanEnv() { return Object.fromEntries(envKeys.flatMap(k => process.env[k] === undefined ? [] : [[k, process.env[k]]])); }
+async function project(dir) { const m = await jsonFile(join(dir, '.scaffold-manifest.json')); if (m.status !== 'complete')
+    throw new ScaffoldError('NOT_INITIALIZED', 'A complete scaffold manifest is required.'); return specFrom(m.normalizedSpec); }
+async function execute(program, args, cwd, env, timeout = 30000, abort) {
+    return new Promise(resolveResult => {
+        let text = '', timedOut = false, settled = false;
+        const c = spawn(program, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'], detached: process.platform !== 'win32' });
+        const append = (chunk) => { if (text.length < 8_000_000)
+            text += chunk.toString('utf8'); };
+        c.stdout.on('data', append);
+        c.stderr.on('data', append);
+        function kill() { if (c.pid)
+            try {
+                process.kill(process.platform === 'win32' ? c.pid : -c.pid, 'SIGTERM');
+            }
+            catch { /* Process already exited. */ } }
+        const timer = setTimeout(() => { timedOut = true; kill(); }, timeout);
+        const hardKill = () => { if (c.pid)
+            try {
+                process.kill(process.platform === 'win32' ? c.pid : -c.pid, 'SIGKILL');
+            }
+            catch { /* Already gone. */ } };
+        const hardTimer = setTimeout(hardKill, timeout + 5000);
+        let abortTimer;
+        const onAbort = () => { kill(); abortTimer = setTimeout(hardKill, 5000); };
+        abort?.addEventListener('abort', onAbort, { once: true });
+        if (abort?.aborted)
+            onAbort();
+        function finish(code, signal) { if (settled)
+            return; settled = true; clearTimeout(timer); clearTimeout(hardTimer); clearTimeout(abortTimer); abort?.removeEventListener('abort', onAbort); resolveResult({ code, signal, output: text + (text.length >= 8_000_000 ? '\n[output truncated]' : ''), timedOut }); }
+        c.on('error', error => { append(Buffer.from(`\n${error.code ?? 'SPAWN_ERROR'}: ${error.message}`)); finish(127, null); });
+        c.on('close', (code, signal) => finish(code, signal));
+    });
+}
+export async function doctor(directory, options = {}) {
+    const dir = resolve(directory), spec = await project(dir), env = cleanEnv();
+    const needs = [
+        { program: 'node', args: ['--version'], label: 'node', remedy: 'Use Node.js 24, then rerun doctor.', accept: output => /^v24\./.test(output.trim()) },
+        { program: 'docker', args: ['info', '--format', '{{.ServerVersion}}'], label: 'docker', remedy: 'Start Docker and check that docker info succeeds for the selected context.' },
+        { program: 'docker', args: ['compose', 'version', '--short'], label: 'docker compose', remedy: 'Install the Docker Compose v2 plugin, then rerun doctor.' }
+    ];
+    if (spec.template === 'react-fastapi')
+        needs.push({ program: 'uv', args: ['--version'], label: 'uv', remedy: 'Install uv and add it to PATH; setup uses the locked Python 3.12 project.' }, { program: 'bun', args: ['--version'], label: 'bun', remedy: 'Install Bun and add it to PATH for the frontend lockfile.' });
+    else
+        needs.push({ program: 'pnpm', args: ['--version'], label: 'pnpm', remedy: 'Use pnpm 10 and add it to PATH.', accept: output => /^10\./.test(output.trim()) });
+    if (spec.template === 'react-spring')
+        needs.push({ program: 'java', args: ['-version'], label: 'java', remedy: 'Use JDK 17 or newer and check JAVA_HOME/PATH.', accept: output => { const major = output.match(/version "(\d+)/)?.[1]; return Number(major) >= 17; } }, { program: 'javac', args: ['-version'], label: 'javac', remedy: 'Install a full JDK 17 or newer (not just a JRE), and put its bin directory on PATH.', accept: output => Number(output.match(/javac (\d+)/)?.[1]) >= 17 });
+    const checks = await Promise.all(needs.map(async (need) => {
+        const r = await execute(need.program, need.args, dir, env, 15000);
+        const ok = r.code === 0 && !r.timedOut && (!need.accept || need.accept(r.output));
+        return { program: need.label, ok, version: r.code === 0 ? r.output.trim().split('\n')[0] : 'unavailable', remedy: ok ? null : need.remedy };
+    }));
+    if (!options.toolsOnly)
+        for (const path of ['node_modules/@playwright/test/package.json', 'web/node_modules/react/package.json', ...(spec.template === 'react-nest' ? ['backend/node_modules/@nestjs/core/package.json'] : [])]) {
+            try {
+                await lstat(join(dir, path));
+                checks.push({ program: path, ok: true, version: 'installed', remedy: null });
+            }
+            catch {
+                checks.push({ program: path, ok: false, version: 'not installed', remedy: 'Run npm run setup for local development, or npm run installProject to install dependencies only.' });
+            }
+        }
+    return { ok: checks.every(c => c.ok), scope: options.toolsOnly ? 'tools' : 'tools-and-dependencies', checks, platform: `${platform()}-${arch()}`, template: spec.template };
+}
+const excluded = new Set(['.git', 'node_modules', '.venv', '__pycache__', '.pytest_cache', '.ruff_cache', '.mypy_cache', '.next', 'target', 'dist', 'reports', 'playwright-report', 'test-results', '.scaffold-runs', '.scaffold-local-credentials']);
+export async function contentDigest(dir) {
+    const files = [];
+    async function visit(at) { for (const e of await readdir(at, { withFileTypes: true })) {
+        if (excluded.has(e.name) || e.name === '.env' || e.name.startsWith('.env.') && e.name !== '.env.example' || e.name.endsWith('.tsbuildinfo'))
+            continue;
+        const full = join(at, e.name);
+        if (e.isSymbolicLink())
+            throw new ScaffoldError('SYMLINK', 'Evidence cannot follow workspace symbolic links.', 2, relative(dir, full));
+        if (e.isDirectory())
+            await visit(full);
+        else if (e.isFile())
+            files.push({ path: relative(dir, full), digest: digest(await readFile(full)) });
+    } }
+    await visit(dir);
+    files.sort((a, b) => a.path.localeCompare(b.path, 'en'));
+    return digest(canonical(files));
+}
+async function freePort() { return new Promise((yes, no) => { const s = createServer(); s.on('error', no); s.listen(0, '127.0.0.1', () => { const address = s.address(); if (!address || typeof address === 'string')
+    return no(new Error('No port')); const port = address.port; s.close(() => yes(port)); }); }); }
+function redact(text, values) { for (const v of values.filter(v => v.length > 3).sort((a, b) => b.length - a.length))
+    text = text.split(v).join('[REDACTED]'); return text.replace(/postgres(?:ql)?:\/\/[^\s"']+/g, '[REDACTED_DATABASE_URL]'); }
+async function nativeReport(reportDir, spec) {
+    if (spec.template !== 'react-spring')
+        return [join(reportDir, 'native.xml')];
+    const folder = join(reportDir, 'spring');
+    try {
+        return (await readdir(folder)).filter(n => n.startsWith('TEST-') && n.endsWith('.xml')).map(n => join(folder, n));
+    }
+    catch {
+        return [];
+    }
+}
+async function executedReports(paths) {
+    if (!paths.length)
+        return false;
+    let executed = 0;
+    for (const path of paths) {
+        let xml;
+        try {
+            xml = await readFile(path, 'utf8');
+        }
+        catch {
+            return false;
+        }
+        const cases = [...xml.matchAll(/<testcase\b[^>]*?(?:\/>|>([\s\S]*?)<\/testcase>)/g)];
+        for (const match of cases) {
+            const body = match[1] ?? '';
+            if (/<(?:failure|error)\b/.test(body))
+                return false;
+            if (!/<skipped\b/.test(body))
+                executed++;
+        }
+    }
+    return executed > 0;
+}
+async function sanitizeArtifacts(folder, secrets) {
+    const files = [];
+    async function visit(at) {
+        for (const entry of await readdir(at, { withFileTypes: true })) {
+            const path = join(at, entry.name);
+            if (entry.isSymbolicLink())
+                throw new Error('Report symbolic link is not allowed');
+            if (entry.isDirectory())
+                await visit(path);
+            else if (entry.isFile()) {
+                await writeFile(path, redact(await readFile(path, 'utf8'), secrets), { mode: 0o600 });
+                files.push(path);
+            }
+        }
+    }
+    await visit(folder);
+    return files;
+}
+export async function verify(directory) {
+    const dir = resolve(directory), spec = await project(dir), start = new Date().toISOString(), runId = randomUUID();
+    const reportDir = join(dir, '.scaffold-runs', runId), artifacts = join(reportDir, 'artifacts');
+    await mkdir(artifacts, { recursive: true, mode: 0o700 });
+    const beforeDigest = await contentDigest(dir), checks = [], warnings = [];
+    const baseEnv = cleanEnv(), secrets = [];
+    let containerId = '', interrupted = false, failed = false, incomplete = false, internal = false;
+    const abort = new AbortController();
+    const interrupt = () => { interrupted = true; abort.abort(); };
+    process.once('SIGINT', interrupt);
+    process.once('SIGTERM', interrupt);
+    const now = () => new Date().toISOString();
+    async function check(id, fn) {
+        const begin = now();
+        process.stderr.write(`[${id}] checking\n`);
+        try {
+            const { result, evidence = [] } = await fn();
+            const log = join(reportDir, `${id}.log`);
+            await writeFile(log, redact(result.output, secrets), { mode: 0o600 });
+            const ok = result.code === 0 && !result.timedOut && !interrupted;
+            checks.push({ id, status: interrupted ? 'NOT RUN' : ok ? 'PASS' : 'FAIL', reason: interrupted ? 'Interrupted' : result.timedOut ? 'Timed out' : ok ? 'Completed' : 'Command failed or required report missing', startedAt: begin, finishedAt: now(), exitCode: result.code, signal: result.signal, evidence: [relative(dir, log), ...evidence], diagnostic: ok ? null : diagnose(id, result.output, { timedOut: result.timedOut, interrupted }) });
+            if (!ok && !interrupted)
+                failed = true;
+        }
+        catch (error) {
+            const output = redact(error instanceof Error ? error.message : 'Unknown execution error', secrets), log = join(reportDir, `${id}.log`);
+            await writeFile(log, output, { mode: 0o600 });
+            checks.push({ id, status: interrupted ? 'NOT RUN' : 'FAIL', reason: 'Check could not complete', startedAt: begin, finishedAt: now(), exitCode: null, signal: null, evidence: [relative(dir, log)], diagnostic: diagnose(id, output, { interrupted }) });
+            if (!interrupted)
+                failed = true;
+        }
+    }
+    function skip(id, reason) { checks.push({ id, status: 'NOT RUN', reason, startedAt: now(), finishedAt: now(), exitCode: null, signal: null, evidence: [] }); incomplete = true; }
+    try {
+        const prerequisites = await doctor(dir);
+        checks.push({ id: 'environment', status: prerequisites.ok ? 'PASS' : 'NOT RUN', reason: prerequisites.ok ? 'Required tools and dependencies available' : prerequisites.checks.filter(c => !c.ok).map(c => c.program).join(', '), startedAt: start, finishedAt: now(), exitCode: prerequisites.ok ? 0 : 3, signal: null, evidence: [] });
+        if (!prerequisites.ok)
+            incomplete = true;
+        const password = randomBytes(24).toString('hex'), secret = randomBytes(32).toString('hex'), seedPassword = randomBytes(18).toString('hex'), bodyMarker = `record-body-${randomUUID()}`;
+        secrets.push(password, secret, seedPassword, bodyMarker);
+        let env = { ...baseEnv, SCAFFOLD_TEST: '1', SCAFFOLD_REPORT_DIR: artifacts, NODE_ENV: 'test', AUTH_SECRET: secret, SEED_A_EMAIL: `a-${runId}@example.test`, SEED_B_EMAIL: `b-${runId}@example.test`, SEED_PASSWORD: seedPassword, TEST_BODY_MARKER: bodyMarker, NEXT_TELEMETRY_DISABLED: '1', CI: '1' };
+        if (!incomplete && !interrupted) {
+            await check('database', async () => {
+                const creation = await execute('docker', ['run', '--detach', '--name', `agent-scaffold-${runId}`, '--label', `agent-scaffold.run=${runId}`, '-e', 'POSTGRES_PASSWORD', '-e', 'POSTGRES_USER=app', '-e', 'POSTGRES_DB=app', '-p', '127.0.0.1::5432', 'postgres:17.9-alpine@sha256:c7526c0f6c3f30260a563d7bcf8ad778effac59a44f8ffa86678c35418338609'], dir, { ...baseEnv, POSTGRES_PASSWORD: password }, 180000, abort.signal);
+                if (creation.code !== 0)
+                    return { result: creation };
+                containerId = creation.output.trim().split('\n').at(-1) ?? '';
+                if (!/^[a-f0-9]{64}$/.test(containerId))
+                    throw new Error('Invalid container id');
+                const inspect = await execute('docker', ['inspect', '--format', '{{json .NetworkSettings.Ports}}', containerId], dir, baseEnv);
+                const mappings = JSON.parse(inspect.output);
+                const mapping = mappings['5432/tcp']?.[0];
+                if (inspect.code !== 0 || !mapping || mapping.HostIp !== '127.0.0.1')
+                    throw new Error('Invalid endpoint');
+                const databaseUrl = `postgresql://app:${password}@127.0.0.1:${mapping.HostPort}/app`;
+                secrets.push(databaseUrl);
+                const contextPath = join(reportDir, 'database.json');
+                await writeFile(contextPath, JSON.stringify({ runId, containerId, databaseUrl }), { mode: 0o600 });
+                env = { ...env, DATABASE_URL: databaseUrl, SCAFFOLD_TEST_CONTEXT: contextPath, WEB_PORT: String(await freePort()), PORT: String(await freePort()) };
+                env.APP_ORIGIN = `http://127.0.0.1:${env.WEB_PORT}`;
+                let ready = { code: 1, signal: null, output: 'Database did not become ready', timedOut: false };
+                for (let n = 0; n < 30 && !interrupted; n++) {
+                    ready = await execute('docker', ['exec', containerId, 'pg_isready', '-h', '127.0.0.1', '-U', 'app', '-d', 'app'], dir, baseEnv, 5000, abort.signal);
+                    if (ready.code === 0)
+                        break;
+                    await new Promise(r => setTimeout(r, 1000));
+                }
+                return { result: ready };
+            });
+        }
+        else
+            skip('database', 'Environment unavailable or interrupted');
+        for (const id of ['api:check', 'typecheck', 'lint', 'build', 'migrate', 'seed', 'test:native', 'test:api', 'test:e2e']) {
+            if (failed || incomplete || interrupted) {
+                skip(id, 'A required prerequisite failed or was not run');
+                continue;
+            }
+            await check(id.replace(':', '-'), async () => {
+                const reportFile = join(artifacts, id === 'test:api' ? 'api.xml' : 'e2e.xml');
+                const result = await execute('node', ['scripts/project.mjs', id], dir, { ...env, PLAYWRIGHT_JUNIT_OUTPUT_FILE: reportFile }, 600000, abort.signal);
+                let evidence = [];
+                if (id.startsWith('test:')) {
+                    const required = id === 'test:native' ? await nativeReport(artifacts, spec) : [reportFile];
+                    const valid = await executedReports(required);
+                    // Sanitize every produced artifact even on failure or interruption, before publishing evidence.
+                    const produced = await sanitizeArtifacts(artifacts, secrets);
+                    evidence = produced.map(path => relative(dir, path));
+                    if (result.code === 0 && !valid) {
+                        result.code = 1;
+                        result.output += '\nRequired report missing, contains failures, or has no executed test cases.';
+                    }
+                }
+                return { result, evidence };
+            });
+        }
+    }
+    catch (error) {
+        internal = true;
+        const log = join(reportDir, 'internal.log');
+        await writeFile(log, redact(error instanceof Error ? error.message : 'Unknown internal error', secrets), { mode: 0o600 });
+        warnings.push('Verification stopped due to an internal error. See ' + relative(dir, log));
+    }
+    finally {
+        // Only delete a container whose immutable ID and run label match this invocation.
+        if (containerId) {
+            await check('cleanup', async () => { const owner = await execute('docker', ['inspect', '--format', '{{index .Config.Labels "agent-scaffold.run"}}', containerId], dir, baseEnv); if (owner.code !== 0 || owner.output.trim() !== runId)
+                throw new Error('Uncertain ownership'); return { result: await execute('docker', ['rm', '-f', containerId], dir, baseEnv, 30000) }; });
+        }
+        process.removeListener('SIGINT', interrupt);
+        process.removeListener('SIGTERM', interrupt);
+    }
+    const afterDigest = await contentDigest(dir);
+    const validity = beforeDigest === afterDigest ? 'CURRENT' : 'STALE';
+    if (validity === 'STALE') {
+        warnings.push('Workspace content changed during verification; results are not for the current candidate.');
+        incomplete = true;
+    }
+    const exitCode = interrupted ? 130 : internal ? 5 : failed ? 4 : incomplete ? 3 : 0;
+    const run = { schemaVersion: 1, runId, template: spec.template, cliVersion: CLI_VERSION, platform: `${platform()}-${arch()}`, runtime: process.version, startedAt: start, finishedAt: now(), beforeDigest, afterDigest, overallStatus: failed || internal ? 'FAIL' : exitCode !== 0 ? 'NOT RUN' : 'PASS', validity, checks, exitCode, warnings };
+    await writeFile(join(reportDir, 'result.json'), JSON.stringify(run, null, 2) + '\n', { mode: 0o600 });
+    await writeFile(join(dir, '.scaffold-runs/latest.json'), JSON.stringify({ runId }) + '\n', { mode: 0o600 });
+    return run;
+}
+export async function report(directory) { const dir = resolve(directory); await project(dir); let latest; try {
+    latest = await jsonFile(join(dir, '.scaffold-runs/latest.json'));
+}
+catch {
+    return { overallStatus: 'NOT RUN', reason: 'No verification result exists.' };
+} if (!/^[a-f0-9-]{36}$/.test(latest.runId))
+    throw new ScaffoldError('INVALID_REPORT', 'Invalid report identifier.'); const result = await jsonFile(join(dir, '.scaffold-runs', latest.runId, 'result.json')); const current = await contentDigest(dir); return { ...result, validity: result.validity === 'CURRENT' && result.afterDigest === current ? 'CURRENT' : 'STALE' }; }

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@cherishxn/agent-scaffold",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "type": "module",
+  "description": "Deterministic project scaffolding for coding agents",
+  "bin": {
+    "scaffold": "dist/cli.js"
+  },
+  "engines": {
+    "node": ">=24 <25"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "schemas",
+    "skills",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "scripts": {
+    "build": "node scripts/materialize.mjs && tsc && node scripts/catalog.mjs",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src tests",
+    "test": "npm run build && vitest run",
+    "check": "npm run typecheck && npm run lint && npm test",
+    "prepack": "npm run build",
+    "matrix": "node scripts/matrix.mjs",
+    "test:interactive": "python3 scripts/test-interactive.py",
+    "test:package": "node scripts/test-package.mjs",
+    "design:verify": "npm run build && node scripts/design-matrix.mjs",
+    "test:onboarding": "node scripts/test-onboarding.mjs",
+    "eval:codex": "node scripts/eval-codex.mjs"
+  },
+  "dependencies": {
+    "ajv": "8.20.0",
+    "commander": "15.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@google/design.md": "0.4.0",
+    "@types/node": "24.19.2",
+    "ajv-formats": "3.0.1",
+    "eslint": "10.13.0",
+    "openapi-typescript": "7.13.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.71.2",
+    "vitest": "5.0.5"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/schemas/manifest.json

@@ -0,0 +1,171 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "cliVersion",
+    "templateId",
+    "templateVersion",
+    "templateDigest",
+    "normalizedSpec",
+    "files",
+    "nextActions",
+    "planDigest",
+    "status"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "cliVersion": {
+      "type": "string"
+    },
+    "templateId": {
+      "enum": [
+        "react-fastapi",
+        "react-spring",
+        "react-nest",
+        "next-fullstack"
+      ]
+    },
+    "templateVersion": {
+      "type": "string"
+    },
+    "templateDigest": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "normalizedSpec": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "nameZh",
+        "nameEn",
+        "description",
+        "template",
+        "ui"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": 1
+        },
+        "nameZh": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 120,
+          "pattern": "^[^\\r\\n\\x00-\\x1f]+$"
+        },
+        "nameEn": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 50,
+          "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1000,
+          "pattern": "^[^\\x00-\\x08\\x0b\\x0c\\x0e-\\x1f]+$"
+        },
+        "template": {
+          "enum": [
+            "react-fastapi",
+            "react-spring",
+            "react-nest",
+            "next-fullstack"
+          ]
+        },
+        "ui": {
+          "enum": [
+            "shadcn",
+            "antd"
+          ]
+        }
+      }
+    },
+    "files": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "path",
+          "source",
+          "digest",
+          "mode"
+        ],
+        "properties": {
+          "path": {
+            "type": "string"
+          },
+          "source": {
+            "type": "string"
+          },
+          "digest": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{64}$"
+          },
+          "mode": {
+            "enum": [
+              420,
+              493
+            ]
+          }
+        }
+      }
+    },
+    "nextActions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "program",
+          "args",
+          "cwd",
+          "prerequisites",
+          "sideEffects"
+        ],
+        "properties": {
+          "program": {
+            "type": "string"
+          },
+          "args": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "cwd": {
+            "type": "string"
+          },
+          "prerequisites": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "sideEffects": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "planDigest": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "status": {
+      "enum": [
+        "generating",
+        "complete"
+      ]
+    }
+  }
+}

package/schemas/plan.json

@@ -0,0 +1,164 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "cliVersion",
+    "templateId",
+    "templateVersion",
+    "templateDigest",
+    "normalizedSpec",
+    "files",
+    "nextActions",
+    "planDigest"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "cliVersion": {
+      "type": "string"
+    },
+    "templateId": {
+      "enum": [
+        "react-fastapi",
+        "react-spring",
+        "react-nest",
+        "next-fullstack"
+      ]
+    },
+    "templateVersion": {
+      "type": "string"
+    },
+    "templateDigest": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "normalizedSpec": {
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "nameZh",
+        "nameEn",
+        "description",
+        "template",
+        "ui"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": 1
+        },
+        "nameZh": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 120,
+          "pattern": "^[^\\r\\n\\x00-\\x1f]+$"
+        },
+        "nameEn": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 50,
+          "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1000,
+          "pattern": "^[^\\x00-\\x08\\x0b\\x0c\\x0e-\\x1f]+$"
+        },
+        "template": {
+          "enum": [
+            "react-fastapi",
+            "react-spring",
+            "react-nest",
+            "next-fullstack"
+          ]
+        },
+        "ui": {
+          "enum": [
+            "shadcn",
+            "antd"
+          ]
+        }
+      }
+    },
+    "files": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "path",
+          "source",
+          "digest",
+          "mode"
+        ],
+        "properties": {
+          "path": {
+            "type": "string"
+          },
+          "source": {
+            "type": "string"
+          },
+          "digest": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{64}$"
+          },
+          "mode": {
+            "enum": [
+              420,
+              493
+            ]
+          }
+        }
+      }
+    },
+    "nextActions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "program",
+          "args",
+          "cwd",
+          "prerequisites",
+          "sideEffects"
+        ],
+        "properties": {
+          "program": {
+            "type": "string"
+          },
+          "args": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "cwd": {
+            "type": "string"
+          },
+          "prerequisites": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "sideEffects": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "planDigest": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    }
+  }
+}