@specverse/engines 5.2.0 → 6.0.0

package/dist/ai/providers/claude-cli.js

@@ -0,0 +1,185 @@
+/**
+ * claude-cli provider — wraps the locally-installed `claude` binary as an
+ * AI SDK v3 LanguageModel. Preserves the Max-subscription zero-cost path
+ * by spawning `claude --print` with the user's authenticated session.
+ *
+ * Session caching: first call uses `--session-id <uuid>`, subsequent calls
+ * `--resume <uuid>` — gives the same 98% token savings the Claude Code
+ * session mechanism provides.
+ *
+ * If the user has run `spv skill install --global`, the SpecVerse skill is
+ * auto-loaded by Claude Code into every session started by this provider.
+ * See detectInstalledSkill() in ../skill-detection.ts.
+ */
+import { spawn, execSync } from 'child_process';
+import { existsSync } from 'fs';
+import { randomUUID } from 'crypto';
+import { join } from 'path';
+/**
+ * Find the first working `claude` binary. Tries:
+ *   1. Explicit path override if given
+ *   2. ~/.claude/local/claude (Claude Code's user install)
+ *   3. `claude` on PATH (Homebrew / manual installs)
+ * Returns null if none respond to `--version`.
+ */
+export function detectClaudePath(override) {
+    const home = process.env.HOME || '';
+    const candidates = override
+        ? [override]
+        : [join(home, '.claude', 'local', 'claude'), 'claude'];
+    for (const candidate of candidates) {
+        // For explicit paths, require existence on disk before exec.
+        if (candidate !== 'claude' && !existsSync(candidate))
+            continue;
+        try {
+            execSync(`${candidate} --version`, { stdio: 'ignore', timeout: 5000 });
+            return candidate;
+        }
+        catch {
+            /* try next */
+        }
+    }
+    return null;
+}
+/** True if any candidate claude binary responds to --version. */
+export function isClaudeCliAvailable(override) {
+    return detectClaudePath(override) !== null;
+}
+/**
+ * Extract a flat { system, user } pair from the AI SDK's message array.
+ * The claude CLI's --system-prompt / -p flags only accept one string each.
+ * For now we concatenate any system messages, and join all user turns with
+ * blank lines. (In practice behavior generation is single-turn; this
+ * provider isn't targeting multi-turn conversational use.)
+ */
+function flattenPrompt(messages) {
+    const systemChunks = [];
+    const userChunks = [];
+    for (const msg of messages) {
+        if (msg.role === 'system') {
+            systemChunks.push(msg.content);
+        }
+        else if (msg.role === 'user') {
+            for (const part of msg.content) {
+                if (part.type === 'text')
+                    userChunks.push(part.text);
+            }
+        }
+        else if (msg.role === 'assistant') {
+            // Prior assistant turns get included into the user prompt as context
+            // so the CLI can see them. Unusual for our use case.
+            const text = msg.content
+                .filter((p) => p.type === 'text')
+                .map((p) => p.text)
+                .join('');
+            if (text)
+                userChunks.push(`[Assistant previously said]\n${text}`);
+        }
+    }
+    return {
+        system: systemChunks.join('\n\n').trim(),
+        user: userChunks.join('\n\n').trim(),
+    };
+}
+/**
+ * Factory for a claude-cli-backed LanguageModelV3. Session state is held
+ * inside the closure, so each call to claudeCli() gets its own session.
+ */
+export function claudeCli(options = {}) {
+    const claudePath = options.claudePath || detectClaudePath() || 'claude';
+    const timeout = options.timeout ?? 120_000;
+    const modelId = options.model ?? 'default';
+    const sessionId = randomUUID();
+    let initialized = false;
+    async function spawnClaude(args, stdinPrompt) {
+        return new Promise((resolve, reject) => {
+            const proc = spawn(claudePath, args, {
+                stdio: ['ignore', 'pipe', 'pipe'],
+                env: { ...process.env },
+            });
+            let out = '';
+            let err = '';
+            const timer = setTimeout(() => {
+                proc.kill();
+                reject(new Error(`claude-cli timed out after ${timeout}ms`));
+            }, timeout);
+            proc.stdout?.on('data', (d) => {
+                out += d.toString();
+            });
+            proc.stderr?.on('data', (d) => {
+                err += d.toString();
+            });
+            proc.on('close', (code) => {
+                clearTimeout(timer);
+                if (code !== 0) {
+                    reject(new Error(`claude-cli exited ${code}: ${err || out}`));
+                    return;
+                }
+                resolve(out);
+            });
+            proc.on('error', (e) => {
+                clearTimeout(timer);
+                reject(e);
+            });
+        });
+    }
+    const model = {
+        specificationVersion: 'v3',
+        provider: 'claude-cli',
+        modelId,
+        supportedUrls: {},
+        async doGenerate(opts) {
+            const { system, user } = flattenPrompt(opts.prompt);
+            const args = ['--print'];
+            if (!initialized) {
+                args.push('--session-id', sessionId);
+                if (system)
+                    args.push('--system-prompt', system);
+            }
+            else {
+                args.push('--resume', sessionId);
+            }
+            if (modelId !== 'default')
+                args.push('--model', modelId);
+            args.push('-p', user);
+            const out = await spawnClaude(args, user);
+            initialized = true;
+            return {
+                content: [{ type: 'text', text: out.trim() }],
+                finishReason: { unified: 'stop', raw: undefined },
+                usage: {
+                    // The CLI doesn't expose token counts in --print mode.
+                    inputTokens: { total: undefined, noCache: undefined, cacheRead: undefined, cacheWrite: undefined },
+                    outputTokens: { total: undefined, text: undefined, reasoning: undefined },
+                },
+                warnings: [],
+            };
+        },
+        async doStream(opts) {
+            // v1 of this provider: no real streaming — buffer the doGenerate result
+            // and emit it as a single chunk. Revisit if behavior-service ever wants
+            // partial-output UX.
+            const result = await model.doGenerate(opts);
+            const text = result.content
+                .filter((c) => c.type === 'text')
+                .map((c) => c.text)
+                .join('');
+            const parts = [
+                { type: 'text-start', id: 'single' },
+                { type: 'text-delta', id: 'single', delta: text },
+                { type: 'text-end', id: 'single' },
+                { type: 'finish', finishReason: { unified: 'stop', raw: undefined }, usage: result.usage },
+            ];
+            const stream = new ReadableStream({
+                start(controller) {
+                    for (const part of parts)
+                        controller.enqueue(part);
+                    controller.close();
+                },
+            });
+            return { stream };
+        },
+    };
+    return model;
+}
+//# sourceMappingURL=claude-cli.js.map

package/dist/ai/providers/claude-cli.js.map

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

package/dist/ai/providers/index.d.ts

@@ -1,6 +1,9 @@
-export * from './llm-provider.js';
-export * from './provider-factory.js';
-export * from './openai-provider.js';
-export * from './anthropic-provider.js';
-export * from './interactive-provider.js';
+/**
+ * AI providers — custom LanguageModelV3 implementations that plug into the
+ * Vercel AI SDK. Most consumers should call `resolveModel()` from the parent
+ * module rather than instantiating these directly.
+ */
+export { claudeCli, isClaudeCliAvailable, detectClaudePath } from './claude-cli.js';
+export type { ClaudeCliOptions } from './claude-cli.js';
+export { stubModel } from './stub.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/ai/providers/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ai/providers/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ai/providers/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,SAAS,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACpF,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC"}

package/dist/ai/providers/index.js

@@ -1,6 +1,8 @@
-export * from './llm-provider.js';
-export * from './provider-factory.js';
-export * from './openai-provider.js';
-export * from './anthropic-provider.js';
-export * from './interactive-provider.js';
+/**
+ * AI providers — custom LanguageModelV3 implementations that plug into the
+ * Vercel AI SDK. Most consumers should call `resolveModel()` from the parent
+ * module rather than instantiating these directly.
+ */
+export { claudeCli, isClaudeCliAvailable, detectClaudePath } from './claude-cli.js';
+export { stubModel } from './stub.js';
 //# sourceMappingURL=index.js.map

package/dist/ai/providers/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/ai/providers/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/ai/providers/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,SAAS,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEpF,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC"}

package/dist/ai/providers/stub.d.ts

@@ -0,0 +1,15 @@
+/**
+ * stub provider — an AI SDK v3 LanguageModel that doesn't call any LLM.
+ * Emits the user prompt verbatim with a marker comment so the ambient
+ * runtime (MCP client, user's editor, etc.) can see what was asked and
+ * execute it themselves.
+ *
+ * Used in two scenarios:
+ * 1. Inside an MCP server context (MCP_SERVER=1) — the Claude Desktop /
+ *    client session IS the LLM; calling a separate API would be wasteful.
+ * 2. As the safe default when no provider is configured — gives a clear
+ *    diagnostic instead of a silent failure or a cryptic auth error.
+ */
+import type { LanguageModelV3 } from '@ai-sdk/provider';
+export declare function stubModel(): LanguageModelV3;
+//# sourceMappingURL=stub.d.ts.map

package/dist/ai/providers/stub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub.d.ts","sourceRoot":"","sources":["../../../src/ai/providers/stub.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EACV,eAAe,EAMhB,MAAM,kBAAkB,CAAC;AAkB1B,wBAAgB,SAAS,IAAI,eAAe,CAqD3C"}

package/dist/ai/providers/stub.js

@@ -0,0 +1,64 @@
+function formatAsText(messages) {
+    const sections = [];
+    for (const msg of messages) {
+        if (msg.role === 'system') {
+            sections.push(`--- system ---\n${msg.content}`);
+        }
+        else if (msg.role === 'user') {
+            const text = msg.content
+                .filter((p) => p.type === 'text')
+                .map((p) => p.text)
+                .join('');
+            sections.push(`--- user ---\n${text}`);
+        }
+    }
+    return sections.join('\n\n');
+}
+export function stubModel() {
+    const model = {
+        specificationVersion: 'v3',
+        provider: 'specverse-stub',
+        modelId: 'stub',
+        supportedUrls: {},
+        async doGenerate(opts) {
+            const text = '// SPECVERSE_AI_PROVIDER=stub — no LLM was called.\n' +
+                '// The ambient runtime (MCP client, agent, or user) is expected to\n' +
+                '// execute the prompt below. To enable real generation, set\n' +
+                '// SPECVERSE_AI_PROVIDER to one of: claude-cli, anthropic, openai-compatible.\n' +
+                '\n' +
+                formatAsText(opts.prompt);
+            return {
+                content: [{ type: 'text', text }],
+                finishReason: { unified: 'stop', raw: undefined },
+                usage: {
+                    inputTokens: { total: 0, noCache: 0, cacheRead: 0, cacheWrite: 0 },
+                    outputTokens: { total: 0, text: 0, reasoning: 0 },
+                },
+                warnings: [],
+            };
+        },
+        async doStream(opts) {
+            const result = await model.doGenerate(opts);
+            const text = result.content
+                .filter((c) => c.type === 'text')
+                .map((c) => c.text)
+                .join('');
+            const parts = [
+                { type: 'text-start', id: 'stub' },
+                { type: 'text-delta', id: 'stub', delta: text },
+                { type: 'text-end', id: 'stub' },
+                { type: 'finish', finishReason: { unified: 'stop', raw: undefined }, usage: result.usage },
+            ];
+            const stream = new ReadableStream({
+                start(controller) {
+                    for (const part of parts)
+                        controller.enqueue(part);
+                    controller.close();
+                },
+            });
+            return { stream };
+        },
+    };
+    return model;
+}
+//# sourceMappingURL=stub.js.map

package/dist/ai/providers/stub.js.map

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

package/dist/ai/skill-detection.d.ts

@@ -0,0 +1,5 @@
+export declare function detectInstalledSkill(skillName?: string): {
+    found: boolean;
+    location: string | null;
+};
+//# sourceMappingURL=skill-detection.d.ts.map

package/dist/ai/skill-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-detection.d.ts","sourceRoot":"","sources":["../../src/ai/skill-detection.ts"],"names":[],"mappings":"AAgBA,wBAAgB,oBAAoB,CAAC,SAAS,SAAc,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CASzG"}

package/dist/ai/skill-detection.js

@@ -0,0 +1,27 @@
+/**
+ * Detect whether the SpecVerse Claude skill is installed in a location
+ * that Claude Code will auto-load.
+ *
+ * Claude Code discovers skills from:
+ *   - ~/.claude/skills/<name>/   (global — shipped by `spv skill install --global`)
+ *   - <cwd>/.claude/skills/<name>/   (project-local — `spv skill install --project`)
+ *
+ * If either is present with a SKILL.md, we assume Claude-CLI-backed behavior
+ * generation will benefit from the skill's auto-loaded context — meaning we
+ * can send a leaner system prompt (skip the fullContext block).
+ */
+import { existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+export function detectInstalledSkill(skillName = 'specverse') {
+    const candidates = [
+        join(process.cwd(), '.claude', 'skills', skillName, 'SKILL.md'),
+        join(homedir(), '.claude', 'skills', skillName, 'SKILL.md'),
+    ];
+    for (const path of candidates) {
+        if (existsSync(path))
+            return { found: true, location: path };
+    }
+    return { found: false, location: null };
+}
+//# sourceMappingURL=skill-detection.js.map

package/dist/ai/skill-detection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-detection.js","sourceRoot":"","sources":["../../src/ai/skill-detection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAC7B,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,MAAM,UAAU,oBAAoB,CAAC,SAAS,GAAG,WAAW;IAC1D,MAAM,UAAU,GAAG;QACjB,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,CAAC;QAC/D,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,CAAC;KAC5D,CAAC;IACF,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,IAAI,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC/D,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAC1C,CAAC"}

package/dist/libs/instance-factories/tools/templates/mcp/mcp-server-generator.js

@@ -130,9 +130,9 @@ function generatePackageJson(version, description) {
     },
     dependencies: {
       "@modelcontextprotocol/sdk": "^1.17.4",
-      "@specverse/engines": "^5.2.0",
+      "@specverse/engines": "^6.0.0",
       "@specverse/entities": "^5.1.0",
-      "@specverse/self": "^5.2.0",
+      "@specverse/self": "^5.3.0",
       "js-yaml": "^4.1.0"
     },
     devDependencies: {

package/libs/instance-factories/tools/templates/mcp/mcp-server-generator.ts

@@ -208,9 +208,9 @@ function generatePackageJson(version: string, description: string): string {
     },
     dependencies: {
       '@modelcontextprotocol/sdk': '^1.17.4',
-      '@specverse/engines': '^5.2.0',
+      '@specverse/engines': '^6.0.0',
       '@specverse/entities': '^5.1.0',
-      '@specverse/self': '^5.2.0',
+      '@specverse/self': '^5.3.0',
       'js-yaml': '^4.1.0',
     },
     devDependencies: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@specverse/engines",
-  "version": "5.2.0",
-  "description": "SpecVerse toolchain \u2014 parser, inference, realize, generators, AI, registry, bundles",
+  "version": "6.0.0",
+  "description": "SpecVerse toolchain — parser, inference, realize, generators, AI, registry, bundles",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -46,16 +46,21 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
+    "@ai-sdk/anthropic": "^3.0.71",
+    "@ai-sdk/openai-compatible": "^2.0.41",
+    "@ai-sdk/provider": "^3.0.8",
     "@specverse/entities": "^5.1.0",
     "@specverse/runtime": "^5.0.1",
     "@specverse/types": "^5.1.0",
+    "ai": "^6.0.168",
     "ajv": "^8.17.0",
     "ajv-formats": "^2.1.0",
     "glob": "^10.0.0",
     "handlebars": "^4.7.9",
     "js-yaml": "^4.1.0",
     "semver": "^7.0.0",
-    "yaml": "^2.8.1"
+    "yaml": "^2.8.1",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",