weavatrix 0.2.18 → 0.3.0

package/src/mcp/extension-api.mjs

@@ -0,0 +1,77 @@
+const EXTENSION_NAME = /^[a-z0-9][a-z0-9._-]{0,127}$/
+const TOOL_NAME = /^[a-z][a-z0-9_]{0,127}$/
+
+const asArray = (value, field) => {
+    if (value == null) return []
+    if (!Array.isArray(value)) throw new TypeError(`${field} must be an array`)
+    return value
+}
+
+const validateProfiles = (profiles = {}) => {
+    if (!profiles || typeof profiles !== 'object' || Array.isArray(profiles)) throw new TypeError('extension profiles must be an object')
+    const normalized = {}
+    for (const [name, capabilities] of Object.entries(profiles)) {
+        if (!EXTENSION_NAME.test(name)) throw new TypeError(`invalid extension profile name: ${name}`)
+        normalized[name] = asArray(capabilities, `profile ${name}`).map(String)
+    }
+    return Object.freeze(normalized)
+}
+
+const validateTools = (tools = []) => Object.freeze(asArray(tools, 'extension tools').map((tool) => {
+    if (!tool || typeof tool !== 'object') throw new TypeError('each extension tool must be an object')
+    if (!TOOL_NAME.test(String(tool.name || ''))) throw new TypeError(`invalid extension tool name: ${tool.name || '(missing)'}`)
+    if (!EXTENSION_NAME.test(String(tool.cap || ''))) throw new TypeError(`invalid extension tool capability: ${tool.cap || '(missing)'}`)
+    if (typeof tool.run !== 'function') throw new TypeError(`extension tool ${tool.name} must provide run()`)
+    return Object.freeze({...tool})
+}))
+
+const validateAuditProviders = (providers = []) => Object.freeze(asArray(providers, 'auditProviders').map((provider) => {
+    if (!provider || typeof provider !== 'object') throw new TypeError('each audit provider must be an object')
+    if (!EXTENSION_NAME.test(String(provider.id || ''))) throw new TypeError(`invalid audit provider id: ${provider.id || '(missing)'}`)
+    if (typeof provider.run !== 'function') throw new TypeError(`audit provider ${provider.id} must provide run()`)
+    if (provider.network !== undefined && provider.network !== 'none') throw new TypeError(`audit provider ${provider.id} must be local (network: "none")`)
+    return Object.freeze({...provider, network: 'none'})
+}))
+
+const validateSkills = (skills = []) => Object.freeze(asArray(skills, 'skills').map((skill) => {
+    if (!skill || typeof skill !== 'object') throw new TypeError('each extension skill must be an object')
+    if (!EXTENSION_NAME.test(String(skill.name || ''))) throw new TypeError(`invalid extension skill name: ${skill.name || '(missing)'}`)
+    if (!String(skill.path || '').trim()) throw new TypeError(`extension skill ${skill.name} must provide a package-relative path`)
+    return Object.freeze({...skill, name: String(skill.name), path: String(skill.path)})
+}))
+
+// Public composition contract for packages layered on top of the MIT core. Extensions may add
+// tools, local audit providers and packaged skills, but cannot replace core tools or profiles.
+export function defineWeavatrixExtension(spec) {
+    if (!spec || typeof spec !== 'object') throw new TypeError('extension definition must be an object')
+    const name = String(spec.name || '')
+    const version = String(spec.version || '')
+    if (!EXTENSION_NAME.test(name)) throw new TypeError(`invalid extension name: ${name || '(missing)'}`)
+    if (!version.trim()) throw new TypeError(`extension ${name} must provide a version`)
+    return Object.freeze({
+        name,
+        version,
+        tools: validateTools(spec.tools),
+        profiles: validateProfiles(spec.profiles),
+        auditProviders: validateAuditProviders(spec.auditProviders),
+        skills: validateSkills(spec.skills),
+    })
+}
+
+export function normalizeWeavatrixExtensions(extensions = []) {
+    const normalized = asArray(extensions, 'extensions').map((extension) => defineWeavatrixExtension(extension))
+    const names = new Set()
+    for (const extension of normalized) {
+        if (names.has(extension.name)) throw new TypeError(`duplicate extension name: ${extension.name}`)
+        names.add(extension.name)
+    }
+    return Object.freeze(normalized)
+}
+
+export const extensionRuntimeSummary = (extensions = []) => extensions.map((extension) => ({
+    name: extension.name,
+    version: extension.version,
+    tools: extension.tools.length,
+    auditProviders: extension.auditProviders.length,
+    skills: extension.skills.map((skill) => skill.name),
+}))

package/src/mcp/health/audit-format.mjs

@@ -52,7 +52,7 @@ export const auditFilter = (audit, args, findings = audit.findings, repoRoot = n
 
 const auditChecksLine = (audit) => {
     const check = (name, state) => `${name} ${state?.status || 'ERROR'}${state?.detail ? ` — ${state.detail}` : ''}`
-    return `Checks: ${check('OSV', audit.checks?.osv)}; ${check('malware', audit.checks?.malware)}. A NOT_CHECKED/PARTIAL/ERROR check is incomplete or unknown, never a clean zero.`
+    return `Checks: ${check('OSV', audit.checks?.osv)}; ${check('RustSec report', audit.checks?.rustsec)}; ${check('malware', audit.checks?.malware)}. A NOT_CHECKED/PARTIAL/ERROR check is incomplete or unknown, never a clean zero.`
 }
 
 const auditCapabilityLines = (audit) => {
@@ -74,6 +74,15 @@ const auditCapabilityLines = (audit) => {
     return lines
 }
 
+const auditExtensionLines = (audit) => {
+    const items = audit.extensionCapabilities || []
+    if (!items.length) return []
+    return [
+        'Extension analyzer matrix (status/completeness):',
+        ...items.map((item) => `  ${item.extension ? `${item.extension}/` : ''}${item.id}: ${item.status}/${item.completeness} — ${item.detail} (${item.findingCount} finding(s)).`),
+    ]
+}
+
 const auditDependencyCoverageLines = (deps) => {
     const ecosystems = Object.values(deps.ecosystems || {}).filter((item) => item?.present)
     const verification = Object.entries(deps.verificationCoverage || {})
@@ -138,6 +147,7 @@ export const formatOrdinaryAudit = (audit, args, findings = audit.findings, head
         auditDependencySummaryLine(audit, deps),
         ...auditDependencyCoverageLines(deps),
         ...auditCapabilityLines(audit),
+        ...auditExtensionLines(audit),
         `Scoped severity: critical ${sev.critical}, high ${sev.high}, medium ${sev.medium}, low ${sev.low}, info ${sev.info}. Scoped categories: unused ${bycat.unused}, structure ${bycat.structure}, vulnerability ${bycat.vulnerability}, malware ${bycat.malware}.`,
         pathScope.suppressed ? `Path policy: production-first; suppressed ${pathScope.suppressed} finding(s) whose evidence is entirely test/e2e/generated/mock/story/docs/benchmark/temp or explicitly excluded. Pass include_classified:true to include them.` : 'Path policy: production-first; no classified-only findings were suppressed.',
         `Repository-level ${auditChecksLine(audit)}`,

package/src/mcp/health/audit.mjs

@@ -1,5 +1,6 @@
 import {rawGraph, effectiveRawGraph} from '../graph-context.mjs'
 import {runInternalAudit} from '../../analysis/internal-audit.js'
+import {applyAuditExtensions} from '../../analysis/audit-extensions.js'
 import {classifyChangeImpact} from '../../analysis/change-classification.js'
 import {
   compareAuditDebt,
@@ -19,6 +20,11 @@ const {
   pathsFromClassification,
 } = await import(new URL(`./audit-format.mjs${auditFormatVersion}`, import.meta.url).href)
 
+const runAudit = async (repoRoot, graph, args, ctx, options = {}) => applyAuditExtensions(
+    await runInternalAudit(repoRoot, {graph, ...options}),
+    {providers: ctx.extensions?.auditProviders || [], repoRoot, graph, args},
+)
+
 async function runAuditWithBaseline(args, ctx, currentGraph) {
     const resolved = resolveGitCommit(ctx.repoRoot, args.base_ref)
     if (!resolved.ok) return toolResult(`Audit baseline unavailable: ${resolved.error}.`, {
@@ -27,10 +33,7 @@ async function runAuditWithBaseline(args, ctx, currentGraph) {
 
     let currentAudit
     try {
-        currentAudit = await runInternalAudit(ctx.repoRoot, {
-            graph: currentGraph,
-            skipMalwareScan: !args.include_malware_scan,
-        })
+        currentAudit = await runAudit(ctx.repoRoot, currentGraph, args, ctx, {skipMalwareScan: !args.include_malware_scan})
     } catch (error) {
         const reason = error instanceof Error ? error.message : String(error)
         return toolResult(`Audit failed while building the current graph: ${reason}`, {
@@ -86,7 +89,7 @@ async function runAuditWithBaseline(args, ctx, currentGraph) {
         if (currentMode !== 'full') graph = filterGraphForMode(graph, currentMode, {repoRoot: checkout})
         graph.graphBuildMode = currentMode
         graph.graphBuildScope = ''
-        return runInternalAudit(checkout, {graph, skipMalwareScan: true})
+        return runAudit(checkout, graph, args, ctx, {skipMalwareScan: true})
     })
     if (!baseline.ok || !baseline.value?.ok) {
         const reason = baseline.error || baseline.value?.error || 'baseline audit failed'
@@ -146,8 +149,8 @@ async function runAuditWithBaseline(args, ctx, currentGraph) {
 export async function tRunAudit(g, args, ctx) {
     if (!ctx.repoRoot) return 'Audit needs the repo root (not provided to this server).'
     if (args.base_ref) return runAuditWithBaseline(args, ctx, rawGraph(ctx))
-    const audit = await runInternalAudit(ctx.repoRoot, {
-        graph: effectiveRawGraph(ctx),
+    const graph = effectiveRawGraph(ctx)
+    const audit = await runAudit(ctx.repoRoot, graph, args, ctx, {
         skipMalwareScan: !args.include_malware_scan, // greps installed packages — slow, so opt-in
     })
     if (!audit.ok) return `Audit failed: ${audit.error}`

package/src/mcp/health/duplicates.mjs

@@ -66,7 +66,10 @@ export function tFindDuplicates(g, args, ctx) {
     const boilerplateNote = analysis.boilerplateSuppressed
         ? ` ${analysis.boilerplateSuppressed} all-router framework boilerplate group(s) were suppressed; pass include_boilerplate:true to inspect them.`
         : ''
-    if (!groups.length) return `No clones at ≥${simMin}% similarity / ≥${tokMin} tokens (${mode} mode). Try lowering the thresholds.${smallPolicy}${suppressionNote}${boilerplateNote}`
+    const declarativeNote = analysis.declarativeSuppressed
+        ? ` ${analysis.declarativeSuppressed} immutable declarative catalog group(s) were suppressed; pass include_declarative:true to inspect repeated data shapes.`
+        : ''
+    if (!groups.length) return `No clones at ≥${simMin}% similarity / ≥${tokMin} tokens (${mode} mode). Try lowering the thresholds.${smallPolicy}${suppressionNote}${boilerplateNote}${declarativeNote}`
     const top = groups.slice(0, Math.min(30, Math.max(1, Number(args.top_n) || 15)))
     const lines = top.map((grp, k) => {
         const isStr = grp.members.some((f) => f.kind === 'string')
@@ -74,10 +77,9 @@ export function tFindDuplicates(g, args, ctx) {
         const sites = grp.members.slice(0, 8).map((f) => `     ${f.file}:${f.start}-${f.end}`)
         return [head, ...sites].join('\n')
     })
-    return `Found ${groups.length} clone group(s) (${mode} mode, ≥${simMin}%, ≥${tokMin} tok${includeStrings ? ', incl. large string literals' : ''}). Top ${top.length}:\n\n${lines.join('\n\n')}\n\nUse read_source on any two sites to compare, then extract shared logic.${smallPolicy}${suppressionNote}${boilerplateNote}`
+    return `Found ${groups.length} clone group(s) (${mode} mode, ≥${simMin}%, ≥${tokMin} tok${includeStrings ? ', incl. large string literals' : ''}). Top ${top.length}:\n\n${lines.join('\n\n')}\n\nUse read_source on any two sites to compare, then extract shared logic.${smallPolicy}${suppressionNote}${boilerplateNote}${declarativeNote}`
 }
 
 // Focused dead-code review queue. Unlike the broad run_audit surface, this includes functions and
 // methods with bounded source-free evidence, and explicitly demotes framework/dynamic/public API
 // candidates. It never returns an automatic-delete verdict.
-

package/src/mcp/sync-payload.mjs

@@ -1,4 +1,4 @@
-// Versioned, explicit wire schema for sync_graph. Never forward graph.json wholesale.
+// Versioned, explicit source-free extension schema. Never forward graph.json wholesale.
 import {sanitizeEvidenceSnapshot} from './sync-evidence.mjs';
 import {
     MAX_SYNC_EXTERNAL_IMPORTS, MAX_SYNC_LINKS, MAX_SYNC_NODES, assertArrayLimit,

package/src/mcp/tools-actions.mjs

@@ -2,17 +2,10 @@
 // behaviorally identical to the former single-file implementation.
 const version = new URL(import.meta.url).search
 const load = (path) => import(new URL(`${path}${version}`, import.meta.url).href)
-const [lifecycle, advisories, architecture, sync] = await Promise.all([
+const [lifecycle] = await Promise.all([
   load('./actions/graph-lifecycle.mjs'),
-  load('./actions/advisories.mjs'),
-  load('./actions/hosted-architecture.mjs'),
-  load('./actions/graph-sync.mjs'),
 ])
 
 export const tOpenRepo = lifecycle.tOpenRepo
 export const tListKnownRepos = lifecycle.tListKnownRepos
 export const tRebuildGraph = lifecycle.tRebuildGraph
-export const tRefreshAdvisories = advisories.tRefreshAdvisories
-export const tPullArchitectureContract = architecture.tPullArchitectureContract
-export const tPreviewSyncGraph = sync.tPreviewSyncGraph
-export const tSyncGraph = sync.tSyncGraph

package/src/mcp/tools-architecture.mjs

@@ -17,7 +17,7 @@ const activeContract = bootstrap.activeArchitectureContract
 
 const remediation = () => ({
     offlinePath: '.weavatrix/architecture.json',
-    hostedAction: 'Open Architecture -> choose intended style -> Save target & baseline',
+    extensionAction: 'A composing extension may provide owner-approved remote contract storage',
     nextTool: 'verify_architecture',
 })
 
@@ -38,7 +38,7 @@ function notConfiguredResult(g, action, {includeStarter = false, repoRoot = null
         : ''
     return toolResult([
         `Architecture ${action} is NOT_CONFIGURED — no target contract is active.${starterText}`,
-        'Next: save .weavatrix/architecture.json (offline) or approve a target in Hosted, then call verify_architecture.',
+        'Next: save .weavatrix/architecture.json, then call verify_architecture.',
     ].join('\n'), {
         state: 'NOT_CONFIGURED',
         remediation: remediation(),

package/src/mcp/tools-company.mjs

@@ -193,7 +193,7 @@ export async function tTraceApiContract(_g, args = {}, ctx = {}) {
             totals: {...analysis.totals, endpoints: 0, clientCalls: 0, matches: 0, methodMismatches: 0, uncertainCalls: 0, notDeadExternalUse: 0, notDeadExternalHandlers: 0, possibleExternalUse: 0, unknownLiveness: 0},
         }
         const transportAnalysis = selectedTransport === 'http'
-            ? {transportContractsV: 1, transport: 'http', status: 'COMPLETE', completeness: {complete: true, reasons: []}, totals: {contracts: 0, matches: 0, uncertain: 0, filesScanned: 0}, contracts: [], uncertain: []}
+            ? {transportContractsV: 2, transport: 'http', status: 'COMPLETE', completeness: {complete: true, reasons: []}, totals: {contracts: 0, matches: 0, uncertain: 0, filesScanned: 0, runtimeObservations: 0, runtimeResolved: 0, runtimeReportsComplete: 0}, contracts: [], uncertain: [], runtimeEvidence: {status: 'NOT_APPLICABLE', reports: [], resolvedUnknowns: 0}}
             : analyzeTransportContracts({
                 backend: {id: backendAlias, repoRoot: backend.repoPath, graph: backendGraph.graph},
                 clients: clientGraphs.map((item) => ({id: item.alias, repoRoot: item.record.repoPath, graph: item.graph})),
@@ -201,6 +201,8 @@ export async function tTraceApiContract(_g, args = {}, ctx = {}) {
                 includeTests: args.include_tests === true,
                 maxImpactDepth: args.max_impact_depth,
                 maxAffectedFiles: args.max_affected_files,
+                runtimeEvidenceFiles: args.runtime_evidence_files,
+                runtimeEvidenceMaxAgeHours: args.runtime_evidence_max_age_hours,
             })
         const verdict = contractVerdict(analysis, transportAnalysis)
         const reasons = [...new Set([...reconciliationReasons, ...(analysis.completeness?.reasons || []), ...(transportAnalysis.completeness?.reasons || [])])]
@@ -232,7 +234,7 @@ export async function tTraceApiContract(_g, args = {}, ctx = {}) {
             ...transportAnalysis.contracts.filter((contract) => contract.callsites.length).slice(0, topN).map((contract) =>
                 `  ${contract.transport.toUpperCase()} ${contract.service ? `${contract.service}.` : contract.operation ? `${contract.operation} ` : ''}${contract.name} (${contract.file}:${contract.line}) [${contract.liveness}] → ${contract.callsites.length} callsite(s), ${contract.affected.files.length} affected file(s)`),
             completeness.complete
-                ? 'Completeness: complete within the declared repository graphs and supported static HTTP/GraphQL/gRPC/event models.'
+                ? 'Completeness: complete within the declared repository graphs, supported static models and fresh revision-bound runtime capture.'
                 : `Completeness: partial — ${completeness.reasons.join('; ')}.`,
         ]
         const result = {

package/src/mcp-runtime.mjs

@@ -0,0 +1,2 @@
+export {startMcpServer} from './mcp-server.mjs'
+export {DEFAULT_CAPS} from './mcp/catalog.mjs'

package/src/mcp-server.mjs

@@ -1,9 +1,4 @@
-// weavatrix MCP server — the stdio entry point. The tool implementations live in src/mcp/*:
-//   graph-context.mjs  — graph load + indexes, node resolution, staleness, raw-graph cache, diffs
-//   tools-graph.mjs    — graph query tools        tools-impact.mjs  — dependents / diff / change impact
-//   tools-health.mjs   — audit / clones / coverage / endpoints
-//   tools-actions.mjs  — rebuild / open_repo / list_known_repos + the 'online' group
-//   catalog.mjs        — tool catalog, capability filter, hot-reload loader
+// Weavatrix MCP stdio entry point; implementations and extension composition live in src/mcp/*.
 // Spawned by Claude Code / Codex as a plain Node child (node mcp-server.mjs <graph.json> <repoRoot>).
 // Speaks newline-delimited JSON-RPC 2.0 over stdio (the MCP stdio transport).
 //
@@ -17,6 +12,8 @@
 //   weavatrix-mcp <repoRoot> [caps]               — graph path derived from the standard layout
 //   weavatrix-mcp <graph.json> <repoRoot> [caps]  — explicit graph file (classic form)
 import process from 'node:process'
+import {resolve} from 'node:path'
+import {pathToFileURL} from 'node:url'
 import {loadGraph} from './mcp/graph-context.mjs'
 import {createStalenessNoticeGate} from './mcp/staleness-notice.mjs'
 import {normalizeToolResult} from './mcp/tool-result.mjs'
@@ -32,23 +29,33 @@ import {
 const DEFAULT_PROTOCOL = '2024-11-05'
 const log = (...a) => process.stderr.write(`[weavatrix] ${a.join(' ')}\n`)
 
-const target = resolveServerTarget(process.argv, log)
-const GRAPH_PATH = target.graphPath, REPO_ROOT = target.repoRoot, CAPS_ARG = target.capabilities
-
 // ---- hot reload of tool implementations -----------------------------------------------------------
 // Node caches modules at spawn, so edits to the tool code would otherwise be invisible until the MCP
 // client reconnects. Before each tools/list|call we stat the hot-reloadable files (HOT_FILES); when
 // any changed on disk we re-import them through catalog.loadHotApi with a cache-busting version and
 // swap the tool table, then notify the client. The stdio shell, graph-context (its caches), and the
 // analysis engines are NOT swapped — changing those still needs a reconnect.
-async function main() {
+export async function startMcpServer({
+    argv = process.argv,
+    defaultCapabilities,
+    loadExtensions = async () => [],
+    packageJsonPath = PACKAGE_JSON_PATH,
+    packageVersion = PKG_VERSION,
+    serverInfo = SERVER_INFO,
+} = {}) {
+    const target = resolveServerTarget(argv, log)
+    const GRAPH_PATH = target.graphPath
+    const REPO_ROOT = target.repoRoot
+    const CAPS_ARG = target.capabilities ?? defaultCapabilities
     let catalog = await loadCatalog()
-    let api = await catalog.loadHotApi(0, CAPS_ARG)
+    let extensions = await loadExtensions({version: 0})
+    let api = await catalog.loadHotApi(0, CAPS_ARG, {extensions})
     const runtimeInfo = () => ({
-        ...runtimeVersionStatus({runningVersion: PKG_VERSION, packageJsonPath: PACKAGE_JSON_PATH}),
+        ...runtimeVersionStatus({runningVersion: packageVersion, packageJsonPath}),
         profile: api.profile || 'custom',
         capabilities: [...api.caps],
         toolCount: api.tools.length,
+        ...(api.extensions.items.length ? {extensions: api.extensions.items} : {}),
     })
     const runtimeInstructions = () => {
         const runtime = runtimeInfo()
@@ -61,7 +68,7 @@ async function main() {
     let graphError = null
     // ctx owns the CURRENT target: rebuild_graph reloads it, open_repo retargets graphPath/repoRoot
     // at runtime. loadInto always reads ctx.graphPath so both paths share one loader.
-    const ctx = {graphPath: GRAPH_PATH, repoRoot: REPO_ROOT, reload: null, runtime: runtimeInfo()}
+    const ctx = {graphPath: GRAPH_PATH, repoRoot: REPO_ROOT, reload: null, runtime: runtimeInfo(), extensions: api.extensions}
     const loadInto = () => { graph = loadGraph(ctx.graphPath, {repoRoot: ctx.repoRoot}); graphError = null; return graph }
     ctx.reload = () => { api.resetStalenessCache(); try { return loadInto() } catch (e) { graphError = e.message; return null } }
     try {
@@ -114,10 +121,13 @@ async function main() {
         if (v <= loadedVersion || v === lastFailedVersion) return
         try {
             const nextCatalog = await loadCatalog(v)
-            const nextApi = await nextCatalog.loadHotApi(v, CAPS_ARG)
+            const nextExtensions = await loadExtensions({version: v})
+            const nextApi = await nextCatalog.loadHotApi(v, CAPS_ARG, {extensions: nextExtensions})
             catalog = nextCatalog
             api = nextApi
+            extensions = nextExtensions
             ctx.runtime = runtimeInfo()
+            ctx.extensions = api.extensions
             loadedVersion = v
             log(`hot-reloaded tool implementations from changed source (${api.tools.length} tools)`)
             send({jsonrpc: '2.0', method: 'notifications/tools/list_changed'})
@@ -145,7 +155,7 @@ async function main() {
         if (method === 'initialize') {
             if (params?.protocolVersion) protocolVersion = String(params.protocolVersion)
             return reply(id, {
-                protocolVersion, capabilities: {tools: {listChanged: true}}, serverInfo: SERVER_INFO,
+                protocolVersion, capabilities: {tools: {listChanged: true}}, serverInfo,
                 instructions: runtimeInstructions(), _meta: {'weavatrix/runtime': runtimeInfo()},
             })
         }
@@ -281,7 +291,8 @@ async function main() {
 
 // Guard: hot-reload re-imports of tool modules never touch this entry, but keep the start guard so a
 // stray re-import of the entry itself can never spawn a second stdio loop.
-if (!globalThis.__weavatrixMcpStarted) {
+const directEntry = process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href
+if (directEntry && !globalThis.__weavatrixMcpStarted) {
     globalThis.__weavatrixMcpStarted = true
-    main()
+    startMcpServer()
 }