@totemsdk/mcp-server 0.4.0 → 0.5.1

package/dist/composition.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Dependency-aware composition planning and application scaffolding.
+ *
+ * The planner considers the entire indexed catalogue but selects only a
+ * justified closure. It preserves declaration provenance and never upgrades a
+ * package's maturity from a successful plan or scaffold.
+ */
+import type { DependencyEdge, SdkIndex } from './types.js';
+import { type WorkflowPlan } from './workflow.js';
+export type AppRuntime = 'node-cjs' | 'node-esm' | 'bare' | 'browser' | 'unknown';
+export interface PlanCompositionInput {
+    brief?: string;
+    runtime?: AppRuntime;
+    requiredPackages?: string[];
+    suggestedPackages?: string[];
+    optionalPackages?: string[];
+    excludedPackages?: string[];
+    requiredCapabilities?: string[];
+}
+export type Disposition = 'direct' | 'transitive' | 'enabled-optional' | 'alternative' | 'excluded' | 'unresolved';
+export interface PackageDisposition {
+    name: string;
+    version?: string;
+    maturity?: string;
+    disposition: Disposition;
+    reasons: string[];
+    dependencyPath?: string[];
+}
+export interface CompositionPlan {
+    brief?: string;
+    runtime: AppRuntime;
+    directDependencies: string[];
+    transitiveDependencies: string[];
+    enabledOptional: string[];
+    excluded: string[];
+    unresolved: string[];
+    dispositions: PackageDisposition[];
+    edges: DependencyEdge[];
+    capabilityMap: Record<string, {
+        selected: string[];
+        candidates: string[];
+        unresolved: boolean;
+    }>;
+    briefMatches: string[];
+    maturity: Record<string, string>;
+    installOrder: string[];
+    conflicts: Array<{
+        package: string;
+        reason: string;
+    }>;
+    hostPorts: string[];
+    workflow: WorkflowPlan;
+    fixtures: string[];
+    acceptance: string[];
+    warnings: string[];
+}
+export declare function planComposition(input: PlanCompositionInput, index: SdkIndex): CompositionPlan;
+export interface ScaffoldAppInput {
+    appName?: string;
+    runtime?: 'node-cjs' | 'node-esm';
+    plan: CompositionPlan;
+}
+export interface ScaffoldAppResult {
+    files: Array<{
+        path: string;
+        content: string;
+    }>;
+    dependencies: Record<string, string>;
+    install: string[];
+    generationManifest: {
+        runtime: string;
+        directDependencies: string[];
+        maturity: Record<string, string>;
+        warnings: string[];
+    };
+}
+export declare function scaffoldApp(input: ScaffoldAppInput, index: SdkIndex): ScaffoldAppResult;

package/dist/composition.js

@@ -0,0 +1,375 @@
+"use strict";
+/**
+ * Dependency-aware composition planning and application scaffolding.
+ *
+ * The planner considers the entire indexed catalogue but selects only a
+ * justified closure. It preserves declaration provenance and never upgrades a
+ * package's maturity from a successful plan or scaffold.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planComposition = planComposition;
+exports.scaffoldApp = scaffoldApp;
+const workflow_js_1 = require("./workflow.js");
+const RUNTIME_KINDS = ['runtime', 'peer'];
+function names(input) {
+    return Array.isArray(input) ? input.filter((v) => typeof v === 'string' && v.length > 0) : [];
+}
+function capabilityMatches(index, token) {
+    const terms = token.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+    return Object.values(index.packages)
+        .map((pkg) => {
+        const haystack = [
+            pkg.name, pkg.description, ...(pkg.keywords ?? []),
+            ...pkg.exports.functions, ...pkg.exports.types, ...pkg.exports.classes,
+            ...pkg.exports.interfaces, ...pkg.exports.consts,
+        ].join(' ').toLowerCase();
+        return { name: pkg.name, score: terms.filter((term) => haystack.includes(term)).length };
+    })
+        .filter((entry) => entry.score > 0)
+        .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
+        .map((entry) => entry.name);
+}
+function installOrder(selected, index) {
+    const visited = new Set();
+    const visiting = new Set();
+    const order = [];
+    const visit = (name) => {
+        if (visited.has(name) || visiting.has(name))
+            return;
+        visiting.add(name);
+        const pkg = index.packages[name];
+        for (const kind of RUNTIME_KINDS) {
+            for (const dep of Object.keys(pkg?.dependencyGroups?.[kind] ?? {})) {
+                if (selected.has(dep))
+                    visit(dep);
+            }
+        }
+        visiting.delete(name);
+        visited.add(name);
+        order.push(name);
+    };
+    for (const name of [...selected].sort())
+        visit(name);
+    return order;
+}
+function planComposition(input, index) {
+    const runtime = input.runtime ?? 'unknown';
+    const required = names(input.requiredPackages);
+    const suggested = names(input.suggestedPackages);
+    const optional = names(input.optionalPackages);
+    const excluded = new Set(names(input.excludedPackages));
+    const unresolved = [...new Set([...required, ...suggested, ...optional])]
+        .filter((name) => !index.packages[name] && !excluded.has(name))
+        .sort();
+    const requested = [...new Set([...required, ...suggested])]
+        .filter((name) => index.packages[name] && !excluded.has(name));
+    const direct = new Set(requested);
+    const transitive = new Set();
+    const enabledOptional = new Set();
+    const edges = new Map();
+    const dependencyPath = new Map();
+    const addEdge = (from, to, kind, range) => {
+        edges.set(`${from}\u0000${to}\u0000${kind}`, { from, to, kind, range });
+    };
+    const queue = [...direct].sort();
+    while (queue.length > 0) {
+        const name = queue.shift();
+        const pkg = index.packages[name];
+        for (const kind of RUNTIME_KINDS) {
+            for (const [dep, range] of Object.entries(pkg?.dependencyGroups?.[kind] ?? {})) {
+                if (!index.packages[dep])
+                    continue;
+                addEdge(name, dep, kind, String(range));
+                if (direct.has(dep) || transitive.has(dep))
+                    continue;
+                transitive.add(dep);
+                dependencyPath.set(dep, [...(dependencyPath.get(name) ?? [name]), dep]);
+                queue.push(dep);
+            }
+        }
+    }
+    for (const name of optional) {
+        if (!index.packages[name] || excluded.has(name))
+            continue;
+        enabledOptional.add(name);
+        for (const kind of RUNTIME_KINDS) {
+            for (const [dep, range] of Object.entries(index.packages[name]?.dependencyGroups?.[kind] ?? {})) {
+                addEdge(name, dep, kind, String(range));
+            }
+        }
+    }
+    const selected = new Set([...direct, ...transitive, ...enabledOptional]);
+    const capabilityMap = {};
+    const alternatives = new Set();
+    const briefMatches = input.brief ? capabilityMatches(index, input.brief).slice(0, 20) : [];
+    for (const name of briefMatches)
+        if (!selected.has(name))
+            alternatives.add(name);
+    for (const capability of names(input.requiredCapabilities)) {
+        const candidates = capabilityMatches(index, capability);
+        capabilityMap[capability] = {
+            selected: candidates.filter((name) => selected.has(name)),
+            candidates: candidates.slice(0, 10),
+            unresolved: candidates.length === 0,
+        };
+        for (const name of candidates)
+            if (!selected.has(name))
+                alternatives.add(name);
+    }
+    const dispositions = Object.values(index.packages)
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((pkg) => {
+        const base = {
+            name: pkg.name, version: pkg.version,
+            ...(pkg.maturity ? { maturity: pkg.maturity } : {}),
+        };
+        if (unresolved.includes(pkg.name)) {
+            return { ...base, disposition: 'unresolved', reasons: ['requested but not present in the selected catalogue'] };
+        }
+        if (excluded.has(pkg.name)) {
+            return { ...base, disposition: 'excluded', reasons: ['explicitly excluded by the brief'] };
+        }
+        if (direct.has(pkg.name)) {
+            return { ...base, disposition: 'direct', reasons: ['required or suggested by the brief'] };
+        }
+        if (transitive.has(pkg.name)) {
+            return {
+                ...base, disposition: 'transitive',
+                reasons: ['required by a selected package'],
+                ...(dependencyPath.has(pkg.name) ? { dependencyPath: dependencyPath.get(pkg.name) } : {}),
+            };
+        }
+        if (enabledOptional.has(pkg.name)) {
+            return { ...base, disposition: 'enabled-optional', reasons: ['optional integration enabled by the brief'] };
+        }
+        if (alternatives.has(pkg.name)) {
+            return { ...base, disposition: 'alternative', reasons: ['matched a required capability but not selected'] };
+        }
+        return { ...base, disposition: 'excluded', reasons: ['not selected by this composition'] };
+    });
+    const warnings = [];
+    if (direct.size === 0 && input.brief) {
+        warnings.push('No direct packages were selected; inspect briefMatches and choose a composition.');
+    }
+    if (briefMatches.length === 0 && input.brief) {
+        warnings.push('No package metadata matched the brief; no recipe is assumed.');
+    }
+    const unresolvedCapabilities = Object.entries(capabilityMap)
+        .filter(([, value]) => value.unresolved)
+        .map(([capability]) => capability);
+    if (unresolvedCapabilities.length > 0) {
+        warnings.push(`No package provides capability: ${unresolvedCapabilities.join(', ')}`);
+    }
+    if (runtime === 'browser' || runtime === 'unknown') {
+        warnings.push(`Runtime '${runtime}' support is not verified for this composition.`);
+    }
+    const selectedMissingMaturity = [...selected].filter((name) => !index.packages[name]?.maturity);
+    if (selectedMissingMaturity.length > 0) {
+        warnings.push(`Maturity unknown for: ${selectedMissingMaturity.sort().join(', ')}`);
+    }
+    const workflow = (0, workflow_js_1.buildWorkflow)({
+        directDependencies: [...direct].sort(),
+        maturity: Object.fromEntries([...selected].sort().map((name) => [
+            name, index.packages[name]?.maturity ?? 'unknown',
+        ])),
+        requiredCapabilities: names(input.requiredCapabilities),
+        index,
+    });
+    if (workflow.unresolved.length > 0) {
+        warnings.push(`No verified workflow adapter for: ${workflow.unresolved.sort().join(', ')}`);
+    }
+    return {
+        ...(input.brief ? { brief: input.brief } : {}),
+        runtime,
+        directDependencies: [...direct].sort(),
+        transitiveDependencies: [...transitive].sort(),
+        enabledOptional: [...enabledOptional].sort(),
+        excluded: [...excluded].sort(),
+        unresolved,
+        dispositions,
+        edges: [...edges.values()].sort((a, b) => `${a.from}:${a.to}:${a.kind}`.localeCompare(`${b.from}:${b.to}:${b.kind}`)),
+        capabilityMap,
+        briefMatches,
+        maturity: Object.fromEntries([...selected].sort().map((name) => [
+            name, index.packages[name]?.maturity ?? 'unknown',
+        ])),
+        installOrder: installOrder(selected, index),
+        conflicts: [],
+        hostPorts: workflow.hostPorts,
+        workflow,
+        fixtures: workflow.fixtures,
+        acceptance: workflow.acceptance,
+        warnings,
+    };
+}
+function scaffoldApp(input, index) {
+    const runtime = input.runtime ?? 'node-esm';
+    const appName = (input.appName ?? 'totem-app').toLowerCase().replace(/[^a-z0-9-]+/g, '-');
+    const dependencies = {};
+    for (const name of input.plan.directDependencies) {
+        const pkg = index.packages[name];
+        if (pkg)
+            dependencies[name] = pkg.version;
+    }
+    const codeSteps = input.plan.workflow.steps.filter((step) => step.kind === 'code');
+    const functions = codeSteps.map((step, index) => {
+        const adapter = (0, workflow_js_1.getWorkflowAdapter)(step.package);
+        if (!adapter)
+            throw new Error(`Missing workflow adapter for ${step.package}`);
+        return {
+            step,
+            name: `step${index + 1}`,
+            imports: adapter.imports,
+            body: adapter.body,
+        };
+    });
+    if (codeSteps.length > 0) {
+        for (const runtimePkg of ['@totemsdk/core', '@totemsdk/core-wasm']) {
+            if (index.packages[runtimePkg])
+                dependencies[runtimePkg] = index.packages[runtimePkg].version;
+        }
+    }
+    const moduleType = runtime === 'node-esm' ? 'module' : 'commonjs';
+    const files = [];
+    files.push({
+        path: 'package.json',
+        content: JSON.stringify({
+            name: appName,
+            private: true,
+            type: moduleType,
+            scripts: {
+                build: 'tsc -p tsconfig.json',
+                start: runtime === 'node-esm' ? 'node dist/index.js' : 'node dist/index.js',
+                test: 'npm run build && node --test test/*.test.mjs',
+            },
+            dependencies,
+            devDependencies: { typescript: '^5.9.3', '@types/node': '^20.0.0' },
+        }, null, 2) + '\n',
+    });
+    files.push({
+        path: 'tsconfig.json',
+        content: JSON.stringify({
+            compilerOptions: {
+                target: 'ES2022',
+                module: runtime === 'node-esm' ? 'NodeNext' : 'CommonJS',
+                moduleResolution: runtime === 'node-esm' ? 'NodeNext' : 'Node',
+                outDir: 'dist',
+                rootDir: 'src',
+                strict: true,
+                esModuleInterop: true,
+                skipLibCheck: true,
+            },
+            include: ['src/**/*.ts'],
+        }, null, 2) + '\n',
+    });
+    const stepFunctions = functions.flatMap(({ step, name, imports, body }) => [
+        `async function ${name}(): Promise<string> {`,
+        ...imports.map((line) => `  ${line}`),
+        ...body.map((line) => `  ${line}`),
+        '}',
+        '',
+    ]);
+    const runners = functions.map(({ step, name }) => `  '${step.id}': ${name},`).join('\n');
+    files.push({
+        path: 'src/workflow.ts',
+        content: `export const workflow = ${JSON.stringify(input.plan.workflow, null, 2)} as const;\n`,
+    });
+    const bootstrap = runtime === 'node-esm' && codeSteps.length > 0
+        ? [
+            "import { initSync } from '@totemsdk/core';",
+            "import { readFileSync } from 'node:fs';",
+            "import { fileURLToPath } from 'node:url';",
+            '',
+            "const wasmModuleUrl = (import.meta as ImportMeta & { resolve: (id: string) => string }).resolve('@totemsdk/core-wasm/web');",
+            "const wasmPath = fileURLToPath(new URL('totemsdk_core_wasm_bg.wasm', wasmModuleUrl));",
+            '(initSync as (options: { module: WebAssembly.Module }) => void)({ module: new WebAssembly.Module(readFileSync(wasmPath)) });',
+            '',
+        ]
+        : [];
+    files.push({
+        path: 'src/index.ts',
+        content: [
+            ...bootstrap,
+            "import { workflow } from './workflow.js';",
+            '',
+            `export const appName = '${appName}';`,
+            'export { workflow };',
+            '',
+            ...stepFunctions,
+            'const runners: Record<string, () => Promise<string>> = {',
+            runners,
+            '};',
+            '',
+            'export interface WorkflowResult {',
+            '  step: string;',
+            "  status: 'ok' | 'host-port' | 'unresolved';",
+            '  result?: string;',
+            '  detail?: string;',
+            '}',
+            '',
+            'export async function run(): Promise<WorkflowResult[]> {',
+            '  const results: WorkflowResult[] = [];',
+            '  for (const step of workflow.steps) {',
+            '    const runner = runners[step.id];',
+            '    if (runner) {',
+            "      results.push({ step: step.id, status: 'ok', result: await runner() });",
+            '    } else {',
+            "      results.push({ step: step.id, status: step.kind === 'host-port' ? 'host-port' : 'unresolved', detail: step.contract });",
+            '    }',
+            '  }',
+            '  return results;',
+            '}',
+            '',
+            'if (process.argv[1]?.endsWith("index.js") || process.argv[1]?.endsWith("index.cjs")) {',
+            '  run().then((results) => console.log(JSON.stringify(results, null, 2))).catch((error) => {',
+            '    console.error(error);',
+            '    process.exitCode = 1;',
+            '  });',
+            '}',
+            '',
+        ].join('\n'),
+    });
+    files.push({
+        path: 'src/integrations.ts',
+        content: [
+            '// Generated integration matrix. Unknown capabilities remain explicit.',
+            `export const integrations = ${JSON.stringify(Object.fromEntries(input.plan.directDependencies.map((name) => [name, {
+                    maturity: input.plan.maturity[name] ?? 'unknown',
+                    status: 'selected',
+                }])), null, 2)} as const;`,
+            '',
+            `export const limitations = ${JSON.stringify(input.plan.warnings, null, 2)} as const;`,
+            '',
+        ].join('\n'),
+    });
+    files.push({
+        path: 'test/workflow.test.mjs',
+        content: [
+            "import test from 'node:test';",
+            "import assert from 'node:assert/strict';",
+            "import { run, workflow } from '../dist/index.js';",
+            '',
+            "test('generated workflow executes every declared step', async () => {",
+            '  const results = await run();',
+            '  assert.equal(results.length, workflow.steps.length);',
+            "  assert.ok(results.every((entry) => entry.status === 'ok' || entry.status === 'host-port' || entry.status === 'unresolved'));",
+            '});',
+            '',
+        ].join('\n'),
+    });
+    files.push({
+        path: 'README.md',
+        content: `# ${appName}\n\nGenerated by @totemsdk/mcp-server.\n\nRuntime: ${runtime}\n\n## Install\n\n\`\`\`bash\nnpm install\nnpm run build\nnpm test\n\`\`\`\n\n## Maturity\n\n${Object.entries(input.plan.maturity).map(([name, maturity]) => `- ${name}: ${maturity}`).join('\n')}\n`,
+    });
+    return {
+        files,
+        dependencies,
+        install: ['npm install', 'npm run build', 'npm test'],
+        generationManifest: {
+            runtime,
+            directDependencies: input.plan.directDependencies,
+            maturity: input.plan.maturity,
+            warnings: input.plan.warnings,
+        },
+    };
+}

package/dist/contracts.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Bounded contract inspection by package, export subpath and symbol.
+ *
+ * Contract metadata comes from the selected index; implementation source is
+ * never implied. A subpath is verified against package.json exports, while
+ * symbols remain package-scoped because the index does not yet map each symbol
+ * to its originating subpath.
+ */
+import type { SdkIndex, ToolResponse } from './types.js';
+export interface InspectContractInput {
+    package?: string;
+    subpath?: string;
+    symbol?: string;
+    offset?: number;
+    limit?: number;
+    includeDocs?: boolean;
+}
+export declare function inspectContract(args: InspectContractInput, index: SdkIndex): ToolResponse;

package/dist/contracts.js

@@ -0,0 +1,108 @@
+"use strict";
+/**
+ * Bounded contract inspection by package, export subpath and symbol.
+ *
+ * Contract metadata comes from the selected index; implementation source is
+ * never implied. A subpath is verified against package.json exports, while
+ * symbols remain package-scoped because the index does not yet map each symbol
+ * to its originating subpath.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inspectContract = inspectContract;
+function hasExportPath(exportsMap, subpath) {
+    if (!exportsMap)
+        return subpath === '.';
+    return exportsMap[subpath] !== undefined;
+}
+function bounded(value, fallback, min, max) {
+    const number = typeof value === 'number' && Number.isFinite(value) ? Math.floor(value) : fallback;
+    return Math.min(max, Math.max(min, number));
+}
+function inspectContract(args, index) {
+    const pkgName = args.package;
+    if (!pkgName) {
+        return { content: [{ type: 'text', text: JSON.stringify({
+                        ok: false, code: 'package-required', message: 'package is required',
+                    }, null, 2) }], isError: true };
+    }
+    const pkg = index.packages[pkgName];
+    if (!pkg) {
+        return { content: [{ type: 'text', text: JSON.stringify({
+                        ok: false, code: 'package-not-found', message: `Package '${pkgName}' is not in the selected SDK index`,
+                    }, null, 2) }], isError: true };
+    }
+    const subpath = args.subpath ?? '.';
+    const subpathExists = hasExportPath(pkg.exportsMap, subpath);
+    if (!subpathExists) {
+        return { content: [{ type: 'text', text: JSON.stringify({
+                        ok: false, code: 'subpath-not-found', package: pkg.name, subpath,
+                        availableSubpaths: Object.keys(pkg.exportsMap ?? { '.': null }),
+                        message: `'${pkg.name}' does not export subpath '${subpath}'`,
+                    }, null, 2) }], isError: true };
+    }
+    const allSymbols = Object.entries(pkg.symbols ?? {}).sort(([a], [b]) => a.localeCompare(b));
+    if (args.symbol) {
+        const symbol = allSymbols.find(([name]) => name === args.symbol);
+        if (!symbol) {
+            const suggestions = allSymbols
+                .filter(([name]) => name.toLowerCase().includes(args.symbol.toLowerCase()))
+                .slice(0, 10)
+                .map(([name]) => name);
+            return { content: [{ type: 'text', text: JSON.stringify({
+                            ok: false, code: 'symbol-not-found', package: pkg.name, symbol: args.symbol,
+                            suggestions,
+                            message: `'${pkg.name}' does not export symbol '${args.symbol}'`,
+                        }, null, 2) }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify({
+                        ok: true,
+                        contentKind: 'contract',
+                        package: pkg.name,
+                        version: pkg.version,
+                        domain: pkg.domain,
+                        ...(pkg.maturity ? { maturity: pkg.maturity } : {}),
+                        origin: index.source ?? 'unknown',
+                        sourceRevision: index.sourceRevision ?? null,
+                        subpath,
+                        subpathScope: 'package',
+                        symbol: symbol[0],
+                        declaration: symbol[1],
+                        limitations: ['Symbol-to-subpath mapping is package-scoped; verify the import path against package exports.'],
+                    }, null, 2) }] };
+    }
+    const offset = bounded(args.offset, 0, 0, allSymbols.length);
+    const limit = bounded(args.limit, 25, 1, 100);
+    const page = allSymbols.slice(offset, offset + limit);
+    const includeDocs = args.includeDocs !== false;
+    const symbols = page.map(([name, meta]) => {
+        const entry = { name, kind: meta.kind };
+        if (meta.signature)
+            entry.signature = meta.signature;
+        if (meta.deprecated)
+            entry.deprecated = true;
+        if (includeDocs && meta.doc)
+            entry.doc = meta.doc;
+        return entry;
+    });
+    return { content: [{ type: 'text', text: JSON.stringify({
+                    ok: true,
+                    contentKind: 'contract',
+                    package: pkg.name,
+                    version: pkg.version,
+                    domain: pkg.domain,
+                    ...(pkg.maturity ? { maturity: pkg.maturity } : {}),
+                    origin: index.source ?? 'unknown',
+                    sourceRevision: index.sourceRevision ?? null,
+                    subpath,
+                    subpathScope: 'package',
+                    totalSymbols: allSymbols.length,
+                    offset,
+                    limit,
+                    nextOffset: offset + symbols.length < allSymbols.length ? offset + symbols.length : null,
+                    symbols,
+                    limitations: [
+                        'Symbols are package-scoped; the index does not yet map each symbol to its export subpath.',
+                        'Contract metadata is not implementation source.',
+                    ],
+                }, null, 2) }] };
+}