@yoyoboot/yoyo-admin-cli 10.5.5

package/dist/kernel/help.js

@@ -0,0 +1,109 @@
+/**
+ * `--help` 渲染。
+ *
+ * 铁律：**help 从 registry 投影，不维护第二份命令清单**。
+ * 根 help 遍历 `registry.list()`；`create` 的 recipe help 遍历
+ * `create-registry`。新增命令/recipe 后 help 自动跟随，无需改本文件。
+ */
+export function helpPayload(text) {
+    return { kind: 'help', text };
+}
+export function isHelpPayload(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return candidate.kind === 'help' && typeof candidate.text === 'string';
+}
+/** 全局选项说明：与 `arguments.ts` 的全局 spec 一一对应，位置无关。 */
+export const GLOBAL_OPTION_LINES = [
+    '  --json          以 JSON 输出完整结果信封，供机器读取。',
+    '  --dry-run       仅展示计划变更，不写入任何文件（仅作者命令）。',
+    '  --help          展示帮助；`yoyo-admin --help` / `yoyo-admin create package --help`。',
+    '  --repo <path>   显式指定仓库查找起点；缺省从当前工作目录向上查找。',
+];
+function formatOptions(options) {
+    const width = options.reduce((max, option) => Math.max(max, option.flag.length), 0);
+    return options.map((option) => {
+        const requirement = option.required ? '必填' : '可选';
+        const values = option.values === undefined ? '' : `（${option.values.join(' | ')}）`;
+        return `  ${option.flag.padEnd(width)}  ${requirement}  ${option.description}${values}`;
+    });
+}
+export function renderRootHelp(commands) {
+    const lines = [
+        'yoyo-admin — Yoyo Admin 标准结构统一作者入口',
+        '',
+        '用法',
+        '  yoyo-admin <command> [arguments] [options]',
+        '',
+        '命令',
+    ];
+    for (const command of commands) {
+        lines.push(`  ${command.name}`);
+        lines.push(`      ${command.summary}`);
+        lines.push(`      usage: ${command.usage}`);
+    }
+    lines.push('', '全局选项（位置无关）', ...GLOBAL_OPTION_LINES);
+    lines.push('', '机器可读能力清单', '  yoyo-admin capabilities --json', '', '查看单个命令：yoyo-admin <command> --help');
+    return `${lines.join('\n')}\n`;
+}
+export function renderCommandHelp(command) {
+    const lines = [
+        `yoyo-admin ${command.name} — ${command.summary}`,
+        '',
+        '用法',
+        `  ${command.usage}`,
+    ];
+    if (command.arguments.length > 0) {
+        lines.push('', '参数');
+        for (const argument of command.arguments) {
+            lines.push(`  ${argument.name}${argument.required ? '（必填）' : ''}  ${argument.description}`);
+        }
+    }
+    if (command.options.length > 0) {
+        lines.push('', '选项', ...formatOptions(command.options.map(option => ({ ...option, required: false }))));
+    }
+    if (command.booleanFlags?.length) {
+        lines.push('', '布尔选项（不接受取值）', ...command.booleanFlags.map(flag => `  ${flag}`));
+    }
+    lines.push('', '全局选项（位置无关）', ...GLOBAL_OPTION_LINES);
+    return `${lines.join('\n')}\n`;
+}
+/** `yoyo-admin create --help`：条目清单 + 各自的 usage。 */
+export function renderRecipeListHelp(items, surface) {
+    const lines = [
+        `yoyo-admin ${surface.command} — ${surface.title}`,
+        '',
+        '用法',
+        `  yoyo-admin ${surface.command} <${items.map(item => item.name).join('|')}> ${surface.usageSuffix}`,
+        '',
+        surface.itemLabel,
+    ];
+    for (const item of items) {
+        lines.push(`  ${item.name}`);
+        lines.push(`      ${item.summary}`);
+        lines.push(`      usage: ${item.usage}`);
+        if (item.kinds.length > 0) {
+            lines.push(`      kinds: ${item.kinds.join(' | ')}`);
+        }
+    }
+    lines.push('', surface.itemUsageHint, '', '全局选项（位置无关）', ...GLOBAL_OPTION_LINES);
+    return `${lines.join('\n')}\n`;
+}
+/** `yoyo-admin create <recipe> --help`：单条目的完整参数。 */
+export function renderRecipeHelp(item, surface) {
+    const lines = [
+        `yoyo-admin ${surface.command} ${item.name} — ${item.summary}`,
+        '',
+        '用法',
+        `  ${item.usage}`,
+    ];
+    if (item.kinds.length > 0) {
+        lines.push('', `kind: ${item.kinds.join(' | ')}`);
+    }
+    if (item.options.length > 0) {
+        lines.push('', '选项', ...formatOptions(item.options));
+    }
+    lines.push('', '全局选项（位置无关）', ...GLOBAL_OPTION_LINES);
+    return `${lines.join('\n')}\n`;
+}

package/dist/kernel/lockfile.d.ts

@@ -0,0 +1,73 @@
+/**
+ * workspace lockfile 闭环。
+ *
+ * **正式语义（冻结）**：
+ * ```text
+ * create package
+ *   → 产生包源码
+ *   → `pnpm install --lockfile-only` 刷新 workspace importer
+ *   → 成功 == 「仓库可提交状态成立」（源码 + lockfile 可复现）
+ * pnpm install --frozen-lockfile
+ *   → 建立/同步本机 node_modules（本机环境状态，不属于 CLI 的产物）
+ * ```
+ * 因此本模块**绝不**跑完整 install：不重建依赖树、不写 node_modules。
+ *
+ * 为什么必须有：`pnpm-workspace.yaml` 的 `'.'` + `'./*'` 会自动把新目录算作
+ * workspace 成员，但 `pnpm-lock.yaml` 的 `importers` 不会自己长出来。不刷新的话，
+ * 当前环境的 node_modules 里恰好有依赖时 `package:verify` 能过，而 clean checkout
+ * 上的 `pnpm install --frozen-lockfile` 会因为「manifest 有、lockfile 无」直接失败。
+ *
+ * 强 fail-closed：**不依赖 pnpm「通常会做对」**。刷新后必须证明目标 importer
+ * 真的出现在 `importers:` 段里 —— 「exit 0 且字节没变」只有在 importer 本来就在
+ * 时才合法；字节相同但 importer 缺失一律视为失败并还原 lockfile。
+ */
+export declare const LOCKFILE_RELATIVE = "pnpm-lock.yaml";
+/** pnpm 只读刷新的固定参数：`--lockfile-only` 之外不加任何隐式开关。 */
+export declare const LOCKFILE_REFRESH_ARGS: readonly ["install", "--lockfile-only"];
+export interface PnpmRunResult {
+    readonly status: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly error?: Error;
+}
+/** 可注入的 pnpm 执行器（默认 spawnSync；测试用它做故障注入）。 */
+export type PnpmRunner = (args: readonly string[], cwd: string) => PnpmRunResult;
+export interface LockfileRefreshOptions {
+    /**
+     * 必须出现在刷新后 `importers:` 段里的 workspace 目录名（例如 `admin-runtime`）。
+     * 必填：新增 package 的闭环不允许「只让 pnpm 跑完就算数」。
+     */
+    readonly expectedImporter: string;
+    readonly run?: PnpmRunner;
+}
+export interface LockfileRefreshOutcome {
+    /** 被刷新的 lockfile 绝对路径。 */
+    readonly lockfilePath: string;
+    /**
+     * lockfile 内容是否发生变化。
+     * `false` 的合法含义只有一个：目标 importer **本来就已经存在**（幂等刷新）。
+     */
+    readonly changed: boolean;
+}
+/**
+ * 判定 lockfile 的顶层 `importers:` 段里是否存在指定 importer。
+ *
+ * 手写扫描而非引入 YAML 依赖（本包零 runtime 依赖）：
+ *   - 只在顶层 `importers:` 行之后扫描；
+ *   - importer key 固定缩进 2 空格（其子键为 4+ 空格，天然不会误匹配）；
+ *   - key 允许 pnpm 的引号形式；
+ *   - 遇到回到第 0 列的下一段即停止。
+ */
+export declare function lockfileHasImporter(content: string, importer: string): boolean;
+/**
+ * 刷新 workspace lockfile 的 importers，并断言目标 importer 确实进入。
+ *
+ * 失败语义（fail-closed，全部还原 lockfile 字节后抛
+ * `YoyoAdminCliUsageError('lockfile-refresh-failed')`）：
+ *   - pnpm 不可执行 / 退出码非 0；
+ *   - pnpm 报成功但没有 lockfile；
+ *   - pnpm 报成功但 `importers:` 段里**仍然找不到** `expectedImporter`
+ *     （含「字节没变」这种最可疑的情形）。
+ */
+export declare function refreshWorkspaceLockfile(adminWorkspace: string, options: LockfileRefreshOptions): LockfileRefreshOutcome;
+//# sourceMappingURL=lockfile.d.ts.map

package/dist/kernel/lockfile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lockfile.d.ts","sourceRoot":"","sources":["../../src/kernel/lockfile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAQH,eAAO,MAAM,iBAAiB,mBAAmB,CAAA;AAEjD,mDAAmD;AACnD,eAAO,MAAM,qBAAqB,yCAA0C,CAAA;AAE5E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CACvB;AAED,6CAA6C;AAC7C,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,KAAK,aAAa,CAAA;AAEhF,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,GAAG,CAAC,EAAE,UAAU,CAAA;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC,0BAA0B;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AA0BD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAmB9E;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,sBAAsB,GAC9B,sBAAsB,CAsCxB"}

package/dist/kernel/lockfile.js

@@ -0,0 +1,117 @@
+/**
+ * workspace lockfile 闭环。
+ *
+ * **正式语义（冻结）**：
+ * ```text
+ * create package
+ *   → 产生包源码
+ *   → `pnpm install --lockfile-only` 刷新 workspace importer
+ *   → 成功 == 「仓库可提交状态成立」（源码 + lockfile 可复现）
+ * pnpm install --frozen-lockfile
+ *   → 建立/同步本机 node_modules（本机环境状态，不属于 CLI 的产物）
+ * ```
+ * 因此本模块**绝不**跑完整 install：不重建依赖树、不写 node_modules。
+ *
+ * 为什么必须有：`pnpm-workspace.yaml` 的 `'.'` + `'./*'` 会自动把新目录算作
+ * workspace 成员，但 `pnpm-lock.yaml` 的 `importers` 不会自己长出来。不刷新的话，
+ * 当前环境的 node_modules 里恰好有依赖时 `package:verify` 能过，而 clean checkout
+ * 上的 `pnpm install --frozen-lockfile` 会因为「manifest 有、lockfile 无」直接失败。
+ *
+ * 强 fail-closed：**不依赖 pnpm「通常会做对」**。刷新后必须证明目标 importer
+ * 真的出现在 `importers:` 段里 —— 「exit 0 且字节没变」只有在 importer 本来就在
+ * 时才合法；字节相同但 importer 缺失一律视为失败并还原 lockfile。
+ */
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { YoyoAdminCliUsageError } from './result.js';
+import { runProcess } from './process-runner.js';
+export const LOCKFILE_RELATIVE = 'pnpm-lock.yaml';
+/** pnpm 只读刷新的固定参数：`--lockfile-only` 之外不加任何隐式开关。 */
+export const LOCKFILE_REFRESH_ARGS = ['install', '--lockfile-only'];
+function defaultPnpmRunner(args, cwd) {
+    const probe = runProcess({ command: 'pnpm', args, cwd });
+    return {
+        status: probe.status,
+        stdout: String(probe.stdout ?? ''),
+        stderr: String(probe.stderr ?? ''),
+        ...(probe.error === undefined ? {} : { error: probe.error }),
+    };
+}
+function describeFailure(result) {
+    const raw = result.error?.message ?? (result.stderr.trim() || result.stdout.trim());
+    return raw.length === 0 ? '(pnpm 未输出任何诊断)' : raw.slice(-800);
+}
+/** 把 lockfile 还原成执行前的字节；原本不存在则删除。 */
+function restoreLockfile(lockfilePath, before) {
+    if (before === undefined) {
+        if (existsSync(lockfilePath))
+            rmSync(lockfilePath, { force: true });
+        return;
+    }
+    writeFileSync(lockfilePath, before, 'utf8');
+}
+/**
+ * 判定 lockfile 的顶层 `importers:` 段里是否存在指定 importer。
+ *
+ * 手写扫描而非引入 YAML 依赖（本包零 runtime 依赖）：
+ *   - 只在顶层 `importers:` 行之后扫描；
+ *   - importer key 固定缩进 2 空格（其子键为 4+ 空格，天然不会误匹配）；
+ *   - key 允许 pnpm 的引号形式；
+ *   - 遇到回到第 0 列的下一段即停止。
+ */
+export function lockfileHasImporter(content, importer) {
+    const lines = content.split(/\r?\n/);
+    const start = lines.findIndex(line => /^importers:\s*$/.test(line));
+    if (start < 0)
+        return false;
+    for (let index = start + 1; index < lines.length; index += 1) {
+        const line = lines[index] ?? '';
+        if (line.trim().length === 0 || line.trimStart().startsWith('#'))
+            continue;
+        // 回到顶层 key：importers 段结束。
+        if (!line.startsWith(' '))
+            break;
+        const match = /^ {2}(?:'([^']+)'|"([^"]+)"|([^:\s][^:]*?)):\s*$/.exec(line);
+        if (match === null)
+            continue;
+        const key = match[1] ?? match[2] ?? match[3];
+        if (key === importer)
+            return true;
+    }
+    return false;
+}
+/**
+ * 刷新 workspace lockfile 的 importers，并断言目标 importer 确实进入。
+ *
+ * 失败语义（fail-closed，全部还原 lockfile 字节后抛
+ * `YoyoAdminCliUsageError('lockfile-refresh-failed')`）：
+ *   - pnpm 不可执行 / 退出码非 0；
+ *   - pnpm 报成功但没有 lockfile；
+ *   - pnpm 报成功但 `importers:` 段里**仍然找不到** `expectedImporter`
+ *     （含「字节没变」这种最可疑的情形）。
+ */
+export function refreshWorkspaceLockfile(adminWorkspace, options) {
+    const run = options.run ?? defaultPnpmRunner;
+    const lockfilePath = join(adminWorkspace, LOCKFILE_RELATIVE);
+    const before = existsSync(lockfilePath) ? readFileSync(lockfilePath, 'utf8') : undefined;
+    const result = run(LOCKFILE_REFRESH_ARGS, adminWorkspace);
+    const succeeded = result.error === undefined && result.status === 0;
+    if (!succeeded) {
+        restoreLockfile(lockfilePath, before);
+        throw new YoyoAdminCliUsageError('lockfile-refresh-failed', `新增 workspace package 后刷新 ${LOCKFILE_RELATIVE} 失败；本次生成已回滚，工作树保持原状。` +
+            `请手工执行 \`pnpm --dir <packages/yoyo-admin> ${LOCKFILE_REFRESH_ARGS.join(' ')}\` 后重试。` +
+            `（${describeFailure(result)}）`);
+    }
+    if (!existsSync(lockfilePath)) {
+        restoreLockfile(lockfilePath, before);
+        throw new YoyoAdminCliUsageError('lockfile-refresh-failed', `pnpm install --lockfile-only 未生成 ${LOCKFILE_RELATIVE}；无法保证 workspace 安装闭环。`);
+    }
+    const after = readFileSync(lockfilePath, 'utf8');
+    if (!lockfileHasImporter(after, options.expectedImporter)) {
+        restoreLockfile(lockfilePath, before);
+        throw new YoyoAdminCliUsageError('lockfile-refresh-failed', `刷新后 ${LOCKFILE_RELATIVE} 的 importers 中仍找不到 ${options.expectedImporter}；` +
+            '拒绝把「pnpm 报了成功」当作安装闭环成立（本次生成已回滚）。' +
+            `请手工执行 \`pnpm --dir <packages/yoyo-admin> ${LOCKFILE_REFRESH_ARGS.join(' ')}\` 确认 importer 已写入。`);
+    }
+    return { lockfilePath, changed: before !== after };
+}

package/dist/kernel/manifests-wiring.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `app/manifests.ts` 接线。
+ *
+ * 这是「统一作者入口」的关键：CLI 必须把 import 与注册一并纳入同一个 FsPlan，
+ * 而不是留下「请人工复制这段代码」。
+ *
+ * 但同时必须 **fail-closed**：
+ * - 无法识别当前文件结构 → 零写入直接失败；
+ * - 已存在重复 moduleKey / import 标识 → 零写入直接失败。
+ *
+ * 实现方式是**按行**操作，而不是按字符偏移：行边界天然稳定，
+ * 不受插入/删除导致的偏移漂移影响。
+ */
+/** `manifests.ts` 的稳定锚点（全部以行号表达）。 */
+export interface ManifestsFileAnchors {
+    /** 最后一个 import 行的行号（0-based，含）。 */
+    readonly lastImportLine: number;
+    /** `appModuleManifests` 数组起始 `[` 所在行号（0-based）。 */
+    readonly arrayOpeningLine: number;
+    /** 数组闭合 `]` 所在行号（0-based）。 */
+    readonly arrayClosingLine: number;
+    /** 当前已注册的 manifest 标识符。 */
+    readonly registeredIdentifiers: readonly string[];
+    /** 数组中的原始 entry（保留 `...spread`，供单行结构重渲染）。 */
+    readonly registeredEntries: readonly string[];
+    /** formatter 可能保留的合法单行或多行布局。 */
+    readonly arrayLayout: 'inline' | 'multiline';
+    /** 单行布局中从行首到 `[`（含）的稳定前缀。 */
+    readonly inlinePrefix?: string;
+    /** 单行布局中从 `]`（含）到行尾的稳定后缀。 */
+    readonly inlineSuffix?: string;
+}
+export interface ManifestsWiringRequest {
+    readonly manifestExportName: string;
+    readonly importPath: string;
+}
+export declare function parseManifestsAnchors(source: string, collectionName?: string): ManifestsFileAnchors;
+export declare function assertWiringIsSafe(anchors: ManifestsFileAnchors, request: ManifestsWiringRequest, source: string): void;
+export declare function renderWiredManifests(source: string, anchors: ManifestsFileAnchors, request: ManifestsWiringRequest): string;
+export declare function buildManifestsWiring(options: {
+    readonly manifestExportName: string;
+    readonly importPath: string;
+}): ManifestsWiringRequest;
+//# sourceMappingURL=manifests-wiring.d.ts.map

package/dist/kernel/manifests-wiring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifests-wiring.d.ts","sourceRoot":"","sources":["../../src/kernel/manifests-wiring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,qCAAqC;AACrC,MAAM,WAAW,oBAAoB;IACnC,mCAAmC;IACnC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,mDAAmD;IACnD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,8BAA8B;IAC9B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,2BAA2B;IAC3B,QAAQ,CAAC,qBAAqB,EAAE,SAAS,MAAM,EAAE,CAAA;IACjD,6CAA6C;IAC7C,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAA;IAC7C,gCAAgC;IAChC,QAAQ,CAAC,WAAW,EAAE,QAAQ,GAAG,WAAW,CAAA;IAC5C,6BAA6B;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,6BAA6B;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC/B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAkDD,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,cAAc,SAAuB,GACpC,oBAAoB,CAkGtB;AAED,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,oBAAoB,EAC7B,OAAO,EAAE,sBAAsB,EAC/B,MAAM,EAAE,MAAM,GACb,IAAI,CAqBN;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,oBAAoB,EAC7B,OAAO,EAAE,sBAAsB,GAC9B,MAAM,CAiDR;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE;IAC5C,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B,GAAG,sBAAsB,CAKzB"}

package/dist/kernel/manifests-wiring.js

@@ -0,0 +1,165 @@
+/**
+ * `app/manifests.ts` 接线。
+ *
+ * 这是「统一作者入口」的关键：CLI 必须把 import 与注册一并纳入同一个 FsPlan，
+ * 而不是留下「请人工复制这段代码」。
+ *
+ * 但同时必须 **fail-closed**：
+ * - 无法识别当前文件结构 → 零写入直接失败；
+ * - 已存在重复 moduleKey / import 标识 → 零写入直接失败。
+ *
+ * 实现方式是**按行**操作，而不是按字符偏移：行边界天然稳定，
+ * 不受插入/删除导致的偏移漂移影响。
+ */
+import { YoyoAdminCliUsageError } from './result.js';
+const IMPORT_LINE_PATTERN = /^import\s+(?:type\s+)?\{[^}]*\}\s+from\s+'[^']*'\s*$/;
+const MANIFESTS_PRINT_WIDTH = 100;
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function parseRegisteredEntries(rawEntries, collectionName, layout) {
+    const entries = [];
+    const identifiers = [];
+    const meaningfulEntries = rawEntries.map((entry) => entry.trim()).filter(Boolean);
+    for (const [index, rawEntry] of meaningfulEntries.entries()) {
+        if (layout === 'multiline' && index < meaningfulEntries.length - 1 && !rawEntry.endsWith(',')) {
+            throw new YoyoAdminCliUsageError('manifests-structure-unrecognized', `${collectionName} 的多行数组项“${rawEntry}”缺少分隔逗号；拒绝写入。`);
+        }
+        const entry = rawEntry.trim().replace(/,$/, '').trim();
+        const match = /^(?:\.\.\.)?([A-Za-z_$][\w$]*)$/.exec(entry);
+        if (match === null) {
+            throw new YoyoAdminCliUsageError('manifests-structure-unrecognized', `${collectionName} 包含无法识别的数组项“${entry}”；只接受标识符或 spread 标识符，拒绝写入。`);
+        }
+        const identifier = match[1];
+        if (identifiers.includes(identifier)) {
+            throw new YoyoAdminCliUsageError('manifests-duplicate-registration', `${collectionName} 中重复注册 ${identifier}；拒绝写入。`);
+        }
+        entries.push(entry);
+        identifiers.push(identifier);
+    }
+    return { entries, identifiers };
+}
+export function parseManifestsAnchors(source, collectionName = 'appModuleManifests') {
+    const lines = source.split(/\r?\n/);
+    const collectionDeclaration = collectionName === 'appModuleManifests'
+        ? `${collectionName}\\s*:\\s*YoyoAdminModuleManifest\\[\\]`
+        : escapeRegExp(collectionName);
+    const arrayOpenLinePattern = new RegExp(`^(export\\s+const\\s+${collectionDeclaration}\\s*=\\s*\\[)\\s*$`);
+    const inlineArrayPattern = new RegExp(`^(export\\s+const\\s+${collectionDeclaration}\\s*=\\s*\\[)\\s*(.*?)\\s*(\\](?:\\s+as\\s+const)?\\s*)$`);
+    const collectionOwnerPattern = new RegExp(`^export\\s+const\\s+${escapeRegExp(collectionName)}(?:\\s|:)`);
+    const ownerLines = lines.flatMap((line, index) => collectionOwnerPattern.test(line) ? [index] : []);
+    if (ownerLines.length !== 1) {
+        throw new YoyoAdminCliUsageError('manifests-structure-unrecognized', ownerLines.length === 0
+            ? `无法在 app/manifests.ts 中定位 ${collectionName} 合法单行/多行数组声明；拒绝写入。`
+            : `app/manifests.ts 中存在多个 ${collectionName} 数组声明；拒绝写入。`);
+    }
+    const arrayOpeningLine = ownerLines[0];
+    const declarationLine = lines[arrayOpeningLine];
+    const inlineMatch = inlineArrayPattern.exec(declarationLine);
+    const isMultiline = arrayOpenLinePattern.test(declarationLine);
+    if (inlineMatch === null && !isMultiline) {
+        throw new YoyoAdminCliUsageError('manifests-structure-unrecognized', `${collectionName} 不是可识别的单行/多行数组声明；拒绝写入。`);
+    }
+    let arrayClosingLine = arrayOpeningLine;
+    let arrayLayout = 'inline';
+    let inlinePrefix;
+    let inlineSuffix;
+    let parsedEntries;
+    if (inlineMatch !== null) {
+        inlinePrefix = inlineMatch[1];
+        inlineSuffix = inlineMatch[3];
+        parsedEntries = parseRegisteredEntries((inlineMatch[2] ?? '').split(','), collectionName, 'inline');
+    }
+    else {
+        arrayLayout = 'multiline';
+        arrayClosingLine = -1;
+        for (let index = arrayOpeningLine + 1; index < lines.length; index += 1) {
+            if (/^\](?:\s+as\s+const)?$/.test(lines[index]?.trim() ?? '')) {
+                arrayClosingLine = index;
+                break;
+            }
+        }
+        if (arrayClosingLine < 0) {
+            throw new YoyoAdminCliUsageError('manifests-structure-unrecognized', `${collectionName} 数组未以行首 \`]\` 结束；拒绝写入。`);
+        }
+        parsedEntries = parseRegisteredEntries(lines.slice(arrayOpeningLine + 1, arrayClosingLine), collectionName, 'multiline');
+    }
+    // 最后一个 import 行必须位于数组之前。
+    let lastImportLine = -1;
+    for (let index = 0; index < arrayOpeningLine; index += 1) {
+        if (IMPORT_LINE_PATTERN.test(lines[index] ?? '')) {
+            lastImportLine = index;
+        }
+    }
+    if (lastImportLine < 0) {
+        throw new YoyoAdminCliUsageError('manifests-structure-unrecognized', '无法在 app/manifests.ts 中定位 import 区块；拒绝写入。');
+    }
+    return {
+        lastImportLine,
+        arrayOpeningLine,
+        arrayClosingLine,
+        registeredIdentifiers: parsedEntries.identifiers,
+        registeredEntries: parsedEntries.entries,
+        arrayLayout,
+        ...(inlinePrefix === undefined ? {} : { inlinePrefix }),
+        ...(inlineSuffix === undefined ? {} : { inlineSuffix }),
+    };
+}
+export function assertWiringIsSafe(anchors, request, source) {
+    if (anchors.registeredIdentifiers.includes(request.manifestExportName)) {
+        throw new YoyoAdminCliUsageError('manifests-duplicate-registration', `appModuleManifests 中已注册 ${request.manifestExportName}；拒绝重复写入。`);
+    }
+    if (source.includes(`from '${request.importPath}'`)) {
+        throw new YoyoAdminCliUsageError('manifests-duplicate-import-path', `app/manifests.ts 中已引用 ${request.importPath}；拒绝重复写入。`);
+    }
+    if (source.includes(request.manifestExportName)) {
+        throw new YoyoAdminCliUsageError('manifests-duplicate-identifier', `app/manifests.ts 中已出现标识符 ${request.manifestExportName}；拒绝重复写入。`);
+    }
+}
+export function renderWiredManifests(source, anchors, request) {
+    assertWiringIsSafe(anchors, request, source);
+    // 保持源文件的换行风格（CRLF 文件插入 LF 行会制造混合换行，触发 lint）。
+    const usesCrLf = source.includes('\r\n');
+    const lines = source.split(/\r?\n/);
+    const importLine = `import { ${request.manifestExportName} } from '${request.importPath}'`;
+    const registrationLine = `  ${request.manifestExportName},`;
+    const next = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? '';
+        if (index === anchors.lastImportLine) {
+            next.push(line);
+            next.push(importLine);
+            continue;
+        }
+        if (index === anchors.arrayOpeningLine && anchors.arrayLayout === 'inline') {
+            if (anchors.inlinePrefix === undefined || anchors.inlineSuffix === undefined) {
+                throw new YoyoAdminCliUsageError('manifests-structure-unrecognized', '单行 manifests 数组缺少可验证的声明边界；拒绝写入。');
+            }
+            const entries = [...anchors.registeredEntries, request.manifestExportName];
+            const inline = `${anchors.inlinePrefix}${entries.join(', ')}${anchors.inlineSuffix}`;
+            if (inline.length <= MANIFESTS_PRINT_WIDTH) {
+                next.push(inline);
+            }
+            else {
+                next.push(anchors.inlinePrefix);
+                next.push(...entries.map((entry) => `  ${entry},`));
+                next.push(anchors.inlineSuffix);
+            }
+            continue;
+        }
+        if (index === anchors.arrayClosingLine) {
+            // 在数组闭合行之前追加注册项。
+            next.push(registrationLine);
+            next.push(line);
+            continue;
+        }
+        next.push(line);
+    }
+    return next.join(usesCrLf ? '\r\n' : '\n');
+}
+export function buildManifestsWiring(options) {
+    return {
+        manifestExportName: options.manifestExportName,
+        importPath: options.importPath,
+    };
+}

package/dist/kernel/plan-runner.d.ts

@@ -0,0 +1,81 @@
+/**
+ * FsPlan 落盘执行器。
+ *
+ * 三段式：
+ *   1. **preflight** —— 只读校验全部 change，任何一条不满足就抛错，**零写入**。
+ *   2. **apply**     —— 事务化写盘：先快照、逐文件落盘；任一文件失败，
+ *      回滚本次已产生的全部文件系统影响（恢复 update 的原内容、删除
+ *      已 create 的文件与本 CLI 新建的目录），**工作树恢复原状**。
+ *   3. 报告实际写入路径。
+ *
+ * 「零部分写入」由 preflight（fail-closed）与 apply（transactional）共同保证：
+ * 即使在 preflight 与 apply 之间文件系统发生变化（竞态），apply 也不会留下半成品。
+ *
+ * 路径收束（confinement）是本层的第一道动作：**每条 change 的路径都要先通过
+ * `confineRepoPath`，全部通过后才允许任何写入**。preflight 与 apply 各自独立
+ * 执行这一层，因此写入边界不依赖 generator 自律。
+ */
+import { type FsChange, type FsPlan } from './fs-plan.js';
+export interface PlanPreflightReport {
+    readonly targets: readonly {
+        readonly path: string;
+        readonly kind: FsChange['kind'];
+        readonly origin: string;
+        readonly summary?: string;
+    }[];
+}
+/**
+ * 把 plan 相对路径收束成仓库内的绝对路径。
+ *
+ * 两层防御：静态字符串判定（`assertConfinedRelativePath`）+ 解析后的
+ * 真实包含关系校验（`resolve` 结果必须仍在 repoRoot 内）。
+ */
+export declare function confineRepoPath(repoRoot: string, relativePath: string): string;
+/**
+ * 只读校验。
+ *
+ * 规则：
+ * - 全部路径先收束（非法路径 → `unsafe-plan-path`，零写入）；
+ * - `create` 目标必须**不存在**（存在即视为重复执行，禁止静默覆盖）；
+ *   父目录允许不存在 —— 新模块目录按定义就是新的，由 apply 阶段创建。
+ * - `update` 目标必须**存在且可读**（防止路径拼写错误被静默新建掩盖）。
+ */
+export declare function preflightFsPlan(repoRoot: string, plan: FsPlan): PlanPreflightReport;
+/**
+ * 事务化落盘。
+ *
+ * 调用前建议先通过 `preflightFsPlan`；即使未调用，本函数自身也保持原子性——
+ * 全部路径先收束（非法路径在**任何写入之前**整体失败），任何一条 change 失败
+ * （含 update 目标缺失、路径非法等 I/O 错误）都会触发回滚：已 create 的文件被
+ * 删除、本 CLI 新建的目录被移除（仅当仍为空）、已 update 的文件恢复写入前的原内容。
+ */
+export declare function applyFsPlan(repoRoot: string, plan: FsPlan): readonly string[];
+/** 已提交的 plan：允许调用方在「apply 之后的额外步骤」失败时显式撤销。 */
+export interface AppliedFsPlan {
+    readonly written: readonly string[];
+    /**
+     * 逆序撤销本次落盘（删除 create 的文件与本 CLI 新建的目录、恢复 update 的原内容）。
+     * 幂等且不抛：撤销自身的失败不掩盖调用方真正关心的错误。
+     */
+    rollback(): void;
+}
+/**
+ * 事务化落盘并返回可撤销句柄。
+ *
+ * 用于 `create package` 这类「写文件 + 额外外部步骤（lockfile 刷新）」的闭环：
+ * 额外步骤失败时调用 `rollback()`，保证全有或全无。
+ */
+export declare function applyFsPlanTransaction(repoRoot: string, plan: FsPlan): AppliedFsPlan;
+export declare function readRepoFile(repoRoot: string, path: string): string;
+/**
+ * 执行门面。
+ *
+ * 把「preflight → apply」封装成对象，确保调用方无法跳过校验直接写盘。
+ */
+export declare const planRunner: {
+    readonly preflight: typeof preflightFsPlan;
+    readonly apply: typeof applyFsPlan;
+    /** 返回可撤销句柄的 apply；额外外部步骤失败时用 `rollback()` 保证全有或全无。 */
+    readonly applyTransaction: typeof applyFsPlanTransaction;
+};
+//# sourceMappingURL=plan-runner.d.ts.map

package/dist/kernel/plan-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-runner.d.ts","sourceRoot":"","sources":["../../src/kernel/plan-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,EAA8B,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,cAAc,CAAA;AAGrF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS;QACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;QAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;QACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAC1B,EAAE,CAAA;CACJ;AAYD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAe9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,mBAAmB,CA+BnF;AAoBD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAE7E;AAED,8CAA8C;AAC9C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC;;;OAGG;IACH,QAAQ,IAAI,IAAI,CAAA;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAsCpF;AA6BD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMnE;AAED;;;;GAIG;AACH,eAAO,MAAM,UAAU;;;IAGrB,sDAAsD;;CAE9C,CAAA"}