@yoyoboot/yoyo-admin-cli 10.5.5

package/dist/kernel/plan-runner.js

@@ -0,0 +1,176 @@
+/**
+ * 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 { existsSync, mkdirSync, readFileSync, rmSync, rmdirSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { assertConfinedRelativePath } from './fs-plan.js';
+import { YoyoAdminCliUsageError } from './result.js';
+/**
+ * 把 plan 相对路径收束成仓库内的绝对路径。
+ *
+ * 两层防御：静态字符串判定（`assertConfinedRelativePath`）+ 解析后的
+ * 真实包含关系校验（`resolve` 结果必须仍在 repoRoot 内）。
+ */
+export function confineRepoPath(repoRoot, relativePath) {
+    assertConfinedRelativePath(relativePath);
+    const root = resolve(repoRoot);
+    const absolute = resolve(root, relativePath);
+    const inside = relative(root, absolute);
+    if (inside.length === 0 || inside.startsWith('..') || isAbsolute(inside)) {
+        throw new YoyoAdminCliUsageError('unsafe-plan-path', `FsPlan 目标路径越出仓库根：${relativePath}。`);
+    }
+    return absolute;
+}
+/**
+ * 只读校验。
+ *
+ * 规则：
+ * - 全部路径先收束（非法路径 → `unsafe-plan-path`，零写入）；
+ * - `create` 目标必须**不存在**（存在即视为重复执行，禁止静默覆盖）；
+ *   父目录允许不存在 —— 新模块目录按定义就是新的，由 apply 阶段创建。
+ * - `update` 目标必须**存在且可读**（防止路径拼写错误被静默新建掩盖）。
+ */
+export function preflightFsPlan(repoRoot, plan) {
+    const confined = plan.changes.map(change => ({
+        change,
+        absolute: confineRepoPath(repoRoot, change.path),
+    }));
+    const targets = [];
+    for (const { change, absolute } of confined) {
+        if (change.kind === 'create' && existsSync(absolute)) {
+            throw new YoyoAdminCliUsageError('target-already-exists', `目标文件已存在，拒绝静默覆盖：${change.path}`);
+        }
+        if (change.kind === 'update' && !existsSync(absolute)) {
+            throw new YoyoAdminCliUsageError('update-target-missing', `待更新文件不存在：${change.path}`);
+        }
+        targets.push(change.kind === 'update'
+            ? { path: change.path, kind: change.kind, origin: change.origin, summary: change.summary }
+            : { path: change.path, kind: change.kind, origin: change.origin });
+    }
+    return { targets };
+}
+/** 创建父目录链，返回「本次新建」的目录（此前不存在），从浅到深排列。 */
+function ensureParentDirectories(absoluteFile) {
+    const missing = [];
+    let cursor = dirname(absoluteFile);
+    while (!existsSync(cursor)) {
+        missing.unshift(cursor);
+        const parent = dirname(cursor);
+        if (parent === cursor)
+            break;
+        cursor = parent;
+    }
+    for (const directory of missing) {
+        mkdirSync(directory, { recursive: false });
+    }
+    return missing;
+}
+/**
+ * 事务化落盘。
+ *
+ * 调用前建议先通过 `preflightFsPlan`；即使未调用，本函数自身也保持原子性——
+ * 全部路径先收束（非法路径在**任何写入之前**整体失败），任何一条 change 失败
+ * （含 update 目标缺失、路径非法等 I/O 错误）都会触发回滚：已 create 的文件被
+ * 删除、本 CLI 新建的目录被移除（仅当仍为空）、已 update 的文件恢复写入前的原内容。
+ */
+export function applyFsPlan(repoRoot, plan) {
+    return applyFsPlanTransaction(repoRoot, plan).written;
+}
+/**
+ * 事务化落盘并返回可撤销句柄。
+ *
+ * 用于 `create package` 这类「写文件 + 额外外部步骤（lockfile 刷新）」的闭环：
+ * 额外步骤失败时调用 `rollback()`，保证全有或全无。
+ */
+export function applyFsPlanTransaction(repoRoot, plan) {
+    // 先收束全部路径：非法目标在任何写入之前整体失败，天然零写入。
+    const confined = plan.changes.map(change => ({
+        change,
+        absolute: confineRepoPath(repoRoot, change.path),
+    }));
+    const applied = [];
+    try {
+        for (const { change, absolute } of confined) {
+            if (change.kind === 'create') {
+                if (existsSync(absolute)) {
+                    throw new YoyoAdminCliUsageError('target-already-exists', `目标文件已存在，拒绝静默覆盖：${change.path}`);
+                }
+                const createdDirectories = ensureParentDirectories(absolute);
+                writeFileSync(absolute, change.content, 'utf8');
+                applied.push({ change, absolute, priorContent: null, createdDirectories });
+                continue;
+            }
+            // update：先读原内容作为回滚凭据（目标缺失时此处抛错，天然安全）。
+            const priorContent = readFileSync(absolute, 'utf8');
+            writeFileSync(absolute, change.content, 'utf8');
+            applied.push({ change, absolute, priorContent, createdDirectories: [] });
+        }
+    }
+    catch (error) {
+        rollbackApplied(applied);
+        throw error;
+    }
+    return {
+        written: applied.map(entry => entry.change.path),
+        rollback: () => rollbackApplied(applied),
+    };
+}
+/** 逆序回滚全部已落盘影响；回滚自身的失败不掩盖原始错误。 */
+function rollbackApplied(applied) {
+    for (const entry of [...applied].reverse()) {
+        try {
+            if (entry.change.kind === 'create') {
+                if (existsSync(entry.absolute)) {
+                    rmSync(entry.absolute, { force: true });
+                }
+                for (const directory of [...entry.createdDirectories].reverse()) {
+                    try {
+                        rmdirSync(directory);
+                    }
+                    catch {
+                        // 目录非空（被并发写入）时保守保留，不影响工作树正确性。
+                    }
+                }
+                continue;
+            }
+            if (entry.priorContent !== null) {
+                writeFileSync(entry.absolute, entry.priorContent, 'utf8');
+            }
+        }
+        catch {
+            // 回滚失败不抛出：调用方拿到的仍是最初的真实错误。
+        }
+    }
+}
+export function readRepoFile(repoRoot, path) {
+    const absolute = confineRepoPath(repoRoot, path);
+    if (!existsSync(absolute)) {
+        throw new YoyoAdminCliUsageError('file-not-found', `文件不存在：${path}`);
+    }
+    return readFileSync(absolute, 'utf8');
+}
+/**
+ * 执行门面。
+ *
+ * 把「preflight → apply」封装成对象，确保调用方无法跳过校验直接写盘。
+ */
+export const planRunner = {
+    preflight: preflightFsPlan,
+    apply: applyFsPlan,
+    /** 返回可撤销句柄的 apply；额外外部步骤失败时用 `rollback()` 保证全有或全无。 */
+    applyTransaction: applyFsPlanTransaction,
+};

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

@@ -0,0 +1,25 @@
+export interface ProcessRequest {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+}
+export interface ProcessResult {
+    readonly status: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly error?: NodeJS.ErrnoException;
+}
+export type ProcessRunner = (request: ProcessRequest) => ProcessResult;
+export interface ProcessInvocation {
+    readonly command: string;
+    readonly args: readonly string[];
+}
+/**
+ * Node 24 on Windows does not launch `.cmd` shims through `spawnSync()` directly.
+ * Route pnpm through the platform command processor while preserving the original
+ * argument vector; other executables keep the normal shell-free path.
+ */
+export declare function createProcessInvocation(command: string, args: readonly string[], platform?: NodeJS.Platform, commandShell?: string | undefined): ProcessInvocation;
+/** Owner checks are captured, never streamed into the CLI result envelope. */
+export declare const runProcess: ProcessRunner;
+//# sourceMappingURL=process-runner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"process-runner.d.ts","sourceRoot":"","sources":["../../src/kernel/process-runner.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED,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,MAAM,CAAC,cAAc,CAAA;CACvC;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,cAAc,KAAK,aAAa,CAAA;AAEtE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CACjC;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,QAAQ,GAAE,MAAM,CAAC,QAA2B,EAC5C,YAAY,GAAE,MAAM,GAAG,SAA+B,GACrD,iBAAiB,CASnB;AAED,8EAA8E;AAC9E,eAAO,MAAM,UAAU,EAAE,aAYxB,CAAA"}

package/dist/kernel/process-runner.js

@@ -0,0 +1,29 @@
+import { spawnSync } from 'node:child_process';
+/**
+ * Node 24 on Windows does not launch `.cmd` shims through `spawnSync()` directly.
+ * Route pnpm through the platform command processor while preserving the original
+ * argument vector; other executables keep the normal shell-free path.
+ */
+export function createProcessInvocation(command, args, platform = process.platform, commandShell = process.env.ComSpec) {
+    if (platform !== 'win32' || !/^pnpm(?:\.cmd)?$/i.test(command)) {
+        return { command, args };
+    }
+    return {
+        command: commandShell?.trim() || 'cmd.exe',
+        args: ['/d', '/s', '/c', 'pnpm.cmd', ...args],
+    };
+}
+/** Owner checks are captured, never streamed into the CLI result envelope. */
+export const runProcess = ({ command, args, cwd }) => {
+    const invocation = createProcessInvocation(command, args);
+    const result = spawnSync(invocation.command, [...invocation.args], {
+        cwd, encoding: 'utf8', windowsHide: true,
+        timeout: 180_000, maxBuffer: 16 * 1024 * 1024,
+    });
+    return {
+        status: result.status,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+        ...(result.error === undefined ? {} : { error: result.error }),
+    };
+};

package/dist/kernel/render.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 结果渲染。
+ *
+ * 规则（需求第 8 条）：
+ * - **不记录「是否运行过 CLI」**，只输出本次真实观察到的结果。
+ * - `--json` 输出完整结果信封，Agent 直接解析。
+ * - 人类模式输出稳定、可 grep 的简洁行。
+ * - 有专用渲染器的载荷（FsPlan / inspect）不再重复 dump JSON。
+ */
+import { type FsPlan } from './fs-plan.js';
+import type { YoyoAdminCliCommandDescriptor, YoyoAdminCliResult } from './result.js';
+export declare function renderJson(value: unknown): string;
+export declare function renderResult(result: YoyoAdminCliResult, options?: {
+    readonly omitData?: boolean;
+}): string;
+export declare function renderFsPlan(plan: FsPlan, options: {
+    dryRun: boolean;
+}): string;
+export declare function renderCapabilities(commands: readonly YoyoAdminCliCommandDescriptor[]): string;
+//# sourceMappingURL=render.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/kernel/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAY,KAAK,MAAM,EAAE,MAAM,cAAc,CAAA;AACpD,OAAO,KAAK,EAAE,6BAA6B,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAQpF,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEjD;AAED,wBAAgB,YAAY,CAC1B,MAAM,EAAE,kBAAkB,EAC1B,OAAO,GAAE;IAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAO,GAC5C,MAAM,CAaR;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAkB/E;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,SAAS,6BAA6B,EAAE,GAAG,MAAM,CAiB7F"}

package/dist/kernel/render.js

@@ -0,0 +1,63 @@
+/**
+ * 结果渲染。
+ *
+ * 规则（需求第 8 条）：
+ * - **不记录「是否运行过 CLI」**，只输出本次真实观察到的结果。
+ * - `--json` 输出完整结果信封，Agent 直接解析。
+ * - 人类模式输出稳定、可 grep 的简洁行。
+ * - 有专用渲染器的载荷（FsPlan / inspect）不再重复 dump JSON。
+ */
+import { isFsPlan } from './fs-plan.js';
+const STATUS_MARK = {
+    ok: '[ok]',
+    warn: '[warn]',
+    error: '[error]',
+};
+export function renderJson(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+export function renderResult(result, options = {}) {
+    const lines = [`${STATUS_MARK[result.status] ?? '[?]'} ${result.command}`];
+    for (const item of result.findings) {
+        const detail = item.detail === undefined ? '' : `\n      ${item.detail}`;
+        lines.push(`  ${STATUS_MARK[item.status] ?? '[?]'} ${item.code}: ${item.message}${detail}`);
+    }
+    if (result.data !== undefined && options.omitData !== true && !isFsPlan(result.data)) {
+        lines.push('', JSON.stringify(result.data, null, 2));
+    }
+    return `${lines.join('\n')}\n`;
+}
+export function renderFsPlan(plan, options) {
+    const action = options.dryRun ? 'will create' : 'created';
+    const updateAction = options.dryRun ? 'will update' : 'updated';
+    const lines = [
+        options.dryRun ? 'dry-run: no files were written' : 'applied',
+        `  ${plan.summary.creates} create(s), ${plan.summary.updates} update(s)`,
+        '',
+    ];
+    for (const change of plan.changes) {
+        if (change.kind === 'create') {
+            lines.push(`  ${action}  ${change.path}   (${change.origin})`);
+        }
+        else {
+            lines.push(`  ${updateAction}  ${change.path}   (${change.origin}) — ${change.summary}`);
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}
+export function renderCapabilities(commands) {
+    const lines = ['yoyo-admin capabilities', ''];
+    for (const command of commands) {
+        lines.push(`  ${command.name}`);
+        lines.push(`      ${command.summary}`);
+        lines.push(`      usage: ${command.usage}`);
+        if (command.authoring) {
+            lines.push('      authoring: writes files; supports --dry-run');
+        }
+        if (command.capability !== undefined) {
+            lines.push(`      capability: ${command.capability}`);
+        }
+        lines.push('');
+    }
+    return `${lines.join('\n')}\n`;
+}

package/dist/kernel/result.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 统一结果信封。
+ *
+ * 所有命令都返回本结构，`--json` 只是把它序列化输出。
+ * 这样 CLI 的任何命令都天然机器可读，Agent 不需要为每个命令单独解析文本。
+ */
+export type YoyoAdminCliExitCode = 0 | 1 | 2;
+/** 命令执行结果的严重级别。`error` 一定伴随非零退出码。 */
+export type YoyoAdminCliStatus = 'ok' | 'warn' | 'error';
+/** 单条诊断/能力项。`code` 是稳定机器标识，`message` 面向人类。 */
+export interface YoyoAdminCliFinding {
+    readonly code: string;
+    readonly status: YoyoAdminCliStatus;
+    readonly message: string;
+    readonly detail?: string;
+}
+/** 命令声明的元数据，供 `capabilities` 与 help 复用。 */
+export interface YoyoAdminCliCommandDescriptor {
+    readonly name: string;
+    readonly summary: string;
+    readonly usage: string;
+    readonly arguments: readonly {
+        readonly name: string;
+        readonly required: boolean;
+        readonly description: string;
+    }[];
+    readonly options: readonly {
+        readonly flag: string;
+        readonly description: string;
+        readonly values?: readonly string[];
+        readonly default?: string;
+    }[];
+    /**
+     * 该命令额外声明的布尔 flag（除全局 `--json` / `--dry-run` / `--help` 外）。
+     * `options` 中的 flag 一律视为**取值选项**；两者不得重叠。
+     */
+    readonly booleanFlags?: readonly string[];
+    /** 该命令是否为作者操作（会写文件），`--dry-run` 只对这类命令有意义。 */
+    readonly authoring: boolean;
+    /** 该命令的成功执行能让哪些治理能力从其下移出。 */
+    readonly capability?: string;
+}
+export interface YoyoAdminCliResult {
+    readonly command: string;
+    readonly status: YoyoAdminCliStatus;
+    readonly findings: readonly YoyoAdminCliFinding[];
+    /** 命令特有的结构化产物，例如 capabilities 清单或 FsPlan。 */
+    readonly data?: unknown;
+}
+export declare function ok(command: string, findings?: readonly YoyoAdminCliFinding[], data?: unknown): YoyoAdminCliResult;
+export declare function warn(command: string, findings: readonly YoyoAdminCliFinding[], data?: unknown): YoyoAdminCliResult;
+export declare function failure(command: string, findings: readonly YoyoAdminCliFinding[], data?: unknown): YoyoAdminCliResult;
+export declare function finding(code: string, status: YoyoAdminCliStatus, message: string, detail?: string): YoyoAdminCliFinding;
+/** 结果中是否含有 error 级 finding —— 决定退出码。 */
+export declare function hasError(result: YoyoAdminCliResult): boolean;
+/**
+ * CLI 的预期失败。
+ *
+ * 抛出它表示「用户输入或仓库状态不允许执行」，不是程序缺陷。
+ * 入口会把它转成 error 级 finding + 退出码 2，不打印堆栈。
+ */
+export declare class YoyoAdminCliUsageError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+//# sourceMappingURL=result.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../src/kernel/result.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;AAE5C,qCAAqC;AACrC,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,MAAM,GAAG,OAAO,CAAA;AAExD,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAA;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,2CAA2C;AAC3C,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,SAAS,EAAE,SAAS;QAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;QAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;KAC7B,EAAE,CAAA;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS;QACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;QAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;QACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAC1B,EAAE,CAAA;IACH;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACzC,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,6BAA6B;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAA;IACnC,QAAQ,CAAC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAA;IACjD,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CACxB;AAED,wBAAgB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,GAAE,SAAS,mBAAmB,EAAO,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,kBAAkB,CAErH;AAED,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,mBAAmB,EAAE,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,kBAAkB,CAElH;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,mBAAmB,EAAE,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,kBAAkB,CAErH;AAED,wBAAgB,OAAO,CACrB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,GACd,mBAAmB,CAErB;AAED,wCAAwC;AACxC,wBAAgB,QAAQ,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAE5D;AAED;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;gBAET,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C"}

package/dist/kernel/result.js

@@ -0,0 +1,36 @@
+/**
+ * 统一结果信封。
+ *
+ * 所有命令都返回本结构，`--json` 只是把它序列化输出。
+ * 这样 CLI 的任何命令都天然机器可读，Agent 不需要为每个命令单独解析文本。
+ */
+export function ok(command, findings = [], data) {
+    return data === undefined ? { command, status: 'ok', findings } : { command, status: 'ok', findings, data };
+}
+export function warn(command, findings, data) {
+    return data === undefined ? { command, status: 'warn', findings } : { command, status: 'warn', findings, data };
+}
+export function failure(command, findings, data) {
+    return data === undefined ? { command, status: 'error', findings } : { command, status: 'error', findings, data };
+}
+export function finding(code, status, message, detail) {
+    return detail === undefined ? { code, status, message } : { code, status, message, detail };
+}
+/** 结果中是否含有 error 级 finding —— 决定退出码。 */
+export function hasError(result) {
+    return result.status === 'error' || result.findings.some(item => item.status === 'error');
+}
+/**
+ * CLI 的预期失败。
+ *
+ * 抛出它表示「用户输入或仓库状态不允许执行」，不是程序缺陷。
+ * 入口会把它转成 error 级 finding + 退出码 2，不打印堆栈。
+ */
+export class YoyoAdminCliUsageError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'YoyoAdminCliUsageError';
+        this.code = code;
+    }
+}

package/dist/kernel/workspace.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 仓库与工作区定位。
+ *
+ * CLI 依赖的稳定锚点（三者必须同时满足，缺一不可）：
+ * - 仓库根：含 `.git` 的祖先目录；
+ * - admin 工作区：`packages/yoyo-admin`；
+ * - 宿主：`apps/yoyo-admin/admin-vue`。
+ *
+ * 查找起点由调用方给出（`--repo <path>` → `runCli` 的 `startDirectory` →
+ * `process.cwd()`）。命中的祖先目录若只有 `.git` 而没有 Yoyo Admin 结构，
+ * 继续向上查找；一路到盘根都没有完整仓库则 fail-closed，不做兜底猜测。
+ */
+export interface YoyoAdminWorkspace {
+    readonly repoRoot: string;
+    readonly adminWorkspace: string;
+    readonly adminVueHost: string;
+    readonly packagesRoot: string;
+}
+export declare const ADMIN_WORKSPACE_RELATIVE = "packages/yoyo-admin";
+export declare const ADMIN_VUE_HOST_RELATIVE = "apps/yoyo-admin/admin-vue";
+export declare const APP_MANIFESTS_RELATIVE = "apps/yoyo-admin/admin-vue/src/app/manifests.ts";
+export declare const ADMIN_VUE_APP_ROOT_RELATIVE = "apps/yoyo-admin/admin-vue/src/app";
+/** 仓库根必须同时具备的标记（错误消息与测试共用同一事实源）。 */
+export declare const REQUIRED_REPO_MARKERS: readonly [".git", "packages/yoyo-admin", "apps/yoyo-admin/admin-vue"];
+/**
+ * 从起点向上查找同时满足 `.git` + `packages/yoyo-admin` +
+ * `apps/yoyo-admin/admin-vue` 的仓库根。
+ */
+export declare function findRepoRoot(startDirectory: string): string;
+export declare function resolveWorkspace(startDirectory?: string): YoyoAdminWorkspace;
+//# sourceMappingURL=workspace.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/kernel/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAC9B;AAED,eAAO,MAAM,wBAAwB,wBAAwB,CAAA;AAC7D,eAAO,MAAM,uBAAuB,8BAA8B,CAAA;AAClE,eAAO,MAAM,sBAAsB,mDAAmD,CAAA;AACtF,eAAO,MAAM,2BAA2B,sCAAsC,CAAA;AAE9E,oCAAoC;AACpC,eAAO,MAAM,qBAAqB,uEAIxB,CAAA;AAMV;;;GAGG;AACH,wBAAgB,YAAY,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAsC3D;AAED,wBAAgB,gBAAgB,CAAC,cAAc,GAAE,MAAsB,GAAG,kBAAkB,CAS3F"}

package/dist/kernel/workspace.js

@@ -0,0 +1,66 @@
+/**
+ * 仓库与工作区定位。
+ *
+ * CLI 依赖的稳定锚点（三者必须同时满足，缺一不可）：
+ * - 仓库根：含 `.git` 的祖先目录；
+ * - admin 工作区：`packages/yoyo-admin`；
+ * - 宿主：`apps/yoyo-admin/admin-vue`。
+ *
+ * 查找起点由调用方给出（`--repo <path>` → `runCli` 的 `startDirectory` →
+ * `process.cwd()`）。命中的祖先目录若只有 `.git` 而没有 Yoyo Admin 结构，
+ * 继续向上查找；一路到盘根都没有完整仓库则 fail-closed，不做兜底猜测。
+ */
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { YoyoAdminCliUsageError } from './result.js';
+export const ADMIN_WORKSPACE_RELATIVE = 'packages/yoyo-admin';
+export const ADMIN_VUE_HOST_RELATIVE = 'apps/yoyo-admin/admin-vue';
+export const APP_MANIFESTS_RELATIVE = 'apps/yoyo-admin/admin-vue/src/app/manifests.ts';
+export const ADMIN_VUE_APP_ROOT_RELATIVE = 'apps/yoyo-admin/admin-vue/src/app';
+/** 仓库根必须同时具备的标记（错误消息与测试共用同一事实源）。 */
+export const REQUIRED_REPO_MARKERS = [
+    '.git',
+    ADMIN_WORKSPACE_RELATIVE,
+    ADMIN_VUE_HOST_RELATIVE,
+];
+function hasCompleteLayout(candidate) {
+    return REQUIRED_REPO_MARKERS.every(marker => existsSync(join(candidate, marker)));
+}
+/**
+ * 从起点向上查找同时满足 `.git` + `packages/yoyo-admin` +
+ * `apps/yoyo-admin/admin-vue` 的仓库根。
+ */
+export function findRepoRoot(startDirectory) {
+    const start = resolve(startDirectory);
+    if (!existsSync(start)) {
+        throw new YoyoAdminCliUsageError('start-directory-missing', `查找起点不存在：${startDirectory}。`);
+    }
+    let current = start;
+    let gitRootWithoutLayout;
+    for (;;) {
+        if (existsSync(join(current, '.git'))) {
+            if (hasCompleteLayout(current))
+                return current;
+            gitRootWithoutLayout ??= current;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    if (gitRootWithoutLayout !== undefined) {
+        const missing = REQUIRED_REPO_MARKERS.filter(marker => marker !== '.git' && !existsSync(join(gitRootWithoutLayout, marker)));
+        throw new YoyoAdminCliUsageError('repo-layout-incomplete', `仓库根 ${gitRootWithoutLayout} 缺少 Yoyo Admin 结构：${missing.join('、')}。` +
+            `CLI 需要在 YoyoBoot 仓库内运行（${ADMIN_WORKSPACE_RELATIVE} 与 ${ADMIN_VUE_HOST_RELATIVE} 必须同时存在）。`);
+    }
+    throw new YoyoAdminCliUsageError('repo-root-not-found', `未能从 ${start} 向上找到含 .git 的仓库根目录；可用 --repo <path> 指定起点。`);
+}
+export function resolveWorkspace(startDirectory = process.cwd()) {
+    const repoRoot = findRepoRoot(startDirectory);
+    return {
+        repoRoot,
+        adminWorkspace: join(repoRoot, ADMIN_WORKSPACE_RELATIVE),
+        adminVueHost: join(repoRoot, ADMIN_VUE_HOST_RELATIVE),
+        packagesRoot: join(repoRoot, 'packages'),
+    };
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@yoyoboot/yoyo-admin-cli",
+  "version": "10.5.5",
+  "description": "Yoyo Admin 统一作者入口 CLI：环境诊断、能力发现与标准结构生成。",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "yoyo-admin": "./dist/bin.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yoyoboot/YoyoBoot.git",
+    "directory": "packages/yoyo-admin/admin-cli"
+  },
+  "homepage": "https://github.com/yoyoboot/YoyoBoot#readme",
+  "bugs": {
+    "url": "https://github.com/yoyoboot/YoyoBoot/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}