@totemsdk/mcp-server 0.3.0 → 0.5.0

package/dist/indexer.js

@@ -72,6 +72,24 @@ function detectRepoRoot() {
     }
     return null;
 }
+/** Read the checked-out Git revision without spawning a process. */
+function readGitRevision(root) {
+    try {
+        const git = path.join(root, '.git');
+        let head = fs.readFileSync(path.join(git, 'HEAD'), 'utf-8').trim();
+        if (head.startsWith('ref: ')) {
+            const ref = head.slice(5).trim();
+            const refPath = path.join(git, ref);
+            head = fs.existsSync(refPath)
+                ? fs.readFileSync(refPath, 'utf-8').trim()
+                : '';
+        }
+        return /^[0-9a-f]{40,64}$/.test(head) ? head : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 function loadRepoData(root) {
     const topPkgDir = path.join(root, 'packages');
     const manifest = new Map();
@@ -97,13 +115,29 @@ function loadRepoData(root) {
     catch {
         // Optional artifact — fall back to the regex scan.
     }
-    return { topPkgDir, manifest, ast };
+    const maturity = new Map();
+    try {
+        const gates = JSON.parse(fs.readFileSync(path.join(root, 'scripts', 'workspace-gates.config.json'), 'utf-8'));
+        for (const [dir, meta] of Object.entries(gates.packages ?? {})) {
+            if (!meta?.maturity)
+                continue;
+            try {
+                const pj = JSON.parse(fs.readFileSync(path.join(root, dir, 'package.json'), 'utf-8'));
+                if (pj.name)
+                    maturity.set(pj.name, meta.maturity);
+            }
+            catch { /* unreadable package */ }
+        }
+    }
+    catch { /* optional */ }
+    return { topPkgDir, manifest, maturity, ast };
 }
 function loadBundledIndex() {
     try {
         const idx = JSON.parse(fs.readFileSync(BUNDLED_INDEX_PATH, 'utf-8'));
-        if (idx && typeof idx === 'object' && idx.packages && typeof idx.packages === 'object')
-            return idx;
+        if (idx && typeof idx === 'object' && idx.packages && typeof idx.packages === 'object') {
+            return { ...idx, schemaVersion: idx.schemaVersion ?? 2, source: idx.source ?? 'bundled' };
+        }
         return null;
     }
     catch {
@@ -310,10 +344,24 @@ function collectExports(file, symbols, visited) {
             const braceMatch = block.match(/\{([^}]+)\}/);
             if (braceMatch) {
                 for (const part of braceMatch[1].split(',')) {
-                    const name = part.trim().split(/\s+as\s+/).pop()?.trim() || '';
-                    if (!name)
+                    let clause = part.trim();
+                    if (!clause)
                         continue;
-                    const kind = isType || /^[A-Z]/.test(name) ? 'type' : 'function';
+                    // Inline type modifiers: `export { type Foo }` / `export { type Foo as Bar }`.
+                    // Strip the leading `type` keyword before resolving the exposed name,
+                    // otherwise the symbol is recorded literally as "type Foo".
+                    let inlineType = false;
+                    const typeKw = clause.match(/^type\s+([\s\S]+)$/);
+                    if (typeKw) {
+                        inlineType = true;
+                        clause = typeKw[1].trim();
+                    }
+                    const name = clause.split(/\s+as\s+/).pop()?.trim() || '';
+                    // Reject anything that isn't a plain identifier (guards against
+                    // malformed fragments leaking in as fake symbols).
+                    if (!/^[A-Za-z_$][\w$]*$/.test(name))
+                        continue;
+                    const kind = isType || inlineType || /^[A-Z]/.test(name) ? 'type' : 'function';
                     setSymbol(symbols, name, { kind });
                 }
             }
@@ -348,15 +396,18 @@ function mergeAst(symbols, ast) {
 }
 /** Scan a monorepo root into an `SdkIndex`. */
 function buildFromMonorepo(root, now = Date.now()) {
-    const { topPkgDir, manifest: MANIFEST, ast: AST } = loadRepoData(root);
+    const { topPkgDir, manifest: MANIFEST, maturity: MATURITY, ast: AST } = loadRepoData(root);
     const packages = {};
     const symbolIndex = {};
     const domainMap = {};
+    const manifestNames = new Set(MANIFEST.keys());
+    const discoveredNames = new Set();
     for (const dir of findPackageDirs(topPkgDir)) {
         const pkg = readPackageJson(dir);
         if (!pkg || !pkg.name)
             continue;
         const manifest = MANIFEST.get(pkg.name);
+        discoveredNames.add(pkg.name);
         if (MANIFEST.size > 0 && !manifest)
             continue;
         const dirName = path.basename(dir);
@@ -372,12 +423,20 @@ function buildFromMonorepo(root, now = Date.now()) {
             ...(Array.isArray(pkg.keywords) ? { keywords: pkg.keywords } : {}),
             dependencies: Object.keys(pkg.dependencies || {}),
             devDependencies: Object.keys(pkg.devDependencies || {}),
+            dependencyGroups: {
+                runtime: { ...(pkg.dependencies || {}) },
+                peer: { ...(pkg.peerDependencies || {}) },
+                optional: { ...(pkg.optionalDependencies || {}) },
+                dev: { ...(pkg.devDependencies || {}) },
+            },
+            ...(pkg.exports && typeof pkg.exports === 'object' ? { exportsMap: pkg.exports } : {}),
             hasRust: hasSubdir(dir, 'rust') || hasSubdir(dir, 'rust-toolchain'),
             hasGo: hasSubdir(dir, 'go'),
             hasTests: hasTestDir(dir),
             exports,
             symbols: Object.fromEntries(symbols),
             domain,
+            ...(MATURITY.get(pkg.name) ? { maturity: MATURITY.get(pkg.name) } : {}),
         };
         packages[pkg.name] = idx;
         if (!domainMap[domain])
@@ -393,7 +452,39 @@ function buildFromMonorepo(root, now = Date.now()) {
             });
         }
     }
-    return { generatedAt: now, packages, symbolIndex, domainMap };
+    // Normalise workspace protocol ranges to the concrete workspace version so
+    // graph output is actionable outside pnpm. External ranges are preserved.
+    for (const pkg of Object.values(packages)) {
+        for (const kind of ['runtime', 'peer', 'optional', 'dev']) {
+            const group = pkg.dependencyGroups?.[kind];
+            if (!group)
+                continue;
+            for (const [dep, range] of Object.entries(group)) {
+                if (String(range).startsWith('workspace:')) {
+                    const version = packages[dep]?.version;
+                    group[dep] = version ? `^${version}` : String(range);
+                }
+            }
+        }
+    }
+    const missingFromIndex = [...manifestNames].filter((name) => !packages[name]).sort();
+    const extraInIndex = [...discoveredNames].filter((name) => !manifestNames.has(name)).sort();
+    const sourceRevision = readGitRevision(root);
+    return {
+        schemaVersion: 2,
+        source: 'monorepo',
+        ...(sourceRevision ? { sourceRevision } : {}),
+        coverage: {
+            manifestCount: manifestNames.size,
+            discoveredCount: discoveredNames.size,
+            missingFromIndex,
+            extraInIndex,
+        },
+        generatedAt: now,
+        packages,
+        symbolIndex,
+        domainMap,
+    };
 }
 /**
  * Build the SDK index. Prefers a live monorepo scan; falls back to the bundled

package/dist/recipes.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Optional verified recipe accelerators. They are fixtures for the shared
+ * planner/scaffolder, not special-cased branches and not the taxonomy of
+ * supported applications.
+ */
+import type { PlanCompositionInput, CompositionPlan } from './composition.js';
+import type { SdkIndex } from './types.js';
+export interface RecipeDefinition {
+    id: string;
+    title: string;
+    boundary: string;
+    input: Omit<PlanCompositionInput, 'brief'>;
+}
+export declare const RECIPES: RecipeDefinition[];
+export declare function planRecipe(recipe: RecipeDefinition, index: SdkIndex): CompositionPlan;

package/dist/recipes.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * Optional verified recipe accelerators. They are fixtures for the shared
+ * planner/scaffolder, not special-cased branches and not the taxonomy of
+ * supported applications.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RECIPES = void 0;
+exports.planRecipe = planRecipe;
+const composition_js_1 = require("./composition.js");
+exports.RECIPES = [
+    {
+        id: 'digital-product-passport',
+        title: 'Digital Product Passport',
+        boundary: 'Passport assembles attested event evidence; generated summaries are not certified digital twins.',
+        input: {
+            runtime: 'node-esm',
+            requiredPackages: ['@totemsdk/edge-mqtt', '@totemsdk/core', '@totemsdk/proof', '@totemsdk/proofgraph'],
+            suggestedPackages: ['@totemsdk/manifest', '@totemsdk/identity', '@totemsdk/authority', '@totemsdk/intelligence', '@totemsdk/qvac', '@totemsdk/storage'],
+            requiredCapabilities: ['attested event evidence', 'manifest identity', 'proof graph', 'local AI summary'],
+        },
+    },
+    {
+        id: 'machinepay-edge',
+        title: 'MachinePay Edge Gateway',
+        boundary: 'The gateway executes only within a signed policy envelope; payment receipts do not certify the physical outcome.',
+        input: {
+            runtime: 'node-esm',
+            requiredPackages: ['@totemsdk/edge', '@totemsdk/edge-mqtt', '@totemsdk/omnia', '@totemsdk/agent-policy'],
+            suggestedPackages: ['@totemsdk/manifest', '@totemsdk/proofgraph', '@totemsdk/root-identity'],
+            requiredCapabilities: ['edge device runtime', 'mqtt transport', 'payment channel', 'agent policy'],
+        },
+    },
+];
+function planRecipe(recipe, index) {
+    return (0, composition_js_1.planComposition)({ ...recipe.input, brief: `${recipe.title}. ${recipe.boundary}` }, index);
+}

package/dist/resources.js

@@ -54,7 +54,7 @@ const PAPERS = [
     {
         uri: 'totemsdk://papers/yellow',
         name: 'Core Yellow Paper',
-        description: 'WOTS+ signatures, TreeKey hierarchy, MMR proofs, byte-exact serialization, lease/watermark coordination, Rust/WASM engine',
+        description: 'WOTS signatures, TreeKey hierarchy, MMR proofs, byte-exact serialization, lease/watermark coordination, Rust/WASM engine',
         file: 'TOTEM_CORE_YELLOW_PAPER.md',
     },
     {
@@ -108,7 +108,12 @@ function docMeta(file, fallbackName) {
         description = t.replace(/[*_`]/g, '').trim();
         break;
     }
-    return { name: name || fallbackName, description: description || name || fallbackName };
+    const clean = description || name || fallbackName;
+    // Cap at the first sentence / ~160 chars. Discovery must stay cheap: an
+    // unbounded first paragraph bloats every client's resource list.
+    const firstSentence = clean.split(/(?<=\.)\s/)[0];
+    const bounded = (firstSentence.length <= 160 ? firstSentence : clean.slice(0, 160)).trim();
+    return { name: name || fallbackName, description: bounded.length > 0 ? bounded : name || fallbackName };
 }
 /**
  * RFCs and audits are discovered from disk, so a new `docs/rfc/RFC-*.md` or
@@ -125,7 +130,14 @@ function discoverDocs() {
                 continue;
             const file = path.join('docs', 'rfc', f);
             const meta = docMeta(file, `RFC-${m[1]}`);
-            docs.push({ uri: `totemsdk://rfc/${m[1]}`, ...meta, file });
+            // Amendments share an RFC number with the original; give them a distinct
+            // URI (`totemsdk://rfc/007/amendment-a`) so a reader never retrieves an
+            // amendment when they asked for the base specification.
+            const amend = m[2].match(/^AMENDMENT-([A-Z])/i);
+            const uri = amend
+                ? `totemsdk://rfc/${m[1]}/amendment-${amend[1].toLowerCase()}`
+                : `totemsdk://rfc/${m[1]}`;
+            docs.push({ uri, ...meta, file });
         }
     }
     const auditDir = path.join(REPO_ROOT, 'docs', 'audits');
@@ -140,6 +152,19 @@ function discoverDocs() {
             docs.push({ uri: `totemsdk://audit/${slug}`, ...meta, file });
         }
     }
+    // Worked, runnable end-to-end scenarios (usually backed by a test under
+    // packages/sdk-tests). Discovered from disk like RFCs/audits.
+    const exampleDir = path.join(REPO_ROOT, 'docs', 'examples');
+    if (fs.existsSync(exampleDir)) {
+        for (const f of fs.readdirSync(exampleDir).sort()) {
+            if (!f.endsWith('.md'))
+                continue;
+            const slug = f.replace(/\.md$/, '');
+            const file = path.join('docs', 'examples', f);
+            const meta = docMeta(file, slug);
+            docs.push({ uri: `totemsdk://example/${slug}`, ...meta, file });
+        }
+    }
     return docs;
 }
 const DOCS = discoverDocs();
@@ -202,7 +227,7 @@ function resourceMimeType(uri) {
     const base = uri.split('#')[0];
     if (base === 'totemsdk://conventions' || base === 'totemsdk://templates')
         return 'text/markdown';
-    if (/^totemsdk:\/\/(papers|rfc|audit)\/[^/]+$/.test(base))
+    if (/^totemsdk:\/\/(papers|rfc|audit|example)\/[^/]+(\/[^/]+)?$/.test(base))
         return 'text/markdown';
     if (base === 'totemsdk://packages' || base === 'totemsdk://domain-map' || base === 'totemsdk://rfc')
         return 'application/json';
@@ -253,6 +278,17 @@ const CONVENTIONS = `# Totem SDK Conventions
 ## Async
 - Promise<T> everywhere, typed event emitters, no Observables
 - Action lifecycle: propose -> reserve -> execute -> confirm/fail/unknown`;
+function decodeResourceSegment(value) {
+    try {
+        const decoded = decodeURIComponent(value);
+        if (!decoded || decoded.includes('..') || decoded.includes('\\') || decoded.includes('\0'))
+            return null;
+        return decoded;
+    }
+    catch {
+        return null;
+    }
+}
 function handleResourceRead(uri, index) {
     if (uri === 'totemsdk://connect/methods')
         return JSON.stringify(connectMethods(), null, 2);
@@ -275,6 +311,16 @@ function handleResourceRead(uri, index) {
         }
         return content;
     }
+    if (uri === 'totemsdk://index') {
+        return JSON.stringify({
+            schemaVersion: index.schemaVersion ?? null,
+            source: index.source ?? 'unknown',
+            sourceRevision: index.sourceRevision ?? null,
+            generatedAt: index.generatedAt,
+            packageCount: Object.keys(index.packages).length,
+            coverage: index.coverage ?? null,
+        }, null, 2);
+    }
     if (uri === 'totemsdk://packages') {
         return JSON.stringify(Object.values(index.packages).map(p => ({
             name: p.name,
@@ -306,29 +352,61 @@ function handleResourceRead(uri, index) {
     }
     const pkgMatch = uri.match(/^totemsdk:\/\/packages\/([^/]+)$/);
     if (pkgMatch) {
-        const pkg = index.packages[pkgMatch[1]];
+        const name = decodeResourceSegment(pkgMatch[1]);
+        if (!name)
+            return null;
+        const pkg = index.packages[name];
         return pkg ? JSON.stringify(pkg, null, 2) : null;
     }
+    const pkgContractsMatch = uri.match(/^totemsdk:\/\/packages\/([^/]+)\/contracts$/);
+    if (pkgContractsMatch) {
+        const name = decodeResourceSegment(pkgContractsMatch[1]);
+        if (!name)
+            return null;
+        const pkg = index.packages[name];
+        if (!pkg)
+            return null;
+        return JSON.stringify({
+            contentKind: 'contract',
+            package: pkg.name,
+            version: pkg.version,
+            origin: index.source ?? 'unknown',
+            sourceRevision: index.sourceRevision ?? null,
+            symbols: pkg.symbols ?? {},
+        }, null, 2);
+    }
     const pkgExportsMatch = uri.match(/^totemsdk:\/\/packages\/([^/]+)\/exports$/);
     if (pkgExportsMatch) {
-        const pkg = index.packages[pkgExportsMatch[1]];
+        const name = decodeResourceSegment(pkgExportsMatch[1]);
+        if (!name)
+            return null;
+        const pkg = index.packages[name];
         return pkg ? JSON.stringify(pkg.exports, null, 2) : null;
     }
     const pkgDepsMatch = uri.match(/^totemsdk:\/\/packages\/([^/]+)\/dependencies$/);
     if (pkgDepsMatch) {
-        const pkg = index.packages[pkgDepsMatch[1]];
+        const name = decodeResourceSegment(pkgDepsMatch[1]);
+        if (!name)
+            return null;
+        const pkg = index.packages[name];
         if (!pkg)
             return null;
         return JSON.stringify({ dependencies: pkg.dependencies, devDependencies: pkg.devDependencies }, null, 2);
     }
     const domainMatch = uri.match(/^totemsdk:\/\/packages\/by-domain\/(.+)$/);
     if (domainMatch) {
-        const pkgs = index.domainMap[domainMatch[1]];
+        const domain = decodeResourceSegment(domainMatch[1]);
+        if (!domain)
+            return null;
+        const pkgs = index.domainMap[domain];
         return pkgs ? JSON.stringify(pkgs.map(n => index.packages[n]).filter(Boolean), null, 2) : null;
     }
     const symbolMatch = uri.match(/^totemsdk:\/\/symbol\/(.+)$/);
     if (symbolMatch) {
-        const entries = index.symbolIndex[symbolMatch[1]];
+        const symbol = decodeResourceSegment(symbolMatch[1]);
+        if (!symbol)
+            return null;
+        const entries = index.symbolIndex[symbol];
         return entries ? JSON.stringify(entries, null, 2) : null;
     }
     return null;
@@ -337,6 +415,7 @@ function listResources(index) {
     const resources = [
         { uri: 'totemsdk://packages', name: 'All Packages', description: `List of all ${Object.keys(index.packages).length} SDK packages with metadata` },
         { uri: 'totemsdk://templates', name: 'All KISSVM Templates', description: `All ${(0, template_catalog_js_1.getAllTemplates)().length} KISSVM script templates with import paths and descriptions` },
+        { uri: 'totemsdk://index', name: 'Index Provenance', description: 'Index schema, source revision, package count and coverage reconciliation' },
         { uri: 'totemsdk://conventions', name: 'Coding Conventions', description: 'Totem SDK coding conventions and patterns' },
         { uri: 'totemsdk://domain-map', name: 'Domain Map', description: 'Packages grouped by domain layer' },
         ...PAPERS.map(p => ({ uri: p.uri, name: p.name, description: p.description })),
@@ -366,11 +445,22 @@ function listResources(index) {
             name: `Dependencies: ${name}`,
             description: `Dependencies of ${name}`,
         });
+        resources.push({
+            uri: `totemsdk://packages/${encodeURIComponent(name)}/contracts`,
+            name: `Contracts: ${name}`,
+            description: `Exact exported contract metadata for ${name} (contentKind: contract)`,
+        });
     }
-    const topSymbols = Object.entries(index.symbolIndex)
-        .filter(([_, v]) => v.length <= 3)
-        .slice(0, 200);
-    for (const [symbol, entries] of topSymbols) {
+    // Symbol lookups are served by the `search-symbol` tool (query-driven), which
+    // is far cheaper than enumerating ~3.7k symbols as resources. Only surface a
+    // small set of the most unambiguous symbols (exported by exactly one package)
+    // so `totemsdk://symbol/{name}` remains discoverable without bloating
+    // discovery to hundreds of entries.
+    const uniqueSymbols = Object.entries(index.symbolIndex)
+        .filter(([_, v]) => v.length === 1)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .slice(0, 50);
+    for (const [symbol, entries] of uniqueSymbols) {
         resources.push({
             uri: `totemsdk://symbol/${symbol}`,
             name: `Symbol: ${symbol}`,