arceus-s 1.6.4

package/dist/cli/ai-context.js

@@ -0,0 +1,289 @@
+/**
+ * AI Context Generator
+ *
+ * Creates AGENTS.md and CLAUDE.md with full inline Arceus context.
+ * AGENTS.md is the standard read by Cursor, Windsurf, OpenCode, Codex, Cline, etc.
+ * CLAUDE.md is for Claude Code which only reads that file.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { logger } from '../core/logger.js';
+// ESM equivalent of __dirname
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const ARC_START_MARKER = '<!-- arc:start -->';
+const ARC_END_MARKER = '<!-- arc:end -->';
+/**
+ * Find the index of a section marker that occupies its own line.
+ * Unlike `indexOf`, this rejects inline prose references like
+ * `` See the `<!-- arc:start -->` block `` that appear
+ * mid-sentence (#1041). A marker counts as section-position only when:
+ *   - preceded by newline or start-of-file, AND
+ *   - followed by newline, `\r` (CRLF files), or end-of-file.
+ * The generator always emits each marker alone on its line, so this
+ * matches every legitimate section and none of the inline mentions.
+ *
+ * `startFrom` lets the end-marker lookup start after the already-found
+ * start marker, avoiding a scan from 0 and guaranteeing we never pick
+ * up an end marker that appears earlier in the file than the start.
+ */
+function findSectionMarkerIndex(content, marker, startFrom = 0) {
+    let idx = content.indexOf(marker, startFrom);
+    while (idx !== -1) {
+        const atLineStart = idx === 0 || content[idx - 1] === '\n';
+        const endPos = idx + marker.length;
+        const atLineEnd = endPos === content.length || content[endPos] === '\n' || content[endPos] === '\r';
+        if (atLineStart && atLineEnd)
+            return idx;
+        idx = content.indexOf(marker, idx + 1);
+    }
+    return -1;
+}
+/**
+ * Generate the full Arceus context content.
+ *
+ * Design principles (learned from real agent behavior and industry research):
+ * - Inline critical workflows — skills are skipped 56% of the time (Vercel eval data)
+ * - Use RFC 2119 language (MUST, NEVER, ALWAYS) — models follow imperative rules
+ * - Three-tier boundaries (Always/When/Never) — proven to change model behavior
+ * - Keep under 120 lines — adherence degrades past 150 lines
+ * - Exact tool commands with parameters — vague directives get ignored
+ * - Self-review checklist — forces model to verify its own work
+ */
+async function findGroupsContainingRegistryName(registryName) {
+    const { listGroups, getDefaultArceusDir, getGroupDir } = await import('../core/group/storage.js');
+    const { loadGroupConfig } = await import('../core/group/config-parser.js');
+    const names = await listGroups();
+    const hits = [];
+    for (const g of names) {
+        try {
+            const config = await loadGroupConfig(getGroupDir(getDefaultArceusDir(), g));
+            if (Object.values(config.repos).some((r) => r === registryName))
+                hits.push(config.name);
+        }
+        catch {
+            // skip invalid or unreadable groups
+        }
+    }
+    return hits;
+}
+function generateArceusContent(projectName, stats, generatedSkills, groupNames, noStats, skipSkills) {
+    const generatedRows = generatedSkills && generatedSkills.length > 0
+        ? generatedSkills
+            .map((s) => `| Work in the ${s.label} area (${s.symbolCount} symbols) | \`.claude/skills/generated/${s.name}/SKILL.md\` |`)
+            .join('\n')
+        : '';
+    // Standard skill rows reference files installed by installSkills(). When
+    // --skip-skills suppresses that install, these rows must be omitted — else
+    // AGENTS.md/CLAUDE.md would direct agents to read files that don't exist.
+    // Community skills (generatedRows) live in .claude/skills/generated/ and
+    // are independent of --skip-skills, so they remain when present.
+    const standardSkillsRows = skipSkills
+        ? ''
+        : `| Understand architecture / "How does X work?" | \`.claude/skills/arc/arc-exploring/SKILL.md\` |
+| Blast radius / "What breaks if I change X?" | \`.claude/skills/arc/arc-impact-analysis/SKILL.md\` |
+| Trace bugs / "Why is X failing?" | \`.claude/skills/arc/arc-debugging/SKILL.md\` |
+| Rename / extract / split / refactor | \`.claude/skills/arc/arc-refactoring/SKILL.md\` |
+| Tools, resources, schema reference | \`.claude/skills/arc/arc-guide/SKILL.md\` |
+| Index, status, clean, wiki CLI commands | \`.claude/skills/arc/arc-cli/SKILL.md\` |`;
+    const tableBody = [standardSkillsRows, generatedRows].filter(Boolean).join('\n');
+    const skillsTable = tableBody
+        ? `| Task | Read this skill file |
+|------|---------------------|
+${tableBody}`
+        : '';
+    return `${ARC_START_MARKER}
+# Arceus — Code Intelligence
+
+This project is indexed by Arceus as **${projectName}**${noStats ? '' : ` (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows)`}. Use the Arceus MCP tools to understand code, assess impact, and navigate safely.
+
+> If any Arceus tool warns the index is stale, run \`npx arc analyze\` in terminal first.
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run \`arc_impact({target: "symbolName", direction: "upstream"})\` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run \`arc_detect_changes()\` before committing** to verify your changes only affect expected symbols and execution flows.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use \`arc_query({query: "concept"})\` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use \`arc_context({name: "symbolName"})\`.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running \`arc_impact\` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use \`arc_rename\` which understands the call graph.
+- NEVER commit changes without running \`arc_detect_changes()\` to check affected scope.
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| \`arc://repo/${projectName}/context\` | Codebase overview, check index freshness |
+| \`arc://repo/${projectName}/clusters\` | All functional areas |
+| \`arc://repo/${projectName}/processes\` | All execution flows |
+| \`arc://repo/${projectName}/process/{name}\` | Step-by-step execution trace |
+
+${groupNames && groupNames.length > 0
+        ? `## Cross-Repo Groups
+
+This repository is listed under Arceus **group(s): ${groupNames.join(', ')}** (see \`~/.arc/groups/\`). For cross-repo analysis, use MCP tools \`impact\`, \`query\`, and \`context\` with \`repo\` set to \`@<groupName>\` or \`@<groupName>/<memberPath>\` (paths match keys in that group’s \`group.yaml\`). Use \`group_list\` / \`group_sync\` for membership and sync. From the terminal: \`npx arc group list\`, \`npx arc group sync <name>\`, \`npx arc group impact <name> --target <symbol> --repo <group-path>\`.
+
+`
+        : ''}${skillsTable
+        ? `## CLI
+
+${skillsTable}
+
+`
+        : ''}${ARC_END_MARKER}`;
+}
+/**
+ * Check if a file exists
+ */
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Create or update Arceus section in a file
+ * - If file doesn't exist: create with Arceus content
+ * - If file exists without Arceus section: append
+ * - If file exists with Arceus section: replace that section
+ */
+async function upsertArceusSection(filePath, content) {
+    const exists = await fileExists(filePath);
+    if (!exists) {
+        await fs.writeFile(filePath, content, 'utf-8');
+        return 'created';
+    }
+    const existingContent = await fs.readFile(filePath, 'utf-8');
+    // Check if Arceus section already exists. Matching is restricted
+    // to markers that occupy their own line so that inline prose
+    // references (e.g. `` See the `<!-- arc:start -->` block `` in
+    // the shipped CLAUDE.md) are NOT treated as section delimiters
+    // (#1041). The end-marker scan starts after the start-marker so it
+    // can never pick up an earlier end in the file.
+    const startIdx = findSectionMarkerIndex(existingContent, ARC_START_MARKER);
+    const endIdx = findSectionMarkerIndex(existingContent, ARC_END_MARKER, startIdx === -1 ? 0 : startIdx);
+    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+        // Replace existing section
+        const before = existingContent.substring(0, startIdx);
+        const after = existingContent.substring(endIdx + ARC_END_MARKER.length);
+        const newContent = before + content + after;
+        await fs.writeFile(filePath, newContent.trim() + '\n', 'utf-8');
+        return 'updated';
+    }
+    // Append new section
+    const newContent = existingContent.trim() + '\n\n' + content + '\n';
+    await fs.writeFile(filePath, newContent, 'utf-8');
+    return 'appended';
+}
+/**
+ * Install Arceus skills to .claude/skills/arc/
+ * Works natively with Claude Code, Cursor, and GitHub Copilot
+ */
+async function installSkills(repoPath) {
+    const skillsDir = path.join(repoPath, '.claude', 'skills', 'arc');
+    const installedSkills = [];
+    // Skill definitions bundled with the package
+    const skills = [
+        {
+            name: 'arc-exploring',
+            description: 'Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: "How does X work?", "What calls this function?", "Show me the auth flow"',
+        },
+        {
+            name: 'arc-debugging',
+            description: 'Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: "Why is X failing?", "Where does this error come from?", "Trace this bug"',
+        },
+        {
+            name: 'arc-impact-analysis',
+            description: 'Use when the user wants to know what will break if they change something, or needs safety analysis before editing code. Examples: "Is it safe to change X?", "What depends on this?", "What will break?"',
+        },
+        {
+            name: 'arc-refactoring',
+            description: 'Use when the user wants to rename, extract, split, move, or restructure code safely. Examples: "Rename this function", "Extract this into a module", "Refactor this class", "Move this to a separate file"',
+        },
+        {
+            name: 'arc-guide',
+            description: 'Use when the user asks about Arceus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: "What Arceus tools are available?", "How do I use Arceus?"',
+        },
+        {
+            name: 'arc-cli',
+            description: 'Use when the user needs to run Arceus CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: "Index this repo", "Reanalyze the codebase", "Generate a wiki"',
+        },
+    ];
+    for (const skill of skills) {
+        const skillDir = path.join(skillsDir, skill.name);
+        const skillPath = path.join(skillDir, 'SKILL.md');
+        try {
+            // Create skill directory
+            await fs.mkdir(skillDir, { recursive: true });
+            // Try to read from package skills directory
+            const packageSkillPath = path.join(__dirname, '..', '..', 'skills', `${skill.name}.md`);
+            let skillContent;
+            try {
+                skillContent = await fs.readFile(packageSkillPath, 'utf-8');
+            }
+            catch {
+                // Fallback: generate minimal skill content
+                skillContent = `---
+name: ${skill.name}
+description: ${skill.description}
+---
+
+# ${skill.name.charAt(0).toUpperCase() + skill.name.slice(1)}
+
+${skill.description}
+
+Use Arceus tools to accomplish this task.
+`;
+            }
+            await fs.writeFile(skillPath, skillContent, 'utf-8');
+            installedSkills.push(skill.name);
+        }
+        catch (err) {
+            // Skip on error, don't fail the whole process
+            logger.warn({ err }, `Warning: Could not install skill ${skill.name}:`);
+        }
+    }
+    return installedSkills;
+}
+/**
+ * Generate AI context files after indexing
+ */
+export async function generateAIContextFiles(repoPath, _storagePath, projectName, stats, generatedSkills, options) {
+    const groupNames = await findGroupsContainingRegistryName(projectName);
+    const content = generateArceusContent(projectName, stats, generatedSkills, groupNames, options?.noStats, options?.skipSkills);
+    const createdFiles = [];
+    if (!options?.skipAgentsMd) {
+        // Create AGENTS.md (standard for Cursor, Windsurf, OpenCode, Cline, etc.)
+        const agentsPath = path.join(repoPath, 'AGENTS.md');
+        const agentsResult = await upsertArceusSection(agentsPath, content);
+        createdFiles.push(`AGENTS.md (${agentsResult})`);
+        // Create CLAUDE.md (for Claude Code)
+        const claudePath = path.join(repoPath, 'CLAUDE.md');
+        const claudeResult = await upsertArceusSection(claudePath, content);
+        createdFiles.push(`CLAUDE.md (${claudeResult})`);
+    }
+    else {
+        createdFiles.push('AGENTS.md (skipped via --skip-agents-md)');
+        createdFiles.push('CLAUDE.md (skipped via --skip-agents-md)');
+    }
+    // Install skills to .claude/skills/arc/ (unless --skip-skills)
+    if (!options?.skipSkills) {
+        const installedSkills = await installSkills(repoPath);
+        if (installedSkills.length > 0) {
+            createdFiles.push(`.claude/skills/arc/ (${installedSkills.length} skills)`);
+        }
+    }
+    else {
+        createdFiles.push('.claude/skills/arc/ (skipped via --skip-skills)');
+    }
+    return { files: createdFiles };
+}

package/dist/cli/analyze.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Analyze Command
+ *
+ * Indexes a repository and stores the knowledge graph in .arc/
+ *
+ * Delegates core analysis to the shared runFullAnalysis orchestrator.
+ * This CLI wrapper handles: heap management, progress bar, SIGINT,
+ * skill generation (--skills), summary output, and process.exit().
+ */
+export interface AnalyzeOptions {
+    force?: boolean;
+    /**
+     * Embedding generation toggle. Commander parses `--embeddings [limit]` as:
+     *   - `undefined` when the flag is omitted
+     *   - `true` when passed without an argument (use default 50K node cap)
+     *   - a string when passed with an argument (`--embeddings 0` disables the
+     *     cap, `--embeddings <n>` uses `<n>` as the cap)
+     */
+    embeddings?: boolean | string;
+    /**
+     * Explicitly drop existing embeddings on rebuild instead of preserving
+     * them. Without this flag, a routine `analyze` keeps any embeddings
+     * already present in the index even when `--embeddings` is omitted.
+     */
+    dropEmbeddings?: boolean;
+    skills?: boolean;
+    verbose?: boolean;
+    /** Skip AGENTS.md and CLAUDE.md arc block updates. */
+    skipAgentsMd?: boolean;
+    /** Omit volatile symbol/relationship counts from AGENTS.md and CLAUDE.md. */
+    noStats?: boolean;
+    /** Skip installing standard Arceus skill files to .claude/skills/arc/. */
+    skipSkills?: boolean;
+    /** Pure index mode: skip all file injection (AGENTS.md, CLAUDE.md, skills). */
+    indexOnly?: boolean;
+    /** Index the folder even when no .git directory is present. */
+    skipGit?: boolean;
+    /**
+     * Override the default basename-derived registry `name` with a
+     * user-supplied alias (#829). Disambiguates repos whose paths share a
+     * basename. Persisted — subsequent re-analyses of the same path without
+     * `--name` preserve the alias.
+     */
+    name?: string;
+    /**
+     * Allow registration even when another path already uses the same
+     * `--name` alias (#829). Intentionally a distinct flag from `--force`
+     * because the user may want to coexist under the same name WITHOUT
+     * paying the cost of a pipeline re-index. Maps to registerRepo's
+     * `allowDuplicateName` option end-to-end.
+     */
+    allowDuplicateName?: boolean;
+    /**
+     * Override the walker's large-file skip threshold (#991). Value in KB;
+     * clamped downstream to the tree-sitter 32 MB ceiling. Sets
+     * `ARC_MAX_FILE_SIZE` for the rest of the pipeline.
+     */
+    maxFileSize?: string;
+    /** Override worker sub-batch idle timeout in seconds. */
+    workerTimeout?: string;
+    embeddingThreads?: string;
+    embeddingBatchSize?: string;
+    embeddingSubBatchSize?: string;
+    embeddingDevice?: string;
+}
+/**
+ * Whether the post-index skill step should run.
+ *
+ * The gated block does two things in sequence: (1) generates the community
+ * skill files from `--skills`, and (2) re-runs `generateAIContextFiles` so
+ * AGENTS.md/CLAUDE.md can reference the freshly written skills. Both are
+ * suppressed together — `--index-only` drops the entire step, not just the
+ * community-skill write. Name retained for the test contract; see call site
+ * in `analyzeCommand` for the AGENTS.md/CLAUDE.md re-generation it also gates.
+ *
+ * Kept as a pure helper so the `--index-only --skills` contract is unit-tested
+ * without booting the full analyze pipeline (#742 review).
+ */
+export declare const shouldGenerateCommunitySkillFiles: (options: Pick<AnalyzeOptions, "skills" | "indexOnly"> | undefined, pipelineResult: unknown) => boolean;
+export declare const analyzeCommand: (inputPath?: string, options?: AnalyzeOptions) => Promise<void>;