archgraph 0.1.0

package/packages/cli/src/index.js

@@ -0,0 +1,415 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { gzipSync } from 'node:zlib';
+import { access, cp, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+
+async function loadWorkspaceModule(name, fallbackPath) {
+  try {
+    return await import(name);
+  } catch {
+    return import(fallbackPath);
+  }
+}
+
+const coreModule = await loadWorkspaceModule('@backend-graphing/core', '../../core/src/index.js');
+const viewerModule = await loadWorkspaceModule('@backend-graphing/viewer', '../../viewer/src/index.js');
+
+const { analyzeProject, buildView, exportGraph } = coreModule;
+const { startViewerServer } = viewerModule;
+const CLI_FILE = fileURLToPath(import.meta.url);
+const PROJECT_ROOT = resolve(dirname(CLI_FILE), '../../../');
+
+function usage() {
+  return [
+    'Usage:',
+    '  bgx analyze --project <path> --out <file> [--format graph-json] [--compress gzip]',
+    '  bgx export --graph <file> --format cypher|mermaid --out <file>',
+    '  bgx view --graph <file> [--spec <view.yaml|json>] [--serve] [--port 4310]',
+    '  bgx describe --graph <file> --out <file> --executor codex|claude [--executor-config <path>] [--language bilingual] [--detail structured]',
+    '  bgx install [--target codex|claude|all] [--codex-home <dir>] [--claude-home <dir>] [--dry-run]',
+  ].join('\n');
+}
+
+function parseYamlValue(raw) {
+  const value = raw.trim();
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  if (/^-?\d+$/.test(value)) return Number(value);
+  if (value.startsWith('[') && value.endsWith(']')) {
+    return value
+      .slice(1, -1)
+      .split(',')
+      .map((item) => item.trim())
+      .filter(Boolean)
+      .map((item) => item.replace(/^['"]|['"]$/g, ''));
+  }
+  return value.replace(/^['"]|['"]$/g, '');
+}
+
+function parseSpecText(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    const out = {};
+    for (const line of text.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) continue;
+      const idx = trimmed.indexOf(':');
+      if (idx <= 0) continue;
+      const key = trimmed.slice(0, idx).trim();
+      const value = trimmed.slice(idx + 1).trim();
+      out[key] = parseYamlValue(value);
+    }
+    return out;
+  }
+}
+
+async function pathExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function edgeKindsFrom(nodeId, edges) {
+  return edges.filter((edge) => edge.from === nodeId);
+}
+
+function edgeKindsTo(nodeId, edges) {
+  return edges.filter((edge) => edge.to === nodeId);
+}
+
+function buildEntrySections(label, kind, dependencies, conditions) {
+  const depText = dependencies.length ? dependencies.join(', ') : 'None';
+  const condText = conditions.length ? conditions.join(', ') : 'No explicit branch conditions detected';
+
+  return {
+    ko: {
+      purpose: `${label} (${kind})의 핵심 목적을 설명하고, 아키텍처 흐름에서의 역할을 요약합니다.`,
+      inputs_outputs: `입력은 호출 컨텍스트/요청 데이터이며 출력은 하위 처리(${depText})로 전달되는 결과입니다.`,
+      main_flow: `선택된 노드에서 1-hop 의존 경로를 따라 주요 실행 흐름을 구성합니다: ${depText}.`,
+      conditions: `정적 분석 기반 분기 조건: ${condText}.`,
+      dependencies: `직접 의존 관계: ${depText}.`,
+      risks_notes: '런타임 동적 분기/리플렉션은 정적 그래프에 완전히 반영되지 않을 수 있습니다.',
+    },
+    en: {
+      purpose: `Summarizes the role of ${label} (${kind}) in the endpoint-first architecture flow.`,
+      inputs_outputs: `Inputs come from caller/request context and outputs are delegated through direct dependencies (${depText}).`,
+      main_flow: `Primary execution path is represented by 1-hop graph dependencies: ${depText}.`,
+      conditions: `Static branch conditions detected: ${condText}.`,
+      dependencies: `Direct dependency set: ${depText}.`,
+      risks_notes: 'Dynamic runtime dispatch and reflection may not be fully captured by static analysis.',
+    },
+  };
+}
+
+function buildDescriptionBundle(graph, { executor, language = 'bilingual', detail = 'structured' }) {
+  const nodeById = new Map(graph.nodes.map((node) => [node.id, node]));
+  const entries = [];
+
+  for (const node of graph.nodes) {
+    if (!['endpoint', 'function', 'route_handler', 'agent', 'condition'].includes(node.kind)) continue;
+
+    const outgoing = edgeKindsFrom(node.id, graph.edges)
+      .map((edge) => nodeById.get(edge.to)?.label)
+      .filter(Boolean)
+      .slice(0, 12);
+
+    const conditionEdges = edgeKindsFrom(node.id, graph.edges)
+      .filter((edge) => edge.kind === 'condition_true' || edge.kind === 'condition_false' || edge.kind === 'condition_case')
+      .map((edge) => `${edge.kind}:${edge.label ?? nodeById.get(edge.to)?.label ?? edge.to}`)
+      .slice(0, 12);
+
+    const inbound = edgeKindsTo(node.id, graph.edges)
+      .map((edge) => edge.kind)
+      .slice(0, 8);
+
+    const sections = buildEntrySections(node.label, node.kind, [...new Set([...outgoing, ...inbound])], conditionEdges);
+
+    entries.push({
+      id: node.id,
+      kind: node.kind,
+      label: node.label,
+      language,
+      detail,
+      sections,
+    });
+  }
+
+  for (const group of graph.groups ?? []) {
+    if (!['endpoint', 'purpose', 'agent'].includes(group.kind)) continue;
+    const memberLabels = group.memberNodeIds
+      .map((id) => nodeById.get(id)?.label)
+      .filter(Boolean)
+      .slice(0, 18);
+
+    entries.push({
+      id: `group:${group.id}`,
+      kind: `group:${group.kind}`,
+      label: group.name,
+      language,
+      detail,
+      sections: buildEntrySections(group.name, `group:${group.kind}`, memberLabels, []),
+    });
+  }
+
+  return {
+    version: '1',
+    generatedAt: new Date().toISOString(),
+    sourceGraph: {
+      schemaVersion: graph.schemaVersion,
+      project: graph.project,
+      nodes: graph.nodes.length,
+      edges: graph.edges.length,
+    },
+    generator: {
+      executor,
+      language,
+      detail,
+    },
+    entries,
+  };
+}
+
+async function installCodexSkill({ codexHome, dryRun }) {
+  const skillNames = ['backend-graphing', 'backend-graphing-describe'];
+  const installs = [];
+
+  for (const name of skillNames) {
+    const source = join(PROJECT_ROOT, 'integrations', 'codex', 'skills', name);
+    const destination = join(codexHome, 'skills', name);
+
+    if (!(await pathExists(source))) {
+      throw new Error(`Codex skill source not found: ${source}`);
+    }
+
+    installs.push({ source, destination });
+  }
+
+  if (!dryRun) {
+    await mkdir(join(codexHome, 'skills'), { recursive: true });
+    for (const item of installs) {
+      await cp(item.source, item.destination, { recursive: true, force: true });
+    }
+  }
+
+  return installs;
+}
+
+async function installClaudePlugin({ claudeHome, dryRun }) {
+  const pluginSource = join(PROJECT_ROOT, 'integrations', 'claude');
+  const pluginDestination = join(claudeHome, 'plugins', 'marketplaces', 'backend-graphing');
+  const skillNames = ['backend-graphing', 'backend-graphing-describe'];
+
+  if (!(await pathExists(pluginSource))) {
+    throw new Error(`Claude plugin source not found: ${pluginSource}`);
+  }
+
+  const skillCopies = skillNames.map((name) => ({
+    skillSource: join(pluginSource, '.claude', 'skills', name),
+    skillDestination: join(claudeHome, 'skills', name),
+  }));
+
+  if (!dryRun) {
+    await mkdir(join(claudeHome, 'plugins', 'marketplaces'), { recursive: true });
+    await cp(pluginSource, pluginDestination, { recursive: true, force: true });
+
+    await mkdir(join(claudeHome, 'skills'), { recursive: true });
+    for (const copySpec of skillCopies) {
+      if (await pathExists(copySpec.skillSource)) {
+        await cp(copySpec.skillSource, copySpec.skillDestination, { recursive: true, force: true });
+      }
+    }
+  }
+
+  return {
+    pluginSource,
+    pluginDestination,
+    skillCopies,
+  };
+}
+
+async function run() {
+  const [command, ...rest] = process.argv.slice(2);
+
+  if (command === '--help' || command === '-h' || command === 'help') {
+    console.log(usage());
+    return;
+  }
+
+  if (command === '--version' || command === '-v') {
+    console.log('0.1.0');
+    return;
+  }
+
+  if (!command) {
+    console.log(usage());
+    return;
+  }
+
+  const parsed = parseArgs({
+    args: rest,
+    allowPositionals: true,
+    strict: false,
+    options: {
+      project: { type: 'string' },
+      out: { type: 'string' },
+      format: { type: 'string' },
+      graph: { type: 'string' },
+      spec: { type: 'string' },
+      serve: { type: 'boolean' },
+      port: { type: 'string' },
+      compress: { type: 'string' },
+      frontend: { type: 'string' },
+      executor: { type: 'string' },
+      'executor-config': { type: 'string' },
+      language: { type: 'string' },
+      detail: { type: 'string' },
+      descriptions: { type: 'string' },
+      target: { type: 'string' },
+      'codex-home': { type: 'string' },
+      'claude-home': { type: 'string' },
+      'dry-run': { type: 'boolean' },
+    },
+  });
+
+  if (command === 'analyze') {
+    if (!parsed.values.project || !parsed.values.out) {
+      throw new Error('analyze requires --project and --out');
+    }
+
+    const graph = await analyzeProject({
+      projectPath: parsed.values.project,
+      includeFrontend: Boolean(parsed.values.frontend),
+      frontendPath: parsed.values.frontend,
+    });
+
+    const format = parsed.values.format ?? 'graph-json';
+    if (format !== 'graph-json') {
+      await exportGraph(graph, format, parsed.values.out);
+      console.log(`Wrote ${parsed.values.out}`);
+      return;
+    }
+
+    const json = `${JSON.stringify(graph, null, 2)}\n`;
+    if (parsed.values.compress === 'gzip') {
+      const compressed = gzipSync(Buffer.from(json, 'utf8'));
+      await writeFile(parsed.values.out, compressed);
+    } else {
+      await writeFile(parsed.values.out, json, 'utf8');
+    }
+    console.log(`Wrote ${parsed.values.out}`);
+    return;
+  }
+
+  if (command === 'export') {
+    if (!parsed.values.graph || !parsed.values.format || !parsed.values.out) {
+      throw new Error('export requires --graph --format --out');
+    }
+    const graphText = await readFile(parsed.values.graph, 'utf8');
+    const graph = JSON.parse(graphText);
+    await exportGraph(graph, parsed.values.format, parsed.values.out);
+    console.log(`Wrote ${parsed.values.out}`);
+    return;
+  }
+
+  if (command === 'view') {
+    if (!parsed.values.graph) {
+      throw new Error('view requires --graph');
+    }
+
+    const graph = JSON.parse(await readFile(parsed.values.graph, 'utf8'));
+    const spec = parsed.values.spec
+      ? parseSpecText(await readFile(parsed.values.spec, 'utf8'))
+      : { version: '1', depth: 2, groupBy: 'endpoint' };
+
+    const view = buildView(graph, spec);
+
+    if (parsed.values.serve) {
+      const port = parsed.values.port ? Number(parsed.values.port) : 4310;
+      await startViewerServer({
+        graph,
+        view,
+        port,
+        descriptionsPath: parsed.values.descriptions,
+      });
+      return;
+    }
+
+    const out = parsed.values.out ?? 'view.json';
+    await writeFile(out, `${JSON.stringify(view, null, 2)}\n`, 'utf8');
+    console.log(`Wrote ${out}`);
+    return;
+  }
+
+  if (command === 'describe') {
+    if (!parsed.values.graph || !parsed.values.out || !parsed.values.executor) {
+      throw new Error('describe requires --graph --out --executor');
+    }
+
+    if (!['codex', 'claude'].includes(parsed.values.executor)) {
+      throw new Error('describe --executor must be codex or claude');
+    }
+
+    if (parsed.values['executor-config']) {
+      const configText = await readFile(parsed.values['executor-config'], 'utf8');
+      const config = JSON.parse(configText);
+      if (!config?.[parsed.values.executor]) {
+        throw new Error(`Executor not found in config: ${parsed.values.executor}`);
+      }
+    }
+
+    const graph = JSON.parse(await readFile(parsed.values.graph, 'utf8'));
+    const bundle = buildDescriptionBundle(graph, {
+      executor: parsed.values.executor,
+      language: parsed.values.language ?? 'bilingual',
+      detail: parsed.values.detail ?? 'structured',
+    });
+
+    await writeFile(parsed.values.out, `${JSON.stringify(bundle, null, 2)}\n`, 'utf8');
+    console.log(`Wrote ${parsed.values.out}`);
+    return;
+  }
+
+  if (command === 'install') {
+    const target = parsed.values.target ?? 'all';
+    if (!['codex', 'claude', 'all'].includes(target)) {
+      throw new Error(`Invalid --target value: ${target}`);
+    }
+
+    const codexHome = parsed.values['codex-home'] ?? process.env.CODEX_HOME ?? join(homedir(), '.codex');
+    const claudeHome = parsed.values['claude-home'] ?? join(homedir(), '.claude');
+    const dryRun = Boolean(parsed.values['dry-run']);
+
+    if (target === 'codex' || target === 'all') {
+      const installed = await installCodexSkill({ codexHome, dryRun });
+      for (const item of installed) {
+        console.log(`${dryRun ? '[dry-run] ' : ''}Codex skill: ${item.source} -> ${item.destination}`);
+      }
+    }
+
+    if (target === 'claude' || target === 'all') {
+      const installed = await installClaudePlugin({ claudeHome, dryRun });
+      console.log(
+        `${dryRun ? '[dry-run] ' : ''}Claude plugin: ${installed.pluginSource} -> ${installed.pluginDestination}`,
+      );
+      for (const item of installed.skillCopies) {
+        console.log(`${dryRun ? '[dry-run] ' : ''}Claude skill: ${item.skillSource} -> ${item.skillDestination}`);
+      }
+    }
+
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+run().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});