@inf-monkeys-tech/monkeys-cli 0.10.0

package/dist/data-transfer/types.d.ts

@@ -0,0 +1,80 @@
+export declare const ONTOLOGY_PACKAGE_KIND: 'monkeys.data.ontology';
+export declare const ONTOLOGY_PACKAGE_VERSION: 1;
+export declare const ASSET_RECORD_KIND: 'monkeys.data.asset';
+export declare const ASSET_RECORD_VERSION: 1;
+export type DataTransferFormat = 'csv' | 'jsonl' | 'xlsx';
+export interface OntologyPackageSource {
+    contextFingerprint: string;
+    exportedAt: string;
+    ontologyId: string;
+    perspective: 'kernel' | 'legacy' | 'studio';
+    resourceTeamId?: string | undefined;
+    teamId?: string | undefined;
+}
+export interface OntologyPackage {
+    fields: Array<Record<string, unknown>>;
+    formatVersion: typeof ONTOLOGY_PACKAGE_VERSION;
+    kind: typeof ONTOLOGY_PACKAGE_KIND;
+    ontology: Record<string, unknown>;
+    source: OntologyPackageSource;
+    tagGroups: Array<Record<string, unknown>>;
+    tags: Array<Record<string, unknown>>;
+    views: unknown[];
+}
+export interface AssetTransferRecord {
+    asset: Record<string, unknown>;
+    formatVersion: typeof ASSET_RECORD_VERSION;
+    kind: typeof ASSET_RECORD_KIND;
+    sourceId?: string | undefined;
+    tagSourceIds?: string[] | undefined;
+    values?: Record<string, unknown> | undefined;
+    viewSourceIds?: string[] | undefined;
+}
+export interface TransferFileResult {
+    bytes: number;
+    format: DataTransferFormat | 'json';
+    path: string;
+    records?: number;
+    sha256: string;
+}
+export interface TransferItemResult {
+    error?: {
+        code: string;
+        message: string;
+        requestState: 'not_sent' | 'sent' | 'unknown';
+    };
+    sourceId?: string;
+    status: 'created' | 'failed' | 'planned' | 'updated';
+    targetId?: string;
+    requestIds?: string[] | undefined;
+    resourceKind?: 'asset' | 'field' | 'ontology' | 'tag' | 'tagGroup' | 'view' | undefined;
+}
+export interface TransferReport {
+    completed: boolean;
+    dryRun: boolean;
+    input: {
+        bytes: number;
+        format: DataTransferFormat | 'json';
+        path: string;
+        records?: number;
+        sha256: string;
+    };
+    items: TransferItemResult[];
+    mode: 'append' | 'create' | 'merge';
+    summary: {
+        created: number;
+        failed: number;
+        planned: number;
+        total: number;
+        updated: number;
+    };
+    target: {
+        contextFingerprint: string;
+        ontologyId?: string | undefined;
+        ownerTeamId?: string | undefined;
+        perspective: 'kernel' | 'legacy' | 'studio';
+        resourceTeamId?: string | undefined;
+        teamId?: string | undefined;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/data-transfer/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/data-transfer/types.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB,EAAG,uBAAgC,CAAC;AACtE,eAAO,MAAM,wBAAwB,EAAG,CAAU,CAAC;AACnD,eAAO,MAAM,iBAAiB,EAAG,oBAA6B,CAAC;AAC/D,eAAO,MAAM,oBAAoB,EAAG,CAAU,CAAC;AAE/C,MAAM,MAAM,kBAAkB,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,CAAC;AAE1D,MAAM,WAAW,qBAAqB;IACpC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC5C,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACvC,aAAa,EAAE,OAAO,wBAAwB,CAAC;IAC/C,IAAI,EAAE,OAAO,qBAAqB,CAAC;IACnC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,MAAM,EAAE,qBAAqB,CAAC;IAC9B,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1C,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrC,KAAK,EAAE,OAAO,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,aAAa,EAAE,OAAO,oBAAoB,CAAC;IAC3C,IAAI,EAAE,OAAO,iBAAiB,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC7C,aAAa,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CACtC;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAAC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC;IACzF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAClC,YAAY,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,UAAU,GAAG,KAAK,GAAG,UAAU,GAAG,MAAM,GAAG,SAAS,CAAC;CACzF;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9G,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;IACpC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9F,MAAM,EAAE;QACN,kBAAkB,EAAE,MAAM,CAAC;QAC3B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAChC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACjC,WAAW,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;QAC5C,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACpC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KAC7B,CAAC;CACH"}

package/dist/data-transfer/types.js

@@ -0,0 +1,5 @@
+export const ONTOLOGY_PACKAGE_KIND = 'monkeys.data.ontology';
+export const ONTOLOGY_PACKAGE_VERSION = 1;
+export const ASSET_RECORD_KIND = 'monkeys.data.asset';
+export const ASSET_RECORD_VERSION = 1;
+//# sourceMappingURL=types.js.map

package/dist/data-transfer/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/data-transfer/types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAgC,CAAC;AACtE,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAU,CAAC;AACnD,MAAM,CAAC,MAAM,iBAAiB,GAAG,oBAA6B,CAAC;AAC/D,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAU,CAAC"}

package/dist/data-transfer/xlsx.d.ts

@@ -0,0 +1,3 @@
+import ExcelJS from 'exceljs';
+export declare function createBoundedWorkbookReader(path: string): Promise<ExcelJS.stream.xlsx.WorkbookReader>;
+//# sourceMappingURL=xlsx.d.ts.map

package/dist/data-transfer/xlsx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xlsx.d.ts","sourceRoot":"","sources":["../../src/data-transfer/xlsx.ts"],"names":[],"mappings":"AAEA,OAAO,OAAO,MAAM,SAAS,CAAC;AA0H9B,wBAAsB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CA6C3G"}

package/dist/data-transfer/xlsx.js

@@ -0,0 +1,146 @@
+import { createRequire } from 'node:module';
+import ExcelJS from 'exceljs';
+import { SaxesParser } from 'saxes';
+import { CliError, EXIT_CODES } from '../errors/cli-error.js';
+const MAX_XLSX_UNCOMPRESSED_BYTES = 128 * 1024 * 1024;
+const MAX_SHARED_STRINGS_BYTES = 64 * 1024 * 1024;
+const require = createRequire(import.meta.url);
+const unzipper = require('unzipper');
+function xlsxError(message, safeDetails) {
+    return new CliError(message, {
+        code: 'DATA_TRANSFER_XLSX_INVALID',
+        exitCode: EXIT_CODES.validation,
+        ...(safeDetails ? { safeDetails } : {}),
+    });
+}
+async function parseXml(entry, configure) {
+    const parser = new SaxesParser();
+    configure(parser);
+    parser.on('doctype', () => {
+        throw xlsxError('XLSX XML 不允许包含 DOCTYPE。');
+    });
+    for await (const chunk of entry.stream())
+        parser.write(Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk));
+    parser.close();
+}
+function attributes(tag) {
+    return tag.attributes;
+}
+async function readWorkbookSheets(entry) {
+    const sheets = [];
+    await parseXml(entry, (parser) => {
+        parser.on('opentag', (tag) => {
+            if (tag.name !== 'sheet')
+                return;
+            const value = attributes(tag);
+            const id = Number(value.sheetId);
+            if (!value.name || !value['r:id'] || !Number.isSafeInteger(id))
+                throw xlsxError('XLSX Workbook 的 Sheet 元数据无效。');
+            sheets.push({ id, name: value.name, rId: value['r:id'], state: value.state ?? 'visible' });
+        });
+    });
+    return sheets;
+}
+async function readWorkbookRelationships(entry) {
+    const relationships = [];
+    await parseXml(entry, (parser) => {
+        parser.on('opentag', (tag) => {
+            if (tag.name !== 'Relationship')
+                return;
+            const value = attributes(tag);
+            if (value.Id && value.Target && value.Type)
+                relationships.push({ Id: value.Id, Target: value.Target, Type: value.Type });
+        });
+    });
+    return relationships;
+}
+async function readSharedStrings(entry) {
+    if (!entry)
+        return [];
+    if ((entry.uncompressedSize ?? 0) > MAX_SHARED_STRINGS_BYTES) {
+        throw xlsxError('XLSX Shared Strings 超过安全上限；请改用默认 JSONL。', {
+            bytes: entry.uncompressedSize,
+            maxBytes: MAX_SHARED_STRINGS_BYTES,
+        });
+    }
+    const values = [];
+    let current = '';
+    let inItem = false;
+    let inText = false;
+    let phoneticDepth = 0;
+    await parseXml(entry, (parser) => {
+        parser.on('opentag', (tag) => {
+            if (tag.name === 'si') {
+                current = '';
+                inItem = true;
+            }
+            else if (tag.name === 'rPh') {
+                phoneticDepth += 1;
+            }
+            else if (tag.name === 't' && inItem && phoneticDepth === 0) {
+                inText = true;
+            }
+        });
+        parser.on('text', (text) => {
+            if (inText)
+                current += text;
+        });
+        parser.on('closetag', (tag) => {
+            if (tag.name === 't')
+                inText = false;
+            else if (tag.name === 'rPh')
+                phoneticDepth = Math.max(0, phoneticDepth - 1);
+            else if (tag.name === 'si') {
+                values.push(current);
+                current = '';
+                inItem = false;
+            }
+        });
+    });
+    return values;
+}
+export async function createBoundedWorkbookReader(path) {
+    let directory;
+    try {
+        directory = await unzipper.Open.file(path);
+    }
+    catch (cause) {
+        throw new CliError('无法读取 XLSX ZIP 目录。', {
+            cause,
+            code: 'DATA_TRANSFER_XLSX_INVALID',
+            exitCode: EXIT_CODES.validation,
+        });
+    }
+    const entries = new Map(directory.files.filter((entry) => entry.type !== 'Directory').map((entry) => [entry.path, entry]));
+    const uncompressedBytes = [...entries.values()].reduce((total, entry) => total + (entry.uncompressedSize ?? 0), 0);
+    if (uncompressedBytes > MAX_XLSX_UNCOMPRESSED_BYTES) {
+        throw xlsxError('XLSX 解压后超过安全上限；请改用默认 JSONL。', {
+            bytes: uncompressedBytes,
+            maxBytes: MAX_XLSX_UNCOMPRESSED_BYTES,
+        });
+    }
+    const workbookEntry = entries.get('xl/workbook.xml');
+    const relationshipsEntry = entries.get('xl/_rels/workbook.xml.rels');
+    if (!workbookEntry || !relationshipsEntry)
+        throw xlsxError('XLSX 缺少 Workbook 元数据。');
+    const [sheets, relationships, sharedStrings] = await Promise.all([
+        readWorkbookSheets(workbookEntry),
+        readWorkbookRelationships(relationshipsEntry),
+        readSharedStrings(entries.get('xl/sharedStrings.xml')),
+    ]);
+    if (!sheets.some((sheet) => sheet.name === 'data'))
+        throw xlsxError('XLSX 中没有 data 工作表。');
+    const reader = new ExcelJS.stream.xlsx.WorkbookReader(path, {
+        entries: 'ignore',
+        hyperlinks: 'ignore',
+        sharedStrings: 'ignore',
+        styles: 'ignore',
+        worksheets: 'emit',
+    });
+    const internal = reader;
+    internal.model = { sheets };
+    internal.sharedStrings = sharedStrings;
+    internal.workbookRels = relationships;
+    return reader;
+}
+//# sourceMappingURL=xlsx.js.map

package/dist/data-transfer/xlsx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xlsx.js","sourceRoot":"","sources":["../../src/data-transfer/xlsx.ts"],"names":[],"mappings":"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"}

package/dist/errors/cli-error.d.ts

@@ -0,0 +1,36 @@
+import type { ErrorDetail } from '../contracts/result.js';
+export declare const EXIT_CODES: {
+    readonly api: 6;
+    readonly authentication: 3;
+    readonly authorization: 4;
+    readonly compatibility: 8;
+    readonly configuration: 2;
+    readonly confirmation: 7;
+    readonly internal: 10;
+    readonly network: 5;
+    readonly partial: 9;
+    readonly success: 0;
+    readonly validation: 1;
+};
+export type ExitCode = (typeof EXIT_CODES)[keyof typeof EXIT_CODES];
+export interface CliErrorOptions {
+    cause?: unknown;
+    code: string;
+    exitCode: ExitCode;
+    fallbackEligible?: boolean;
+    recovery?: string[];
+    retryable?: boolean;
+    safeDetails?: unknown;
+}
+export declare class CliError extends Error {
+    readonly code: string;
+    readonly exitCode: ExitCode;
+    readonly fallbackEligible: boolean;
+    readonly recovery: string[] | undefined;
+    readonly retryable: boolean;
+    readonly safeDetails?: unknown;
+    constructor(message: string, options: CliErrorOptions);
+    toErrorDetail(): ErrorDetail;
+}
+export declare function asCliError(error: unknown): CliError;
+//# sourceMappingURL=cli-error.d.ts.map

package/dist/errors/cli-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-error.d.ts","sourceRoot":"","sources":["../../src/errors/cli-error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D,eAAO,MAAM,UAAU;aACrB,GAAG,EAAE,CAAC;aACN,cAAc,EAAE,CAAC;aACjB,aAAa,EAAE,CAAC;aAChB,aAAa,EAAE,CAAC;aAChB,aAAa,EAAE,CAAC;aAChB,YAAY,EAAE,CAAC;aACf,QAAQ,EAAE,EAAE;aACZ,OAAO,EAAE,CAAC;aACV,OAAO,EAAE,CAAC;aACV,OAAO,EAAE,CAAC;aACV,UAAU,EAAE,CAAC;CACL,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,CAAC;AAEpE,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;IACnB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAE/B,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EASpD;IAED,aAAa,IAAI,WAAW,CAS3B;CACF;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAGnD"}

package/dist/errors/cli-error.js

@@ -0,0 +1,47 @@
+export const EXIT_CODES = {
+    api: 6,
+    authentication: 3,
+    authorization: 4,
+    compatibility: 8,
+    configuration: 2,
+    confirmation: 7,
+    internal: 10,
+    network: 5,
+    partial: 9,
+    success: 0,
+    validation: 1,
+};
+export class CliError extends Error {
+    code;
+    exitCode;
+    fallbackEligible;
+    recovery;
+    retryable;
+    safeDetails;
+    constructor(message, options) {
+        super(message, { cause: options.cause });
+        this.name = 'CliError';
+        this.code = options.code;
+        this.exitCode = options.exitCode;
+        this.fallbackEligible = options.fallbackEligible ?? false;
+        this.recovery = options.recovery;
+        this.retryable = options.retryable ?? false;
+        this.safeDetails = options.safeDetails;
+    }
+    toErrorDetail() {
+        return {
+            code: this.code,
+            fallbackEligible: this.fallbackEligible,
+            message: this.message,
+            retryable: this.retryable,
+            ...(this.recovery === undefined ? {} : { recovery: this.recovery }),
+            ...(this.safeDetails === undefined ? {} : { safeDetails: this.safeDetails }),
+        };
+    }
+}
+export function asCliError(error) {
+    if (error instanceof CliError)
+        return error;
+    return new CliError('发生未预期的内部错误。', { cause: error, code: 'INTERNAL_ERROR', exitCode: EXIT_CODES.internal });
+}
+//# sourceMappingURL=cli-error.js.map

package/dist/errors/cli-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-error.js","sourceRoot":"","sources":["../../src/errors/cli-error.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,GAAG,EAAE,CAAC;IACN,cAAc,EAAE,CAAC;IACjB,aAAa,EAAE,CAAC;IAChB,aAAa,EAAE,CAAC;IAChB,aAAa,EAAE,CAAC;IAChB,YAAY,EAAE,CAAC;IACf,QAAQ,EAAE,EAAE;IACZ,OAAO,EAAE,CAAC;IACV,OAAO,EAAE,CAAC;IACV,OAAO,EAAE,CAAC;IACV,UAAU,EAAE,CAAC;CACL,CAAC;AAcX,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,IAAI,CAAS;IACb,QAAQ,CAAW;IACnB,gBAAgB,CAAU;IAC1B,QAAQ,CAAuB;IAC/B,SAAS,CAAU;IACnB,WAAW,CAAW;IAE/B,YAAY,OAAe,EAAE,OAAwB;QACnD,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,KAAK,CAAC;QAC1D,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC;QAC5C,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IACzC,CAAC;IAED,aAAa;QACX,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;YACvC,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnE,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;SAC7E,CAAC;IACJ,CAAC;CACF;AAED,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,IAAI,KAAK,YAAY,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,OAAO,IAAI,QAAQ,CAAC,aAAa,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,gBAAgB,EAAE,QAAQ,EAAE,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC;AAC9G,CAAC"}

package/dist/fallback/evidence.d.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import type { ResolvedContext } from '../context/resolver.js';
+import type { SecretStore } from '../credential/secret-store.js';
+import { CliError } from '../errors/cli-error.js';
+import type { RiskLevel } from '../policy/risk.js';
+export declare const fallbackEvidenceSchema: z.ZodObject<{
+    attemptId: z.ZodString;
+    commandId: z.ZodString;
+    contextFingerprint: z.ZodString;
+    createdAt: z.ZodString;
+    expiresAt: z.ZodString;
+    failureCode: z.ZodString;
+    requestState: z.ZodEnum<{
+        not_sent: "not_sent";
+        read_failed: "read_failed";
+        result_unknown: "result_unknown";
+        sent: "sent";
+    }>;
+    risk: z.ZodEnum<{
+        "bounded-write": "bounded-write";
+        credential: "credential";
+        destructive: "destructive";
+        privileged: "privileged";
+        read: "read";
+    }>;
+    v: z.ZodLiteral<2>;
+}, z.core.$strip>;
+export type FallbackEvidence = z.infer<typeof fallbackEvidenceSchema>;
+export declare function deriveFallbackKey(context: ResolvedContext, secrets: SecretStore): Promise<Uint8Array>;
+export declare function createFallbackEvidence(context: ResolvedContext, commandId: string, failureCode: string, requestState: FallbackEvidence['requestState'], risk: RiskLevel, attemptId?: string, now?: Date): FallbackEvidence;
+export declare function encodeFallbackEvidence(evidence: FallbackEvidence, key: Uint8Array): string;
+export declare function decodeFallbackEvidence(value: string, key: Uint8Array): FallbackEvidence;
+export declare function assertFallbackContext(evidence: FallbackEvidence, context: ResolvedContext, mutation: boolean, now?: number): void;
+export declare function consumeFallbackEvidence(encoded: string, evidence: FallbackEvidence, context: ResolvedContext, mutation: boolean, operation: string, directory?: string): Promise<void>;
+export declare function wrapFallbackEligibleError(error: CliError, context: ResolvedContext, commandId: string, requestState: FallbackEvidence['requestState'], risk: RiskLevel, key: Uint8Array, attemptId?: string): CliError;
+//# sourceMappingURL=evidence.d.ts.map

package/dist/fallback/evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../../src/fallback/evidence.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,QAAQ,EAAc,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAInD,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;iBAUjC,CAAC;AAGH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AActE,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAO3G;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,gBAAgB,CAAC,cAAc,CAAC,EAC9C,IAAI,EAAE,SAAS,EACf,SAAS,GAAE,MAAqB,EAChC,GAAG,GAAE,IAAiB,GACrB,gBAAgB,CAYlB;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,GAAG,EAAE,UAAU,GAAG,MAAM,CAE1F;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,gBAAgB,CAWvF;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,SAAa,GAAG,IAAI,CA6BrI;AAED,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE,OAAO,EACjB,SAAS,EAAE,MAAM,EACjB,SAAS,SAA0D,GAClE,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,gBAAgB,CAAC,cAAc,CAAC,EAC9C,IAAI,EAAE,SAAS,EACf,GAAG,EAAE,UAAU,EACf,SAAS,CAAC,EAAE,MAAM,GACjB,QAAQ,CAgBV"}

package/dist/fallback/evidence.js

@@ -0,0 +1,144 @@
+import { createHash, createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
+import { mkdir, open } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { z } from 'zod';
+import { resolveConfigPath } from '../config/paths.js';
+import { CliError, EXIT_CODES } from '../errors/cli-error.js';
+const EVIDENCE_TTL_MS = 10 * 60 * 1000;
+export const fallbackEvidenceSchema = z.object({
+    attemptId: z.string().uuid(),
+    commandId: z.string().min(1),
+    contextFingerprint: z.string().regex(/^[a-f0-9]{64}$/),
+    createdAt: z.string().datetime(),
+    expiresAt: z.string().datetime(),
+    failureCode: z.string().min(1),
+    requestState: z.enum(['not_sent', 'read_failed', 'sent', 'result_unknown']),
+    risk: z.enum(['read', 'bounded-write', 'credential', 'destructive', 'privileged']),
+    v: z.literal(2),
+});
+const signedEvidenceSchema = z.object({ payload: fallbackEvidenceSchema, signature: z.string().regex(/^[a-f0-9]{64}$/) });
+function invalidEvidence(cause) {
+    return new CliError('Fallback Evidence 无效或已被篡改。', {
+        ...(cause === undefined ? {} : { cause }),
+        code: 'FALLBACK_EVIDENCE_INVALID',
+        exitCode: EXIT_CODES.validation,
+    });
+}
+function signatureFor(evidence, key) {
+    return createHmac('sha256', key).update(JSON.stringify(evidence)).digest('hex');
+}
+export async function deriveFallbackKey(context, secrets) {
+    const secret = await secrets.get(context.credential.secretRef);
+    try {
+        return Uint8Array.from(createHmac('sha256', secret).update('monkeys-cli-fallback-evidence-v2').digest());
+    }
+    finally {
+        secret.fill(0);
+    }
+}
+export function createFallbackEvidence(context, commandId, failureCode, requestState, risk, attemptId = randomUUID(), now = new Date()) {
+    return {
+        attemptId,
+        commandId,
+        contextFingerprint: context.fingerprint,
+        createdAt: now.toISOString(),
+        expiresAt: new Date(now.getTime() + EVIDENCE_TTL_MS).toISOString(),
+        failureCode,
+        requestState,
+        risk,
+        v: 2,
+    };
+}
+export function encodeFallbackEvidence(evidence, key) {
+    return Buffer.from(JSON.stringify({ payload: evidence, signature: signatureFor(evidence, key) })).toString('base64url');
+}
+export function decodeFallbackEvidence(value, key) {
+    try {
+        const signed = signedEvidenceSchema.parse(JSON.parse(Buffer.from(value, 'base64url').toString('utf8')));
+        const actual = Buffer.from(signed.signature, 'hex');
+        const expected = Buffer.from(signatureFor(signed.payload, key), 'hex');
+        if (actual.length !== expected.length || !timingSafeEqual(actual, expected))
+            throw invalidEvidence();
+        return signed.payload;
+    }
+    catch (cause) {
+        if (cause instanceof CliError)
+            throw cause;
+        throw invalidEvidence(cause);
+    }
+}
+export function assertFallbackContext(evidence, context, mutation, now = Date.now()) {
+    if (evidence.contextFingerprint !== context.fingerprint) {
+        throw new CliError('Fallback Evidence 与当前 Profile/Tenant/Team/Credential Context 不一致。', {
+            code: 'FALLBACK_CONTEXT_MISMATCH',
+            exitCode: EXIT_CODES.authorization,
+            safeDetails: { actual: context.fingerprint, expected: evidence.contextFingerprint },
+        });
+    }
+    if (Date.parse(evidence.expiresAt) <= now) {
+        throw new CliError('Fallback Evidence 已过期，请重新执行语义命令确认当前状态。', {
+            code: 'FALLBACK_EVIDENCE_EXPIRED',
+            exitCode: EXIT_CODES.confirmation,
+            safeDetails: { attemptId: evidence.attemptId, expiresAt: evidence.expiresAt },
+        });
+    }
+    if (mutation && evidence.requestState !== 'not_sent') {
+        throw new CliError('原语义写操作可能已发送，禁止通过 Raw API 重放。', {
+            code: 'FALLBACK_MUTATION_REPLAY_BLOCKED',
+            exitCode: EXIT_CODES.confirmation,
+            safeDetails: { attemptId: evidence.attemptId, requestState: evidence.requestState },
+        });
+    }
+    if (mutation && !['bounded-write', 'destructive', 'privileged'].includes(evidence.risk)) {
+        throw new CliError('非写入语义命令的 Evidence 不能授权 Raw API 写操作。', {
+            code: 'FALLBACK_OPERATION_MISMATCH',
+            exitCode: EXIT_CODES.confirmation,
+            safeDetails: { attemptId: evidence.attemptId, commandId: evidence.commandId },
+        });
+    }
+}
+export async function consumeFallbackEvidence(encoded, evidence, context, mutation, operation, directory = join(dirname(resolveConfigPath()), 'fallback-consumed')) {
+    assertFallbackContext(evidence, context, mutation);
+    if (!mutation)
+        return;
+    await mkdir(directory, { mode: 0o700, recursive: true });
+    const digest = createHash('sha256').update(encoded).digest('hex');
+    const marker = join(directory, `${digest}.json`);
+    let handle;
+    try {
+        handle = await open(marker, 'wx', 0o600);
+        await handle.writeFile(JSON.stringify({ attemptId: evidence.attemptId, consumedAt: new Date().toISOString(), operation }), 'utf8');
+    }
+    catch (cause) {
+        if (cause.code === 'EEXIST') {
+            throw new CliError('Fallback Evidence 已用于一次写操作，禁止重复使用。', {
+                code: 'FALLBACK_EVIDENCE_REPLAYED',
+                exitCode: EXIT_CODES.confirmation,
+                safeDetails: { attemptId: evidence.attemptId },
+            });
+        }
+        throw cause;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+export function wrapFallbackEligibleError(error, context, commandId, requestState, risk, key, attemptId) {
+    if (!error.fallbackEligible)
+        return error;
+    const evidence = createFallbackEvidence(context, commandId, error.code, requestState, risk, attemptId);
+    return new CliError(error.message, {
+        cause: error,
+        code: error.code,
+        exitCode: error.exitCode,
+        fallbackEligible: true,
+        recovery: [...(error.recovery ?? []), '检查 OpenAPI 后，仅在同一 Context 中把 Fallback Evidence 传给 api call。'],
+        retryable: error.retryable,
+        safeDetails: {
+            ...(error.safeDetails && typeof error.safeDetails === 'object' ? error.safeDetails : {}),
+            fallbackEvidence: encodeFallbackEvidence(evidence, key),
+            semanticAttemptId: evidence.attemptId,
+        },
+    });
+}
+//# sourceMappingURL=evidence.js.map

package/dist/fallback/evidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.js","sourceRoot":"","sources":["../../src/fallback/evidence.ts"],"names":[],"mappings":"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"}

package/dist/fallback/index.d.ts

@@ -0,0 +1,2 @@
+export * from './evidence.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/fallback/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fallback/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC"}

package/dist/fallback/index.js

@@ -0,0 +1,2 @@
+export * from './evidence.js';
+//# sourceMappingURL=index.js.map

package/dist/fallback/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/fallback/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export * from './api-operation/index.js';
+export * from './api/index.js';
+export * from './client/index.js';
+export * from './data/index.js';
+export * from './contracts/index.js';
+export * from './config/index.js';
+export * from './context/index.js';
+export * from './credential/index.js';
+export * from './errors/cli-error.js';
+export * from './fallback/index.js';
+export * from './openapi/index.js';
+export * from './policy/risk.js';
+export * from './security/redact.js';
+export * from './semantic/index.js';
+export * from './system-config/contracts.js';
+export * from './system-config/client.js';
+export * from './transport/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+export * from './api-operation/index.js';
+export * from './api/index.js';
+export * from './client/index.js';
+export * from './data/index.js';
+export * from './contracts/index.js';
+export * from './config/index.js';
+export * from './context/index.js';
+export * from './credential/index.js';
+export * from './errors/cli-error.js';
+export * from './fallback/index.js';
+export * from './openapi/index.js';
+export * from './policy/risk.js';
+export * from './security/redact.js';
+export * from './semantic/index.js';
+export * from './system-config/contracts.js';
+export * from './system-config/client.js';
+export * from './transport/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC"}

package/dist/openapi/cache.d.ts

@@ -0,0 +1,8 @@
+import { type OpenApiSnapshot } from './types.js';
+export declare class OpenApiCache {
+    #private;
+    constructor(file: string);
+    read(): Promise<OpenApiSnapshot | undefined>;
+    write(snapshot: OpenApiSnapshot): Promise<void>;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/openapi/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/openapi/cache.ts"],"names":[],"mappings":"AAKA,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA8BzE,qBAAa,YAAY;;IAGvB,YAAY,IAAI,EAAE,MAAM,EAEvB;IAEK,IAAI,IAAI,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAuBjD;IAEK,KAAK,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAOpD;CACF"}