@instruktlabs/kiln 1.0.0 → 1.2.0

package/scripts/workspace-config.mjs

@@ -0,0 +1,239 @@
+/** Shared configuration edits for local project integrations. Never writes files. */
+import { isDeepStrictEqual } from 'node:util';
+import { applyEdits, getNodeValue, modify, parseTree } from 'jsonc-parser';
+import { parse as parseToml } from 'smol-toml';
+
+const maxLength = 2 * 1024 * 1024;
+const forbidden = new Set(['__proto__', 'prototype', 'constructor']);
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const conflict = (path) =>
+  new Error(`Configuration conflict at ${path.join('.')}; no files were changed.`);
+
+function checkPath(path) {
+  if (
+    !Array.isArray(path) ||
+    !path.length ||
+    path.length > 16 ||
+    path.some(
+      (part) => typeof part !== 'string' || !/^[a-zA-Z0-9_-]+$/.test(part) || forbidden.has(part),
+    )
+  )
+    throw new Error('Invalid configuration path.');
+}
+
+function checkText(text, kind) {
+  if (typeof text !== 'string' || text.length > maxLength)
+    throw new Error(`Invalid ${kind} configuration.`);
+}
+
+function jsonTree(text, comments) {
+  checkText(text, 'JSON');
+  try {
+    const errors = [];
+    const root = parseTree(text, errors, {
+      disallowComments: !comments,
+      allowTrailingComma: comments,
+    });
+    if (errors.length || root?.type !== 'object') throw new Error();
+    let count = 0;
+    const visit = (node, depth = 0) => {
+      if (++count > 100000 || depth > 64) throw new Error();
+      if (node.type === 'object') {
+        const keys = new Set();
+        for (const property of node.children ?? []) {
+          const key = property.children[0].value;
+          if (keys.has(key)) throw new Error();
+          keys.add(key);
+        }
+      }
+      for (const child of node.children ?? []) visit(child, depth + 1);
+    };
+    visit(root);
+    return root;
+  } catch {
+    // Parser messages can include source lines containing user credentials.
+    throw new Error('Invalid JSON configuration.');
+  }
+}
+
+function jsonEntry(root, path) {
+  let node = root;
+  for (const part of path) {
+    if (node === undefined) return undefined;
+    if (node.type !== 'object') throw conflict(path);
+    node = node.children?.find((property) => property.children[0].value === part)?.children[1];
+  }
+  return node;
+}
+
+function jsonValue(value) {
+  try {
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined || !isDeepStrictEqual(JSON.parse(serialized), value))
+      throw new Error();
+    jsonTree(`{"value":${serialized}}`, false);
+    return value;
+  } catch {
+    throw new Error('Invalid configuration value.');
+  }
+}
+
+function equalJson(a, b) {
+  if (Object.is(a, b)) return true;
+  if (
+    !a ||
+    !b ||
+    typeof a !== 'object' ||
+    typeof b !== 'object' ||
+    Array.isArray(a) !== Array.isArray(b)
+  )
+    return false;
+  const keys = Object.keys(a);
+  return (
+    keys.length === Object.keys(b).length &&
+    keys.every((key) => Object.hasOwn(b, key) && equalJson(a[key], b[key]))
+  );
+}
+
+function checkOwnedNumbers(node, path) {
+  if (
+    node.type === 'number' &&
+    (!Number.isFinite(node.value) ||
+      (Number.isInteger(node.value) && !Number.isSafeInteger(node.value)))
+  )
+    throw conflict(path);
+  for (const child of node.children ?? []) checkOwnedNumbers(child, path);
+}
+
+/** Apply non-overlapping owned entries; unrelated JSON bytes are not reserialized. */
+export function mergeJsonConfig(text, changes, { comments = false } = {}) {
+  checkText(text, 'JSON');
+  if (!Array.isArray(changes) || changes.length > 64)
+    throw new Error('Invalid configuration edits.');
+  for (const change of changes) {
+    checkPath(change?.path);
+    jsonValue(change.value);
+    if (Object.hasOwn(change, 'previous')) jsonValue(change.previous);
+  }
+  for (let i = 0; i < changes.length; i++)
+    for (let j = i + 1; j < changes.length; j++) {
+      const a = changes[i].path,
+        b = changes[j].path;
+      if (a.slice(0, Math.min(a.length, b.length)).every((part, k) => part === b[k]))
+        throw new Error('Overlapping configuration edits.');
+    }
+  let result = text.trim() ? text : `${text}{}\n`;
+  let root = jsonTree(result, comments);
+  for (const change of changes) {
+    const node = jsonEntry(root, change.path);
+    if (node !== undefined) {
+      checkOwnedNumbers(node, change.path);
+      const current = getNodeValue(node);
+      if (equalJson(current, change.value)) continue;
+      if (!Object.hasOwn(change, 'previous') || !equalJson(current, change.previous))
+        throw conflict(change.path);
+    }
+    // No whole-document formatter: preserve comments, large numbers and unrelated bytes.
+    result = applyEdits(result, modify(result, change.path, change.value, {}));
+    root = jsonTree(result, comments);
+  }
+  return result;
+}
+
+function toml(text) {
+  checkText(text, 'TOML');
+  try {
+    return parseToml(text, { integersAsBigInt: true });
+  } catch {
+    throw new Error('Invalid TOML configuration.');
+  }
+}
+
+function entry(root, path) {
+  let value = root;
+  for (const part of path) {
+    if (!object(value)) throw conflict(path);
+    if (!Object.hasOwn(value, part)) return undefined;
+    value = value[part];
+  }
+  return value;
+}
+
+function withoutEntry(root, path) {
+  const result = { ...root };
+  const [key, ...rest] = path;
+  if (Object.hasOwn(result, key)) {
+    if (!rest.length) delete result[key];
+    else {
+      result[key] = withoutEntry(result[key], rest);
+      if (!Object.keys(result[key]).length) delete result[key];
+    }
+  }
+  return result;
+}
+
+function fragmentValue(fragment, path) {
+  const parsed = toml(fragment);
+  const value = entry(parsed, path);
+  if (
+    !object(value) ||
+    !Object.keys(value).length ||
+    Object.keys(withoutEntry(parsed, path)).length
+  )
+    throw new Error('Invalid managed TOML fragment.');
+  return value;
+}
+
+function markerLines(text, marker) {
+  const offsets = [];
+  let offset = 0;
+  for (const line of text.split('\n')) {
+    if (line.replace(/\r$/, '') === marker) offsets.push(offset);
+    offset += line.length + 1;
+  }
+  return offsets;
+}
+
+/** TOML is preserved verbatim outside a validated, exclusively owned table block. */
+export function mergeTomlConfig(text, { path, fragment, previous } = {}) {
+  checkPath(path);
+  const original = toml(text);
+  const desired = fragmentValue(fragment, path);
+  if (previous !== undefined) fragmentValue(previous, path);
+  const start = `# BEGIN KILN ${JSON.stringify(path)}`;
+  const end = `# END KILN ${JSON.stringify(path)}`;
+  const starts = markerLines(text, start),
+    ends = markerLines(text, end);
+  const newline = text.includes('\r\n') ? '\r\n' : '\n';
+  const block = (value) =>
+    `${start}${newline}${value.replace(/\r\n/g, '\n').trim().replace(/\n/g, newline)}${newline}${end}${newline}`;
+  let prefix = text,
+    suffix = '',
+    base = original;
+  if (starts.length || ends.length) {
+    if (starts.length !== 1 || ends.length !== 1 || starts[0] >= ends[0]) throw conflict(path);
+    const afterLine = text.indexOf('\n', ends[0]);
+    const after = afterLine < 0 ? text.length : afterLine + 1;
+    if (text.slice(starts[0], after) !== block(previous ?? fragment)) throw conflict(path);
+    prefix = text.slice(0, starts[0]);
+    suffix = text.slice(after);
+    base = toml(prefix + suffix);
+    if (
+      entry(base, path) !== undefined ||
+      !isDeepStrictEqual(entry(original, path), fragmentValue(previous ?? fragment, path)) ||
+      !isDeepStrictEqual(withoutEntry(original, path), withoutEntry(base, path))
+    )
+      throw conflict(path);
+  } else {
+    if (entry(original, path) !== undefined) throw conflict(path);
+    if (prefix && !prefix.endsWith('\n')) prefix += newline;
+  }
+  const result = prefix + block(fragment) + suffix;
+  const parsed = toml(result);
+  if (
+    !isDeepStrictEqual(entry(parsed, path), desired) ||
+    !isDeepStrictEqual(withoutEntry(parsed, path), withoutEntry(base, path))
+  )
+    throw conflict(path);
+  return result;
+}

package/scripts/workspace-project.mjs

@@ -0,0 +1,384 @@
+/** Shared project adoption and maintenance, independent of any one agent client. */
+import { createHash } from 'node:crypto';
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getNodeValue, parseTree } from 'jsonc-parser';
+import { mergeJsonConfig, mergeTomlConfig } from './workspace-config.mjs';
+import { applyProjectEdits, readProjectFile } from './workspace-transaction.mjs';
+
+const hash = (value) =>
+  value === undefined ? undefined : createHash('sha256').update(value).digest('hex');
+const digestPattern = /^[a-f0-9]{64}$/;
+const text = (value, name) => {
+  try {
+    return value === undefined ? '' : new TextDecoder('utf-8', { fatal: true }).decode(value);
+  } catch {
+    throw new Error(`Invalid UTF-8 project configuration: ${name}`);
+  }
+};
+const descriptorKey = (value) => JSON.stringify([value.file, value.path]);
+const object = (value) => value && typeof value === 'object' && !Array.isArray(value);
+
+function configProjection(file, body) {
+  if (file === '.codex/config.toml')
+    return [{ file, kind: 'toml', path: ['mcp_servers', 'kiln_workspace'], fragment: body }];
+  if (file === 'opencode.json') {
+    const value = JSON.parse(body);
+    return [
+      {
+        file,
+        kind: 'json',
+        path: ['mcp', 'kiln_workspace'],
+        value: value.mcp.kiln_workspace,
+        comments: true,
+      },
+      {
+        file,
+        kind: 'json-list',
+        path: ['skills', 'paths'],
+        value: value.skills.paths[0],
+        comments: true,
+      },
+    ];
+  }
+  if (['.mcp.json', '.cursor/mcp.json', '.agents/mcp_config.json'].includes(file))
+    return [
+      {
+        file,
+        kind: 'json',
+        path: ['mcpServers', 'kiln_workspace'],
+        value: JSON.parse(body).mcpServers.kiln_workspace,
+      },
+    ];
+  return [];
+}
+
+function validatePrevious(previous, allowedNames, skills, knownConfigs, allowedHarnesses) {
+  if (!previous) return;
+  if (![1, 2].includes(previous.schemaVersion))
+    throw new Error('Unsupported workspace manifest version.');
+  if (!allowedHarnesses.includes(previous.harness))
+    throw new Error('Invalid workspace harness manifest.');
+  const ownedName = (name) => {
+    if (
+      typeof name !== 'string' ||
+      name.includes('\\') ||
+      name.includes(':') ||
+      name.split('/').some((p) => !p || p === '.' || p === '..')
+    )
+      return false;
+    if (allowedNames.has(name)) return true;
+    for (const prefix of ['skills/', '.claude/skills/', '.agents/skills/']) {
+      if (name.startsWith(prefix) && skills.includes(name.slice(prefix.length).split('/')[0]))
+        return true;
+    }
+    return false;
+  };
+  for (const map of [previous.ownedFiles, previous.managedHashes, previous.generated]) {
+    if (
+      map !== undefined &&
+      (!object(map) ||
+        Object.entries(map).some(
+          ([name, value]) =>
+            !ownedName(name) || typeof value !== 'string' || !digestPattern.test(value),
+        ))
+    )
+      throw new Error('Invalid managed-file manifest.');
+  }
+  if (previous.schemaVersion === 2) {
+    if (!Array.isArray(previous.configEntries) || previous.configEntries.length > 32)
+      throw new Error('Invalid configuration ownership manifest.');
+    const seen = new Set();
+    for (const entry of previous.configEntries) {
+      const key = descriptorKey(entry);
+      if (!knownConfigs.has(key) || entry.kind !== knownConfigs.get(key).kind || seen.has(key))
+        throw new Error('Invalid configuration ownership manifest.');
+      seen.add(key);
+    }
+  }
+}
+
+function listValue(content, path) {
+  const errors = [];
+  const tree = parseTree(content, errors, { allowTrailingComma: true });
+  if (errors.length || tree?.type !== 'object') throw new Error('Invalid JSON configuration.');
+  let value = getNodeValue(tree);
+  for (const part of path) {
+    if (!object(value)) throw new Error('Configuration conflict at skills.paths.');
+    value = value[part];
+    if (value === undefined) return [];
+  }
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string'))
+    throw new Error('Configuration conflict at skills.paths.');
+  return value;
+}
+
+/** All side effects go through one validated transaction after the complete plan is built. */
+export async function setupProject({
+  root,
+  runtime,
+  harness,
+  previous,
+  metadata,
+  exists,
+  options,
+  projectFiles,
+  skillFiles,
+  guide,
+  startGuide,
+  allowedHarnesses,
+}) {
+  if (
+    previous?.schemaVersion === 2 &&
+    (!Array.isArray(previous.harnesses) ||
+      !previous.harnesses.includes(previous.harness) ||
+      previous.harnesses.some((name) => !allowedHarnesses.includes(name)) ||
+      new Set(previous.harnesses).size !== previous.harnesses.length)
+  )
+    throw new Error('Invalid workspace harness manifest.');
+  const selected =
+    previous?.schemaVersion === 2 ? [...previous.harnesses] : previous ? [previous.harness] : [];
+  if (options.adopt || !previous) selected.push(harness);
+  const registrations = [...new Set(selected)].sort();
+  const projection = new Map();
+  const desired = {};
+  const runtimeFiles = new Set();
+  const knownConfigs = new Map();
+  const allowedNames = new Set([
+    'AGENTS.md',
+    'CLAUDE.md',
+    'START.md',
+    '.kiln/AGENTS.md',
+    '.kiln/START.md',
+    '.kiln/.gitignore',
+  ]);
+  for (const name of allowedHarnesses) {
+    for (const [file, body] of Object.entries(projectFiles(name))) {
+      allowedNames.add(file);
+      for (const descriptor of configProjection(file, body))
+        knownConfigs.set(descriptorKey(descriptor), descriptor);
+    }
+  }
+  validatePrevious(previous, allowedNames, metadata.skills, knownConfigs, allowedHarnesses);
+  const snapshots = new Map();
+  const read = async (name) => {
+    if (!snapshots.has(name))
+      snapshots.set(name, exists ? await readProjectFile(root, name) : undefined);
+    return snapshots.get(name);
+  };
+  for (const name of registrations) {
+    for (const [file, body] of Object.entries(projectFiles(name))) {
+      const descriptors = configProjection(file, body);
+      if (!descriptors.length) {
+        desired[file] = body;
+        runtimeFiles.add(file);
+        continue;
+      }
+      for (const descriptor of descriptors) {
+        const key = descriptorKey(descriptor);
+        if (
+          projection.has(key) &&
+          JSON.stringify(projection.get(key)) !== JSON.stringify(descriptor)
+        )
+          throw new Error(
+            `The selected clients require conflicting configuration at ${file}. Keep their registrations separate until a compatible adapter is available.`,
+          );
+        projection.set(key, descriptor);
+      }
+    }
+  }
+  const configFiles = new Set([...knownConfigs.values()].map((entry) => entry.file));
+  const original =
+    previous?.schemaVersion === 2
+      ? { ...previous.ownedFiles }
+      : { ...previous?.generated, ...previous?.managedHashes };
+  if (previous?.schemaVersion === 1) {
+    for (const [name, value] of Object.entries(previous.skillHashes ?? {})) {
+      if (typeof value !== 'string' || !digestPattern.test(value))
+        throw new Error('Invalid skill manifest.');
+      for (const folder of ['skills', '.claude/skills', '.agents/skills']) {
+        const path = `${folder}/${name}`;
+        // Validate before reading paths from an older manifest.
+        validatePrevious(
+          { schemaVersion: 1, harness: previous.harness, generated: { [path]: value } },
+          allowedNames,
+          metadata.skills,
+          knownConfigs,
+          allowedHarnesses,
+        );
+        if ((await read(path)) !== undefined) original[path] ??= value;
+      }
+    }
+  }
+  for (const file of configFiles) delete original[file];
+  desired['.kiln/AGENTS.md'] = guide;
+  desired['.kiln/START.md'] = registrations.map((name) => startGuide(name)).join('\n---\n\n');
+  desired['.kiln/.gitignore'] = 'programs/\n';
+  const preserved = [];
+  for (const [file, body] of Object.entries({
+    'AGENTS.md': guide,
+    'CLAUDE.md':
+      (await read('AGENTS.md')) === undefined || original['AGENTS.md']
+        ? '@AGENTS.md\n'
+        : '@AGENTS.md\n@.kiln/AGENTS.md\n',
+    'START.md': desired['.kiln/START.md'],
+  })) {
+    if ((await read(file)) === undefined || original[file]) desired[file] = body;
+    else preserved.push(file);
+  }
+  const registries = new Set(['skills']);
+  for (const name of registrations) {
+    if (name === 'claude') registries.add('.claude/skills');
+    else if (name !== 'opencode') registries.add('.agents/skills');
+  }
+  const skillHashes = {};
+  for (const [name, body] of Object.entries(await skillFiles()).sort(([a], [b]) =>
+    a.localeCompare(b),
+  )) {
+    skillHashes[name] = hash(body);
+    for (const folder of registries) desired[`${folder}/${name}`] = body;
+  }
+  const edits = [],
+    files = [],
+    ownedFiles = {};
+  for (const name of [...new Set([...Object.keys(original), ...Object.keys(desired)])].sort()) {
+    if (options.repair && previous && !runtimeFiles.has(name)) {
+      if (original[name] !== undefined) ownedFiles[name] = original[name];
+      continue;
+    }
+    const before = await read(name);
+    const after = desired[name] === undefined ? undefined : Buffer.from(desired[name]);
+    const localHash = hash(before),
+      desiredHash = hash(after),
+      previousHash = original[name];
+    const status =
+      localHash === desiredHash
+        ? 'current'
+        : before === undefined
+          ? 'missing'
+          : localHash === previousHash
+            ? after === undefined
+              ? 'retired'
+              : 'outdated'
+            : previousHash === desiredHash && after !== undefined
+              ? 'customized'
+              : 'conflict';
+    if (after !== undefined) ownedFiles[name] = desiredHash;
+    if (status !== 'current') files.push({ path: name, status });
+    if (!['current', 'customized', 'conflict'].includes(status))
+      edits.push({ path: name, before, after });
+  }
+  const previousEntries = new Map(
+    (previous?.configEntries ?? []).map((value) => [descriptorKey(value), value]),
+  );
+  const configEntries = [...projection.values()];
+  for (const file of [...new Set(configEntries.map((entry) => entry.file))].sort()) {
+    const before = await read(file);
+    try {
+      let merged = text(before, file);
+      const legacyOwned =
+        previous?.schemaVersion === 1 &&
+        before !== undefined &&
+        hash(before) === (previous.generated?.[file] ?? previous.managedHashes?.[file]);
+      for (const entry of configEntries.filter((value) => value.file === file)) {
+        let prior = previousEntries.get(descriptorKey(entry));
+        if (entry.kind === 'toml') {
+          if (legacyOwned) merged = '';
+          merged = mergeTomlConfig(merged, {
+            path: entry.path,
+            fragment: entry.fragment,
+            ...(prior ? { previous: prior.fragment } : {}),
+          });
+        } else if (entry.kind === 'json') {
+          if (legacyOwned) {
+            let value = JSON.parse(text(before, file));
+            for (const part of entry.path) value = value?.[part];
+            if (value !== undefined) prior = { value };
+          }
+          merged = mergeJsonConfig(
+            merged,
+            [{ path: entry.path, value: entry.value, ...(prior ? { previous: prior.value } : {}) }],
+            { comments: entry.comments === true },
+          );
+        } else {
+          const current = listValue(merged, entry.path);
+          // Schema 1 owns the unchanged generated config as a whole. Its single
+          // skill path belongs to the original workspace, which may have moved.
+          // Never infer this ownership from a modified or adopted user config.
+          const oldPath =
+            prior?.value ?? (legacyOwned && current.length === 1 ? current[0] : undefined);
+          const value = current.filter((item) => item !== oldPath || oldPath === entry.value);
+          if (!value.includes(entry.value)) value.push(entry.value);
+          merged = mergeJsonConfig(merged, [{ path: entry.path, value, previous: current }], {
+            comments: true,
+          });
+        }
+      }
+      if (before === undefined || !before.equals(Buffer.from(merged))) {
+        files.push({ path: file, status: before === undefined ? 'missing' : 'outdated' });
+        edits.push({ path: file, before, after: merged });
+      }
+    } catch {
+      files.push({ path: file, status: 'conflict' });
+    }
+  }
+  const next = {
+    schemaVersion: 2,
+    root,
+    harness: previous?.harness ?? harness,
+    harnesses: registrations,
+    runtime,
+    runtimeVersion: metadata.runtimeVersion,
+    buildIdentity: metadata.buildIdentity,
+    runtimeHashes: metadata.runtimeHashes,
+    node: metadata.node,
+    skills: metadata.skills,
+    skillHashes: options.repair && previous ? previous.skillHashes : skillHashes,
+    ownedFiles,
+    configEntries,
+  };
+  const manifestBefore = await read('.kiln/workspace.json');
+  const manifestAfter = JSON.stringify(next);
+  const runtimeChanged =
+    !!previous &&
+    (previous.runtime !== runtime ||
+      previous.node !== next.node ||
+      previous.runtimeVersion !== next.runtimeVersion ||
+      (previous.buildIdentity ?? previous.runtimeIdentity) !== next.buildIdentity ||
+      JSON.stringify(previous.runtimeHashes) !== JSON.stringify(next.runtimeHashes) ||
+      (previous.schemaVersion === 2 && previous.root !== root));
+  const manifestChanged =
+    manifestBefore === undefined || !manifestBefore.equals(Buffer.from(manifestAfter));
+  if (manifestChanged)
+    edits.push({ path: '.kiln/workspace.json', before: manifestBefore, after: manifestAfter });
+  const conflicts = files.filter((file) => file.status === 'conflict');
+  const report = {
+    root,
+    runtime,
+    harness: next.harness,
+    harnesses: registrations,
+    store: join(root, '.kiln', 'programs'),
+    server: join(runtime, 'dist', 'mcp-server.mjs'),
+    instructions: join(root, '.kiln', 'AGENTS.md'),
+    status: edits.length || conflicts.length || runtimeChanged ? 'update-required' : 'current',
+    runtimeChanged,
+    files,
+    preserved,
+    next: 'Stop active agent/MCP sessions before setup changes. Restart afterward and accept the normal project and MCP trust prompts.',
+  };
+  if (options.check) {
+    if (exists && !conflicts.length)
+      await applyProjectEdits(root, edits, { stateDirectory: options.stateDirectory, check: true });
+    return report;
+  }
+  if (conflicts.length)
+    throw new Error(
+      `Project setup has conflicts; no files were changed: ${conflicts.map((file) => file.path).join(', ')}. Preserve and resolve these files before retrying.`,
+    );
+  if (!exists) await mkdir(root, { recursive: true });
+  await applyProjectEdits(root, edits, {
+    stateDirectory: options.stateDirectory,
+    onStep: options.onStep,
+  });
+  return { ...report, status: 'current', changed: edits.map((edit) => edit.path) };
+}