@inf-monkeys-tech/monkeys-cli 0.10.0

package/dist/openapi/cache.js

@@ -0,0 +1,75 @@
+import { mkdir, open, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { CliError, EXIT_CODES } from '../errors/cli-error.js';
+import { digestOpenApi, digestOpenApiLegacy } from './digest.js';
+import { indexOpenApi, OPENAPI_PARSER_VERSION } from './indexer.js';
+import { openApiSnapshotSchema } from './types.js';
+const LOCK_TIMEOUT_MS = 5_000;
+async function withLock(target, action) {
+    const lockPath = `${target}.lock`;
+    await mkdir(dirname(lockPath), { recursive: true });
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    let handle;
+    while (!handle) {
+        try {
+            handle = await open(lockPath, 'wx');
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const lockStat = await stat(lockPath).catch(() => undefined);
+            if (lockStat && Date.now() - lockStat.mtimeMs > LOCK_TIMEOUT_MS * 2)
+                await rm(lockPath, { force: true });
+            if (Date.now() >= deadline) {
+                throw new CliError('等待 OpenAPI 缓存锁超时。', { code: 'OPENAPI_CACHE_LOCK_TIMEOUT', exitCode: EXIT_CODES.configuration });
+            }
+            await new Promise((done) => setTimeout(done, 50));
+        }
+    }
+    try {
+        return await action();
+    }
+    finally {
+        await handle.close();
+        await rm(lockPath, { force: true });
+    }
+}
+export class OpenApiCache {
+    #file;
+    constructor(file) {
+        this.#file = resolve(file);
+    }
+    async read() {
+        try {
+            const snapshot = openApiSnapshotSchema.parse(JSON.parse(await readFile(this.#file, 'utf8')));
+            const currentDigest = digestOpenApi(snapshot.document);
+            const isCurrentDigest = currentDigest === snapshot.digest;
+            const isMigratableLegacyDigest = digestOpenApiLegacy(snapshot.document) === snapshot.digest;
+            if ((!isCurrentDigest && !isMigratableLegacyDigest) ||
+                (snapshot.index.parserVersion === OPENAPI_PARSER_VERSION &&
+                    digestOpenApi(indexOpenApi(snapshot.document)) !== digestOpenApi(snapshot.index))) {
+                throw new Error('snapshot digest or index mismatch');
+            }
+            return isCurrentDigest ? snapshot : { ...snapshot, digest: currentDigest };
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw new CliError('OpenAPI 缓存已损坏。', {
+                cause: error,
+                code: 'OPENAPI_CACHE_CORRUPT',
+                exitCode: EXIT_CODES.configuration,
+                safeDetails: { path: this.#file },
+            });
+        }
+    }
+    async write(snapshot) {
+        await withLock(this.#file, async () => {
+            await mkdir(dirname(this.#file), { recursive: true });
+            const temporary = `${this.#file}.${process.pid}.${Date.now()}.tmp`;
+            await writeFile(temporary, JSON.stringify(snapshot), { encoding: 'utf8', mode: 0o600 });
+            await rename(temporary, this.#file);
+        });
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/openapi/cache.js.map

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

package/dist/openapi/contract.d.ts

@@ -0,0 +1,3 @@
+import type { OpenApiDocument } from './types.js';
+export declare function assertOpenApiContractIdentity(document: OpenApiDocument, endpoint: string, etag?: string): void;
+//# sourceMappingURL=contract.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/openapi/contract.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAalD,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAwC9G"}

package/dist/openapi/contract.js

@@ -0,0 +1,52 @@
+import { CliError, EXIT_CODES } from '../errors/cli-error.js';
+import { digestOpenApi } from './digest.js';
+const SUPPORTED_CONTRACT_REVISIONS = new Set([1, 2, 3]);
+const SHA256_PATTERN = /^[a-f0-9]{64}$/;
+function compatibilityError(message, code, safeDetails) {
+    return new CliError(message, {
+        code,
+        exitCode: EXIT_CODES.compatibility,
+        ...(safeDetails ? { safeDetails } : {}),
+    });
+}
+export function assertOpenApiContractIdentity(document, endpoint, etag) {
+    const kind = document['x-monkeys-document-kind'];
+    const revision = document['x-monkeys-contract-revision'];
+    const declaredDigest = document['x-monkeys-schema-digest'];
+    const isMarkerlessLegacy = kind === undefined && revision === undefined && declaredDigest === undefined;
+    if (isMarkerlessLegacy)
+        return;
+    if (kind !== 'platform-api') {
+        throw compatibilityError('目标返回的 OpenAPI 不是 Monkeys Platform API 合同。', 'OPENAPI_DOCUMENT_KIND_UNSUPPORTED', {
+            endpoint,
+            kind,
+        });
+    }
+    if (revision === undefined || !SUPPORTED_CONTRACT_REVISIONS.has(revision)) {
+        throw compatibilityError('目标 Platform API 合同版本不受当前 CLI 支持。', 'OPENAPI_CONTRACT_REVISION_UNSUPPORTED', {
+            endpoint,
+            revision,
+            supported: [...SUPPORTED_CONTRACT_REVISIONS],
+        });
+    }
+    if (revision !== undefined && revision >= 2 && declaredDigest === undefined) {
+        throw compatibilityError(`Platform API revision ${revision} 缺少合同摘要。`, 'OPENAPI_SCHEMA_DIGEST_REQUIRED', {
+            endpoint,
+        });
+    }
+    if (declaredDigest !== undefined) {
+        if (!SHA256_PATTERN.test(declaredDigest) || digestOpenApi(document) !== declaredDigest) {
+            throw compatibilityError('Platform API 合同摘要校验失败。', 'OPENAPI_SCHEMA_DIGEST_MISMATCH', {
+                endpoint,
+                declaredDigest,
+            });
+        }
+        if (etag !== undefined && etag !== `"${declaredDigest}"`) {
+            throw compatibilityError('Platform API ETag 与合同摘要不一致。', 'OPENAPI_ETAG_DIGEST_MISMATCH', {
+                endpoint,
+                etag,
+            });
+        }
+    }
+}
+//# sourceMappingURL=contract.js.map

package/dist/openapi/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/openapi/contract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,MAAM,4BAA4B,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AACxD,MAAM,cAAc,GAAG,gBAAgB,CAAC;AAExC,SAAS,kBAAkB,CAAC,OAAe,EAAE,IAAY,EAAE,WAAqC;IAC9F,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE;QAC3B,IAAI;QACJ,QAAQ,EAAE,UAAU,CAAC,aAAa;QAClC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,6BAA6B,CAAC,QAAyB,EAAE,QAAgB,EAAE,IAAa;IACtG,MAAM,IAAI,GAAG,QAAQ,CAAC,yBAAyB,CAAC,CAAC;IACjD,MAAM,QAAQ,GAAG,QAAQ,CAAC,6BAA6B,CAAC,CAAC;IACzD,MAAM,cAAc,GAAG,QAAQ,CAAC,yBAAyB,CAAC,CAAC;IAC3D,MAAM,kBAAkB,GAAG,IAAI,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS,IAAI,cAAc,KAAK,SAAS,CAAC;IAExG,IAAI,kBAAkB;QAAE,OAAO;IAE/B,IAAI,IAAI,KAAK,cAAc,EAAE,CAAC;QAC5B,MAAM,kBAAkB,CAAC,2CAA2C,EAAE,mCAAmC,EAAE;YACzG,QAAQ;YACR,IAAI;SACL,CAAC,CAAC;IACL,CAAC;IACD,IAAI,QAAQ,KAAK,SAAS,IAAI,CAAC,4BAA4B,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1E,MAAM,kBAAkB,CAAC,kCAAkC,EAAE,uCAAuC,EAAE;YACpG,QAAQ;YACR,QAAQ;YACR,SAAS,EAAE,CAAC,GAAG,4BAA4B,CAAC;SAC7C,CAAC,CAAC;IACL,CAAC;IACD,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,IAAI,CAAC,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;QAC5E,MAAM,kBAAkB,CAAC,yBAAyB,QAAQ,UAAU,EAAE,gCAAgC,EAAE;YACtG,QAAQ;SACT,CAAC,CAAC;IACL,CAAC;IACD,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,aAAa,CAAC,QAAQ,CAAC,KAAK,cAAc,EAAE,CAAC;YACvF,MAAM,kBAAkB,CAAC,wBAAwB,EAAE,gCAAgC,EAAE;gBACnF,QAAQ;gBACR,cAAc;aACf,CAAC,CAAC;QACL,CAAC;QACD,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,cAAc,GAAG,EAAE,CAAC;YACzD,MAAM,kBAAkB,CAAC,6BAA6B,EAAE,8BAA8B,EAAE;gBACtF,QAAQ;gBACR,IAAI;aACL,CAAC,CAAC;QACL,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/openapi/digest.d.ts

@@ -0,0 +1,3 @@
+export declare function digestOpenApi(value: unknown): string;
+export declare function digestOpenApiLegacy(value: unknown): string;
+//# sourceMappingURL=digest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"digest.d.ts","sourceRoot":"","sources":["../../src/openapi/digest.ts"],"names":[],"mappings":"AAYA,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQpD;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAI1D"}

package/dist/openapi/digest.js

@@ -0,0 +1,24 @@
+import { createHash } from 'node:crypto';
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (value === null || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, child]) => [key, canonicalize(child)]));
+}
+export function digestOpenApi(value) {
+    const digestInput = value && typeof value === 'object' && !Array.isArray(value)
+        ? Object.fromEntries(Object.entries(value).filter(([key]) => key !== 'x-monkeys-schema-digest'))
+        : value;
+    return createHash('sha256')
+        .update(JSON.stringify(canonicalize(digestInput)))
+        .digest('hex');
+}
+export function digestOpenApiLegacy(value) {
+    return createHash('sha256')
+        .update(JSON.stringify(canonicalize(value)))
+        .digest('hex');
+}
+//# sourceMappingURL=digest.js.map

package/dist/openapi/digest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"digest.js","sourceRoot":"","sources":["../../src/openapi/digest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACzD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9D,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;SAClB,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;SACpD,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CACrD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,MAAM,WAAW,GACf,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACzD,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,yBAAyB,CAAC,CAAC;QAChG,CAAC,CAAC,KAAK,CAAC;IACZ,OAAO,UAAU,CAAC,QAAQ,CAAC;SACxB,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,CAAC;SACjD,MAAM,CAAC,KAAK,CAAC,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,OAAO,UAAU,CAAC,QAAQ,CAAC;SACxB,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;SAC3C,MAAM,CAAC,KAAK,CAAC,CAAC;AACnB,CAAC"}

package/dist/openapi/discovery.d.ts

@@ -0,0 +1,5 @@
+import type { HttpClient } from '../transport/http-client.js';
+import { OpenApiCache } from './cache.js';
+import { type OpenApiRefreshResult } from './types.js';
+export declare function refreshOpenApi(client: HttpClient, cache: OpenApiCache): Promise<OpenApiRefreshResult>;
+//# sourceMappingURL=discovery.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/openapi/discovery.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAK1C,OAAO,EAAqD,KAAK,oBAAoB,EAAwB,MAAM,YAAY,CAAC;AAyChI,wBAAsB,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA8E3G"}

package/dist/openapi/discovery.js

@@ -0,0 +1,127 @@
+import { CliError, EXIT_CODES } from '../errors/cli-error.js';
+import { digestOpenApi } from './digest.js';
+import { assertOpenApiContractIdentity } from './contract.js';
+import { indexOpenApi } from './indexer.js';
+import { OPENAPI_PARSER_VERSION } from './indexer.js';
+import { openApiDocumentSchema } from './types.js';
+const DISCOVERY_ENDPOINTS = ['/api/platform/openapi.json', '/api/agent/openapi.json'];
+const CONTRACT_ERROR_CODES = new Set([
+    'OPENAPI_CONTRACT_REVISION_UNSUPPORTED',
+    'OPENAPI_DOCUMENT_KIND_UNSUPPORTED',
+    'OPENAPI_ETAG_DIGEST_MISMATCH',
+    'OPENAPI_SCHEMA_DIGEST_MISMATCH',
+    'OPENAPI_SCHEMA_DIGEST_REQUIRED',
+]);
+function snapshotHeaders(headers) {
+    return {
+        ...(headers.etag ? { etag: headers.etag } : {}),
+        ...(headers['last-modified'] ? { lastModified: headers['last-modified'] } : {}),
+    };
+}
+function safeFailure(error, endpoint) {
+    if (!(error instanceof CliError))
+        return { code: 'OPENAPI_FETCH_FAILED', endpoint };
+    const details = error.safeDetails && typeof error.safeDetails === 'object' ? error.safeDetails : {};
+    const status = typeof details.status === 'number' ? details.status : undefined;
+    const code = status === 404
+        ? 'OPENAPI_ENDPOINT_NOT_FOUND'
+        : status === 405
+            ? 'OPENAPI_UPSTREAM_REJECTED'
+            : status !== undefined && status >= 500
+                ? 'OPENAPI_SERVER_ERROR'
+                : error.code === 'NETWORK_ERROR'
+                    ? 'OPENAPI_NETWORK_ERROR'
+                    : 'OPENAPI_FETCH_FAILED';
+    return {
+        code,
+        ...(typeof details.contentType === 'string' ? { contentType: details.contentType } : {}),
+        endpoint,
+        ...(typeof details.responseKind === 'string' ? { responseKind: details.responseKind } : {}),
+        ...(status === undefined ? {} : { status }),
+    };
+}
+export async function refreshOpenApi(client, cache) {
+    const previous = await cache.read();
+    let lastError;
+    let lastEndpoint = DISCOVERY_ENDPOINTS[0];
+    const attemptedEndpoints = [];
+    for (const endpoint of DISCOVERY_ENDPOINTS) {
+        lastEndpoint = endpoint;
+        attemptedEndpoints.push(endpoint);
+        try {
+            const response = await client.request({
+                acceptStatuses: [304],
+                headers: {
+                    ...(previous?.endpoint === endpoint && previous.etag ? { 'if-none-match': previous.etag } : {}),
+                    ...(previous?.endpoint === endpoint && previous.lastModified ? { 'if-modified-since': previous.lastModified } : {}),
+                },
+                maxResponseBytes: 20 * 1024 * 1024,
+                method: 'GET',
+                path: endpoint,
+            });
+            if (response.status === 304 && previous?.endpoint === endpoint) {
+                const snapshot = {
+                    ...previous,
+                    digest: digestOpenApi(previous.document),
+                    fetchedAt: new Date().toISOString(),
+                    index: previous.index.parserVersion === OPENAPI_PARSER_VERSION ? previous.index : indexOpenApi(previous.document),
+                    ...snapshotHeaders({
+                        ...(previous.etag ? { etag: previous.etag } : {}),
+                        ...(previous.lastModified ? { 'last-modified': previous.lastModified } : {}),
+                        ...response.headers,
+                    }),
+                };
+                assertOpenApiContractIdentity(snapshot.document, endpoint, snapshot.etag);
+                await cache.write(snapshot);
+                return { snapshot, state: 'not_modified' };
+            }
+            const document = openApiDocumentSchema.parse(response.data);
+            assertOpenApiContractIdentity(document, endpoint, response.headers.etag);
+            const digest = digestOpenApi(document);
+            if (previous?.digest === digest) {
+                const snapshot = {
+                    ...previous,
+                    document,
+                    endpoint,
+                    fetchedAt: new Date().toISOString(),
+                    index: previous.index.parserVersion === OPENAPI_PARSER_VERSION ? previous.index : indexOpenApi(document),
+                    ...snapshotHeaders(response.headers),
+                };
+                await cache.write(snapshot);
+                return { snapshot, state: 'not_modified' };
+            }
+            const snapshot = {
+                digest,
+                document,
+                endpoint,
+                fetchedAt: new Date().toISOString(),
+                index: indexOpenApi(document),
+                ...snapshotHeaders(response.headers),
+            };
+            await cache.write(snapshot);
+            return { snapshot, state: previous ? 'updated' : 'initial' };
+        }
+        catch (error) {
+            lastError = error;
+            if (error instanceof CliError && error.code === 'HTTP_404')
+                continue;
+            if (error instanceof CliError && CONTRACT_ERROR_CODES.has(error.code))
+                throw error;
+            if (error instanceof CliError && (error.code === 'HTTP_401' || error.code === 'HTTP_403'))
+                throw error;
+            break;
+        }
+    }
+    const failure = safeFailure(lastError, lastEndpoint);
+    if (previous)
+        return { failure, snapshot: previous, state: 'stale_kept' };
+    throw new CliError('无法获取目标部署的 OpenAPI。', {
+        cause: lastError,
+        code: 'OPENAPI_UNAVAILABLE',
+        exitCode: EXIT_CODES.compatibility,
+        recovery: ['确认 Deployment Base URL 可访问。', '确认目标部署公开 /api/platform/openapi.json，或 legacy /api/agent/openapi.json。'],
+        retryable: failure.code !== 'OPENAPI_ENDPOINT_NOT_FOUND',
+        safeDetails: { ...failure, attemptedEndpoints },
+    });
+}
+//# sourceMappingURL=discovery.js.map

package/dist/openapi/discovery.js.map

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

package/dist/openapi/index.d.ts

@@ -0,0 +1,7 @@
+export * from './cache.js';
+export * from './digest.js';
+export * from './discovery.js';
+export * from './indexer.js';
+export * from './loader.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/openapi/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/openapi/index.js

@@ -0,0 +1,7 @@
+export * from './cache.js';
+export * from './digest.js';
+export * from './discovery.js';
+export * from './indexer.js';
+export * from './loader.js';
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/openapi/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/openapi/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/openapi/indexer.d.ts

@@ -0,0 +1,4 @@
+import { type OpenApiDocument, type OpenApiIndex } from './types.js';
+export declare const OPENAPI_PARSER_VERSION = 3;
+export declare function indexOpenApi(document: OpenApiDocument): OpenApiIndex;
+//# sourceMappingURL=indexer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"indexer.d.ts","sourceRoot":"","sources":["../../src/openapi/indexer.ts"],"names":[],"mappings":"AACA,OAAO,EAA0B,KAAK,eAAe,EAAE,KAAK,YAAY,EAAyB,MAAM,YAAY,CAAC;AAEpH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAqBxC,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,YAAY,CAwEpE"}

package/dist/openapi/indexer.js

@@ -0,0 +1,97 @@
+import { CliError, EXIT_CODES } from '../errors/cli-error.js';
+import { openApiOperationSchema } from './types.js';
+export const OPENAPI_PARSER_VERSION = 3;
+const METHODS = ['delete', 'get', 'head', 'options', 'patch', 'post', 'put'];
+function assertNoExternalRefs(value) {
+    if (Array.isArray(value)) {
+        value.forEach(assertNoExternalRefs);
+        return;
+    }
+    if (value === null || typeof value !== 'object')
+        return;
+    for (const [key, child] of Object.entries(value)) {
+        if (key === '$ref' && typeof child === 'string' && !child.startsWith('#/')) {
+            throw new CliError('OpenAPI 包含未允许的外部 $ref。', {
+                code: 'OPENAPI_EXTERNAL_REF',
+                exitCode: EXIT_CODES.compatibility,
+                safeDetails: { ref: child },
+            });
+        }
+        assertNoExternalRefs(child);
+    }
+}
+export function indexOpenApi(document) {
+    assertNoExternalRefs(document);
+    const operations = [];
+    const byMethodPath = {};
+    const byOperationId = {};
+    for (const [pathTemplate, pathItem] of Object.entries(document.paths)) {
+        if (!pathItem || typeof pathItem !== 'object')
+            continue;
+        for (const method of METHODS) {
+            const raw = pathItem[method];
+            if (!raw || typeof raw !== 'object')
+                continue;
+            const record = raw;
+            const operation = {
+                method: method.toUpperCase(),
+                ...(Array.isArray(record['x-monkeys-auth-surfaces']) ? { authSurfaces: record['x-monkeys-auth-surfaces'] } : {}),
+                ...(typeof record.deprecated === 'boolean' ? { deprecated: record.deprecated } : {}),
+                ...(typeof record['x-monkeys-idempotency'] === 'string' ? { idempotency: record['x-monkeys-idempotency'] } : {}),
+                ...(typeof record['x-monkeys-long-running'] === 'boolean' ? { longRunning: record['x-monkeys-long-running'] } : {}),
+                ...(pathItem.parameters === undefined && record.parameters === undefined
+                    ? {}
+                    : {
+                        parameters: [
+                            ...(Array.isArray(pathItem.parameters)
+                                ? pathItem.parameters
+                                : []),
+                            ...(Array.isArray(record.parameters) ? record.parameters : []),
+                        ],
+                    }),
+                pathTemplate,
+                ...(typeof record['x-monkeys-published'] === 'boolean' ? { published: record['x-monkeys-published'] } : {}),
+                ...(record['x-monkeys-request-body-mode'] === 'none' ? { requestBodyMode: 'none' } : {}),
+                tags: Array.isArray(record.tags) ? record.tags.filter((tag) => typeof tag === 'string') : [],
+                ...(typeof record.operationId === 'string' ? { operationId: record.operationId } : {}),
+                ...(record.requestBody === undefined ? {} : { requestBody: record.requestBody }),
+                ...(record.responses === undefined ? {} : { responses: record.responses }),
+                ...(Array.isArray(record['x-monkeys-required-permissions'])
+                    ? { requiredPermissions: record['x-monkeys-required-permissions'] }
+                    : {}),
+                ...(typeof record['x-monkeys-resource-policy-enforced'] === 'boolean'
+                    ? { resourcePolicyEnforced: record['x-monkeys-resource-policy-enforced'] }
+                    : {}),
+                ...(typeof record['x-monkeys-risk'] === 'string' ? { risk: record['x-monkeys-risk'] } : {}),
+                ...(typeof record['x-monkeys-stability'] === 'string' ? { stability: record['x-monkeys-stability'] } : {}),
+                ...(typeof record.summary === 'string' ? { summary: record.summary } : {}),
+            };
+            const parsedOperation = openApiOperationSchema.safeParse(operation);
+            if (!parsedOperation.success) {
+                throw new CliError(`OpenAPI Operation 元数据无效：${operation.method} ${pathTemplate}`, {
+                    code: 'OPENAPI_INVALID_OPERATION_METADATA',
+                    exitCode: EXIT_CODES.compatibility,
+                    safeDetails: { issues: parsedOperation.error.issues.map((issue) => ({ message: issue.message, path: issue.path })) },
+                });
+            }
+            const validatedOperation = parsedOperation.data;
+            const key = `${validatedOperation.method} ${pathTemplate}`;
+            if (byMethodPath[key]) {
+                throw new CliError(`OpenAPI 中存在重复 Operation：${key}`, { code: 'OPENAPI_DUPLICATE_PATH', exitCode: EXIT_CODES.compatibility });
+            }
+            byMethodPath[key] = validatedOperation;
+            if (validatedOperation.operationId) {
+                if (byOperationId[validatedOperation.operationId]) {
+                    throw new CliError(`OpenAPI 中存在重复 operationId：${validatedOperation.operationId}`, {
+                        code: 'OPENAPI_DUPLICATE_OPERATION_ID',
+                        exitCode: EXIT_CODES.compatibility,
+                    });
+                }
+                byOperationId[validatedOperation.operationId] = validatedOperation;
+            }
+            operations.push(validatedOperation);
+        }
+    }
+    return { byMethodPath, byOperationId, operations, parserVersion: OPENAPI_PARSER_VERSION };
+}
+//# sourceMappingURL=indexer.js.map

package/dist/openapi/indexer.js.map

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

package/dist/openapi/loader.d.ts

@@ -0,0 +1,16 @@
+import type { ResolvedContext } from '../context/resolver.js';
+import type { HttpClient } from '../transport/http-client.js';
+import type { OpenApiRefreshFailure, OpenApiSnapshot, RefreshState } from './types.js';
+export interface LoadedOpenApi {
+    refreshFailure?: OpenApiRefreshFailure;
+    schemaFresh: boolean;
+    snapshot: OpenApiSnapshot;
+    state: 'cache_hit' | RefreshState;
+}
+export declare function openApiCachePath(context: ResolvedContext, configPath?: string): string;
+export declare function loadOpenApi(context: ResolvedContext, client: HttpClient, options?: {
+    forceRefresh?: boolean;
+    now?: number;
+    ttlMs?: number;
+}): Promise<LoadedOpenApi>;
+//# sourceMappingURL=loader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/openapi/loader.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAI9D,OAAO,KAAK,EAAE,qBAAqB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAIvF,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,EAAE,qBAAqB,CAAC;IACvC,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,eAAe,CAAC;IAC1B,KAAK,EAAE,WAAW,GAAG,YAAY,CAAC;CACnC;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,eAAe,EAAE,UAAU,SAAsB,GAAG,MAAM,CASnG;AAED,wBAAsB,WAAW,CAC/B,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GACrE,OAAO,CAAC,aAAa,CAAC,CAkBxB"}

package/dist/openapi/loader.js

@@ -0,0 +1,37 @@
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { configDirectory, resolveConfigPath } from '../config/paths.js';
+import { OpenApiCache } from './cache.js';
+import { refreshOpenApi } from './discovery.js';
+import { indexOpenApi, OPENAPI_PARSER_VERSION } from './indexer.js';
+const DEFAULT_TTL_MS = 60 * 60 * 1000;
+export function openApiCachePath(context, configPath = resolveConfigPath()) {
+    const isolationKey = JSON.stringify({
+        baseUrl: context.baseUrl,
+        deployment: context.deployment,
+        surfaces: context.expectedSurfaces,
+        tenant: context.tenant,
+    });
+    const digest = createHash('sha256').update(isolationKey).digest('hex');
+    return join(configDirectory(configPath), 'cache', 'openapi', `${digest}.json`);
+}
+export async function loadOpenApi(context, client, options = {}) {
+    const cache = new OpenApiCache(openApiCachePath(context));
+    let cached = await cache.read();
+    if (cached && cached.index.parserVersion !== OPENAPI_PARSER_VERSION) {
+        cached = { ...cached, index: indexOpenApi(cached.document) };
+        await cache.write(cached);
+    }
+    const age = cached ? (options.now ?? Date.now()) - Date.parse(cached.fetchedAt) : Number.POSITIVE_INFINITY;
+    if (!options.forceRefresh && cached && age <= (options.ttlMs ?? DEFAULT_TTL_MS)) {
+        return { schemaFresh: true, snapshot: cached, state: 'cache_hit' };
+    }
+    const refreshed = await refreshOpenApi(client, cache);
+    return {
+        ...(refreshed.failure ? { refreshFailure: refreshed.failure } : {}),
+        schemaFresh: refreshed.state !== 'stale_kept',
+        snapshot: refreshed.snapshot,
+        state: refreshed.state,
+    };
+}
+//# sourceMappingURL=loader.js.map

package/dist/openapi/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/openapi/loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAGxE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAGpE,MAAM,cAAc,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAStC,MAAM,UAAU,gBAAgB,CAAC,OAAwB,EAAE,UAAU,GAAG,iBAAiB,EAAE;IACzF,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,CAAC;QAClC,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,QAAQ,EAAE,OAAO,CAAC,gBAAgB;QAClC,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,MAAM,OAAO,CAAC,CAAC;AACjF,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAAwB,EACxB,MAAkB,EAClB,OAAO,GAA6D,EAAE;IAEtE,MAAM,KAAK,GAAG,IAAI,YAAY,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC;IAC1D,IAAI,MAAM,GAAG,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;IAChC,IAAI,MAAM,IAAI,MAAM,CAAC,KAAK,CAAC,aAAa,KAAK,sBAAsB,EAAE,CAAC;QACpE,MAAM,GAAG,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7D,MAAM,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,iBAAiB,CAAC;IAC3G,IAAI,CAAC,OAAO,CAAC,YAAY,IAAI,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,cAAc,CAAC,EAAE,CAAC;QAChF,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;IACrE,CAAC;IACD,MAAM,SAAS,GAAG,MAAM,cAAc,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACtD,OAAO;QACL,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnE,WAAW,EAAE,SAAS,CAAC,KAAK,KAAK,YAAY;QAC7C,QAAQ,EAAE,SAAS,CAAC,QAAQ;QAC5B,KAAK,EAAE,SAAS,CAAC,KAAK;KACvB,CAAC;AACJ,CAAC"}