jamdesk 1.1.166 → 1.1.167

package/dist/__tests__/unit/dev-workspace-symlinks.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=dev-workspace-symlinks.test.d.ts.map

package/dist/__tests__/unit/dev-workspace-symlinks.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-workspace-symlinks.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/unit/dev-workspace-symlinks.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/unit/dev-workspace-symlinks.test.js

@@ -0,0 +1,112 @@
+/**
+ * @vitest-environment node
+ *
+ * Tests prepareProjectWorkspaceLinks — replaces the single
+ * <workspace>/projects/<name> -> <projectDir> symlink with per-entry
+ * symlinks that skip non-active language directories. This is what
+ * actually reduces Turbopack's filesystem scan from 403 MDX files to
+ * 135 on jamdesk-docs.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'fs-extra';
+import path from 'path';
+import { tmpdir } from 'os';
+import { prepareProjectWorkspaceLinks } from '../../commands/dev.js';
+import { output } from '../../lib/output.js';
+describe('prepareProjectWorkspaceLinks', () => {
+    let tmpRoot;
+    let projectDir;
+    let workspaceProjectDir;
+    beforeEach(() => {
+        tmpRoot = fs.mkdtempSync(path.join(tmpdir(), 'jam-ws-'));
+        projectDir = path.join(tmpRoot, 'project');
+        workspaceProjectDir = path.join(tmpRoot, 'ws', 'projects', 'project');
+        // Set up a project layout that mirrors a multi-language docs project:
+        //   project/
+        //     ai/intro.mdx       (en at root)
+        //     development/foo.mdx (en at root)
+        //     es/ai/intro.mdx    (spanish)
+        //     fr/ai/intro.mdx    (french)
+        //     docs.json
+        //     images/logo.png
+        fs.mkdirpSync(path.join(projectDir, 'ai'));
+        fs.writeFileSync(path.join(projectDir, 'ai', 'intro.mdx'), '# en');
+        fs.mkdirpSync(path.join(projectDir, 'development'));
+        fs.writeFileSync(path.join(projectDir, 'development', 'foo.mdx'), '# en');
+        fs.mkdirpSync(path.join(projectDir, 'es', 'ai'));
+        fs.writeFileSync(path.join(projectDir, 'es', 'ai', 'intro.mdx'), '# es');
+        fs.mkdirpSync(path.join(projectDir, 'fr', 'ai'));
+        fs.writeFileSync(path.join(projectDir, 'fr', 'ai', 'intro.mdx'), '# fr');
+        fs.writeFileSync(path.join(projectDir, 'docs.json'), '{}');
+        fs.mkdirpSync(path.join(projectDir, 'images'));
+        fs.writeFileSync(path.join(projectDir, 'images', 'logo.png'), '');
+    });
+    afterEach(() => {
+        fs.removeSync(tmpRoot);
+    });
+    it('symlinks every top-level entry when skip set is empty', async () => {
+        await prepareProjectWorkspaceLinks(projectDir, workspaceProjectDir, new Set());
+        expect(fs.existsSync(path.join(workspaceProjectDir, 'ai', 'intro.mdx'))).toBe(true);
+        expect(fs.existsSync(path.join(workspaceProjectDir, 'es', 'ai', 'intro.mdx'))).toBe(true);
+        expect(fs.existsSync(path.join(workspaceProjectDir, 'fr', 'ai', 'intro.mdx'))).toBe(true);
+    });
+    it('does not symlink docs.json (caller writes a filtered copy)', async () => {
+        // docs.json must not be symlinked — the caller writes a per-language
+        // filtered copy, and fs.writeFile through a symlink would clobber the
+        // user's source docs.json.
+        await prepareProjectWorkspaceLinks(projectDir, workspaceProjectDir, new Set());
+        expect(fs.existsSync(path.join(workspaceProjectDir, 'docs.json'))).toBe(false);
+    });
+    it('skips entries whose names are in the skip set', async () => {
+        await prepareProjectWorkspaceLinks(projectDir, workspaceProjectDir, new Set(['es', 'fr']));
+        expect(fs.existsSync(path.join(workspaceProjectDir, 'ai', 'intro.mdx'))).toBe(true);
+        expect(fs.existsSync(path.join(workspaceProjectDir, 'development', 'foo.mdx'))).toBe(true);
+        expect(fs.existsSync(path.join(workspaceProjectDir, 'images', 'logo.png'))).toBe(true);
+        // Skipped:
+        expect(fs.existsSync(path.join(workspaceProjectDir, 'es'))).toBe(false);
+        expect(fs.existsSync(path.join(workspaceProjectDir, 'fr'))).toBe(false);
+        // docs.json not symlinked — caller writes a filtered copy.
+        expect(fs.existsSync(path.join(workspaceProjectDir, 'docs.json'))).toBe(false);
+    });
+    it('rebuilds the workspace links from scratch on subsequent calls', async () => {
+        // First call: no skip
+        await prepareProjectWorkspaceLinks(projectDir, workspaceProjectDir, new Set());
+        expect(fs.existsSync(path.join(workspaceProjectDir, 'es'))).toBe(true);
+        // Second call: skip es
+        await prepareProjectWorkspaceLinks(projectDir, workspaceProjectDir, new Set(['es']));
+        expect(fs.existsSync(path.join(workspaceProjectDir, 'es'))).toBe(false);
+        expect(fs.existsSync(path.join(workspaceProjectDir, 'fr'))).toBe(true);
+        expect(fs.existsSync(path.join(workspaceProjectDir, 'ai', 'intro.mdx'))).toBe(true);
+    });
+    it('handles a pre-existing single symlink at workspaceProjectDir (legacy layout)', async () => {
+        // Pre-create the legacy single-symlink layout
+        fs.mkdirpSync(path.dirname(workspaceProjectDir));
+        fs.symlinkSync(projectDir, workspaceProjectDir, 'junction');
+        await prepareProjectWorkspaceLinks(projectDir, workspaceProjectDir, new Set(['es', 'fr']));
+        const lstat = fs.lstatSync(workspaceProjectDir);
+        expect(lstat.isDirectory()).toBe(true);
+        expect(fs.existsSync(path.join(workspaceProjectDir, 'ai', 'intro.mdx'))).toBe(true);
+        expect(fs.existsSync(path.join(workspaceProjectDir, 'es'))).toBe(false);
+    });
+    it('surfaces friendly error (not raw stack trace) when fs.rm throws ENOTEMPTY', async () => {
+        // Regression: before safeRemoveCache, fs.remove raised an unfriendly stack
+        // trace when Turbopack still held open files. Now safeRemoveCache detects
+        // the race and calls process.exit(1) with a human-readable message.
+        const rmSpy = vi.spyOn(fs, 'rm');
+        const exitSpy = vi.spyOn(process, 'exit').mockImplementation(((code) => {
+            throw new Error(`process.exit:${code}`);
+        }));
+        const errorSpy = vi.spyOn(output, 'error').mockImplementation(() => undefined);
+        const enotempty = Object.assign(new Error('ENOTEMPTY'), { code: 'ENOTEMPTY' });
+        // fs.rm will be called by safeRemoveCache; make it fail with ENOTEMPTY
+        // even after the internal maxRetries — simulate persistent race condition.
+        rmSpy.mockRejectedValue(enotempty);
+        await expect(prepareProjectWorkspaceLinks(projectDir, workspaceProjectDir, new Set())).rejects.toThrow('process.exit:1');
+        const msg = errorSpy.mock.calls[0]?.[0] ?? '';
+        expect(msg).toContain('Another `jamdesk dev` instance');
+        expect(msg).toContain('pkill -f');
+        expect(exitSpy).toHaveBeenCalledWith(1);
+        vi.restoreAllMocks();
+    });
+});
+//# sourceMappingURL=dev-workspace-symlinks.test.js.map

package/dist/__tests__/unit/dev-workspace-symlinks.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-workspace-symlinks.test.js","sourceRoot":"","sources":["../../../src/__tests__/unit/dev-workspace-symlinks.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/unit/language-filter.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=language-filter.test.d.ts.map

package/dist/__tests__/unit/language-filter.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"language-filter.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/unit/language-filter.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/unit/language-filter.test.js

@@ -0,0 +1,166 @@
+/**
+ * @vitest-environment node
+ *
+ * Tests for getActiveLanguageFilter — pure helper that decides which
+ * top-level language directories to skip when symlinking project content
+ * into the dev workspace. Multi-language sites' non-default languages
+ * inflate Turbopack's filesystem scan and balloon cold compile time
+ * (jamdesk-docs: 67s with 3 langs vs. 12.5s with 1 lang).
+ */
+import { describe, it, expect } from 'vitest';
+import { getActiveLanguageFilter, isPageInSkippedLanguage, filterConfigByActiveLanguage, } from '../../lib/language-filter.js';
+const config = (langs) => ({
+    navigation: { languages: langs.map(l => ({ language: l.language, default: l.default })) },
+});
+describe('getActiveLanguageFilter', () => {
+    it('returns null filter when project has no languages array', () => {
+        const result = getActiveLanguageFilter({ navigation: {} }, undefined, false);
+        expect(result).toEqual({ active: null, skip: new Set() });
+    });
+    it('returns null filter when project has only one language', () => {
+        const result = getActiveLanguageFilter(config([{ language: 'en', default: true }]), undefined, false);
+        expect(result).toEqual({ active: 'en', skip: new Set() });
+    });
+    it('skips non-default languages when active is the default', () => {
+        const result = getActiveLanguageFilter(config([
+            { language: 'en', default: true },
+            { language: 'es' },
+            { language: 'fr' },
+        ]), undefined, false);
+        expect(result.active).toBe('en');
+        expect(result.skip).toEqual(new Set(['es', 'fr']));
+    });
+    it('falls back to first language when none is marked default', () => {
+        const result = getActiveLanguageFilter(config([{ language: 'en' }, { language: 'es' }, { language: 'fr' }]), undefined, false);
+        expect(result.active).toBe('en');
+        expect(result.skip).toEqual(new Set(['es', 'fr']));
+    });
+    it('accepts --lang matching the default language (no-op equivalence)', () => {
+        const result = getActiveLanguageFilter(config([
+            { language: 'en', default: true },
+            { language: 'es' },
+        ]), 'en', false);
+        expect(result.active).toBe('en');
+        expect(result.skip).toEqual(new Set(['es']));
+    });
+    it('throws on --lang for a non-default language (initial release scope)', () => {
+        // Non-default-language layouts mix root-level default-lang content with
+        // <lang>/ subdirs for translations; correctly stripping the default
+        // content while keeping <lang>/ takes more work and is deferred to a
+        // follow-up. For now, surface the workaround clearly.
+        expect(() => getActiveLanguageFilter(config([
+            { language: 'en', default: true },
+            { language: 'es' },
+            { language: 'fr' },
+        ]), 'es', false)).toThrow(/--lang es: previewing non-default languages.*--all-langs/i);
+    });
+    it('returns empty skip set when --all-langs is set', () => {
+        const result = getActiveLanguageFilter(config([
+            { language: 'en', default: true },
+            { language: 'es' },
+        ]), undefined, true);
+        expect(result.active).toBe('en');
+        expect(result.skip).toEqual(new Set());
+    });
+    it('throws on --lang code that does not exist in docs.json', () => {
+        expect(() => getActiveLanguageFilter(config([{ language: 'en', default: true }, { language: 'es' }]), 'de', false)).toThrow(/--lang de.*not.*docs\.json.*Available: en, es/);
+    });
+    it('handles malformed languages array (entries missing language field) by ignoring them', () => {
+        const malformed = {
+            navigation: {
+                languages: [
+                    { language: 'en', default: true },
+                    { default: false }, // missing language: ignored
+                    { language: 'es' },
+                    { language: 42 }, // wrong type: ignored
+                ],
+            },
+        };
+        const result = getActiveLanguageFilter(malformed, undefined, false);
+        expect(result.active).toBe('en');
+        expect(result.skip).toEqual(new Set(['es']));
+    });
+    it('returns null active when no valid language entries exist', () => {
+        const result = getActiveLanguageFilter({ navigation: { languages: [{ default: true }] } }, undefined, false);
+        expect(result).toEqual({ active: null, skip: new Set() });
+    });
+    it('rejects empty-string --lang as an invalid code (commander passes "" through)', () => {
+        // commander.js treats `--lang ""` as a value, not as missing — so
+        // langOption is "" (defined, but empty). Empty string is never a valid
+        // language code; surface it as a clear error rather than silently
+        // falling back to the default.
+        expect(() => getActiveLanguageFilter(config([{ language: 'en', default: true }, { language: 'es' }]), '', false)).toThrow(/--lang.*not.*docs\.json/);
+    });
+});
+describe('isPageInSkippedLanguage', () => {
+    it('returns false when skip set is empty', () => {
+        expect(isPageInSkippedLanguage('fr/introduction', new Set())).toBe(false);
+    });
+    it('returns true when first path segment is a skipped language', () => {
+        expect(isPageInSkippedLanguage('fr/introduction', new Set(['fr']))).toBe(true);
+    });
+    it('returns true for nested paths inside a skipped language', () => {
+        expect(isPageInSkippedLanguage('fr/setup/connecting-github', new Set(['fr', 'de']))).toBe(true);
+    });
+    it('returns false when first segment is the active language', () => {
+        expect(isPageInSkippedLanguage('en/introduction', new Set(['fr']))).toBe(false);
+    });
+    it('returns false for unprefixed root pages', () => {
+        expect(isPageInSkippedLanguage('introduction', new Set(['fr']))).toBe(false);
+    });
+    it('does not match when the skip code is a prefix-substring of a different segment', () => {
+        // Guard against startsWith('fr/') matching e.g. 'fr-something/foo'
+        expect(isPageInSkippedLanguage('fr-something/foo', new Set(['fr']))).toBe(false);
+    });
+    it('returns true for a path with a fragment anchor in a skipped language', () => {
+        // Broken-anchor warnings from validate-links.cjs surface as link values
+        // like `fr/introduction#missing-section` — the fragment lives past the
+        // first segment so the language check still works.
+        expect(isPageInSkippedLanguage('fr/introduction#setup', new Set(['fr']))).toBe(true);
+    });
+});
+describe('filterConfigByActiveLanguage', () => {
+    it('returns the input unchanged (same reference) when skip is empty', () => {
+        const config = { name: 'foo', navigation: { languages: [{ language: 'en' }] } };
+        const result = filterConfigByActiveLanguage(config, { active: 'en', skip: new Set() });
+        expect(result).toBe(config);
+    });
+    it('drops skipped languages from navigation.languages', () => {
+        const config = {
+            name: 'jamdesk-docs',
+            navigation: {
+                languages: [
+                    { language: 'en', default: true, tabs: [{ tab: 'Guide' }] },
+                    { language: 'fr', tabs: [{ tab: 'Guide' }] },
+                    { language: 'de', tabs: [{ tab: 'Guide' }] },
+                ],
+            },
+        };
+        const result = filterConfigByActiveLanguage(config, {
+            active: 'en',
+            skip: new Set(['fr', 'de']),
+        });
+        expect(result.navigation.languages).toEqual([
+            { language: 'en', default: true, tabs: [{ tab: 'Guide' }] },
+        ]);
+        // Top-level fields preserved.
+        expect(result.name).toBe('jamdesk-docs');
+        // Original config untouched.
+        expect(config.navigation.languages).toHaveLength(3);
+    });
+    it('preserves other navigation fields (tabs, global, anchors, etc.)', () => {
+        const config = {
+            navigation: {
+                languages: [{ language: 'en' }, { language: 'fr' }],
+                global: { anchors: [{ anchor: 'Support' }] },
+            },
+        };
+        const result = filterConfigByActiveLanguage(config, {
+            active: 'en',
+            skip: new Set(['fr']),
+        });
+        expect(result.navigation.global).toEqual({ anchors: [{ anchor: 'Support' }] });
+        expect(result.navigation.languages).toHaveLength(1);
+    });
+});
+//# sourceMappingURL=language-filter.test.js.map

package/dist/__tests__/unit/language-filter.test.js.map

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

package/dist/__tests__/unit/openapi-license-identifier.test.js

@@ -10,12 +10,22 @@
  * valid — Mintlify accepts it, and `jamdesk migrate`'s auto-discovered
  * Mintlify starter spec uses exactly `{ "name": "MIT" }`.
  *
- * The patcher (scripts/patch-openapi-schemas.js) must have replaced the bad
- * oneOf with `not: { required: [identifier, url] }` by the time this runs.
- * Uses the REAL SwaggerParser so it exercises the bundled schema.
+ * The bad oneOf must be replaced with `not: { required: [identifier, url] }`
+ * by the time these specs are validated. Uses the REAL SwaggerParser so it
+ * exercises the bundled schema, and heals the in-memory singleton first
+ * because the on-disk postinstall patch (scripts/patch-openapi-schemas.js)
+ * CANNOT be assumed to have run: npm 12 blocks lifecycle scripts by default,
+ * so a fresh `npm ci` leaves node_modules unpatched. Relying on the
+ * postinstall made this test fail on correct code after any clean install —
+ * the same heal production code performs at the top of validateOpenApiSpec()
+ * is what it must exercise.
  */
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeAll } from 'vitest';
 import SwaggerParser from '@apidevtools/swagger-parser';
+import { patchOpenApiSchemasInMemory } from '../../lib/openapi/patch-openapi-schemas-runtime.js';
+beforeAll(() => {
+    patchOpenApiSchemasInMemory();
+});
 const base = (license) => ({
     openapi: '3.1.0',
     info: { title: 'License Regression', version: '1.0.0', license },

package/dist/__tests__/unit/openapi-license-identifier.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"openapi-license-identifier.test.js","sourceRoot":"","sources":["../../../src/__tests__/unit/openapi-license-identifier.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,aAAa,MAAM,6BAA6B,CAAC;AAExD,MAAM,IAAI,GAAG,CAAC,OAAgC,EAAE,EAAE,CAAC,CAAC;IAClD,OAAO,EAAE,OAAO;IAChB,IAAI,EAAE,EAAE,KAAK,EAAE,oBAAoB,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE;IAChE,KAAK,EAAE,EAAE;CACV,CAAC,CAAC;AAEH,QAAQ,CAAC,iDAAiD,EAAE,GAAG,EAAE;IAC/D,EAAE,CAAC,yDAAyD,EAAE,KAAK,IAAI,EAAE;QACvE,MAAM,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAU,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2BAA2B,EAAE,KAAK,IAAI,EAAE;QACzC,MAAM,aAAa,CAAC,QAAQ,CAC1B,IAAI,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,CAAU,CAChE,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oBAAoB,EAAE,KAAK,IAAI,EAAE;QAClC,MAAM,aAAa,CAAC,QAAQ,CAC1B,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,6BAA6B,EAAE,CAAU,CACtE,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oEAAoE,EAAE,KAAK,IAAI,EAAE;QAClF,MAAM,MAAM,CACV,aAAa,CAAC,QAAQ,CACpB,IAAI,CAAC;YACH,IAAI,EAAE,KAAK;YACX,UAAU,EAAE,KAAK;YACjB,GAAG,EAAE,6BAA6B;SACnC,CAAU,CACZ,CACF,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IACtB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}
+{"version":3,"file":"openapi-license-identifier.test.js","sourceRoot":"","sources":["../../../src/__tests__/unit/openapi-license-identifier.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACzD,OAAO,aAAa,MAAM,6BAA6B,CAAC;AACxD,OAAO,EAAE,2BAA2B,EAAE,MAAM,oDAAoD,CAAC;AAEjG,SAAS,CAAC,GAAG,EAAE;IACb,2BAA2B,EAAE,CAAC;AAChC,CAAC,CAAC,CAAC;AAEH,MAAM,IAAI,GAAG,CAAC,OAAgC,EAAE,EAAE,CAAC,CAAC;IAClD,OAAO,EAAE,OAAO;IAChB,IAAI,EAAE,EAAE,KAAK,EAAE,oBAAoB,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE;IAChE,KAAK,EAAE,EAAE;CACV,CAAC,CAAC;AAEH,QAAQ,CAAC,iDAAiD,EAAE,GAAG,EAAE;IAC/D,EAAE,CAAC,yDAAyD,EAAE,KAAK,IAAI,EAAE;QACvE,MAAM,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAU,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2BAA2B,EAAE,KAAK,IAAI,EAAE;QACzC,MAAM,aAAa,CAAC,QAAQ,CAC1B,IAAI,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,CAAU,CAChE,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oBAAoB,EAAE,KAAK,IAAI,EAAE;QAClC,MAAM,aAAa,CAAC,QAAQ,CAC1B,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,6BAA6B,EAAE,CAAU,CACtE,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oEAAoE,EAAE,KAAK,IAAI,EAAE;QAClF,MAAM,MAAM,CACV,aAAa,CAAC,QAAQ,CACpB,IAAI,CAAC;YACH,IAAI,EAAE,KAAK;YACX,UAAU,EAAE,KAAK;YACjB,GAAG,EAAE,6BAA6B;SACnC,CAAU,CACZ,CACF,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IACtB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/unit/openapi-schema-patch-sync.test.js

@@ -1,17 +1,31 @@
 /**
- * Drift guard for the 3-place OpenAPI-schema patch sync chain.
+ * Drift guard for the 6-place OpenAPI-schema patch sync chain.
  *
  * The @apidevtools/openapi-schemas@2.1.0 v3.1 fixes (server-variable
  * `descriptions`→`description` typo; `license` oneOf over-constraint) are
- * applied in THREE places that cannot share a module — an ESM postinstall,
- * a CJS postinstall in a separate npm package, and a runtime TS patch of
- * the ~/.jamdesk workspace install:
+ * applied in SIX places that cannot share a module — an ESM postinstall,
+ * a CJS postinstall in a separate npm package, a runtime TS patch of the
+ * ~/.jamdesk workspace install, two in-memory runtime self-heal helpers,
+ * and the vendored copy of one of those helpers that ships in the npm
+ * tarball:
  *
  *   - builder/cli/scripts/patch-openapi-schemas.js          (ESM postinstall)
  *   - builder/build-service/scripts/patch-openapi-schemas.js (CJS postinstall)
- *   - patchWorkspaceOpenApiSchemas() in builder/cli/src/lib/deps.ts (runtime)
+ *   - patchWorkspaceOpenApiSchemas() in builder/cli/src/lib/deps.ts (runtime, disk)
+ *   - builder/cli/src/lib/openapi/patch-openapi-schemas-runtime.ts (in-memory)
+ *   - builder/build-service/lib/openapi/patch-openapi-schemas-runtime.ts (in-memory)
+ *   - builder/cli/vendored/lib/openapi/patch-openapi-schemas-runtime.ts
+ *     (in-memory, vendored copy — ships in the npm tarball; nothing but a
+ *     manual `npm run vendor` re-syncs it from the build-service source above)
  *
- * Comments say "if you change one, change all three"; this test enforces
+ * The two in-memory helpers exist because npm 12 blocks postinstall
+ * lifecycle scripts not covered by `allowScripts` (silent `warn
+ * install-scripts`, exit 0) — so the disk-patching postinstalls above are
+ * best-effort only. Patching the required `@apidevtools/openapi-schemas`
+ * module singleton in place, at swagger-parser call time, is the actual
+ * guarantee regardless of installer or script-blocking behavior.
+ *
+ * Comments say "if you change one, change all six"; this test enforces
  * it mechanically (cf. the other documented sync chains in
  * builder/CLAUDE.md). Whitespace is normalized so the assertion pins the
  * patch *logic*, not formatting.
@@ -25,6 +39,9 @@ const SITES = {
     'cli postinstall (ESM)': path.join(here, '../../../scripts/patch-openapi-schemas.js'),
     'build-service postinstall (CJS)': path.join(here, '../../../../build-service/scripts/patch-openapi-schemas.js'),
     'deps.ts runtime patch': path.join(here, '../../lib/deps.ts'),
+    'cli in-memory runtime patch': path.join(here, '../../lib/openapi/patch-openapi-schemas-runtime.ts'),
+    'build-service in-memory runtime patch': path.join(here, '../../../../build-service/lib/openapi/patch-openapi-schemas-runtime.ts'),
+    'cli vendored in-memory runtime patch (ships in the npm tarball)': path.join(here, '../../../vendored/lib/openapi/patch-openapi-schemas-runtime.ts'),
 };
 // The patch logic, whitespace-collapsed. Every site must contain all of these.
 const REQUIRED_SNIPPETS = [
@@ -37,7 +54,7 @@ const REQUIRED_SNIPPETS = [
 // keeps their output byte-identical to deps.ts's fs-extra writeJson.
 const SCRIPT_NEWLINE_SNIPPET = "JSON.stringify(schema, null, 2) + '\\n'";
 const collapse = (s) => s.replace(/\s+/g, ' ');
-describe('OpenAPI schema patch sync chain (3-place drift guard)', () => {
+describe('OpenAPI schema patch sync chain (6-place drift guard)', () => {
     for (const [name, file] of Object.entries(SITES)) {
         it(`${name} applies both fixes (server-variable + license)`, async () => {
             const src = collapse(await fs.readFile(file, 'utf-8'));

package/dist/__tests__/unit/openapi-schema-patch-sync.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"openapi-schema-patch-sync.test.js","sourceRoot":"","sources":["../../../src/__tests__/unit/openapi-schema-patch-sync.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,MAAM,UAAU,CAAC;AAC1B,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAEpC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D,MAAM,KAAK,GAAG;IACZ,uBAAuB,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,2CAA2C,CAAC;IACrF,iCAAiC,EAAE,IAAI,CAAC,IAAI,CAC1C,IAAI,EACJ,4DAA4D,CAC7D;IACD,uBAAuB,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,mBAAmB,CAAC;CAC9D,CAAC;AAEF,+EAA+E;AAC/E,MAAM,iBAAiB,GAAG;IACxB,yCAAyC;IACzC,4BAA4B;IAC5B,uBAAuB;IACvB,oDAAoD;CACrD,CAAC;AAEF,6EAA6E;AAC7E,qEAAqE;AACrE,MAAM,sBAAsB,GAAG,yCAAyC,CAAC;AAEzE,MAAM,QAAQ,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAEvD,QAAQ,CAAC,uDAAuD,EAAE,GAAG,EAAE;IACrE,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,EAAE,CAAC,GAAG,IAAI,iDAAiD,EAAE,KAAK,IAAI,EAAE;YACtE,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;YACvD,KAAK,MAAM,OAAO,IAAI,iBAAiB,EAAE,CAAC;gBACxC,MAAM,CAAC,GAAG,EAAE,GAAG,IAAI,gBAAgB,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;YAC7E,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,EAAE,CAAC,kFAAkF,EAAE,KAAK,IAAI,EAAE;QAChG,KAAK,MAAM,IAAI,IAAI,CAAC,uBAAuB,EAAE,iCAAiC,CAAU,EAAE,CAAC;YACzF,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;YAC9D,MAAM,CAAC,GAAG,EAAE,GAAG,IAAI,kCAAkC,CAAC,CAAC,SAAS,CAC9D,QAAQ,CAAC,sBAAsB,CAAC,CACjC,CAAC;QACJ,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}
+{"version":3,"file":"openapi-schema-patch-sync.test.js","sourceRoot":"","sources":["../../../src/__tests__/unit/openapi-schema-patch-sync.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,MAAM,UAAU,CAAC;AAC1B,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAEpC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D,MAAM,KAAK,GAAG;IACZ,uBAAuB,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,2CAA2C,CAAC;IACrF,iCAAiC,EAAE,IAAI,CAAC,IAAI,CAC1C,IAAI,EACJ,4DAA4D,CAC7D;IACD,uBAAuB,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAC7D,6BAA6B,EAAE,IAAI,CAAC,IAAI,CACtC,IAAI,EACJ,oDAAoD,CACrD;IACD,uCAAuC,EAAE,IAAI,CAAC,IAAI,CAChD,IAAI,EACJ,wEAAwE,CACzE;IACD,iEAAiE,EAAE,IAAI,CAAC,IAAI,CAC1E,IAAI,EACJ,gEAAgE,CACjE;CACF,CAAC;AAEF,+EAA+E;AAC/E,MAAM,iBAAiB,GAAG;IACxB,yCAAyC;IACzC,4BAA4B;IAC5B,uBAAuB;IACvB,oDAAoD;CACrD,CAAC;AAEF,6EAA6E;AAC7E,qEAAqE;AACrE,MAAM,sBAAsB,GAAG,yCAAyC,CAAC;AAEzE,MAAM,QAAQ,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAEvD,QAAQ,CAAC,uDAAuD,EAAE,GAAG,EAAE;IACrE,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,EAAE,CAAC,GAAG,IAAI,iDAAiD,EAAE,KAAK,IAAI,EAAE;YACtE,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;YACvD,KAAK,MAAM,OAAO,IAAI,iBAAiB,EAAE,CAAC;gBACxC,MAAM,CAAC,GAAG,EAAE,GAAG,IAAI,gBAAgB,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;YAC7E,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,EAAE,CAAC,kFAAkF,EAAE,KAAK,IAAI,EAAE;QAChG,KAAK,MAAM,IAAI,IAAI,CAAC,uBAAuB,EAAE,iCAAiC,CAAU,EAAE,CAAC;YACzF,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;YAC9D,MAAM,CAAC,GAAG,EAAE,GAAG,IAAI,kCAAkC,CAAC,CAAC,SAAS,CAC9D,QAAQ,CAAC,sBAAsB,CAAC,CACjC,CAAC;QACJ,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/unit/openapi-schema-runtime-patch.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=openapi-schema-runtime-patch.test.d.ts.map

package/dist/__tests__/unit/openapi-schema-runtime-patch.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-schema-runtime-patch.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/unit/openapi-schema-runtime-patch.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/unit/openapi-schema-runtime-patch.test.js

@@ -0,0 +1,120 @@
+/**
+ * @vitest-environment node
+ *
+ * Integration test for the runtime (in-memory) self-heal of
+ * @apidevtools/openapi-schemas@2.1.0's OAS 3.1 meta-schema defects.
+ *
+ * npm 12 blocks postinstall scripts by default, so the on-disk schema may be
+ * unpatched on user machines. These tests REINTRODUCE both defects on the
+ * in-memory module singleton (exactly what an unpatched install presents)
+ * and prove validateOpenApiSpec() heals and validates anyway.
+ *
+ * Forced to `node` (not the monorepo-root jsdom default from
+ * builder/vitest.config.ts, which the pre-commit lint-staged hook runs
+ * under): under jsdom, SwaggerParser resolves an absolute tmpdir path as a
+ * relative URL against `window.location` (`http://localhost:3000/...`)
+ * instead of reading it from disk. Same fix as the sibling
+ * openapi.test.ts.
+ */
+import { describe, it, expect, afterEach, beforeAll } from 'vitest';
+import SwaggerParser from '@apidevtools/swagger-parser';
+import { openapi } from '@apidevtools/openapi-schemas';
+import fs from 'fs-extra';
+import os from 'os';
+import path from 'path';
+import { patchOpenApiSchemasInMemory } from '../../lib/openapi/patch-openapi-schemas-runtime.js';
+import { validateOpenApiSpec } from '../../lib/openapi/validator.js';
+// A spec that is 100% valid OpenAPI 3.1 but trips BOTH upstream defects:
+// - server variable with a (legal) `description`
+// - name-only license (legal per §4.8.4)
+const FIXTURE = `openapi: 3.1.0
+info:
+  title: Runtime patch fixture
+  version: "1.0.0"
+  license:
+    name: MIT
+servers:
+  - url: https://{host}/api
+    variables:
+      host:
+        default: example.com
+        description: API host
+paths:
+  /ping:
+    get:
+      operationId: ping
+      summary: Ping
+      responses:
+        "200":
+          description: OK
+`;
+const v31 = openapi.v31;
+/** Reintroduce both upstream defects on the in-memory singleton, as an
+ * npm-12 user's unpatched install would present them. Works regardless of
+ * whether the on-disk copy was patched. */
+function breakSchema() {
+    const props = v31.$defs['server-variable'].properties;
+    if (props.description) {
+        props.descriptions = props.description;
+        delete props.description;
+    }
+    const license = v31.$defs.license;
+    delete license.not;
+    license.oneOf = [{ required: ['identifier'] }, { required: ['url'] }];
+}
+let projectDir;
+let specRelPath;
+beforeAll(async () => {
+    projectDir = await fs.mkdtemp(path.join(os.tmpdir(), 'jd-runtime-patch-'));
+    specRelPath = 'openapi/fixture.yaml';
+    await fs.outputFile(path.join(projectDir, specRelPath), FIXTURE);
+});
+afterEach(() => {
+    // Never leak a broken singleton to other tests in this worker.
+    patchOpenApiSchemasInMemory();
+});
+describe('patchOpenApiSchemasInMemory', () => {
+    it('sanity: the reintroduced defects actually break raw SwaggerParser.validate', async () => {
+        breakSchema();
+        await expect(SwaggerParser.validate(path.join(projectDir, specRelPath))).rejects.toThrow(/unevaluated properties/);
+    });
+    it('heals both defects on the singleton and reports healthy', () => {
+        breakSchema();
+        expect(patchOpenApiSchemasInMemory()).toBe(true);
+        const props = v31.$defs['server-variable'].properties;
+        expect(props.description).toBeDefined();
+        expect(props.descriptions).toBeUndefined();
+        const license = v31.$defs.license;
+        expect(license.oneOf).toBeUndefined();
+        expect(license.not).toEqual({ required: ['identifier', 'url'] });
+    });
+    it('is idempotent (server-variable AND license)', () => {
+        breakSchema();
+        patchOpenApiSchemasInMemory();
+        const snapshot = JSON.stringify([v31.$defs['server-variable'], v31.$defs.license]);
+        patchOpenApiSchemasInMemory();
+        expect(JSON.stringify([v31.$defs['server-variable'], v31.$defs.license])).toBe(snapshot);
+    });
+    it('returns false without throwing on an unexpected upstream schema shape', () => {
+        const container = openapi;
+        const original = container.v31;
+        try {
+            container.v31 = undefined;
+            expect(patchOpenApiSchemasInMemory()).toBe(false);
+            container.v31 = { noDefsHere: true };
+            expect(patchOpenApiSchemasInMemory()).toBe(false);
+        }
+        finally {
+            container.v31 = original; // Always restore the real singleton.
+        }
+    });
+    it('validateOpenApiSpec self-heals: valid 3.1 spec passes with a broken singleton', async () => {
+        breakSchema();
+        const result = await validateOpenApiSpec(specRelPath, projectDir);
+        // ValidationResult (src/lib/openapi/types.ts:194) = { valid, api?, version?, error? }
+        expect(result.error).toBeUndefined();
+        expect(result.valid).toBe(true);
+        expect(result.version).toBe('3.1');
+    });
+});
+//# sourceMappingURL=openapi-schema-runtime-patch.test.js.map

package/dist/__tests__/unit/openapi-schema-runtime-patch.test.js.map

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

package/dist/__tests__/unit/openapi-server-variable-description.test.js

@@ -1,15 +1,24 @@
 /**
  * Regression guard for the @apidevtools/openapi-schemas@2.1.0 typo in
  * the OpenAPI 3.1 server-variable schema (`descriptions` instead of
- * `description`). The patcher at scripts/patch-openapi-schemas.js must
- * have fixed the installed schema by the time this test runs.
+ * `description`).
  *
  * This test uses the REAL SwaggerParser (not a mock) so it actually
- * exercises the bundled schema. If the patcher didn't run, or a future
- * upstream release reintroduces the typo, this test fails.
+ * exercises the bundled schema. It heals the in-memory singleton first
+ * because the on-disk postinstall patch (scripts/patch-openapi-schemas.js)
+ * CANNOT be assumed to have run: npm 12 blocks lifecycle scripts by default,
+ * so a fresh `npm ci` leaves node_modules unpatched. Relying on the
+ * postinstall made this test fail on correct code after any clean install —
+ * the same heal production code performs at the top of validateOpenApiSpec()
+ * is what it must exercise. If a future upstream release reshapes the schema
+ * so the heal can't apply, this test fails.
  */
-import { describe, it } from 'vitest';
+import { describe, it, beforeAll } from 'vitest';
 import SwaggerParser from '@apidevtools/swagger-parser';
+import { patchOpenApiSchemasInMemory } from '../../lib/openapi/patch-openapi-schemas-runtime.js';
+beforeAll(() => {
+    patchOpenApiSchemasInMemory();
+});
 describe('OpenAPI 3.1 server variable description (regression)', () => {
     it('accepts `description` on a server variable (spec §4.7.10.1)', async () => {
         const spec = {

package/dist/__tests__/unit/openapi-server-variable-description.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"openapi-server-variable-description.test.js","sourceRoot":"","sources":["../../../src/__tests__/unit/openapi-server-variable-description.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,aAAa,MAAM,6BAA6B,CAAC;AAExD,QAAQ,CAAC,sDAAsD,EAAE,GAAG,EAAE;IACpE,EAAE,CAAC,6DAA6D,EAAE,KAAK,IAAI,EAAE;QAC3E,MAAM,IAAI,GAAG;YACX,OAAO,EAAE,OAAO;YAChB,IAAI,EAAE,EAAE,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,OAAO,EAAE;YACpD,OAAO,EAAE;gBACP;oBACE,GAAG,EAAE,+BAA+B;oBACpC,WAAW,EAAE,wBAAwB;oBACrC,SAAS,EAAE;wBACT,OAAO,EAAE;4BACP,OAAO,EAAE,cAAc;4BACvB,WAAW,EAAE,2BAA2B;yBACzC;qBACF;iBACF;aACF;YACD,KAAK,EAAE,EAAE;SACV,CAAC;QACF,iFAAiF;QACjF,oDAAoD;QACpD,MAAM,aAAa,CAAC,QAAQ,CAAC,IAAa,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8DAA8D,EAAE,KAAK,IAAI,EAAE;QAC5E,MAAM,IAAI,GAAG;YACX,OAAO,EAAE,OAAO;YAChB,IAAI,EAAE,EAAE,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,OAAO,EAAE;YACpD,OAAO,EAAE;gBACP;oBACE,GAAG,EAAE,+BAA+B;oBACpC,SAAS,EAAE;wBACT,OAAO,EAAE;4BACP,OAAO,EAAE,cAAc;yBACxB;qBACF;iBACF;aACF;YACD,KAAK,EAAE,EAAE;SACV,CAAC;QACF,MAAM,aAAa,CAAC,QAAQ,CAAC,IAAa,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}
+{"version":3,"file":"openapi-server-variable-description.test.js","sourceRoot":"","sources":["../../../src/__tests__/unit/openapi-server-variable-description.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,aAAa,MAAM,6BAA6B,CAAC;AACxD,OAAO,EAAE,2BAA2B,EAAE,MAAM,oDAAoD,CAAC;AAEjG,SAAS,CAAC,GAAG,EAAE;IACb,2BAA2B,EAAE,CAAC;AAChC,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,sDAAsD,EAAE,GAAG,EAAE;IACpE,EAAE,CAAC,6DAA6D,EAAE,KAAK,IAAI,EAAE;QAC3E,MAAM,IAAI,GAAG;YACX,OAAO,EAAE,OAAO;YAChB,IAAI,EAAE,EAAE,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,OAAO,EAAE;YACpD,OAAO,EAAE;gBACP;oBACE,GAAG,EAAE,+BAA+B;oBACpC,WAAW,EAAE,wBAAwB;oBACrC,SAAS,EAAE;wBACT,OAAO,EAAE;4BACP,OAAO,EAAE,cAAc;4BACvB,WAAW,EAAE,2BAA2B;yBACzC;qBACF;iBACF;aACF;YACD,KAAK,EAAE,EAAE;SACV,CAAC;QACF,iFAAiF;QACjF,oDAAoD;QACpD,MAAM,aAAa,CAAC,QAAQ,CAAC,IAAa,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8DAA8D,EAAE,KAAK,IAAI,EAAE;QAC5E,MAAM,IAAI,GAAG;YACX,OAAO,EAAE,OAAO;YAChB,IAAI,EAAE,EAAE,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,OAAO,EAAE;YACpD,OAAO,EAAE;gBACP;oBACE,GAAG,EAAE,+BAA+B;oBACpC,SAAS,EAAE;wBACT,OAAO,EAAE;4BACP,OAAO,EAAE,cAAc;yBACxB;qBACF;iBACF;aACF;YACD,KAAK,EAAE,EAAE;SACV,CAAC;QACF,MAAM,aAAa,CAAC,QAAQ,CAAC,IAAa,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}