@ketecode/loom 0.0.0-stage → 0.2.0

package/scripts/lib/mcp-install.js

@@ -0,0 +1,288 @@
+'use strict';
+
+// Registers curated MCP servers (mcp/<name>.json) with each host (verified against host docs and Kete
+// Code's source, Oct 2026). Servers carry no secrets: remote ones sign in with the host's own OAuth
+// flow, local ones need no tokens. Each host gets the server in its own shape:
+//   Claude Code  user: `claude mcp add-json --scope user` (never edits ~/.claude.json); project: .mcp.json
+//   Codex        [mcp_servers.<name>] tables in a marked block of config.toml
+//   Gemini CLI   settings.json `mcpServers` (httpUrl = streamable HTTP)
+//   Cursor       mcp.json `mcpServers`
+//   Copilot CLI  ~/.copilot/mcp-config.json `mcpServers`; local servers only (its OAuth isn't documented)
+//   OpenCode     opencode.json `mcp` (command is an array)
+//   Kete Code    kete.json `mcp.servers`
+//   Kiro         ~/.kiro/settings/mcp.json `mcpServers` (remote servers sign in with OAuth)
+// An entry is ours when it equals what we would write, so a server you configured yourself under the
+// same name is never touched. Claude Code's CLI-managed servers are tracked in ~/.kete-loom/mcp.json.
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { readJson, writeAtomic, CommentedFileError } = require('./hooks-install');
+
+const MCP_DIR = path.join(__dirname, '..', '..', 'mcp');
+const listMcp = (dir = MCP_DIR) =>
+  fs.existsSync(dir)
+    ? fs.readdirSync(dir).filter((f) => f.endsWith('.json')).sort().map((f) => ({ kind: 'mcp', dir: f.slice(0, -5), file: path.join(dir, f), ...JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8')) }))
+    : [];
+
+const http = (s) => s.transport === 'http';
+// Each host's JSON for one server, or null when that host can't run it.
+const RENDER = {
+  claude: (s) => (http(s) ? { type: 'http', url: s.url } : { type: 'stdio', command: s.command, args: s.args }),
+  cursor: (s) => (http(s) ? { url: s.url } : { type: 'stdio', command: s.command, args: s.args }),
+  gemini: (s) => (http(s) ? { httpUrl: s.url } : { command: s.command, args: s.args }),
+  copilot: (s) => (http(s) ? null : { type: 'local', command: s.command, args: s.args, tools: ['*'] }),
+  opencode: (s) => (http(s) ? { type: 'remote', url: s.url, enabled: true } : { type: 'local', command: [s.command, ...s.args], enabled: true }),
+  kete: (s) => (http(s) ? { type: 'remote', url: s.url } : { type: 'local', command: [s.command, ...s.args] }),
+  kiro: (s) => (http(s) ? { url: s.url } : { command: s.command, args: s.args }),
+};
+
+const SIGN_IN = {
+  claude: (n) => `run /mcp in Claude Code to sign in to ${n}`,
+  codex: (n) => `codex mcp login ${n}`,
+  gemini: (n) => `run /mcp auth ${n} in Gemini CLI`,
+  cursor: (n) => `Cursor asks you to sign in to ${n} the first time it connects`,
+  opencode: (n) => `opencode mcp auth ${n}`,
+  kete: (n) => `kete mcp auth ${n}`,
+  kiro: (n) => `Kiro opens a browser to sign in to ${n} the first time it connects`,
+};
+
+const keteFile = (dir) => (fs.existsSync(path.join(dir, 'kete.jsonc')) ? path.join(dir, 'kete.jsonc') : path.join(dir, 'kete.json'));
+
+// JSON hosts: file per scope, and the object that holds the servers.
+const JSON_HOSTS = {
+  claude: { file: { project: (cwd) => path.join(cwd, '.mcp.json') }, holder: (d) => (d.mcpServers ||= {}), standalone: true },
+  cursor: { file: { user: (h) => path.join(h, '.cursor', 'mcp.json'), project: (cwd) => path.join(cwd, '.cursor', 'mcp.json') }, holder: (d) => (d.mcpServers ||= {}), standalone: true },
+  gemini: { file: { user: (h) => path.join(h, '.gemini', 'settings.json'), project: (cwd) => path.join(cwd, '.gemini', 'settings.json') }, holder: (d) => (d.mcpServers ||= {}) },
+  copilot: { file: { user: (h) => path.join(process.env.COPILOT_HOME || path.join(h, '.copilot'), 'mcp-config.json') }, holder: (d) => (d.mcpServers ||= {}), standalone: true },
+  opencode: { file: { user: (h) => path.join(h, '.config', 'opencode', 'opencode.json'), project: (cwd) => path.join(cwd, 'opencode.json') }, holder: (d) => (d.mcp ||= {}) },
+  kete: { file: { user: (h) => keteFile(path.join(h, '.config', 'kete')), project: (cwd) => keteFile(path.join(cwd, '.kete')) }, holder: (d) => ((d.mcp ||= {}).servers ||= {}) },
+  kiro: { file: { user: (h) => path.join(h, '.kiro', 'settings', 'mcp.json'), project: (cwd) => path.join(cwd, '.kiro', 'settings', 'mcp.json') }, holder: (d) => (d.mcpServers ||= {}), standalone: true },
+};
+const MCP_HOSTS = ['claude', 'codex', 'gemini', 'cursor', 'copilot', 'opencode', 'kete', 'kiro'];
+
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+function pruneJson(data) {
+  const empty = (v) => v && typeof v === 'object' && !Array.isArray(v) && !Object.keys(v).length;
+  if (data.mcp && empty(data.mcp.servers)) delete data.mcp.servers;
+  for (const k of ['mcpServers', 'mcp']) if (empty(data[k])) delete data[k];
+  return data;
+}
+
+function jsonRegister(host, servers, { file, dryRun }) {
+  let data;
+  try {
+    data = readJson(file);
+  } catch (e) {
+    const reason = e instanceof CommentedFileError ? `${e.message}; add the servers yourself` : e.message;
+    return servers.map((s) => ({ name: s.dir, action: 'skipped', reason, dest: file }));
+  }
+  const holder = JSON_HOSTS[host].holder(data);
+  const rows = servers.map((s) => {
+    const want = RENDER[host](s);
+    if (!want) return { name: s.dir, action: 'skipped', reason: `${host} can't sign in to remote MCP servers yet; add ${s.dir} there yourself`, dest: file };
+    const have = holder[s.dir];
+    if (have && !same(have, want)) return { name: s.dir, action: 'skipped', reason: `a server named ${s.dir} already exists there and wasn't installed by kete-loom`, dest: file };
+    holder[s.dir] = want;
+    return { name: s.dir, action: have ? 'updated' : 'installed', dest: file };
+  });
+  pruneJson(data);
+  if (!dryRun && rows.some((r) => r.action !== 'skipped')) writeAtomic(file, JSON.stringify(data, null, 2) + '\n');
+  return rows;
+}
+
+function jsonUnregister(host, servers, { file, dryRun }) {
+  if (!fs.existsSync(file)) return [];
+  let data;
+  try {
+    data = readJson(file);
+  } catch {
+    return [];
+  }
+  const holder = JSON_HOSTS[host].holder(data);
+  const gone = servers.filter((s) => holder[s.dir] && RENDER[host](s) && same(holder[s.dir], RENDER[host](s)));
+  if (!gone.length) return [];
+  for (const s of gone) delete holder[s.dir];
+  pruneJson(data);
+  if (!dryRun) {
+    if (JSON_HOSTS[host].standalone && !Object.keys(data).length) fs.rmSync(file);
+    else writeAtomic(file, JSON.stringify(data, null, 2) + '\n');
+  }
+  return gone.map((s) => ({ name: s.dir, action: 'removed', dest: file }));
+}
+
+// Codex: TOML tables in a block we own. Strings and arrays are written as JSON, which is valid TOML.
+const TOML_START = '# kete-loom:mcp:start (managed by kete-loom: edit outside this block)';
+const TOML_END = '# kete-loom:mcp:end';
+const TOML_BLOCK_RE = /\n*# kete-loom:mcp:start[^\n]*\n[\s\S]*?# kete-loom:mcp:end\n?/;
+const codexFile = (scope, home, cwd) => (scope === 'project' ? path.join(cwd, '.codex', 'config.toml') : path.join(home, '.codex', 'config.toml'));
+const tomlTable = (s) =>
+  [`[mcp_servers.${s.dir}]`, ...(http(s) ? [`url = ${JSON.stringify(s.url)}`] : [`command = ${JSON.stringify(s.command)}`, `args = ${JSON.stringify(s.args)}`])].join('\n');
+const blockNames = (text) => [...((TOML_BLOCK_RE.exec(text) || [''])[0].matchAll(/^\[mcp_servers\.([a-z0-9-]+)\]$/gm))].map((m) => m[1]);
+
+function codexWrite(file, text, names, all, dryRun) {
+  const rest = text.replace(TOML_BLOCK_RE, '\n').trimEnd();
+  const tables = all.filter((s) => names.includes(s.dir)).map(tomlTable);
+  const next = tables.length ? `${rest ? `${rest}\n\n` : ''}${TOML_START}\n${tables.join('\n\n')}\n${TOML_END}\n` : rest ? `${rest}\n` : '';
+  if (dryRun || next === text) return;
+  if (next) writeAtomic(file, next);
+  else fs.rmSync(file);
+}
+
+function codexRegister(servers, all, { file, dryRun }) {
+  const text = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  const outside = text.replace(TOML_BLOCK_RE, '\n');
+  const ours = blockNames(text);
+  const rows = servers.map((s) => {
+    // A table or dotted key for this name outside our block would make config.toml invalid TOML.
+    if (new RegExp(`(^|\\n)\\s*\\[mcp_servers\\.(?:"${s.dir}"|${s.dir})\\]|mcp_servers\\.(?:"${s.dir}"|${s.dir})\\.`).test(outside)) {
+      return { name: s.dir, action: 'skipped', reason: `config.toml already defines mcp_servers.${s.dir}`, dest: file };
+    }
+    return { name: s.dir, action: ours.includes(s.dir) ? 'updated' : 'installed', dest: file };
+  });
+  const names = [...new Set([...ours, ...rows.filter((r) => r.action !== 'skipped').map((r) => r.name)])];
+  codexWrite(file, text, names, all, dryRun);
+  return rows;
+}
+
+function codexUnregister(servers, all, { file, dryRun }) {
+  if (!fs.existsSync(file)) return [];
+  const text = fs.readFileSync(file, 'utf8');
+  const ours = blockNames(text);
+  const gone = ours.filter((n) => servers.some((s) => s.dir === n));
+  if (!gone.length) return [];
+  codexWrite(file, text, ours.filter((n) => !gone.includes(n)), all, dryRun);
+  return gone.map((name) => ({ name, action: 'removed', dest: file }));
+}
+
+// Claude Code user scope goes through its CLI; ~/.kete-loom/mcp.json records which servers we added.
+const stateFile = (home) => path.join(home, '.kete-loom', 'mcp.json');
+const readState = (home) => {
+  try {
+    return JSON.parse(fs.readFileSync(stateFile(home), 'utf8'));
+  } catch {
+    return {};
+  }
+};
+function writeState(home, state) {
+  const file = stateFile(home);
+  if (Object.values(state).some((v) => v.length)) {
+    // Our own state file: atomic, but no backup (backups are for files that belong to you).
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(`${file}.tmp`, JSON.stringify(state, null, 2) + '\n');
+    fs.renameSync(`${file}.tmp`, file);
+  }
+  else if (fs.existsSync(file)) {
+    fs.rmSync(file);
+    if (!fs.readdirSync(path.dirname(file)).length) fs.rmdirSync(path.dirname(file));
+  }
+}
+const claudeBin = () => process.env.KETE_LOOM_CLAUDE_BIN || 'claude';
+const claude = (args) => execFileSync(claudeBin(), args, { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8', timeout: 30000 });
+
+function claudeUserRegister(servers, { home, dryRun }) {
+  const state = readState(home);
+  const mine = new Set(state['claude-user'] || []);
+  const rows = servers.map((s) => {
+    const json = JSON.stringify(RENDER.claude(s));
+    const dest = `claude mcp (user scope)`;
+    try {
+      if (mine.has(s.dir)) {
+        if (!dryRun) {
+          claude(['mcp', 'remove', s.dir, '--scope', 'user']);
+          claude(['mcp', 'add-json', s.dir, json, '--scope', 'user']);
+        }
+        return { name: s.dir, action: 'updated', dest };
+      }
+      let exists = true;
+      try {
+        claude(['mcp', 'get', s.dir]);
+      } catch (e) {
+        if (e.code === 'ENOENT') throw e;
+        exists = false;
+      }
+      if (exists) return { name: s.dir, action: 'skipped', reason: `Claude Code already has a server named ${s.dir}, not installed by kete-loom`, dest };
+      if (!dryRun) claude(['mcp', 'add-json', s.dir, json, '--scope', 'user']);
+      mine.add(s.dir);
+      return { name: s.dir, action: 'installed', dest };
+    } catch (e) {
+      const reason = e.code === 'ENOENT' ? `the claude CLI isn't on your PATH; run: claude mcp add-json ${s.dir} '${json}' --scope user` : `claude mcp failed: ${(e.stderr || e.message).trim().slice(0, 200)}`;
+      return { name: s.dir, action: 'skipped', reason, dest };
+    }
+  });
+  if (!dryRun) writeState(home, { ...state, 'claude-user': [...mine].sort() });
+  return rows;
+}
+
+function claudeUserUnregister(servers, { home, dryRun }) {
+  const state = readState(home);
+  const mine = state['claude-user'] || [];
+  const gone = mine.filter((n) => servers.some((s) => s.dir === n));
+  const removed = [];
+  for (const name of gone) {
+    try {
+      if (!dryRun) claude(['mcp', 'remove', name, '--scope', 'user']);
+      removed.push(name);
+    } catch (e) {
+      // Already removed by hand: forget it either way.
+      if (e.code !== 'ENOENT') removed.push(name);
+    }
+  }
+  if (!dryRun) writeState(home, { ...state, 'claude-user': mine.filter((n) => !removed.includes(n)) });
+  return removed.map((name) => ({ name, action: 'removed', dest: 'claude mcp (user scope)' }));
+}
+
+function fileFor(host, scope, home, cwd) {
+  if (host === 'codex') return codexFile(scope, home, cwd);
+  const f = JSON_HOSTS[host].file[scope];
+  return f ? f(scope === 'project' ? cwd : home) : null;
+}
+
+// Registers servers with one host. Returns rows { target, kind, name, action, dest, reason?, note? }.
+function installMcp(host, servers, all, { scope = 'user', home, cwd = process.cwd(), dryRun = false }) {
+  let rows;
+  if (host === 'claude' && scope === 'user') rows = claudeUserRegister(servers, { home, dryRun });
+  else {
+    const file = fileFor(host, scope, home, cwd);
+    if (!file) {
+      const reason = host === 'copilot' ? "Copilot CLI reads the project's .mcp.json, which kete-loom writes for Claude Code" : `${host} has no ${scope} MCP config`;
+      return servers.map((s) => ({ target: host, kind: 'mcp', name: s.dir, action: 'skipped', reason, dest: '' }));
+    }
+    rows = host === 'codex' ? codexRegister(servers, all, { file, dryRun }) : jsonRegister(host, servers, { file, dryRun });
+  }
+  return rows.map((r) => {
+    const s = servers.find((x) => x.dir === r.name);
+    const note = r.action !== 'skipped' && s && http(s) && SIGN_IN[host] ? `Remote MCP servers sign in with OAuth. ${host}: ${SIGN_IN[host]('<server>')}.` : undefined;
+    return { target: host, kind: 'mcp', ...r, ...(note ? { note } : {}) };
+  });
+}
+
+function uninstallMcp(host, servers, all, { scope = 'user', home, cwd = process.cwd(), dryRun = false }) {
+  let rows;
+  if (host === 'claude' && scope === 'user') rows = claudeUserUnregister(servers, { home, dryRun });
+  else {
+    const file = fileFor(host, scope, home, cwd);
+    if (!file) return [];
+    rows = host === 'codex' ? codexUnregister(servers, all, { file, dryRun }) : jsonUnregister(host, servers, { file, dryRun });
+  }
+  return rows.map((r) => ({ target: host, kind: 'mcp', ...r }));
+}
+
+// Names of kete-loom MCP servers registered with a host (exact matches only).
+function registeredMcp(host, all, { scope = 'user', home, cwd = process.cwd() }) {
+  if (host === 'claude' && scope === 'user') return readState(home)['claude-user'] || [];
+  const file = fileFor(host, scope, home, cwd);
+  if (!file || !fs.existsSync(file)) return [];
+  if (host === 'codex') return blockNames(fs.readFileSync(file, 'utf8'));
+  let data;
+  try {
+    data = readJson(file);
+  } catch {
+    return [];
+  }
+  const holder = JSON_HOSTS[host].holder(data);
+  return all.filter((s) => holder[s.dir] && RENDER[host](s) && same(holder[s.dir], RENDER[host](s))).map((s) => s.dir);
+}
+
+module.exports = { MCP_HOSTS, MCP_DIR, listMcp, RENDER, installMcp, uninstallMcp, registeredMcp, tomlTable };

package/scripts/lib/profiles.js

@@ -0,0 +1,128 @@
+'use strict';
+
+// Install profiles (profiles.json): named selections of skills, agents, commands and hooks.
+// A profile can extend others, add whole categories, and `detect` the project's languages,
+// frameworks and tools so only the packs it uses are installed.
+
+const fs = require('fs');
+const path = require('path');
+
+const PROFILES_FILE = path.join(__dirname, '..', '..', 'profiles.json');
+const KINDS = ['skills', 'agents', 'commands', 'rules', 'hooks', 'mcp'];
+
+const loadProfiles = (file = PROFILES_FILE) => JSON.parse(fs.readFileSync(file, 'utf8'));
+
+// What a project uses -> the items that help with it. `when` gets helpers over the project folder.
+const lang = (name) => ({ skills: [`${name}-patterns`, `${name}-testing`], agents: [`${name}-reviewer`, `${name}-build-resolver`], rules: [name] });
+const DETECT = [
+  { what: 'TypeScript/JavaScript', when: (p) => p.has('package.json') || p.has('tsconfig.json'), ...lang('typescript') },
+  { what: 'Python', when: (p) => p.has('pyproject.toml') || p.has('requirements.txt') || p.has('setup.py') || p.has('Pipfile'), ...lang('python') },
+  { what: 'Go', when: (p) => p.has('go.mod'), ...lang('go') },
+  { what: 'Rust', when: (p) => p.has('Cargo.toml'), ...lang('rust') },
+  { what: 'Java', when: (p) => p.has('pom.xml') || p.has('build.gradle') || p.ext('.java'), ...lang('java') },
+  { what: 'Kotlin', when: (p) => p.has('build.gradle.kts') || p.ext('.kt'), ...lang('kotlin') },
+  { what: 'C#', when: (p) => p.ext('.csproj') || p.ext('.sln'), ...lang('csharp') },
+  { what: 'F#', when: (p) => p.ext('.fsproj'), ...lang('fsharp') },
+  { what: 'C++', when: (p) => p.has('CMakeLists.txt') || p.ext('.cpp') || p.ext('.hpp'), ...lang('cpp') },
+  { what: 'Swift', when: (p) => p.has('Package.swift') || p.ext('.xcodeproj'), ...lang('swift') },
+  { what: 'Dart', when: (p) => p.has('pubspec.yaml'), ...lang('dart') },
+  { what: 'PHP', when: (p) => p.has('composer.json'), ...lang('php') },
+  { what: 'Ruby', when: (p) => p.has('Gemfile'), ...lang('ruby') },
+  { what: 'Perl', when: (p) => p.has('cpanfile') || p.has('Makefile.PL'), ...lang('perl') },
+  { what: 'React', when: (p) => p.dep('react'), skills: ['react-patterns', 'react-performance'], agents: ['react-reviewer'] },
+  { what: 'Next.js', when: (p) => p.dep('next'), skills: ['nextjs-patterns'] },
+  { what: 'Vue', when: (p) => p.dep('vue'), skills: ['vue-patterns'], agents: ['vue-reviewer'] },
+  { what: 'Nuxt', when: (p) => p.dep('nuxt'), skills: ['nuxt-patterns'] },
+  { what: 'Angular', when: (p) => p.dep('@angular/core'), skills: ['angular-patterns'] },
+  { what: 'Svelte', when: (p) => p.dep('svelte'), skills: ['svelte-patterns'] },
+  { what: 'React Native', when: (p) => p.dep('react-native'), skills: ['react-native-patterns'] },
+  { what: 'NestJS', when: (p) => p.dep('@nestjs/core'), skills: ['nestjs-patterns'] },
+  { what: 'Node HTTP server', when: (p) => p.dep('express') || p.dep('fastify'), skills: ['node-backend-patterns'] },
+  { what: 'Prisma', when: (p) => p.dep('prisma') || p.dep('@prisma/client'), skills: ['prisma-patterns'] },
+  { what: 'Vite', when: (p) => p.dep('vite'), skills: ['vite-patterns'] },
+  { what: 'Playwright', when: (p) => p.dep('@playwright/test'), skills: ['e2e-testing-playwright'], agents: ['e2e-runner'] },
+  { what: 'Django', when: (p) => p.py('django'), skills: ['django-patterns'], agents: ['django-reviewer'] },
+  { what: 'FastAPI', when: (p) => p.py('fastapi'), skills: ['fastapi-patterns'], agents: ['fastapi-reviewer'] },
+  { what: 'Flask', when: (p) => p.py('flask'), skills: ['flask-patterns'] },
+  { what: 'PyTorch', when: (p) => p.py('torch'), skills: ['pytorch-patterns'], agents: ['mle-reviewer'] },
+  { what: 'Rails', when: (p) => /\brails\b/.test(p.read('Gemfile')), skills: ['rails-patterns'] },
+  { what: 'Laravel', when: (p) => /laravel\/framework/.test(p.read('composer.json')), skills: ['laravel-patterns'] },
+  { what: 'Spring Boot', when: (p) => /spring-boot/.test(p.read('pom.xml') + p.read('build.gradle') + p.read('build.gradle.kts')), skills: ['spring-boot-patterns', 'jpa-hibernate'] },
+  { what: 'Quarkus', when: (p) => /io\.quarkus/.test(p.read('pom.xml') + p.read('build.gradle') + p.read('build.gradle.kts')), skills: ['quarkus-patterns'] },
+  { what: 'Ktor', when: (p) => /io\.ktor/.test(p.read('build.gradle.kts') + p.read('build.gradle')), skills: ['ktor-patterns'] },
+  { what: 'ASP.NET Core', when: (p) => p.ext('.csproj') && /Microsoft\.NET\.Sdk\.Web|AspNetCore/.test(p.readExt('.csproj')), skills: ['aspnet-core-patterns'] },
+  { what: 'EF Core', when: (p) => /EntityFrameworkCore/.test(p.readExt('.csproj')), skills: ['ef-core-patterns'] },
+  { what: 'Flutter', when: (p) => /\bflutter:/.test(p.read('pubspec.yaml')), skills: ['flutter-patterns'], agents: ['flutter-reviewer'] },
+  { what: 'Docker', when: (p) => p.has('Dockerfile') || p.has('compose.yaml') || p.has('docker-compose.yml'), skills: ['docker-patterns'] },
+  { what: 'Terraform', when: (p) => p.ext('.tf'), skills: ['terraform-patterns'], agents: ['infra-reviewer'] },
+  { what: 'GitHub Actions', when: (p) => p.has('.github/workflows'), skills: ['github-actions-ci'] },
+  { what: 'dbt', when: (p) => p.has('dbt_project.yml'), skills: ['dbt-patterns'] },
+  { what: 'Solidity', when: (p) => p.has('foundry.toml') || p.has('hardhat.config.ts') || p.has('hardhat.config.js'), skills: ['solidity-patterns', 'smart-contract-security'], agents: ['solidity-reviewer'] },
+];
+
+// Read-only view of a project folder (top level only, plus package.json/pyproject dependencies).
+function inspect(dir) {
+  let entries = [];
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    // unreadable or missing folder: nothing detected
+  }
+  const read = (f) => {
+    try {
+      return fs.readFileSync(path.join(dir, f), 'utf8');
+    } catch {
+      return '';
+    }
+  };
+  let pkg = {};
+  try {
+    pkg = JSON.parse(read('package.json') || '{}');
+  } catch {
+    // invalid package.json: no JS dependencies detected
+  }
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies, ...pkg.peerDependencies };
+  const python = (read('pyproject.toml') + read('requirements.txt') + read('setup.py') + read('Pipfile')).toLowerCase();
+  return {
+    has: (f) => fs.existsSync(path.join(dir, f)),
+    ext: (e) => entries.some((f) => f.endsWith(e)),
+    read,
+    readExt: (e) => entries.filter((f) => f.endsWith(e)).map(read).join('\n'),
+    dep: (name) => Object.prototype.hasOwnProperty.call(deps, name),
+    py: (name) => new RegExp(`(^|[\\s"'\\[,])${name}([\\s"'<>=~!\\],;]|$)`, 'm').test(python),
+  };
+}
+
+function detect(dir) {
+  const p = inspect(dir);
+  return DETECT.filter((d) => d.when(p));
+}
+
+// Resolves profile names to { all, skills, agents, commands, hooks: Set, detected: [labels] }.
+function resolveProfiles(names, { catalog, cwd = process.cwd(), profiles = loadProfiles() }) {
+  const out = { all: false, detected: [], ...Object.fromEntries(KINDS.map((k) => [k, new Set()])) };
+  const seen = new Set();
+  const visit = (name, chain = []) => {
+    const p = profiles[name];
+    if (!p) throw new Error(`unknown profile "${name}". Known: ${Object.keys(profiles).join(', ')}`);
+    if (chain.includes(name)) throw new Error(`profile "${name}" extends itself: ${[...chain, name].join(' -> ')}`);
+    if (seen.has(name)) return;
+    seen.add(name);
+    for (const parent of p.extends || []) visit(parent, [...chain, name]);
+    if (p.all) out.all = true;
+    for (const k of KINDS) for (const n of p[k] || []) out[k].add(n);
+    // MCP servers reach the network and run code, so they come only from a profile's explicit `mcp` list.
+    for (const cat of p.categories || []) for (const k of KINDS.filter((x) => x !== 'mcp')) for (const item of catalog[k] || []) if (item.category === cat) out[k].add(item.dir);
+    if (p.detect) {
+      for (const d of detect(cwd)) {
+        out.detected.push(d.what);
+        for (const k of ['skills', 'agents', 'rules']) for (const n of d[k] || []) out[k].add(n);
+      }
+    }
+  };
+  for (const n of names) visit(n);
+  out.detected = [...new Set(out.detected)];
+  return out;
+}
+
+module.exports = { loadProfiles, resolveProfiles, detect, DETECT, PROFILES_FILE };

package/scripts/lib/render.js

@@ -0,0 +1,92 @@
+'use strict';
+
+// Turns one portable agent or command into the file each host expects.
+// Every rendered file carries a `# kete-loom <name>@<version>` comment (YAML or TOML),
+// which is how install and uninstall recognise files kete-loom wrote.
+
+const TOOLS = ['read', 'search', 'shell', 'edit', 'web'];
+// `# kete-loom name@version` inside YAML/TOML, or `<!-- kete-loom name@version -->` in plain Markdown.
+const MARKER_RE = /^(?:# |<!-- )kete-loom [a-z0-9-]+@/m;
+
+const CLAUDE_TOOLS = { read: ['Read'], search: ['Grep', 'Glob'], shell: ['Bash'], edit: ['Edit', 'Write'], web: ['WebFetch', 'WebSearch'] };
+const COPILOT_TOOLS = { read: 'read', search: 'search', shell: 'execute', edit: 'edit', web: 'web' };
+const KIRO_TOOLS = { read: ['read'], search: ['glob', 'grep'], shell: ['shell'], edit: ['write'], web: ['web_search', 'web_fetch'] };
+
+const marker = (item) => `# kete-loom ${item.dir}@${item.version}`;
+// JSON strings are valid YAML double-quoted scalars and TOML basic strings (TOML also bans raw DEL).
+const str = (s) => JSON.stringify(String(s)).replace(/\x7f/g, '\\u007f');
+const body = (item) => item.body.replace(/^\s*\n/, '');
+
+function markdown(item, fields) {
+  const lines = [marker(item)];
+  for (const [k, v] of Object.entries(fields)) {
+    if (v === undefined || v === null) continue;
+    if (Array.isArray(v)) lines.push(`${k}: [${v.map(str).join(', ')}]`);
+    else if (typeof v === 'object') {
+      lines.push(`${k}:`);
+      for (const [k2, v2] of Object.entries(v)) lines.push(`  ${k2}: ${v2}`);
+    } else lines.push(`${k}: ${typeof v === 'string' ? str(v) : v}`);
+  }
+  return `---\n${lines.join('\n')}\n---\n\n${body(item)}`;
+}
+
+// Multi-line literal ('''...''') keeps prompts readable; it can't hold ''' or control characters other than tab/newline.
+const tomlValue = (v) => (/\n/.test(v) && !v.includes("'''") && !/[\x00-\x08\x0b-\x1f\x7f]/.test(v) ? `'''\n${v}'''` : str(v));
+
+function toml(item, fields) {
+  return [marker(item), ...Object.entries(fields).filter(([, v]) => v !== undefined).map(([k, v]) => `${k} = ${tomlValue(v)}`)].join('\n') + '\n';
+}
+
+const has = (item, tool) => !item.tools || item.tools.includes(tool);
+
+// OpenCode restricts with permissions rather than a tool list.
+function opencodePermission(item) {
+  if (!item.tools) return undefined;
+  const p = {};
+  if (!has(item, 'edit')) p.edit = 'deny';
+  if (!has(item, 'shell')) p.bash = 'deny';
+  if (!has(item, 'web')) p.webfetch = 'deny';
+  return Object.keys(p).length ? p : undefined;
+}
+
+// shortcut: Codex and Gemini agents inherit every tool (Codex can't set a sandbox per agent; Gemini's
+// tool names aren't mapped yet), so `kete-loom/tools` is advisory there. Map them when hosts allow it.
+const AGENT = {
+  claude: (a) => ({ file: `${a.dir}.md`, content: markdown(a, { name: a.dir, description: a.description, tools: a.tools && a.tools.flatMap((t) => CLAUDE_TOOLS[t]).join(', ') }) }),
+  codex: (a) => ({ file: `${a.dir}.toml`, content: toml(a, { name: a.dir, description: a.description, developer_instructions: body(a) }) }),
+  opencode: (a) => ({ file: `${a.dir}.md`, content: markdown(a, { description: a.description, mode: 'subagent', permission: opencodePermission(a) }) }),
+  cursor: (a) => ({ file: `${a.dir}.md`, content: markdown(a, { name: a.dir, description: a.description, readonly: a.tools && !has(a, 'edit') && !has(a, 'shell') ? true : undefined }) }),
+  gemini: (a) => ({ file: `${a.dir}.md`, content: markdown(a, { name: a.dir, description: a.description }) }),
+  kete: (a) => AGENT.opencode(a), // Kete Code reads the OpenCode agent format
+  copilot: (a) => ({ file: `${a.dir}.agent.md`, content: markdown(a, { name: a.dir, description: a.description, tools: a.tools && a.tools.map((t) => COPILOT_TOOLS[t]) }) }),
+  kiro: (a) => ({ file: `${a.dir}.md`, content: markdown(a, { name: a.dir, description: a.description, tools: a.tools && a.tools.flatMap((t) => KIRO_TOOLS[t]) }) }),
+};
+
+const COMMAND = {
+  claude: (c) => ({ file: `${c.dir}.md`, content: markdown(c, { description: c.description, 'argument-hint': c.argumentHint }) }),
+  opencode: (c) => ({ file: `${c.dir}.md`, content: markdown(c, { description: c.description }) }),
+  kete: (c) => COMMAND.opencode(c),
+  // Kiro prompts are plain Markdown and take $ARGUMENTS as is.
+  kiro: (c) => ({ file: `${c.dir}.md`, content: `<!-- ${marker(c).slice(2)} -->\n${body(c)}` }),
+  gemini: (c) => ({ file: `${c.dir}.toml`, content: toml(c, { description: c.description, prompt: body(c).replace(/\$ARGUMENTS/g, '{{args}}') }) }),
+};
+
+// Rules: path-scoped where the host supports it (Claude Code, Copilot, Cursor). Hosts that can't scope
+// get plain Markdown that says which files it is about (scripts/lib/rules-install.js).
+const appliesTo = (r) => (r.paths.length ? `Applies when working on files matching: ${r.paths.join(', ')}.\n\n` : '');
+const RULE = {
+  claude: (r) => ({ file: `${r.dir}.md`, content: markdown(r, { paths: r.paths.length ? r.paths : undefined }) }),
+  copilot: (r) => ({ file: `${r.dir}.instructions.md`, content: markdown(r, { applyTo: r.paths.length ? r.paths.join(',') : '**' }) }),
+  cursor: (r) => ({ file: `${r.dir}.mdc`, content: markdown(r, { description: r.description, globs: r.paths.length ? r.paths.join(', ') : undefined, alwaysApply: !r.paths.length }) }),
+  // Steering front matter must come first; inclusion: fileMatch scopes it like a path rule.
+  kiro: (r) => ({ file: `${r.dir}.md`, content: markdown(r, r.paths.length ? { inclusion: 'fileMatch', fileMatchPattern: r.paths } : { inclusion: 'always' }) }),
+  plain: (r) => ({ file: `${r.dir}.md`, content: `<!-- ${marker(r).slice(2)} -->\n# ${r.dir} rules\n\n${appliesTo(r)}${body(r)}` }),
+};
+
+function render(item, target) {
+  if (item.kind === 'rule') return RULE[target] ? RULE[target](item) : null;
+  const table = item.kind === 'agent' ? AGENT : COMMAND;
+  return table[target] ? table[target](item) : null;
+}
+
+module.exports = { TOOLS, MARKER_RE, render };

package/scripts/lib/rules-install.js

@@ -0,0 +1,118 @@
+'use strict';
+
+// Rules for hosts that can't scope instructions to file paths (verified against host docs and Kete
+// Code's source, Oct 2026). User scope only. Each rule is written to a kete-loom folder that is the
+// source of truth, and the host's instructions are pointed at that folder:
+//   Kete Code   `@kete-loom/rules/<name>.md` imports in ~/.config/kete/AGENTS.md (relative to that file)
+//   Gemini CLI  `@./kete-loom/rules/<name>.md` imports in ~/.gemini/GEMINI.md
+//   OpenCode    one `<folder>/*.md` entry in the `instructions` array of ~/.config/opencode/opencode.json
+//   Codex       no imports: the rule text inline in ~/.codex/AGENTS.md, kept under its 32 KiB limit
+// Shared files are only changed between our markers, backed up and written atomically.
+
+const fs = require('fs');
+const path = require('path');
+const { render } = require('./render');
+const { readJson, writeAtomic, CommentedFileError } = require('./hooks-install');
+
+const START = '<!-- kete-loom:rules:start (managed by kete-loom: edit outside this block) -->';
+const END = '<!-- kete-loom:rules:end -->';
+const BLOCK_RE = /\n*<!-- kete-loom:rules:start[^\n]*-->[\s\S]*?<!-- kete-loom:rules:end -->\n?/;
+const CODEX_MAX_BYTES = 32768;
+
+const HOSTS = {
+  kete: { dir: (h) => path.join(h, '.config', 'kete', 'kete-loom', 'rules'), file: (h) => path.join(h, '.config', 'kete', 'AGENTS.md'), mode: 'import', ref: (n) => `@kete-loom/rules/${n}.md` },
+  gemini: { dir: (h) => path.join(h, '.gemini', 'kete-loom', 'rules'), file: (h) => path.join(h, '.gemini', 'GEMINI.md'), mode: 'import', ref: (n) => `@./kete-loom/rules/${n}.md` },
+  opencode: { dir: (h) => path.join(h, '.config', 'opencode', 'kete-loom', 'rules'), file: (h) => path.join(h, '.config', 'opencode', 'opencode.json'), mode: 'instructions' },
+  codex: { dir: (h) => path.join(h, '.codex', 'kete-loom', 'rules'), file: (h) => path.join(h, '.codex', 'AGENTS.md'), mode: 'inline' },
+};
+const RULE_HOSTS = Object.keys(HOSTS);
+
+const installedNames = (dir) => (fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => f.endsWith('.md')).map((f) => f.slice(0, -3)).sort() : []);
+
+// Replaces our block in a Markdown file (or appends one); an empty block is removed.
+function withBlock(text, lines) {
+  const rest = text.replace(BLOCK_RE, '\n').replace(/\n{3,}$/, '\n\n');
+  if (!lines.length) return rest.trim() ? `${rest.trimEnd()}\n` : '';
+  return `${rest.trimEnd() ? `${rest.trimEnd()}\n\n` : ''}${START}\n${lines.join('\n')}\n${END}\n`;
+}
+
+// Points the host at whatever is in its kete-loom rules folder now. Returns a skip reason or null.
+function sync(host, home, dryRun) {
+  const h = HOSTS[host];
+  const dir = h.dir(home);
+  const names = installedNames(dir);
+  const file = h.file(home);
+  if (h.mode === 'instructions') {
+    let data;
+    try {
+      data = readJson(file);
+    } catch (e) {
+      return e instanceof CommentedFileError ? `${e.message}. Add "${path.join(dir, '*.md')}" to its "instructions" array yourself.` : e.message;
+    }
+    const entry = path.join(dir, '*.md');
+    const list = (Array.isArray(data.instructions) ? data.instructions : []).filter((i) => i !== entry);
+    if (names.length) list.push(entry);
+    if (list.length) data.instructions = list;
+    else delete data.instructions;
+    if (!dryRun) {
+      if (Object.keys(data).length) writeAtomic(file, JSON.stringify(data, null, 2) + '\n');
+      else if (fs.existsSync(file)) fs.rmSync(file);
+    }
+    return null;
+  }
+  const lines = h.mode === 'import'
+    ? names.map(h.ref)
+    : names.map((n) => fs.readFileSync(path.join(dir, `${n}.md`), 'utf8').replace(/^<!--[^\n]*-->\n/, '').trimEnd());
+  const old = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  const next = withBlock(old, h.mode === 'inline' ? [lines.join('\n\n')].filter(Boolean) : lines);
+  if (h.mode === 'inline' && Buffer.byteLength(next) > CODEX_MAX_BYTES) {
+    return `~/.codex/AGENTS.md would be ${Buffer.byteLength(next)} bytes, over Codex's ${CODEX_MAX_BYTES}-byte limit; install fewer rules for Codex`;
+  }
+  if (!dryRun && next !== old) {
+    if (next) writeAtomic(file, next);
+    else fs.rmSync(file);
+  }
+  return null;
+}
+
+// Installs rules for one host. Returns result rows like the main installer's.
+function installRules(host, rules, { home, dryRun = false }) {
+  const h = HOSTS[host];
+  const dir = h.dir(home);
+  const before = installedNames(dir);
+  const rows = rules.map((r) => ({ target: host, kind: 'rule', name: r.dir, action: before.includes(r.dir) ? 'updated' : 'installed', dest: h.file(home) }));
+  if (dryRun) return rows;
+  fs.mkdirSync(dir, { recursive: true });
+  const previous = new Map(before.map((n) => [n, fs.readFileSync(path.join(dir, `${n}.md`), 'utf8')]));
+  for (const r of rules) fs.writeFileSync(path.join(dir, `${r.dir}.md`), render(r, 'plain').content);
+  const reason = sync(host, home, false);
+  if (reason) {
+    // Leave the folder as it was so it keeps matching what the host loads.
+    for (const r of rules) {
+      if (previous.has(r.dir)) fs.writeFileSync(path.join(dir, `${r.dir}.md`), previous.get(r.dir));
+      else fs.rmSync(path.join(dir, `${r.dir}.md`), { force: true });
+    }
+    return rows.map((row) => ({ ...row, action: 'skipped', reason }));
+  }
+  return rows;
+}
+
+// Removes the named rules (or all kete-loom rules) for one host.
+function uninstallRules(host, names, { home, dryRun = false }) {
+  const h = HOSTS[host];
+  const dir = h.dir(home);
+  const gone = installedNames(dir).filter((n) => !names || names.includes(n));
+  if (!gone.length) return [];
+  if (!dryRun) {
+    for (const n of gone) fs.rmSync(path.join(dir, `${n}.md`));
+    sync(host, home, false);
+    if (!installedNames(dir).length) {
+      fs.rmSync(dir, { recursive: true, force: true });
+      const parent = path.dirname(dir);
+      if (fs.existsSync(parent) && !fs.readdirSync(parent).length) fs.rmdirSync(parent);
+    }
+  }
+  return gone.map((n) => ({ target: host, kind: 'rule', name: n, action: 'removed', dest: h.file(home) }));
+}
+
+module.exports = { RULE_HOSTS, HOSTS, installRules, uninstallRules, installedNames, withBlock };