@aikdna/kdna-studio-cli 0.10.2 → 0.11.0

package/src/llm/config.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const { canonicalLlmBaseUrl } = require('./transport');
 
 const ENV_PREFIX = 'KDNA_LLM_';
 
@@ -14,8 +15,8 @@ const WELL_KNOWN = {
   gemini: { baseURL: 'https://generativelanguage.googleapis.com/v1beta', models: ['gemini-2.5-flash', 'gemini-2.5-pro'] },
   perplexity: { baseURL: 'https://api.perplexity.ai', models: ['sonar-pro', 'sonar'] },
   groq: { baseURL: 'https://api.groq.com/openai/v1', models: ['llama-4-scout-17b-16e-instruct', 'deepseek-r1-distill-llama-70b'] },
-  local: { baseURL: 'http://localhost:11434/v1', models: ['llama3.2'] },
-  ollama: { baseURL: 'http://localhost:11434/v1', models: ['llama3.2'] },
+  local: { baseURL: 'http://127.0.0.1:11434/v1', models: ['llama3.2'] },
+  ollama: { baseURL: 'http://127.0.0.1:11434/v1', models: ['llama3.2'] },
   openai_compatible: { baseURL: null, models: [] },
 };
 
@@ -66,10 +67,14 @@ function loadConfig() {
 }
 
 function saveConfig(updates) {
+  const safeUpdates = { ...updates };
+  if (Object.prototype.hasOwnProperty.call(safeUpdates, 'baseURL')) {
+    safeUpdates.baseURL = canonicalLlmBaseUrl(safeUpdates.baseURL);
+  }
   const configPath = path.join(os.homedir(), '.kdna', 'config.json');
   let existing = {};
   try { if (fs.existsSync(configPath)) existing = JSON.parse(fs.readFileSync(configPath, 'utf8')); } catch (e) { console.error('Error reading config file for save:', e.message); }
-  existing.llm = { ...(existing.llm || {}), ...updates };
+  existing.llm = { ...(existing.llm || {}), ...safeUpdates };
   fs.mkdirSync(path.dirname(configPath), { recursive: true });
   fs.writeFileSync(configPath, JSON.stringify(existing, null, 2) + '\n');
 }
@@ -79,6 +84,14 @@ function validateConfig(config) {
   if (!config.provider) errors.push('Missing KDNA_LLM_PROVIDER. Set via env var or ~/.kdna/config.json');
   if (!config.apiKey) errors.push('Missing KDNA_LLM_API_KEY');
   if (!config.model) errors.push('Missing KDNA_LLM_MODEL');
+  if (!config.baseURL) errors.push('Missing KDNA_LLM_BASE_URL');
+  else {
+    try {
+      canonicalLlmBaseUrl(config.baseURL);
+    } catch {
+      errors.push('Invalid KDNA_LLM_BASE_URL: external providers require HTTPS; HTTP is loopback-only');
+    }
+  }
   return { valid: errors.length === 0, errors };
 }
 

package/src/llm/index.js

@@ -29,12 +29,12 @@ async function chatWithJSON(messages, options = {}) {
   const result = await chat(messages, { ...options, responseFormat: { type: 'json_object' } });
   try {
     result.data = JSON.parse(result.content);
-  } catch (e) {
-    console.error('Error parsing LLM JSON response:', e.message);
+  } catch {
+    console.error('Error parsing LLM JSON response.');
     // Try to extract JSON from markdown code blocks
     const match = result.content.match(/```(?:json)?\s*([\s\S]*?)```/);
     if (match) {
-      try { result.data = JSON.parse(match[1].trim()); } catch (e2) { console.error('Error parsing JSON from markdown code block:', e2.message); }
+      try { result.data = JSON.parse(match[1].trim()); } catch { console.error('Error parsing JSON from markdown code block.'); }
     }
   }
   return result;

package/src/llm/providers/anthropic.js

@@ -1,7 +1,8 @@
 // Anthropic Messages API provider
 
+const { postLlmJson } = require('../transport');
+
 async function chat(config, messages, options = {}) {
-  const url = `${config.baseURL}/messages`;
   const model = options.model || config.model;
   const maxTokens = options.maxTokens || config.maxTokens || 4096;
 
@@ -21,12 +22,12 @@ async function chat(config, messages, options = {}) {
     'anthropic-version': '2023-06-01',
   };
 
-  const res = await fetch(url, { method: 'POST', headers, body: JSON.stringify(body), signal: AbortSignal.timeout(120000) });
-  if (!res.ok) {
-    const text = await res.text();
-    throw new Error(`Anthropic API error ${res.status}: ${text.slice(0, 500)}`);
-  }
-  const data = await res.json();
+  const data = await postLlmJson({
+    baseUrl: config.baseURL,
+    endpoint: '/messages',
+    headers,
+    body,
+  });
   const content = data.content?.[0]?.text;
   if (!content) throw new Error('Anthropic returned empty response');
 

package/src/llm/providers/openai.js

@@ -1,8 +1,9 @@
 // OpenAI-compatible chat completions provider
 // Works with: OpenAI, DeepSeek, OpenRouter, Groq, Ollama, LM Studio, Perplexity, and any OpenAI-compatible API
 
+const { postLlmJson } = require('../transport');
+
 async function chat(config, messages, options = {}) {
-  const url = `${config.baseURL}/chat/completions`;
   const model = options.model || config.model;
   const temperature = options.temperature ?? config.temperature ?? 0.7;
   const maxTokens = options.maxTokens || config.maxTokens || 4096;
@@ -22,12 +23,12 @@ async function chat(config, messages, options = {}) {
     headers['X-Title'] = 'KDNA Studio CLI';
   }
 
-  const res = await fetch(url, { method: 'POST', headers, body: JSON.stringify(body), signal: AbortSignal.timeout(120000) });
-  if (!res.ok) {
-    const text = await res.text();
-    throw new Error(`LLM API error ${res.status}: ${text.slice(0, 500)}`);
-  }
-  const data = await res.json();
+  const data = await postLlmJson({
+    baseUrl: config.baseURL,
+    endpoint: '/chat/completions',
+    headers,
+    body,
+  });
   const content = data.choices?.[0]?.message?.content;
   if (!content) throw new Error('LLM returned empty response');
 

package/src/llm/transport.js

@@ -0,0 +1,196 @@
+'use strict';
+
+/**
+ * Transport boundary for supported AI authoring providers.
+ *
+ * Requests contain provider credentials plus source evidence, interview
+ * answers, or other judgment-authoring material. External providers must use
+ * HTTPS. Plain HTTP is limited to exact numeric loopback development hosts;
+ * localhost, LAN addresses, and arbitrary hostnames are not exceptions.
+ */
+
+const MAX_LLM_URL_BYTES = 2048;
+const MAX_LLM_RESPONSE_BYTES = 4 * 1024 * 1024;
+const ALLOWED_ENDPOINTS = new Set(['/chat/completions', '/messages']);
+
+class LlmTransportError extends Error {
+  constructor(code, message, status = null) {
+    super(message);
+    this.name = 'LlmTransportError';
+    this.code = code;
+    this.status = Number.isInteger(status) ? status : null;
+  }
+}
+
+function isExactLoopback(hostname) {
+  return hostname === '127.0.0.1' || hostname === '[::1]';
+}
+
+function canonicalLlmBaseUrl(value) {
+  if (
+    typeof value !== 'string' ||
+    value.length === 0 ||
+    Buffer.byteLength(value, 'utf8') > MAX_LLM_URL_BYTES ||
+    [...value].some((character) => {
+      const codePoint = character.codePointAt(0);
+      return (
+        character === '\\' ||
+        character === '?' ||
+        character === '#' ||
+        codePoint < 0x21 ||
+        codePoint > 0x7e
+      );
+    })
+  ) {
+    throw new LlmTransportError(
+      'LLM_URL_REFUSED',
+      'LLM base URL must be a canonical visible-ASCII URL.',
+    );
+  }
+
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new LlmTransportError('LLM_URL_REFUSED', 'LLM base URL must be absolute.');
+  }
+  if (
+    !parsed.hostname ||
+    parsed.username ||
+    parsed.password ||
+    parsed.search ||
+    parsed.hash ||
+    parsed.pathname.includes('%') ||
+    parsed.pathname
+      .split('/')
+      .some((segment, index) =>
+        segment === '.' ||
+        segment === '..' ||
+        (index > 0 && segment === '' && parsed.pathname !== '/'))
+  ) {
+    throw new LlmTransportError(
+      'LLM_URL_REFUSED',
+      'LLM base URL contains credentials or an unsupported component.',
+    );
+  }
+  if (
+    parsed.protocol !== 'https:' &&
+    !(parsed.protocol === 'http:' && isExactLoopback(parsed.hostname))
+  ) {
+    throw new LlmTransportError(
+      'LLM_URL_REFUSED',
+      'LLM base URL must use HTTPS except for an exact loopback HTTP origin.',
+    );
+  }
+
+  const canonical = parsed.pathname === '/' ? parsed.origin : `${parsed.origin}${parsed.pathname}`;
+  if (value !== canonical || (parsed.pathname !== '/' && parsed.pathname.endsWith('/'))) {
+    throw new LlmTransportError('LLM_URL_REFUSED', 'LLM base URL is not canonical.');
+  }
+  return canonical;
+}
+
+function providerEndpoint(baseUrl, endpoint) {
+  if (!ALLOWED_ENDPOINTS.has(endpoint)) {
+    throw new LlmTransportError('LLM_URL_REFUSED', 'LLM provider endpoint is not admitted.');
+  }
+  return `${canonicalLlmBaseUrl(baseUrl)}${endpoint}`;
+}
+
+async function refuseInvalidResponse(response) {
+  try {
+    await response.body?.cancel();
+  } catch {
+    // Response bytes never cross the transport boundary.
+  }
+  throw new LlmTransportError('LLM_RESPONSE_INVALID', 'LLM provider returned an invalid response.');
+}
+
+async function readBoundedJson(response) {
+  const contentType = response.headers.get('content-type') || '';
+  if (!/^application\/json(?:\s*;\s*charset=utf-8)?$/i.test(contentType)) {
+    return refuseInvalidResponse(response);
+  }
+  const contentLength = response.headers.get('content-length');
+  if (
+    contentLength !== null &&
+    (!/^(0|[1-9]\d*)$/.test(contentLength) || Number(contentLength) > MAX_LLM_RESPONSE_BYTES)
+  ) {
+    return refuseInvalidResponse(response);
+  }
+  if (!response.body) {
+    return refuseInvalidResponse(response);
+  }
+
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > MAX_LLM_RESPONSE_BYTES) {
+        await reader.cancel();
+        throw new LlmTransportError(
+          'LLM_RESPONSE_INVALID',
+          'LLM provider returned an invalid response.',
+        );
+      }
+      chunks.push(Buffer.from(value));
+    }
+    const text = new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks, total));
+    const payload = JSON.parse(text);
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+      throw new Error('not an object');
+    }
+    return payload;
+  } catch (error) {
+    if (error instanceof LlmTransportError) throw error;
+    throw new LlmTransportError('LLM_RESPONSE_INVALID', 'LLM provider returned an invalid response.');
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+async function postLlmJson({ baseUrl, endpoint, headers, body, timeoutMs = 120000 }) {
+  const url = providerEndpoint(baseUrl, endpoint);
+  let response;
+  try {
+    response = await fetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+      redirect: 'error',
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch {
+    throw new LlmTransportError(
+      'LLM_TRANSPORT_FAILED',
+      'LLM provider request failed [LLM_TRANSPORT_FAILED].',
+    );
+  }
+
+  if (!response.ok) {
+    try {
+      await response.body?.cancel();
+    } catch {
+      // Nothing from the provider response crosses the error boundary.
+    }
+    throw new LlmTransportError(
+      'LLM_HTTP_ERROR',
+      `LLM provider rejected the request [LLM_HTTP_ERROR] (HTTP ${response.status}).`,
+      response.status,
+    );
+  }
+  return readBoundedJson(response);
+}
+
+module.exports = {
+  LlmTransportError,
+  MAX_LLM_RESPONSE_BYTES,
+  canonicalLlmBaseUrl,
+  isExactLoopback,
+  postLlmJson,
+  providerEndpoint,
+};

package/src/ai/feynman.js

@@ -1,120 +0,0 @@
-// Feynman Evaluation — AI-driven assessment of understanding quality
-const llm = require('../llm');
-
-const CRITERIA = {
-  notJustRepeat: 'NOT just repeating the axiom text verbatim — uses different words/phrasing',
-  notTooAbstract: 'NOT too abstract — grounds the explanation in concrete terms',
-  hasConcreteExample: 'Provides at least one specific, realistic example or scenario',
-  clarifiesBoundary: 'Makes clear when the judgment does NOT apply (boundary awareness)',
-  ordinaryPersonUnderstands: 'Would make sense to someone unfamiliar with the domain',
-};
-
-const SYSTEM = `You are a Feynman evaluation engine. Your task is to assess how well someone understands a judgment principle based on their restatement of it in their own words.
-
-Evaluate the restatement on these 5 criteria (each YES/NO):
-${Object.entries(CRITERIA).map(([k, v]) => `- ${k}: ${v}`).join('\n')}
-
-Also provide a brief explanation for each criterion (1-2 sentences) and a suggested improvement if any criterion fails.
-
-Return ONLY valid JSON:
-{
-  "score": <0-5 integer>,
-  "criteria": {
-    "notJustRepeat": true/false,
-    "notTooAbstract": true/false,
-    "hasConcreteExample": true/false,
-    "clarifiesBoundary": true/false,
-    "ordinaryPersonUnderstands": true/false
-  },
-  "explanations": { "<criterion>": "<explanation>" },
-  "suggestions": ["<improvement suggestion>"]
-}`;
-
-async function evaluate(config, card, options = {}) {
-  // Bug: prior version read `card.feynman_text` (a field nothing in the
-  // codebase ever wrote) and flattened `card.one_sentence` /
-  // `card.full_statement` — the schema actually nests those under
-  // `card.fields`. The AI evaluator therefore always received an empty
-  // restatement and a blank axiom, no matter what was in the project.
-  // The fix reads the canonical schema field names and the nested
-  // `fields` object, with a fallback for callers that pass the flattened
-  // shape directly.
-  const fields = (card && card.fields) || card || {};
-  const axiomText = fields.one_sentence || fields.full_statement || fields.question || '';
-  const restatement = card.feynman_restatement
-    || fields.feynman_restatement
-    // NOTE: fields.feynman_text was previously in this fallback chain
-    // but is intentionally excluded — no code path in @aikdna writes
-    // feynman_text. The canonical field is feynman_restatement.
-    || '';
-
-  if (!restatement) {
-    // Bug (#62): prior version returned score 0 with the explanation
-    // "No Feynman restatement provided", but nothing in the CLI ever
-    // *writes* a feynman_restatement on a card. Every `kdna-studio
-    // feynman` call hit this path, every call returned 0, and the
-    // fynchmann command was effectively dead.
-    //
-    // The fix synthesises a first-cut restatement from the card's own
-    // text (so the LLM has *something* to evaluate), and returns a
-    // structured note in `suggestions` so the caller knows the score
-    // is on a machine-generated restatement, not their own. The
-    // caller can then `card update --field feynman_restatement='...'`
-    // to lock in a human-written version.
-    const synthesised = synthFeynmanRestatement(fields);
-    return {
-      score: 0,
-      criteria: {},
-      explanations: {
-        notJustRepeat: 'No human-written Feynman restatement — evaluated a synthesised one.',
-        notTooAbstract: 'Review the synthesised restatement before trusting the score.',
-      },
-      suggestions: [
-        'No feynman_restatement found on this card. The score below is on an auto-generated restatement.',
-        `Set a human-written restatement: kdna-studio card update <project> ${card.id || '<card-id>'} --field feynman_restatement='{"text":"<your plain-language restatement>"}'`,
-        `Synthesised restatement: "${synthesised}"`,
-      ],
-      synthesised_restatement: synthesised,
-    };
-  }
-
-  const userPrompt = [
-    `## Original Axiom`,
-    `"${axiomText}"`,
-    ``,
-    `## User's Restatement (Feynman)`,
-    `"${restatement}"`,
-    ``,
-    `Evaluate this restatement.`,
-  ].join('\n');
-
-  const result = await llm.chatWithJSON([
-    { role: 'system', content: SYSTEM },
-    { role: 'user', content: userPrompt },
-  ], options);
-
-  return result.data || { score: 0, criteria: {}, explanations: {}, suggestions: [] };
-}
-
-// Synthesise a first-cut restatement from the card's own fields. The
-// output is intentionally plain — Feynman is "explain it like I'm
-// five", so we strip axiom-speak and surface only the human-readable
-// core.
-function synthFeynmanRestatement(fields) {
-  const text = fields.one_sentence
-    || fields.full_statement
-    || fields.question
-    || fields.essence
-    || fields.scope
-    || '(no text to restate)';
-  // Strip the leading "always/never/must" markers that signal axiom
-  // language. The LLM evaluator will then score the result on its
-  // own merits, but the human reader can already see plain English.
-  return String(text)
-    .replace(/^(always|never|must|should|shall)\s+/i, '')
-    .replace(/\s+always\s+/gi, ' ')
-    .replace(/\s+never\s+/gi, ' ')
-    .trim();
-}
-
-module.exports = { evaluate, CRITERIA, SYSTEM, synthFeynmanRestatement };

package/src/ai/testlab.js

@@ -1,73 +0,0 @@
-// TestLab — A/B comparison testing with LLM
-const llm = require('../llm');
-
-const COMPARE_SYSTEM = `You are a controlled experiment evaluator. You will see the same user input twice — once with a knowledge domain loaded, and once without. Your task is to produce a structured comparison.
-
-IMPORTANT: You must respond with raw JSON only, no markdown wrapping, no explanatory text.
-
-The JSON format:
-{
-  "without_kdna": {
-    "response": "how you would respond WITHOUT the domain knowledge",
-    "classification": "how you categorized the task",
-    "diagnosis": "your analysis of the situation",
-    "actions": "what actions you would take"
-  },
-  "with_kdna": {
-    "response": "how you respond WITH the domain knowledge applied",
-    "classification": "domain-specific classification from the loaded domain",
-    "diagnosis": "analysis informed by domain axioms and ontology",
-    "actions": "actions influenced by domain judgment"
-  },
-  "delta": {
-    "classification_changed": true/false,
-    "diagnosis_changed": true/false,
-    "actions_changed": true/false,
-    "terminology_changed": true/false,
-    "overall_impact": "none" | "minor" | "moderate" | "significant"
-  }
-}`;
-
-async function compare(config, domainName, input, domainPrompt, options = {}) {
-  // Run WITHOUT KDNA
-  const withoutResult = await llm.chat([
-    { role: 'system', content: COMPARE_SYSTEM },
-    { role: 'user', content: `Respond to the following WITHOUT any special domain knowledge:\n\n${input}\n\nRespond with the structured JSON comparison format. For the "without_kdna" section, fill in your normal response. For the "with_kdna" section, fill in what you think would change (we will verify this in a separate pass).` },
-  ], { ...options, responseFormat: { type: 'json_object' } });
-
-  let withoutData;
-  try { withoutData = JSON.parse(withoutResult.content); } catch { withoutData = { without_kdna: { response: withoutResult.content } }; }
-
-  // Run WITH KDNA
-  const withResult = await llm.chat([
-    { role: 'system', content: `${domainPrompt}\n\n${COMPARE_SYSTEM}` },
-    { role: 'user', content: `Respond to the following WITH the domain knowledge loaded:\n\n${input}\n\nRespond with the structured JSON comparison format. Fill in the "with_kdna" section and the "delta" section based on what actually changed.` },
-  ], { ...options, responseFormat: { type: 'json_object' } });
-
-  let withData;
-  try { withData = JSON.parse(withResult.content); } catch { withData = { with_kdna: { response: withResult.content } }; }
-
-  return {
-    input,
-    domain: domainName,
-    without_kdna: withoutData.without_kdna || { response: withoutResult.content },
-    with_kdna: withData.with_kdna || { response: withResult.content },
-    delta: withData.delta || { overall_impact: 'unknown' },
-  };
-}
-
-async function testPreset(config, domainName, input, domainPrompt, options = {}) {
-  const presets = {
-    baseline: `Test the core judgment: ${input}`,
-    edge_case: `Test a boundary case where domain judgment may or may not apply: ${input}`,
-    contradiction: `Test for potential contradiction: present a scenario that challenges the domain's axioms: ${input}`,
-  };
-
-  const results = {};
-  for (const [name, prompt] of Object.entries(presets)) {
-    results[name] = await compare(config, domainName, prompt, domainPrompt, options);
-  }
-  return results;
-}
-
-module.exports = { compare, testPreset, COMPARE_SYSTEM };