@crossdelta/platform-sdk 0.17.4 → 0.18.0

package/CHANGELOG.md

@@ -0,0 +1,407 @@
+# Changelog
+
+All notable changes to `@crossdelta/platform-sdk` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.18.0] - 2025-12-22
+
+### Changed
+- **CLI Architecture** - Reorganized internal structure for better maintainability
+  - Moved `services/` to `core/` (ai, ast, bun, env, events, filesystem, etc.)
+  - AI setup now under `setup/ai/` subcommand structure
+  - Centralized CLI config in `config/index.ts`
+  - Unified help formatting with declarative formatter
+
+### Performance
+- **Shell Completion** - Complete overhaul of completion system
+  - Workspace-local cache (`node_modules/.cache/pf/`) instead of dynamic extraction
+  - Shell scripts read from cache file for instant completions
+  - Fast event name scanner without Zod validation overhead
+  - `pf event publish <TAB>` now responds in <50ms (was 200-500ms)
+  - Auto-regenerate cache on workspace changes
+  - See `docs/completion-performance.md` for technical details
+
+### Fixed
+- **Dev Mode Exit Codes** - Simplified exit code handling
+  - Exit codes 0, 1, 130 (SIGINT), 143 (SIGTERM) treated as normal exits
+  - Cleaner shutdown without spurious error messages
+
+### Removed
+- Dead code cleanup (`regenerate.ts`, unused completion extractors)
+- Decorative ASCII header blocks (per conventions)
+- Duplicated `KNOWN_COMMAND_DESCRIPTIONS` constant
+
+## [0.17.5] - 2025-12-21
+
+### Fixed
+- **npm Publishing** - README now correctly uploaded in publish workflow
+  - Fixed GitHub Actions workflow to upload README.md, CHANGELOG.md, LICENSE, etc.
+  - Previously only `dist/` was uploaded, causing missing README on npm
+  - Now uploads all files needed for npm package (bin, schemas, logo, install.sh)
+
+## [0.17.3] - 2025-12-21
+
+### Fixed
+- **Dev Mode Shutdown** - `pf dev` now exits cleanly with single CTRL+C after service crash
+  - File watchers are properly closed on shutdown to release event loop
+  - No more "hanging" process requiring second CTRL+C
+  - Graceful shutdown sequence: Services → NATS → Watchers → Exit
+
+### Removed
+- **Unused Code** - Removed `promptCompletionSetup()` function
+  - Function was never called, dead code from initial completion feature
+  - Autocompletion still works via explicit `pf setup --completion`
+  - Removed misleading README statement about "first-run prompt"
+
+## [0.17.2] - 2024-12-21
+
+### Fixed
+- **Event Handler Naming** - Fixed documentation to match CLI implementation
+  - All examples now use singular handler names (`order-created.handler.ts` not `orders-created.handler.ts`)
+  - Updated `service.md` and `nest.md` AI generation guidelines
+  - Fixed test mock data to use singular event types (`order.created` not `orders.created`)
+  - Resolved issue where AI generated plural handlers but CLI generated singular handlers, causing duplicate files
+  - Handler files now consistently match event types in kebab-case (e.g., `order.created` → `order-created.handler.ts`)
+
+## [0.17.0] - 2025-12-21
+
+### Added
+- **Root `tsconfig.json` Generation** - `pf new workspace` now creates a modern TypeScript config
+  - TypeScript 5+ best practices (`verbatimModuleSyntax`, `allowImportingTsExtensions`)
+  - Strict type checking with additional safety (`noFallthroughCasesInSwitch`)
+  - Flexible base config - packages can override with their specific needs
+  - Prevents warnings from test workspaces in `tmp/` directory
+
+### Changed
+- **TypeScript Configuration** - Modern, less restrictive root config
+  - `noEmit: true` - root doesn't emit, packages handle their own compilation
+  - Removed decorators from root (NestJS packages define themselves)
+  - Added `tmp/` to exclude list for test workspaces
+
+## [0.16.6] - 2025-12-21
+
+### Performance
+- **Bundle Size Reduction**: 90% smaller package size
+  - Before: 3.15MB unpacked (2.9MB cli.js)
+  - After: 321KB unpacked (114KB cli.js)
+  - Changed esbuild config to use `packages: 'external'` instead of explicit external list
+  - All node_modules dependencies now excluded from bundle
+  - Only source code is bundled, dependencies loaded at runtime
+
+### Changed
+- Removed explicit `esbuild.external` list from package.json (no longer needed)
+
+## [0.16.5] - 2025-12-21
+
+### Fixed
+- **Naming Convention Enforcement**: All documentation examples now use singular event types
+  - Event types: `order.created` not `orders.created` (singular - one fact)
+  - Schemas: `OrderCreatedSchema` not `OrdersCreatedSchema` (singular - one instance)
+  - Data types: `OrderCreatedData` not `OrdersCreatedData` (singular - one instance)
+  - Fixed 22+ examples across all generator docs
+- **CLI Generation Consistency**: Contract names now properly pluralized
+  - Contracts: `OrdersCreatedContract` (plural - category of events)
+  - Aligns with documentation and naming convention rules
+
+### Changed
+- **Documentation Cleanup**: Removed duplicate sections and improved clarity
+  - Consolidated Stream Architecture section
+  - Clarified singular/plural naming rules with prominent examples
+  - Added final rule table for Schema/Type/Contract/Stream naming
+
+## [0.16.2] - 2025-12-21
+
+### Added
+- **Environment Validation Scaffold**: Automatic `src/config/env.ts` creation
+  - Uses Zod v4 with `safeParse()` + explicit error handling
+  - Export validated `env` object for type-safe access
+  - Better error messages via `result.error.format()`
+  - Process exits with code 1 on validation failure
+- **Zod Dependency**: Auto-added to Hono service dependencies (`^4.0.0`)
+
+### Changed
+- **Import Order Enforcement**: Critical import sequence now documented
+  1. Environment validation (`./config/env`) - First to validate before any code runs
+  2. Telemetry (`@crossdelta/telemetry`) - Second to patch modules before they load
+  3. All other imports follow
+- **Clean Documentation**: Removed redundant comments from code examples
+  - Import order explained in section header, not inline comments
+  - Self-documenting code pattern
+
+### Fixed
+- **Dev Mode UX**: `pf dev` no longer exits when services crash
+  - Removed `process.exit()` call in process manager
+  - Context-aware messages based on exit code (0 vs non-zero)
+  - Auto-restart on file save preserved
+
+### Internal
+- Centralized event naming logic in `eventTypeToNames()` (8 return fields)
+- Refactored 5 CLI services to use centralized naming
+- Template build process includes new `src/config/` directory
+
+### Documentation
+- Updated `hono-bun.md` and `hono-node.md` with env validation examples
+- Added import order requirements for AI code generation
+- Environment validation section with Zod v4 best practices
+
+### Breaking Changes
+- Hono services now require `import './config/env'` before telemetry
+- Environment validation runs at startup (fails fast on invalid env)
+
+---
+
+## [0.13.0] - 2025-12-20
+
+### Added
+- **Domain-Grouped Event Structure**: Events organized by domain (`events/<domain>/<event>.ts`)
+  - Scalable for 100+ events (e.g., `events/orders/created.ts`, `events/customers/updated.ts`)
+  - Three-layer export system: domain index → events index → main index
+  - Auto-activation of exports on first event creation
+- **Stream Policies**: Business rules for JetStream retention/storage in contracts package
+  - `STREAM_POLICIES` - Stream-specific overrides (ORDERS: 14d, CUSTOMERS: 30d)
+  - `DEFAULT_POLICY` - Default retention (7 days, file storage, 1 replica)
+  - Time/size constants for readability (`DAYS`, `MB`)
+- **Generic Stream Deployment**: `@crossdelta/infrastructure` now exports `deployStreams()`
+  - Separates logic (library) from data (workspace)
+  - Workspaces inject contracts + policies via thin wrapper
+  - Replaces workspace-specific stream deployment code
+- **Workspace Templates**: Added domain structure templates
+  - `src/events/index.ts` - Event contracts index with helpful comments
+  - `src/stream-policies.ts.hbs` - Stream policy template
+  - Templates synced via `bun run sync-templates`
+- **Ephemeral Stream Auto-Creation**: `pf dev` now auto-creates streams from contracts
+  - Scans `packages/contracts/src/index.ts` for contracts with `channel.stream` metadata
+  - Creates ephemeral streams (memory storage, 1h retention) before services start
+  - No manual stream setup needed in development
+  - Services can immediately consume from streams on startup
+- **Environment Validation Pattern**: Documented fail-fast config validation for Hono
+  - Separate `src/config/env.ts` with Zod schema
+  - Uses `safeParse()` + `process.exit(1)` pattern (Bun --hot compatible)
+  - Must import in `src/index.ts` for validation to execute
+  - Ensures Turbo TUI shows red X on validation failure (like NestJS)
+  - Explicit rule: DO NOT include `SERVICE_NAME_PORT` in env schema (handled by template)
+- **Infrastructure Directory**: `infra/services/.gitkeep` in workspace template
+  - Ensures directory exists for `pf new` to create service configs
+  - Fixes issue where empty `.env.local` was generated
+
+### Changed
+- **BREAKING: Handler File Extension**: `*.event.ts` → `*.handler.ts`
+  - More semantically correct (files contain handlers, not event definitions)
+  - Event definitions live in `packages/contracts/src/events/`
+  - Handlers live in `services/*/src/events/`
+  - Discover pattern: `./src/events/**/*.handler.ts`
+  - **Migration**: Rename `*.event.ts` → `*.handler.ts` in your services
+- **Contracts Structure**: Migrated from flat to domain-grouped
+  - Before: `events/orders-created.ts`
+  - After: `events/orders/created.ts` + `events/orders/index.ts`
+- **CLI Event Generation**: Updated to create domain structure automatically
+  - `pf event add order.created` → creates `events/orders/created.ts`
+  - Auto-creates domain index files
+  - Three-phase export management (domain → events → main)
+- **Service Generation**: Updated to use new `consumeJetStreams` API
+  - Removed manual stream creation (`ensureJetStreamStream`)
+  - Services consume from streams, never create them
+  - Import changed: `consumeJetStreams` (plural, new API)
+- **Index Management**: Fixed duplicate export detection
+  - Now checks actual exports, not just text in comments
+  - `lines.some(line => line.trim() === exportLine)` for precision
+- **Infrastructure**: Moved stream deployment logic from workspace to library
+  - Generic logic: `@crossdelta/infrastructure/lib/helpers/deploy-streams.ts`
+  - Workspace: `infra/streams/index.ts` (thin wrapper)
+  - Policies: `packages/contracts/src/stream-policies.ts` (business rules)
+- **Hono Template Restoration**: Restored `src/index.ts.hbs` template
+  - Was accidentally deleted in commit 76dcc90
+  - Now properly generates entry point with correct port configuration
+  - Uses `generateHonoIndexTs()` helper instead of regex replacement
+- **NestJS Port Configuration**: Removed `process.env.PORT ||` fallback
+  - Services now use only their specific env var (e.g., `MY_SERVICE_PORT`)
+  - Prevents port conflicts in multi-service development
+  - Consistent with Hono template pattern
+- **Stream Architecture Documentation**: Clarified ephemeral vs persistent streams
+  - Development: `pf dev` auto-creates ephemeral streams from contracts
+  - Production: Pulumi materializes persistent streams with retention policies
+  - Services NEVER create streams (in any environment)
+  - Updated all READMEs to reflect correct flow
+- **AI Generation Rules**: Consolidated and simplified documentation
+  - Removed redundant rules from framework-specific MD files
+  - Core rules in `ai-prompt-builder.ts`: AI can modify entry points but must preserve port line
+  - Added explicit "DO NOT generate `infra/services/*.ts`" rule (CLI handles this)
+  - Clarified naming convention: Events singular (domain.created), Streams PLURAL (DOMAINS)
+- **NestJS Templates**: Removed `ensureJetStreams` references
+  - `events.service.ts.hbs` now uses only `consumeJetStreams`
+  - Updated comments to reflect stream auto-creation architecture
+  - Consistent with Hono templates
+
+### Fixed
+- Export detection in `index-manager.ts` no longer matches commented examples
+- Handler service now uses correct `consumeJetStreams` API
+- Contract path resolution for domain structure
+- Template variable substitution (`{{workspaceName}}` in stream-policies.ts.hbs)
+- **Environment Validation Import**: Added explicit requirement to import `env` in entry point
+  - Without import, validation code exists but never executes
+  - AI was generating `src/config/env.ts` but not importing it
+  - Now documented with CRITICAL warnings in both `hono-bun.md` and `hono-node.md`
+- **Port Configuration in Env Schema**: Removed confusing PORT validation examples
+  - Port is read from template-generated env var, not from env schema
+  - Prevents AI from duplicating port config in validation
+  - Clear comments: "DO NOT include SERVICE_NAME_PORT here"
+- **Discovery Service**: Fixed `ensureJetStreams` code generation
+  - Removed stream creation code from `generateStreamConfigCode()`
+  - Only generates `consumeJetStreams` with correct plural stream names
+  - Added architecture comments explaining stream creation responsibility
+- **Legacy Content Cleanup**: Removed contradictory sections from documentation
+  - Deleted "Benefits" sections that referenced removed patterns (env.PORT)
+  - Removed duplicate/conflicting CRITICAL rules from hono-node.md
+  - Consistent CRITICAL rules across all framework docs
+
+### Documentation
+- Updated contracts README with domain structure examples
+- Updated workspace templates to reflect new structure
+- Added stream architecture documentation (conceptual vs. architectural)
+- Clarified separation: contracts define "what", infrastructure defines "how"
+- Removed legacy API references from all public package READMEs
+- **Stream Naming Convention**: Extensively documented singular vs plural pattern
+  - Event types: singular (domain.created, order.created)
+  - Stream names: PLURAL (DOMAINS, ORDERS)
+  - Added "Merksatz" mnemonic: "Events sind singular. Streams sind plural."
+  - Examples in `consumeJetStreams` showing correct/incorrect usage
+- **Port Configuration**: Clarified SERVICE_NAME_PORT pattern
+  - Convert service name to SCREAMING_SNAKE_CASE + `_PORT`
+  - DO NOT use generic `PORT` - causes conflicts
+  - Port assigned by CLI, written to `infra/services/*.ts`
+  - Service reads from specific env var, never hardcoded
+- **Environment Validation**: Two-step pattern documented
+  - Step 1: Create `src/config/env.ts` with validation
+  - Step 2: Import in `src/index.ts` (CRITICAL - validation never runs without this!)
+  - Clear examples showing crash behavior and exit codes
+
+### Internal
+- **Code Organization**: Extracted pure functions from event command
+  - `format-consumers.ts` - Format consumer list for display
+  - `render-events-table.ts` - Render events table with schemas
+  - Improved testability and separation of concerns
+- **Dev Command**: Integrated stream auto-creation into development workflow
+  - `startNatsInfra()` now returns boolean indicating success
+  - `ensureDevStreams()` called after NATS starts
+  - Uses `jiti` for TypeScript contract imports
+  - Silent failure with helpful message if stream creation fails
+
+### Removed
+- **Legacy API**: `consumeJetStreamEvents()` removed from public documentation
+  - Use `consumeJetStreams()` instead (plural, supports multiple streams)
+
+### Migration Guide
+1. **Rename handler files**: `*.event.ts` → `*.handler.ts`
+   ```bash
+   find services -name "*.event.ts" -exec bash -c 'mv "$0" "${0%.event.ts}.handler.ts"' {} \;
+   ```
+2. **Update discover patterns**: Change `'./src/events/**/*.event.ts'` → `'./src/events/**/*.handler.ts'`
+3. **Update contract imports**: Adjust for domain structure if using contracts package
+
+### Dependencies
+- `@crossdelta/infrastructure` added to contracts `package.json`
+- **BREAKING: Handler File Extension**: `*.event.ts` → `*.handler.ts`
+  - More semantically correct (files contain handlers, not event definitions)
+  - Event definitions live in `packages/contracts/src/events/`
+  - Handlers live in `services/*/src/events/`
+  - Discover pattern: `./src/events/**/*.handler.ts`
+  - **Migration**: Rename `*.event.ts` → `*.handler.ts` in your services
+- **Contracts Structure**: Migrated from flat to domain-grouped
+  - Before: `events/orders-created.ts`
+  - After: `events/orders/created.ts` + `events/orders/index.ts`
+- **CLI Event Generation**: Updated to create domain structure automatically
+  - `pf event add order.created` → creates `events/orders/created.ts`
+  - Auto-creates domain index files
+  - Three-phase export management (domain → events → main)
+- **Service Generation**: Updated to use new `consumeJetStreams` API
+  - Removed manual stream creation (`ensureJetStreamStream`)
+  - Services consume from streams, never create them
+  - Import changed: `consumeJetStreams` (plural, new API)
+- **Index Management**: Fixed duplicate export detection
+  - Now checks actual exports, not just text in comments
+  - `lines.some(line => line.trim() === exportLine)` for precision
+- **Infrastructure**: Moved stream deployment logic from workspace to library
+  - Generic logic: `@crossdelta/infrastructure/lib/helpers/deploy-streams.ts`
+  - Workspace: `infra/streams/index.ts` (thin wrapper)
+  - Policies: `packages/contracts/src/stream-policies.ts` (business rules)
+
+### Fixed
+- Export detection in `index-manager.ts` no longer matches commented examples
+- Handler service now uses correct `consumeJetStreams` API
+- Contract path resolution for domain structure
+- Template variable substitution (`{{workspaceName}}` in stream-policies.ts.hbs)
+
+### Documentation
+- Updated contracts README with domain structure examples
+- Updated workspace templates to reflect new structure
+- Added stream architecture documentation (conceptual vs. architectural)
+- Clarified separation: contracts define "what", infrastructure defines "how"
+- Removed legacy API references from all public package READMEs
+
+### Removed
+- **Legacy API**: `consumeJetStreamEvents()` removed from public documentation
+  - Use `consumeJetStreams()` instead (plural, supports multiple streams)
+
+### Migration Guide
+1. **Rename handler files**: `*.event.ts` → `*.handler.ts`
+   ```bash
+   find services -name "*.event.ts" -exec bash -c 'mv "$0" "${0%.event.ts}.handler.ts"' {} \;
+   ```
+2. **Update discover patterns**: Change `'./src/events/**/*.event.ts'` → `'./src/events/**/*.handler.ts'`
+3. **Update contract imports**: Adjust for domain structure if using contracts package
+
+### Dependencies
+- `@crossdelta/infrastructure` added to contracts `package.json`
+
+## [0.11.0] - 2025-12-19
+
+### Added
+- **Config-Driven Generator Docs**: Generator instructions now configured in `package.json` under `generatorConfig`
+  - `docs.base`: Base instruction files (service.md, code-style.md, testing.md)
+  - `docs.frameworks`: Framework-specific files (hono-bun.md, hono-node.md, nest.md)
+  - `serviceTypes`: Service type configuration (command types, entry points, skip files)
+- **Lock-File Mechanism**: `.pf-generating` file pauses hot-reload during AI service generation
+- **File-Watcher Service**: Refactored from `dev.command.ts` to `services/file-watcher.ts`
+  - Watches for lock file deletion to trigger reload
+  - Configurable watch paths via `pf.paths` in package.json
+- **Modular AI Instructions**: Split large instruction file into focused modules:
+  - `service.md` - Core service generation rules
+  - `code-style.md` - Formatting, imports, naming conventions
+  - `testing.md` - Testing patterns with bun:test
+  - `hono-bun.md` / `hono-node.md` - Hono-specific patterns
+  - `nest.md` - NestJS-specific patterns
+- **Tests**: Added `config.test.ts` for `getGeneratorConfig()` validation
+
+### Changed
+- **NestJS tsconfig**: Changed to `moduleResolution: bundler` + added `bun-types`
+- **NestJS structure**: Removed test file exclusion from tsconfig.json (needed for IDE)
+- **Biome Config**: Disabled `useImportType` globally for NestJS DI compatibility
+- **Generator docs**: Massively simplified and reorganized (README, framework docs)
+- **AI Instructions Loading**: Now uses config from package.json instead of hardcoded paths
+- **CloudEvents API**: Updated all generators to use new `ensureJetStreams` / `consumeJetStreams`
+
+### Fixed
+- NestJS import sorting issues with DI patterns
+- Handler logging standardized on `console.log` (services can use Logger)
+- Schema field consistency checks in AI generation
+
+### Documentation
+- Expanded AI section in README with feature list and "What makes it different"
+- Added link to `@crossdelta/cloudevents` package
+- Added "AI-assisted" mention in header tagline
+- Updated generator docs with NestJS best practices (use built-in features)
+- Added config validation patterns with `@nestjs/config` + Zod
+
+### Infrastructure
+- Added VS Code workspace settings (`.vscode/settings.json`)
+- Added VS Code extension recommendations (`.vscode/extensions.json`)
+- Biome format-on-save enabled by default
+
+---
+
+## Older Versions
+
+For changes in versions prior to 0.11.0, please refer to the [git commit history](https://github.com/orderboss/platform/commits/main/packages/platform-sdk).
+

package/README.md

@@ -196,32 +196,33 @@ pf event publish order.created
 | `pf event add <type> --service <path>` | 🔗 Add contract + handler + wire stream |
 | `pf event list` | 📋 List available events and consumers |
 | `pf event publish <type>` | 📤 Publish mock event to NATS |
+| `pf setup completion` | 🔧 Install shell autocompletion (zsh/bash) |
+| `pf setup ai` | 🤖 Configure AI provider for code generation |
 | `pf test` | 🧪 Run tests across the monorepo |
 | `pf build` | 📦 Build all packages and services |
 | `pf lint` | ✨ Lint and format with Biome |
 | `pf audit` | 🔒 Run security audit on dependencies |
-| `pf setup --completion` | 🎯 Install shell autocompletion |
 
 > `pf` proxies all commands to Turborepo (works from any subdirectory).
 
-### 🎯 Shell Autocompletion
+#### Custom Command Descriptions
 
-Enable tab completion for `pf` commands - it's automatic!
+Add descriptions to your workspace commands for better autocompletion:
 
-```bash
-# One-time setup
-pf setup --completion
-
-# Restart your shell
-exec $SHELL
-
-# Then enjoy tab completion!
-pf <TAB>         # Shows all commands
-pf event <TAB>   # Shows event subcommands
-pf setup --<TAB>  # Shows --ai, --completion
+```json
+{
+  "pf": {
+    "commands": {
+      "deploy": {
+        "command": "cd infra && pulumi up",
+        "description": "Deploy infrastructure to production"
+      }
+    }
+  }
+}
 ```
 
-**Supported shells:** bash, zsh, fish
+Then `pf <TAB>` shows: `deploy -- Deploy infrastructure to production`
 
 ---
 
@@ -230,7 +231,7 @@ pf setup --<TAB>  # Shows --ai, --completion
 > **Optional but powerful.** Configure once, then use `--ai` with any generator.
 
 ```bash
-pf setup --ai   # OpenAI or Anthropic
+pf setup ai   # OpenAI or Anthropic
 
 pf new hono-micro services/notifications --ai \
   -d "Send emails when orders are created"
@@ -363,7 +364,11 @@ my-platform/
   "pf": {
     "registry": "my-org/my-platform",
     "commands": {
-      "deploy": { "cwd": "infra", "command": "pulumi up --yes" }
+      "deploy": {
+        "cwd": "infra",
+        "command": "pulumi up --yes",
+        "description": "Deploy infrastructure to production"
+      }
     },
     "paths": {
       "services": { "path": "services", "watch": true },