knowy-cli 0.1.2

package/src/adapters/registry.js

@@ -0,0 +1,276 @@
+/**
+ * Tool registry — defines how to detect and handshake with each AI/spec tool.
+ *
+ * Each entry:
+ *   id          — unique key
+ *   name        — human-readable label
+ *   detect      — array of { type: 'file'|'dir', path } checks (OR logic)
+ *   targets     — files to inject the Knowy reference into
+ *   readsAgents — true if the tool also reads AGENTS.md
+ *   category    — 'ai' | 'spec' | 'standard'
+ */
+export const TOOL_REGISTRY = [
+  // ── Cross-tool standard ──────────────────────────────────────────
+  {
+    id: 'agents-md',
+    name: 'AGENTS.md (Cross-tool standard)',
+    detect: [{ type: 'file', path: 'AGENTS.md' }],
+    targets: [{ file: 'AGENTS.md', format: 'markdown' }],
+    readsAgents: true,
+    category: 'standard',
+    alwaysAvailable: true,
+  },
+
+  // ── AI coding tools ──────────────────────────────────────────────
+  {
+    id: 'claude-code',
+    name: 'Claude Code',
+    detect: [{ type: 'file', path: 'CLAUDE.md' }],
+    targets: [{ file: 'CLAUDE.md', format: 'markdown' }],
+    readsAgents: false,
+    category: 'ai',
+  },
+  {
+    id: 'cursor',
+    name: 'Cursor',
+    detect: [{ type: 'dir', path: '.cursor' }],
+    targets: [{ file: '.cursor/rules/knowy.mdc', format: 'mdc' }],
+    readsAgents: true,
+    category: 'ai',
+  },
+  {
+    id: 'windsurf',
+    name: 'Windsurf',
+    detect: [
+      { type: 'file', path: '.windsurfrules' },
+      { type: 'dir', path: '.windsurf' },
+    ],
+    targets: [{ file: '.windsurf/rules/knowy.md', format: 'markdown' }],
+    readsAgents: true,
+    category: 'ai',
+  },
+  {
+    id: 'copilot',
+    name: 'GitHub Copilot',
+    detect: [
+      { type: 'file', path: '.github/copilot-instructions.md' },
+      { type: 'dir', path: '.github/instructions' },
+    ],
+    targets: [{ file: '.github/copilot-instructions.md', format: 'markdown' }],
+    readsAgents: true,
+    category: 'ai',
+  },
+  {
+    id: 'codex',
+    name: 'Codex CLI (OpenAI)',
+    detect: [],
+    targets: [{ file: 'AGENTS.md', format: 'markdown' }],
+    readsAgents: true,
+    category: 'ai',
+  },
+  {
+    id: 'gemini',
+    name: 'Gemini CLI',
+    detect: [{ type: 'file', path: 'GEMINI.md' }],
+    targets: [{ file: 'GEMINI.md', format: 'markdown' }],
+    readsAgents: false,
+    category: 'ai',
+  },
+  {
+    id: 'kiro',
+    name: 'Kiro',
+    detect: [{ type: 'dir', path: '.kiro' }],
+    targets: [{ file: '.kiro/steering/knowy.md', format: 'markdown' }],
+    readsAgents: false,
+    category: 'ai',
+  },
+  {
+    id: 'amazon-q',
+    name: 'Amazon Q Developer',
+    detect: [{ type: 'dir', path: '.amazonq' }],
+    targets: [{ file: '.amazonq/rules/knowy.md', format: 'markdown' }],
+    readsAgents: false,
+    category: 'ai',
+  },
+  {
+    id: 'cline',
+    name: 'Cline',
+    detect: [
+      { type: 'file', path: '.clinerules' },
+      { type: 'dir', path: '.clinerules' },
+    ],
+    targets: [{ file: '.clinerules/knowy.md', format: 'markdown' }],
+    readsAgents: false,
+    category: 'ai',
+  },
+  {
+    id: 'roo-code',
+    name: 'Roo Code',
+    detect: [{ type: 'dir', path: '.roo' }],
+    targets: [{ file: '.roo/rules/knowy.md', format: 'markdown' }],
+    readsAgents: true,
+    category: 'ai',
+  },
+  {
+    id: 'kilo-code',
+    name: 'Kilo Code',
+    detect: [{ type: 'dir', path: '.kilocode' }],
+    targets: [{ file: '.kilocode/rules/knowy.md', format: 'markdown' }],
+    readsAgents: true,
+    category: 'ai',
+  },
+  {
+    id: 'aider',
+    name: 'Aider',
+    detect: [{ type: 'file', path: '.aider.conf.yml' }],
+    targets: [{ file: 'AGENTS.md', format: 'markdown' }],
+    readsAgents: true,
+    category: 'ai',
+  },
+  {
+    id: 'continue',
+    name: 'Continue.dev',
+    detect: [{ type: 'dir', path: '.continue' }],
+    targets: [{ file: '.continue/rules/knowy.md', format: 'markdown' }],
+    readsAgents: false,
+    category: 'ai',
+  },
+  {
+    id: 'augment',
+    name: 'Augment Code',
+    detect: [
+      { type: 'dir', path: '.augment' },
+      { type: 'file', path: '.augment-guidelines' },
+    ],
+    targets: [{ file: '.augment/rules/knowy.md', format: 'markdown' }],
+    readsAgents: true,
+    category: 'ai',
+  },
+  {
+    id: 'amp',
+    name: 'Amp (Sourcegraph)',
+    detect: [],
+    targets: [{ file: 'AGENTS.md', format: 'markdown' }],
+    readsAgents: true,
+    category: 'ai',
+  },
+  {
+    id: 'devin',
+    name: 'Devin',
+    detect: [],
+    targets: [{ file: 'AGENTS.md', format: 'markdown' }],
+    readsAgents: true,
+    category: 'ai',
+  },
+  {
+    id: 'warp',
+    name: 'Warp',
+    detect: [{ type: 'file', path: 'WARP.md' }],
+    targets: [{ file: 'WARP.md', format: 'markdown' }],
+    readsAgents: true,
+    category: 'ai',
+  },
+  {
+    id: 'zed',
+    name: 'Zed',
+    detect: [{ type: 'file', path: '.rules' }],
+    targets: [{ file: '.rules', format: 'markdown' }],
+    readsAgents: true,
+    category: 'ai',
+  },
+  {
+    id: 'opencode',
+    name: 'OpenCode',
+    detect: [
+      { type: 'file', path: 'opencode.json' },
+      { type: 'file', path: 'opencode.jsonc' },
+    ],
+    targets: [{ file: 'AGENTS.md', format: 'markdown' }],
+    readsAgents: true,
+    category: 'ai',
+  },
+  {
+    id: 'qodo',
+    name: 'Qodo',
+    detect: [],
+    targets: [{ file: 'AGENTS.md', format: 'markdown' }],
+    readsAgents: true,
+    category: 'ai',
+  },
+  {
+    id: 'jetbrains',
+    name: 'JetBrains AI Assistant',
+    detect: [{ type: 'dir', path: '.aiassistant' }],
+    targets: [{ file: '.aiassistant/rules/knowy.md', format: 'markdown' }],
+    readsAgents: false,
+    category: 'ai',
+  },
+  {
+    id: 'tabnine',
+    name: 'Tabnine',
+    detect: [
+      { type: 'dir', path: '.tabnine' },
+      { type: 'file', path: '.tabnine' },
+    ],
+    targets: [{ file: '.tabnine/guidelines/knowy.md', format: 'markdown' }],
+    readsAgents: false,
+    category: 'ai',
+  },
+  {
+    id: 'replit',
+    name: 'Replit Agent',
+    detect: [{ type: 'file', path: 'replit.md' }],
+    targets: [{ file: 'replit.md', format: 'markdown' }],
+    readsAgents: false,
+    category: 'ai',
+  },
+  {
+    id: 'bolt',
+    name: 'Bolt.new',
+    detect: [{ type: 'dir', path: '.bolt' }],
+    targets: [{ file: '.bolt/prompt', format: 'markdown' }],
+    readsAgents: false,
+    category: 'ai',
+  },
+
+  // ── Spec tools ───────────────────────────────────────────────────
+  {
+    id: 'speckit',
+    name: 'Speckit',
+    detect: [{ type: 'dir', path: '.specify' }],
+    targets: [{ file: '.specify/memory/constitution.md', format: 'markdown' }],
+    readsAgents: false,
+    category: 'spec',
+  },
+  {
+    id: 'openspec',
+    name: 'OpenSpec',
+    detect: [{ type: 'dir', path: 'openspec' }],
+    targets: [{ file: 'openspec/project.md', format: 'markdown' }],
+    readsAgents: false,
+    category: 'spec',
+  },
+  {
+    id: 'kiro-specs',
+    name: 'Kiro Specs',
+    detect: [{ type: 'dir', path: '.kiro/specs' }],
+    targets: [{ file: '.kiro/steering/knowy.md', format: 'markdown' }],
+    readsAgents: false,
+    category: 'spec',
+  },
+];
+
+/** Get tools that can be detected (have detect rules) */
+export function getDetectableTools() {
+  return TOOL_REGISTRY.filter(t => t.detect.length > 0);
+}
+
+/** Get all selectable tools (for the interactive menu) */
+export function getSelectableTools() {
+  return TOOL_REGISTRY.filter(t => t.category !== 'standard' || t.alwaysAvailable);
+}
+
+/** Find a tool by id */
+export function getToolById(id) {
+  return TOOL_REGISTRY.find(t => t.id === id);
+}

package/src/cli.js

@@ -0,0 +1,58 @@
+import { VERSION } from './constants.js';
+import { resolveLanguage, detectLanguage, normalizeLanguage, t } from './i18n.js';
+
+function buildHelp(lang) {
+  return `
+knowy v${VERSION} — ${t(lang, 'cli.help.tagline')}
+
+${t(lang, 'cli.help.usage')}:
+  knowy <command>
+
+${t(lang, 'cli.help.commands')}:
+  init        ${t(lang, 'cli.help.init')}
+  update      ${t(lang, 'cli.help.update')}
+  setup-mcp   ${t(lang, 'cli.help.setupMcp')}
+
+${t(lang, 'cli.help.options')}:
+  --help, -h       ${t(lang, 'cli.help.help')}
+  --version, -v    ${t(lang, 'cli.help.version')}
+`.trim();
+}
+
+export async function run(args) {
+  const cmd = args[0];
+  const lang = await resolveLanguage(process.cwd()).catch(() => normalizeLanguage(detectLanguage()));
+
+  if (!cmd || cmd === '--help' || cmd === '-h') {
+    console.log(buildHelp(lang));
+    return;
+  }
+
+  if (cmd === '--version' || cmd === '-v') {
+    console.log(VERSION);
+    return;
+  }
+
+  if (cmd === 'init') {
+    const { init } = await import('./commands/init.js');
+    await init(process.cwd());
+    return;
+  }
+
+  if (cmd === 'update') {
+    const { update } = await import('./commands/update.js');
+    await update(process.cwd());
+    return;
+  }
+
+  if (cmd === 'setup-mcp') {
+    const { setupMcp } = await import('./commands/setup-mcp.js');
+    await setupMcp();
+    return;
+  }
+
+  const unknownMsg = t(lang, 'cli.unknownCommand');
+  console.error(typeof unknownMsg === 'function' ? unknownMsg(cmd) : `Unknown command: ${cmd}`);
+  console.log(buildHelp(lang));
+  process.exitCode = 1;
+}

package/src/commands/init.js

@@ -0,0 +1,130 @@
+import { readFile, writeFile, access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { KNOWLEDGE_DIR, KNOWY_CONFIG, VERSION } from '../constants.js';
+import { scaffoldKnowledge } from '../scaffold.js';
+import { installTemplates } from '../templates.js';
+import { installSkills } from '../skills.js';
+import { detectTools } from '../adapters/detect.js';
+import { getToolById, TOOL_REGISTRY } from '../adapters/registry.js';
+import { injectHandshake } from '../adapters/handshake.js';
+import { confirm, multiSelect, select } from '../ui.js';
+import { detectLanguage, normalizeLanguage, t } from '../i18n.js';
+
+async function exists(p) {
+  try { await access(p); return true; } catch { return false; }
+}
+
+const LANGUAGE_CHOICES = [
+  { id: 'en', name: 'English' },
+  { id: 'zh-TW', name: '繁體中文' },
+];
+
+export async function init(projectRoot) {
+  // Detect language
+  const detectedLang = normalizeLanguage(detectLanguage());
+  let lang = detectedLang;
+
+  console.log(`\n🧠 knowy v${VERSION}\n`);
+
+  // 1. Language selection
+  const msg = t(lang, 'cli.init.langDetected');
+  console.log(typeof msg === 'function' ? msg(lang) : msg);
+
+  const langChoices = LANGUAGE_CHOICES.map(c => ({
+    ...c,
+    checked: c.id === detectedLang,
+  }));
+  lang = await select(t(lang, 'cli.init.selectLanguage'), langChoices);
+
+  // 2. Check if .knowledge/ already exists
+  const knowledgeExists = await exists(join(projectRoot, KNOWLEDGE_DIR));
+  if (knowledgeExists) {
+    console.log(t(lang, 'cli.init.exists'));
+    const proceed = await confirm(t(lang, 'cli.init.continue'));
+    if (!proceed) {
+      console.log(t(lang, 'cli.init.aborted'));
+      return;
+    }
+  }
+
+  // 3. Scaffold .knowledge/
+  console.log('');
+  const scaffoldReport = await scaffoldKnowledge(projectRoot, lang);
+  for (const f of scaffoldReport.created) console.log(t(lang, 'cli.init.created')(f));
+  for (const f of scaffoldReport.skipped) console.log(t(lang, 'cli.init.skipped')(f));
+
+  // 4. Install templates
+  const templates = await installTemplates(projectRoot, lang);
+  console.log(t(lang, 'cli.init.templates')(templates.length));
+
+  // 5. Detect tools
+  const { detected } = await detectTools(projectRoot);
+  if (detected.length > 0) {
+    const names = detected.map(id => getToolById(id)?.name).filter(Boolean);
+    console.log(`\n${t(lang, 'cli.init.detected')(names.join(', '))}`);
+  }
+
+  // 6. Build selection choices
+  const aiTools = TOOL_REGISTRY.filter(t => t.category === 'ai');
+  const specTools = TOOL_REGISTRY.filter(t => t.category === 'spec');
+  const standardTools = TOOL_REGISTRY.filter(t => t.category === 'standard');
+
+  const choices = [
+    ...standardTools.map(t => ({
+      id: t.id,
+      name: t.name,
+      checked: true,
+    })),
+    ...aiTools.map(t => ({
+      id: t.id,
+      name: t.name,
+      checked: detected.includes(t.id),
+    })),
+    ...specTools.map(t => ({
+      id: t.id,
+      name: `${t.name} (spec tool)`,
+      checked: detected.includes(t.id),
+    })),
+  ];
+
+  const selectedIds = await multiSelect(t(lang, 'cli.init.selectTools'), choices, lang);
+
+  // 7. Handshake
+  const handshaked = [];
+  const writtenFiles = new Set();
+
+  for (const id of selectedIds) {
+    const tool = getToolById(id);
+    if (!tool) continue;
+
+    for (const target of tool.targets) {
+      if (writtenFiles.has(target.file)) continue;
+      const result = await injectHandshake(projectRoot, target);
+      writtenFiles.add(target.file);
+      const msgKey = `cli.init.handshake.${result.action}`;
+      console.log(t(lang, msgKey)(result.file, tool.name));
+    }
+  }
+
+  // 8. Install skills
+  const skills = await installSkills(projectRoot);
+  console.log(`\n${t(lang, 'cli.init.skills')(skills.length)}`);
+
+  // 9. Update .knowy.json
+  const configPath = join(projectRoot, KNOWY_CONFIG);
+  let config;
+  try {
+    config = JSON.parse(await readFile(configPath, 'utf-8'));
+  } catch {
+    config = { version: VERSION, createdAt: new Date().toISOString() };
+  }
+  config.version = VERSION;
+  config.language = lang;
+  config.tools = selectedIds;
+  config.updatedAt = new Date().toISOString();
+  await writeFile(configPath, JSON.stringify(config, null, 2) + '\n');
+
+  // 10. Summary
+  console.log(`\n${t(lang, 'cli.init.done')}\n`);
+  console.log(`${t(lang, 'cli.init.nextStep')}\n`);
+}

package/src/commands/setup-mcp.js

@@ -0,0 +1,87 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { VERSION } from '../constants.js';
+import { multiSelect } from '../ui.js';
+import { resolveLanguage, t } from '../i18n.js';
+
+const MCP_TARGETS = [
+  {
+    id: 'claude-code',
+    name: 'Claude Code (project settings)',
+    configPath: (projectRoot) => join(projectRoot, '.claude', 'settings.local.json'),
+    ensureDir: (projectRoot) => join(projectRoot, '.claude'),
+    scope: 'project',
+  },
+  {
+    id: 'claude-desktop',
+    name: 'Claude Desktop',
+    configPath: () => join(homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json'),
+    ensureDir: () => join(homedir(), 'Library', 'Application Support', 'Claude'),
+    scope: 'global',
+  },
+  {
+    id: 'cursor',
+    name: 'Cursor (project settings)',
+    configPath: (projectRoot) => join(projectRoot, '.cursor', 'mcp.json'),
+    ensureDir: (projectRoot) => join(projectRoot, '.cursor'),
+    scope: 'project',
+  },
+];
+
+const MCP_ENTRY = {
+  command: 'npx',
+  args: ['-y', 'knowy-cli', '--', 'knowy-mcp'],
+};
+
+async function readJsonSafe(path) {
+  try {
+    return JSON.parse(await readFile(path, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+export async function setupMcp(projectRoot = process.cwd()) {
+  const lang = await resolveLanguage(projectRoot);
+
+  console.log(`\n🧠 knowy v${VERSION} — ${t(lang, 'cli.mcp.title')}\n`);
+
+  const choices = MCP_TARGETS.map(t => ({
+    id: t.id,
+    name: `${t.name} (${t.scope})`,
+    checked: false,
+  }));
+
+  const selectedIds = await multiSelect(t(lang, 'cli.mcp.selectTools'), choices, lang);
+
+  if (selectedIds.length === 0) {
+    console.log(`\n${t(lang, 'cli.mcp.noSelection')}`);
+    return;
+  }
+
+  for (const id of selectedIds) {
+    const target = MCP_TARGETS.find(t => t.id === id);
+    if (!target) continue;
+
+    const configPath = target.configPath(projectRoot);
+    const dir = target.ensureDir(projectRoot);
+    await mkdir(dir, { recursive: true });
+
+    let config = await readJsonSafe(configPath) || {};
+
+    if (!config.mcpServers) config.mcpServers = {};
+
+    if (config.mcpServers.knowy) {
+      console.log(t(lang, 'cli.mcp.alreadyConfigured')(target.name));
+      continue;
+    }
+
+    config.mcpServers.knowy = MCP_ENTRY;
+    await writeFile(configPath, JSON.stringify(config, null, 2) + '\n');
+    console.log(t(lang, 'cli.mcp.added')(target.name));
+  }
+
+  console.log(`\n${t(lang, 'cli.mcp.done')}`);
+  console.log(`${t(lang, 'cli.mcp.restart')}\n`);
+}

package/src/commands/update.js

@@ -0,0 +1,90 @@
+import { readFile, writeFile, access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { KNOWY_CONFIG, VERSION } from '../constants.js';
+import { installTemplates } from '../templates.js';
+import { installSkills } from '../skills.js';
+import { detectTools } from '../adapters/detect.js';
+import { getToolById } from '../adapters/registry.js';
+import { injectHandshake } from '../adapters/handshake.js';
+import { confirm } from '../ui.js';
+import { resolveLanguage, t } from '../i18n.js';
+
+async function exists(p) {
+  try { await access(p); return true; } catch { return false; }
+}
+
+export async function update(projectRoot) {
+  const lang = await resolveLanguage(projectRoot);
+
+  console.log(`\n🧠 knowy v${VERSION} — ${t(lang, 'cli.update.title')}\n`);
+
+  // 1. Check .knowy.json exists
+  const configPath = join(projectRoot, KNOWY_CONFIG);
+  if (!await exists(configPath)) {
+    console.log(t(lang, 'cli.update.noConfig'));
+    return;
+  }
+
+  let config;
+  try {
+    config = JSON.parse(await readFile(configPath, 'utf-8'));
+  } catch {
+    console.log(t(lang, 'cli.update.badConfig'));
+    return;
+  }
+
+  const configLang = config.language || lang;
+
+  // 2. Update templates
+  const templates = await installTemplates(projectRoot, configLang);
+  console.log(t(lang, 'cli.update.templates')(templates.length));
+
+  // 3. Update skills
+  const skills = await installSkills(projectRoot);
+  console.log(t(lang, 'cli.update.skills')(skills.length));
+
+  // 4. Re-detect tools
+  const { detected } = await detectTools(projectRoot);
+  const existingTools = new Set(config.tools || []);
+  const newTools = detected.filter(id => !existingTools.has(id));
+
+  // 5. Handshake new tools
+  if (newTools.length > 0) {
+    const names = newTools.map(id => getToolById(id)?.name).filter(Boolean);
+    console.log(`\n${t(lang, 'cli.update.newTools')(names.join(', '))}`);
+    const add = await confirm(t(lang, 'cli.update.addTools'));
+    if (add) {
+      for (const id of newTools) {
+        const tool = getToolById(id);
+        if (!tool) continue;
+        for (const target of tool.targets) {
+          const result = await injectHandshake(projectRoot, target);
+          const verb = result.action === 'created' ? 'Created' : 'Updated';
+          console.log(`  ✓ ${verb} ${result.file}`);
+        }
+        existingTools.add(id);
+      }
+    }
+  }
+
+  // 6. Refresh existing handshakes
+  const writtenFiles = new Set();
+  for (const id of existingTools) {
+    const tool = getToolById(id);
+    if (!tool) continue;
+    for (const target of tool.targets) {
+      if (writtenFiles.has(target.file)) continue;
+      await injectHandshake(projectRoot, target);
+      writtenFiles.add(target.file);
+    }
+  }
+  console.log(t(lang, 'cli.update.refreshed')(writtenFiles.size));
+
+  // 7. Update .knowy.json
+  config.version = VERSION;
+  config.tools = [...existingTools];
+  config.updatedAt = new Date().toISOString();
+  await writeFile(configPath, JSON.stringify(config, null, 2) + '\n');
+
+  console.log(`\n${t(lang, 'cli.update.done')}\n`);
+}

package/src/constants.js

@@ -0,0 +1,23 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+
+export const VERSION = pkg.version;
+export const PACKAGE_ROOT = join(__dirname, '..');
+
+export const KNOWLEDGE_DIR = '.knowledge';
+export const KNOWY_CONFIG = '.knowy.json';
+export const TEMPLATES_DIR = '.templates';
+
+export const CORE_FILES = ['principles.md', 'vision.md', 'experience.md'];
+export const SUBDIRS = ['research', 'design', 'history', TEMPLATES_DIR];
+
+export const SKILLS_SOURCE = join(PACKAGE_ROOT, 'skills');
+export const SKILLS_TARGET = '.claude/skills/knowy';
+export const SKILL_NAMES = ['knowy-init', 'knowy-update', 'knowy-judge', 'knowy-next'];
+
+export const MARKER_START = '<!-- Knowy: Project Knowledge -->';
+export const MARKER_END = '<!-- /Knowy -->';