{"_id":"@aegis-cli/infra-sdk","_rev":"2-d5315e87155e41dab1efdd367772b83a","name":"@aegis-cli/infra-sdk","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@aegis-cli/infra-sdk","version":"0.1.0","license":"MIT","_id":"@aegis-cli/infra-sdk@0.1.0","maintainers":[{"name":"rtmx","email":"dev@rtmx.ai"}],"dist":{"shasum":"fbac1e22073f25f4e6adf9bfea0e74b91d5c0d4a","tarball":"https://registry.npmjs.org/@aegis-cli/infra-sdk/-/infra-sdk-0.1.0.tgz","fileCount":141,"integrity":"sha512-sx4NvGI0NJjg6h9rOEOCsT1rn0aI9BpJ3mIIzXSkCXJ9xk5lThAL4/DAGWq0QODixR6uccvjVmWYrb3Bzqh1sg==","signatures":[{"sig":"MEUCIQDzl6VawW5vqebZFE7SoLIJz7/lQc3ZJg1OuYdic8dWGwIgbUyGk80Y3AtFh3qkDhBGfOhQcsGN3BRYqjjVRYLcvh4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":311742},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=22.0.0"},"exports":{".":"./dist/index.js","./ports":"./dist/domain/ports.js","./domain":"./dist/domain/types.js","./protocol":"./dist/protocol/events.js"},"gitHead":"c2b6b6491214834f359c6da9cf8b38e1d52702d2","scripts":{"lint":"eslint src/","test":"vitest run","build":"tsc","format":"prettier --check 'src/**/*.ts'","prepare":"npm run build","lint:fix":"eslint src/ --fix","precommit":"npm run format && npm run lint && npm run build && npm run test:unit","test:unit":"vitest run src/","format:fix":"prettier --write 'src/**/*.ts'"},"_npmUser":{"name":"rtmx","email":"dev@rtmx.ai"},"_npmVersion":"10.5.0","description":"Plugin SDK for aegis-cli infrastructure backends","directories":{},"_nodeVersion":"18.20.1","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","eslint":"^9.0.0","vitest":"^3.0.0","prettier":"^3.0.0","typescript":"^5.5.0","@types/node":"^22.0.0","@typescript-eslint/parser":"^8.0.0","@typescript-eslint/eslint-plugin":"^8.0.0"},"_npmOperationalInternal":{"tmp":"tmp/infra-sdk_0.1.0_1774487926577_0.1919134275808707","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@aegis-cli/infra-sdk","version":"0.2.0","description":"Plugin SDK for aegis-cli infrastructure backends","license":"MIT","repository":{"type":"git","url":"git+https://github.com/rtmx-ai/aegis-infra-sdk.git"},"type":"module","main":"dist/index.js","types":"dist/index.d.ts","bin":{"aegis-ci-check":"dist/security/ci-compliance-cli.js"},"exports":{".":"./dist/index.js","./domain":"./dist/domain/types.js","./ports":"./dist/domain/ports.js","./protocol":"./dist/protocol/events.js"},"scripts":{"build":"tsc","prepare":"npm run build","lint":"eslint src/","lint:fix":"eslint src/ --fix","format":"prettier --check 'src/**/*.ts'","format:fix":"prettier --write 'src/**/*.ts'","test":"vitest run","test:unit":"vitest run src/","precommit":"npm run format && npm run lint && npm run build && npm run test:unit"},"devDependencies":{"@types/node":"^22.0.0","@typescript-eslint/eslint-plugin":"^8.0.0","@typescript-eslint/parser":"^8.0.0","eslint":"^9.0.0","prettier":"^3.0.0","tsx":"^4.21.0","typescript":"^5.5.0","vitest":"^3.0.0"},"engines":{"node":">=22.0.0"},"gitHead":"b8960e2240c142a9aaadf99f90450cdb527be41a","_id":"@aegis-cli/infra-sdk@0.2.0","bugs":{"url":"https://github.com/rtmx-ai/aegis-infra-sdk/issues"},"homepage":"https://github.com/rtmx-ai/aegis-infra-sdk#readme","_nodeVersion":"22.22.1","_npmVersion":"11.12.0","dist":{"integrity":"sha512-ekEWZsuSB1MpvnM5n0bBtqT0x1iJLPqFdfx4ni7LgyaN7ztCRclOqy83YrzFsEQqOFJ11pOPMh3qKKBpsO1QWg==","shasum":"cb0e64207e953f4fde29cd4dfdda6dd001f6e47b","tarball":"https://registry.npmjs.org/@aegis-cli/infra-sdk/-/infra-sdk-0.2.0.tgz","fileCount":200,"unpackedSize":432348,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aegis-cli%2finfra-sdk@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGJhh5hTM/VRgvdynaovBquf7zYflZl8k8z/KJbBrkpwAiBcn3Z3RoU++dQbbzU4ye0IT1S47rK437ofrXQyX8jVJw=="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:2546a6ff-2bb5-48af-9cc7-2e60bbf24069"}},"directories":{},"maintainers":[{"name":"rtmx","email":"dev@rtmx.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/infra-sdk_0.2.0_1774502965575_0.013685595846318455"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-26T01:18:46.441Z","modified":"2026-03-26T05:29:26.046Z","0.1.0":"2026-03-26T01:18:46.722Z","0.2.0":"2026-03-26T05:29:25.756Z"},"license":"MIT","description":"Plugin SDK for aegis-cli infrastructure backends","maintainers":[{"name":"rtmx","email":"dev@rtmx.ai"}],"readme":"# @aegis-cli/infra-sdk\n\n[](https://github.com/rtmx-ai/aegis-infra-sdk/actions/workflows/ci.yml)\n[](LICENSE)\n[](.nvmrc)\n[](PLUGIN_GUIDE.md)\n\nPlugin SDK for aegis-cli infrastructure backends. This package extracts the generic plugin infrastructure (CLI argument parsing, lifecycle state machine, JSON-line protocol emission, health check aggregation, and local state management) from concrete IaC deployer plugins so that each new cloud-provider plugin implements only its domain-specific logic: resource definitions, health checks, and API client calls.\n\n## Architecture\n\n```mermaid\ngraph TD\n A[aegis-cli] -->|spawns subprocess| B[\"Plugin Binary
(e.g., gcp-cui-gemini)\"]\n B -->|uses| C[\"@aegis-cli/infra-sdk\"]\n C -->|provides| D[CLI Entrypoint]\n C -->|provides| E[Lifecycle State Machine]\n C -->|provides| F[Protocol Emitter]\n C -->|provides| G[Health Aggregator]\n C -->|provides| H[Local State Mgmt]\n B -->|implements| I[CspClient port]\n B -->|implements| J[IaCEngine port]\n B -->|implements| K[HealthChecker port]\n\n style C fill:#e0e0ff,stroke:#333\n style B fill:#ffe0e0,stroke:#333\n style A fill:#e0ffe0,stroke:#333\n```\n\nThe SDK sits between aegis-cli and the plugin implementation. aegis-cli spawns the plugin binary as a subprocess and communicates over a JSON-line stdout protocol (aegis-infra/v1). The plugin author only implements three port interfaces -- the SDK handles all CLI parsing, protocol emission, lifecycle orchestration, and error handling.\n\n## Quick Start\n\n```typescript\n#!/usr/bin/env node\nimport { createPluginCli } from \"@aegis-cli/infra-sdk\";\nimport type { CspClient, IaCEngine, HealthChecker } from \"@aegis-cli/infra-sdk\";\n\n// Implement the three port interfaces for your cloud provider\nconst myCspClient: CspClient = { /* ... */ };\nconst myEngine: IaCEngine = { /* ... */ };\nconst myHealthChecker: HealthChecker = { /* ... */ };\n\ncreatePluginCli({\n name: \"my-cloud-plugin\",\n version: \"0.1.0\",\n description: \"Provisions resources on MyCloud\",\n credentials: [\"mycloud-token\"],\n inputs: [\n { name: \"project_id\", type: \"string\", required: true },\n { name: \"region\", type: \"string\", default: \"us-east-1\" },\n ],\n outputs: [\"endpoint_url\", \"resource_id\"],\n cspClient: myCspClient,\n engine: myEngine,\n healthChecker: myHealthChecker,\n requiredApis: [\"compute.mycloud.com\", \"storage.mycloud.com\"],\n});\n```\n\nThat is the entire plugin entrypoint. The SDK handles:\n- Parsing `process.argv` for subcommand and `--input` JSON\n- Validating required inputs against the declared schema\n- Running preflight checks via your `CspClient`\n- Enabling required APIs and polling until active\n- Dispatching to your `IaCEngine` for preview/up/destroy\n- Running health checks and aggregating results\n- Emitting all protocol events as newline-delimited JSON on stdout\n- Catching errors and emitting structured error results\n\n## API Reference\n\n### `createPluginCli(config: PluginConfig): Promise`\n\nThe single public API. Call this from your plugin's entrypoint. It reads `process.argv`, dispatches the subcommand, and handles all protocol emission.\n\n### `PluginConfig`\n\n```typescript\ninterface PluginConfig {\n name: string; // Plugin name (used in manifest and state dir)\n version: string; // Semver version string\n description: string; // Human-readable description\n credentials: string[]; // Required credential types (e.g., [\"gcp-adc\"])\n inputs: InputField[]; // Declared input schema\n outputs: string[]; // Declared output field names\n cspClient: CspClient; // Cloud provider API client implementation\n engine: IaCEngine; // IaC engine implementation\n healthChecker: HealthChecker; // Health check implementation\n requiredApis: string[]; // APIs to enable before provisioning\n stateDir?: string; // Custom state directory (default: ~/.aegis/state/{name}/)\n apiPollIntervalMs?: number; // API poll interval (default: 5000)\n apiPollTimeoutMs?: number; // API poll timeout (default: 120000)\n}\n```\n\n### `CspClient` (port interface)\n\n```typescript\ninterface CspClient {\n validateCredentials(): Promise;\n checkAccess(config: InfraConfig): Promise;\n getApiState(config: InfraConfig, api: string): Promise<\"ENABLED\" | \"DISABLED\">;\n enableApi(config: InfraConfig, api: string): Promise;\n}\n```\n\n### `IaCEngine` (port interface)\n\n```typescript\ninterface IaCEngine {\n preview(config: InfraConfig): Promise;\n up(config: InfraConfig): Promise;\n destroy(config: InfraConfig): Promise;\n getOutputs(config: InfraConfig): Promise;\n}\n```\n\n### `HealthChecker` (port interface)\n\n```typescript\ninterface HealthChecker {\n checkAll(config: InfraConfig, outputs?: BoundaryOutput): Promise;\n}\n```\n\n### `InfraConfig`\n\n```typescript\ninterface InfraConfig {\n readonly params: Record; // Parsed --input JSON\n}\n```\n\n### `BoundaryOutput`\n\n```typescript\ntype BoundaryOutput = Record; // Plugin-defined output keys\n```\n\n## Development Commands\n\n```bash\n# Install dependencies\nnvm use && npm install\n\n# Build\nnpm run build\n\n# Lint and format\nnpm run lint\nnpm run lint:fix\nnpm run format\nnpm run format:fix\n\n# Test\nnpm test # all tests\nnpm run test:unit # unit tests only\n\n# Run a single test file\nnpx vitest run src/cli/__tests__/args.test.ts\n\n# Run tests matching a pattern\nnpx vitest run -t \"parseSubcommand\"\n```\n\n## Project Structure\n\n```\nsrc/\n cli/\n entrypoint.ts - createPluginCli() (the single public API)\n args.ts - parseSubcommand, parseInput, extractInput, requireConfirmDestroy\n lifecycle/\n state-machine.ts - runPreflight, enableApis, checkApiReadiness, pollApiEnabled\n types.ts - InitState enum, InitContext interface\n protocol/\n emitter.ts - StdoutEmitter class\n events.ts - ProtocolEvent union type\n manifest.ts - buildManifest() from PluginConfig\n domain/\n types.ts - InfraConfig, BoundaryOutput, HealthCheck, InputField, etc.\n ports.ts - CspClient, IaCEngine, HealthChecker interfaces\n health/\n aggregator.ts - aggregateChecks()\n state/\n local.ts - resolveStateDir(), ensureStateDir(), buildStackName()\n index.ts - re-export public API\n```\n","readmeFilename":"README.md","homepage":"https://github.com/rtmx-ai/aegis-infra-sdk#readme","repository":{"type":"git","url":"git+https://github.com/rtmx-ai/aegis-infra-sdk.git"},"bugs":{"url":"https://github.com/rtmx-ai/aegis-infra-sdk/issues"}}