agents-reverse-engineer 0.3.2 → 0.3.4

package/dist/integration/templates.js

@@ -101,8 +101,17 @@ For each directory (in post-order):
 Generate root documents:
 
 1. **CLAUDE.md** - Synthesize all AGENTS.md into project overview
-2. **ARCHITECTURE.md** - Document system architecture
-3. **STACK.md** - Document technology stack from package.json
+2. **ARCHITECTURE.md** - Document system architecture (if 20+ source files)
+
+Generate per-package documents (at each directory containing package.json, requirements.txt, Cargo.toml, etc.):
+
+1. **STACK.md** - Technology stack from manifest file
+2. **STRUCTURE.md** - Codebase structure and organization
+3. **CONVENTIONS.md** - Coding conventions and patterns
+4. **TESTING.md** - Test setup and patterns
+5. **INTEGRATIONS.md** - External services and APIs
+
+In monorepos, these appear in each package directory (e.g., \`packages/api/STACK.md\`).
 
 ## Completion
 
@@ -226,42 +235,289 @@ Suggest running \`/are:discover --plan\` to start fresh.
         description: 'Show available ARE commands and usage guide',
         argumentHint: '',
         // Content uses COMMAND_PREFIX placeholder, replaced per platform
-        content: `Show help for agents-reverse-engineer commands.
+        content: `<objective>
+Display the complete ARE command reference.
 
-<execution>
-Display the following help information:
+Output ONLY the reference content below. Do NOT add:
+- Project-specific analysis
+- Git status or file context
+- Next-step suggestions
+- Any commentary beyond the reference
+</objective>
+
+<reference>
+# agents-reverse-engineer (ARE) Command Reference
+
+**ARE** generates AI-friendly documentation for codebases, creating structured summaries optimized for AI assistants.
+
+## Quick Start
 
-## agents-reverse-engineer (ARE) Commands
+1. \`COMMAND_PREFIXinit\` — Create configuration file
+2. \`COMMAND_PREFIXdiscover --plan\` — Scan codebase, create execution plan
+3. \`COMMAND_PREFIXgenerate\` — Generate documentation from the plan
+4. \`COMMAND_PREFIXupdate\` — Keep docs in sync after code changes
+
+## Commands Reference
+
+### \`COMMAND_PREFIXinit\`
+Initialize configuration in this project.
+
+Creates \`.agents-reverse-engineer/config.yaml\` with customizable settings.
+
+**Usage:** \`COMMAND_PREFIXinit\`
+**CLI:** \`npx are init\`
+
+---
 
-| Command | Description |
-|---------|-------------|
-| \`COMMAND_PREFIXhelp\` | Show this help message |
-| \`COMMAND_PREFIXinit\` | Initialize configuration file |
-| \`COMMAND_PREFIXdiscover\` | Discover files (use --plan for GENERATION-PLAN.md) |
-| \`COMMAND_PREFIXgenerate\` | Generate documentation from the plan |
-| \`COMMAND_PREFIXupdate\` | Update docs for changed files only |
-| \`COMMAND_PREFIXclean\` | Remove all generated documentation |
+### \`COMMAND_PREFIXdiscover\`
+Discover files that would be analyzed for documentation.
 
-## Typical Workflow
+**Options:**
+| Flag | Description |
+|------|-------------|
+| \`[path]\` | Target directory (default: current directory) |
+| \`--plan\` | Generate \`GENERATION-PLAN.md\` execution plan |
+| \`--show-excluded\` | List excluded files with reasons |
+| \`--quiet, -q\` | Suppress output except errors |
+
+**Usage:**
+- \`COMMAND_PREFIXdiscover\` — List discoverable files
+- \`COMMAND_PREFIXdiscover --plan\` — Create execution plan for generate
+- \`COMMAND_PREFIXdiscover --show-excluded\` — Debug exclusion rules
+
+**CLI:**
+\`\`\`bash
+npx are discover
+npx are discover --plan
+npx are discover ./src --show-excluded
+\`\`\`
+
+---
+
+### \`COMMAND_PREFIXgenerate\`
+Generate comprehensive documentation for the codebase.
+
+**Requires:** Run \`COMMAND_PREFIXdiscover --plan\` first to create \`GENERATION-PLAN.md\`.
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| \`--budget N\` | Override token budget (default: from config) |
+| \`--dry-run\` | Show what would be generated without writing |
+| \`--execute\` | Output JSON execution plan for AI agents |
+| \`--stream\` | Output tasks as streaming JSON, one per line |
+| \`--verbose, -v\` | Show detailed task breakdown |
+| \`--quiet, -q\` | Suppress output except errors |
+
+**Usage:**
+- \`COMMAND_PREFIXgenerate\` — Generate docs (resumes from plan)
+- \`COMMAND_PREFIXgenerate --dry-run\` — Preview without writing
+
+**CLI:**
+\`\`\`bash
+npx are generate
+npx are generate --dry-run
+npx are generate --budget 50000
+npx are generate --execute  # For programmatic use
+\`\`\`
+
+**How it works:**
+1. Reads \`GENERATION-PLAN.md\` and finds unchecked tasks
+2. Spawns parallel subagents to analyze each file
+3. Writes \`.sum\` summary files alongside source files
+4. Generates \`AGENTS.md\` for each directory (post-order)
+5. Creates root documents: \`CLAUDE.md\`, \`ARCHITECTURE.md\`
+6. Creates per-package documents at each manifest location: \`STACK.md\`, \`STRUCTURE.md\`, \`CONVENTIONS.md\`, \`TESTING.md\`, \`INTEGRATIONS.md\`
+
+---
+
+### \`COMMAND_PREFIXupdate\`
+Incrementally update documentation for changed files.
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| \`--uncommitted\` | Include staged but uncommitted changes |
+| \`--dry-run\` | Show what would be updated without writing |
+| \`--budget N\` | Override token budget |
+| \`--verbose, -v\` | Show detailed output |
+| \`--quiet, -q\` | Suppress output except errors |
+
+**Usage:**
+- \`COMMAND_PREFIXupdate\` — Update docs for committed changes
+- \`COMMAND_PREFIXupdate --uncommitted\` — Include uncommitted changes
+
+**CLI:**
+\`\`\`bash
+npx are update
+npx are update --uncommitted --verbose
+npx are update --dry-run
+\`\`\`
+
+---
+
+### \`COMMAND_PREFIXclean\`
+Remove all generated documentation artifacts.
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| \`--dry-run\` | Show what would be deleted without deleting |
+
+**What gets deleted:**
+- \`.agents-reverse-engineer/GENERATION-PLAN.md\`
+- All \`*.sum\` files
+- All \`AGENTS.md\` files
+- Root docs: \`CLAUDE.md\`, \`ARCHITECTURE.md\`
+- Per-package docs: \`STACK.md\`, \`STRUCTURE.md\`, \`CONVENTIONS.md\`, \`TESTING.md\`, \`INTEGRATIONS.md\`
+
+**Usage:**
+- \`COMMAND_PREFIXclean --dry-run\` — Preview deletions
+- \`COMMAND_PREFIXclean\` — Delete all artifacts
+
+---
+
+### \`COMMAND_PREFIXhelp\`
+Show this command reference.
+
+## CLI Installation
+
+Install ARE commands to your AI assistant:
+
+\`\`\`bash
+npx agents-reverse-engineer install              # Interactive mode
+npx agents-reverse-engineer install --runtime claude -g  # Global Claude
+npx agents-reverse-engineer install --runtime claude -l  # Local project
+npx agents-reverse-engineer install --runtime all -g     # All runtimes
+\`\`\`
 
-1. **\`COMMAND_PREFIXinit\`** — Create \`.agents-reverse-engineer/config.yaml\`
-2. **\`COMMAND_PREFIXdiscover --plan\`** — Scan codebase, create \`GENERATION-PLAN.md\`
-3. **\`COMMAND_PREFIXgenerate\`** — Execute plan, generate \`.sum\` and \`AGENTS.md\` files
-4. **\`COMMAND_PREFIXupdate\`** — After code changes, update only what changed
+**Install/Uninstall Options:**
+| Flag | Description |
+|------|-------------|
+| \`--runtime <name>\` | Target: \`claude\`, \`opencode\`, \`gemini\`, \`all\` |
+| \`-g, --global\` | Install to global config directory |
+| \`-l, --local\` | Install to current project directory |
+| \`--force\` | Overwrite existing files (install only) |
+
+## Configuration
+
+**File:** \`.agents-reverse-engineer/config.yaml\`
+
+\`\`\`yaml
+# Exclusion patterns
+exclude:
+  patterns:
+    - "**/*.test.ts"
+    - "**/__mocks__/**"
+  vendorDirs:
+    - node_modules
+    - dist
+    - .git
+  binaryExtensions:
+    - .png
+    - .jpg
+    - .pdf
+
+# Options
+options:
+  followSymlinks: false
+  maxFileSize: 100000
+
+# Output settings
+output:
+  verbose: false
+  colors: true
+
+# Generation settings
+generation:
+  tokenBudget: 50000
+\`\`\`
 
 ## Generated Files
 
-- \`*.sum\` — Per-file summaries (purpose, exports, dependencies)
-- \`AGENTS.md\` — Per-directory overviews
-- \`CLAUDE.md\` — Project entry point
-- \`ARCHITECTURE.md\` — System design overview
-- \`STACK.md\` — Technology stack
+### Per Source File
 
-## More Info
+**\`*.sum\`** — File summaries with YAML frontmatter + detailed prose.
 
-- Docs: https://github.com/GeoloeG-IsT/agents-reverse-engineer
-- Update: \`npx agents-reverse-engineer@latest\`
-</execution>`,
+\`\`\`yaml
+---
+file_type: service
+generated_at: 2025-01-15T10:30:00Z
+content_hash: abc123...
+purpose: Handles user authentication and session management
+public_interface: [login(), logout(), refreshToken(), AuthService]
+dependencies: [express, jsonwebtoken, ./user-model]
+patterns: [singleton, factory, observer]
+related_files: [./types.ts, ./middleware.ts]
+---
+
+<300-500 word summary covering implementation, patterns, edge cases>
+\`\`\`
+
+### Per Directory
+
+**\`AGENTS.md\`** — Directory overview synthesized from \`.sum\` files. Groups files by purpose and links to subdirectories.
+
+### Root Documents
+
+| File | Purpose |
+|------|---------|
+| \`CLAUDE.md\` | Project entry point — synthesizes all AGENTS.md |
+| \`ARCHITECTURE.md\` | System design, layers, data flow (if 20+ files) |
+
+### Per-Package Documents (at each manifest file location)
+
+Generated alongside \`package.json\`, \`requirements.txt\`, \`Cargo.toml\`, etc.:
+
+| File | Purpose |
+|------|---------|
+| \`STACK.md\` | Technology stack from manifest |
+| \`STRUCTURE.md\` | Codebase structure and organization |
+| \`CONVENTIONS.md\` | Coding conventions and patterns |
+| \`TESTING.md\` | Test setup and patterns |
+| \`INTEGRATIONS.md\` | External services and APIs |
+
+In monorepos, these appear in each package directory (e.g., \`packages/api/STACK.md\`).
+
+## Common Workflows
+
+**Initial documentation:**
+\`\`\`
+COMMAND_PREFIXinit
+COMMAND_PREFIXdiscover --plan
+COMMAND_PREFIXgenerate
+\`\`\`
+
+**After code changes:**
+\`\`\`
+COMMAND_PREFIXupdate
+\`\`\`
+
+**Full regeneration:**
+\`\`\`
+COMMAND_PREFIXclean
+COMMAND_PREFIXdiscover --plan
+COMMAND_PREFIXgenerate
+\`\`\`
+
+**Preview before generating:**
+\`\`\`
+COMMAND_PREFIXdiscover --show-excluded  # Check exclusions
+COMMAND_PREFIXgenerate --dry-run         # Preview generation
+\`\`\`
+
+## Tips
+
+- **Resume generation**: If interrupted, run \`COMMAND_PREFIXgenerate\` again — it resumes from unchecked tasks in \`GENERATION-PLAN.md\`
+- **Large codebases**: Use \`--budget N\` to limit token usage per run
+- **Custom exclusions**: Edit \`.agents-reverse-engineer/config.yaml\` to skip files
+- **Hook auto-update**: Install creates a session-end hook that auto-runs update
+
+## Resources
+
+- **Repository:** https://github.com/GeoloeG-IsT/agents-reverse-engineer
+- **Update:** \`npx agents-reverse-engineer@latest install --force\`
+</reference>`,
     },
 };
 const PLATFORM_CONFIGS = {
@@ -342,49 +598,4 @@ export function getOpenCodeTemplates() {
 export function getGeminiTemplates() {
     return getTemplatesForPlatform('gemini');
 }
-/**
- * Get session-end hook template for automatic documentation updates
- */
-export function getHookTemplate() {
-    return `#!/usr/bin/env node
-// .claude/hooks/are-session-end.js
-// Triggers are update when session ends (if there are uncommitted changes)
-
-const { execSync, spawn } = require('child_process');
-const fs = require('fs');
-
-// Check for disable flag
-if (process.env.ARE_DISABLE_HOOK === '1') {
-  process.exit(0);
-}
-
-// Check config file for permanent disable
-const configPath = '.agents-reverse-engineer.yaml';
-if (fs.existsSync(configPath)) {
-  const config = fs.readFileSync(configPath, 'utf-8');
-  if (config.includes('hook_enabled: false')) {
-    process.exit(0);
-  }
-}
-
-// Check git status - skip if no changes
-try {
-  const status = execSync('git status --porcelain', { encoding: 'utf-8' });
-  if (!status.trim()) {
-    // No changes since last run - exit silently
-    process.exit(0);
-  }
-} catch {
-  // Not a git repo or git not available - exit silently
-  process.exit(0);
-}
-
-// Run update in background (don't block session close)
-const child = spawn('npx', ['agents-reverse-engineer@latest', 'update', '--quiet'], {
-  stdio: 'ignore',
-  detached: true,
-});
-child.unref();
-`;
-}
 //# sourceMappingURL=templates.js.map

package/dist/integration/templates.js.map

@@ -1 +1 @@
-{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../src/integration/templates.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../src/integration/templates.ts"],"names":[],"mappings":"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"}

package/hooks/dist/are-check-update.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+/**
+ * ARE Update Check Hook
+ *
+ * Checks for ARE updates in background, writes result to cache.
+ * Called by SessionStart hook - runs once per session.
+ *
+ * Cache file: ~/.claude/cache/are-update-check.json
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { spawn, execSync } from 'child_process';
+
+const homeDir = homedir();
+const cwd = process.cwd();
+const cacheDir = join(homeDir, '.claude', 'cache');
+const cacheFile = join(cacheDir, 'are-update-check.json');
+
+// VERSION file locations (check project first, then global)
+const projectVersionFile = join(cwd, '.claude', 'VERSION');
+const globalVersionFile = join(homeDir, '.claude', 'VERSION');
+
+// Ensure cache directory exists
+if (!existsSync(cacheDir)) {
+  mkdirSync(cacheDir, { recursive: true });
+}
+
+// Run check in background (spawn background process)
+const child = spawn(process.execPath, ['-e', `
+  const fs = require('fs');
+  const { execSync } = require('child_process');
+
+  const cacheFile = ${JSON.stringify(cacheFile)};
+  const projectVersionFile = ${JSON.stringify(projectVersionFile)};
+  const globalVersionFile = ${JSON.stringify(globalVersionFile)};
+
+  // Check project directory first (local install), then global
+  let installed = '0.0.0';
+  try {
+    if (fs.existsSync(projectVersionFile)) {
+      installed = fs.readFileSync(projectVersionFile, 'utf8').trim();
+    } else if (fs.existsSync(globalVersionFile)) {
+      installed = fs.readFileSync(globalVersionFile, 'utf8').trim();
+    }
+  } catch (e) {}
+
+  let latest = null;
+  try {
+    latest = execSync('npm view agents-reverse-engineer version', { encoding: 'utf8', timeout: 10000, windowsHide: true }).trim();
+  } catch (e) {}
+
+  const result = {
+    update_available: latest && installed !== latest,
+    installed,
+    latest: latest || 'unknown',
+    checked: Math.floor(Date.now() / 1000)
+  };
+
+  fs.writeFileSync(cacheFile, JSON.stringify(result));
+`], {
+  stdio: 'ignore',
+  detached: true,
+  windowsHide: true,
+});
+
+child.unref();

package/hooks/dist/are-session-end.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * ARE Session End Hook
+ *
+ * Triggers `are update` when session ends (if there are uncommitted changes).
+ * Runs in background to avoid blocking session close.
+ *
+ * Disable via:
+ * - Environment variable: ARE_DISABLE_HOOK=1
+ * - Config file: hook_enabled: false in .agents-reverse-engineer.yaml
+ */
+
+import { execSync, spawn } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+
+// Check for disable flag
+if (process.env.ARE_DISABLE_HOOK === '1') {
+  process.exit(0);
+}
+
+// Check config file for permanent disable
+const configPath = '.agents-reverse-engineer.yaml';
+if (existsSync(configPath)) {
+  const config = readFileSync(configPath, 'utf-8');
+  if (config.includes('hook_enabled: false')) {
+    process.exit(0);
+  }
+}
+
+// Check git status - skip if no changes
+try {
+  const status = execSync('git status --porcelain', { encoding: 'utf-8' });
+  if (!status.trim()) {
+    // No changes since last run - exit silently
+    process.exit(0);
+  }
+} catch {
+  // Not a git repo or git not available - exit silently
+  process.exit(0);
+}
+
+// Run update in background (don't block session close)
+const child = spawn('npx', ['agents-reverse-engineer@latest', 'update', '--quiet'], {
+  stdio: 'ignore',
+  detached: true,
+});
+child.unref();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-reverse-engineer",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "CLI tool for reverse-engineering codebase documentation for AI agents",
   "type": "module",
   "bin": {
@@ -9,11 +9,12 @@
   },
   "scripts": {
     "build": "tsc",
+    "build:hooks": "node scripts/build-hooks.js",
+    "prepublishOnly": "npm run build && npm run build:hooks",
     "dev": "tsx watch src/cli/index.ts",
     "test": "vitest"
   },
   "dependencies": {
-    "better-sqlite3": "^12.6.2",
     "fast-glob": "^3.3.3",
     "gpt-tokenizer": "^3.4.0",
     "ignore": "^7.0.3",
@@ -25,7 +26,6 @@
     "zod": "^3.24.1"
   },
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.10.7",
     "tsx": "^4.19.2",
     "typescript": "^5.7.3",
@@ -46,6 +46,7 @@
   "main": "dist/cli/index.js",
   "files": [
     "dist",
+    "hooks/dist",
     "README.md",
     "LICENSE"
   ],

package/dist/generation/writers/claude-md.d.ts

@@ -1,17 +0,0 @@
-/**
- * Write CLAUDE.md at the project root.
- *
- * Only writes if Claude Code is installed locally (`.claude` directory exists).
- * If a user-defined CLAUDE.md exists (not generated by us), it will be
- * preserved as CLAUDE.local.md and referenced in the generated file.
- *
- * @param projectRoot - Project root directory
- * @returns Path to written CLAUDE.md, or null if Claude Code is not installed
- */
-export declare function writeClaudeMd(projectRoot: string): Promise<string | null>;
-/**
- * Get the content that would be written to CLAUDE.md.
- * Useful for previewing without writing.
- */
-export declare function getClaudeMdContent(): string;
-//# sourceMappingURL=claude-md.d.ts.map

package/dist/generation/writers/claude-md.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"claude-md.d.ts","sourceRoot":"","sources":["../../../src/generation/writers/claude-md.ts"],"names":[],"mappings":"AA4DA;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA4B/E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C"}

package/dist/generation/writers/claude-md.js

@@ -1,96 +0,0 @@
-import { writeFile, readFile, stat, rename } from 'node:fs/promises';
-import * as path from 'node:path';
-import { isRuntimeInstalledLocally } from '../../installer/paths.js';
-/** Marker comment to identify generated CLAUDE.md files */
-const GENERATED_MARKER = '<!-- Generated by agents-reverse-engineer -->';
-/**
- * Standard CLAUDE.md content - simple pointer to AGENTS.md.
- *
- * Per CONTEXT.md: "Simple pointer to AGENTS.md for Anthropic compatibility"
- */
-function buildClaudeMdContent(hasLocalFile) {
-    const sections = [];
-    // Generated marker (first line)
-    sections.push(GENERATED_MARKER);
-    sections.push('');
-    // Reference to user-defined local file if it exists
-    if (hasLocalFile) {
-        sections.push('> **Note:** This project has additional documentation in [CLAUDE.local.md](./CLAUDE.local.md)');
-        sections.push('');
-    }
-    sections.push('# CLAUDE.md');
-    sections.push('');
-    sections.push('See [AGENTS.md](./AGENTS.md) for codebase documentation.');
-    sections.push('');
-    sections.push('This file exists for Anthropic compatibility. The actual documentation');
-    sections.push('is maintained in AGENTS.md files throughout the codebase.');
-    sections.push('');
-    return sections.join('\n');
-}
-/**
- * Check if a file was generated by us (contains marker).
- */
-async function isGeneratedFile(filePath) {
-    try {
-        const content = await readFile(filePath, 'utf-8');
-        return content.includes(GENERATED_MARKER);
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Check if a local file exists.
- */
-async function hasLocalFile(localPath) {
-    try {
-        await stat(localPath);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Write CLAUDE.md at the project root.
- *
- * Only writes if Claude Code is installed locally (`.claude` directory exists).
- * If a user-defined CLAUDE.md exists (not generated by us), it will be
- * preserved as CLAUDE.local.md and referenced in the generated file.
- *
- * @param projectRoot - Project root directory
- * @returns Path to written CLAUDE.md, or null if Claude Code is not installed
- */
-export async function writeClaudeMd(projectRoot) {
-    // Only generate if Claude Code is installed locally
-    const isInstalled = await isRuntimeInstalledLocally('claude', projectRoot);
-    if (!isInstalled) {
-        return null;
-    }
-    const claudePath = path.join(projectRoot, 'CLAUDE.md');
-    const localPath = path.join(projectRoot, 'CLAUDE.local.md');
-    // Check if existing CLAUDE.md is user-defined (not generated by us)
-    let hasLocal = await hasLocalFile(localPath);
-    try {
-        const existingIsGenerated = await isGeneratedFile(claudePath);
-        if (!existingIsGenerated) {
-            // User-defined CLAUDE.md exists - preserve it
-            await rename(claudePath, localPath);
-            hasLocal = true;
-        }
-    }
-    catch {
-        // No existing CLAUDE.md - that's fine
-    }
-    const content = buildClaudeMdContent(hasLocal);
-    await writeFile(claudePath, content, 'utf-8');
-    return claudePath;
-}
-/**
- * Get the content that would be written to CLAUDE.md.
- * Useful for previewing without writing.
- */
-export function getClaudeMdContent() {
-    return buildClaudeMdContent(false);
-}
-//# sourceMappingURL=claude-md.js.map

package/dist/generation/writers/claude-md.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"claude-md.js","sourceRoot":"","sources":["../../../src/generation/writers/claude-md.ts"],"names":[],"mappings":"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"}