diff --git a/.specledger/memory/constitution.md b/.specledger/memory/constitution.md index 7142d22ba..46944e54d 100644 --- a/.specledger/memory/constitution.md +++ b/.specledger/memory/constitution.md @@ -1,29 +1,27 @@ @@ -72,35 +70,22 @@ Each PR/change MUST do one thing well. Avoid bundling unrelated improvements. **Rationale:** Small, focused changes are easier to review, test, and revert if problems arise. -### IV. Community Alignment - -Feature specifications MUST be reviewed and approved in collaboration with the community before implementation begins. - -**Rules:** -- Major features require RFC or discussion issue before implementation -- Breaking changes MUST have a migration path documented -- Deprecations MUST include timeline and alternatives -- Community feedback periods MUST be respected before merging significant changes -- Maintainers MUST respond to community concerns with technical rationale - -**Rationale:** CDK Terrain is a community fork; decisions should reflect community needs and consensus. - ## User Experience Standards -### V. API Consistency +### IV. Cross-Language Consistency -Similar operations MUST have similar interfaces across all supported languages. +TypeScript is the single source of truth for all library APIs via JSII. Language-specific code (scaffolding templates, post-scaffold hooks, WASM bridges, runtime shims) MUST maintain equivalent behavior across all supported languages. **Rules:** -- Method names MUST follow language-specific conventions while preserving semantic meaning -- Parameter order MUST be consistent: required before optional, context before specifics -- Return types MUST be predictable: similar operations return similar structures -- Error types MUST be consistent within a domain -- Naming patterns established in one area MUST be followed in related areas +- Library API parity is enforced by JSII; do NOT duplicate or override JSII-generated interfaces +- Scaffolding templates MUST provide equivalent project structure and developer experience per language +- Language-specific post-scaffold hooks MUST produce equivalent build/dependency setup +- WASM bridge changes MUST be tested against all consuming language contexts +- Language-specific limitations MUST be documented with workarounds -**Rationale:** Consistency reduces learning curve and prevents user errors. +**Rationale:** Users choose CDK Terrain for multi-language support. JSII guarantees API parity but scaffolding and tooling gaps erode the cross-language promise. -### VI. Predictable Behavior +### V. Predictable Behavior No surprises. Users MUST be able to reason about system behavior from documentation and type signatures. @@ -113,7 +98,7 @@ No surprises. Users MUST be able to reason about system behavior from documentat **Rationale:** Predictable systems build user trust and reduce support burden. -### VII. Progressive Disclosure +### VI. Progressive Disclosure Simple use cases require simple code. Advanced features available but not in the way. @@ -126,22 +111,9 @@ Simple use cases require simple code. Advanced features available but not in the **Rationale:** Low barrier to entry enables adoption; advanced features retain power users. -### VIII. Cross-Language Parity - -Features available in one language MUST be available in all supported languages (TypeScript, Python, Go). - -**Rules:** -- New features MUST NOT ship until available in all supported languages -- Language-specific limitations MUST be documented with workarounds -- Test coverage MUST be equivalent across all language bindings -- Examples MUST be provided in all supported languages -- Performance characteristics SHOULD be comparable across languages - -**Rationale:** Users choose CDK Terrain for multi-language support; partial support defeats the purpose. - ## Quality Standards -### IX. Test Coverage +### VII. Test Coverage All changes to core libraries require appropriate test coverage. @@ -154,15 +126,27 @@ All changes to core libraries require appropriate test coverage. **Rationale:** Tests are the specification; untested code is undefined behavior. +### VIII. Quickstart-Driven Testing + +The quickstart.md produced during plan Phase 1 is the canonical source of expected user journeys. Every step MUST be directly translatable into an integration test scenario. + +**Rules:** +- Each quickstart.md step MUST map to at least one integration test scenario +- CLI-facing changes MUST have corresponding integration tests derived from quickstart steps +- If a quickstart step cannot be automated as a test, it MUST be flagged as NEEDS CLARIFICATION in the spec +- Integration tests MUST exercise the same commands, flags, and expected outputs documented in quickstart.md +- Quickstart.md validation is NOT a polish-phase task; it MUST be verified per user-story phase + +**Rationale:** Quickstart docs that diverge from tested behavior become misleading. Treating quickstart steps as test cases ensures documentation accuracy, catches CLI regressions, and guarantees that the plan>research output has a verifiable integration contract. + ## Governance ### Amendment Procedure -1. Propose changes via GitHub Discussion or RFC -2. Allow minimum 7 days for community feedback on significant changes -3. Maintainer approval required for all amendments -4. Migration plan required for any principle that affects existing code -5. Update all dependent templates and documentation before merging +1. Propose changes via specledger.io spec approval workflow +2. Maintainer approval required for all amendments +3. Migration plan required for any principle that affects existing code +4. Update all dependent templates and documentation before merging ### Versioning Policy @@ -187,4 +171,4 @@ When principles conflict, apply in this order: Explicit override allowed with documented rationale approved by maintainer. -**Version**: 1.0.0 | **Ratified**: 2026-01-14 | **Last Amended**: 2026-01-14 +**Version**: 2.0.0 | **Ratified**: 2026-01-14 | **Last Amended**: 2026-03-20 diff --git a/.specledger/templates/plan-template.md b/.specledger/templates/plan-template.md index b5578ee50..8b6101a51 100644 --- a/.specledger/templates/plan-template.md +++ b/.specledger/templates/plan-template.md @@ -39,6 +39,7 @@ Verify compliance with principles from `.specledger/memory/constitution.md`: - [ ] **UX Consistency**: User flows documented in spec.md acceptance scenarios - [ ] **Performance**: Metrics defined in Technical Context (response time, throughput, memory) - [ ] **Observability**: Logging/metrics strategy documented +- [ ] **Quickstart-Driven Testing**: Quickstart.md steps map to integration test scenarios (per user-story phase, not deferred to polish) - [ ] **Issue Tracking**: Epic created with `sl issue create --type epic` and linked to spec **Complexity Violations** (if any, justify in Complexity Tracking table below): diff --git a/.specledger/templates/tasks-template.md b/.specledger/templates/tasks-template.md index ca6f2d910..031ee0abc 100644 --- a/.specledger/templates/tasks-template.md +++ b/.specledger/templates/tasks-template.md @@ -166,6 +166,8 @@ Examples of foundational tasks (adjust based on your project): - [ ] T016 [US1] Add validation and error handling - [ ] T017 [US1] Add logging for user story 1 operations +- [ ] T0XX [US1] Validate quickstart.md steps map to integration test scenarios for this story + **Checkpoint**: At this point, User Story 1 should be fully functional and testable independently --- @@ -188,6 +190,8 @@ Examples of foundational tasks (adjust based on your project): - [ ] T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py - [ ] T023 [US2] Integrate with User Story 1 components (if needed) +- [ ] T0XX [US2] Validate quickstart.md steps map to integration test scenarios for this story + **Checkpoint**: At this point, User Stories 1 AND 2 should both work independently --- @@ -209,6 +213,8 @@ Examples of foundational tasks (adjust based on your project): - [ ] T027 [US3] Implement [Service] in src/services/[service].py - [ ] T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py +- [ ] T0XX [US3] Validate quickstart.md steps map to integration test scenarios for this story + **Checkpoint**: All user stories should now be independently functional --- @@ -226,7 +232,6 @@ Examples of foundational tasks (adjust based on your project): - [ ] TXXX Performance optimization across all stories - [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/ - [ ] TXXX Security hardening -- [ ] TXXX Run quickstart.md validation --- diff --git a/specledger/001-cdktn-package-rename/issues.jsonl b/specledger/001-cdktn-package-rename/issues.jsonl index d94099b5d..22fd3ddff 100644 --- a/specledger/001-cdktn-package-rename/issues.jsonl +++ b/specledger/001-cdktn-package-rename/issues.jsonl @@ -1,56 +1,56 @@ -{"id":"SL-a3b2de","title":"Update Python project templates (pipenv and pip)","description":"Update both Python template variants to generate projects with cdktn dependencies. Templates must use cdktn PyPI package and cdktn imports.","status":"open","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:02:29.229395624+07:00","updated_at":"2026-01-18T16:02:29.229395624+07:00","labels":["component:templates","phase:us1","requirement:FR-004","requirement:FR-016","spec:001-cdktn-package-rename","story:US1"],"design":"Files: packages/@cdktf/cli-core/src/lib/init/templates/python-pip/**, python-pipenv/**. Update: requirements.txt/Pipfile (cdktf→cdktn), main.py imports (from cdktn import), test imports, .hooks.sscaff.js pypi_cdktn var.","acceptance_criteria":"cdktn init --template python generates project with cdktn imports. Generated project runs successfully.","beads_migration":{"original_id":"core-0e3","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-6b54af","title":"Update Sentry telemetry release tag","description":"Update Sentry error reporting to use cdktn-cli release tag instead of cdktf-cli. Maintain existing telemetry patterns.","status":"open","priority":2,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:28:42.576922155+07:00","updated_at":"2026-01-18T16:28:42.576922155+07:00","labels":["component:cli-core","phase:polish","requirement:FR-033","spec:001-cdktn-package-rename"],"design":"Files: packages/@cdktf/cli-core/src/lib/error-reporting.ts. Update release tag from cdktf-cli-VERSION to cdktn-cli-VERSION. Keep opt-in model and other patterns unchanged.","acceptance_criteria":"Sentry events show cdktn-cli-X.Y.Z release tag. Telemetry opt-in still works.","beads_migration":{"original_id":"core-0hi","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} +{"id":"SL-a3b2de","title":"Update Python project templates (pipenv and pip)","description":"Update both Python template variants to generate projects with cdktn dependencies. Templates must use cdktn PyPI package and cdktn imports.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:02:29.229395624+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:templates","phase:us1","requirement:FR-004","requirement:FR-016","spec:001-cdktn-package-rename","story:US1"],"design":"Files: packages/@cdktf/cli-core/src/lib/init/templates/python-pip/**, python-pipenv/**. Update: requirements.txt/Pipfile (cdktf→cdktn), main.py imports (from cdktn import), test imports, .hooks.sscaff.js pypi_cdktn var.","acceptance_criteria":"cdktn init --template python generates project with cdktn imports. Generated project runs successfully.","beads_migration":{"original_id":"core-0e3","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} +{"id":"SL-6b54af","title":"Update Sentry telemetry release tag","description":"Update Sentry error reporting to use cdktn-cli release tag instead of cdktf-cli. Maintain existing telemetry patterns.","status":"closed","priority":2,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:28:42.576922155+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:cli-core","phase:polish","requirement:FR-033","spec:001-cdktn-package-rename"],"design":"Files: packages/@cdktf/cli-core/src/lib/error-reporting.ts. Update release tag from cdktf-cli-VERSION to cdktn-cli-VERSION. Keep opt-in model and other patterns unchanged.","acceptance_criteria":"Sentry events show cdktn-cli-X.Y.Z release tag. Telemetry opt-in still works.","beads_migration":{"original_id":"core-0hi","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} {"id":"SL-cd2b8c","title":"Rename packages/cdktf-cli to cdktn-cli","description":"Rename the CLI entry point package from cdktf-cli to cdktn-cli. Update package.json name, bin entry point from cdktf to cdktn, and update internal references to cli-core.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T15:52:41.711257915+07:00","updated_at":"2026-01-19T04:16:53.240835252+07:00","closed_at":"2026-01-19T04:16:53.240835252+07:00","labels":["component:cdktf-cli","phase:foundational","requirement:FR-003","requirement:FR-014","spec:001-cdktn-package-rename"],"design":"Files: packages/cdktf-cli/package.json. Update: name cdktf-cli→cdktn-cli, bin entry cdktf→cdktn, dependency @cdktf/cli-core→@cdktn/cli-core. Rename src/bin/cdktf.ts→cdktn.ts if applicable.","acceptance_criteria":"npx cdktn-cli --version works. Package can be npm published.","beads_migration":{"original_id":"core-0ou","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-973168","title":"Validate identical synth output after migration","description":"Verify that migrated projects produce identical synthesized output to ensure no Terraform state drift. US2 acceptance scenario requires 'identical synth output (no state drift)' but no explicit diff-based validation task existed.","status":"open","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T21:04:50.639226236+07:00","updated_at":"2026-01-18T21:04:50.639226236+07:00","labels":["component:cli-core","phase:us2","requirement:FR-012","requirement:FR-013","spec:001-cdktn-package-rename","story:US2"],"design":"Test procedure: 1) Create CDKTF project and synth, 2) Save cdk.tf.json output, 3) Run cdktn migrate --apply, 4) Synth with cdktn, 5) Compare JSON outputs with diff tool, 6) Define equivalence rules (e.g., comment order doesn't matter, but resource structure must match exactly). Document any acceptable differences.","acceptance_criteria":"Migrated project synthesizes identical Terraform JSON. Resource definitions unchanged. Logical IDs unchanged. No state drift occurs.","beads_migration":{"original_id":"core-1a3","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} +{"id":"SL-973168","title":"Validate identical synth output after migration","description":"Verify that migrated projects produce identical synthesized output to ensure no Terraform state drift. US2 acceptance scenario requires 'identical synth output (no state drift)' but no explicit diff-based validation task existed.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T21:04:50.639226236+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:cli-core","phase:us2","requirement:FR-012","requirement:FR-013","spec:001-cdktn-package-rename","story:US2"],"design":"Test procedure: 1) Create CDKTF project and synth, 2) Save cdk.tf.json output, 3) Run cdktn migrate --apply, 4) Synth with cdktn, 5) Compare JSON outputs with diff tool, 6) Define equivalence rules (e.g., comment order doesn't matter, but resource structure must match exactly). Document any acceptable differences.","acceptance_criteria":"Migrated project synthesizes identical Terraform JSON. Resource definitions unchanged. Logical IDs unchanged. No state drift occurs.","beads_migration":{"original_id":"core-1a3","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} {"id":"SL-da1eaf","title":"Phase 1: Setup","description":"Project initialization and build system preparation. Ensures all package renames have correct build configurations before starting implementation.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T15:23:07.645183309+07:00","updated_at":"2026-01-19T04:11:48.731453337+07:00","closed_at":"2026-01-19T04:11:48.731453337+07:00","labels":["phase:setup","spec:001-cdktn-package-rename"],"beads_migration":{"original_id":"core-1q9","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-48f144","title":"Verify npx cdktn-cli invocation path","description":"Validate that npx cdktn-cli init works correctly as documented in US1 acceptance scenario. This tests the package runner path (npx) vs installed binary path.","status":"open","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T21:04:10.577303113+07:00","updated_at":"2026-01-18T21:04:10.577303113+07:00","labels":["component:cdktf-cli","phase:us1","requirement:FR-014","spec:001-cdktn-package-rename","story:US1"],"design":"After core-0ou completes: 1) Publish local package to verdaccio or npm link, 2) Test: npx cdktn-cli init --template typescript, 3) Verify bin field in package.json points to correct entry, 4) Verify generated project is identical to cdktn init output.","acceptance_criteria":"npx cdktn-cli init generates working project. Matches behavior of installed cdktn init command. US1 acceptance scenario passes.","beads_migration":{"original_id":"core-2nj","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-7db9a4","title":"Update cross-package import statements","description":"After all packages are renamed, do a sweep to ensure ALL import statements across the monorepo reference @cdktn/* instead of @cdktf/*. This includes test files, examples, and any other TypeScript files.","status":"open","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T15:58:47.575259365+07:00","updated_at":"2026-01-18T15:58:47.575259365+07:00","labels":["component:build","phase:foundational","spec:001-cdktn-package-rename"],"design":"Use grep -r to find remaining @cdktf/ and cdktf imports. Update all occurrences except Symbol.for() strings and legacy path references (cdktf.json, cdktf.out, CDKTF_*).","acceptance_criteria":"grep -r for @cdktf/ in *.ts files returns no results (except Symbol.for strings). yarn build succeeds.","beads_migration":{"original_id":"core-2v8","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-c4ffcb","title":"Verify provider peer dependency resolution","description":"Verify that cdktn core library can be used as peer dependency by provider packages. Test that a project with @cdktn/provider-* (when available) or @cdktf/provider-* (transitional) can synthesize.","status":"open","priority":2,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:18:37.03777435+07:00","updated_at":"2026-01-18T16:18:37.03777435+07:00","labels":["component:cdktf","phase:us3","requirement:FR-018","spec:001-cdktn-package-rename","story:US3"],"design":"Create test project with cdktn and a provider. Verify peer dependency resolution works. Document behavior with mixed provider versions.","acceptance_criteria":"Project with provider dependency synthesizes correctly. Peer dependency warnings (if any) are expected and documented.","beads_migration":{"original_id":"core-317","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-3d9d60","title":"Add migration telemetry events","description":"Add telemetry events for cdktn migrate command execution. Track migration success, failure, and dual-dependency detection using existing Sentry patterns.","status":"open","priority":3,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:28:55.860542971+07:00","updated_at":"2026-01-18T16:28:55.860542971+07:00","labels":["component:cli-core","phase:polish","requirement:FR-034","spec:001-cdktn-package-rename"],"design":"Files: packages/@cdktf/cli-core/src/lib/commands/migrate.ts, error-reporting.ts. Add breadcrumbs/events for: migration started, files updated, success, errors. Follow existing telemetry patterns.","acceptance_criteria":"Migration events appear in Sentry. Events respect opt-in setting.","beads_migration":{"original_id":"core-3gz","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} +{"id":"SL-48f144","title":"Verify npx cdktn-cli invocation path","description":"Validate that npx cdktn-cli init works correctly as documented in US1 acceptance scenario. This tests the package runner path (npx) vs installed binary path.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T21:04:10.577303113+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:cdktf-cli","phase:us1","requirement:FR-014","spec:001-cdktn-package-rename","story:US1"],"design":"After core-0ou completes: 1) Publish local package to verdaccio or npm link, 2) Test: npx cdktn-cli init --template typescript, 3) Verify bin field in package.json points to correct entry, 4) Verify generated project is identical to cdktn init output.","acceptance_criteria":"npx cdktn-cli init generates working project. Matches behavior of installed cdktn init command. US1 acceptance scenario passes.","beads_migration":{"original_id":"core-2nj","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} +{"id":"SL-7db9a4","title":"Update cross-package import statements","description":"After all packages are renamed, do a sweep to ensure ALL import statements across the monorepo reference @cdktn/* instead of @cdktf/*. This includes test files, examples, and any other TypeScript files.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T15:58:47.575259365+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:build","phase:foundational","spec:001-cdktn-package-rename"],"design":"Use grep -r to find remaining @cdktf/ and cdktf imports. Update all occurrences except Symbol.for() strings and legacy path references (cdktf.json, cdktf.out, CDKTF_*).","acceptance_criteria":"grep -r for @cdktf/ in *.ts files returns no results (except Symbol.for strings). yarn build succeeds.","beads_migration":{"original_id":"core-2v8","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} +{"id":"SL-c4ffcb","title":"Verify provider peer dependency resolution","description":"Verify that cdktn core library can be used as peer dependency by provider packages. Test that a project with @cdktn/provider-* (when available) or @cdktf/provider-* (transitional) can synthesize.","status":"closed","priority":2,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:18:37.03777435+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:cdktf","phase:us3","requirement:FR-018","spec:001-cdktn-package-rename","story:US3"],"design":"Create test project with cdktn and a provider. Verify peer dependency resolution works. Document behavior with mixed provider versions.","acceptance_criteria":"Project with provider dependency synthesizes correctly. Peer dependency warnings (if any) are expected and documented.","beads_migration":{"original_id":"core-317","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} +{"id":"SL-3d9d60","title":"Add migration telemetry events","description":"Add telemetry events for cdktn migrate command execution. Track migration success, failure, and dual-dependency detection using existing Sentry patterns.","status":"closed","priority":3,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:28:55.860542971+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:cli-core","phase:polish","requirement:FR-034","spec:001-cdktn-package-rename"],"design":"Files: packages/@cdktf/cli-core/src/lib/commands/migrate.ts, error-reporting.ts. Add breadcrumbs/events for: migration started, files updated, success, errors. Follow existing telemetry patterns.","acceptance_criteria":"Migration events appear in Sentry. Events respect opt-in setting.","beads_migration":{"original_id":"core-3gz","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} {"id":"SL-3d5d80","title":"Rename packages/@cdktf/provider-schema to @cdktn/provider-schema","description":"Rename the provider schema fetching package. Update package.json name and consumer imports.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T15:58:13.265069092+07:00","updated_at":"2026-01-19T06:54:36.762833028+07:00","closed_at":"2026-01-19T06:54:36.762833028+07:00","labels":["component:provider-schema","phase:foundational","spec:001-cdktn-package-rename"],"design":"Files: packages/@cdktf/provider-schema/package.json. Update name. Search and update imports in other packages.","acceptance_criteria":"Package builds. cdktn get successfully fetches provider schemas.","beads_migration":{"original_id":"core-3qc","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} {"id":"SL-d66209","title":"Rename packages/@cdktf/cli-core to @cdktn/cli-core","description":"Rename the CLI core implementation package. This contains all CLI command implementations. Update package.json name and all internal imports.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T15:53:32.207796039+07:00","updated_at":"2026-01-19T04:17:57.416816643+07:00","closed_at":"2026-01-19T04:17:57.416816643+07:00","labels":["component:cli-core","phase:foundational","spec:001-cdktn-package-rename"],"design":"Files: packages/@cdktf/cli-core/package.json. Update: name @cdktf/cli-core→@cdktn/cli-core, all dependency references from @cdktf/*→@cdktn/*. Update imports in src/**/*.ts files.","acceptance_criteria":"Package builds successfully. All cli-core commands work through cdktn-cli.","beads_migration":{"original_id":"core-4sx","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-539860","title":"Run quickstart.md validation scenarios","description":"Execute all validation scenarios documented in quickstart.md to ensure the migration guide is accurate and complete.","status":"open","priority":2,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:35:30.004358252+07:00","updated_at":"2026-01-18T16:35:30.004358252+07:00","labels":["component:docs","phase:polish","spec:001-cdktn-package-rename"],"design":"Follow quickstart.md step by step. Test automated migration (cdktn migrate). Test manual migration for each language. Verify troubleshooting steps work. Update quickstart.md if any steps are incorrect.","acceptance_criteria":"All quickstart.md scenarios work as documented. Any inaccuracies corrected.","beads_migration":{"original_id":"core-67c","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} +{"id":"SL-539860","title":"Run quickstart.md validation scenarios","description":"Execute all validation scenarios documented in quickstart.md to ensure the migration guide is accurate and complete.","status":"closed","priority":2,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:35:30.004358252+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:docs","phase:polish","spec:001-cdktn-package-rename"],"design":"Follow quickstart.md step by step. Test automated migration (cdktn migrate). Test manual migration for each language. Verify troubleshooting steps work. Update quickstart.md if any steps are incorrect.","acceptance_criteria":"All quickstart.md scenarios work as documented. Any inaccuracies corrected.","beads_migration":{"original_id":"core-67c","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} {"id":"SL-3e86a3","title":"Rename packages/@cdktf/provider-generator to @cdktn/provider-generator","description":"Rename the provider binding generator package. Update package.json name, internal imports, AND critically ensure generated provider code references cdktn imports (not cdktf).","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T15:57:10.824052009+07:00","updated_at":"2026-01-19T04:25:31.564355125+07:00","closed_at":"2026-01-19T04:25:31.564355125+07:00","labels":["component:provider-generator","phase:foundational","requirement:FR-019","requirement:FR-024","spec:001-cdktn-package-rename","story:US4"],"design":"Files: packages/@cdktf/provider-generator/package.json, src/**/*.ts. Update name. CRITICAL: Find all code generation templates/strings that output cdktf imports and change to cdktn. Generated package.json must have cdktn peer dependency.","acceptance_criteria":"Package builds. cdktn get generates providers with cdktn imports and peer dependency.","beads_migration":{"original_id":"core-6ly","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-a33ca8","title":"Verify convert command works with cdktn","description":"End-to-end verification that cdktn convert produces working CDK code. Test with sample HCL files and verify generated project synthesizes.","status":"open","priority":3,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:27:29.917769265+07:00","updated_at":"2026-01-18T16:27:29.917769265+07:00","labels":["component:hcl2cdk","phase:us5","spec:001-cdktn-package-rename","story:US5"],"design":"Create test HCL file with common Terraform patterns. Run cdktn convert. Verify generated code imports from cdktn. Verify cdktn synth works on generated project.","acceptance_criteria":"cdktn convert produces compilable code with cdktn imports. Full round-trip (HCL→CDK→synth) works.","beads_migration":{"original_id":"core-815","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-18d652","title":"Phase 6: User Story 4 - Developer Generates Local Providers","description":"A developer can generate local provider bindings using cdktn get. This is the CLEAN MIGRATION PATH allowing complete removal of cdktf dependencies. Generated code uses cdktn imports with zero cdktf references. Independent Test: Run cdktn get, verify generated code uses cdktn imports exclusively.","status":"open","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:22:08.043413364+07:00","updated_at":"2026-01-18T17:17:16.31318706+07:00","labels":["phase:us4","spec:001-cdktn-package-rename","story:US4"],"beads_migration":{"original_id":"core-86i","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-f0a941","title":"Implement cdktn migrate command - TypeScript support","description":"Implement the cdktn migrate command to assist users transitioning from cdktf. Support TypeScript projects: update package.json dependencies and import statements. Dry-run mode by default.","status":"open","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:09:38.576685474+07:00","updated_at":"2026-01-18T16:09:38.576685474+07:00","labels":["component:cli-core","phase:us2","requirement:FR-028","requirement:FR-029","requirement:FR-030","requirement:FR-031","spec:001-cdktn-package-rename","story:US2"],"design":"Files: packages/@cdktf/cli-core/src/lib/commands/migrate.ts (new), update command registration. Parse package.json for cdktf deps, find .ts files with cdktf imports. Replace patterns per data-model.md. Print changes in dry-run, apply with flag.","acceptance_criteria":"cdktn migrate --dry-run shows changes for a cdktf TypeScript project. cdktn migrate updates deps and imports correctly.","beads_migration":{"original_id":"core-8hm","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-b88785","title":"Update C# project template","description":"Update the C# template to generate projects with Io.Cdktn NuGet package reference. Note: C# packages built but NOT published to NuGet in Release 1.","status":"open","priority":2,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:04:33.721375494+07:00","updated_at":"2026-01-18T16:04:33.721375494+07:00","labels":["component:templates","phase:us1","requirement:FR-007","requirement:FR-016","spec:001-cdktn-package-rename","story:US1"],"design":"Files: packages/@cdktf/cli-core/src/lib/init/templates/csharp/**. Update: .csproj PackageReference (Io.Cdktn), Program.cs using (Io.Cdktn), MainStack.cs, TestProgram.cs, .hooks.sscaff.js nuget_cdktn var.","acceptance_criteria":"cdktn init --template csharp generates project with cdktn usings. dotnet build succeeds.","beads_migration":{"original_id":"core-8xe","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} +{"id":"SL-a33ca8","title":"Verify convert command works with cdktn","description":"End-to-end verification that cdktn convert produces working CDK code. Test with sample HCL files and verify generated project synthesizes.","status":"closed","priority":3,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:27:29.917769265+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:hcl2cdk","phase:us5","spec:001-cdktn-package-rename","story:US5"],"design":"Create test HCL file with common Terraform patterns. Run cdktn convert. Verify generated code imports from cdktn. Verify cdktn synth works on generated project.","acceptance_criteria":"cdktn convert produces compilable code with cdktn imports. Full round-trip (HCL→CDK→synth) works.","beads_migration":{"original_id":"core-815","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} +{"id":"SL-18d652","title":"Phase 6: User Story 4 - Developer Generates Local Providers","description":"A developer can generate local provider bindings using cdktn get. This is the CLEAN MIGRATION PATH allowing complete removal of cdktf dependencies. Generated code uses cdktn imports with zero cdktf references. Independent Test: Run cdktn get, verify generated code uses cdktn imports exclusively.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:22:08.043413364+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["phase:us4","spec:001-cdktn-package-rename","story:US4"],"beads_migration":{"original_id":"core-86i","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} +{"id":"SL-f0a941","title":"Implement cdktn migrate command - TypeScript support","description":"Implement the cdktn migrate command to assist users transitioning from cdktf. Support TypeScript projects: update package.json dependencies and import statements. Dry-run mode by default.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:09:38.576685474+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:cli-core","phase:us2","requirement:FR-028","requirement:FR-029","requirement:FR-030","requirement:FR-031","spec:001-cdktn-package-rename","story:US2"],"design":"Files: packages/@cdktf/cli-core/src/lib/commands/migrate.ts (new), update command registration. Parse package.json for cdktf deps, find .ts files with cdktf imports. Replace patterns per data-model.md. Print changes in dry-run, apply with flag.","acceptance_criteria":"cdktn migrate --dry-run shows changes for a cdktf TypeScript project. cdktn migrate updates deps and imports correctly.","beads_migration":{"original_id":"core-8hm","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Not implemented - migrate command deemed unnecessary, migration is simple enough without tooling"} +{"id":"SL-b88785","title":"Update C# project template","description":"Update the C# template to generate projects with Io.Cdktn NuGet package reference. Note: C# packages built but NOT published to NuGet in Release 1.","status":"closed","priority":2,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:04:33.721375494+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:templates","phase:us1","requirement:FR-007","requirement:FR-016","spec:001-cdktn-package-rename","story:US1"],"design":"Files: packages/@cdktf/cli-core/src/lib/init/templates/csharp/**. Update: .csproj PackageReference (Io.Cdktn), Program.cs using (Io.Cdktn), MainStack.cs, TestProgram.cs, .hooks.sscaff.js nuget_cdktn var.","acceptance_criteria":"cdktn init --template csharp generates project with cdktn usings. dotnet build succeeds.","beads_migration":{"original_id":"core-8xe","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} {"id":"SL-a1375f","title":"Update lerna.json and release configuration","description":"Update lerna.json for new package naming scheme. Ensure version management and publishing work correctly for @cdktn scope.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T15:48:53.704701658+07:00","updated_at":"2026-01-19T04:10:30.379754766+07:00","closed_at":"2026-01-19T04:10:30.379754766+07:00","labels":["component:build","phase:setup","spec:001-cdktn-package-rename"],"design":"Files: lerna.json, .releaserc (if exists). Update any package name patterns.","acceptance_criteria":"yarn version and lerna commands work correctly with new package names.","beads_migration":{"original_id":"core-98d","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} {"id":"SL-bf9774","title":"Rename packages/@cdktf/commons to @cdktn/commons","description":"Rename the shared utilities package from @cdktf/commons to @cdktn/commons. Update package.json name and all consumer imports.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T15:54:18.741434588+07:00","updated_at":"2026-01-19T04:21:08.329152338+07:00","closed_at":"2026-01-19T04:21:08.329152338+07:00","labels":["component:commons","phase:foundational","spec:001-cdktn-package-rename"],"design":"Files: packages/@cdktf/commons/package.json. Update name. Search for @cdktf/commons imports in other packages and update them.","acceptance_criteria":"Package builds. All dependent packages compile successfully.","beads_migration":{"original_id":"core-9nu","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} {"id":"SL-516a2d","title":"Update CI/CD workflow configurations","description":"Update GitHub Actions workflows and any CI configurations to reference new package names. Ensure publish workflows target correct npm scopes (@cdktn/*).","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T15:44:46.242628356+07:00","updated_at":"2026-01-18T21:36:58.369422599+07:00","closed_at":"2026-01-18T21:36:58.369422599+07:00","labels":["component:ci","phase:setup","spec:001-cdktn-package-rename"],"design":"Files: .github/workflows/*.yml. Search for cdktf references in publish/release workflows. Update npm publish targets.","acceptance_criteria":"CI workflows pass without errors. Release workflows configured for @cdktn scope.","beads_migration":{"original_id":"core-9r8","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-806182","title":"Phase 5: User Story 3 - Developer Uses Prebuilt Providers (P2)","description":"A developer can use prebuilt provider packages (@cdktn/provider-*) with their cdktn project. Note: Prebuilt providers live in external repos and do major version bump AFTER cdktn Release 1 ships. This story verifies the core library supports providers correctly. Independent Test: Install a provider package and verify it synthesizes correctly with cdktn stack.","status":"open","priority":2,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:17:11.381233356+07:00","updated_at":"2026-01-18T16:17:11.381233356+07:00","labels":["phase:us3","spec:001-cdktn-package-rename","story:US3"],"beads_migration":{"original_id":"core-at3","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} +{"id":"SL-806182","title":"Phase 5: User Story 3 - Developer Uses Prebuilt Providers (P2)","description":"A developer can use prebuilt provider packages (@cdktn/provider-*) with their cdktn project. Note: Prebuilt providers live in external repos and do major version bump AFTER cdktn Release 1 ships. This story verifies the core library supports providers correctly. Independent Test: Install a provider package and verify it synthesizes correctly with cdktn stack.","status":"closed","priority":2,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:17:11.381233356+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["phase:us3","spec:001-cdktn-package-rename","story:US3"],"beads_migration":{"original_id":"core-at3","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} {"id":"SL-fa6b63","title":"Phase 2: Foundational - Core Package Renames","description":"Rename all package.json files and JSII configurations for the 9 core packages. This phase MUST complete before any user story can be implemented. All import paths and cross-package dependencies updated.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T15:49:35.473655917+07:00","updated_at":"2026-01-19T06:56:07.03742958+07:00","closed_at":"2026-01-19T06:56:07.03742958+07:00","labels":["phase:foundational","spec:001-cdktn-package-rename"],"beads_migration":{"original_id":"core-atg","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-5a1f0e","title":"Phase 8: Polish \u0026 Validation","description":"Final validation, cross-cutting concerns, and polish. Run test suites, verify examples, update Sentry telemetry, ensure integration tests pass. This phase depends on all user stories being complete for full validation.","status":"open","priority":2,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:28:03.681039055+07:00","updated_at":"2026-01-18T16:28:03.681039055+07:00","labels":["phase:polish","spec:001-cdktn-package-rename"],"beads_migration":{"original_id":"core-az4","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-cc1d58","title":"Update provider generator code templates","description":"Update the provider generator to output code with cdktn imports instead of cdktf. All generated TypeScript must import from cdktn. Generated package.json must have cdktn peer dependency with zero @cdktf references.","status":"open","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:24:01.980100882+07:00","updated_at":"2026-01-18T16:24:01.980100882+07:00","labels":["component:provider-generator","phase:us4","requirement:FR-019","spec:001-cdktn-package-rename","story:US4"],"design":"Files: packages/@cdktf/provider-generator/lib/**/*.ts. Find template strings and code generation that outputs cdktf imports. Update to cdktn. Critical: generated package.json must not contain any @cdktf scope references.","acceptance_criteria":"cdktn get generates provider with cdktn imports. Generated package.json shows cdktn peer dependency only.","beads_migration":{"original_id":"core-c64","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-9a0dfd","title":"Implement cdktn migrate command - Go support","description":"Extend cdktn migrate to support Go projects. Update go.mod module paths and Go import statements.","status":"open","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:12:47.014407949+07:00","updated_at":"2026-01-18T16:12:47.014407949+07:00","labels":["component:cli-core","phase:us2","requirement:FR-029","spec:001-cdktn-package-rename","story:US2"],"design":"Files: packages/@cdktf/cli-core/src/lib/commands/migrate.ts. Add Go file detection. Replace github.com/hashicorp/terraform-cdk-go/cdktf with github.com/open-constructs/cdk-terrain-go/cdktn. Update go.mod require paths.","acceptance_criteria":"cdktn migrate works on Go cdktf projects. go.mod and imports updated correctly.","beads_migration":{"original_id":"core-cq5","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-3ebc24","title":"Update template help files","description":"Update the help files in each template that display after cdktn init. These should reference cdktn commands and cdktn provider URLs.","status":"open","priority":2,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:06:20.60604951+07:00","updated_at":"2026-01-18T16:06:20.60604951+07:00","labels":["component:templates","phase:us1","spec:001-cdktn-package-rename","story:US1"],"design":"Files: packages/@cdktf/cli-core/src/lib/init/templates/*/help. Update command references (cdktf→cdktn). Update any package URLs to cdktn equivalents.","acceptance_criteria":"After cdktn init, displayed help references cdktn commands.","beads_migration":{"original_id":"core-cv6","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-8fbe47","title":"Verify CLI coexistence with cdktf-cli","description":"Verify that cdktn-cli works correctly when cdktf-cli is also installed globally. Both CLIs should function independently without conflicts.","status":"open","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:34:49.399802274+07:00","updated_at":"2026-01-18T16:34:49.399802274+07:00","labels":["component:cli","phase:polish","spec:001-cdktn-package-rename"],"design":"Install both cdktf-cli and cdktn-cli globally. Verify cdktn commands work. Verify cdktf commands still work. Check no command conflicts or PATH issues.","acceptance_criteria":"Both CLIs can be installed simultaneously. Each responds to its own command (cdktn vs cdktf). No conflicts.","beads_migration":{"original_id":"core-cyy","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-06fafd","title":"Update example projects","description":"Update example projects in examples/ directory to use cdktn imports and dependencies. Ensure selected examples compile and synthesize correctly.","status":"open","priority":2,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:33:26.776775721+07:00","updated_at":"2026-01-18T16:33:26.776775721+07:00","labels":["component:examples","phase:polish","spec:001-cdktn-package-rename"],"design":"Step 1: Explore examples/ directory and group examples by language (TypeScript, Python, Go, Java, C#). Step 2: Generate categorized list of examples. Step 3: Use AskUserQuestion tool to ask user which examples are priority to update vs skip. Step 4: Update selected examples: package.json deps (cdktf→cdktn), import statements, CLI commands. Step 5: Verify selected examples compile and synthesize.","acceptance_criteria":"User-selected examples updated with cdktn imports. Selected examples compile and synthesize. Skipped examples documented.","beads_migration":{"original_id":"core-d2n","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-9ba554","title":"Update CLI help text and user-facing output","description":"Update all CLI help text, log messages, and user-facing output to reference cdktn instead of cdktf. This includes command descriptions, examples, and error messages.","status":"open","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:05:02.152967358+07:00","updated_at":"2026-01-18T16:05:02.152967358+07:00","labels":["component:cli-core","phase:us1","requirement:FR-015","spec:001-cdktn-package-rename","story:US1"],"design":"Files: packages/@cdktf/cli-core/src/lib/**/*.ts. Search for user-facing strings containing cdktf (not Symbol.for or file paths) and update to cdktn. Update command help descriptions.","acceptance_criteria":"cdktn --help shows cdktn references. All command help shows cdktn examples.","beads_migration":{"original_id":"core-d4p","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-1628c2","title":"Verify backward-compatible paths preserved","description":"Verify that cdktf.json config file, cdktf.out/ output directory, CDKTF_* env vars, and ~/.cdktf home directory are still used. No changes needed to these paths.","status":"open","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:05:43.964621062+07:00","updated_at":"2026-01-18T16:05:43.964621062+07:00","labels":["component:cli-core","phase:us1","requirement:FR-008","requirement:FR-009","requirement:FR-010","requirement:FR-011","spec:001-cdktn-package-rename","story:US1"],"design":"Review packages/@cdktf/cli-core/src/lib/cdktf-config.ts and related files. Ensure cdktf.json is the config filename. Ensure cdktf.out is default output. Ensure CDKTF_* env vars are read. Document any references found.","acceptance_criteria":"cdktn synth writes to cdktf.out/. cdktn reads cdktf.json. CDKTF_LOG_LEVEL works with cdktn CLI.","beads_migration":{"original_id":"core-dt7","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-900f3b","title":"Run integration test suite","description":"Run integration tests for published languages. Identify critical test suites via exploration and user preference gathering.","status":"open","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:32:00.586385508+07:00","updated_at":"2026-01-18T16:32:00.586385508+07:00","labels":["component:test","phase:polish","spec:001-cdktn-package-rename"],"design":"Step 1: Explore test/ directory to identify full set of integration tests per target language (TypeScript, Python, Go). Step 2: Use AskUserQuestion tool to gather user preference on which tests are critical vs nice-to-have. Step 3: Run yarn package. Step 4: Run identified critical tests. Step 5: Document results and any known limitations.","acceptance_criteria":"Critical integration tests identified with user input and run. At minimum one critical test per published language passes. Known limitations documented.","beads_migration":{"original_id":"core-evj","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-2a9b9b","title":"Verify __cdktf_* logical IDs unchanged","description":"Verify that Terraform logical IDs (resource identifiers in synthesized JSON) remain unchanged after package renames. Logical IDs use __cdktf_* pattern and MUST stay 'cdktf' NOT 'cdktn' to prevent state drift.","status":"open","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T21:06:36.770022504+07:00","updated_at":"2026-01-18T21:06:36.770022504+07:00","labels":["component:cdktf","phase:foundational","requirement:FR-013","spec:001-cdktn-package-rename"],"design":"After foundational renames: 1) Create test project with resources, 2) Synth and inspect cdk.tf.json, 3) Verify all logical IDs still use __cdktf_* pattern (NOT __cdktn_*), 4) Compare with CDKTF baseline output, 5) Add integration test that fails if logical ID pattern changes. Check both TerraformStack and TerraformResource naming.","acceptance_criteria":"Synthesized JSON shows __cdktf_* logical IDs unchanged. No __cdktn_* patterns present. Integration test validates pattern stability.","beads_migration":{"original_id":"core-ezc","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-d19cab","title":"Document prebuilt provider release strategy","description":"Document in quickstart.md or similar that prebuilt providers (@cdktn/provider-*) ship AFTER cdktn Release 1. Document that users can use @cdktf/provider-* transitionally or generate local providers via cdktn get.","status":"open","priority":3,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:21:01.020722577+07:00","updated_at":"2026-01-18T17:18:05.377967101+07:00","labels":["component:docs","phase:us3","spec:001-cdktn-package-rename","story:US3"],"design":"Update specs/001-cdktn-package-rename/quickstart.md or create release notes section. Explain timing: Release 1 core ships first, providers do major bump after.","acceptance_criteria":"Documentation clearly explains provider release timing and migration options.","beads_migration":{"original_id":"core-fe6","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} +{"id":"SL-5a1f0e","title":"Phase 8: Polish & Validation","description":"Final validation, cross-cutting concerns, and polish. Run test suites, verify examples, update Sentry telemetry, ensure integration tests pass. This phase depends on all user stories being complete for full validation.","status":"closed","priority":2,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:28:03.681039055+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["phase:polish","spec:001-cdktn-package-rename"],"beads_migration":{"original_id":"core-az4","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} +{"id":"SL-cc1d58","title":"Update provider generator code templates","description":"Update the provider generator to output code with cdktn imports instead of cdktf. All generated TypeScript must import from cdktn. Generated package.json must have cdktn peer dependency with zero @cdktf references.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:24:01.980100882+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:provider-generator","phase:us4","requirement:FR-019","spec:001-cdktn-package-rename","story:US4"],"design":"Files: packages/@cdktf/provider-generator/lib/**/*.ts. Find template strings and code generation that outputs cdktf imports. Update to cdktn. Critical: generated package.json must not contain any @cdktf scope references.","acceptance_criteria":"cdktn get generates provider with cdktn imports. Generated package.json shows cdktn peer dependency only.","beads_migration":{"original_id":"core-c64","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} +{"id":"SL-9a0dfd","title":"Implement cdktn migrate command - Go support","description":"Extend cdktn migrate to support Go projects. Update go.mod module paths and Go import statements.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:12:47.014407949+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:cli-core","phase:us2","requirement:FR-029","spec:001-cdktn-package-rename","story:US2"],"design":"Files: packages/@cdktf/cli-core/src/lib/commands/migrate.ts. Add Go file detection. Replace github.com/hashicorp/terraform-cdk-go/cdktf with github.com/open-constructs/cdk-terrain-go/cdktn. Update go.mod require paths.","acceptance_criteria":"cdktn migrate works on Go cdktf projects. go.mod and imports updated correctly.","beads_migration":{"original_id":"core-cq5","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Not implemented - migrate command deemed unnecessary, migration is simple enough without tooling"} +{"id":"SL-3ebc24","title":"Update template help files","description":"Update the help files in each template that display after cdktn init. These should reference cdktn commands and cdktn provider URLs.","status":"closed","priority":2,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:06:20.60604951+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:templates","phase:us1","spec:001-cdktn-package-rename","story:US1"],"design":"Files: packages/@cdktf/cli-core/src/lib/init/templates/*/help. Update command references (cdktf→cdktn). Update any package URLs to cdktn equivalents.","acceptance_criteria":"After cdktn init, displayed help references cdktn commands.","beads_migration":{"original_id":"core-cv6","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} +{"id":"SL-8fbe47","title":"Verify CLI coexistence with cdktf-cli","description":"Verify that cdktn-cli works correctly when cdktf-cli is also installed globally. Both CLIs should function independently without conflicts.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:34:49.399802274+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:cli","phase:polish","spec:001-cdktn-package-rename"],"design":"Install both cdktf-cli and cdktn-cli globally. Verify cdktn commands work. Verify cdktf commands still work. Check no command conflicts or PATH issues.","acceptance_criteria":"Both CLIs can be installed simultaneously. Each responds to its own command (cdktn vs cdktf). No conflicts.","beads_migration":{"original_id":"core-cyy","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} +{"id":"SL-06fafd","title":"Update example projects","description":"Update example projects in examples/ directory to use cdktn imports and dependencies. Ensure selected examples compile and synthesize correctly.","status":"closed","priority":2,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:33:26.776775721+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:examples","phase:polish","spec:001-cdktn-package-rename"],"design":"Step 1: Explore examples/ directory and group examples by language (TypeScript, Python, Go, Java, C#). Step 2: Generate categorized list of examples. Step 3: Use AskUserQuestion tool to ask user which examples are priority to update vs skip. Step 4: Update selected examples: package.json deps (cdktf→cdktn), import statements, CLI commands. Step 5: Verify selected examples compile and synthesize.","acceptance_criteria":"User-selected examples updated with cdktn imports. Selected examples compile and synthesize. Skipped examples documented.","beads_migration":{"original_id":"core-d2n","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} +{"id":"SL-9ba554","title":"Update CLI help text and user-facing output","description":"Update all CLI help text, log messages, and user-facing output to reference cdktn instead of cdktf. This includes command descriptions, examples, and error messages.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:05:02.152967358+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:cli-core","phase:us1","requirement:FR-015","spec:001-cdktn-package-rename","story:US1"],"design":"Files: packages/@cdktf/cli-core/src/lib/**/*.ts. Search for user-facing strings containing cdktf (not Symbol.for or file paths) and update to cdktn. Update command help descriptions.","acceptance_criteria":"cdktn --help shows cdktn references. All command help shows cdktn examples.","beads_migration":{"original_id":"core-d4p","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} +{"id":"SL-1628c2","title":"Verify backward-compatible paths preserved","description":"Verify that cdktf.json config file, cdktf.out/ output directory, CDKTF_* env vars, and ~/.cdktf home directory are still used. No changes needed to these paths.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:05:43.964621062+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:cli-core","phase:us1","requirement:FR-008","requirement:FR-009","requirement:FR-010","requirement:FR-011","spec:001-cdktn-package-rename","story:US1"],"design":"Review packages/@cdktf/cli-core/src/lib/cdktf-config.ts and related files. Ensure cdktf.json is the config filename. Ensure cdktf.out is default output. Ensure CDKTF_* env vars are read. Document any references found.","acceptance_criteria":"cdktn synth writes to cdktf.out/. cdktn reads cdktf.json. CDKTF_LOG_LEVEL works with cdktn CLI.","beads_migration":{"original_id":"core-dt7","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} +{"id":"SL-900f3b","title":"Run integration test suite","description":"Run integration tests for published languages. Identify critical test suites via exploration and user preference gathering.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:32:00.586385508+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:test","phase:polish","spec:001-cdktn-package-rename"],"design":"Step 1: Explore test/ directory to identify full set of integration tests per target language (TypeScript, Python, Go). Step 2: Use AskUserQuestion tool to gather user preference on which tests are critical vs nice-to-have. Step 3: Run yarn package. Step 4: Run identified critical tests. Step 5: Document results and any known limitations.","acceptance_criteria":"Critical integration tests identified with user input and run. At minimum one critical test per published language passes. Known limitations documented.","beads_migration":{"original_id":"core-evj","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} +{"id":"SL-2a9b9b","title":"Verify __cdktf_* logical IDs unchanged","description":"Verify that Terraform logical IDs (resource identifiers in synthesized JSON) remain unchanged after package renames. Logical IDs use __cdktf_* pattern and MUST stay 'cdktf' NOT 'cdktn' to prevent state drift.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T21:06:36.770022504+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:cdktf","phase:foundational","requirement:FR-013","spec:001-cdktn-package-rename"],"design":"After foundational renames: 1) Create test project with resources, 2) Synth and inspect cdk.tf.json, 3) Verify all logical IDs still use __cdktf_* pattern (NOT __cdktn_*), 4) Compare with CDKTF baseline output, 5) Add integration test that fails if logical ID pattern changes. Check both TerraformStack and TerraformResource naming.","acceptance_criteria":"Synthesized JSON shows __cdktf_* logical IDs unchanged. No __cdktn_* patterns present. Integration test validates pattern stability.","beads_migration":{"original_id":"core-ezc","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} +{"id":"SL-d19cab","title":"Document prebuilt provider release strategy","description":"Document in quickstart.md or similar that prebuilt providers (@cdktn/provider-*) ship AFTER cdktn Release 1. Document that users can use @cdktf/provider-* transitionally or generate local providers via cdktn get.","status":"closed","priority":3,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:21:01.020722577+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:docs","phase:us3","spec:001-cdktn-package-rename","story:US3"],"design":"Update specs/001-cdktn-package-rename/quickstart.md or create release notes section. Explain timing: Release 1 core ships first, providers do major bump after.","acceptance_criteria":"Documentation clearly explains provider release timing and migration options.","beads_migration":{"original_id":"core-fe6","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} {"id":"SL-ab1cfe","title":"Rename packages/@cdktf/hcl2json to @cdktn/hcl2json","description":"Rename the HCL-to-JSON WASM parser package. Update package.json name and consumer imports.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T15:56:04.169694608+07:00","updated_at":"2026-01-19T04:24:31.187727812+07:00","closed_at":"2026-01-19T04:24:31.187727812+07:00","labels":["component:hcl2json","phase:foundational","spec:001-cdktn-package-rename"],"design":"Files: packages/@cdktf/hcl2json/package.json. Update name. This is the Go WASM compilation - no internal changes needed beyond package identity.","acceptance_criteria":"Package builds. WASM module loads correctly.","beads_migration":{"original_id":"core-fps","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-603c85","title":"Add migrate command dry-run and validation","description":"Enhance cdktn migrate with dry-run mode (default behavior), pre-run validations, and helpful user messaging. Validate it is a cdktf project, warn about backup recommendations.","status":"open","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:13:22.697589513+07:00","updated_at":"2026-01-18T16:13:22.697589513+07:00","labels":["component:cli-core","phase:us2","requirement:FR-031","spec:001-cdktn-package-rename","story:US2"],"design":"Files: packages/@cdktf/cli-core/src/lib/commands/migrate.ts. Add --dry-run flag (default true), --apply flag to make changes. Check for cdktf.json presence. Warn users to backup/commit before applying.","acceptance_criteria":"cdktn migrate shows preview by default. cdktn migrate --apply makes changes. Clear warnings shown before applying.","beads_migration":{"original_id":"core-htq","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-756ef7","title":"Phase 3: User Story 1 - New User Bootstraps Project (P1)","description":"A developer new to CDK Terrain can start a fresh project using the new cdktn packages and CLI. This is the MVP - if new users cannot start fresh projects, the rename effort provides no value. Independent Test: Run npx cdktn-cli init and verify generated project has correct @cdktn/* dependencies.","status":"open","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:00:45.719289032+07:00","updated_at":"2026-01-18T16:00:45.719289032+07:00","labels":["phase:us1","spec:001-cdktn-package-rename","story:US1"],"beads_migration":{"original_id":"core-hu1","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-30513f","title":"Update hcl2cdk generated code output","description":"Update the hcl2cdk library to generate CDK code that imports from cdktn instead of cdktf. All generated TypeScript code must reference cdktn packages.","status":"open","priority":3,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:27:14.891664+07:00","updated_at":"2026-01-18T16:27:14.891664+07:00","labels":["component:hcl2cdk","phase:us5","spec:001-cdktn-package-rename","story:US5"],"design":"Files: packages/@cdktf/hcl2cdk/lib/**/*.ts. Find code generation templates/strings that output cdktf imports. Update to cdktn. Ensure generated code compiles with cdktn dependency.","acceptance_criteria":"cdktn convert generates TypeScript with cdktn imports. Generated code compiles successfully.","beads_migration":{"original_id":"core-ikl","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-ee191a","title":"Verify Terraform provider sources unchanged","description":"Verify that synthesized Terraform JSON still references correct provider sources (e.g., hashicorp/aws) without modification. Provider source addresses must NOT change.","status":"open","priority":3,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:19:43.731407489+07:00","updated_at":"2026-01-18T17:17:57.885823815+07:00","labels":["component:cdktf","phase:us3","requirement:FR-020","spec:001-cdktn-package-rename","story:US3"],"design":"Run cdktn synth with provider configuration. Inspect cdk.tf.json output. Verify provider source is hashicorp/aws (not cdktn/aws or similar).","acceptance_criteria":"Synthesized JSON shows hashicorp/aws (or appropriate source). No cdktn references in provider source addresses.","beads_migration":{"original_id":"core-im8","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-b7a221","title":"Run unit test suite","description":"Run the full unit test suite (yarn test) and ensure all tests pass. Fix any test failures caused by rename changes. Update test snapshots if needed.","status":"open","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:29:09.117803726+07:00","updated_at":"2026-01-18T16:29:09.117803726+07:00","labels":["component:test","phase:polish","spec:001-cdktn-package-rename"],"design":"Run yarn test. Review any failures. Tests may need import updates or snapshot regeneration. Do not change test behavior, only references.","acceptance_criteria":"yarn test passes. No regressions introduced.","beads_migration":{"original_id":"core-ixl","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-bdf9c7","title":"Update TypeScript project template","description":"Update the TypeScript cdktn init template to generate projects with cdktn dependencies. Template must reference cdktn package, use cdktn CLI commands in scripts, and import from cdktn.","status":"open","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:01:44.9719836+07:00","updated_at":"2026-01-18T16:01:44.9719836+07:00","labels":["component:templates","phase:us1","requirement:FR-016","spec:001-cdktn-package-rename","story:US1"],"design":"Files: packages/@cdktf/cli-core/src/lib/init/templates/typescript/**. Update: package.json deps (cdktf→cdktn), scripts (cdktf→cdktn), main.ts imports (from cdktn), test imports, .hooks.sscaff.js context vars. Reference research.md Template section.","acceptance_criteria":"cdktn init --template typescript generates project with cdktn imports. Generated project compiles and synthesizes.","beads_migration":{"original_id":"core-j4o","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-74935b","title":"Phase 7: User Story 5 - Developer Converts HCL to CDK (P3)","description":"A developer can convert existing HCL Terraform configurations to CDK code using cdktn convert. Generated code imports from cdktn. This is a specialized workflow used less frequently than core synthesis. Independent Test: Run cdktn convert on HCL file, verify output imports from cdktn.","status":"open","priority":3,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:26:25.474629892+07:00","updated_at":"2026-01-18T16:26:25.474629892+07:00","labels":["phase:us5","spec:001-cdktn-package-rename","story:US5"],"beads_migration":{"original_id":"core-kki","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-8b17f0","title":"Update Java project template","description":"Update the Java template to generate projects with cdktn Maven coordinates. Use io.cdktn:cdktn groupId/artifactId. Note: Java packages built but NOT published to Maven Central in Release 1.","status":"open","priority":2,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:04:03.866925099+07:00","updated_at":"2026-01-18T16:04:03.866925099+07:00","labels":["component:templates","phase:us1","requirement:FR-006","requirement:FR-016","spec:001-cdktn-package-rename","story:US1"],"design":"Files: packages/@cdktf/cli-core/src/lib/init/templates/java/**. Update: build.gradle (io.cdktn:cdktn), Main.java imports (io.cdktn.cdktn.*), MainStack.java, MainTest.java, .hooks.sscaff.js mvn_cdktn var.","acceptance_criteria":"cdktn init --template java generates project with cdktn imports. gradle build succeeds.","beads_migration":{"original_id":"core-lmr","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} +{"id":"SL-603c85","title":"Add migrate command dry-run and validation","description":"Enhance cdktn migrate with dry-run mode (default behavior), pre-run validations, and helpful user messaging. Validate it is a cdktf project, warn about backup recommendations.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:13:22.697589513+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:cli-core","phase:us2","requirement:FR-031","spec:001-cdktn-package-rename","story:US2"],"design":"Files: packages/@cdktf/cli-core/src/lib/commands/migrate.ts. Add --dry-run flag (default true), --apply flag to make changes. Check for cdktf.json presence. Warn users to backup/commit before applying.","acceptance_criteria":"cdktn migrate shows preview by default. cdktn migrate --apply makes changes. Clear warnings shown before applying.","beads_migration":{"original_id":"core-htq","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Not implemented - migrate command deemed unnecessary, migration is simple enough without tooling"} +{"id":"SL-756ef7","title":"Phase 3: User Story 1 - New User Bootstraps Project (P1)","description":"A developer new to CDK Terrain can start a fresh project using the new cdktn packages and CLI. This is the MVP - if new users cannot start fresh projects, the rename effort provides no value. Independent Test: Run npx cdktn-cli init and verify generated project has correct @cdktn/* dependencies.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:00:45.719289032+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["phase:us1","spec:001-cdktn-package-rename","story:US1"],"beads_migration":{"original_id":"core-hu1","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} +{"id":"SL-30513f","title":"Update hcl2cdk generated code output","description":"Update the hcl2cdk library to generate CDK code that imports from cdktn instead of cdktf. All generated TypeScript code must reference cdktn packages.","status":"closed","priority":3,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:27:14.891664+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:hcl2cdk","phase:us5","spec:001-cdktn-package-rename","story:US5"],"design":"Files: packages/@cdktf/hcl2cdk/lib/**/*.ts. Find code generation templates/strings that output cdktf imports. Update to cdktn. Ensure generated code compiles with cdktn dependency.","acceptance_criteria":"cdktn convert generates TypeScript with cdktn imports. Generated code compiles successfully.","beads_migration":{"original_id":"core-ikl","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} +{"id":"SL-ee191a","title":"Verify Terraform provider sources unchanged","description":"Verify that synthesized Terraform JSON still references correct provider sources (e.g., hashicorp/aws) without modification. Provider source addresses must NOT change.","status":"closed","priority":3,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:19:43.731407489+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:cdktf","phase:us3","requirement:FR-020","spec:001-cdktn-package-rename","story:US3"],"design":"Run cdktn synth with provider configuration. Inspect cdk.tf.json output. Verify provider source is hashicorp/aws (not cdktn/aws or similar).","acceptance_criteria":"Synthesized JSON shows hashicorp/aws (or appropriate source). No cdktn references in provider source addresses.","beads_migration":{"original_id":"core-im8","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} +{"id":"SL-b7a221","title":"Run unit test suite","description":"Run the full unit test suite (yarn test) and ensure all tests pass. Fix any test failures caused by rename changes. Update test snapshots if needed.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:29:09.117803726+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:test","phase:polish","spec:001-cdktn-package-rename"],"design":"Run yarn test. Review any failures. Tests may need import updates or snapshot regeneration. Do not change test behavior, only references.","acceptance_criteria":"yarn test passes. No regressions introduced.","beads_migration":{"original_id":"core-ixl","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} +{"id":"SL-bdf9c7","title":"Update TypeScript project template","description":"Update the TypeScript cdktn init template to generate projects with cdktn dependencies. Template must reference cdktn package, use cdktn CLI commands in scripts, and import from cdktn.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:01:44.9719836+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:templates","phase:us1","requirement:FR-016","spec:001-cdktn-package-rename","story:US1"],"design":"Files: packages/@cdktf/cli-core/src/lib/init/templates/typescript/**. Update: package.json deps (cdktf→cdktn), scripts (cdktf→cdktn), main.ts imports (from cdktn), test imports, .hooks.sscaff.js context vars. Reference research.md Template section.","acceptance_criteria":"cdktn init --template typescript generates project with cdktn imports. Generated project compiles and synthesizes.","beads_migration":{"original_id":"core-j4o","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} +{"id":"SL-74935b","title":"Phase 7: User Story 5 - Developer Converts HCL to CDK (P3)","description":"A developer can convert existing HCL Terraform configurations to CDK code using cdktn convert. Generated code imports from cdktn. This is a specialized workflow used less frequently than core synthesis. Independent Test: Run cdktn convert on HCL file, verify output imports from cdktn.","status":"closed","priority":3,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:26:25.474629892+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["phase:us5","spec:001-cdktn-package-rename","story:US5"],"beads_migration":{"original_id":"core-kki","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} +{"id":"SL-8b17f0","title":"Update Java project template","description":"Update the Java template to generate projects with cdktn Maven coordinates. Use io.cdktn:cdktn groupId/artifactId. Note: Java packages built but NOT published to Maven Central in Release 1.","status":"closed","priority":2,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:04:03.866925099+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:templates","phase:us1","requirement:FR-006","requirement:FR-016","spec:001-cdktn-package-rename","story:US1"],"design":"Files: packages/@cdktf/cli-core/src/lib/init/templates/java/**. Update: build.gradle (io.cdktn:cdktn), Main.java imports (io.cdktn.cdktn.*), MainStack.java, MainTest.java, .hooks.sscaff.js mvn_cdktn var.","acceptance_criteria":"cdktn init --template java generates project with cdktn imports. gradle build succeeds.","beads_migration":{"original_id":"core-lmr","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} {"id":"SL-5c5fd0","title":"Update root package.json workspace configuration","description":"Update the root package.json to reflect new workspace package names from @cdktf/* to @cdktn/*. This ensures yarn workspaces resolve the renamed packages correctly.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T15:43:47.818009964+07:00","updated_at":"2026-01-18T21:32:27.232004314+07:00","closed_at":"2026-01-18T21:32:27.232004314+07:00","labels":["component:build","phase:setup","spec:001-cdktn-package-rename"],"design":"Files: /package.json. Update workspaces array references if needed. Keep lerna.json compatible.","acceptance_criteria":"yarn install completes successfully with new workspace package names recognized.","beads_migration":{"original_id":"core-mau","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-ad1d9f","title":"Update generated provider JSII targets","description":"Ensure provider generator outputs correct JSII targets for generated providers. Python module names, Go import paths, Java packages, and C# namespaces should reference cdktn equivalents.","status":"open","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:25:36.234835096+07:00","updated_at":"2026-01-18T16:25:36.234835096+07:00","labels":["component:provider-generator","phase:us4","spec:001-cdktn-package-rename","story:US4"],"design":"Files: packages/@cdktf/provider-generator/lib/**/generate*.ts. Update JSII target configuration in generated package.json to use cdktn namespaces per data-model.md patterns.","acceptance_criteria":"Generated provider JSII targets show cdktn references. jsii-pacmak generates correct cross-language bindings.","beads_migration":{"original_id":"core-nrh","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-b78398","title":"Verify Symbol.for() strings unchanged","description":"Verify all internal Symbol.for('cdktf/*') strings remain unchanged after package renames. Critical for backward compatibility - these symbols are used for runtime type checking and must NOT change or existing CDKTF code breaks.","status":"open","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T21:05:50.497004876+07:00","updated_at":"2026-01-18T21:05:50.497004876+07:00","labels":["component:cdktf","phase:foundational","requirement:FR-012","spec:001-cdktn-package-rename"],"design":"After foundational renames (core-2v8): 1) grep -r 'Symbol\\.for' packages/cdktf/lib, 2) Verify all still use 'cdktf' NOT 'cdktn' (e.g., Symbol.for('@cdktf/...') unchanged), 3) Create test that verifies symbols match between cdktf and cdktn packages, 4) Document which files contain these symbols for future reference.","acceptance_criteria":"All Symbol.for() strings use original 'cdktf' naming. grep shows no Symbol.for('cdktn') or Symbol.for('@cdktn/'). Backward compat test passes.","beads_migration":{"original_id":"core-q5b","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-790c9f","title":"Verify provider generator works without cdktf installed","description":"Verify that cdktn get works correctly when only cdktn is installed (not cdktf). The generator must have no implicit dependency on cdktf being present.","status":"open","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:24:35.028799242+07:00","updated_at":"2026-01-18T16:24:35.028799242+07:00","labels":["component:provider-generator","phase:us4","requirement:FR-024","spec:001-cdktn-package-rename","story:US4"],"design":"Test environment with only cdktn-cli installed (no cdktf-cli). Run cdktn get. Verify provider generation succeeds without cdktf.","acceptance_criteria":"cdktn get succeeds in clean environment with only cdktn installed.","beads_migration":{"original_id":"core-tjr","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} +{"id":"SL-ad1d9f","title":"Update generated provider JSII targets","description":"Ensure provider generator outputs correct JSII targets for generated providers. Python module names, Go import paths, Java packages, and C# namespaces should reference cdktn equivalents.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:25:36.234835096+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:provider-generator","phase:us4","spec:001-cdktn-package-rename","story:US4"],"design":"Files: packages/@cdktf/provider-generator/lib/**/generate*.ts. Update JSII target configuration in generated package.json to use cdktn namespaces per data-model.md patterns.","acceptance_criteria":"Generated provider JSII targets show cdktn references. jsii-pacmak generates correct cross-language bindings.","beads_migration":{"original_id":"core-nrh","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} +{"id":"SL-b78398","title":"Verify Symbol.for() strings unchanged","description":"Verify all internal Symbol.for('cdktf/*') strings remain unchanged after package renames. Critical for backward compatibility - these symbols are used for runtime type checking and must NOT change or existing CDKTF code breaks.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T21:05:50.497004876+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:cdktf","phase:foundational","requirement:FR-012","spec:001-cdktn-package-rename"],"design":"After foundational renames (core-2v8): 1) grep -r 'Symbol\\.for' packages/cdktf/lib, 2) Verify all still use 'cdktf' NOT 'cdktn' (e.g., Symbol.for('@cdktf/...') unchanged), 3) Create test that verifies symbols match between cdktf and cdktn packages, 4) Document which files contain these symbols for future reference.","acceptance_criteria":"All Symbol.for() strings use original 'cdktf' naming. grep shows no Symbol.for('cdktn') or Symbol.for('@cdktn/'). Backward compat test passes.","beads_migration":{"original_id":"core-q5b","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} +{"id":"SL-790c9f","title":"Verify provider generator works without cdktf installed","description":"Verify that cdktn get works correctly when only cdktn is installed (not cdktf). The generator must have no implicit dependency on cdktf being present.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:24:35.028799242+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:provider-generator","phase:us4","requirement:FR-024","spec:001-cdktn-package-rename","story:US4"],"design":"Test environment with only cdktn-cli installed (no cdktf-cli). Run cdktn get. Verify provider generation succeeds without cdktf.","acceptance_criteria":"cdktn get succeeds in clean environment with only cdktn installed.","beads_migration":{"original_id":"core-tjr","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} {"id":"SL-169b7f","title":"Rename packages/@cdktf/hcl2cdk to @cdktn/hcl2cdk","description":"Rename the HCL-to-CDK conversion library. Update package.json name, internal imports, and generated code output references.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T15:55:24.116514278+07:00","updated_at":"2026-01-19T04:23:43.196665372+07:00","closed_at":"2026-01-19T04:23:43.196665372+07:00","labels":["component:hcl2cdk","phase:foundational","spec:001-cdktn-package-rename","story:US5"],"design":"Files: packages/@cdktf/hcl2cdk/package.json. Update name. Ensure generated CDK code outputs cdktn imports (not cdktf).","acceptance_criteria":"Package builds. cdktn convert generates code with cdktn imports.","beads_migration":{"original_id":"core-tsu","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-c7617e","title":"Implement cdktn migrate command - Python support","description":"Extend cdktn migrate to support Python projects. Update requirements.txt/Pipfile dependencies and Python import statements.","status":"open","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:12:03.289563249+07:00","updated_at":"2026-01-18T16:12:03.289563249+07:00","labels":["component:cli-core","phase:us2","requirement:FR-029","spec:001-cdktn-package-rename","story:US2"],"design":"Files: packages/@cdktf/cli-core/src/lib/commands/migrate.ts. Add Python file detection. Replace cdktf imports with cdktn per data-model.md patterns. Update requirements.txt/Pipfile cdktf→cdktn.","acceptance_criteria":"cdktn migrate works on Python cdktf projects. Imports updated from cdktf to cdktn.","beads_migration":{"original_id":"core-u4l","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-192e5c","title":"Add dual-dependency detection warning (optional)","description":"Optionally add runtime warning when both cdktf and cdktn packages are detected in the same project. Per research.md this is supported but not recommended long-term.","status":"open","priority":3,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:14:32.181365448+07:00","updated_at":"2026-01-18T16:14:32.181365448+07:00","labels":["component:cdktf","phase:us2","requirement:FR-026","spec:001-cdktn-package-rename","story:US2"],"design":"Files: packages/cdktf/lib/app.ts or appropriate startup hook. Check require.cache or process modules for both cdktf and cdktn. Log warning recommending migration completion.","acceptance_criteria":"Project with both cdktf and cdktn deps shows optional warning at synthesis time.","beads_migration":{"original_id":"core-unc","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-b7f54b","title":"Verify end-to-end workflow: init → synth → get → convert","description":"Complete end-to-end verification of all major CLI workflows. Test the full user journey from project creation to synthesis.","status":"open","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:34:15.731755465+07:00","updated_at":"2026-01-18T16:34:15.731755465+07:00","labels":["component:test","phase:polish","spec:001-cdktn-package-rename"],"design":"Test each workflow: 1) cdktn init --template typescript → cdktn synth 2) cdktn init with provider config → cdktn get → cdktn synth 3) cdktn convert on sample HCL. Verify each produces valid output.","acceptance_criteria":"All major workflows complete successfully. Init creates valid project, synth produces Terraform JSON, get generates providers, convert generates CDK code.","beads_migration":{"original_id":"core-vfv","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-860e3f","title":"Add cdktn get recommendation in migrate","description":"When cdktn migrate detects @cdktf/provider-* dependencies without @cdktn/provider-* equivalents available, recommend using cdktn get to generate local providers for a clean migration.","status":"open","priority":2,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:14:03.534807728+07:00","updated_at":"2026-01-18T16:14:03.534807728+07:00","labels":["component:cli-core","phase:us2","requirement:FR-032","spec:001-cdktn-package-rename","story:US2"],"design":"Files: packages/@cdktf/cli-core/src/lib/commands/migrate.ts. After analyzing deps, check for @cdktf/provider-* packages. Output recommendation to use cdktn get for clean migration path.","acceptance_criteria":"cdktn migrate on project with @cdktf/provider-aws shows recommendation to use cdktn get.","beads_migration":{"original_id":"core-vmx","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} +{"id":"SL-c7617e","title":"Implement cdktn migrate command - Python support","description":"Extend cdktn migrate to support Python projects. Update requirements.txt/Pipfile dependencies and Python import statements.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:12:03.289563249+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:cli-core","phase:us2","requirement:FR-029","spec:001-cdktn-package-rename","story:US2"],"design":"Files: packages/@cdktf/cli-core/src/lib/commands/migrate.ts. Add Python file detection. Replace cdktf imports with cdktn per data-model.md patterns. Update requirements.txt/Pipfile cdktf→cdktn.","acceptance_criteria":"cdktn migrate works on Python cdktf projects. Imports updated from cdktf to cdktn.","beads_migration":{"original_id":"core-u4l","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Not implemented - migrate command deemed unnecessary, migration is simple enough without tooling"} +{"id":"SL-192e5c","title":"Add dual-dependency detection warning (optional)","description":"Optionally add runtime warning when both cdktf and cdktn packages are detected in the same project. Per research.md this is supported but not recommended long-term.","status":"closed","priority":3,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:14:32.181365448+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:cdktf","phase:us2","requirement:FR-026","spec:001-cdktn-package-rename","story:US2"],"design":"Files: packages/cdktf/lib/app.ts or appropriate startup hook. Check require.cache or process modules for both cdktf and cdktn. Log warning recommending migration completion.","acceptance_criteria":"Project with both cdktf and cdktn deps shows optional warning at synthesis time.","beads_migration":{"original_id":"core-unc","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} +{"id":"SL-b7f54b","title":"Verify end-to-end workflow: init → synth → get → convert","description":"Complete end-to-end verification of all major CLI workflows. Test the full user journey from project creation to synthesis.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:34:15.731755465+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:test","phase:polish","spec:001-cdktn-package-rename"],"design":"Test each workflow: 1) cdktn init --template typescript → cdktn synth 2) cdktn init with provider config → cdktn get → cdktn synth 3) cdktn convert on sample HCL. Verify each produces valid output.","acceptance_criteria":"All major workflows complete successfully. Init creates valid project, synth produces Terraform JSON, get generates providers, convert generates CDK code.","beads_migration":{"original_id":"core-vfv","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} +{"id":"SL-860e3f","title":"Add cdktn get recommendation in migrate","description":"When cdktn migrate detects @cdktf/provider-* dependencies without @cdktn/provider-* equivalents available, recommend using cdktn get to generate local providers for a clean migration.","status":"closed","priority":2,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:14:03.534807728+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:cli-core","phase:us2","requirement:FR-032","spec:001-cdktn-package-rename","story:US2"],"design":"Files: packages/@cdktf/cli-core/src/lib/commands/migrate.ts. After analyzing deps, check for @cdktf/provider-* packages. Output recommendation to use cdktn get for clean migration path.","acceptance_criteria":"cdktn migrate on project with @cdktf/provider-aws shows recommendation to use cdktn get.","beads_migration":{"original_id":"core-vmx","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Not implemented - migrate command deemed unnecessary, migration is simple enough without tooling"} {"id":"SL-c5f45d","title":"Rename packages/cdktf to cdktn - core library","description":"Rename the core cdktf package to cdktn. This is the main library consumed by all users. Update package.json name, JSII targets for Python/Java/C#/Go, and update all internal cross-references. MUST preserve Symbol.for() strings unchanged.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T15:51:26.15615569+07:00","updated_at":"2026-01-19T04:15:18.877327576+07:00","closed_at":"2026-01-19T04:15:18.877327576+07:00","labels":["component:cdktf","phase:foundational","requirement:FR-001","requirement:FR-002","spec:001-cdktn-package-rename"],"design":"Files: packages/cdktf/package.json. Update: name cdktf→cdktn, JSII python distName/module, java groupId/artifactId, dotnet packageId/namespace, go moduleName. Reference data-model.md for exact mappings. DO NOT change any Symbol.for() strings in lib/*.ts files.","acceptance_criteria":"Package builds successfully with jsii. Generated .jsii manifest shows new names. yarn test passes.","beads_migration":{"original_id":"core-w61","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-fb9ab2","title":"Phase 4: User Story 2 - Existing User Migrates from CDKTF (P1)","description":"An existing CDKTF user can migrate their project to cdktn packages while preserving Terraform state. Migration path for existing users is equally critical - without safe migration, existing users cannot adopt the fork. Independent Test: Take existing CDKTF project, update deps/imports, verify cdktn synth produces identical output.","status":"open","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:07:13.609400048+07:00","updated_at":"2026-01-18T16:07:13.609400048+07:00","labels":["phase:us2","spec:001-cdktn-package-rename","story:US2"],"beads_migration":{"original_id":"core-w6w","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-4ac993","title":"CDKTN Package Rename (Release 1)","description":"Rename all public-facing package names, modules, and CLI commands from cdktf to cdktn for the cdk-terrain community fork. Preserves internal symbols and logical IDs for backward compatibility. Enables community fork identity while allowing existing users to migrate without infrastructure state drift.","status":"open","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T15:22:27.568615641+07:00","updated_at":"2026-01-18T15:22:27.568615641+07:00","labels":["component:cdktf","component:cdktf-cli","component:cli-core","component:provider-generator","spec:001-cdktn-package-rename"],"beads_migration":{"original_id":"core-x3d","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} +{"id":"SL-fb9ab2","title":"Phase 4: User Story 2 - Existing User Migrates from CDKTF (P1)","description":"An existing CDKTF user can migrate their project to cdktn packages while preserving Terraform state. Migration path for existing users is equally critical - without safe migration, existing users cannot adopt the fork. Independent Test: Take existing CDKTF project, update deps/imports, verify cdktn synth produces identical output.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:07:13.609400048+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["phase:us2","spec:001-cdktn-package-rename","story:US2"],"beads_migration":{"original_id":"core-w6w","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Not implemented - migrate command deemed unnecessary, migration is simple enough without tooling"} +{"id":"SL-4ac993","title":"CDKTN Package Rename (Release 1)","description":"Rename all public-facing package names, modules, and CLI commands from cdktf to cdktn for the cdk-terrain community fork. Preserves internal symbols and logical IDs for backward compatibility. Enables community fork identity while allowing existing users to migrate without infrastructure state drift.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T15:22:27.568615641+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:cdktf","component:cdktf-cli","component:cli-core","component:provider-generator","spec:001-cdktn-package-rename"],"beads_migration":{"original_id":"core-x3d","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} {"id":"SL-c57e8e","title":"Rename packages/@cdktf/hcl-tools to @cdktn/hcl-tools","description":"Rename the HCL tools utility package. Update package.json name and all consumer imports.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T15:54:51.307041312+07:00","updated_at":"2026-01-19T04:21:49.974450348+07:00","closed_at":"2026-01-19T04:21:49.974450348+07:00","labels":["component:hcl-tools","phase:foundational","spec:001-cdktn-package-rename"],"design":"Files: packages/@cdktf/hcl-tools/package.json. Update name. Search and update imports.","acceptance_criteria":"Package builds. All dependent packages compile.","beads_migration":{"original_id":"core-y0k","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} -{"id":"SL-5604fd","title":"Update Go project template","description":"Update the Go template to generate projects with cdktn module imports. Use the new Go module path github.com/open-constructs/cdk-terrain-go/cdktn.","status":"open","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:03:30.658525578+07:00","updated_at":"2026-01-18T16:03:30.658525578+07:00","labels":["component:templates","phase:us1","requirement:FR-005","requirement:FR-016","spec:001-cdktn-package-rename","story:US1"],"design":"Files: packages/@cdktf/cli-core/src/lib/init/templates/go/**. Update: go.mod (module path), main.go imports, main_test.go imports, .hooks.sscaff.js go_cdktn var.","acceptance_criteria":"cdktn init --template go generates project with cdktn imports. go build succeeds.","beads_migration":{"original_id":"core-zx5","migrated_at":"2026-03-20T13:10:00.194406+07:00"}} +{"id":"SL-5604fd","title":"Update Go project template","description":"Update the Go template to generate projects with cdktn module imports. Use the new Go module path github.com/open-constructs/cdk-terrain-go/cdktn.","status":"closed","priority":1,"issue_type":"task","spec_context":"001-cdktn-package-rename","created_at":"2026-01-18T16:03:30.658525578+07:00","updated_at":"2026-03-20T06:48:02.000000000+00:00","labels":["component:templates","phase:us1","requirement:FR-005","requirement:FR-016","spec:001-cdktn-package-rename","story:US1"],"design":"Files: packages/@cdktf/cli-core/src/lib/init/templates/go/**. Update: go.mod (module path), main.go imports, main_test.go imports, .hooks.sscaff.js go_cdktn var.","acceptance_criteria":"cdktn init --template go generates project with cdktn imports. go build succeeds.","beads_migration":{"original_id":"core-zx5","migrated_at":"2026-03-20T13:10:00.194406+07:00"},"closed_at":"2026-03-20T06:48:02.000000000+00:00","close_reason":"Released in v0.22.0"} diff --git a/specledger/002-remove-hashicorp-telemetry/checklists/requirements.md b/specledger/002-remove-hashicorp-telemetry/checklists/requirements.md new file mode 100644 index 000000000..256c3a0b3 --- /dev/null +++ b/specledger/002-remove-hashicorp-telemetry/checklists/requirements.md @@ -0,0 +1,38 @@ +# Specification Quality Checklist: Replace HashiCorp Telemetry with Sentry Analytics + +**Purpose**: Validate specification completeness and quality before proceeding to planning +**Created**: 2026-03-20 +**Feature**: [spec.md](../spec.md) + +## Content Quality + +- [x] No implementation details (languages, frameworks, APIs) +- [x] Focused on user value and business needs +- [x] Written for non-technical stakeholders +- [x] All mandatory sections completed + +## Requirement Completeness + +- [x] No [NEEDS CLARIFICATION] markers remain +- [x] Requirements are testable and unambiguous +- [x] Success criteria are measurable +- [x] Success criteria are technology-agnostic (no implementation details) +- [x] All acceptance scenarios are defined +- [x] Edge cases are identified +- [x] Scope is clearly bounded +- [x] Dependencies and assumptions identified + +## Feature Readiness + +- [x] All functional requirements have clear acceptance criteria +- [x] User scenarios cover primary flows +- [x] Feature meets measurable outcomes defined in Success Criteria +- [x] No implementation details leak into specification + +## Notes + +- All items pass validation. Spec is ready for `/specledger.plan`. +- Scope expanded from "remove" to "replace" — usage analytics migrated to Sentry instead of deleted. +- SDK compatibility verified via spike research (no upgrade needed). +- Three research spikes inform this spec — linked in the Research section. +- Consent flow reuse confirmed — no new opt-out mechanism required. diff --git a/specledger/002-remove-hashicorp-telemetry/research/2026-03-20-checkpoint-usage-analysis.md b/specledger/002-remove-hashicorp-telemetry/research/2026-03-20-checkpoint-usage-analysis.md new file mode 100644 index 000000000..1aded2681 --- /dev/null +++ b/specledger/002-remove-hashicorp-telemetry/research/2026-03-20-checkpoint-usage-analysis.md @@ -0,0 +1,118 @@ +# Research: What checkpoint.ts does and where it is used + +**Date**: 2026-03-20 +**Context**: Need to understand the full blast radius before removing HashiCorp telemetry endpoint (Issue #48) +**Time-box**: 15 minutes + +## Question + +What does `packages/@cdktn/commons/src/checkpoint.ts` do, what are all its exports, and where is each export used across the codebase? + +## Findings + +### Finding 1: checkpoint.ts has two distinct responsibilities + +The file serves two purposes: + +1. **HashiCorp checkpoint telemetry** (TO REMOVE): Sends usage data to `https://checkpoint-api.hashicorp.com/v1/telemetry/cdktn` via HTTP POST. This includes command name, language, OS, arch, CI info, user ID, project ID, and arbitrary payload data. + +2. **ID generation utilities** (TO KEEP): `getUserId()` and `getProjectId()` generate/persist UUIDs for identifying users and projects. These are used by Sentry error reporting. + +**Exports:** +| Export | Type | Used by HashiCorp telemetry | Used by Sentry | Action | +|--------|------|---------------------------|----------------|--------| +| `sendTelemetry()` | function | Yes - wraps ReportRequest | No | Remove | +| `ReportRequest()` | function | Yes - sends HTTP POST to HashiCorp | No | Remove | +| `ReportParams` | interface | Yes - shapes telemetry payload | No | Remove | +| `getUserId()` | function | Yes - enriches telemetry | Yes - Sentry scope tagging | Keep | +| `getProjectId()` | function | Yes - enriches telemetry | Yes - Sentry scope tagging | Keep | + +**Internal (non-exported):** +| Symbol | Purpose | Action | +|--------|---------|--------| +| `BASE_URL` | HashiCorp endpoint URL | Remove | +| `post()` | HTTP POST helper | Remove | +| `getId()` | Shared UUID helper for getUserId/getProjectId | Keep | +| `homeDir()` | Resolves ~/.cdktf path | Keep | + +### Finding 2: sendTelemetry has 7 call sites across 5 files + +All call sites send usage analytics to HashiCorp. None are related to Sentry. + +| File | Line | Command | What it reports | +|------|------|---------|-----------------| +| `cli-core/src/lib/watch.ts` | 184 | `"watch"` | Event: start | +| `cli-core/src/lib/synth-stack.ts` | 279 | `"synth"` | Language, timing, stack metadata, providers | +| `cli-core/src/lib/synth-stack.ts` | 294 | `"synth"` | Error flag | +| `cli-core/src/lib/cdktf-project.ts` | 648 | varies | Language + command-specific payload | +| `cdktn-cli/src/bin/cmds/handlers.ts` | 169 | `"convert"` | Conversion stats | +| `cdktn-cli/src/bin/cmds/helper/init.ts` | 285 | `"init"` | Template, language, providers | +| `cdktn-cli/src/bin/cmds/ui/get.tsx` | 58 | `"get"` | Provider get payload | + +### Finding 3: errors.ts has a hidden HashiCorp telemetry path + +`packages/@cdktn/commons/src/errors.ts` imports `ReportRequest` and calls it via a private `report()` function. Every time `Errors.Internal()`, `Errors.External()`, or `Errors.Usage()` is called, it sends error details to HashiCorp's endpoint **in addition to** Sentry (which is handled separately via `Sentry.configureScope` in the same file). + +This is a **fire-and-forget** call — the `report()` result is not awaited in `reportPrefixedError`, so the error creation doesn't depend on the telemetry succeeding. This means removing `report()` won't change error behavior. + +### Finding 4: getUserId and getProjectId are shared with Sentry + +`packages/@cdktn/cli-core/src/lib/error-reporting.ts` (lines 120-125): +```typescript +Sentry.configureScope(function (scope) { + scope.setUser({ id: getUserId() }); + scope.setTag("projectId", getProjectId()); +}); +``` + +These functions MUST be preserved. They currently live in `checkpoint.ts` but should be relocated to a more appropriate module (e.g., a new `identity.ts` or kept in a stripped-down `checkpoint.ts`). + +### Finding 5: CHECKPOINT_DISABLE is set in 14 CI workflow locations + +All GitHub Actions workflows set `CHECKPOINT_DISABLE: "1"` as a global env var. Affected files: +- `build.yml`, `unit.yml`, `examples.yml`, `pr-depcheck.yml` +- `integration.yml` (3 locations) +- `provider-integration.yml` (3 locations) +- `release.yml`, `release_next.yml` +- `registry-docs-pr-based.yml` (2 locations) + +These can be cleaned up after removal, but are low priority since setting an unused env var is harmless. + +### Finding 6: Dependency analysis + +| Dependency | Used in checkpoint.ts | Used elsewhere | Action | +|------------|----------------------|----------------|--------| +| `uuid` | `getId()` (line 104), `ReportRequest()` (line 160) | `init.ts` (line 143 for project ID generation) | Keep — used by `getId()` which is preserved, and by `init.ts` | +| `ci-info` | `ReportRequest()` (line 175) | `error-reporting.ts` (line 13, for Sentry CI detection) | Keep — used by Sentry | +| `https` (node built-in) | `post()` function | N/A | No action needed | + +### Finding 7: Test file is entirely HashiCorp-specific + +`packages/@cdktn/cli-core/src/test/checkpoint.test.ts` tests only `ReportRequest` against the HashiCorp endpoint using `nock`. The entire file can be deleted. + +## Decisions + +- **Decision 1**: Split `checkpoint.ts` — extract `getUserId()`, `getProjectId()`, `getId()`, and `homeDir()` into a preserved module. Remove everything else (`sendTelemetry`, `ReportRequest`, `ReportParams`, `post`, `BASE_URL`). +- **Decision 2**: Remove the `report()` function and `ReportRequest`/`ReportParams` imports from `errors.ts`. The `Errors` object and its Sentry integration remain unchanged. +- **Decision 3**: Keep `uuid` and `ci-info` dependencies — both are used outside the checkpoint system. +- **Decision 4**: Delete `checkpoint.test.ts` entirely — it only tests HashiCorp endpoint communication. +- **Decision 5**: `CHECKPOINT_DISABLE` env var in CI workflows can be cleaned up as a low-priority follow-up. Setting an unused env var is harmless. +- **Decision 6**: `CHECKPOINT_DISABLE` in `environment.ts` should be removed since nothing will reference it after checkpoint removal. + +## Recommendations + +1. **Refactor checkpoint.ts**: Rename to `identity.ts` (or similar) containing only `getUserId`, `getProjectId`, `getId`, `homeDir`. Update `index.ts` export accordingly. +2. **Remove 7 sendTelemetry call sites** across watch.ts, synth-stack.ts, cdktf-project.ts, handlers.ts, init.ts, get.tsx. +3. **Clean up errors.ts**: Remove `report()` function, `ReportRequest`/`ReportParams` imports. Keep `Errors` object and Sentry integration. +4. **Delete checkpoint.test.ts**. +5. **Remove `CHECKPOINT_DISABLE` from environment.ts**. +6. **Low priority**: Clean up `CHECKPOINT_DISABLE: "1"` from 14 CI workflow env vars. + +## References + +- Issue: https://github.com/open-constructs/cdk-terrain/issues/48 +- Checkpoint.ts: `packages/@cdktn/commons/src/checkpoint.ts` +- Error reporting: `packages/@cdktn/cli-core/src/lib/error-reporting.ts` +- Errors module: `packages/@cdktn/commons/src/errors.ts` +- Environment: `packages/@cdktn/commons/src/environment.ts` +- Checkpoint tests: `packages/@cdktn/cli-core/src/test/checkpoint.test.ts` diff --git a/specledger/002-remove-hashicorp-telemetry/research/2026-03-20-sentry-usage-and-checkpoint-migration.md b/specledger/002-remove-hashicorp-telemetry/research/2026-03-20-sentry-usage-and-checkpoint-migration.md new file mode 100644 index 000000000..2270df0ed --- /dev/null +++ b/specledger/002-remove-hashicorp-telemetry/research/2026-03-20-sentry-usage-and-checkpoint-migration.md @@ -0,0 +1,148 @@ +# Research: Sentry usage and whether checkpoint functionality should move to Sentry + +**Date**: 2026-03-20 +**Context**: Before removing HashiCorp checkpoint telemetry, need to understand the full Sentry integration and whether any checkpoint data should be preserved via Sentry instead. +**Time-box**: 30 minutes + +## Question + +What is the full scope of Sentry usage in the codebase, and should any of the data currently sent to HashiCorp's checkpoint API be migrated to Sentry instead of simply deleted? + +## Findings + +### Finding 1: Sentry provides usage analytics features — not just error tracking + +**UPDATE (2026-03-20)**: Sentry now offers [custom metrics](https://docs.sentry.io/product/explore/metrics/) (counters, gauges, distributions) that are trace-connected, meaning every metric event can be linked back to traces, logs, and errors. This is suitable for the kind of usage telemetry currently sent to HashiCorp's checkpoint API. + +Key Sentry analytics capabilities: + +- **Custom metrics**: Send counters (e.g., `command.invoked`), gauges, and distributions from code +- **Trace-connected**: Every metric links to related traces and errors — richer than what checkpoint provides +- **Span metrics**: Performance data automatically derived from spans ([span metrics docs](https://docs.sentry.io/concepts/key-terms/tracing/span-metrics/)) +- **Dashboards**: Built-in exploration and visualization of metrics data +- **SDK support**: Available for JavaScript/Node.js, Python, and all languages cdktn targets + +**Note on Sentry Metrics evolution**: Sentry [deprecated their original custom metrics SDK API](https://develop.sentry.dev/sdk/telemetry/metrics/) and rebuilt it on top of their new Event Analytics Platform (EAP), which stores every metric event independently in ClickHouse and connects it to trace IDs. The new approach is span-based metrics. Implementation should target the current (non-deprecated) API. + +**Confidence**: High — verified via [Sentry docs](https://docs.sentry.io/product/explore/metrics/) and [Sentry blog](https://blog.sentry.io/the-metrics-product-we-built-worked-but-we-killed-it-and-started-over-anyway/). + +### Finding 2: Sentry is a strong fit for migrating checkpoint analytics + +The project has Sentry on a **full business plan with OSS support**, which includes metrics features. Migrating usage telemetry to Sentry instead of simply deleting it provides: + +| Benefit | Details | +|---------|---------| +| **Feature prioritization** | Know which commands, languages, and providers are actually used | +| **Project evolution** | Data-driven decisions about what to build/deprecate | +| **Single platform** | No new vendor — reuse existing Sentry infrastructure, DSN, and consent flow | +| **User opt-out preserved** | Existing `sendCrashReports` consent in `cdktf.json` already gates Sentry; usage telemetry respects the same opt-out | +| **Trace correlation** | Usage metrics linked to errors — see which commands fail most, not just that they were used | +| **No additional cost** | Already on business plan with analytics features included | + +What checkpoint currently tracks (and should be preserved via Sentry): + +| Data point | Sentry mechanism | Value | +|------------|-----------------|-------| +| Command invoked (`synth`, `init`, `deploy`, etc.) | Custom metric counter or span | Feature adoption tracking | +| Language used (`typescript`, `python`, etc.) | Metric tag / span attribute | Language support prioritization | +| CLI version | Already set as Sentry release | Version adoption tracking | +| OS / arch | Already captured in Sentry environment context | Platform support decisions | +| CI environment | Metric tag / span attribute | CI vs interactive usage patterns | +| Synth timing | Span duration or distribution metric | Performance monitoring | +| Provider usage | Metric tag | Provider ecosystem priorities | + +### Finding 3: Current Sentry integration serves crash/error reporting only + +Today, the codebase uses Sentry exclusively for **error reporting and crash diagnostics**: + +| Component | File | What it does | +|-----------|------|-------------| +| Initialization | `cli-core/src/lib/error-reporting.ts` | `Sentry.init()` with session tracking, custom `beforeSend` filter | +| User context | `cli-core/src/lib/error-reporting.ts` | Sets `userId` and `projectId` as Sentry scope tags | +| Environment context | `cli-core/src/lib/error-reporting.ts` | Attaches debug info (versions, OS, etc.) | +| Breadcrumbs | `commons/src/logging.ts` | Every log call (`trace`→`fatal`) adds a Sentry breadcrumb | +| Error scope | `commons/src/errors.ts` | `Errors.setScope()` sets Sentry transaction name | +| Flush on exit | `cdktn-cli/src/bin/cdktn.ts` | `Sentry.close(4000)` in error handler | +| Exception capture | `cli-core/src/lib/error-reporting.ts` | `captureException()` wraps `Sentry.captureException()` | + +**Confidence**: High — comprehensive search of all `@sentry/node` imports. + +### Finding 4: The errors.ts → checkpoint path is a redundant telemetry channel + +`errors.ts` has a `report()` function that sends error metadata to HashiCorp's checkpoint API whenever `Errors.Internal/External/Usage()` is called. This is **separate from Sentry** — the same errors go to both: + +1. **Sentry** (via breadcrumbs in logging.ts + scope tags + captureException) +2. **HashiCorp checkpoint** (via `report()` → `ReportRequest()` → `post()`) + +The HashiCorp path is redundant. Sentry already captures these errors with richer context (stack traces, breadcrumbs, environment info). The `report()` function in errors.ts should be removed — Sentry handles this better. + +**Error volume**: ~80 call sites across the codebase use `Errors.Internal/External/Usage`: +- `Errors.Usage()`: ~45 call sites +- `Errors.Internal()`: ~20 call sites +- `Errors.External()`: ~15 call sites + +Every one of these currently fires-and-forgets a report to HashiCorp. None depend on the result. + +**Confidence**: High. + +### Finding 5: Sentry initialization is consent-gated and lazy + +- **Opt-in**: Controlled by `sendCrashReports` field in `cdktf.json` +- **Consent prompt**: Users are asked on first CLI use (non-CI only) +- **Lazy**: Initialized per-command in `handlers.ts` (9 command handlers call `initializErrorReporting`) +- **SENTRY_DSN required**: Built into the CLI bundle at build time via esbuild define; if not set, Sentry is disabled +- **CI skip**: No consent prompt in CI environments + +Usage telemetry migration to Sentry can reuse this same consent gate — if the user has opted out of crash reports, usage telemetry is also suppressed. This maintains the existing privacy contract. + +**Confidence**: High. + +### Finding 6: Dependencies are shared but separable + +| Dependency | checkpoint.ts | Sentry/errors | Can remove? | +|------------|--------------|---------------|-------------| +| `@sentry/node` | No | Yes (3 packages) | No — Sentry needs it | +| `uuid` | `getId()`, `ReportRequest()` | No direct use, but `getUserId()` uses it | No — `getUserId()` preserved for Sentry | +| `ci-info` | `ReportRequest()` | `error-reporting.ts` | No — Sentry needs it | +| `https` (builtin) | `post()` | No | N/A — builtin | + +### Finding 7: captureException is defined but never called externally + +The custom `captureException()` function in `error-reporting.ts` is exported but **has zero external callers**. This is dead code that could be cleaned up, but that's outside the scope of the checkpoint removal. + +**Confidence**: High — grep found no imports of this function outside its definition file. + +## Decisions + +- **Decision 1: Migrate checkpoint usage analytics to Sentry.** Sentry's metrics and span-based analytics provide the same (and richer) capabilities as HashiCorp's checkpoint API. The project has a full Sentry business plan with OSS support, so these features are available at no additional cost. Usage data helps the project evolve, prioritize features, and understand adoption patterns. Users can still opt out via the existing `sendCrashReports` consent mechanism. + +- **Decision 2: The `report()` function in errors.ts is fully redundant with Sentry.** Every error that goes to HashiCorp via `report()` is already captured by Sentry with richer context. Safe to remove entirely — no need to migrate this path. + +- **Decision 3: Replace `sendTelemetry` call sites with Sentry spans/metrics.** The 7 existing `sendTelemetry` call sites should be converted to emit Sentry custom metrics or spans instead of POSTing to HashiCorp. This preserves the analytics data while routing it through infrastructure the project controls. + +- **Decision 4: Reuse existing consent flow.** The `sendCrashReports` opt-out in `cdktf.json` already gates all Sentry activity. Usage telemetry sent via Sentry will automatically respect this setting — no new consent mechanism needed. + +## Recommendations + +1. **Remove HashiCorp-specific code** — delete `ReportRequest`, `ReportParams`, `post()`, `BASE_URL`, and the `report()` function in errors.ts. These are the HashiCorp-specific transport layer. + +2. **Replace `sendTelemetry` with Sentry-based telemetry** — convert the 7 call sites to use Sentry custom metrics or spans. Preserve the same data points (command, language, OS, CI, timing) but route through Sentry instead of HashiCorp. + +3. **Preserve `getUserId`/`getProjectId`** — relocate to a new module (e.g., `identity.ts`). These are used by both Sentry error reporting and will be used by the new telemetry. + +4. **Target Sentry's current (non-deprecated) metrics API** — use span-based metrics, not the deprecated `metrics.incr()` SDK API. Check `@sentry/node` 7.120.4 capabilities or evaluate upgrading to the latest SDK version if needed for metrics support. + +5. **Consider renaming `sendCrashReports` to a broader telemetry consent flag** — since it now gates both crash reports and usage analytics, a name like `sendTelemetry` or `telemetryEnabled` may be clearer. However, this is a breaking config change and should be weighed against backward compatibility (could accept both names). + +## References + +- [Sentry Metrics](https://docs.sentry.io/product/explore/metrics/) +- [Sentry Span Metrics](https://docs.sentry.io/concepts/key-terms/tracing/span-metrics/) +- [Sentry Metrics rebuild blog post](https://blog.sentry.io/the-metrics-product-we-built-worked-but-we-killed-it-and-started-over-anyway/) +- [Sentry Metrics SDK (deprecated)](https://develop.sentry.dev/sdk/telemetry/metrics/) +- Error reporting: `packages/@cdktn/cli-core/src/lib/error-reporting.ts` +- Errors module: `packages/@cdktn/commons/src/errors.ts` +- Logging breadcrumbs: `packages/@cdktn/commons/src/logging.ts` +- CLI entry point: `packages/cdktn-cli/src/bin/cdktn.ts` +- Build config (SENTRY_DSN): `packages/cdktn-cli/build.ts` +- Prior research: `specledger/002-remove-hashicorp-telemetry/research/2026-03-20-checkpoint-usage-analysis.md` diff --git a/specledger/002-remove-hashicorp-telemetry/research/2026-03-20-testing-strategy-and-sentry-sdk-validation.md b/specledger/002-remove-hashicorp-telemetry/research/2026-03-20-testing-strategy-and-sentry-sdk-validation.md new file mode 100644 index 000000000..5f8d5c87b --- /dev/null +++ b/specledger/002-remove-hashicorp-telemetry/research/2026-03-20-testing-strategy-and-sentry-sdk-validation.md @@ -0,0 +1,213 @@ +# Research: Testing strategy, Sentry SDK validation, and migration feasibility + +**Date**: 2026-03-20 +**Context**: Before committing to Option B (migrate analytics to Sentry), we need to confirm the SDK supports metrics, understand the test infrastructure, and design a fast validation loop. +**Time-box**: 25 minutes + +## Question + +Can we validate Sentry metrics in isolation to get fast feedback on the migration, and what does the testing strategy look like? + +## Findings + +### Finding 1: The "big if" is resolved — @sentry/node@7.120.4 fully supports custom metrics + +The installed SDK (`@sentry/node@7.120.3` resolved from `7.120.4` range) has a complete metrics API: + +```typescript +import * as Sentry from "@sentry/node"; + +// Counter — perfect for command invocation tracking +Sentry.metrics.increment("command.invoked", 1, { + tags: { command: "synth", language: "typescript" }, +}); + +// Distribution — perfect for synth timing +Sentry.metrics.distribution("synth.duration", totalTimeMs, { + unit: "millisecond", + tags: { language: "typescript", ci: "github-actions" }, +}); + +// Set — track unique users/projects +Sentry.metrics.set("unique.projects", projectId, { + tags: { language: "python" }, +}); + +// Gauge — track current values +Sentry.metrics.gauge("providers.count", 3, { + tags: { command: "get" }, +}); +``` + +**One setup requirement**: Add `metricsAggregatorIntegration()` to `Sentry.init()`: + +```typescript +Sentry.init({ + dsn: process.env.SENTRY_DSN, + integrations: [ + Sentry.metricsAggregatorIntegration(), // enables metrics + ], +}); +``` + +**API status**: Marked `@experimental` but fully functional. Metrics are bucketed into 10-second intervals and flushed automatically. Max 10,000 metrics in memory. + +**Confidence**: High — verified directly in `node_modules/@sentry/core/types/metrics/exports.d.ts`. + +### Finding 2: No SDK upgrade needed + +The current `@sentry/node@7.120.4` across all 3 packages (`commons`, `cli-core`, `cdktn-cli`) already has everything needed. No version bump, no breaking changes, no risk. + +This eliminates the biggest risk identified in the effort estimate. The migration is purely about: +1. Adding `metricsAggregatorIntegration()` to `Sentry.init()` (1 line) +2. Converting 7 `sendTelemetry()` call sites to `Sentry.metrics.*` calls +3. Removing HashiCorp-specific code + +### Finding 3: Current test infrastructure and gaps + +**What exists:** +| Test | File | What it covers | +|------|------|---------------| +| Checkpoint unit tests | `cli-core/src/test/checkpoint.test.ts` | `ReportRequest` HTTP behavior, `CHECKPOINT_DISABLE` env var | + +**What doesn't exist (and doesn't need to):** +- No Sentry mock tests — Sentry is never initialized in tests (no `SENTRY_DSN`) +- No `sendTelemetry()` unit tests — only `ReportRequest` is tested +- No error-reporting.ts tests +- No logger breadcrumb tests + +**How telemetry is disabled in tests:** +- Unit tests: `SENTRY_DSN` not set → Sentry init skips. `CHECKPOINT_DISABLE=1` set in CI workflows → checkpoint skips. +- Integration tests: `--enable-crash-reporting=false` flag in `TestDriver.init()` + +**Test runner**: Jest 29.7 + ts-jest. No global Sentry mocks. Fast per-package feedback: +```bash +cd packages/@cdktn/commons && yarn jest # seconds +cd packages/@cdktn/cli-core && yarn jest # seconds +``` + +### Finding 4: Isolated validation is straightforward + +We can validate Sentry metrics **without running the full CLI** by writing a focused unit test that mocks Sentry: + +```typescript +// packages/@cdktn/commons/src/test/telemetry.test.ts +import * as Sentry from "@sentry/node"; + +jest.mock("@sentry/node", () => ({ + metrics: { + increment: jest.fn(), + distribution: jest.fn(), + set: jest.fn(), + gauge: jest.fn(), + }, +})); + +describe("telemetry", () => { + it("sends command metric via Sentry", () => { + // Call the new telemetry function + sendTelemetry("synth", { language: "typescript" }); + + expect(Sentry.metrics.increment).toHaveBeenCalledWith( + "command.invoked", 1, + expect.objectContaining({ + tags: expect.objectContaining({ command: "synth", language: "typescript" }), + }) + ); + }); + + it("does not send when telemetry is disabled", () => { + // Verify consent gating works + // ... + }); +}); +``` + +**Fast feedback loop**: This test runs in isolation in seconds, doesn't need a real Sentry DSN, and validates the exact API contract. + +### Finding 5: The 7 call sites map cleanly to Sentry metrics + +Each existing `sendTelemetry` call maps 1:1 to a Sentry metric: + +| Call site | Current code | Sentry replacement | +|-----------|-------------|-------------------| +| `watch.ts:184` | `sendTelemetry("watch", { event: "start" })` | `metrics.increment("command.invoked", 1, { tags: { command: "watch" } })` | +| `synth-stack.ts:279` | `sendTelemetry("synth", { totalTime, language, ... })` | `metrics.increment("command.invoked", ...)` + `metrics.distribution("synth.duration", totalTime, ...)` | +| `synth-stack.ts:294` | `sendTelemetry("synth", { error: true })` | `metrics.increment("command.error", 1, { tags: { command: "synth" } })` | +| `cdktf-project.ts:648` | `sendTelemetry(command, { language, ... })` | `metrics.increment("command.invoked", 1, { tags: { command, language } })` | +| `handlers.ts:169` | `sendTelemetry("convert", { ...stats })` | `metrics.increment("command.invoked", 1, { tags: { command: "convert" } })` | +| `init.ts:285` | `sendTelemetry("init", { language, ... })` | `metrics.increment("command.invoked", 1, { tags: { command: "init", language } })` | +| `get.tsx:58` | `sendTelemetry("get", { language, ... })` | `metrics.increment("command.invoked", 1, { tags: { command: "get", language } })` | + +The conversion is mechanical. Each call site changes from a function that POSTs JSON to HashiCorp to a function that emits a Sentry metric. The data is the same, only the transport changes. + +### Finding 6: Consent flow already covers this + +The existing consent gate in `error-reporting.ts` checks: +1. `cdktf.json` → `sendCrashReports` (persisted user choice) +2. `SENTRY_DSN` env var (build-time bake-in) +3. CI detection (skip consent prompt in CI) + +Since Sentry metrics go through the same `Sentry.init()` pipeline, they automatically respect the same opt-out. If a user sets `sendCrashReports: false`, Sentry never initializes, and `Sentry.metrics.*` calls become no-ops. + +No new consent mechanism needed. + +### Finding 7: Recommended test strategy + +**Layer 1: Unit tests (fast, isolated — seconds)** +- Mock `@sentry/node` with `jest.mock()` +- Test that the new telemetry function calls `Sentry.metrics.increment()` with correct tags +- Test consent gating (telemetry disabled when Sentry not initialized) +- Test that removed code paths don't exist (no HTTP calls to HashiCorp) +- Location: `packages/@cdktn/commons/src/test/telemetry.test.ts` + +**Layer 2: Integration smoke test (medium — minutes)** +- Run `cdktn synth` on a simple project +- Verify no errors, no outbound calls to `checkpoint-api.hashicorp.com` +- Can use `nock.disableNetConnect()` to catch any unexpected outbound calls +- Location: existing integration test suite with `CHECKPOINT_DISABLE` removed + +**Layer 3: Manual Sentry dashboard validation (one-time)** +- Build CLI with real `SENTRY_DSN` +- Run a few commands +- Check Sentry dashboard for metrics appearing +- Not automated — done once during development to confirm end-to-end + +**What to delete:** +- `packages/@cdktn/cli-core/src/test/checkpoint.test.ts` — tests HashiCorp endpoint behavior that no longer exists + +## Decisions + +- **Decision 1: Option B is feasible with low risk.** The SDK supports metrics, no upgrade needed, call sites map cleanly, consent flow is reused. The "big if" is resolved. + +- **Decision 2: Write a standalone validation test first.** Before touching any call sites, write a unit test that mocks Sentry and validates `Sentry.metrics.increment()` is called correctly. This gives fast feedback in seconds and de-risks the entire migration. + +- **Decision 3: The migration is mechanical, not creative.** Each of the 7 call sites is a straightforward substitution. No architectural decisions needed per-site. + +- **Decision 4: One PR is viable.** Given the low risk (no SDK upgrade, same consent flow, mechanical substitution), a single PR covering both removal and migration is clean and reviewable. The PR would be small — mostly deletions with a few line changes at call sites. + +## Recommendations + +1. **Start with the validation test**: Write `telemetry.test.ts` with Sentry mocked. Get green. This proves the API contract in seconds. + +2. **Then do the migration in order**: + a. Add `metricsAggregatorIntegration()` to `Sentry.init()` in `error-reporting.ts` + b. Create new `sendTelemetry()` wrapper that calls `Sentry.metrics.*` + c. Update 7 call sites (or keep the same function signature with new internals) + d. Remove HashiCorp-specific code (`ReportRequest`, `post()`, `BASE_URL`, `report()`) + e. Relocate `getUserId`/`getProjectId` out of `checkpoint.ts` + f. Delete `checkpoint.test.ts` + +3. **Keep the same `sendTelemetry(command, payload)` function signature** if possible — this minimizes changes at the 7 call sites. Just change the implementation from "POST to HashiCorp" to "emit Sentry metric". + +4. **Run existing tests to catch regressions**: `yarn test` across all packages should pass with the only changes being checkpoint.test.ts deletion. + +## References + +- Sentry metrics API types: `node_modules/@sentry/core/types/metrics/exports.d.ts` +- Sentry metrics integration: `node_modules/@sentry/core/types/metrics/integration.d.ts` +- Checkpoint test: `packages/@cdktn/cli-core/src/test/checkpoint.test.ts` +- Error reporting: `packages/@cdktn/cli-core/src/lib/error-reporting.ts` +- Jest configs: `packages/@cdktn/{commons,cli-core}/jest.config.js` +- Prior research: `specledger/002-remove-hashicorp-telemetry/research/2026-03-20-checkpoint-usage-analysis.md` +- Prior research: `specledger/002-remove-hashicorp-telemetry/research/2026-03-20-sentry-usage-and-checkpoint-migration.md` diff --git a/specledger/002-remove-hashicorp-telemetry/spec.md b/specledger/002-remove-hashicorp-telemetry/spec.md new file mode 100644 index 000000000..b7813acdb --- /dev/null +++ b/specledger/002-remove-hashicorp-telemetry/spec.md @@ -0,0 +1,159 @@ +# Feature Specification: Replace HashiCorp Telemetry with Sentry Analytics + +**Feature Branch**: `002-remove-hashicorp-telemetry` +**Created**: 2026-03-20 +**Status**: Draft +**Input**: GitHub Issue #48 - cdktn-cli telemetry uses HashiCorp's endpoint +**Issue**: https://github.com/open-constructs/cdk-terrain/issues/48 + +## User Scenarios & Testing *(mandatory)* + +### User Story 1 - CLI stops sending data to HashiCorp (Priority: P1) + +As a cdktn user, I want the CLI to not send any data to HashiCorp's checkpoint API, so that my usage data is not shared with an unrelated third party and the CLI does not depend on HashiCorp infrastructure. + +**Why this priority**: This is the core ask of the issue. The cdktn project has forked from cdktf, and the checkpoint module still sends telemetry and error reports to `checkpoint-api.hashicorp.com`. This is a privacy concern and an operational dependency on infrastructure the project does not control. + +**Independent Test**: Can be fully tested by running any CLI command (e.g., `cdktn synth`) and verifying no outbound HTTP requests are made to `checkpoint-api.hashicorp.com`. Delivers immediate value by removing the external dependency. + +**Acceptance Scenarios**: + +1. **Given** a user runs any cdktn CLI command, **When** the command executes, **Then** no HTTP requests are made to `checkpoint-api.hashicorp.com` or any other HashiCorp-owned endpoint. +2. **Given** a user has not set `CHECKPOINT_DISABLE`, **When** they run a cdktn CLI command, **Then** no data is sent to HashiCorp. +3. **Given** a user upgrades from a previous cdktn version, **When** they run CLI commands, **Then** behavior is identical except no HashiCorp calls are made. + +--- + +### User Story 2 - Usage analytics are preserved via Sentry (Priority: P1) + +As a project maintainer, I want usage telemetry (which commands are run, which languages are used, synth timing) routed through the project's own Sentry account instead of HashiCorp, so that the project retains data-driven insights for feature prioritization and support without depending on Hashicorp infrastructure. + +**Why this priority**: The project has a full Sentry business plan with OSS support that includes metrics features. Deleting analytics entirely would leave the project blind to adoption patterns, language usage, and performance trends. Migrating to Sentry preserves these insights at no additional cost, using infrastructure the project already controls. The existing `@sentry/node@7.120.4` SDK already supports custom metrics (`Sentry.metrics.increment()`, `.distribution()`, etc.) — no SDK upgrade needed. + +**Independent Test**: Can be validated in isolation by writing a unit test that mocks `@sentry/node` and verifies `Sentry.metrics.increment()` is called with correct metric names and tags when a CLI command executes. Runs in seconds without a real Sentry DSN. + +**Acceptance Scenarios**: + +1. **Given** a user has usage telemetry enabled (`sendUsageTelemetry: true` in `cdktf.json`) and `SENTRY_DSN` is set and `CHECKPOINT_DISABLE` is not set, **When** they run `cdktn synth`, **Then** a command invocation metric is emitted to Sentry with tags for command name, language, and environment. +2. **Given** a user has usage telemetry disabled (`sendUsageTelemetry: false` in `cdktf.json`), **When** they run any CLI command, **Then** no usage metrics are sent to Sentry. +3. **Given** a user has `CHECKPOINT_DISABLE` set (regardless of `sendUsageTelemetry` value), **When** they run any CLI command, **Then** no usage metrics are sent to Sentry. +4. **Given** the CLI is running in CI, **When** a command executes with telemetry enabled, **Then** the CI environment is captured as a metric tag. +5. **Given** the `sendTelemetry` function is called, **When** Sentry is not initialized (no DSN), **Then** the metric calls are silent no-ops with no errors. + +--- + +### User Story 3 - Sentry error reporting continues working (Priority: P1) + +As a project maintainer, I want the existing Sentry-based error/crash reporting to continue functioning after the HashiCorp endpoint is removed, so that the team retains visibility into production errors. + +**Why this priority**: Sentry is the project's own error reporting system and must not be disrupted. The Sentry integration depends on shared utilities (`getUserId`, `getProjectId`) that currently live in the checkpoint module, and the error-handling module currently sends error reports to both Sentry and HashiCorp's checkpoint API. Both coupling points must be handled carefully. + +**Independent Test**: Can be tested by triggering a crash-reportable error with `SENTRY_DSN` set and `sendCrashReports: true`, then verifying the error appears in Sentry. Also verify that `getUserId` and `getProjectId` continue to function for Sentry scope tagging. + +**Acceptance Scenarios**: + +1. **Given** a user has `sendCrashReports: true` in `cdktf.json` and `SENTRY_DSN` is set, **When** an internal error occurs, **Then** the error is reported to Sentry. +2. **Given** the checkpoint module's HashiCorp-specific code is removed, **When** Sentry initializes, **Then** it can still obtain `userId` and `projectId` for scope tagging. +3. **Given** the error-handling module previously sent reports to both Sentry and HashiCorp, **When** an error is created via `Errors.Internal/External/Usage`, **Then** only the Sentry path remains active. + +--- + +### User Story 4 - HashiCorp checkpoint code is cleaned up (Priority: P2) + +As a project maintainer, I want all HashiCorp checkpoint-specific code removed from the codebase, so that there is no dead code, no confusion about what telemetry is active, and reduced maintenance burden. + +**Why this priority**: Once the HashiCorp endpoint is replaced by Sentry (P1), cleaning up the remaining dead code is a follow-on concern. This includes removing the `ReportRequest` function, the `post()` helper, the `BASE_URL` constant, the `report()` function in errors.ts, and the checkpoint-specific tests. + +**Independent Test**: Can be tested by searching the codebase for references to `checkpoint-api.hashicorp.com`, `ReportRequest`, and the `post()` function. Delivers value by reducing code complexity. + +**Acceptance Scenarios**: + +1. **Given** the cleanup is complete, **When** a maintainer searches the codebase for HashiCorp checkpoint references, **Then** no active code references remain (copyright headers are acceptable). +2. **Given** the checkpoint code is removed, **When** the project is built, **Then** all builds succeed without errors. +3. **Given** the `report()` function in errors.ts is removed, **When** `Errors.Internal/External/Usage` is called, **Then** no errors occur and Sentry error tracking still functions. + +--- + +### Edge Cases + +- What happens when existing users have `CHECKPOINT_DISABLE` set in their environment? It continues to disable usage telemetry (now via Sentry instead of HashiCorp). No behavior change from the user's perspective. +- What happens when `CHECKPOINT_DISABLE` is set but `sendCrashReports: true`? Crash reporting still works — `CHECKPOINT_DISABLE` only controls usage telemetry, not crash reports. These are independent concerns. +- What happens to the `~/.cdktf/config.json` file that stores `userId`? The file and `getUserId()` function must be preserved since Sentry uses `userId` for scope tagging. +- What happens to `projectId` in `cdktf.json`? The field and `getProjectId()` function must be preserved since Sentry uses `projectId` for scope tagging. +- What happens to the `report()` function in errors.ts that sends error telemetry to HashiCorp via `ReportRequest`? It must be removed. Sentry already captures these errors with richer context (stack traces, breadcrumbs, environment info) — the HashiCorp path is redundant. +- What happens if Sentry is not initialized (no DSN, user opted out of both flags)? The `Sentry.metrics.*` calls are silent no-ops — no errors, no data sent. +- What happens to `CHECKPOINT_DISABLE` in CI workflows (set in 14 locations)? These continue to work as before — they disable usage telemetry. No CI workflow changes needed. +- What happens when neither `sendUsageTelemetry` nor `sendCrashReports` is set in `cdktf.json`? The user is prompted on first CLI use (non-CI only), consistent with the existing consent flow. In CI, both default to disabled (no prompt). + +## Requirements *(mandatory)* + +### Functional Requirements + +**Telemetry migration:** + +- **FR-001**: The CLI MUST NOT make any outbound HTTP requests to `checkpoint-api.hashicorp.com` or any other HashiCorp-owned endpoint. +- **FR-002**: Usage telemetry (command invocations, language, timing, CI environment) MUST be emitted as Sentry custom metrics instead of being sent to HashiCorp. +- **FR-003**: The Sentry metrics aggregator integration MUST be enabled in `Sentry.init()` to support custom metrics. +- **FR-004**: The existing `sendTelemetry(command, payload)` function signature SHOULD be preserved where practical, with the implementation changed from HTTP POST to HashiCorp to Sentry metric emission. + +**Consent model:** + +- **FR-005**: A new `sendUsageTelemetry` field MUST be added to `cdktf.json` to independently control usage telemetry, separate from `sendCrashReports` which controls crash reporting. +- **FR-006**: The `CHECKPOINT_DISABLE` environment variable MUST continue to disable usage telemetry when set, overriding `sendUsageTelemetry: true`. It MUST NOT affect crash reporting (`sendCrashReports`). +- **FR-007**: Sentry MUST be initialized if either `sendCrashReports` or `sendUsageTelemetry` is true (and `SENTRY_DSN` is set). +- **FR-008**: When neither `sendUsageTelemetry` nor `sendCrashReports` is set, the user MUST be prompted on first CLI use (non-CI only), consistent with the existing consent flow. + +**Sentry preservation:** + +- **FR-009**: The Sentry error reporting system MUST continue to function unchanged, including `userId` and `projectId` scope tagging, breadcrumbs, and crash reporting. +- **FR-010**: The `getUserId()` and `getProjectId()` utility functions MUST be preserved and relocated from `checkpoint.ts` to an appropriate module. + +**Code cleanup:** + +- **FR-011**: The `ReportRequest` function, `post()` helper, `BASE_URL` constant, and `ReportParams` interface MUST be removed. +- **FR-012**: The `report()` function in errors.ts that sends error data to HashiCorp via `ReportRequest` MUST be removed. The `Errors` object and its Sentry integration MUST be preserved. +- **FR-013**: All existing tests MUST continue to pass, with checkpoint-specific tests replaced by Sentry metrics tests. + +**Out of scope:** + +- **OS-001**: Removing `CHECKPOINT_DISABLE` from CI workflows (14 locations) is explicitly out of scope. The env var continues to function as a usage telemetry override. +- **OS-002**: Renaming `sendCrashReports` to a broader name is out of scope. The two flags remain independent. + +## Success Criteria *(mandatory)* + +### Measurable Outcomes + +- **SC-001**: Zero outbound HTTP requests to HashiCorp endpoints when running any CLI command. +- **SC-002**: Usage metrics (command name, language, OS, CI environment) appear in Sentry when `sendUsageTelemetry: true` and `CHECKPOINT_DISABLE` is not set. +- **SC-003**: Usage metrics are not sent when `CHECKPOINT_DISABLE` is set, regardless of `sendUsageTelemetry` value. +- **SC-004**: Sentry error reporting functions correctly (errors appear in Sentry when `sendCrashReports: true`), independent of usage telemetry settings. +- **SC-005**: All unit tests pass, including new telemetry tests validating Sentry metric emission and consent gating. +- **SC-006**: All integration tests pass after the migration. +- **SC-007**: No dead code remains related to HashiCorp's checkpoint API. + +### Previous work + +- **SL-6b54af - Update Sentry telemetry release tag** (001-cdktn-package-rename): Related task that updates Sentry telemetry release tags as part of the rename. Sentry error reporting is preserved and unaffected by this feature. +- **SL-3d9d60 - Add migration telemetry events** (001-cdktn-package-rename): Related task for adding migration telemetry events. This feature replaces the HashiCorp transport with Sentry, so migration telemetry should use the new Sentry-based `sendTelemetry` function. +- **GitHub Issue #48**: The originating issue reporting that cdktn-cli telemetry uses HashiCorp's endpoint. + +## Dependencies & Assumptions + +### Assumptions + +- **Sentry business plan includes metrics**: The project has a full Sentry business plan with OSS support. Custom metrics features are available at no additional cost. +- **`@sentry/node@7.120.4` supports custom metrics**: Verified — the installed SDK has `Sentry.metrics.increment()`, `.distribution()`, `.set()`, `.gauge()` and `metricsAggregatorIntegration()`. No SDK upgrade required. +- **Two independent consent flags**: `sendCrashReports` controls crash/error reporting. `sendUsageTelemetry` controls usage analytics. Both are in `cdktf.json`. Sentry is initialized if either is true. +- **`CHECKPOINT_DISABLE` remains a usage telemetry override**: The env var continues to disable usage telemetry when set, providing backward compatibility for existing CI workflows (14 locations) and users. It does not affect crash reporting. +- **`getUserId` and `getProjectId` are shared utilities**: Used by both the checkpoint system (being removed) and Sentry error reporting (being preserved). Must be retained and relocated from `checkpoint.ts`. +- **`ci-info` is a shared dependency**: Used by both the checkpoint system and Sentry error reporting, so it must not be removed. +- **`uuid` is still needed**: `getUserId()` uses `uuidv4()` and is preserved for Sentry. Also used by `init.ts` for project ID generation. +- **Metrics are silent no-ops when Sentry is not initialized**: If `SENTRY_DSN` is not set or user has opted out of both flags, `Sentry.metrics.*` calls do nothing — no errors, no data sent. + +### Research + +The following research spikes informed this specification: + +- [Checkpoint usage analysis](research/2026-03-20-checkpoint-usage-analysis.md): Complete map of checkpoint.ts exports, 7 sendTelemetry call sites, and dependency analysis. +- [Sentry usage and migration feasibility](research/2026-03-20-sentry-usage-and-checkpoint-migration.md): Sentry metrics capabilities, migration mapping, and decision to route analytics through Sentry. +- [Testing strategy and SDK validation](research/2026-03-20-testing-strategy-and-sentry-sdk-validation.md): Confirmed SDK supports metrics without upgrade, designed isolated validation test approach, and mapped call site conversions. diff --git a/specledger/specledger.yaml b/specledger/specledger.yaml index 4fa952609..f3072bda4 100644 --- a/specledger/specledger.yaml +++ b/specledger/specledger.yaml @@ -1,9 +1,10 @@ version: 1.0.0 project: + id: cf0ebc3d-be3d-4506-a46f-fe40c4d4f036 name: cdk-terrain short_code: cdkt created: 2026-03-20T13:07:33.211166+07:00 - modified: 2026-03-20T13:07:34.294146+07:00 + modified: 2026-03-20T17:56:34.054145+07:00 version: 0.1.0 playbook: name: specledger