@sky.ui/mcp 0.0.1

package/dist/framework-wrappers.js

@@ -0,0 +1,131 @@
+import { createRequire } from 'node:module';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadSkyComponentsCached, resolveComponentEntry, packagesDir } from './catalog.js';
+import { PACKAGE_IMPORTS } from './component-tier.js';
+export function kebabTagToPascal(tag) {
+    return tag
+        .split('-')
+        .map((p) => (p ? p[0].toUpperCase() + p.slice(1) : ''))
+        .join('');
+}
+function buildSnippets(framework, tag, pascal, vuePkg, reactPkg) {
+    if (framework === 'react') {
+        return {
+            reactPerComponent: `import { ${pascal} } from '${reactPkg}/${tag}';\n\nexport default function Demo() {\n  return <${pascal}>Hello</${pascal}>;\n}`,
+            reactBarrel: `import { ${pascal} } from '${reactPkg}';\n\nexport default function Demo() {\n  return <${pascal}>Hello</${pascal}>;\n}`,
+            reactAutoImportNote: `// With SkyUIReactVitePlugin() or SkyUIReactWebpackPlugin + SkyUIReactResolver — JSX can use <${pascal} /> without manual imports.\n// Full explicit barrel:\nimport { ${pascal} } from '${reactPkg}';\n\nexport default function Demo() {\n  return <${pascal} variant="primary">Hello</${pascal}>;\n}`,
+            vuePerComponent: '',
+            vueBarrel: '',
+            vueAutoImportNote: '',
+            vueTemplateKebab: ''
+        };
+    }
+    return {
+        reactPerComponent: '',
+        reactBarrel: '',
+        reactAutoImportNote: '',
+        vuePerComponent: `<script setup lang="ts">\nimport { ${pascal} } from '${vuePkg}/${tag}';\n</script>\n\n<template>\n  <${pascal}>Hello</${pascal}>\n</template>`,
+        vueBarrel: `<script setup lang="ts">\nimport { ${pascal} } from '${vuePkg}';\n</script>\n\n<template>\n  <${pascal}>Hello</${pascal}>\n</template>`,
+        vueAutoImportNote: `<!-- With SkyUIVueVitePlugin() / SkyUIVueWebpackPlugin + SkyUIVueResolver — SFCs can use <${pascal}> without script imports. -->\n<script setup lang="ts">\n// Optional explicit: import { ${pascal} } from '${vuePkg}';\n</script>\n\n<template>\n  <${pascal} variant="primary">Hello</${pascal}>\n</template>`,
+        vueTemplateKebab: `<template>\n  <!-- Pascal (recommended with script import) -->\n  <${pascal} label="OK" />\n  <!-- Kebab form also works (aligns with custom element name): -->\n  <${tag} label="OK" />\n</template>`
+    };
+}
+function readPublishedWrapperMeta(framework, tier) {
+    const monoFolder = tier === 'pro' ? `${framework}-pro` : framework;
+    const packageName = PACKAGE_IMPORTS[tier][framework];
+    const mono = join(packagesDir(), monoFolder);
+    const monoPkg = join(mono, 'package.json');
+    const parse = (path) => {
+        const raw = JSON.parse(readFileSync(path, 'utf8'));
+        return {
+            version: typeof raw.version === 'string' ? raw.version : null,
+            peerDependencies: raw.peerDependencies && typeof raw.peerDependencies === 'object' ? raw.peerDependencies : {}
+        };
+    };
+    if (existsSync(monoPkg)) {
+        return parse(monoPkg);
+    }
+    try {
+        const req = createRequire(import.meta.url);
+        const resolved = req.resolve(`${packageName}/package.json`);
+        return parse(resolved);
+    }
+    catch {
+        return { version: null, peerDependencies: {} };
+    }
+}
+export function buildFrameworkWrapperDetails(framework, nameInput) {
+    const hitRes = loadSkyComponentsCached();
+    if (!hitRes.ok)
+        return { ok: false, error: hitRes.error };
+    const resolved = resolveComponentEntry(nameInput, hitRes.components);
+    if (!resolved)
+        return { ok: false, error: `Unknown component: ${nameInput}` };
+    const tag = resolved.entry.name;
+    const tier = resolved.entry.tier;
+    const pascal = kebabTagToPascal(tag);
+    const vuePkg = resolved.entry.vueImport.replace(/\/[^/]+$/, '');
+    const reactPkg = resolved.entry.reactImport.replace(/\/[^/]+$/, '');
+    const meta = readPublishedWrapperMeta(framework, tier);
+    const pkg = framework === 'react' ? reactPkg : vuePkg;
+    const primaryImportLine = framework === 'react'
+        ? `import { ${pascal} } from '${resolved.entry.reactImport}';`
+        : `import { ${pascal} } from '${resolved.entry.vueImport}';`;
+    const conventions = framework === 'react'
+        ? [
+            'JSX props follow camelCase; they map to the underlying custom element (see get_sky_component_docs with surface props for names/types).',
+            'Use children for default slot content; named slots may require patterns from get_sky_component_docs with surface slots.',
+            `For DOM/custom events, use get_sky_component_docs with surface events — @lit/react exposes listeners as React props (see component typings in ${reactPkg}).`,
+            'Bundler: prefer get_project_guide with kind setup, framework react, and your bundler (@sky.ui/react/vite or @sky.ui.pro/react/vite, /webpack, /rollup) + optional unplugin auto-import.',
+            `Barrel import \`import { ... } from '${reactPkg}'\` re-exports all wrappers; per-component path tree-shakes more predictably.`
+        ]
+        : [
+            'In SFC templates you may use PascalCase (<SkyButton>) or kebab-case (<sky-button>) once the component is registered or auto-imported.',
+            'Props in templates: kebab-case attributes map to the underlying component (Vue generally accepts both where applicable).',
+            `Use get_sky_component_docs (props / events / slots surfaces) for authoritative names; Vue SFC types come from ${vuePkg}.`,
+            'v-model: use it only when the component docs describe a two-way prop + event pair; otherwise bind with :prop and @event from get_sky_component_docs. Custom events use CustomEvent detail—match the documented payload.',
+            'Usage patterns (default vs named v-model, explicit bindings): get_docs packages/mcp/docs/vue-wrapper-v-model.md',
+            `Bundler: get_project_guide with kind setup and framework vue for SkyUIVueVitePlugin (${vuePkg}/vite, /webpack, /rollup) and unplugin-vue-components resolver.`,
+            `Barrel \`import { ... } from '${vuePkg}'\` loads the full export surface; subpath \`${vuePkg}/<tag>\` matches core folder names.`
+        ];
+    const details = {
+        framework,
+        componentKebab: tag,
+        pascalName: pascal,
+        primaryImportLine,
+        importPerComponent: framework === 'react' ? resolved.entry.reactImport : resolved.entry.vueImport,
+        importBarrel: pkg,
+        vueKebabTagInTemplate: tag,
+        snippets: buildSnippets(framework, tag, pascal, vuePkg, reactPkg),
+        conventions,
+        relatedMcpTools: [
+            'get_sky_component_docs',
+            'get_project_guide',
+            'get_component_usage',
+            ...(framework === 'vue' ? ['get_docs'] : [])
+        ],
+        packageVersion: meta.version,
+        peerDependencies: meta.peerDependencies
+    };
+    return { ok: true, details };
+}
+export function buildUsageSnippetForFramework(framework, componentInput, style) {
+    const rich = buildFrameworkWrapperDetails(framework, componentInput);
+    if (!rich.ok)
+        return rich;
+    const { componentKebab, pascalName, snippets } = rich.details;
+    if (framework === 'react') {
+        if (style === 'per_component')
+            return { ok: true, componentName: componentKebab, snippet: snippets.reactPerComponent };
+        if (style === 'barrel')
+            return { ok: true, componentName: componentKebab, snippet: snippets.reactBarrel };
+        return { ok: true, componentName: componentKebab, snippet: snippets.reactAutoImportNote };
+    }
+    if (style === 'per_component')
+        return { ok: true, componentName: componentKebab, snippet: snippets.vuePerComponent };
+    if (style === 'barrel')
+        return { ok: true, componentName: componentKebab, snippet: snippets.vueBarrel };
+    return { ok: true, componentName: componentKebab, snippet: snippets.vueAutoImportNote };
+}
+//# sourceMappingURL=framework-wrappers.js.map

package/dist/framework-wrappers.js.map

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

package/dist/mcp-response-truth.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Every MCP tool response should carry explicit epistemic classification so clients
+ * never treat heuristic or guideline output as authoritative API truth.
+ */
+export type SkyUiMcpTruthLayer = 'api_source' | 'guideline_scoring' | 'heuristic_search' | 'deterministic' | 'static_reference' | 'external_optional';
+export type SkyUiMcpMeta = {
+    truthLayer: SkyUiMcpTruthLayer;
+    summary: string;
+    agentMust: string;
+    serverVersion?: string;
+    enrichmentNote?: string;
+};
+export declare function skyUiMcpMeta(layer: SkyUiMcpTruthLayer, enrichmentNote?: string): SkyUiMcpMeta;
+/** Attach once per JSON payload (merge-safe). */
+export declare function withSkyUiMcpMeta<T extends Record<string, unknown>>(body: T, layer: SkyUiMcpTruthLayer, enrichmentNote?: string): T & {
+    _skyUiMcp: SkyUiMcpMeta;
+};
+//# sourceMappingURL=mcp-response-truth.d.ts.map

package/dist/mcp-response-truth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-response-truth.d.ts","sourceRoot":"","sources":["../src/mcp-response-truth.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAC1B,YAAY,GACZ,mBAAmB,GACnB,kBAAkB,GAClB,eAAe,GACf,kBAAkB,GAClB,mBAAmB,CAAC;AAqCxB,MAAM,MAAM,YAAY,GAAG;IACzB,UAAU,EAAE,kBAAkB,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,wBAAgB,YAAY,CAC1B,KAAK,EAAE,kBAAkB,EACzB,cAAc,CAAC,EAAE,MAAM,GACtB,YAAY,CASd;AAED,iDAAiD;AACjD,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChE,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,kBAAkB,EACzB,cAAc,CAAC,EAAE,MAAM,GACtB,CAAC,GAAG;IAAE,SAAS,EAAE,YAAY,CAAA;CAAE,CAKjC"}

package/dist/mcp-response-truth.js

@@ -0,0 +1,45 @@
+const TRUTH_GUIDANCE = {
+    api_source: {
+        summary: 'Derived from repo or package sources (CEM, AST, package.json, shipped JSON).',
+        agentMust: 'Use dataSource fields; confirm behavior against the consumer app version and tests — docs can lag or differ by build.'
+    },
+    guideline_scoring: {
+        summary: 'Design-guideline heuristics (rules, scores, recommendations).',
+        agentMust: 'Do not cite as API contracts or browser guarantees — validate UX and a11y in the real product.'
+    },
+    heuristic_search: {
+        summary: 'Search / ranking over catalogs — relevance is approximate.',
+        agentMust: 'Verify hits against get_sky_component_docs or split prop/event tools before asserting APIs.'
+    },
+    deterministic: {
+        summary: 'Computed from fixed inputs with explicit rules (contrast math, catalog membership, etc.).',
+        agentMust: 'Still scope results to stated assumptions (e.g. default theme catalog vs project theme).'
+    },
+    static_reference: {
+        summary: 'Bundled prose or version lists — not live API verification.',
+        agentMust: 'Cross-check installation paths and versions with the user package.json and registry.'
+    },
+    external_optional: {
+        summary: 'Optional HTTP response or shipped embed — not authoritative for the consumer repo.',
+        agentMust: 'Never prefer this over get_sky_component_docs or split prop/event tools for API facts; may be stale or marketing skewed.'
+    }
+};
+import { getMcpPackageVersion } from './mcp-runtime-status.js';
+export function skyUiMcpMeta(layer, enrichmentNote) {
+    const g = TRUTH_GUIDANCE[layer];
+    return {
+        truthLayer: layer,
+        summary: g.summary,
+        agentMust: g.agentMust,
+        serverVersion: getMcpPackageVersion(),
+        ...(enrichmentNote ? { enrichmentNote } : {})
+    };
+}
+/** Attach once per JSON payload (merge-safe). */
+export function withSkyUiMcpMeta(body, layer, enrichmentNote) {
+    return {
+        ...body,
+        _skyUiMcp: skyUiMcpMeta(layer, enrichmentNote)
+    };
+}
+//# sourceMappingURL=mcp-response-truth.js.map

package/dist/mcp-response-truth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-response-truth.js","sourceRoot":"","sources":["../src/mcp-response-truth.ts"],"names":[],"mappings":"AAYA,MAAM,cAAc,GAGhB;IACF,UAAU,EAAE;QACV,OAAO,EAAE,8EAA8E;QACvF,SAAS,EACP,uHAAuH;KAC1H;IACD,iBAAiB,EAAE;QACjB,OAAO,EAAE,+DAA+D;QACxE,SAAS,EACP,gGAAgG;KACnG;IACD,gBAAgB,EAAE;QAChB,OAAO,EAAE,4DAA4D;QACrE,SAAS,EAAE,6FAA6F;KACzG;IACD,aAAa,EAAE;QACb,OAAO,EAAE,2FAA2F;QACpG,SAAS,EAAE,0FAA0F;KACtG;IACD,gBAAgB,EAAE;QAChB,OAAO,EAAE,6DAA6D;QACtE,SAAS,EAAE,sFAAsF;KAClG;IACD,iBAAiB,EAAE;QACjB,OAAO,EAAE,oFAAoF;QAC7F,SAAS,EACP,0HAA0H;KAC7H;CACF,CAAC;AAEF,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAU/D,MAAM,UAAU,YAAY,CAC1B,KAAyB,EACzB,cAAuB;IAEvB,MAAM,CAAC,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IAChC,OAAO;QACL,UAAU,EAAE,KAAK;QACjB,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,aAAa,EAAE,oBAAoB,EAAE;QACrC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9C,CAAC;AACJ,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,gBAAgB,CAC9B,IAAO,EACP,KAAyB,EACzB,cAAuB;IAEvB,OAAO;QACL,GAAG,IAAI;QACP,SAAS,EAAE,YAAY,CAAC,KAAK,EAAE,cAAc,CAAC;KAC/C,CAAC;AACJ,CAAC"}

package/dist/mcp-runtime-status.d.ts

@@ -0,0 +1,37 @@
+export declare function getMcpPackageVersion(): string;
+export type McpRuntimeStatus = {
+    version: string;
+    toolCount: number;
+    tools: readonly string[];
+    core: {
+        resolved: boolean;
+        root: string | null;
+        proResolved: boolean;
+        proRoot: string | null;
+        customElementsManifest: boolean;
+        astSourceAvailable: boolean;
+        docsReady: boolean;
+        hint: string | null;
+    };
+    utils: {
+        packageResolved: boolean;
+        engineSource: 'live' | 'snapshot' | 'none';
+    };
+    reactivity: {
+        packageResolved: boolean;
+        readmeSnapshot: boolean;
+    };
+    data: {
+        themeContract: boolean;
+        chartApiSections: boolean;
+        utilsClassSnapshot: boolean;
+        reactivityReadmeSnapshot: boolean;
+    };
+    exampleSite: {
+        baseUrlConfigured: boolean;
+        baseUrl: string | null;
+    };
+    remediation: string[];
+};
+export declare function getMcpRuntimeStatus(): McpRuntimeStatus;
+//# sourceMappingURL=mcp-runtime-status.d.ts.map

package/dist/mcp-runtime-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-runtime-status.d.ts","sourceRoot":"","sources":["../src/mcp-runtime-status.ts"],"names":[],"mappings":"AAUA,wBAAgB,oBAAoB,IAAI,MAAM,CAO7C;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,IAAI,EAAE;QACJ,QAAQ,EAAE,OAAO,CAAC;QAClB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QACpB,WAAW,EAAE,OAAO,CAAC;QACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,sBAAsB,EAAE,OAAO,CAAC;QAChC,kBAAkB,EAAE,OAAO,CAAC;QAC5B,SAAS,EAAE,OAAO,CAAC;QACnB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;KACrB,CAAC;IACF,KAAK,EAAE;QACL,eAAe,EAAE,OAAO,CAAC;QACzB,YAAY,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;KAC5C,CAAC;IACF,UAAU,EAAE;QACV,eAAe,EAAE,OAAO,CAAC;QACzB,cAAc,EAAE,OAAO,CAAC;KACzB,CAAC;IACF,IAAI,EAAE;QACJ,aAAa,EAAE,OAAO,CAAC;QACvB,gBAAgB,EAAE,OAAO,CAAC;QAC1B,kBAAkB,EAAE,OAAO,CAAC;QAC5B,wBAAwB,EAAE,OAAO,CAAC;KACnC,CAAC;IACF,WAAW,EAAE;QACX,iBAAiB,EAAE,OAAO,CAAC;QAC3B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;KACxB,CAAC;IACF,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB,CAAC;AAWF,wBAAgB,mBAAmB,IAAI,gBAAgB,CAsEtD"}

package/dist/mcp-runtime-status.js

@@ -0,0 +1,96 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { mcpPackageRoot, resolveMainPackageRoot, resolveMainProPackageRoot } from './catalog.js';
+import { isCemManifestPresent } from './cem.js';
+import { READ_ONLY_TOOL_NAMES } from './read-only-tool-allowlist.js';
+import { resolveReactivityPackageRoot } from './reactivity-info.js';
+import { resolveUtilsPackageRoot, utilityEngineSource } from './utils-suggestion-grounding.js';
+import { themeAuthoringContractPath } from './theme-authoring/repository.js';
+import { resolveExampleSiteBaseUrl } from './example-site-fetch.js';
+export function getMcpPackageVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(join(mcpPackageRoot(), 'package.json'), 'utf8'));
+        return pkg.version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function dataFile(name) {
+    return existsSync(join(mcpPackageRoot(), 'data', name));
+}
+function coreAstSourceAvailable(mainRoot) {
+    if (!mainRoot)
+        return false;
+    return existsSync(join(mainRoot, 'src', 'sky-button', 'sky-button.ts'));
+}
+export function getMcpRuntimeStatus() {
+    const mainRoot = resolveMainPackageRoot();
+    const proRoot = resolveMainProPackageRoot();
+    const cem = isCemManifestPresent();
+    const ast = coreAstSourceAvailable(mainRoot) || coreAstSourceAvailable(proRoot);
+    const docsReady = Boolean((mainRoot || proRoot) && (cem || ast));
+    const utilsRoot = resolveUtilsPackageRoot();
+    const reactivityRoot = resolveReactivityPackageRoot();
+    const snapshotUtils = dataFile('utils-suggestion-snapshot.json');
+    const engineSource = utilityEngineSource() !== 'none'
+        ? utilityEngineSource()
+        : snapshotUtils
+            ? 'snapshot'
+            : 'none';
+    const remediation = [];
+    if (!mainRoot) {
+        remediation.push('Install @sky.ui/core alongside @sky.ui/mcp, or set SKY_UI_MAIN_PACKAGE_ROOT to a built core package.');
+    }
+    else if (!docsReady) {
+        remediation.push('Run npm run build:main (and build:main-pro for pro docs) so custom-elements.json exists, or point SKY_UI_MAIN_PACKAGE_ROOT / SKY_UI_MAIN_PRO_PACKAGE_ROOT at monorepo packages.');
+    }
+    if (!proRoot) {
+        remediation.push('Pro component docs/snippets need @sky.ui.pro/core (npm install @sky.ui.pro/vue pulls it) or monorepo packages/main-pro.');
+    }
+    if (engineSource === 'none') {
+        remediation.push('Install @sky.ui/utils@>=0.0.1 or use @sky.ui/mcp build that ships utils-suggestion-snapshot.json.');
+    }
+    if (!reactivityRoot && !dataFile('reactivity-readme-snapshot.json')) {
+        remediation.push('Install @sky.ui/reactivity or use MCP build with reactivity-readme-snapshot.json.');
+    }
+    return {
+        version: getMcpPackageVersion(),
+        toolCount: READ_ONLY_TOOL_NAMES.length,
+        tools: READ_ONLY_TOOL_NAMES,
+        core: {
+            resolved: !!mainRoot,
+            root: mainRoot,
+            proResolved: !!proRoot,
+            proRoot,
+            customElementsManifest: cem,
+            astSourceAvailable: ast,
+            docsReady,
+            hint: !mainRoot
+                ? 'Missing @sky.ui/core'
+                : !docsReady
+                    ? 'Core resolved but neither CEM nor AST sources found for component docs'
+                    : null
+        },
+        utils: {
+            packageResolved: !!utilsRoot,
+            engineSource
+        },
+        reactivity: {
+            packageResolved: !!reactivityRoot,
+            readmeSnapshot: dataFile('reactivity-readme-snapshot.json')
+        },
+        data: {
+            themeContract: existsSync(themeAuthoringContractPath()),
+            chartApiSections: dataFile('chart-api-sections.json'),
+            utilsClassSnapshot: dataFile('utils-suggestion-snapshot.json'),
+            reactivityReadmeSnapshot: dataFile('reactivity-readme-snapshot.json')
+        },
+        exampleSite: {
+            baseUrlConfigured: Boolean(resolveExampleSiteBaseUrl()),
+            baseUrl: resolveExampleSiteBaseUrl()
+        },
+        remediation
+    };
+}
+//# sourceMappingURL=mcp-runtime-status.js.map

package/dist/mcp-runtime-status.js.map

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

package/dist/mcp-stdio-entry.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=mcp-stdio-entry.d.ts.map

package/dist/mcp-stdio-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-stdio-entry.d.ts","sourceRoot":"","sources":["../src/mcp-stdio-entry.ts"],"names":[],"mappings":""}

package/dist/mcp-stdio-entry.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+/**
+ * stdio MCP process entry only. Kept tiny so `process.argv[1]` always matches this file
+ * (avoids silent no-op when `npx` / Windows shims pass a path that does not match `server.js`).
+ */
+import { assertCoreDependencyAvailable, startSkyUiMcpStdio } from './server.js';
+import { getMcpRuntimeStatus } from './mcp-runtime-status.js';
+const args = process.argv.slice(2);
+if (args.includes('--health')) {
+    try {
+        assertCoreDependencyAvailable();
+        const status = getMcpRuntimeStatus();
+        const ok = status.core.resolved && status.core.docsReady;
+        console.log(JSON.stringify({ ok, ...status }, null, 2));
+        if (status.remediation.length > 0) {
+            console.error('[sky-ui-mcp] health: ok with warnings');
+            for (const line of status.remediation)
+                console.error(`  - ${line}`);
+        }
+        else {
+            console.error(`[sky-ui-mcp] health: ok (@sky.ui/mcp@${status.version}, ${status.toolCount} tools)`);
+        }
+        process.exit(ok ? 0 : 1);
+    }
+    catch (err) {
+        console.error('[sky-ui-mcp] health: failed');
+        console.error(err);
+        process.exit(1);
+    }
+}
+startSkyUiMcpStdio().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});
+//# sourceMappingURL=mcp-stdio-entry.js.map

package/dist/mcp-stdio-entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-stdio-entry.js","sourceRoot":"","sources":["../src/mcp-stdio-entry.ts"],"names":[],"mappings":";AACA;;;GAGG;AACH,OAAO,EAAE,6BAA6B,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAE9D,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACnC,IAAI,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;IAC9B,IAAI,CAAC;QACH,6BAA6B,EAAE,CAAC;QAChC,MAAM,MAAM,GAAG,mBAAmB,EAAE,CAAC;QACrC,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC;QACzD,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,GAAG,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QACxD,IAAI,MAAM,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClC,OAAO,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC;YACvD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,WAAW;gBAAE,OAAO,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;QACtE,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,KAAK,CAAC,wCAAwC,MAAM,CAAC,OAAO,KAAK,MAAM,CAAC,SAAS,SAAS,CAAC,CAAC;QACtG,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,OAAO,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;QAC7C,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,kBAAkB,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC1C,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/mcp-tool-errors.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Stable `code` values for MCP tool JSON error payloads (`isError: true`).
+ * Clients should branch on `code`; `error` is human-readable detail.
+ */
+export declare const McpErrorCode: {
+    readonly COMPONENT_DOCS_FAILED: "COMPONENT_DOCS_FAILED";
+    readonly COMPONENT_CATALOG_FAILED: "COMPONENT_CATALOG_FAILED";
+    readonly COMPONENT_SEARCH_FAILED: "COMPONENT_SEARCH_FAILED";
+    readonly COMPONENT_API_SEARCH_FAILED: "COMPONENT_API_SEARCH_FAILED";
+    readonly INSTALL_GUIDE_INVALID_FRAMEWORK: "INSTALL_GUIDE_INVALID_FRAMEWORK";
+    readonly SETUP_GUIDE_INVALID_INPUT: "SETUP_GUIDE_INVALID_INPUT";
+    readonly USAGE_SNIPPET_INVALID_FRAMEWORK: "USAGE_SNIPPET_INVALID_FRAMEWORK";
+    readonly USAGE_SNIPPET_FAILED: "USAGE_SNIPPET_FAILED";
+    readonly COMPONENT_USAGE_FAILED: "COMPONENT_USAGE_FAILED";
+    readonly UNKNOWN_COMPONENT: "UNKNOWN_COMPONENT";
+    readonly THEME_EXTRACT_FAILED: "THEME_EXTRACT_FAILED";
+    readonly THEME_CONTRACT_FAILED: "THEME_CONTRACT_FAILED";
+    readonly DOCS_READ_FAILED: "DOCS_READ_FAILED";
+    readonly REACTIVITY_INFO_FAILED: "REACTIVITY_INFO_FAILED";
+    readonly REACTIVITY_TOPICS_FAILED: "REACTIVITY_TOPICS_FAILED";
+    readonly REACTIVITY_TOPIC_FAILED: "REACTIVITY_TOPIC_FAILED";
+    readonly UTILS_SUGGESTION_FAILED: "UTILS_SUGGESTION_FAILED";
+    readonly EXAMPLE_SITE_FETCH_FAILED: "EXAMPLE_SITE_FETCH_FAILED";
+    readonly CHART_USAGE_UNKNOWN_TYPE: "CHART_USAGE_UNKNOWN_TYPE";
+};
+export type McpErrorCodeValue = (typeof McpErrorCode)[keyof typeof McpErrorCode];
+export declare function mcpErrorJson(code: McpErrorCodeValue | string, error: string, extra?: Record<string, unknown>): string;
+export declare function mcpToolErr(code: McpErrorCodeValue | string, error: string, extra?: Record<string, unknown>): {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError: true;
+};
+//# sourceMappingURL=mcp-tool-errors.d.ts.map

package/dist/mcp-tool-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tool-errors.d.ts","sourceRoot":"","sources":["../src/mcp-tool-errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;CAoBf,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAEjF,wBAAgB,YAAY,CAC1B,IAAI,EAAE,iBAAiB,GAAG,MAAM,EAChC,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAQR;AAED,wBAAgB,UAAU,CACxB,IAAI,EAAE,iBAAiB,GAAG,MAAM,EAChC,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAAC,OAAO,EAAE,IAAI,CAAA;CAAE,CAKnE"}

package/dist/mcp-tool-errors.js

@@ -0,0 +1,42 @@
+/**
+ * Stable `code` values for MCP tool JSON error payloads (`isError: true`).
+ * Clients should branch on `code`; `error` is human-readable detail.
+ */
+export const McpErrorCode = {
+    COMPONENT_DOCS_FAILED: 'COMPONENT_DOCS_FAILED',
+    COMPONENT_CATALOG_FAILED: 'COMPONENT_CATALOG_FAILED',
+    COMPONENT_SEARCH_FAILED: 'COMPONENT_SEARCH_FAILED',
+    COMPONENT_API_SEARCH_FAILED: 'COMPONENT_API_SEARCH_FAILED',
+    INSTALL_GUIDE_INVALID_FRAMEWORK: 'INSTALL_GUIDE_INVALID_FRAMEWORK',
+    SETUP_GUIDE_INVALID_INPUT: 'SETUP_GUIDE_INVALID_INPUT',
+    USAGE_SNIPPET_INVALID_FRAMEWORK: 'USAGE_SNIPPET_INVALID_FRAMEWORK',
+    USAGE_SNIPPET_FAILED: 'USAGE_SNIPPET_FAILED',
+    COMPONENT_USAGE_FAILED: 'COMPONENT_USAGE_FAILED',
+    UNKNOWN_COMPONENT: 'UNKNOWN_COMPONENT',
+    THEME_EXTRACT_FAILED: 'THEME_EXTRACT_FAILED',
+    THEME_CONTRACT_FAILED: 'THEME_CONTRACT_FAILED',
+    DOCS_READ_FAILED: 'DOCS_READ_FAILED',
+    REACTIVITY_INFO_FAILED: 'REACTIVITY_INFO_FAILED',
+    REACTIVITY_TOPICS_FAILED: 'REACTIVITY_TOPICS_FAILED',
+    REACTIVITY_TOPIC_FAILED: 'REACTIVITY_TOPIC_FAILED',
+    UTILS_SUGGESTION_FAILED: 'UTILS_SUGGESTION_FAILED',
+    EXAMPLE_SITE_FETCH_FAILED: 'EXAMPLE_SITE_FETCH_FAILED',
+    CHART_USAGE_UNKNOWN_TYPE: 'CHART_USAGE_UNKNOWN_TYPE'
+};
+export function mcpErrorJson(code, error, extra) {
+    const body = { code, error };
+    if (extra) {
+        for (const [k, v] of Object.entries(extra)) {
+            if (v !== undefined)
+                body[k] = v;
+        }
+    }
+    return JSON.stringify(body, null, 2);
+}
+export function mcpToolErr(code, error, extra) {
+    return {
+        content: [{ type: 'text', text: mcpErrorJson(code, error, extra) }],
+        isError: true
+    };
+}
+//# sourceMappingURL=mcp-tool-errors.js.map

package/dist/mcp-tool-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tool-errors.js","sourceRoot":"","sources":["../src/mcp-tool-errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,qBAAqB,EAAE,uBAAuB;IAC9C,wBAAwB,EAAE,0BAA0B;IACpD,uBAAuB,EAAE,yBAAyB;IAClD,2BAA2B,EAAE,6BAA6B;IAC1D,+BAA+B,EAAE,iCAAiC;IAClE,yBAAyB,EAAE,2BAA2B;IACtD,+BAA+B,EAAE,iCAAiC;IAClE,oBAAoB,EAAE,sBAAsB;IAC5C,sBAAsB,EAAE,wBAAwB;IAChD,iBAAiB,EAAE,mBAAmB;IACtC,oBAAoB,EAAE,sBAAsB;IAC5C,qBAAqB,EAAE,uBAAuB;IAC9C,gBAAgB,EAAE,kBAAkB;IACpC,sBAAsB,EAAE,wBAAwB;IAChD,wBAAwB,EAAE,0BAA0B;IACpD,uBAAuB,EAAE,yBAAyB;IAClD,uBAAuB,EAAE,yBAAyB;IAClD,yBAAyB,EAAE,2BAA2B;IACtD,wBAAwB,EAAE,0BAA0B;CAC5C,CAAC;AAIX,MAAM,UAAU,YAAY,CAC1B,IAAgC,EAChC,KAAa,EACb,KAA+B;IAE/B,MAAM,IAAI,GAA4B,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IACtD,IAAI,KAAK,EAAE,CAAC;QACV,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3C,IAAI,CAAC,KAAK,SAAS;gBAAE,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,UAAU,CACxB,IAAgC,EAChC,KAAa,EACb,KAA+B;IAE/B,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC;QACnE,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC"}

package/dist/parse-component-ast.d.ts

@@ -0,0 +1,112 @@
+import * as ts from 'typescript';
+/** Structured component reference documentation (CEM-style fields where applicable). */
+export type ComponentDocumentation = {
+    schemaVersion: 1;
+    /** Whether docs came from dist/custom-elements.json (CEM) or TypeScript AST */
+    dataSource?: 'cem' | 'ast';
+    /** Folder / export name, e.g. sky-button */
+    name: string;
+    /** Custom element tag from @customElement */
+    tagName: string;
+    npmImport?: string;
+    sourceFile: string;
+    className?: string;
+    /** @element */
+    element?: string;
+    /** @summary */
+    summary?: string;
+    /** @status */
+    status?: string;
+    /** @since */
+    since?: string;
+    /** @documentation URL */
+    documentation?: string;
+    slots: {
+        name: string;
+        description?: string;
+    }[];
+    properties: {
+        name: string;
+        type?: string;
+        description?: string;
+    }[];
+    cssParts: {
+        name: string;
+        description?: string;
+    }[];
+    events: {
+        name: string;
+        type?: string;
+        description?: string;
+    }[];
+    methods: {
+        name: string;
+        description?: string;
+        params: {
+            name: string;
+            type?: string;
+            optional?: boolean;
+            description?: string;
+        }[];
+        returns?: {
+            type?: string;
+            description?: string;
+        };
+    }[];
+    /** Named TS types referenced by extracted API types (flattened where possible) */
+    typeDefinitions?: Array<{
+        name: string;
+        kind: 'typeAlias' | 'interface';
+        definition: string;
+    }>;
+    /** @example bodies (trimmed) */
+    examples: {
+        source: string;
+    }[];
+    /** Tags we do not map to first-class fields */
+    miscTags: {
+        tag: string;
+        text: string;
+    }[];
+    /** Leading trivia before class (JSDoc + decorators) for debugging */
+    rawLeadTrivia?: string;
+};
+/**
+ * Prefer the better human description when both CEM and JSDoc supply text.
+ * CEM summaries are often terse; JSDoc next to `@property` / `@event` is usually richer—use length + tie-break to AST.
+ */
+export declare function pickRicherDescription(cemDesc: string | undefined, astDesc: string | undefined): string | undefined;
+/** Prefer the more specific / documented type (e.g. `CustomEvent<Foo>` over `Event` or empty). */
+export declare function pickRicherPropertyOrEventType(a: string | undefined, b: string | undefined): string | undefined;
+/**
+ * When CEM is the primary source, it often omits or weakly types `events` / `properties`,
+ * or carries shorter descriptions than JSDoc.
+ * Merge with the AST (JSDoc) list: union by `name`, richer type via {@link pickRicherPropertyOrEventType},
+ * richer description via {@link pickRicherDescription}, keep CEM order then append AST-only.
+ */
+export declare function mergeCemWithAstEventLists(cem: ComponentDocumentation['events'], ast: ComponentDocumentation['events']): ComponentDocumentation['events'];
+export declare function mergeCemWithAstPropertyLists(cem: ComponentDocumentation['properties'], ast: ComponentDocumentation['properties']): ComponentDocumentation['properties'];
+type NameDesc = {
+    name: string;
+    description?: string;
+};
+/** Merge slots or cssParts: union by `name`, enrich descriptions (same rules as props/events). */
+export declare function mergeCemWithAstSlotLikeLists(cem: NameDesc[], ast: NameDesc[]): NameDesc[];
+export declare function collectNamedTypeDefinitions(sf: ts.SourceFile, doc: ComponentDocumentation): ComponentDocumentation['typeDefinitions'];
+/**
+ * Parse a Lit core component `.ts` file and return structured documentation from JSDoc + `@customElement`.
+ */
+export declare function parseLitComponentDocumentation(sourceFilePath: string, sourceText: string, componentFolderName: string, npmImport?: string, options?: {
+    maxCharsPerExample?: number;
+}): {
+    ok: true;
+    doc: ComponentDocumentation;
+    truncated: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+/** Lightweight summary for search (parses full file; reuse parseLitComponentDocumentation). */
+export declare function parseSummaryOnly(sourceFilePath: string, sourceText: string, componentFolderName: string): string | null;
+export {};
+//# sourceMappingURL=parse-component-ast.d.ts.map

package/dist/parse-component-ast.d.ts.map

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