@cherishxn/agent-scaffold 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qinchaomeishenmeshi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# Agent Scaffold
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+面向 Codex、Claude Code、Grok Build 的项目脚手架。四套技术栈（React + FastAPI、React + Spring Boot、React + NestJS、Next.js）各支持 shadcn/ui 和 Ant Design，共八个组合。生成应用包含登录和个人记录 CRUD，默认不含 AI。
+
+## 选择技术栈
+
+| 已有偏好 | 建议起点 | 额外运行环境 |
+| --- | --- | --- |
+| Python 后端 | React + FastAPI | Python 3.12、uv、Bun |
+| Java / Spring 团队 | React + Spring Boot | JDK 17 或更高版本、pnpm 10；自带 Maven Wrapper |
+| 前后端都用 TypeScript，独立 API | React + NestJS | pnpm 10 |
+| 一个 TypeScript 全栈工程 | Next.js | pnpm 10 |
+
+都需要 Node.js 24 和 Docker。没有既定偏好时可从 Next.js + shadcn 开始；两种 UI 的设计意图和业务能力保持一致，按组件库偏好选择。
+
+## 本地使用
+
+需要 Node.js 24：
+
+```bash
+npx @cherishxn/agent-scaffold@latest init
+```
+
+交互创建收集中文名称、英文名称、简介、技术栈和 UI；确认前不写项目文件。也可创建 `spec.json`：
+
+```json
+{"schemaVersion":1,"nameZh":"客户服务平台","nameEn":"customer-service","description":"客户资料和服务记录管理","template":"react-fastapi","ui":"shadcn"}
+```
+
+```bash
+npx @cherishxn/agent-scaffold@latest templates --json
+npx @cherishxn/agent-scaffold@latest init --help --json
+npx @cherishxn/agent-scaffold@latest plan --spec spec.json --out plan.json --json
+npx @cherishxn/agent-scaffold@latest init --plan plan.json --json
+```
+
+1.1.0 候选支持 `plan --spec spec.json --json` 的零写入预览；只有提供 `--out` 才保存计划。预览与创建使用同一精确 CLI 版本，计划绑定模板摘要。当前公开版与候选验收状态见 [验证记录](docs/VERIFICATION.md)。
+
+也可直接 `init --spec spec.json --json`。命令返回安装步骤和工作目录，不自动安装依赖或启动服务。进入生成目录后：
+
+```bash
+npm run setup
+npm run dev
+```
+
+开发账号与随机密码写入被 Git 忽略的 `.scaffold-local-credentials`。FastAPI 需要 Python 3.12、uv、Bun；Spring 需要 Java 17 和 pnpm；Nest/Next 需要 pnpm。数据库使用 Docker。具体版本锁定在模板中。
+
+## 检查与报告
+
+1.1.0 候选提供安装前工具检查 `doctor --dir . --tools-only --json`，失败项会说明修复方法；默认 doctor 同时检查项目依赖。它只诊断，不安装工具或启动服务。
+
+新生成项目的 `npm run check` 按类型、Lint、构建顺序执行，遇到失败即停止，适合日常反馈；它不替代以下真实业务验证。
+
+
+```bash
+npx @cherishxn/agent-scaffold@latest doctor --dir . --json
+npx @cherishxn/agent-scaffold@latest verify --dir . --json
+npx @cherishxn/agent-scaffold@latest report --dir . --json
+```
+
+verify 启动独立 PostgreSQL，运行类型、Lint、构建、迁移、种子数据、原生测试、API 和浏览器测试，并清理本次容器。不会使用开发环境的数据库连接。结果保存于 `.scaffold-runs`，包含内容摘要和原生报告引用；代码变化后 report 标记 STALE。失败、空测试、缺前置与中断不会标为 PASS。生成项目的 verify 会执行该项目脚本，仅对自己信任的项目运行。
+
+## 视觉设计
+
+八组合默认使用从 [CleerScience](https://cleerscience.com/) 提炼的深色科技视觉：近黑蓝底、冷白文字、冰蓝强调与直角面板。可独立复用的 [通用 DESIGN.md](docs/reference/CLEERSCIENCE-DESIGN.md) 区分官网实测与产品适配；生成项目的根 DESIGN.md 是当前 UI 的实际规范。
+
+设计采用四层分离：共享 `design/` 规范、语义 Widget 契约、组件库适配层、独立业务模型。`design:sync` 生成 DESIGN.md、CSS 和运行时规范；`design:check` 检测漂移；`design:verify` 验证全部组件状态及页面在桌面/移动端的几何、颜色、圆角和图标。位置容差 0.6px，其余指定属性严格相等。生成项目内置三宿主可发现的 `design-contract` Skill。根目录 `npm run design:verify` 运行全部八种组合并比较跨模板测量；单个生成项目仅验证已选适配器。
+
+## Agent 入口
+
+打包后的 CLI 包含 `skills/scaffold-use/SKILL.md`。按当前宿主约定，把该目录复制到发起创建的工作目录：Codex 使用 `.agents/skills/scaffold-use`，Claude Code 使用 `.claude/skills/scaffold-use`，Grok Build 使用 `.grok/skills/scaffold-use`。这一步由使用者或已获授权的 Agent 执行；CLI 不改全局配置。
+
+生成项目自带 AGENTS.md、薄 CLAUDE.md，以及上述三个原生目录下同源的 project-work Skill。docs/PROJECT.md 的任务表按实际技术栈指向 API、认证、迁移、设计和测试入口。切换到新工程后核对规则与 Skill 是否加载。具体宿主兼容范围以交付记录为准。
+
+## 开发与分发
+
+```bash
+npm run check
+npm run test:interactive
+npm run test:package
+npm run test:onboarding
+npm run matrix
+npm pack
+```
+
+源码仓库保持私有，CLI 按发布白名单分发至 npm 公共包。`npm pack` 构建包含八套模板与锁文件的本地安装包。模板源码位于 template-src；templates 是可重新生成的产物。普通模板层只允许添加文件，路径冲突会停止构建；生成文件或锁文件替换由 materialize 脚本显式完成。更新依赖后运行 scripts/lock-templates.mjs 并重新验证受影响矩阵。
+
+[开发计划](docs/DEVELOPMENT-PLAN.md) · [验证记录](docs/VERIFICATION.md) · [设计基线 v0.5](docs/reference/AGENT-SCAFFOLD-DESIGN-v0.5.md) · [来源与许可证](THIRD_PARTY_NOTICES.md)
+
+运行测试通过不代表生产部署或产品/PM 业务验收完成。
+
+本轮选择性学习 VibeStart 的预览、Agent 指引、快速反馈与模板文件归属机制；具体采用项和保留边界见 [源码研究与采纳映射](docs/reference/VIBESTART-REVIEW.md)。实现沿用本项目架构，未引入其技术栈或全量源码。
+
+## 验证反馈与接口一致性
+
+verify 保留原退出码和报告字段，失败分项新增 diagnostic（code、retryable、nextAction），evidence 指向脱敏日志及 JUnit。端口冲突、连接拒绝、主机解析失败、启动失败、超时与缺测试证据分开；未知错误保持 UNKNOWN_FAILURE，不自动重试或修改运行环境。API/浏览器测试采集服务 stdout/stderr。
+
+生成项目提供 `npm run api:check`：在系统临时目录生成类型并比较 docs/api.d.ts，检查不回写源码；有意修改 docs/openapi.json 后运行 `npm run api:generate`。check/verify 自动运行此门禁，真实 HTTP 回归按契约检查响应状态和结构。
+
+Codex 接手开发的固定题库、运行方法与局限见 [评测说明](evals/codex/README.md)。这与模板本身的八组合业务矩阵分别留证。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,18 @@
+# Template sources and licenses
+
+Templates are maintained derivatives, not unmodified upstream distributions. Exact bundled files are hashed in templates/catalog.json; npm/uv/pnpm/Bun locks pin dependency resolution. Initialization is offline and never invokes upstream generators.
+
+| Source | Fixed reference | Use / modifications | License |
+| --- | --- | --- | --- |
+| fastapi/full-stack-fastapi-template | b1125d8839482cb7bbae603ddc6d0081bf87532e | SQLModel/Alembic/JWT/pwdlib foundation; reduced accounts, replaced sample feature with owner-scoped records, retained Bun frontend | MIT, licenses/fastapi.txt |
+| nestjs/typescript-starter | a122dea65cd0610ee205d7765ed46f9d73629141 | Nest module/bootstrap foundation; added Prisma, JWT/Guard, Jest/Supertest; no deployment tooling | MIT, licenses/nest.txt |
+| Spring Initializr | starter.zip fetched 2026-10-19; Maven Wrapper and Java layout | Generator returned unresolved 4.1.1.RELEASE; parent adjusted to stable Maven Central 3.5.16, Session/JPA/Flyway/CRUD added | Apache-2.0 wrapper, licenses/spring.txt |
+| create-next-app | npm 16.4.2 | Official App Router/TypeScript baseline; Better Auth + Prisma + records; no remote fonts | MIT, licenses/next.txt |
+| shadcn/ui | Button/Input pattern, pinned source reference in licenses/sources.json | Adapted local CVA/Slot controls with Tailwind; retained copy ownership | MIT, licenses/shadcn.txt |
+| Ant Design | npm 6.6.6 | Installed dependency; no copied source | MIT (package license) |
+
+Package dependencies carry their own licenses. Generated apps include these notices; template authors must carry applicable notices when changing upstream-derived files. Names and marks remain their respective owners'.
+
+## Design and workflow reference
+
+VinkyDev/vibestart at commit `5768fc561340422bf7736499fe69b1aae263790a` (MIT) informed the preview, task-oriented Agent guidance, quick checks and template-layer collision rules. These changes are independently implemented for Agent Scaffold; no VibeStart source, bundled skills, branding or UI assets are redistributed. The source review and selected adaptations are recorded in docs/reference/VIBESTART-REVIEW.md.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { createInterface } from 'node:readline/promises';
+import { resolve, join } from 'node:path';
+import { stdin, stdout } from 'node:process';
+import { CLI_VERSION, ScaffoldError, templates, uis } from './model.js';
+import { catalog, initialize, jsonFile, makePlan, validatePlan, writePlan, packageRoot } from './generate.js';
+import { doctor, verify, report } from './verify.js';
+const args = process.argv.slice(2);
+const json = args.includes('--json');
+let commandName = 'scaffold';
+function output(data, nextActions = []) {
+    const payload = { schemaVersion: 1, command: commandName, status: 'success', data, errors: [], warnings: [], nextActions };
+    stdout.write(JSON.stringify(payload, null, json ? undefined : 2) + '\n');
+}
+async function interactive() {
+    const r = createInterface({ input: stdin, output: stdout });
+    const abort = new AbortController();
+    let interrupted = false;
+    const stop = () => { interrupted = true; abort.abort(); r.close(); };
+    r.on('SIGINT', stop);
+    process.once('SIGINT', stop);
+    const ask = (prompt) => r.question(prompt, { signal: abort.signal });
+    try {
+        const nameZh = await ask('项目中文名称：');
+        const nameEn = await ask('项目英文名称（小写字母、数字、连字符）：');
+        const description = await ask('项目简介：');
+        const templateAnswer = (await ask('技术栈 1 FastAPI / 2 Spring / 3 Nest / 4 Next [1]：')).trim() || '1';
+        const uiAnswer = (await ask('UI 1 shadcn/ui / 2 Ant Design [1]：')).trim() || '1';
+        const template = templates[Number(templateAnswer) - 1] ?? templateAnswer;
+        const ui = uis[Number(uiAnswer) - 1] ?? uiAnswer;
+        const input = { schemaVersion: 1, nameZh, nameEn, description, template, ui };
+        const plan = await makePlan(input);
+        const dir = (await ask(`创建目录 [./${plan.normalizedSpec.nameEn}]：`)).trim() || `./${plan.normalizedSpec.nameEn}`;
+        stdout.write(JSON.stringify({ project: plan.normalizedSpec, directory: resolve(dir), files: plan.files.length }, null, 2) + '\n');
+        const yes = (await ask('确认创建？[y/N]：')).trim().toLowerCase();
+        if (!['y', 'yes', '是'].includes(yes))
+            throw new ScaffoldError('CANCELLED', 'Creation cancelled; no project files were written.', 130);
+        return { spec: plan.normalizedSpec, dir };
+    }
+    catch (error) {
+        if (interrupted)
+            throw new ScaffoldError('CANCELLED', 'Creation interrupted; no project files were written.', 130);
+        throw error;
+    }
+    finally {
+        process.removeListener('SIGINT', stop);
+        r.close();
+    }
+}
+const program = new Command().name('scaffold').version(CLI_VERSION).description('Create and verify complete web projects.').option('--json', 'Non-interactive JSON output').exitOverride().configureOutput({ writeOut: s => process.stdout.write(s), writeErr: s => process.stderr.write(s) });
+program.command('templates').description('List bundled templates and input schema').action(async () => { commandName = 'templates'; output(await catalog()); });
+program.command('plan').description('Preview a deterministic plan; write it only when --out is provided').requiredOption('--spec <file>').option('--out <file>', 'Write to a new plan file').action(async (o) => { commandName = 'plan'; const spec = await jsonFile(o.spec); output(o.out ? await writePlan(spec, o.out) : await makePlan(spec)); });
+program.command('init').description('Create a project interactively, from JSON spec, or from a plan').option('--spec <file>').option('--plan <file>').option('--dir <path>').action(async (o) => {
+    commandName = 'init';
+    if (o.spec && o.plan)
+        throw new ScaffoldError('MODE_CONFLICT', '--spec and --plan are mutually exclusive.');
+    let plan;
+    if (o.plan)
+        plan = await validatePlan(await jsonFile(o.plan));
+    else if (o.spec)
+        plan = await makePlan(await jsonFile(o.spec));
+    else {
+        if (json || !stdin.isTTY || !stdout.isTTY)
+            throw new ScaffoldError('MISSING_INPUT', 'Provide --spec or --plan in non-interactive mode.');
+        const i = await interactive();
+        plan = await makePlan(i.spec);
+        o.dir = o.dir ?? i.dir;
+    }
+    const result = await initialize(plan, o.dir ?? plan.normalizedSpec.nameEn);
+    if (json)
+        output(result, result.nextActions);
+    else {
+        const directory = "'" + result.directory.replaceAll("'", "'\"'\"'") + "'";
+        stdout.write(`\n${result.status === 'created' ? '已创建' : '工程已存在且内容一致'}：${plan.normalizedSpec.nameZh}\n${plan.templateId} / ${plan.normalizedSpec.ui}\n目录：${result.directory}\n\n下一步：\n  cd ${directory}\n  npm run setup\n  npm run dev\n\n安装前检查：npx @cherishxn/agent-scaffold@${CLI_VERSION} doctor --dir . --tools-only --json\n开发规则：AGENTS.md；任务路径：docs/PROJECT.md；本地账号：.scaffold-local-credentials（setup 后生成）\n项目文件已生成；依赖安装、启动与业务验证尚未执行。\n`);
+    }
+});
+program.command('doctor').description('Read-only local prerequisite checks').requiredOption('--dir <path>').option('--tools-only', 'Check tools before installing project dependencies').action(async (o) => { commandName = 'doctor'; const r = await doctor(o.dir, { toolsOnly: o.toolsOnly }); output(r); process.exitCode = r.ok ? 0 : 3; });
+program.command('verify').description('Run isolated baseline checks').requiredOption('--dir <path>').option('--profile <name>', 'Check profile', 'baseline').action(async (o) => { commandName = 'verify'; if (o.profile !== 'baseline')
+    throw new ScaffoldError('INVALID_PROFILE', 'Only baseline is supported.'); const r = await verify(o.dir); output(r); process.exitCode = r.exitCode; });
+program.command('report').description('Read latest results and current content validity').requiredOption('--dir <path>').action(async (o) => { commandName = 'report'; output(await report(o.dir)); });
+try {
+    if (json && (args.includes('--help') || args.includes('-h'))) {
+        const name = args.find(a => !a.startsWith('-'));
+        const c = name ? program.commands.find(c => c.name() === name) : program;
+        if (!c)
+            throw new ScaffoldError('UNKNOWN_COMMAND', 'Unknown command.');
+        commandName = 'help';
+        output({ version: CLI_VERSION, name: c.name(), description: c.description(), options: c.options.map(o => ({ flags: o.flags, description: o.description, required: o.mandatory })), commands: program.commands.map(c => ({ name: c.name(), description: c.description() })), schemas: ['spec', 'plan', 'manifest', 'result'].map(s => join(packageRoot, `schemas/${s}.json`)), exitCodes: { 0: 'command succeeded; inspect overallStatus for report', 2: 'invalid input', 3: 'environment or incomplete checks', 4: 'failed checks', 5: 'internal error', 130: 'interrupted' }, sideEffects: { templates: [], plan: ['write new plan only with --out'], init: ['write new project'], doctor: [], verify: ['build, isolated database, reports'], report: [] }, prerequisites: ['Node.js 24', 'See templates for stack-specific runtimes'] });
+    }
+    else if (args.length === 0)
+        program.help();
+    else
+        await program.parseAsync(process.argv);
+}
+catch (e) {
+    const c = e;
+    if (c.code === 'commander.helpDisplayed' || c.code === 'commander.version')
+        process.exitCode = 0;
+    else {
+        const error = e instanceof ScaffoldError ? e : new ScaffoldError(c.code?.startsWith('commander.') ? 'ARGUMENT_ERROR' : 'INTERNAL_ERROR', c.code?.startsWith('commander.') ? 'Invalid command arguments. See --help.' : 'Operation failed; no successful result was recorded.', c.code?.startsWith('commander.') ? 2 : 5);
+        stdout.write(JSON.stringify({ schemaVersion: 1, command: commandName, status: 'error', data: null, errors: [error.issue()], warnings: [], nextActions: [] }) + '\n');
+        process.exitCode = error.exitCode;
+    }
+}

package/dist/diagnostics.d.ts

@@ -0,0 +1,10 @@
+export type Diagnostic = {
+    code: string;
+    retryable: boolean;
+    nextAction: string;
+};
+/** Classify observed failures only; unknown output must not invent a root cause. */
+export declare function diagnose(stage: string, output: string, options?: {
+    timedOut?: boolean;
+    interrupted?: boolean;
+}): Diagnostic;

package/dist/diagnostics.js

@@ -0,0 +1,27 @@
+/** Classify observed failures only; unknown output must not invent a root cause. */
+export function diagnose(stage, output, options = {}) {
+    if (options.interrupted)
+        return { code: 'INTERRUPTED', retryable: false, nextAction: 'Review the completed steps and cleanup evidence before starting a new verification.' };
+    if (options.timedOut)
+        return { code: 'TIMEOUT', retryable: false, nextAction: 'Inspect the stage log and service startup output; resolve the stalled dependency before rerunning.' };
+    if (/EADDRINUSE|Address already in use|Port \d+ was already in use/i.test(output))
+        return { code: 'PORT_IN_USE', retryable: false, nextAction: 'Identify the process owning the reported port; choose a free port or stop only a process you own.' };
+    if (/UnknownHostException|Name or service not known|ENOTFOUND|getaddrinfo failed/i.test(output))
+        return { code: 'HOST_RESOLUTION_FAILED', retryable: false, nextAction: 'Check the failing hostname and this runtime\'s DNS/proxy configuration. Do not infer a database or application defect from this alone.' };
+    if (/ECONNREFUSED|Connection refused|connection to server .* failed|could not connect to server/i.test(output))
+        return { code: 'CONNECTION_REFUSED', retryable: false, nextAction: 'Use the endpoint in the log to check the expected service, port and runtime connectivity before retrying.' };
+    if (/Required report missing, contains failures, or has no executed test cases/.test(output))
+        return { code: 'TEST_EVIDENCE_INVALID', retryable: false, nextAction: 'Inspect the test command and JUnit artifact; missing, empty or failing reports cannot prove a pass.' };
+    if (/API_CONTRACT_DRIFT/.test(output))
+        return { code: 'API_CONTRACT_DRIFT', retryable: false, nextAction: 'Compare the contract and generated types; run api:generate after the intended contract change, then api:check.' };
+    if (/API_RESPONSE_INVALID/.test(output))
+        return { code: 'API_RESPONSE_INVALID', retryable: false, nextAction: 'Compare the reported operation, response status and schema path with the intended HTTP behavior.' };
+    if (/spawn(?:Sync)? \S+ ENOENT|command not found/.test(output))
+        return { code: 'COMMAND_NOT_FOUND', retryable: false, nextAction: 'Run doctor and install the missing executable or correct its path.' };
+    if (/ENOENT/.test(output))
+        return { code: 'FILE_NOT_FOUND', retryable: false, nextAction: 'Inspect the missing file path and the stage that requested it; an ENOENT file error does not establish a missing executable.' };
+    if (stage === 'test-api' || stage === 'test-e2e')
+        if (/Process from config.webServer|webServer.*(?:exited|failed)|Timed out waiting.*config.webServer/i.test(output))
+            return { code: 'SERVICE_START_FAILED', retryable: false, nextAction: 'Inspect the captured webServer stdout/stderr for the first startup error; the underlying cause is not yet classified.' };
+    return { code: 'UNKNOWN_FAILURE', retryable: false, nextAction: 'Inspect the linked log and artifacts. The cause is unknown; do not automatically repeat the action or modify unrelated code.' };
+}

package/dist/generate.d.ts

@@ -0,0 +1,55 @@
+import { type Spec, type Action } from './model.js';
+export declare const packageRoot: string;
+export type FileEntry = {
+    path: string;
+    source: string;
+    digest: string;
+    mode: number;
+};
+export type Plan = {
+    schemaVersion: 1;
+    cliVersion: string;
+    templateId: string;
+    templateVersion: string;
+    templateDigest: string;
+    normalizedSpec: Spec;
+    files: FileEntry[];
+    nextActions: Action[];
+    planDigest: string;
+};
+export declare function jsonFile(path: string): Promise<unknown>;
+export declare function specFrom(input: unknown): Promise<Spec>;
+export declare function walk(root: string, prefix?: string): Promise<string[]>;
+export declare function makePlan(input: unknown): Promise<Plan>;
+export declare function validatePlan(input: unknown): Promise<Plan>;
+export declare function writePlan(input: unknown, output: string): Promise<Plan>;
+export declare function initialize(plan: Plan, target: string): Promise<{
+    directory: string;
+    status: string;
+    nextActions: {
+        cwd: string;
+        program: string;
+        args: string[];
+        prerequisites: string[];
+        sideEffects: string[];
+    }[];
+}>;
+export declare function catalog(): Promise<{
+    version: string;
+    templates: {
+        id: "react-fastapi" | "react-spring" | "react-nest" | "next-fullstack";
+        uis: ("shadcn" | "antd")[];
+        node: string;
+        database: string;
+        requirements: string[];
+    }[];
+    specSchema: string;
+    example: {
+        schemaVersion: number;
+        nameZh: string;
+        nameEn: string;
+        description: string;
+        template: string;
+        ui: string;
+    };
+}>;

package/dist/generate.js

@@ -0,0 +1,159 @@
+import { readFile, readdir, lstat, mkdir, writeFile, access } from 'node:fs/promises';
+import { join, resolve, dirname, relative, isAbsolute, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Ajv } from 'ajv';
+import { canonical, digest, ScaffoldError, CLI_VERSION, templates, uis } from './model.js';
+export const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+export async function jsonFile(path) {
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        throw new ScaffoldError('INVALID_JSON', 'Cannot read a valid JSON file.', 2, path);
+    }
+}
+export async function specFrom(input) {
+    const schema = await jsonFile(join(packageRoot, 'schemas/spec.json'));
+    const ajv = new Ajv({ allErrors: true });
+    const validate = ajv.compile(schema);
+    const normalized = input && typeof input === 'object' && !Array.isArray(input) ? Object.fromEntries(Object.entries(input).map(([k, v]) => [k, typeof v === 'string' ? v.trim() : v])) : input;
+    if (!validate(normalized)) {
+        const e = validate.errors?.[0];
+        const field = e?.instancePath || String(e?.params.missingProperty ?? 'spec');
+        const reason = e?.keyword === 'enum' ? `Choose one of: ${e.params.allowedValues.join(', ')}.`
+            : field === '/nameEn' ? 'Use 1–50 lowercase letters, digits and single hyphens; start with a letter (for example: my-project).'
+                : e?.keyword === 'additionalProperties' ? `Unknown field: ${String(e.params.additionalProperty)}. See templates --json for the input schema.`
+                    : `${e?.message ?? 'Invalid project specification'}. See templates --json for an example.`;
+        throw new ScaffoldError('INVALID_SPEC', reason, 2, field);
+    }
+    return normalized;
+}
+export async function walk(root, prefix = '') {
+    const out = [];
+    for (const entry of await readdir(join(root, prefix), { withFileTypes: true })) {
+        const name = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isSymbolicLink())
+            throw new ScaffoldError('SYMLINK', 'Symbolic links are not allowed in template/output files.', 2, name);
+        if (entry.isDirectory())
+            out.push(...await walk(root, name));
+        else if (entry.isFile())
+            out.push(name);
+        else
+            throw new ScaffoldError('FILE_TYPE', 'Unsupported file type.', 2, name);
+    }
+    return out.sort();
+}
+async function render(spec) {
+    const dir = join(packageRoot, 'templates', `${spec.template}-${spec.ui}`);
+    const catalog = await jsonFile(join(packageRoot, 'templates/catalog.json'));
+    const names = await walk(dir);
+    const source = await Promise.all(names.map(async (path) => ({ path, bytes: await readFile(join(dir, path)), mode: ((await lstat(join(dir, path))).mode & 0o111) ? 0o755 : 0o644 })));
+    const sourceDigest = digest(canonical(source.map(x => ({ path: x.path, digest: digest(x.bytes), mode: x.mode }))));
+    if (catalog.entries[`${spec.template}-${spec.ui}`]?.digest !== sourceDigest)
+        throw new ScaffoldError('TEMPLATE_INTEGRITY', 'Bundled template does not match the published catalog.');
+    const contents = new Map(source.map(x => [x.path === 'gitignore.template' ? '.gitignore' : x.path, { content: Buffer.from(x.bytes.toString('utf8').replaceAll('__NAME_EN__', spec.nameEn).replaceAll('__CLI_VERSION__', CLI_VERSION)), source: x.path, mode: x.mode }]));
+    contents.set('project.json', { content: Buffer.from(JSON.stringify(spec, null, 2) + '\n'), source: 'generated:spec', mode: 0o644 });
+    const pkg = contents.get('package.json');
+    if (pkg) {
+        const metadata = JSON.parse(pkg.content.toString());
+        metadata.description = spec.description;
+        pkg.content = Buffer.from(JSON.stringify(metadata, null, 2) + '\n');
+    }
+    const readme = contents.get('README.md');
+    if (readme)
+        readme.content = Buffer.from(`# ${spec.nameZh}\n\n${spec.description}\n\n` + readme.content.toString());
+    const project = contents.get('docs/PROJECT.md');
+    if (project)
+        project.content = Buffer.from(`# ${spec.nameZh}\n\n工程标识：${spec.nameEn}\n\n${spec.description}\n\n` + project.content.toString());
+    return { contents, sourceDigest };
+}
+function actions() { return ['setup', 'dev'].map(task => ({ program: 'npm', args: ['run', task], cwd: '.', prerequisites: task === 'setup' ? ['Node.js 24, Docker and template runtimes'] : ['Setup completed'], sideEffects: task === 'setup' ? ['Download locked dependencies and execute their installation scripts', 'Create local development database and explicitly seed development users'] : ['Build and start local application processes'] })); }
+export async function makePlan(input) {
+    const normalizedSpec = await specFrom(input);
+    const { contents, sourceDigest } = await render(normalizedSpec);
+    const base = { schemaVersion: 1, cliVersion: CLI_VERSION, templateId: normalizedSpec.template, templateVersion: CLI_VERSION, templateDigest: sourceDigest, normalizedSpec, files: [...contents].sort(([a], [b]) => a.localeCompare(b, 'en')).map(([path, f]) => ({ path, source: f.source, digest: digest(f.content), mode: f.mode })), nextActions: actions() };
+    return { ...base, planDigest: digest(canonical(base)) };
+}
+export async function validatePlan(input) {
+    if (!input || typeof input !== 'object' || !('normalizedSpec' in input))
+        throw new ScaffoldError('INVALID_PLAN', 'Plan must contain normalizedSpec.');
+    const expected = await makePlan(input.normalizedSpec);
+    if (canonical(input) !== canonical(expected))
+        throw new ScaffoldError('PLAN_MISMATCH', 'Plan does not match this CLI and bundled template. Generate a fresh plan.');
+    return expected;
+}
+export async function writePlan(input, output) {
+    const plan = await makePlan(input);
+    try {
+        await writeFile(output, JSON.stringify(plan, null, 2) + '\n', { flag: 'wx', mode: 0o644 });
+    }
+    catch {
+        throw new ScaffoldError('PLAN_OUTPUT', 'Cannot create plan; output must be a new writable file.', 2, output);
+    }
+    return plan;
+}
+async function rejectSymlinkAncestors(path) {
+    // /tmp and /var are OS aliases on macOS; resolve the caller-selected parent before checking children.
+    let cursor = resolve(path);
+    while (cursor !== dirname(cursor)) {
+        try {
+            if ((await lstat(cursor)).isSymbolicLink() && cursor !== '/tmp' && cursor !== '/var')
+                throw new ScaffoldError('SYMLINK', 'Target directory cannot traverse a symbolic link.', 2, cursor);
+        }
+        catch (e) {
+            if (e instanceof ScaffoldError)
+                throw e;
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+        cursor = dirname(cursor);
+    }
+}
+export async function initialize(plan, target) {
+    await validatePlan(plan);
+    const dir = resolve(target);
+    await rejectSymlinkAncestors(dir);
+    let existing = [];
+    try {
+        existing = await walk(dir);
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    const manifestPath = join(dir, '.scaffold-manifest.json');
+    if (existing.length) {
+        try {
+            const m = await jsonFile(manifestPath);
+            if (m.status === 'complete' && m.planDigest === plan.planDigest && existing.length === plan.files.length + 1) {
+                for (const f of plan.files) {
+                    if (digest(await readFile(join(dir, f.path))) !== f.digest)
+                        throw new Error('changed');
+                }
+                return { directory: dir, status: 'already_initialized', nextActions: plan.nextActions.map(a => ({ ...a, cwd: dir })) };
+            }
+        }
+        catch { /* Existing data is never overwritten. */ }
+        throw new ScaffoldError('DIRECTORY_CONFLICT', 'Target is non-empty or contains changed/incomplete output. Choose a new --dir; existing files were preserved.', 2, dir);
+    }
+    await mkdir(dir, { recursive: true });
+    // Reject even empty user-created subdirectories, and concurrent writes before the first output.
+    if ((await readdir(dir)).length)
+        throw new ScaffoldError('DIRECTORY_CONFLICT', 'Target must be empty.', 2, dir);
+    const manifest = { status: 'generating', ...plan };
+    await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n', { flag: 'wx' });
+    const { contents } = await render(plan.normalizedSpec);
+    for (const [path, f] of contents) {
+        if (isAbsolute(path) || relative(dir, resolve(dir, path)).split(sep).includes('..'))
+            throw new ScaffoldError('PATH_ESCAPE', 'Output path escapes target.');
+        await mkdir(dirname(join(dir, path)), { recursive: true });
+        await rejectSymlinkAncestors(join(dir, path));
+        await writeFile(join(dir, path), f.content, { flag: 'wx', mode: f.mode });
+    }
+    await writeFile(manifestPath, JSON.stringify({ ...manifest, status: 'complete' }, null, 2) + '\n');
+    return { directory: dir, status: 'created', nextActions: plan.nextActions.map(a => ({ ...a, cwd: dir })) };
+}
+export async function catalog() {
+    await access(join(packageRoot, 'templates/catalog.json'));
+    return { version: CLI_VERSION, templates: templates.map(id => ({ id, uis: [...uis], node: '24.x', database: 'PostgreSQL 17', requirements: id === 'react-fastapi' ? ['uv', 'Python 3.12', 'Bun', 'Docker'] : id === 'react-spring' ? ['Java 17', 'Maven Wrapper', 'pnpm', 'Docker'] : ['pnpm', 'Docker'] })), specSchema: join(packageRoot, 'schemas/spec.json'), example: { schemaVersion: 1, nameZh: '客户服务平台', nameEn: 'customer-service', description: '客户资料和服务记录管理', template: 'react-fastapi', ui: 'shadcn' } };
+}

package/dist/model.d.ts

@@ -0,0 +1,33 @@
+export declare const templates: readonly ["react-fastapi", "react-spring", "react-nest", "next-fullstack"];
+export declare const uis: readonly ["shadcn", "antd"];
+export type Spec = {
+    schemaVersion: 1;
+    nameZh: string;
+    nameEn: string;
+    description: string;
+    template: typeof templates[number];
+    ui: typeof uis[number];
+};
+export type Action = {
+    program: string;
+    args: string[];
+    cwd: string;
+    prerequisites: string[];
+    sideEffects: string[];
+};
+export type Issue = {
+    code: string;
+    message: string;
+    field?: string;
+    retryable: boolean;
+};
+export declare class ScaffoldError extends Error {
+    code: string;
+    exitCode: number;
+    field?: string | undefined;
+    constructor(code: string, message: string, exitCode?: number, field?: string | undefined);
+    issue(): Issue;
+}
+export declare function canonical(value: unknown): string;
+export declare function digest(value: string | Buffer): string;
+export declare const CLI_VERSION = "1.1.0";

package/dist/model.js

@@ -0,0 +1,24 @@
+import { createHash } from 'node:crypto';
+export const templates = ['react-fastapi', 'react-spring', 'react-nest', 'next-fullstack'];
+export const uis = ['shadcn', 'antd'];
+export class ScaffoldError extends Error {
+    code;
+    exitCode;
+    field;
+    constructor(code, message, exitCode = 2, field) {
+        super(message);
+        this.code = code;
+        this.exitCode = exitCode;
+        this.field = field;
+    }
+    issue() { return { code: this.code, message: this.message, ...(this.field ? { field: this.field } : {}), retryable: false }; }
+}
+export function canonical(value) {
+    if (Array.isArray(value))
+        return '[' + value.map(canonical).join(',') + ']';
+    if (value !== null && typeof value === 'object')
+        return '{' + Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => JSON.stringify(k) + ':' + canonical(v)).join(',') + '}';
+    return JSON.stringify(value);
+}
+export function digest(value) { return createHash('sha256').update(value).digest('hex'); }
+export const CLI_VERSION = '1.1.0';

package/dist/verify.d.ts

@@ -0,0 +1,67 @@
+import { type Diagnostic } from './diagnostics.js';
+type Check = {
+    id: string;
+    status: 'PASS' | 'FAIL' | 'NOT RUN' | 'N/A';
+    reason: string;
+    startedAt: string;
+    finishedAt: string;
+    exitCode: number | null;
+    signal: string | null;
+    evidence: string[];
+    diagnostic?: Diagnostic | null;
+};
+type Run = {
+    schemaVersion: 1;
+    runId: string;
+    template: string;
+    cliVersion: string;
+    platform: string;
+    runtime: string;
+    startedAt: string;
+    finishedAt: string;
+    beforeDigest: string;
+    afterDigest: string;
+    overallStatus: 'PASS' | 'FAIL' | 'NOT RUN';
+    validity: 'CURRENT' | 'STALE';
+    checks: Check[];
+    exitCode: number;
+    warnings: string[];
+};
+export declare function doctor(directory: string, options?: {
+    toolsOnly?: boolean;
+}): Promise<{
+    ok: boolean;
+    scope: string;
+    checks: {
+        program: string;
+        ok: boolean;
+        version: string | undefined;
+        remedy: string | null;
+    }[];
+    platform: string;
+    template: "react-fastapi" | "react-spring" | "react-nest" | "next-fullstack";
+}>;
+export declare function contentDigest(dir: string): Promise<string>;
+export declare function verify(directory: string): Promise<Run>;
+export declare function report(directory: string): Promise<{
+    overallStatus: string;
+    reason: string;
+} | {
+    validity: string;
+    schemaVersion: 1;
+    runId: string;
+    template: string;
+    cliVersion: string;
+    platform: string;
+    runtime: string;
+    startedAt: string;
+    finishedAt: string;
+    beforeDigest: string;
+    afterDigest: string;
+    overallStatus: "PASS" | "FAIL" | "NOT RUN";
+    checks: Check[];
+    exitCode: number;
+    warnings: string[];
+    reason?: undefined;
+}>;
+export {};