@unerr-ai/unerr 0.2.0 → 0.2.2

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@unerr-ai/unerr",
-  "version": "0.2.0",
+  "version": "0.2.2",
+  "mcpName": "io.github.unerr-ai/unerr",
   "description": "Local-first code intelligence CLI for unerr",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/unerr-ai/unerr-cli.git"
+  },
   "type": "module",
   "bin": {
     "unerr": "./dist/cli.js"

package/dist/behaviors/agent-llm-bridge.js

@@ -1,166 +0,0 @@
-/**
- * Agent-as-LLM Bridge — BA-3.3
- *
- * Formalizes the sub-prompt injection pattern used throughout Layer 4.
- * Instead of managing API keys, unerr injects follow-up prompts that the
- * host agent (Claude/GPT) processes as part of its normal flow.
- *
- * Features:
- *   - Template system for common sub-prompt types
- *   - 5s timeout with graceful fallback to AST-only processing
- *   - Follow-through tracking: did the agent act on the injected prompt?
- *   - Prompt budgeting: limits injected context to prevent bloat
- */
-const DEFAULT_TIMEOUT_MS = 5_000;
-const MAX_PROMPT_TOKENS = 500;
-const PROMPT_BUDGET_PER_CALL = 1000;
-const TEMPLATE_DEFINITIONS = {
-    session_resume: {
-        prefix: "Summarize the following session state for the developer in 2-3 natural sentences.",
-        maxTokens: 300,
-        priority: "normal",
-    },
-    doc_generation: {
-        prefix: "Generate documentation following the existing style in this file.",
-        maxTokens: 400,
-        priority: "low",
-    },
-    doc_update: {
-        prefix: "Update the documentation to reflect the following signature change.",
-        maxTokens: 300,
-        priority: "low",
-    },
-    loop_diagnosis: {
-        prefix: "Analyze why the previous attempts failed before trying again.",
-        maxTokens: 500,
-        priority: "high",
-    },
-    convention_fix: {
-        prefix: "Regenerate the code following the project's naming conventions.",
-        maxTokens: 400,
-        priority: "normal",
-    },
-    cascade_fix: {
-        prefix: "Generate updated call sites for each caller with the new signature.",
-        maxTokens: 500,
-        priority: "high",
-    },
-    architecture_alternative: {
-        prefix: "The following import crosses a module boundary. Suggest an alternative pattern.",
-        maxTokens: 400,
-        priority: "normal",
-    },
-};
-let promptIdCounter = 0;
-export class AgentLlmBridge {
-    injections = [];
-    totalPromptTokensThisCall = 0;
-    /**
-     * Create a sub-prompt from a template with custom context.
-     */
-    createPrompt(template, context, options) {
-        const def = TEMPLATE_DEFINITIONS[template];
-        const content = [def.prefix, "", context].join("\n");
-        return {
-            template,
-            content: truncateToTokens(content, def.maxTokens),
-            priority: def.priority,
-            maxTokens: def.maxTokens,
-            timeoutMs: options?.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-            fallbackContent: options?.fallback ?? null,
-        };
-    }
-    /**
-     * Inject a sub-prompt into the internal `context` carrier; surfaces as `ur|hnt` prefix line on the response.
-     * Returns the prompt content if within budget, or the fallback if over budget.
-     */
-    inject(prompt) {
-        const estimatedTokens = estimateTokens(prompt.content);
-        if (this.totalPromptTokensThisCall + estimatedTokens >
-            PROMPT_BUDGET_PER_CALL) {
-            return prompt.fallbackContent ?? "";
-        }
-        this.totalPromptTokensThisCall += estimatedTokens;
-        const injection = {
-            id: `prompt-${++promptIdCounter}`,
-            prompt,
-            injectedAt: Date.now(),
-            followedThrough: null,
-            responseDetectedAt: null,
-        };
-        this.injections.push(injection);
-        return prompt.content;
-    }
-    /**
-     * Record that the agent acted on an injected prompt.
-     * Called when a subsequent tool call references the prompted action.
-     */
-    recordFollowThrough(promptId) {
-        const injection = this.injections.find((i) => i.id === promptId);
-        if (injection) {
-            injection.followedThrough = true;
-            injection.responseDetectedAt = Date.now();
-        }
-    }
-    /**
-     * Reset per-call budget (call at the start of each tool call).
-     */
-    resetCallBudget() {
-        this.totalPromptTokensThisCall = 0;
-    }
-    /**
-     * Get follow-through rate: what % of injected prompts led to agent action.
-     * Counts all injections (null = not followed through yet = counts as miss).
-     */
-    getFollowThroughRate() {
-        if (this.injections.length === 0)
-            return 0;
-        const followed = this.injections.filter((i) => i.followedThrough === true);
-        return followed.length / this.injections.length;
-    }
-    /**
-     * Get the last injected prompt's ID (useful for follow-through recording).
-     */
-    getLastInjectionId() {
-        if (this.injections.length === 0)
-            return null;
-        return this.injections[this.injections.length - 1]?.id ?? null;
-    }
-    getStats() {
-        const byTemplate = {};
-        let followedCount = 0;
-        for (const injection of this.injections) {
-            const key = injection.prompt.template;
-            byTemplate[key] = (byTemplate[key] ?? 0) + 1;
-            if (injection.followedThrough)
-                followedCount++;
-        }
-        return {
-            totalInjected: this.injections.length,
-            followedThrough: followedCount,
-            followThroughRate: this.getFollowThroughRate(),
-            byTemplate,
-        };
-    }
-    /**
-     * Get all available template types.
-     */
-    static getTemplates() {
-        return Object.keys(TEMPLATE_DEFINITIONS);
-    }
-    /**
-     * Get template definition for a specific type.
-     */
-    static getTemplateDefinition(template) {
-        return { ...TEMPLATE_DEFINITIONS[template] };
-    }
-}
-function estimateTokens(text) {
-    return Math.ceil(text.length / 4);
-}
-function truncateToTokens(text, maxTokens) {
-    const maxChars = maxTokens * 4;
-    if (text.length <= maxChars)
-        return text;
-    return `${text.slice(0, maxChars - 3)}...`;
-}

package/dist/behaviors/architecture-guard.js

@@ -1,256 +0,0 @@
-/**
- * Architecture Boundary Guard — BA-3.1
- *
- * PreToolUse: when an agent writes/edits code, parses new import statements,
- * resolves them to file paths, and queries CozoDB for community membership.
- * Blocks cross-community direct imports unless:
- *   - The import is a type-only import (`import type`)
- *   - An override comment (`// @unerr-allow cross-community: [reason]`) exists
- *   - An established bridge exists (same pattern used 3+ times → auto-bridge)
- *
- * Assertiveness: enforcement (blocks with alternatives)
- * Performance: <5ms (CozoDB community query)
- */
-import { Behavior, } from "./framework.js";
-const BRIDGE_THRESHOLD = 3;
-const OVERRIDE_PATTERN = /\/\/\s*@unerr-allow\s+cross-community:\s*(.*)/;
-const EDIT_TOOLS = new Set([
-    "file_write",
-    "write_file",
-    "edit_file",
-    "str_replace_editor",
-    "insert_code",
-    "replace_code",
-]);
-export class ArchitectureBoundaryGuard extends Behavior {
-    id = "architecture_boundary";
-    hooks = ["pre_tool_use"];
-    defaultLevel = "enforcement";
-    graph = null;
-    bridges = new Map();
-    guardConfig;
-    violationsBlocked = 0;
-    typeImportsAllowed = 0;
-    overridesRecorded = 0;
-    constructor(config) {
-        super(config, "enforcement");
-        this.guardConfig = {
-            enabled: true,
-            level: "enforcement",
-            allowTypeImports: true,
-            bridgeThreshold: BRIDGE_THRESHOLD,
-            ...config,
-        };
-    }
-    attachGraph(graph) {
-        this.graph = graph;
-    }
-    async onPreToolUse(ctx) {
-        if (!this.graph)
-            return null;
-        if (!EDIT_TOOLS.has(ctx.toolName))
-            return null;
-        const filePath = extractFilePath(ctx.args);
-        if (!filePath)
-            return null;
-        if (!isCodeFile(filePath))
-            return null;
-        const newContent = extractNewContent(ctx.args);
-        if (!newContent)
-            return null;
-        const imports = parseImports(newContent);
-        if (imports.length === 0)
-            return null;
-        const sourceEntities = await this.graph.getEntitiesByFile(filePath);
-        if (sourceEntities.length === 0)
-            return null;
-        const sourceCommunity = await this.graph.getCommunityForEntity(sourceEntities[0].key);
-        if (!sourceCommunity)
-            return null;
-        const violations = [];
-        const alternatives = [];
-        for (const imp of imports) {
-            if (imp.isTypeOnly && this.guardConfig.allowTypeImports) {
-                this.typeImportsAllowed++;
-                continue;
-            }
-            if (imp.hasOverride) {
-                this.overridesRecorded++;
-                await this.recordOverride(sourceCommunity.id, imp.resolvedPath ?? "", filePath);
-                continue;
-            }
-            const targetCommunity = await this.resolveTargetCommunity(imp.resolvedPath ?? imp.specifier, filePath);
-            if (!targetCommunity)
-                continue;
-            if (targetCommunity.id === sourceCommunity.id)
-                continue;
-            const bridgeKey = `${sourceCommunity.id}→${targetCommunity.id}`;
-            const bridge = this.bridges.get(bridgeKey);
-            if (bridge?.autoBridged)
-                continue;
-            violations.push({
-                import: imp.raw,
-                sourceFile: filePath,
-                sourceCommunity: sourceCommunity.label,
-                sourceCommunityId: sourceCommunity.id,
-                targetCommunity: targetCommunity.label,
-                targetCommunityId: targetCommunity.id,
-                violationType: "cross_community_direct_import",
-            });
-            alternatives.push({
-                pattern: "type_import",
-                example: `import type { ... } from '${imp.specifier}' // types are OK, not implementation`,
-            }, {
-                pattern: "interface_bridge",
-                example: "Define shared types in a schemas/ module accessible to both communities",
-            });
-        }
-        if (violations.length === 0)
-            return null;
-        this.violationsBlocked += violations.length;
-        return {
-            behaviorId: this.id,
-            level: this.level,
-            halt: this.level === "enforcement",
-            relatedSkillId: "understand-before-modify",
-            _meta: {
-                behavior: this.id,
-                blocked: this.level === "enforcement",
-                violations_count: violations.length,
-            },
-            _context: {
-                violations: violations.map((v) => ({
-                    import: v.import,
-                    source_file: v.sourceFile,
-                    source_community: v.sourceCommunity,
-                    target_community: v.targetCommunity,
-                    violation_type: v.violationType,
-                })),
-                alternatives,
-                override: "Add '// @unerr-allow cross-community: [reason]' to bypass",
-            },
-        };
-    }
-    getSessionStats() {
-        let autoBridges = 0;
-        for (const bridge of this.bridges.values()) {
-            if (bridge.autoBridged)
-                autoBridges++;
-        }
-        return {
-            violationsBlocked: this.violationsBlocked,
-            typeImportsAllowed: this.typeImportsAllowed,
-            overridesRecorded: this.overridesRecorded,
-            autoBridges,
-        };
-    }
-    getBridges() {
-        return new Map(this.bridges);
-    }
-    async resolveTargetCommunity(importSpecifier, sourceFile) {
-        if (!this.graph)
-            return null;
-        const resolvedPath = resolveImportPath(importSpecifier, sourceFile);
-        if (!resolvedPath)
-            return null;
-        const targetEntities = await this.graph.getEntitiesByFile(resolvedPath);
-        if (targetEntities.length === 0)
-            return null;
-        const community = await this.graph.getCommunityForEntity(targetEntities[0].key);
-        if (!community)
-            return null;
-        return { id: community.id, label: community.label };
-    }
-    async recordOverride(sourceCommunityId, _targetPath, _sourceFile) {
-        const targetCommunity = await this.resolveTargetCommunity(_targetPath, _sourceFile);
-        if (!targetCommunity)
-            return;
-        const bridgeKey = `${sourceCommunityId}→${targetCommunity.id}`;
-        const existing = this.bridges.get(bridgeKey);
-        if (existing) {
-            existing.overrideCount++;
-            if (existing.overrideCount >= this.guardConfig.bridgeThreshold &&
-                !existing.autoBridged) {
-                existing.autoBridged = true;
-            }
-        }
-        else {
-            this.bridges.set(bridgeKey, {
-                sourceCommunity: sourceCommunityId,
-                targetCommunity: targetCommunity.id,
-                overrideCount: 1,
-                autoBridged: false,
-            });
-        }
-    }
-}
-function parseImports(content) {
-    const results = [];
-    const lines = content.split("\n");
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i].trim();
-        const importMatch = line.match(/^import\s+(type\s+)?(?:\{[^}]*\}|[^'"]+)\s+from\s+['"]([^'"]+)['"]/);
-        if (!importMatch)
-            continue;
-        const isTypeOnly = !!importMatch[1];
-        const specifier = importMatch[2];
-        if (!specifier.startsWith("."))
-            continue;
-        const prevLine = i > 0 ? (lines[i - 1]?.trim() ?? "") : "";
-        const hasOverride = OVERRIDE_PATTERN.test(prevLine) || OVERRIDE_PATTERN.test(line);
-        results.push({
-            raw: line,
-            specifier,
-            isTypeOnly,
-            hasOverride,
-            resolvedPath: null,
-        });
-    }
-    return results;
-}
-function resolveImportPath(specifier, sourceFile) {
-    if (!specifier.startsWith("."))
-        return null;
-    const sourceParts = sourceFile.split("/");
-    sourceParts.pop();
-    const specParts = specifier.split("/");
-    const resolved = [...sourceParts];
-    for (const part of specParts) {
-        if (part === ".")
-            continue;
-        if (part === "..") {
-            resolved.pop();
-        }
-        else {
-            resolved.push(part);
-        }
-    }
-    let result = resolved.join("/");
-    if (!result.match(/\.[jt]sx?$/)) {
-        result += ".ts";
-    }
-    return result;
-}
-function extractFilePath(args) {
-    if (typeof args.path === "string")
-        return args.path;
-    if (typeof args.file_path === "string")
-        return args.file_path;
-    if (typeof args.file === "string")
-        return args.file;
-    return null;
-}
-function extractNewContent(args) {
-    if (typeof args.new_str === "string")
-        return args.new_str;
-    if (typeof args.new_string === "string")
-        return args.new_string;
-    if (typeof args.content === "string")
-        return args.content;
-    if (typeof args.after === "string")
-        return args.after;
-    return null;
-}
-function isCodeFile(filePath) {
-    return /\.[jt]sx?$/.test(filePath);
-}

package/dist/behaviors/auto-doc.js

@@ -1,247 +0,0 @@
-/**
- * Auto-Documentation Generation — BA-2.3
- *
- * PostToolUse: detects exported symbol changes (function signature, type
- * definition, class method). Two-tier approach:
- *
- *   1. Fast path (invisible): template JSDoc/TSDoc from new signature
- *   2. Semantic path (agent-as-LLM): inject sub-prompt for complex docs
- *      with 5s timeout + graceful AST fallback
- *
- * Tracks doc updates so the learning loop can calibrate quality.
- */
-import { Behavior, } from "./framework.js";
-const AGENT_LLM_TIMEOUT_MS = 5_000;
-const EDIT_TOOLS = new Set([
-    "file_write",
-    "write_file",
-    "edit_file",
-    "str_replace_editor",
-    "insert_code",
-    "replace_code",
-]);
-export class AutoDocBehavior extends Behavior {
-    id = "auto_doc";
-    hooks = ["post_tool_use"];
-    defaultLevel = "invisible";
-    graph = null;
-    docConfig;
-    docsGeneratedThisSession = 0;
-    docsFlaggedThisSession = 0;
-    constructor(config) {
-        super(config, "invisible");
-        this.docConfig = {
-            enabled: true,
-            level: "invisible",
-            inlineDocs: true,
-            useAgentAsLlm: true,
-            ...config,
-        };
-    }
-    attachGraph(graph) {
-        this.graph = graph;
-    }
-    async onPostToolUse(ctx) {
-        if (!EDIT_TOOLS.has(ctx.toolName))
-            return null;
-        if (!ctx.filePath)
-            return null;
-        if (!isCodeFile(ctx.filePath))
-            return null;
-        const newContent = extractNewContent(ctx.args);
-        if (!newContent)
-            return null;
-        const actions = [];
-        const inlineActions = await this.detectInlineDocNeeds(ctx.filePath, newContent);
-        actions.push(...inlineActions);
-        const refActions = await this.detectStaleReferences(ctx.filePath, newContent);
-        actions.push(...refActions);
-        if (actions.length === 0)
-            return null;
-        this.docsGeneratedThisSession += actions.filter((a) => a.type !== "reference_flagged").length;
-        this.docsFlaggedThisSession += actions.filter((a) => a.type === "reference_flagged").length;
-        const agentPrompt = this.docConfig.useAgentAsLlm
-            ? this.buildAgentPrompt(ctx.filePath, actions)
-            : undefined;
-        return {
-            behaviorId: this.id,
-            level: this.level,
-            _meta: {
-                behavior: this.id,
-                docs_updated: actions.filter((a) => a.type !== "reference_flagged")
-                    .length,
-                docs_flagged: actions.filter((a) => a.type === "reference_flagged")
-                    .length,
-                method: agentPrompt ? "agent_as_llm" : "template",
-            },
-            _context: {
-                doc_actions: actions,
-                ...(agentPrompt ? { agent_prompt: agentPrompt } : {}),
-            },
-        };
-    }
-    getSessionStats() {
-        return {
-            docsGenerated: this.docsGeneratedThisSession,
-            docsFlagged: this.docsFlaggedThisSession,
-        };
-    }
-    /**
-     * Detect exported functions/classes that were changed and need doc updates.
-     * Fast path: generate template JSDoc from the new signature.
-     */
-    async detectInlineDocNeeds(filePath, content) {
-        const actions = [];
-        const exportedFunctions = extractExportedSignatures(content);
-        for (const sig of exportedFunctions) {
-            const hasDoc = hasExistingDoc(content, sig.startIndex);
-            const params = extractParamsFromSignature(sig.signature);
-            if (!hasDoc && params.length > 0) {
-                const jsdoc = generateTemplateJSDoc(sig.name, params, sig.returnType);
-                actions.push({
-                    type: "jsdoc_generated",
-                    entity: sig.name,
-                    file: filePath,
-                    change: `Generated JSDoc for ${sig.name}(${params.map((p) => p.name).join(", ")})`,
-                    agentPrompt: this.docConfig.useAgentAsLlm
-                        ? buildInlineDocPrompt(filePath, sig.name, sig.signature)
-                        : undefined,
-                });
-            }
-            else if (hasDoc && this.graph) {
-                const entity = await this.findEntity(sig.name, filePath);
-                if (entity?.signature && entity.signature !== sig.signature) {
-                    actions.push({
-                        type: "jsdoc_updated",
-                        entity: sig.name,
-                        file: filePath,
-                        change: "Signature changed — doc may be stale",
-                        agentPrompt: this.docConfig.useAgentAsLlm
-                            ? buildUpdateDocPrompt(filePath, sig.name, entity.signature, sig.signature)
-                            : undefined,
-                    });
-                }
-            }
-        }
-        return actions;
-    }
-    /**
-     * Flag reference documentation (.md files) that may reference changed entities.
-     */
-    async detectStaleReferences(filePath, content) {
-        if (!this.graph)
-            return [];
-        const exportedNames = extractExportedSignatures(content).map((s) => s.name);
-        if (exportedNames.length === 0)
-            return [];
-        const actions = [];
-        for (const name of exportedNames) {
-            const entity = await this.findEntity(name, filePath);
-            if (!entity)
-                continue;
-            if (entity.fan_in > 3) {
-                actions.push({
-                    type: "reference_flagged",
-                    entity: name,
-                    file: filePath,
-                    change: `High-usage symbol "${name}" (${entity.fan_in} callers) modified — check referencing docs`,
-                });
-            }
-        }
-        return actions;
-    }
-    async findEntity(name, filePath) {
-        if (!this.graph)
-            return null;
-        const entities = await this.graph.getEntitiesByFile(filePath);
-        return entities.find((e) => e.name === name) ?? null;
-    }
-    buildAgentPrompt(filePath, actions) {
-        const parts = [
-            "Documentation may need updating based on recent code changes:",
-            "",
-        ];
-        for (const action of actions) {
-            if (action.agentPrompt) {
-                parts.push(action.agentPrompt);
-                parts.push("");
-            }
-            else {
-                parts.push(`- ${action.file}: ${action.change}`);
-            }
-        }
-        parts.push("");
-        parts.push("Please review and update documentation as needed, following the existing doc style in this project.");
-        return parts.join("\n");
-    }
-}
-function isCodeFile(filePath) {
-    return /\.[jt]sx?$/.test(filePath);
-}
-function extractNewContent(args) {
-    if (typeof args.new_str === "string")
-        return args.new_str;
-    if (typeof args.new_string === "string")
-        return args.new_string;
-    if (typeof args.content === "string")
-        return args.content;
-    if (typeof args.after === "string")
-        return args.after;
-    return null;
-}
-function extractExportedSignatures(content) {
-    const results = [];
-    const pattern = /(?:export\s+)?(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*(\([^)]*\))(?:\s*:\s*([^{]+?))?(?:\s*\{)/g;
-    let match;
-    match = pattern.exec(content);
-    while (match !== null) {
-        const name = match[1];
-        const params = match[2];
-        const returnType = match[3]?.trim() ?? null;
-        results.push({
-            name,
-            signature: `${name}${params}${returnType ? `: ${returnType}` : ""}`,
-            startIndex: match.index,
-            returnType,
-        });
-        match = pattern.exec(content);
-    }
-    return results;
-}
-function hasExistingDoc(content, signatureIndex) {
-    const before = content.slice(Math.max(0, signatureIndex - 200), signatureIndex);
-    return /\/\*\*[\s\S]*?\*\/\s*$/.test(before);
-}
-function extractParamsFromSignature(signature) {
-    const match = signature.match(/\(([^)]*)\)/);
-    if (!match || !match[1]?.trim())
-        return [];
-    return match[1]
-        .split(",")
-        .map((p) => {
-        const trimmed = p.trim();
-        const parts = trimmed.split(/\s*:\s*/);
-        const name = parts[0]?.replace(/[?]$/, "").trim() ?? "";
-        const type = parts[1]?.trim() ?? null;
-        return { name, type };
-    })
-        .filter((p) => p.name.length > 0);
-}
-function generateTemplateJSDoc(name, params, returnType) {
-    const lines = ["/**"];
-    for (const param of params) {
-        const typeStr = param.type ? ` {${param.type}}` : "";
-        lines.push(` * @param${typeStr} ${param.name}`);
-    }
-    if (returnType && returnType !== "void") {
-        lines.push(` * @returns {${returnType}}`);
-    }
-    lines.push(" */");
-    return lines.join("\n");
-}
-function buildInlineDocPrompt(filePath, funcName, signature) {
-    return `Generate a concise JSDoc comment for the function "${funcName}" in ${filePath}. Signature: ${signature}. Follow the existing documentation style in this file. Focus on what the function does, not how.`;
-}
-function buildUpdateDocPrompt(filePath, funcName, oldSignature, newSignature) {
-    return `The function "${funcName}" in ${filePath} had its signature changed from "${oldSignature}" to "${newSignature}". Update the JSDoc above the function to reflect the new parameters. Preserve the existing description.`;
-}