simt-dev 0.3.0 → 0.4.0

package/src/local/client.mjs

@@ -0,0 +1,482 @@
+// Zero-dependency OpenAI-compatible client for local model servers (plan 0003 R37):
+// Ollama, llama.cpp `llama-server`, LM Studio and MLX servers over `http://127.0.0.1:<port>/v1/...`.
+//
+// Two hard invariants (ADR-075, ADR-090):
+//   1. When `local` is unset in the manifest, no socket is ever opened.
+//   2. Non-loopback URLs are refused before any socket is opened unless `allowRemote`
+//      (`--allow-remote`) is explicitly set.
+
+import {
+  DEFAULT_LOCAL_TIMEOUT_MS,
+  isLoopbackUrl,
+  parseLocalConfig,
+  readLocalConfig,
+  resolveEndpointUrl,
+} from './config.mjs';
+
+function guardEndpoint(endpoint, { allowRemote = false } = {}) {
+  if (!endpoint || typeof endpoint !== 'object') {
+    return { ok: false, error: 'local model endpoint is not configured', refusedRemote: false };
+  }
+  const rawUrl = typeof endpoint.url === 'string' ? endpoint.url.trim() : '';
+  if (!rawUrl) {
+    return { ok: false, error: 'local model endpoint is missing `url`', refusedRemote: false };
+  }
+  const model = typeof endpoint.model === 'string' ? endpoint.model.trim() : '';
+  if (!model) {
+    return { ok: false, error: 'local model endpoint is missing `model`', refusedRemote: false };
+  }
+  const loopback = isLoopbackUrl(rawUrl);
+  if (!loopback && !allowRemote) {
+    return {
+      ok: false,
+      refusedRemote: true,
+      error: `refused non-loopback URL ${rawUrl} without --allow-remote (ADR-075)`,
+    };
+  }
+  return {
+    ok: true,
+    url: rawUrl,
+    baseUrl: resolveEndpointUrl(rawUrl, ''),
+    model,
+    timeoutMs: Number.isInteger(endpoint.timeoutMs) && endpoint.timeoutMs > 0
+      ? endpoint.timeoutMs
+      : DEFAULT_LOCAL_TIMEOUT_MS,
+    loopback,
+  };
+}
+
+async function requestJson(url, { method = 'GET', body = undefined, timeoutMs = DEFAULT_LOCAL_TIMEOUT_MS, fetchImpl = globalThis.fetch } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetchImpl(url, {
+      method,
+      headers: body !== undefined ? { 'content-type': 'application/json', accept: 'application/json' } : { accept: 'application/json' },
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+      signal: controller.signal,
+    });
+    const text = await response.text();
+    let parsed = null;
+    if (text.trim().length > 0) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = null;
+      }
+    }
+    if (!response.ok) {
+      const serverMsg =
+        parsed?.error?.message ??
+        (typeof parsed?.error === 'string' ? parsed.error : null) ??
+        (text.trim().slice(0, 160) || `HTTP ${response.status}`);
+      return {
+        ok: false,
+        status: response.status,
+        error: `${method} ${url} failed (${response.status}): ${serverMsg}`,
+        socketOpened: true,
+      };
+    }
+    if (parsed === null || typeof parsed !== 'object') {
+      return {
+        ok: false,
+        status: response.status,
+        error: `${method} ${url} returned non-JSON response`,
+        socketOpened: true,
+      };
+    }
+    return { ok: true, status: response.status, data: parsed, socketOpened: true };
+  } catch (error) {
+    const reason =
+      error?.name === 'AbortError'
+        ? `timed out after ${timeoutMs} ms`
+        : error?.cause?.message ?? error?.message ?? String(error);
+    return {
+      ok: false,
+      status: null,
+      error: `${method} ${url} failed: ${reason}`,
+      socketOpened: true,
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Query `GET <baseUrl>/v1/models` on an OpenAI-compatible local server.
+ */
+export async function localModels(endpoint, { allowRemote = false, fetchImpl = globalThis.fetch } = {}) {
+  const guard = guardEndpoint(endpoint, { allowRemote });
+  if (!guard.ok) {
+    return {
+      ok: false,
+      models: [],
+      error: guard.error,
+      refusedRemote: guard.refusedRemote,
+      socketOpened: false,
+    };
+  }
+
+  const targetUrl = resolveEndpointUrl(guard.baseUrl, '/models');
+  const res = await requestJson(targetUrl, {
+    method: 'GET',
+    timeoutMs: guard.timeoutMs,
+    fetchImpl,
+  });
+  if (!res.ok) {
+    return {
+      ok: false,
+      models: [],
+      status: res.status,
+      error: res.error,
+      refusedRemote: false,
+      socketOpened: res.socketOpened,
+    };
+  }
+
+  const rawList = Array.isArray(res.data.data)
+    ? res.data.data
+    : Array.isArray(res.data.models)
+      ? res.data.models
+      : [];
+  const models = rawList
+    .map((item) => (typeof item === 'string' ? item : item?.id ?? item?.name ?? ''))
+    .map((id) => String(id).trim())
+    .filter(Boolean);
+
+  return {
+    ok: true,
+    models,
+    status: res.status,
+    error: null,
+    refusedRemote: false,
+    socketOpened: true,
+  };
+}
+
+/**
+ * Send a `POST <baseUrl>/v1/chat/completions` request to an OpenAI-compatible local server.
+ */
+export async function localChat(
+  endpoint,
+  {
+    messages = undefined,
+    prompt = '',
+    system = undefined,
+    temperature = 0,
+    maxTokens = 256,
+    allowRemote = false,
+    fetchImpl = globalThis.fetch,
+  } = {},
+) {
+  const guard = guardEndpoint(endpoint, { allowRemote });
+  if (!guard.ok) {
+    return {
+      ok: false,
+      content: null,
+      model: endpoint?.model ?? null,
+      usage: null,
+      error: guard.error,
+      refusedRemote: guard.refusedRemote,
+      socketOpened: false,
+    };
+  }
+
+  const chatMessages = Array.isArray(messages) && messages.length > 0
+    ? messages
+    : [
+        ...(system ? [{ role: 'system', content: String(system) }] : []),
+        { role: 'user', content: String(prompt) },
+      ];
+
+  const targetUrl = resolveEndpointUrl(guard.baseUrl, '/chat/completions');
+  const res = await requestJson(targetUrl, {
+    method: 'POST',
+    body: {
+      model: guard.model,
+      messages: chatMessages,
+      temperature,
+      ...(Number.isInteger(maxTokens) && maxTokens > 0 ? { max_tokens: maxTokens } : {}),
+      stream: false,
+    },
+    timeoutMs: guard.timeoutMs,
+    fetchImpl,
+  });
+
+  if (!res.ok) {
+    return {
+      ok: false,
+      content: null,
+      model: guard.model,
+      usage: null,
+      error: res.error,
+      refusedRemote: false,
+      socketOpened: res.socketOpened,
+    };
+  }
+
+  const choice = Array.isArray(res.data.choices) ? res.data.choices[0] : null;
+  const content =
+    typeof choice?.message?.content === 'string'
+      ? choice.message.content
+      : typeof choice?.text === 'string'
+        ? choice.text
+        : null;
+
+  if (content === null) {
+    return {
+      ok: false,
+      content: null,
+      model: guard.model,
+      usage: null,
+      error: `POST ${targetUrl} returned no choice content`,
+      refusedRemote: false,
+      socketOpened: true,
+    };
+  }
+
+  return {
+    ok: true,
+    content,
+    model: typeof res.data.model === 'string' ? res.data.model : guard.model,
+    usage: res.data.usage ?? null,
+    error: null,
+    refusedRemote: false,
+    socketOpened: true,
+  };
+}
+
+/**
+ * Send a `POST <baseUrl>/v1/embeddings` request to an OpenAI-compatible local server.
+ */
+export async function localEmbed(
+  endpoint,
+  { input, allowRemote = false, fetchImpl = globalThis.fetch } = {},
+) {
+  const guard = guardEndpoint(endpoint, { allowRemote });
+  if (!guard.ok) {
+    return {
+      ok: false,
+      embeddings: [],
+      dimensions: 0,
+      model: endpoint?.model ?? null,
+      usage: null,
+      error: guard.error,
+      refusedRemote: guard.refusedRemote,
+      socketOpened: false,
+    };
+  }
+
+  const targetUrl = resolveEndpointUrl(guard.baseUrl, '/embeddings');
+  const res = await requestJson(targetUrl, {
+    method: 'POST',
+    body: {
+      model: guard.model,
+      input: Array.isArray(input) ? input.map(String) : String(input ?? ''),
+    },
+    timeoutMs: guard.timeoutMs,
+    fetchImpl,
+  });
+
+  if (!res.ok) {
+    return {
+      ok: false,
+      embeddings: [],
+      dimensions: 0,
+      model: guard.model,
+      usage: null,
+      error: res.error,
+      refusedRemote: false,
+      socketOpened: res.socketOpened,
+    };
+  }
+
+  const rawVectors = Array.isArray(res.data.data)
+    ? res.data.data.map((entry) => entry?.embedding)
+    : Array.isArray(res.data.embeddings)
+      ? res.data.embeddings
+      : Array.isArray(res.data.embedding)
+        ? [res.data.embedding]
+        : [];
+
+  const validVectors = rawVectors.filter(
+    (vec) => Array.isArray(vec) && vec.length > 0 && vec.every((n) => typeof n === 'number' && Number.isFinite(n)),
+  );
+
+  if (validVectors.length === 0) {
+    return {
+      ok: false,
+      embeddings: [],
+      dimensions: 0,
+      model: guard.model,
+      usage: null,
+      error: `POST ${targetUrl} returned no valid embedding vector`,
+      refusedRemote: false,
+      socketOpened: true,
+    };
+  }
+
+  return {
+    ok: true,
+    embeddings: validVectors,
+    dimensions: validVectors[0].length,
+    model: typeof res.data.model === 'string' ? res.data.model : guard.model,
+    usage: res.data.usage ?? null,
+    error: null,
+    refusedRemote: false,
+    socketOpened: true,
+  };
+}
+
+function summarizeBlockedEndpoint(endpoint) {
+  if (!endpoint) return null;
+  return {
+    role: endpoint.role,
+    configured: true,
+    ok: false,
+    status: endpoint.blocked ? 'refused-remote' : 'skipped',
+    url: endpoint.baseUrl,
+    model: endpoint.model,
+    loopback: endpoint.loopback,
+    error: endpoint.blocked
+      ? `refused non-loopback URL ${endpoint.url} without --allow-remote (ADR-075)`
+      : 'skipped due to configuration errors',
+  };
+}
+
+/**
+ * Probe the capabilities of the repository's configured local model endpoints (`simt local doctor`).
+ *
+ * When `local` is unset in the manifest, returns `status: 'unconfigured'` with
+ * `socketsOpened: 0` without calling `fetchImpl`. When any endpoint is non-loopback
+ * and `allowRemote` is false, refuses with `status: 'refused-remote'` and `socketsOpened: 0`.
+ */
+export async function probeLocal(
+  root,
+  { manifest = undefined, allowRemote = false, fetchImpl = globalThis.fetch } = {},
+) {
+  const config =
+    manifest !== undefined
+      ? { ...parseLocalConfig(manifest, { allowRemote }), manifestExists: true, manifestError: null }
+      : await readLocalConfig(root, { allowRemote });
+
+  if (config.manifestError !== null) {
+    return {
+      ok: false,
+      configured: false,
+      status: 'invalid-manifest',
+      allowRemote,
+      remoteBlocked: false,
+      socketsOpened: 0,
+      chat: null,
+      embed: null,
+      findings: config.findings,
+    };
+  }
+
+  if (!config.configured) {
+    return {
+      ok: true,
+      configured: false,
+      status: 'unconfigured',
+      allowRemote,
+      remoteBlocked: false,
+      socketsOpened: 0,
+      chat: null,
+      embed: null,
+      findings: [],
+    };
+  }
+
+  if (config.findings.length > 0) {
+    return {
+      ok: false,
+      configured: true,
+      status: config.remoteBlocked ? 'refused-remote' : 'invalid-config',
+      allowRemote,
+      remoteBlocked: config.remoteBlocked,
+      socketsOpened: 0,
+      chat: summarizeBlockedEndpoint(config.chat),
+      embed: summarizeBlockedEndpoint(config.embed),
+      findings: config.findings,
+    };
+  }
+
+  let socketsOpened = 0;
+  const findings = [];
+  let chatReport = null;
+  let embedReport = null;
+
+  if (config.chat) {
+    const modelsRes = await localModels(config.chat, { allowRemote, fetchImpl });
+    if (modelsRes.socketOpened) socketsOpened += 1;
+    const chatRes = await localChat(config.chat, {
+      messages: [{ role: 'user', content: 'ping' }],
+      maxTokens: 1,
+      temperature: 0,
+      allowRemote,
+      fetchImpl,
+    });
+    if (chatRes.socketOpened) socketsOpened += 1;
+
+    if (!chatRes.ok) findings.push(`chat probe failed: ${chatRes.error}`);
+
+    chatReport = {
+      role: 'chat',
+      configured: true,
+      ok: chatRes.ok,
+      status: chatRes.ok ? 'ok' : 'unreachable',
+      url: config.chat.baseUrl,
+      model: config.chat.model,
+      responseModel: chatRes.ok ? chatRes.model : null,
+      loopback: config.chat.loopback,
+      modelListed: modelsRes.ok ? modelsRes.models.includes(config.chat.model) : null,
+      models: modelsRes.ok ? modelsRes.models : [],
+      error: chatRes.ok ? null : chatRes.error,
+    };
+  }
+
+  if (config.embed) {
+    const modelsRes = await localModels(config.embed, { allowRemote, fetchImpl });
+    if (modelsRes.socketOpened) socketsOpened += 1;
+    const embedRes = await localEmbed(config.embed, {
+      input: 'ping',
+      allowRemote,
+      fetchImpl,
+    });
+    if (embedRes.socketOpened) socketsOpened += 1;
+
+    if (!embedRes.ok) findings.push(`embed probe failed: ${embedRes.error}`);
+
+    embedReport = {
+      role: 'embed',
+      configured: true,
+      ok: embedRes.ok,
+      status: embedRes.ok ? 'ok' : 'unreachable',
+      url: config.embed.baseUrl,
+      model: config.embed.model,
+      responseModel: embedRes.ok ? embedRes.model : null,
+      loopback: config.embed.loopback,
+      modelListed: modelsRes.ok ? modelsRes.models.includes(config.embed.model) : null,
+      models: modelsRes.ok ? modelsRes.models : [],
+      dimensions: embedRes.ok ? embedRes.dimensions : null,
+      error: embedRes.ok ? null : embedRes.error,
+    };
+  }
+
+  const ok =
+    (chatReport === null || chatReport.ok) &&
+    (embedReport === null || embedReport.ok);
+
+  return {
+    ok,
+    configured: true,
+    status: ok ? 'ok' : 'unreachable',
+    allowRemote,
+    remoteBlocked: false,
+    socketsOpened,
+    chat: chatReport,
+    embed: embedReport,
+    findings,
+  };
+}

package/src/local/config.mjs

@@ -0,0 +1,234 @@
+// Local model configuration in `simt.json` / `simt-dev.json` (plan 0003 R37, ADR-075, ADR-090).
+//
+// Local models are optional and off by default. When `local` is absent from the manifest,
+// no socket is ever opened. When configured:
+//
+//   "local": {
+//     "chat":  { "url": "http://127.0.0.1:11434/v1", "model": "qwen2.5-coder:7b" },
+//     "embed": { "url": "http://127.0.0.1:11434/v1", "model": "nomic-embed-code" }
+//   }
+//
+// Non-loopback URLs are refused unless `--allow-remote` is explicitly passed (ADR-075).
+
+import { MANIFEST_FILE } from '../name.mjs';
+import { readManifest } from '../projection/manifest.mjs';
+
+/** Default per-request timeout for local model probes and requests, in milliseconds. */
+export const DEFAULT_LOCAL_TIMEOUT_MS = 5000;
+
+const ROLES = ['chat', 'embed'];
+
+const IPV4_LOOPBACK = /^127(?:\.(?:25[0-5]|2[0-4]\d|1?\d?\d)){3}$/;
+
+/**
+ * Whether a parsed URL hostname resolves strictly to the local loopback interface.
+ *
+ * Accepts `localhost` (and `*.localhost`), IPv4 `127.0.0.0/8`, and IPv6 `::1`.
+ * Wildcard bind addresses (`0.0.0.0`, `::`) and LAN/remote hosts return false.
+ */
+export function isLoopbackHost(hostname) {
+  if (typeof hostname !== 'string') return false;
+  const clean = hostname.trim().toLowerCase().replace(/^\[|\]$/g, '');
+  if (!clean) return false;
+  if (clean === 'localhost' || clean.endsWith('.localhost')) return true;
+  if (IPV4_LOOPBACK.test(clean)) return true;
+  if (clean === '::1' || clean === '0:0:0:0:0:0:0:1') return true;
+  return false;
+}
+
+/**
+ * Whether a URL string is a valid HTTP(S) loopback URL with no embedded credentials.
+ */
+export function isLoopbackUrl(urlString) {
+  if (typeof urlString !== 'string' || urlString.trim().length === 0) return false;
+  let parsed;
+  try {
+    parsed = new URL(urlString.trim());
+  } catch {
+    return false;
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return false;
+  if (parsed.username !== '' || parsed.password !== '') return false;
+  return isLoopbackHost(parsed.hostname);
+}
+
+/**
+ * Normalise an OpenAI-compatible base URL and append an endpoint path under `/v1`.
+ *
+ * Accepts base URLs written either with or without a trailing `/v1` (for example
+ * `http://127.0.0.1:11434` or `http://127.0.0.1:11434/v1`) so Ollama, llama.cpp
+ * `llama-server`, LM Studio and MLX configs work identically.
+ */
+export function resolveEndpointUrl(baseUrl, endpointPath = '') {
+  const trimmedBase = String(baseUrl ?? '').trim().replace(/\/+$/, '');
+  const baseWithV1 = trimmedBase.endsWith('/v1') ? trimmedBase : `${trimmedBase}/v1`;
+  const cleanPath = String(endpointPath ?? '')
+    .trim()
+    .replace(/^\/+/, '')
+    .replace(/^v1(?:\/+|$)/, '');
+  return cleanPath ? `${baseWithV1}/${cleanPath}` : baseWithV1;
+}
+
+function parseEndpoint(role, entry, { allowRemote = false } = {}) {
+  if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+    return { endpoint: null, finding: `\`local.${role}\` must be an object with \`url\` and \`model\`` };
+  }
+
+  const rawUrl = typeof entry.url === 'string' ? entry.url.trim() : '';
+  if (!rawUrl) {
+    return { endpoint: null, finding: `\`local.${role}.url\` is required` };
+  }
+
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(rawUrl);
+  } catch {
+    return { endpoint: null, finding: `\`local.${role}.url\` (${rawUrl}) is not a valid URL` };
+  }
+
+  if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+    return {
+      endpoint: null,
+      finding: `\`local.${role}.url\` (${rawUrl}) must use http:// or https://`,
+    };
+  }
+
+  if (parsedUrl.username !== '' || parsedUrl.password !== '') {
+    return {
+      endpoint: null,
+      finding: `\`local.${role}.url\` must not embed credentials in the URL`,
+    };
+  }
+
+  const model = typeof entry.model === 'string' ? entry.model.trim() : '';
+  if (!model) {
+    return { endpoint: null, finding: `\`local.${role}.model\` is required` };
+  }
+
+  const timeoutMs = entry.timeoutMs === undefined ? DEFAULT_LOCAL_TIMEOUT_MS : entry.timeoutMs;
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+    return {
+      endpoint: null,
+      finding: `\`local.${role}.timeoutMs\` must be a positive whole number`,
+    };
+  }
+
+  const loopback = isLoopbackHost(parsedUrl.hostname);
+  const baseUrl = resolveEndpointUrl(rawUrl, '');
+  const blocked = !loopback && !allowRemote;
+
+  if (blocked) {
+    return {
+      endpoint: {
+        role,
+        url: rawUrl,
+        baseUrl,
+        model,
+        timeoutMs,
+        loopback: false,
+        blocked: true,
+      },
+      remoteBlocked: true,
+      finding: `\`local.${role}.url\` (${rawUrl}) is not a loopback address; non-loopback URLs are refused without --allow-remote (ADR-075)`,
+    };
+  }
+
+  return {
+    endpoint: {
+      role,
+      url: rawUrl,
+      baseUrl,
+      model,
+      timeoutMs,
+      loopback,
+      blocked: false,
+    },
+    remoteBlocked: false,
+    finding: null,
+  };
+}
+
+/**
+ * Parse and validate the `local` block of a manifest. Pure: never opens a file or socket.
+ */
+export function parseLocalConfig(manifest, { allowRemote = false } = {}) {
+  const block = manifest?.local;
+  if (block === undefined || block === null) {
+    return { configured: false, chat: null, embed: null, findings: [], remoteBlocked: false };
+  }
+  if (typeof block !== 'object' || Array.isArray(block)) {
+    return {
+      configured: true,
+      chat: null,
+      embed: null,
+      findings: ['`local` must be an object'],
+      remoteBlocked: false,
+    };
+  }
+
+  const findings = [];
+  let remoteBlocked = false;
+
+  for (const key of Object.keys(block)) {
+    if (!ROLES.includes(key)) {
+      findings.push(`\`local.${key}\` is not a recognised local model role (expected \`chat\` or \`embed\`)`);
+    }
+  }
+
+  const parsedRoles = { chat: null, embed: null };
+  for (const role of ROLES) {
+    const raw = block[role];
+    if (raw === undefined || raw === null) continue;
+    const parsed = parseEndpoint(role, raw, { allowRemote });
+    parsedRoles[role] = parsed.endpoint;
+    if (parsed.remoteBlocked) remoteBlocked = true;
+    if (parsed.finding) findings.push(parsed.finding);
+  }
+
+  const configured =
+    parsedRoles.chat !== null ||
+    parsedRoles.embed !== null ||
+    findings.length > 0;
+
+  return {
+    configured,
+    chat: parsedRoles.chat,
+    embed: parsedRoles.embed,
+    findings,
+    remoteBlocked,
+  };
+}
+
+/**
+ * Read and validate the `local` block from a repository's manifest on disk.
+ */
+export async function readLocalConfig(root, { allowRemote = false } = {}) {
+  const { manifest, exists, error } = await readManifest(root);
+  if (!exists) {
+    return {
+      configured: false,
+      chat: null,
+      embed: null,
+      findings: [],
+      remoteBlocked: false,
+      manifestExists: false,
+      manifestError: null,
+    };
+  }
+  if (error !== null || manifest === null) {
+    return {
+      configured: false,
+      chat: null,
+      embed: null,
+      findings: [`${MANIFEST_FILE} is ${error ?? 'unreadable'}`],
+      remoteBlocked: false,
+      manifestExists: true,
+      manifestError: error ?? 'unreadable',
+    };
+  }
+  return {
+    ...parseLocalConfig(manifest, { allowRemote }),
+    manifestExists: true,
+    manifestError: null,
+  };
+}