{"_id":"@anillabs/alvi","_rev":"6-c55b9ae262ac9514990104491fa6f8c9","name":"@anillabs/alvi","dist-tags":{"latest":"2.0.0"},"versions":{"1.0.1":{"name":"@anillabs/alvi","version":"1.0.1","_id":"@anillabs/alvi@1.0.1","maintainers":[{"name":"anillabs","email":"kumaranil21@gmail.com"}],"bin":{"alvi":"bin/alvi"},"dist":{"shasum":"5c1a7c3459fe74eacadfdb483ff962069d7223a9","tarball":"https://registry.npmjs.org/@anillabs/alvi/-/alvi-1.0.1.tgz","fileCount":52,"integrity":"sha512-0CESf+1SL6l6KQtq0/3oMECt9wzmUdJc2CrKMHe7eNO1qmweO6opC/FCgsA725jXa1ye6I9Vxu+pFri6tXtjFA==","signatures":[{"sig":"MEUCIG02K9p5ckvrXRASW4ZhmMvulJ+W5UvsYMftBCaCYwAQAiEAp5bG8T2/Pvy1wXWNF3obmM4gp+K+4U+APSiOa5B5qQM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":110817},"main":"dist/cli/index.js","gitHead":"5f520cf782912a2085c17922830c2154d4c5d618","scripts":{"dev":"npm run build && node dist/dev-server.js","lint":"eslint src/**/*.ts","build":"tsc","clean":"rm -rf dist","start":"node dist/cli/index.js","format":"prettier --write \"src/**/*.ts\"","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"anillabs","email":"kumaranil21@gmail.com"},"_npmVersion":"11.17.0","description":"An open-source, token-optimized AI Development Lifecycle framework and local MCP governance engine.","directories":{},"_nodeVersion":"24.19.0","dependencies":{"zod":"^4.5.2","yaml":"^2.9.0","chalk":"^6.0.0","commander":"^12.0.0","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^8.56.0","prettier":"^3.1.1","typescript":"^5.3.3","@types/node":"^20.11.0"},"_npmOperationalInternal":{"tmp":"tmp/alvi_1.0.1_1788024774786_0.26383305715524297","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@anillabs/alvi","version":"1.0.2","keywords":["ai","mcp","lifecycle","governance","agents","cli","aidlc","model-context-protocol","developer-tools","cursor","copilot","typescript","open-source"],"author":{"name":"Anil Labs","email":"kumaranil21@gmail.com"},"license":"MIT","_id":"@anillabs/alvi@1.0.2","maintainers":[{"name":"anillabs","email":"kumaranil21@gmail.com"}],"homepage":"https://github.com/anillabs/alvi#readme","bugs":{"url":"https://github.com/anillabs/alvi/issues"},"bin":{"alvi":"bin/alvi"},"dist":{"shasum":"36cb11d6ed1acd0499e1962a1d37f53d3bec04c3","tarball":"https://registry.npmjs.org/@anillabs/alvi/-/alvi-1.0.2.tgz","fileCount":52,"integrity":"sha512-wcKhR+H4d9GIwoILBileXnWeTqxIC39gaO+XmTE1gmdfVgMFymhvbBXSfOZqii33I4kFzNDrXQbeW07RkVBkvg==","signatures":[{"sig":"MEUCIH4WyXbpfB1SNJ1Kfh8bsnqy/9FpZIUgzpJ/gvqtrkf6AiEAtSYrqCVVzGvzAYGqWON1RzH3UCXBlsl8FnN634wXAUc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQDRZS77QIbkBeDSJOdkqDP6WKmsdAjJYAygIadVV+csawIgE2x7PBBBg8jC6saYUoOZHrCqxkgwKDhFLF6e1KYYykg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":123802},"main":"dist/cli/index.js","engines":{"node":">=20.0.0"},"gitHead":"eaacce86fc71921ca0d158ee3aadb3846cbdf0a6","scripts":{"dev":"npm run build && node dist/dev-server.js","lint":"eslint src/**/*.ts","build":"tsc","clean":"rm -rf dist","start":"node dist/cli/index.js","format":"prettier --write \"src/**/*.ts\"","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"anillabs","email":"kumaranil21@gmail.com"},"repository":{"url":"git+https://github.com/anillabs/alvi.git","type":"git"},"_npmVersion":"11.19.0","description":"An open-source, token-optimized AI Development Lifecycle framework and local MCP governance engine.","directories":{},"_nodeVersion":"24.20.0","dependencies":{"zod":"^4.5.2","yaml":"^2.9.0","chalk":"^6.0.0","commander":"^12.0.0","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^8.56.0","prettier":"^3.1.1","typescript":"^5.3.3","@types/node":"^24.0.0"},"_npmOperationalInternal":{"tmp":"tmp/alvi_1.0.2_1788713144455_0.8153536178759","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"_id":"@anillabs/alvi@2.0.0","bin":{"alvi":"bin/alvi"},"bugs":{"email":"anil@anillabs.com"},"dist":{"shasum":"ab142bcc5b6672ccadd39beb13e3953998b9af94","tarball":"https://registry.npmjs.org/@anillabs/alvi/-/alvi-2.0.0.tgz","fileCount":100,"integrity":"sha512-6IVpgKmUJRE9ont7HXgChE7sd65+LGoxQae8CtTEdyhXN4l26zDyLhMDgMKUmQrpwhEAw576SXSzYrolsUqFCQ==","signatures":[{"sig":"MEYCIQCF1S45q7PJnX1IDCDMlHpn3zSvfEydlAvb8kWc8h/wQAIhAPO7Q+DnOqO3+ntYO9RsKzz/mo7nfwzowOr7YxMlCfJr","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCBPpKe8M/D6UFKDcoZGVXbhCKdNGvjTzLH5IhDAFh6AAIhANRvLW6/agAaSsNgIDRACeNlHYgiRYQYI2nyT5tnjUd+"}],"unpackedSize":196115},"main":"dist/cli/index.js","name":"@anillabs/alvi","type":"module","author":{"name":"Anil Labs","email":"anil@anillabs.com"},"engines":{"node":">=24.0.0"},"gitHead":"11dac9d29ac364c89f2e463fd7e5b26635802d97","license":"MIT","scripts":{"dev":"npm run build && node dist/cli/index.js","lint":"eslint src/**/*.ts","test":"vitest run","build":"tsc","clean":"rm -rf dist","start":"node dist/cli/index.js","format":"prettier --write \"src/**/*.ts\"","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"npm run clean && npm run build"},"version":"2.0.0","_npmUser":{"name":"anillabs","email":"kumaranil21@gmail.com"},"homepage":"https://www.anillabs.com/","keywords":["ai","mcp","lifecycle","governance","agents","cli","aidlc","model-context-protocol","developer-tools","cursor","copilot","typescript","open-source"],"_npmVersion":"11.19.0","description":"Alvi — The engineering control plane for AI coding agents.","directories":{},"maintainers":[{"name":"anillabs","email":"kumaranil21@gmail.com"}],"_nodeVersion":"24.20.0","dependencies":{"zod":"^3.23.0","yaml":"^2.9.0","chalk":"^5.3.0","commander":"^12.0.0","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^8.56.0","vitest":"^4.1.11","prettier":"^3.1.1","typescript":"^5.9.3","@types/node":"^20.11.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/alvi_2.0.0_1789229890757_0.7110238421984056"}}},"time":{"created":"2026-08-29T17:32:54.604Z","modified":"2026-09-12T16:18:10.993Z","1.0.0":"2026-08-29T17:04:03.545Z","1.0.1":"2026-08-29T17:32:54.946Z","1.0.2":"2026-09-06T16:45:44.543Z","2.0.0":"2026-09-12T16:18:10.838Z"},"bugs":{"email":"anil@anillabs.com"},"author":{"name":"Anil Labs","email":"anil@anillabs.com"},"license":"MIT","homepage":"https://www.anillabs.com/","keywords":["ai","mcp","lifecycle","governance","agents","cli","aidlc","model-context-protocol","developer-tools","cursor","copilot","typescript","open-source"],"description":"Alvi — The engineering control plane for AI coding agents.","maintainers":[{"name":"anillabs","email":"kumaranil21@gmail.com"}],"readme":"# Alvi\n\n> Alvi — The engineering control plane for AI coding agents.\n\n[![npm version](https://badge.fury.io/js/@anillabs%2Falvi.svg)](https://badge.fury.io/js/@anillabs%2Falvi)\n\nAlvi is a lightweight, open-source framework designed to steer AI coding agents across multiple IDEs (Cursor, VS Code Copilot, Kiro) without blowing up your token context window or budget.\n\nAI agents should be able to move fast without allowing engineering quality, security, architecture, scope, testing, or governance to move backwards. Alvi sits between AI coding agents and the software repository to enforce policy via a unified Core. It can be used both as a CLI tool and natively via the Model Context Protocol (MCP) in your IDE.\n\n## Architecture\n\n```mermaid\ngraph TD\n    %% External Interfaces\n    Agent[AI Agent / IDE]\n    Developer[Developer CLI]\n    CI[CI Pipeline]\n\n    %% Interfaces\n    MCP[MCP Server]\n    CLI[CLI Interface]\n    \n    Agent -->|MCP Protocol| MCP\n    Developer -->|CLI Commands| CLI\n    CI -->|CLI Checks| CLI\n\n    %% Alvi Runtime\n    subgraph \"AlviRuntime (Unified Core)\"\n        Context[ContextEngine]\n        Task[TaskEngine]\n        Life[LifecycleEngine]\n        Config[ConfigEngine]\n        GitWrap[GitService]\n        \n        subgraph \"GateRegistry (Plugin System)\"\n            Sec[SecretGate]\n            Scope[ScopeGate]\n            Arch[ArchitectureGate]\n            TS[TypeScriptGate]\n        end\n    end\n\n    %% Wiring Interfaces to Core\n    MCP --> Context\n    MCP --> Task\n    MCP --> Life\n    CLI --> Config\n    CLI --> Task\n    CLI --> Life\n    CLI --> GitWrap\n    \n    %% Core interactions\n    Task --> Life\n    Task --> GateRegistry\n    GateRegistry --> Config\n    \n    %% Output\n    GitWrap --> Repo[(Local Git Repository)]\n    GateRegistry --> Repo\n\n    classDef core fill:#0a192f,stroke:#64ffda,stroke-width:2px,color:#fff;\n    classDef plugin fill:#112240,stroke:#64ffda,stroke-width:1px,color:#fff;\n    classDef interface fill:#000,stroke:#8892b0,stroke-width:2px,color:#fff;\n    \n    class MCP,CLI interface;\n    class Context,Task,Life,Config,GitWrap core;\n    class Sec,Scope,Arch,TS plugin;\n```\n\n---\n\n## Installation\n\n```bash\nnpm install -g @anillabs/alvi\n```\n\nInitialize a new project:\n```bash\ncd my-project\nalvi init\n```\nThis generates the `alvi.yml` configuration and bootstraps your IDE agent rules (for Cursor, Copilot, etc.).\n\n---\n\n## CLI Commands\n\nAlvi provides a comprehensive CLI for managing agent workflows.\n\n### 1. Task & Lifecycle\n- `alvi task <title>`: Creates and activates a new engineering task, assigning it a unique ID.\n- `alvi status`: Displays the active task and current lifecycle phase.\n- `alvi transition <to>`: Moves the active task to a new phase (e.g., `intake`, `plan`, `implement`, `review`).\n\n### 2. Quality & Security Gates\n- `alvi check`: Runs all applicable plugin gates (TypeScript, ESLint, Secrets, Scope, Architecture, Complexity).\n- `alvi check --json`: Outputs gate findings in CI/machine-readable JSON format.\n- `alvi fix`: Automatically fixes any gate findings that support autofix (e.g., executing ESLint autofixes).\n\n### 3. Agent Context & Intelligence\n- `alvi plan`: Generates and records the technical implementation plan.\n- `alvi review`: Runs an AI-aware engineering review of the current Git diff.\n- `alvi explain`: Explains the current task and policies in plain English.\n- `alvi context`: Dynamically surfaces relevant context files and their relevance score based on the current task.\n\n### 4. Git Safety Wrappers\n- `alvi git status` / `alvi git diff`: Standard Git wrappers.\n- `alvi git commit` / `alvi git push`: Mutating Git wrappers that enforce user-approval requirements to prevent autonomous agents from silently mutating the remote.\n\n### 5. Configuration & System\n- `alvi doctor`: Checks if Alvi is correctly installed and configured.\n- `alvi config show`: Dumps the current active `alvi.yml` settings.\n- `alvi config validate`: Validates `alvi.yml` against the strict Zod schema.\n\n---\n\n## MCP (Model Context Protocol)\n\nStart the MCP server to connect Alvi directly to your IDE (Cursor, VS Code, Kiro):\n```bash\nalvi mcp\n```\n\n### Available MCP Capabilities:\n- **Tools**: `alvi_status`, `alvi_task`, `alvi_check`, `alvi_transition`, `alvi_scope`.\n- **Resources**:\n  - `alvi://status`: Exposes current task metadata.\n  - `alvi://policy`: Exposes active `alvi.yml` rule set.\n- **Prompts**: `alvi-plan` (to initiate the planning phase).\n\n---\n\n## Configuration (`alvi.yml`)\n\nAlvi configuration is defined in `alvi.yml` at the root of your workspace:\n\n```yaml\nversion: \"1.0\"\nquality:\n  gates:\n    typecheck:\n      enabled: true\n      command: \"npm run typecheck\"\n    lint:\n      enabled: true\n      command: \"npm run lint\"\n      severity: \"warning\"\narchitecture:\n  enabled: true\n  maxComplexity: 10\n  boundaries:\n    - from: \"src/api/**\"\n      deny: [\"src/database/**\"]\nsecurity:\n  secrets:\n    enabled: true\nscopeGuard:\n  enabled: true\n  maxFiles: 30\n```\n\n## End-to-End Flow\n\nA standard workflow for an AI agent (or developer) using Alvi looks like this:\n\n1. **Intake & Initialization:**\n   The developer creates a new task:\n   `alvi task \"Implement Stripe Checkout\"`\n2. **Context & Planning (Agent):**\n   The AI agent reads the current task context via MCP (`alvi://status`) and generates an implementation plan (`alvi plan`). It then transitions the task:\n   `alvi transition plan`\n3. **Implementation:**\n   The agent writes code, taking care to check its blast radius using `alvi check`. If it breaks an architectural boundary, the Gate Engine blocks it.\n   `alvi transition implement`\n4. **Verification & Review:**\n   The agent finishes the code and runs the internal autofixer (`alvi fix`). The developer runs an AI-aware review over the diff (`alvi review`).\n   `alvi transition review`\n5. **Git Push (Guarded):**\n   The agent tries to push the code, but `alvi git push` halts the operation and demands explicit human approval before the remote is mutated.\n\n---\n\n## Troubleshooting & Common Errors\n\n### `Error [ERR_REQUIRE_ESM]` or `require is not defined`\n**Cause:** Alvi is distributed as an ES Module. You might have tried to `require()` Alvi from a CommonJS script.\n**Solution:** Ensure your `package.json` contains `\"type\": \"module\"` or use a dynamic `import()` to consume Alvi programmatically.\n\n### `Architecture Boundary Violation`\n**Cause:** You (or your AI agent) imported a module that is explicitly denied in `alvi.yml` (e.g. the UI layer attempting to import directly from the Database layer).\n**Solution:** Refactor the code to use the correct intermediary interface (e.g., an API route) and run `alvi check` again.\n\n### `Scope Violation: Too many files changed`\n**Cause:** Your AI agent modified more files than the `maxFiles` limit defined in `alvi.yml` -> `scopeGuard`.\n**Solution:** Break the task into smaller, incremental PRs. This prevents AI hallucination spirals from destroying unrelated parts of the codebase.\n\n### `alvi check` returns `{}`\n**Cause:** No files were changed in the git tree, or the specific gates are disabled in `alvi.yml`.\n**Solution:** `alvi check` analyzes the `git diff`. Ensure you have uncommitted changes or staged changes, and verify `enabled: true` for the gates in `alvi.yml`.\n\n---\n\n## Development\n\n```bash\nnpm install\nnpm run build\nnpm test\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}