@zlnap/astrolabe 0.16.0 → 0.17.0

package/lib/setup/kimicode.js

@@ -0,0 +1,94 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const MANAGED_BEGIN = '# >>> astrolabe-managed-kimi-hooks >>>';
+const MANAGED_END = '# <<< astrolabe-managed-kimi-hooks <<<';
+
+const MANAGED_BLOCK = `${MANAGED_BEGIN}
+[[hooks]]
+event = "PreToolUse"
+matcher = "Read|Grep|Bash|mcp__astrolabe__.*"
+command = "astrolabe hooks remind --client=kimicode"
+
+[[hooks]]
+event = "SessionEnd"
+command = "astrolabe hooks cleanup"
+${MANAGED_END}
+`;
+
+function detectKimiCode(home, env, { whichFn, existsFn }) {
+  const evidence = [];
+  if (whichFn('kimi', env)) evidence.push('kimi on PATH');
+  if (existsFn(path.join(home, '.kimi-code'))) evidence.push('~/.kimi-code/');
+  if (existsFn(path.join(home, '.kimi-code', 'config.toml'))) {
+    evidence.push('~/.kimi-code/config.toml');
+  }
+  if (existsFn(path.join(home, '.kimi-code', 'mcp.json'))) {
+    evidence.push('~/.kimi-code/mcp.json');
+  }
+  return { detected: evidence.length > 0, evidence };
+}
+
+function resolveKimiMcpPath(home) {
+  return path.join(home, '.kimi-code', 'mcp.json');
+}
+
+function resolveKimiConfigToml(home) {
+  return path.join(home, '.kimi-code', 'config.toml');
+}
+
+/**
+ * Merge managed [[hooks]] into ~/.kimi-code/config.toml without touching other
+ * tables or user hook blocks (same marker strategy as DSH cordis patch).
+ */
+function mergeKimiHooksToml(filePath, { create = true, existsFn = fs.existsSync } = {}) {
+  let created = false;
+  let text = '';
+  if (existsFn(filePath)) {
+    text = fs.readFileSync(filePath, 'utf8');
+  } else if (!create) {
+    return { skipped: true, reason: `missing ${filePath} (will not create)` };
+  } else {
+    created = true;
+    text = '';
+  }
+
+  const begin = text.indexOf(MANAGED_BEGIN);
+  const end = text.indexOf(MANAGED_END);
+  let next;
+  let replaced = false;
+  if (begin >= 0 && end > begin) {
+    replaced = true;
+    const afterEnd = end + MANAGED_END.length;
+    let tail = text.slice(afterEnd);
+    if (tail.startsWith('\n')) tail = tail.slice(1);
+    next = `${text.slice(0, begin)}${MANAGED_BLOCK}${tail}`;
+  } else if (begin >= 0 || end >= 0) {
+    throw new Error(
+      `${filePath} has a broken astrolabe-managed-kimi-hooks marker; fix or remove it, then re-run setup`,
+    );
+  } else {
+    const trimmed = text.replace(/\s*$/, '');
+    next = trimmed ? `${trimmed}\n\n${MANAGED_BLOCK}` : `${MANAGED_BLOCK}`;
+  }
+  if (!next.endsWith('\n')) next += '\n';
+  return {
+    filePath,
+    text: next,
+    created,
+    replaced,
+    entryPreview: MANAGED_BLOCK.trim(),
+  };
+}
+
+module.exports = {
+  MANAGED_BEGIN,
+  MANAGED_END,
+  MANAGED_BLOCK,
+  detectKimiCode,
+  resolveKimiMcpPath,
+  resolveKimiConfigToml,
+  mergeKimiHooksToml,
+};

package/lib/setup/opencode.js

@@ -0,0 +1,159 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parseJsonc, upsertJsoncProperty } = require('./jsonc');
+
+const OPENCODE_GUARD_TS = `import type { Plugin } from "@opencode-ai/plugin";
+
+export const AstrolabeGuard: Plugin = async () => {
+  return {
+    "tool.execute.before": async (input, output) => {
+      const payload = JSON.stringify({
+        session_id: input.sessionID,
+        tool_name: input.tool,
+        tool_input: output.args ?? {},
+      });
+      const proc = Bun.spawnSync(["astrolabe", "hooks", "remind", "--client=opencode"], {
+        stdin: payload,
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+      const stdout = new TextDecoder().decode(proc.stdout).trim();
+      if (stdout) {
+        const decision = JSON.parse(stdout);
+        if (decision.decision === "deny") {
+          throw new Error(decision.reason);
+        }
+      }
+    },
+  };
+};
+export default AstrolabeGuard;
+`;
+
+function resolveOpenCodeConfigPath(home, existsFn) {
+  const candidates = [
+    path.join(home, '.config', 'opencode', 'opencode.jsonc'),
+    path.join(home, '.config', 'opencode', 'opencode.json'),
+    path.join(home, '.config', 'opencode', 'config.json'),
+    path.join(home, '.opencode', 'opencode.jsonc'),
+    path.join(home, '.opencode', 'opencode.json'),
+    path.join(home, '.opencode', 'config.json'),
+  ];
+  for (const cand of candidates) {
+    if (existsFn(cand)) return cand;
+  }
+  // Default: new-style user config (JSONC).
+  return path.join(home, '.config', 'opencode', 'opencode.jsonc');
+}
+
+/**
+ * @returns {'v1'|'v2'|'mcpServers'}
+ */
+function detectOpenCodeMcpFormat(doc) {
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) return 'v1';
+  if (doc.mcpServers && typeof doc.mcpServers === 'object' && !Array.isArray(doc.mcpServers)) {
+    return 'mcpServers';
+  }
+  if (doc.mcp && typeof doc.mcp === 'object' && !Array.isArray(doc.mcp)) {
+    if (doc.mcp.servers && typeof doc.mcp.servers === 'object' && !Array.isArray(doc.mcp.servers)) {
+      return 'v2';
+    }
+    return 'v1';
+  }
+  // New file: prefer V1 (OpenCode 1.x / docs.opencode.ai classic shape).
+  return 'v1';
+}
+
+function openCodeServerEntry(launch, format) {
+  const command = [launch.command, ...launch.args];
+  if (format === 'mcpServers') {
+    return { command: launch.command, args: launch.args };
+  }
+  if (format === 'v2') {
+    return { type: 'local', command };
+  }
+  // v1
+  return { type: 'local', command, enabled: true };
+}
+
+/**
+ * Merge Astrolabe into an OpenCode config file, preserving JSONC comments when
+ * the parent `mcp` / `mcp.servers` object already exists.
+ */
+function mergeOpenCodeMcpFile(filePath, launch, { create = true, existsFn = fs.existsSync } = {}) {
+  let created = false;
+  let raw = '';
+  let format = 'v1';
+  if (existsFn(filePath)) {
+    raw = fs.readFileSync(filePath, 'utf8');
+    try {
+      format = detectOpenCodeMcpFormat(parseJsonc(raw));
+    } catch (err) {
+      throw new Error(`${filePath} is not valid JSON/JSONC: ${err.message}`);
+    }
+  } else if (!create) {
+    return { skipped: true, reason: `missing ${filePath} (will not create)` };
+  } else {
+    created = true;
+    raw = '{\n  "$schema": "https://opencode.ai/config.json"\n}\n';
+  }
+
+  const entry = openCodeServerEntry(launch, format);
+  let parentPath;
+  if (format === 'mcpServers') parentPath = ['mcpServers'];
+  else if (format === 'v2') parentPath = ['mcp', 'servers'];
+  else parentPath = ['mcp'];
+
+  const result = upsertJsoncProperty(raw, parentPath, 'astrolabe', entry, { indent: 2 });
+  return {
+    filePath,
+    text: result.text,
+    created,
+    replaced: result.replaced,
+    format,
+    entry,
+    commentsPreserved: result.commentsPreserved !== false,
+    write: null, // filled by caller with writeTextAtomic
+  };
+}
+
+function detectOpenCode(home, env, { whichFn, existsFn }) {
+  const evidence = [];
+  if (whichFn('opencode', env)) evidence.push('opencode on PATH');
+  if (existsFn(path.join(home, '.config', 'opencode'))) evidence.push('~/.config/opencode/');
+  if (existsFn(path.join(home, '.opencode'))) evidence.push('~/.opencode/');
+  return { detected: evidence.length > 0, evidence };
+}
+
+function planOpenCodeGuardPlugin(home, existsFn) {
+  // Prefer user-level plugins dir used by OpenCode 1.x on this Mac.
+  const userPlugins = path.join(home, '.config', 'opencode', 'plugins');
+  const filePath = path.join(userPlugins, 'astrolabe-guard.ts');
+  return {
+    kind: 'opencode-guard',
+    filePath,
+    summary: `write OpenCode guard plugin ${filePath}`,
+    apply() {
+      const created = !existsFn(filePath);
+      return {
+        filePath,
+        created,
+        replaced: !created,
+        text: OPENCODE_GUARD_TS,
+        write: null,
+      };
+    },
+  };
+}
+
+module.exports = {
+  OPENCODE_GUARD_TS,
+  resolveOpenCodeConfigPath,
+  detectOpenCodeMcpFormat,
+  openCodeServerEntry,
+  mergeOpenCodeMcpFile,
+  detectOpenCode,
+  planOpenCodeGuardPlugin,
+};

package/lib/setup/prompt.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const fs = require('fs');
+
+function isTTY() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+function readLine(question) {
+  process.stdout.write(question);
+  if (!process.stdin.isTTY) {
+    return '';
+  }
+  const buf = Buffer.alloc(1024);
+  let n = 0;
+  try {
+    n = fs.readSync(0, buf, 0, buf.length, null);
+  } catch {
+    return '';
+  }
+  return buf.toString('utf8', 0, n).replace(/\r?\n$/, '');
+}
+
+function confirm(question, { defaultYes = false } = {}) {
+  const hint = defaultYes ? 'Y/n' : 'y/N';
+  const answer = readLine(`${question} [${hint}] `).trim().toLowerCase();
+  if (!answer) return defaultYes;
+  return answer === 'y' || answer === 'yes';
+}
+
+/**
+ * Multi-select from rows: [{ id, label, detected, evidence }]
+ * Returns selected ids.
+ */
+function selectClients(rows, { preselectDetected = true } = {}) {
+  if (!isTTY()) {
+    return rows.filter((r) => r.detected).map((r) => r.id);
+  }
+
+  process.stdout.write('\nDetected / known agents:\n');
+  rows.forEach((row, i) => {
+    const mark = row.detected ? '*' : ' ';
+    const status = row.detected
+      ? `detected (${row.evidence.join(', ')})`
+      : 'not detected';
+    process.stdout.write(`  ${i + 1}. [${mark}] ${row.label} (${row.id}) — ${status}\n`);
+  });
+  process.stdout.write(
+    '\nEnter numbers to configure (e.g. 1,2), "d" for all detected, "a" for all, or empty to cancel:\n> ',
+  );
+
+  const answer = readLine('').trim().toLowerCase();
+  if (!answer) return [];
+  if (answer === 'd') return rows.filter((r) => r.detected).map((r) => r.id);
+  if (answer === 'a') return rows.map((r) => r.id);
+
+  const selected = new Set();
+  for (const part of answer.split(/[,\s]+/)) {
+    if (!part) continue;
+    const n = Number(part);
+    if (!Number.isInteger(n) || n < 1 || n > rows.length) {
+      throw new Error(`invalid selection: ${part}`);
+    }
+    selected.add(rows[n - 1].id);
+  }
+  return [...selected];
+}
+
+module.exports = { isTTY, readLine, confirm, selectClients };

package/lib/setup/run.js

@@ -0,0 +1,305 @@
+'use strict';
+
+const path = require('path');
+const os = require('os');
+const {
+  CLIENTS,
+  getClient,
+  canonicalClientId,
+  resolveLaunch,
+  mergeCursorPermissions,
+  backupFile,
+  writeJsonAtomic,
+} = require('./clients');
+const { parseArgs, USAGE } = require('./args');
+const { isTTY, confirm, selectClients } = require('./prompt');
+
+function resolveHome(homeFlag) {
+  if (homeFlag) return path.resolve(homeFlag);
+  if (process.env.HOME) return process.env.HOME;
+  if (process.env.USERPROFILE) return process.env.USERPROFILE;
+  return os.homedir();
+}
+
+function detectAll(home) {
+  return CLIENTS.map((client) => {
+    const { detected, evidence } = client.detect(home);
+    return {
+      id: client.id,
+      label: client.label,
+      context: client.context,
+      detected,
+      evidence,
+    };
+  });
+}
+
+function printList(rows) {
+  for (const row of rows) {
+    const status = row.detected ? 'detected' : 'missing';
+    const ev = row.evidence.length ? ` (${row.evidence.join('; ')})` : '';
+    process.stdout.write(`${row.id.padEnd(18)} ${status}${ev}\n`);
+  }
+}
+
+function chooseIds(rows, opts) {
+  if (opts.clients && opts.clients.length) {
+    const unknown = opts.clients.filter((id) => !getClient(id));
+    if (unknown.length) {
+      throw new Error(`unknown client id(s): ${unknown.join(', ')}`);
+    }
+    // Deduplicate aliases onto canonical ids (e.g. dsh → deepseek-harness).
+    return [...new Set(opts.clients.map((id) => canonicalClientId(id)))];
+  }
+  if (opts.yes) {
+    const detected = rows.filter((r) => r.detected).map((r) => r.id);
+    if (!detected.length) {
+      throw new Error('no clients detected; pass --clients=... or run interactively');
+    }
+    return detected;
+  }
+  if (!isTTY()) {
+    throw new Error(
+      'stdin is not a TTY; pass --yes (all detected) or --clients=claude-code,cursor,...',
+    );
+  }
+  return selectClients(rows);
+}
+
+function formatEntryPreview(planResult) {
+  if (planResult.entryPreview) return String(planResult.entryPreview).trimEnd();
+  if (planResult.entry) {
+    return JSON.stringify({ astrolabe: planResult.entry }, null, 2);
+  }
+  if (planResult.doc && planResult.doc.mcpServers) {
+    return JSON.stringify(
+      { mcpServers: { astrolabe: planResult.doc.mcpServers.astrolabe } },
+      null,
+      2,
+    );
+  }
+  if (planResult.text) {
+    const match = planResult.text.match(/\[mcp_servers\.astrolabe\][\s\S]*?(?=\n\[|$)/);
+    if (match) return match[0].trimEnd();
+    const managed = planResult.text.match(
+      /# >>> astrolabe-managed-dsh-guard >>>[\s\S]*?# <<< astrolabe-managed-dsh-guard <<</,
+    );
+    if (managed) return managed[0].trimEnd();
+    // OpenCode: show a short snippet around "astrolabe"
+    const idx = planResult.text.indexOf('"astrolabe"');
+    if (idx >= 0) {
+      const start = Math.max(0, planResult.text.lastIndexOf('\n', idx) - 80);
+      return planResult.text.slice(start, Math.min(planResult.text.length, idx + 220)).trimEnd();
+    }
+    return planResult.text.trimEnd();
+  }
+  return '';
+}
+
+function run(argv = process.argv.slice(2)) {
+  const opts = parseArgs(argv);
+  if (opts.help) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  const home = resolveHome(opts.home);
+  const rows = detectAll(home);
+
+  if (opts.list) {
+    printList(rows);
+    return 0;
+  }
+
+  let selectedIds;
+  try {
+    selectedIds = chooseIds(rows, opts);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    return 1;
+  }
+  if (!selectedIds.length) {
+    process.stdout.write('Nothing selected; no files changed.\n');
+    return 0;
+  }
+
+  const actions = [];
+  for (const id of selectedIds) {
+    const client = getClient(id);
+    const launch = resolveLaunch({
+      context: client.context,
+      native: opts.native,
+      commandOverride: opts.command,
+    });
+    const plan = client.plan({ home, launch, withHooks: opts.withHooks });
+    const applied = plan.apply();
+    actions.push({
+      id,
+      label: client.label,
+      summary: plan.summary,
+      launch,
+      applied,
+    });
+  }
+
+  let permissionsPlan = null;
+  if (opts.cursorPermissions && selectedIds.includes('cursor')) {
+    permissionsPlan = mergeCursorPermissions(home, {
+      dryRun: opts.dryRun,
+      yes: opts.yes,
+    });
+  }
+
+  process.stdout.write('\nPlan:\n');
+  for (const action of actions) {
+    if (action.applied.skipped) {
+      process.stdout.write(`  - ${action.label}: SKIP ${action.applied.reason}\n`);
+      continue;
+    }
+    const op = action.applied.created ? 'create' : action.applied.replaced ? 'update' : 'write';
+    process.stdout.write(`  - ${action.label}: ${op} ${action.applied.filePath}\n`);
+    if (action.applied.installDirs) {
+      for (const dir of action.applied.installDirs) {
+        process.stdout.write(`      plugin → ${dir}\n`);
+      }
+    }
+    if (Array.isArray(action.applied.results)) {
+      for (const step of action.applied.results) {
+        if (!step || step.skipped) continue;
+        if (step.filePath && step.filePath !== action.applied.filePath) {
+          const sop = step.created ? 'create' : step.replaced ? 'update' : 'write';
+          process.stdout.write(`      ${sop} ${step.filePath}\n`);
+        }
+      }
+    }
+    if (action.id !== 'deepseek-harness') {
+      process.stdout.write(`      command: ${action.launch.command} ${action.launch.args.join(' ')}\n`);
+    }
+    const preview = formatEntryPreview(action.applied);
+    if (preview) {
+      for (const line of preview.split('\n')) {
+        process.stdout.write(`      ${line}\n`);
+      }
+    }
+  }
+  if (permissionsPlan) {
+    process.stdout.write(
+      `  - Cursor permissions: merge ${permissionsPlan.added} allowlist entries into ${permissionsPlan.filePath}` +
+        `${permissionsPlan.created ? ' (new file)' : ''}\n`,
+    );
+  }
+
+  if (opts.dryRun) {
+    process.stdout.write('\n[dry-run] No files written.\n');
+    return 0;
+  }
+
+  if (!opts.yes && isTTY()) {
+    if (!confirm('Apply these changes?', { defaultYes: false })) {
+      process.stdout.write('Cancelled; no files written.\n');
+      return 1;
+    }
+  } else if (!opts.yes && !isTTY()) {
+    process.stderr.write('Refusing to write without --yes in non-interactive mode.\n');
+    return 1;
+  }
+
+  const summary = [];
+  for (const action of actions) {
+    if (action.applied.skipped) {
+      summary.push({ id: action.id, status: 'skipped', reason: action.applied.reason });
+      continue;
+    }
+    const backup = backupFile(action.applied.filePath);
+    action.applied.write();
+    summary.push({
+      id: action.id,
+      status: 'written',
+      file: action.applied.filePath,
+      backup,
+    });
+    process.stdout.write(
+      `Wrote ${action.applied.filePath}${backup ? ` (backup ${backup})` : ''}\n`,
+    );
+  }
+
+  if (permissionsPlan) {
+    if (permissionsPlan.created && !opts.yes && isTTY()) {
+      process.stdout.write(
+        `\nNote: defining mcpAllowlist replaces the IDE MCP allowlist table. ` +
+          `Other MCP tools must be listed in the same file. Cursor Run Mode must be on.\n`,
+      );
+      if (!confirm(`Create ${permissionsPlan.filePath}?`, { defaultYes: false })) {
+        process.stdout.write('Skipped Cursor permissions.json\n');
+        permissionsPlan = null;
+      }
+    }
+    if (permissionsPlan) {
+      const backup = backupFile(permissionsPlan.filePath);
+      writeJsonAtomic(permissionsPlan.filePath, permissionsPlan.doc);
+      process.stdout.write(
+        `Merged Cursor allowlist ${permissionsPlan.filePath} ` +
+          `(+${permissionsPlan.added}, total ${permissionsPlan.total})` +
+          `${backup ? `; backup ${backup}` : ''}\n`,
+      );
+      summary.push({
+        id: 'cursor-permissions',
+        status: 'written',
+        file: permissionsPlan.filePath,
+        backup,
+      });
+    }
+  }
+
+  process.stdout.write('\nDone. Next steps:\n');
+  process.stdout.write('  1. Restart each configured agent / IDE so it reloads MCP servers.\n');
+  process.stdout.write('  2. Verify: npx -y @zlnap/astrolabe --version\n');
+  if (selectedIds.includes('claude-code')) {
+    process.stdout.write('  3. Claude Code: claude mcp get astrolabe\n');
+  }
+  if (selectedIds.includes('cursor')) {
+    process.stdout.write(
+      '  3. Cursor: open Settings → MCP and confirm astrolabe is listed; enable Run Mode for allowlist.\n',
+    );
+  }
+  if (selectedIds.includes('opencode')) {
+    process.stdout.write(
+      '  3. OpenCode: restart opencode; MCP is under mcp / mcp.servers in ~/.config/opencode/.\n',
+    );
+    if (!opts.withHooks) {
+      process.stdout.write(
+        '     Tip: re-run with --with-hooks to install plugins/astrolabe-guard.ts\n',
+      );
+    }
+  }
+  if (selectedIds.includes('deepseek-harness')) {
+    process.stdout.write(
+      '  3. DSH: native guard is in cordis.patch.yml; add the Astrolabe MCP server per repo in the DSH UI.\n',
+    );
+  }
+  if (selectedIds.includes('codebuddy')) {
+    process.stdout.write(
+      '  3. Codebuddy: MCP in ~/.codebuddy/.mcp.json; restart codebuddy. Tip: --with-hooks merges ~/.codebuddy/settings.json.\n',
+    );
+  }
+  if (selectedIds.includes('grok')) {
+    process.stdout.write(
+      '  3. Grok Build: MCP in ~/.grok/config.toml ([mcp_servers.astrolabe]); tip: --with-hooks writes ~/.grok/hooks/astrolabe.json.\n',
+    );
+  }
+  if (selectedIds.includes('kimicode')) {
+    process.stdout.write(
+      '  3. Kimi Code: MCP in ~/.kimi-code/mcp.json; tip: --with-hooks merges [[hooks]] into config.toml.\n',
+    );
+  }
+  if (selectedIds.includes('zcode')) {
+    process.stdout.write(
+      '  3. ZCode: MCP under mcp.servers in ~/.zcode/cli/config.json; tip: --with-hooks adds hooks.events.PreToolUse (no SessionEnd).\n',
+    );
+  }
+  return summary.some((row) => row.status === 'written') || summary.every((row) => row.status === 'skipped')
+    ? 0
+    : 0;
+}
+
+module.exports = { run, detectAll, resolveHome };