|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +**@codifycli/schemas** is the central contract library for the Codify ecosystem. It defines: |
| 8 | +- JSON Schemas for all IPC message formats between Codify CLI core and plugins |
| 9 | +- TypeScript type definitions for type-safe message handling |
| 10 | +- Configuration file schemas for Codify projects and resources |
| 11 | +- Schema store integration for IDE autocomplete/validation |
| 12 | + |
| 13 | +Codify is an infrastructure-as-code tool with a plugin-based architecture where the CLI core orchestrates resource management through plugins that communicate via IPC messages validated by this package. |
| 14 | + |
| 15 | +## Common Commands |
| 16 | + |
| 17 | +### Testing |
| 18 | +```bash |
| 19 | +npm test # Run all tests with vitest |
| 20 | +``` |
| 21 | + |
| 22 | +### Building |
| 23 | +```bash |
| 24 | +npm run prepublishOnly # Compile TypeScript and prepare for publishing (runs `tsc`) |
| 25 | +``` |
| 26 | + |
| 27 | +### Scripts |
| 28 | +```bash |
| 29 | +npm run script:upload-plugin # Upload resource schemas to Supabase registry |
| 30 | +``` |
| 31 | + |
| 32 | +## Architecture |
| 33 | + |
| 34 | +### Plugin Communication Protocol |
| 35 | + |
| 36 | +Codify uses a request/response IPC protocol where: |
| 37 | +- **Core CLI** sends messages to plugins with commands like `initialize`, `validate`, `plan`, `apply`, `import` |
| 38 | +- **Plugins** respond with structured data validated against response schemas |
| 39 | +- **Two message wrapper versions**: V1 (basic) and V2 (adds `requestId` for correlation) |
| 40 | + |
| 41 | +### Directory Structure |
| 42 | + |
| 43 | +``` |
| 44 | +src/ |
| 45 | +├── messages/ # Request/response schemas for each IPC message type |
| 46 | +│ ├── *-request-data-schema.json |
| 47 | +│ ├── *-response-data-schema.json |
| 48 | +│ └── commands.ts # MessageCmd enum |
| 49 | +├── types/ # TypeScript interfaces and enums |
| 50 | +│ └── index.ts # All exported types |
| 51 | +├── schemastore/ # IDE integration schema |
| 52 | +│ └── codify-schema.json # Combined schema for autocomplete (2,462 lines) |
| 53 | +├── config-file-schema.json # Top-level config file format |
| 54 | +├── project-schema.json # "project" block definition |
| 55 | +├── resource-schema.json # Base resource configuration |
| 56 | +├── ipc-message-schema.json # V1 message wrapper |
| 57 | +├── ipc-message-schema-v2.json # V2 message wrapper (adds requestId) |
| 58 | +└── index.ts # Main exports |
| 59 | +``` |
| 60 | + |
| 61 | +### Key Schemas |
| 62 | + |
| 63 | +**Configuration Schemas:** |
| 64 | +- `config-file-schema.json` - Top-level array of config blocks with `type` field |
| 65 | +- `project-schema.json` - Special "project" block with version, plugins, description |
| 66 | +- `resource-schema.json` - Base schema for all resources (type, name, dependsOn, os) |
| 67 | + |
| 68 | +**Message Schemas (src/messages/):** |
| 69 | +- Initialize: Plugin startup, capability discovery |
| 70 | +- Validate: Resource configuration validation |
| 71 | +- Plan: Calculate changes (create/destroy/modify/recreate/noop) |
| 72 | +- Apply: Execute planned changes |
| 73 | +- Import: Discover existing system resources |
| 74 | +- Match: Find matching resource in array |
| 75 | +- Get Resource Info: Query resource metadata |
| 76 | +- Command Request/Response: Execute commands (sudo/interactive) |
| 77 | +- Set Verbosity, Press Key to Continue, Error Response, Empty Response |
| 78 | + |
| 79 | +**Schema Store:** |
| 80 | +- `codify-schema.json` - Comprehensive IDE integration schema combining all resource types |
| 81 | + |
| 82 | +### TypeScript Integration |
| 83 | + |
| 84 | +- Uses `resolveJsonModule: true` to import JSON schemas as typed modules |
| 85 | +- All JSON schemas are copied to `dist/` during build |
| 86 | +- Types and schemas are co-located for easier maintenance |
| 87 | +- Strict mode enabled with full null checking |
| 88 | + |
| 89 | +### Build Process |
| 90 | + |
| 91 | +1. TypeScript compiles `src/` → `dist/` |
| 92 | +2. JSON schemas copied to `dist/` |
| 93 | +3. Type declarations (`.d.ts`) generated |
| 94 | +4. Source maps created |
| 95 | +5. Package published as ES modules |
| 96 | + |
| 97 | +## Development Workflow |
| 98 | + |
| 99 | +### Adding a New Message Type |
| 100 | + |
| 101 | +1. Create schemas in `src/messages/`: |
| 102 | + - `[name]-request-data-schema.json` |
| 103 | + - `[name]-response-data-schema.json` |
| 104 | +2. Add TypeScript types in `src/types/index.ts`: |
| 105 | + - `[Name]RequestData` interface |
| 106 | + - `[Name]ResponseData` interface |
| 107 | +3. Update `MessageCmd` enum if needed in `src/messages/commands.ts` |
| 108 | +4. Import and export schemas in `src/index.ts` |
| 109 | +5. Create test: `src/messages/[name]-request-data-schema.test.ts` |
| 110 | +6. Run tests and build |
| 111 | + |
| 112 | +### Testing Pattern |
| 113 | + |
| 114 | +Each schema has a `.test.ts` file that: |
| 115 | +- Uses AJV in strict mode to compile the schema |
| 116 | +- Tests valid inputs return `true` |
| 117 | +- Tests invalid inputs return `false` with appropriate errors |
| 118 | +- Validates naming conventions and patterns |
| 119 | + |
| 120 | +**Configuration:** Tests use `tsconfig.test.json` which disables `strictNullChecks` for testing flexibility. |
| 121 | + |
| 122 | +### Resource Schema Management |
| 123 | + |
| 124 | +Resource schemas are defined in `src/schemastore/codify-schema.json` and uploaded to Supabase registry via `scripts/upload-resources.ts`. This script: |
| 125 | +1. Upserts "default" plugin |
| 126 | +2. Extracts each resource from the schema store |
| 127 | +3. Upserts into `registry_resources` table |
| 128 | +4. Extracts parameters and upserts into `registry_resource_parameters` table |
| 129 | + |
| 130 | +Requires environment variables: `SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY` |
| 131 | + |
| 132 | +## Key Concepts |
| 133 | + |
| 134 | +### Stateful vs Stateless Resources |
| 135 | +- **Stateful**: CLI tracks state, plugins receive both desired config and current state |
| 136 | +- **Stateless**: Plugins determine current state themselves, receive only desired config |
| 137 | + |
| 138 | +### Resource Dependencies |
| 139 | +Resources declare dependencies via `dependsOn` array containing resource identifiers. |
| 140 | + |
| 141 | +### Operating System Support |
| 142 | +Resources specify OS compatibility: |
| 143 | +- `ResourceOs` enum: LINUX | MACOS | WINDOWS |
| 144 | +- `LinuxDistro` enum: Comprehensive distro list (debian, ubuntu, fedora, arch, alpine, etc.) |
| 145 | +- `OS` enum: Node.js platform values (Darwin | Linux | Windows_NT) |
| 146 | + |
| 147 | +### Sensitive Parameters |
| 148 | +Parameters can be marked `isSensitive: true` for secure handling by the CLI. |
| 149 | + |
| 150 | +### Plan Parameter Changes |
| 151 | +Plans track changes at parameter level: |
| 152 | +- `ParameterOperation`: ADD | REMOVE | MODIFY | NOOP |
| 153 | +- Each parameter change includes old/new values |
| 154 | + |
| 155 | +## Important Notes |
| 156 | + |
| 157 | +- **Breaking Changes**: This package is critical infrastructure - maintain backward compatibility |
| 158 | +- **Validation**: All schemas must have corresponding tests |
| 159 | +- **Documentation**: Include `$comment` fields with documentation URLs in schemas |
| 160 | +- **Version Patterns**: Use semantic versioning regex: `^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$` |
| 161 | +- **Type Patterns**: Resource types use pattern `^[a-zA-Z][\w-]+$` (alphanumeric start, then alphanumeric/underscore/hyphen) |
0 commit comments