prompt-contract 0.2.0

package/packages/mcp-server/test/mcp.test.js

@@ -0,0 +1,167 @@
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { createMockServer, ZH_RESULT } from '../../../mock/server.js';
+
+let mock, base;
+const SERVER = join(dirname(fileURLToPath(import.meta.url)), '..', 'src', 'server.js');
+
+before(async () => {
+  mock = createMockServer({});
+  const port = await mock.listen();
+  base = `http://127.0.0.1:${port}`;
+});
+
+after(async () => { await mock.close(); });
+
+function startServer() {
+  const child = spawn(process.execPath, [SERVER], {
+    env: { ...process.env, CONTRACT_PROVIDER: 'openai', CONTRACT_BASE_URL: `${base}/v1`, CONTRACT_API_KEY: 'test-key-123', CONTRACT_MODEL: 'mock-model' }
+  });
+  const pending = [];
+  let buffer = '';
+  const waiters = [];
+  child.stdout.setEncoding('utf8');
+  child.stdout.on('data', (d) => {
+    buffer += d;
+    let nl;
+    while ((nl = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, nl).trim();
+      buffer = buffer.slice(nl + 1);
+      if (!line) continue;
+      const msg = JSON.parse(line);
+      const w = waiters.shift();
+      if (w) w(msg);
+      else pending.push(msg);
+    }
+  });
+  let stderr = '';
+  child.stderr.on('data', (d) => { stderr += d; });
+  const request = (obj) => new Promise((resolveReq) => {
+    const waiter = (msg) => resolveReq(msg);
+    if (pending.length) waiter(pending.shift()); else waiters.push(waiter);
+    child.stdin.write(JSON.stringify(obj) + '\n');
+  });
+  const done = () => new Promise((r) => child.on('close', r));
+  const kill = () => { child.stdin.end(); };
+  return { child, request, done, kill, getStderr: () => stderr };
+}
+
+test('MCP: initialize → tools → tool call → prompts, full handshake', async () => {
+  const s = startServer();
+  try {
+    const init = await s.request({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-06-18' } });
+    assert.equal(init.result.serverInfo.name, 'prompt-contract');
+    assert.ok(init.result.capabilities.tools);
+    assert.ok(init.result.capabilities.prompts);
+
+    const tools = await s.request({ jsonrpc: '2.0', id: 2, method: 'tools/list' });
+    assert.equal(tools.result.tools.length, 1);
+    assert.equal(tools.result.tools[0].name, 'enhance_prompt');
+    assert.deepEqual(tools.result.tools[0].inputSchema.required, ['text']);
+
+    const call = await s.request({
+      jsonrpc: '2.0', id: 3, method: 'tools/call',
+      params: { name: 'enhance_prompt', arguments: { text: '帮我做一个展示我家狗的网站' } }
+    });
+    assert.equal(call.result.isError, undefined);
+    assert.equal(call.result.content[0].text, ZH_RESULT);
+
+    const callProfiled = await s.request({
+      jsonrpc: '2.0', id: 4, method: 'tools/call',
+      params: { name: 'enhance_prompt', arguments: { text: 'A website for my dog', profile: 'writing', strength: 'polish' } }
+    });
+    assert.equal(callProfiled.result.isError, undefined);
+    assert.ok(callProfiled.result.content[0].text.length > 0);
+
+    const prompts = await s.request({ jsonrpc: '2.0', id: 5, method: 'prompts/list' });
+    assert.deepEqual(prompts.result.prompts.map((p) => p.name), ['contract-coding-agent', 'contract-image-gen', 'contract-writing']);
+
+    const get = await s.request({
+      jsonrpc: '2.0', id: 6, method: 'prompts/get',
+      params: { name: 'contract-writing', arguments: { text: '帮我写一封请假邮件' } }
+    });
+    const promptText = get.result.messages[0].content.text;
+    assert.match(promptText, /USER INPUT:\s*\n+帮我写一封请假邮件/);
+    assert.match(promptText, /HARD CONSTRAINTS:/);
+
+    const unknown = await s.request({ jsonrpc: '2.0', id: 7, method: 'bogus/method' });
+    assert.equal(unknown.error.code, -32601);
+
+    const badTool = await s.request({
+      jsonrpc: '2.0', id: 8, method: 'tools/call',
+      params: { name: 'enhance_prompt', arguments: { text: '' } }
+    });
+    assert.equal(badTool.result.isError, true);
+    assert.match(badTool.result.content[0].text, /empty_input/);
+  } finally {
+    s.kill();
+    await s.done();
+  }
+});
+
+test('MCP: notification messages get no response frame', async () => {
+  const s = startServer();
+  try {
+    child_notify(s);
+    const res = await s.request({ jsonrpc: '2.0', id: 100, method: 'ping' });
+    assert.deepEqual(res.result, {});
+  } finally {
+    s.kill();
+    await s.done();
+  }
+});
+
+test('MCP: zero-key startup — prompts work, tool calls report config_error honestly (R12 caveat fixed)', async () => {
+  // strip every config source so nothing can satisfy the tool mode
+  const cleanEnv = { ...process.env };
+  for (const k of Object.keys(cleanEnv)) if (k.startsWith('PB_')) delete cleanEnv[k];
+  cleanEnv.CONTRACT_CONFIG = '/tmp/definitely-missing-contract-config.json';
+  const child = spawn(process.execPath, [SERVER], { env: cleanEnv });
+  const pending = [];
+  let buffer = '';
+  child.stdout.setEncoding('utf8');
+  child.stdout.on('data', (d) => {
+    buffer += d;
+    let nl;
+    while ((nl = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, nl).trim();
+      buffer = buffer.slice(nl + 1);
+      if (line) pending.push(JSON.parse(line));
+    }
+  });
+  const request = (obj) => new Promise((resolveReq) => {
+    const check = () => {
+      if (pending.length) resolveReq(pending.shift());
+      else setTimeout(check, 20);
+    };
+    child.stdin.write(JSON.stringify(obj) + '\n');
+    check();
+  });
+  try {
+    const init = await request({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} });
+    assert.equal(init.result.serverInfo.name, 'prompt-contract');
+
+    const get = await request({
+      jsonrpc: '2.0', id: 2, method: 'prompts/get',
+      params: { name: 'contract-coding-agent', arguments: { text: '做个网站' } }
+    });
+    assert.match(get.result.messages[0].content.text, /USER INPUT:\s*\n+做个网站/);
+
+    const call = await request({
+      jsonrpc: '2.0', id: 3, method: 'tools/call',
+      params: { name: 'enhance_prompt', arguments: { text: '做个网站' } }
+    });
+    assert.equal(call.result.isError, true);
+    assert.match(call.result.content[0].text, /config_error/);
+  } finally {
+    child.stdin.end();
+    await new Promise((r) => child.on('close', r));
+  }
+});
+
+function child_notify(s) {
+  s.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n');
+}

package/packages/providers/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "@prompt-contract/providers",
+  "version": "0.1.0",
+  "description": "Provider adapters — OpenAI-compatible SSE and Ollama (with keep_alive model pinning). Fetch-based, browser-safe.",
+  "type": "module",
+  "license": "Apache-2.0"
+}

package/packages/providers/src/ollama.js

@@ -0,0 +1,89 @@
+/**
+ * Ollama provider — native /api/chat (ndjson streaming).
+ * Key detail (PRD §7.6-1 / risk R9): every request carries `keep_alive` so the small model stays
+ * resident in memory — a cold model load takes seconds and would kill the hotkey experience.
+ */
+import { PromptContractError } from '../../core/src/errors.js';
+
+export function createOllamaProvider({ baseUrl = 'http://localhost:11434', keepAlive = '60m', fetchImpl = globalThis.fetch } = {}) {
+  const root = String(baseUrl).replace(/\/+$/, '');
+  return {
+    name: 'ollama',
+    keepAlive,
+    /** Preload the model into memory so the first hotkey press doesn't pay the cold-load cost. */
+    async warmup({ model, signal } = {}) {
+      if (!model) return;
+      try {
+        await fetchImpl(`${root}/api/generate`, {
+          method: 'POST',
+          signal,
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ model, prompt: '', keep_alive: keepAlive })
+        });
+      } catch { /* best effort — doctor/doctor-report surfaces connectivity */ }
+    },
+    async complete({ system, user, model, signal, onDelta, maxTokens = 1024, timeoutMs = 30000, temperature = 0.7 }) {
+      if (!model) throw new PromptContractError('config_error', 'ollama provider requires a model');
+      let timer = null;
+      let timeoutCtrl = null;
+      let fullSignal = signal;
+      if (!signal && timeoutMs) {
+        timeoutCtrl = new AbortController();
+        timer = setTimeout(() => timeoutCtrl.abort(new DOMException('timeout', 'TimeoutError')), timeoutMs);
+        fullSignal = timeoutCtrl.signal;
+      }
+      let res;
+      try {
+        res = await fetchImpl(`${root}/api/chat`, {
+          method: 'POST',
+          signal: fullSignal,
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({
+            model,
+            stream: true,
+            keep_alive: keepAlive,
+            options: { num_predict: maxTokens, temperature },
+            messages: [
+              { role: 'system', content: system },
+              { role: 'user', content: user }
+            ]
+          })
+        });
+      } catch (err) {
+        if (timer) clearTimeout(timer);
+        throw err;
+      }
+      if (!res.ok) {
+        if (timer) clearTimeout(timer);
+        let detail = '';
+        try { detail = (await res.text()).slice(0, 300); } catch { /* body unreadable */ }
+        throw new PromptContractError('provider_unavailable', `ollama HTTP ${res.status}${detail ? `: ${detail}` : ''}`);
+      }
+      let text = '';
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = '';
+      try {
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          let nl;
+          while ((nl = buffer.indexOf('\n')) >= 0) {
+            const line = buffer.slice(0, nl).trim();
+            buffer = buffer.slice(nl + 1);
+            if (!line) continue;
+            let json;
+            try { json = JSON.parse(line); } catch { continue; }
+            const delta = json.message?.content;
+            if (delta) { text += delta; if (onDelta) onDelta(delta); }
+            if (json.done) return { text };
+          }
+        }
+      } finally {
+        if (timer) clearTimeout(timer);
+      }
+      return { text };
+    }
+  };
+}

package/packages/providers/src/openai.js

@@ -0,0 +1,89 @@
+/**
+ * OpenAI-compatible provider — the universal protocol (covers OpenAI, DeepSeek, Qwen, GLM, Moonshot,
+ * OpenRouter, vLLM, LM Studio, Ollama's /v1 …). Single streaming POST, no handshake (PRD §7.6-4).
+ */
+import { PromptContractError } from '../../core/src/errors.js';
+
+/** Combine caller signal + internal timeout. Caller abort must always stay effective (ADR-017). */
+function withTimeout(signal, timeoutMs) {
+  const timeoutCtrl = new AbortController();
+  const timer = timeoutMs
+    ? setTimeout(() => timeoutCtrl.abort(new DOMException('timeout', 'TimeoutError')), timeoutMs)
+    : null;
+  let combined = timeoutCtrl.signal;
+  if (signal) {
+    if (typeof AbortSignal.any === 'function') {
+      combined = AbortSignal.any([signal, timeoutCtrl.signal]);
+    } else {
+      signal.addEventListener('abort', () => timeoutCtrl.abort(signal.reason), { once: true });
+    }
+  }
+  return { signal: combined, cleanup: () => { if (timer) clearTimeout(timer); } };
+}
+
+export function createOpenAIProvider({ baseUrl = 'https://api.openai.com/v1', apiKey = '', fetchImpl = globalThis.fetch } = {}) {
+  const root = String(baseUrl).replace(/\/+$/, '');
+  return {
+    name: 'openai',
+    /** Open one TLS/TCP connection early so the first real request pays no handshake (PRD §7.6-1). */
+    async warmup({ signal } = {}) {
+      try { await fetchImpl(`${root}/models`, { headers: { authorization: `Bearer ${apiKey}` }, signal }); } catch { /* best effort */ }
+    },
+    async complete({ system, user, model, signal, onDelta, maxTokens = 1024, timeoutMs = 30000, temperature = 0.7 }) {
+      const { signal: fullSignal, cleanup } = withTimeout(signal, timeoutMs);
+      let res;
+      try {
+        res = await fetchImpl(`${root}/chat/completions`, {
+          method: 'POST',
+          signal: fullSignal,
+          headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
+          body: JSON.stringify({
+            model,
+            stream: true,
+            max_tokens: maxTokens,
+            temperature,
+            messages: [
+              { role: 'system', content: system },
+              { role: 'user', content: user }
+            ]
+          })
+        });
+      } catch (err) {
+        cleanup();
+        throw err; // pipeline normalizes AbortError / network errors
+      }
+      if (!res.ok) {
+        cleanup();
+        let detail = '';
+        try { detail = (await res.text()).slice(0, 300); } catch { /* body unreadable */ }
+        throw new PromptContractError('provider_unavailable', `provider HTTP ${res.status}${detail ? `: ${detail}` : ''}`);
+      }
+      let text = '';
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = '';
+      try {
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          let nl;
+          while ((nl = buffer.indexOf('\n')) >= 0) {
+            const line = buffer.slice(0, nl).trim();
+            buffer = buffer.slice(nl + 1);
+            if (!line.startsWith('data:')) continue;
+            const data = line.slice(5).trim();
+            if (!data || data === '[DONE]') continue;
+            let json;
+            try { json = JSON.parse(data); } catch { continue; }
+            const delta = json.choices?.[0]?.delta?.content;
+            if (delta) { text += delta; if (onDelta) onDelta(delta); }
+          }
+        }
+      } finally {
+        cleanup();
+      }
+      return { text };
+    }
+  };
+}

package/packages/providers/test/providers.test.js

@@ -0,0 +1,64 @@
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { createMockServer, EN_RESULT, ZH_RESULT } from '../../../mock/server.js';
+import { createOpenAIProvider } from '../src/openai.js';
+import { createOllamaProvider } from '../src/ollama.js';
+import { PromptContractError } from '../../core/src/errors.js';
+
+let mock, base;
+before(async () => {
+  mock = createMockServer({});
+  const port = await mock.listen();
+  base = `http://127.0.0.1:${port}`;
+});
+after(async () => { await mock.close(); });
+
+test('openai provider reassembles SSE chunks in order', async () => {
+  const p = createOpenAIProvider({ baseUrl: `${base}/v1`, apiKey: 'test-key-123' });
+  let deltas = 0;
+  const { text } = await p.complete({ system: 's', user: 'USER INPUT:\n帮我做一个展示我家狗的网站', model: 'mock-model', onDelta: () => deltas++ });
+  assert.equal(text, ZH_RESULT);
+  assert.ok(deltas > 3, `expected multiple deltas, got ${deltas}`);
+});
+
+test('openai provider handles english input', async () => {
+  const p = createOpenAIProvider({ baseUrl: `${base}/v1`, apiKey: 'test-key-123' });
+  const { text } = await p.complete({ system: 's', user: 'USER INPUT:\nA website for my dog', model: 'mock-model' });
+  assert.equal(text, EN_RESULT);
+});
+
+test('openai provider maps non-200 to provider_unavailable', async () => {
+  const p = createOpenAIProvider({ baseUrl: base, apiKey: 'test-key-123' }); // /chat/completions → 404
+  await assert.rejects(
+    () => p.complete({ system: 's', user: 'u', model: 'm' }),
+    (e) => e instanceof PromptContractError && e.code === 'provider_unavailable'
+  );
+});
+
+test('openai provider: caller abort cancels the stream (ADR-017)', async () => {
+  const p = createOpenAIProvider({ baseUrl: `${base}/v1`, apiKey: 'test-key-123' });
+  const ctrl = new AbortController();
+  const promise = p.complete({
+    system: 's', user: 'USER INPUT:\nA website for my dog', model: 'm',
+    signal: ctrl.signal,
+    onDelta: () => ctrl.abort()
+  });
+  await assert.rejects(promise, (e) => e.name === 'AbortError');
+  await new Promise((r) => setTimeout(r, 50));
+  assert.ok(mock.state.aborts >= 1, 'mock should have observed the aborted connection');
+});
+
+test('ollama provider sends keep_alive so the model stays warm (R10)', async () => {
+  const p = createOllamaProvider({ baseUrl: base, keepAlive: '60m' });
+  const { text } = await p.complete({ system: 's', user: 'USER INPUT:\n帮我做一个展示我家狗的网站', model: 'mock-model', maxTokens: 960 });
+  assert.equal(text, ZH_RESULT);
+  assert.equal(mock.state.lastChatBody.keep_alive, '60m');
+  assert.equal(mock.state.lastChatBody.options.num_predict, 960);
+});
+
+test('ollama warmup preloads the model via /api/generate (R10)', async () => {
+  const p = createOllamaProvider({ baseUrl: base, keepAlive: '30m' });
+  await p.warmup({ model: 'mock-model' });
+  assert.equal(mock.state.lastGenerateBody.model, 'mock-model');
+  assert.equal(mock.state.lastGenerateBody.keep_alive, '30m');
+});

package/profiles/coding-agent.md

@@ -0,0 +1,9 @@
+---
+name: coding-agent
+domain: 编码 agent 任务规范化（Claude Code / Cursor / Cline 等）
+maxChars: 800
+noUnmentionedTech: true
+---
+You are a prompt rewriting specialist for requests submitted to an AI coding assistant. Your only job is to rewrite the user's vague request into a precise, executable task specification while preserving its intent and language.
+
+A good specification states: what to build or change, the scope and boundaries, observable acceptance criteria, relevant constraints, and what is explicitly out of scope. It describes outcomes rather than implementation steps, and it never introduces tools, frameworks, or requirements the requester did not mention.

package/profiles/image-gen.md

@@ -0,0 +1,9 @@
+---
+name: image-gen
+domain: 图像生成提示词（Midjourney / 即梦 / SD 类）
+maxChars: 600
+noUnmentionedTech: true
+---
+You are a prompt rewriting specialist for text-to-image requests. Your only job is to expand the user's vague image idea into a vivid, unambiguous generation prompt, in the same language as the request.
+
+A good image prompt states: the main subject and its action, composition and framing, lighting and atmosphere, style and medium, and level of detail. Keep only qualities the user implied or that naturally serve the subject; never inject named artists, brands, or proprietary style names the user did not mention.

package/profiles/writing.md

@@ -0,0 +1,9 @@
+---
+name: writing
+domain: 通用写作与改写（语气、结构、受众）
+maxChars: 800
+noUnmentionedTech: true
+---
+You are a prompt rewriting specialist for writing and editing requests. Your only job is to turn the user's vague writing instruction into a clear brief that any writing assistant can execute faithfully, preserving the request's intent and language.
+
+A good brief specifies: the piece to produce or edit, the intended audience and tone, structural expectations (length, sections, ordering), what must be preserved (facts, terminology, voice), and what to avoid. It never invents subject matter the requester did not mention.