feat: v1 release

.github/workflows/release.yml

@@ -7,6 +7,11 @@ on:
 
 concurrency: ${{ github.workflow }}-${{ github.ref }}
 
+permissions:
+  id-token: write
+  contents: write
+  pull-requests: write
+
 jobs:
   release:
     name: Release
@@ -19,6 +24,7 @@ jobs:
         uses: actions/setup-node@v5
         with:
           node-version: 24.x
+          registry-url: "https://registry.npmjs.org"
 
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
@@ -40,3 +46,4 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NPM_CONFIG_PROVENANCE: true

.gitignore

@@ -12,3 +12,4 @@ node_modules/
 /tests/unit/coverage/
 .claude
 **/public/pagefind
+.planning

.planning/STATE.md

@@ -0,0 +1,126 @@
+---
+gsd_state_version: 1.0
+milestone: v1.0
+milestone_name: milestone
+status: completed
+stopped_at: Completed quick task 16
+last_updated: "2026-03-27T00:00:00.000Z"
+last_activity: 2026-03-27 — Completed quick task 16: hardened upgrade full test to require success unconditionally; added React-only e2e --add test with real install
+progress:
+  total_phases: 3
+  completed_phases: 3
+  total_plans: 8
+  completed_plans: 8
+  percent: 100
+---
+
+# Project State
+
+## Project Reference
+
+See: .planning/PROJECT.md (updated 2026-03-26)
+
+**Core value:** A single CLI that gets users from zero to a working Qwik + Astro project
+**Current focus:** All 3 phases complete — milestone v1.0 delivered
+
+## Current Position
+
+Phase: 3 of 3 (Integration) — complete
+Plan: All plans complete (8/8)
+Status: Milestone complete
+Last activity: 2026-03-27 - Completed quick task 12: Fix persistTsconfigForAdd comment-stripping and strengthen add-flow regression test
+
+Progress: [██████████] 100%
+
+## Performance Metrics
+
+**Velocity:**
+- Total plans completed: 0
+- Average duration: --
+- Total execution time: --
+
+**By Phase:**
+
+| Phase | Plans | Total | Avg/Plan |
+|-------|-------|-------|----------|
+| - | - | - | - |
+
+**Recent Trend:**
+- Last 5 plans: --
+- Trend: --
+
+*Updated after each plan completion*
+| Phase 01-upgrade-command P01 | 2 | 2 tasks | 2 files |
+| Phase 02-multi-framework-add-flow P01 | 3 | 2 tasks | 6 files |
+| Phase 01-upgrade-command P02 | 2min | 2 tasks | 2 files |
+| Phase 02-multi-framework-add-flow P03 | 3 | 2 tasks | 4 files |
+| Phase 02-multi-framework-add-flow P02 | 3min | 1 tasks | 3 files |
+| Phase 01-upgrade-command P03 | 2min | 2 tasks | 1 files |
+| Phase 03-integration P01 | 2min | 2 tasks | 2 files |
+| Phase 03-integration P02 | 3min | 1 tasks | 3 files |
+
+## Accumulated Context
+
+### Decisions
+
+Decisions are logged in PROJECT.md Key Decisions table.
+Recent decisions affecting current work:
+
+- Milestone v1.0: Parallel workstreams with non-overlapping file ownership (upgrade owns `src/upgrade*`, add-flow owns `src/add*`, shared files reserved for Phase 3)
+- Milestone v1.0: AST-based config parsing via oxc-parser (not regex)
+- Milestone v1.0: Upgrade command must delegate to `@astrojs/upgrade` first before Qwik-specific steps
+- [Phase 01-upgrade-command]: validate() runs validateProject() sync, checkGitStatus() async deferred to interact()
+- [Phase 01-upgrade-command]: validateProject detects @qwikdev/astro and @qwik.dev/astro integration packages in addition to core Qwik packages
+- [Phase 01-upgrade-command]: --no flag aborts on dirty git, --yes skips prompt, interactive mode defaults to false
+- [Phase 02-multi-framework-add-flow]: oxc-parser (not regex) for config AST analysis to handle aliased imports and complex object expressions
+- [Phase 02-multi-framework-add-flow]: Regex (not AST) for source file scanning - sufficient for import/pragma detection, much simpler
+- [Phase 02-multi-framework-add-flow]: DetectionOutcome 'unsafe' returned when spread elements found in integrations array
+- [Phase 01-upgrade-command]: PACKAGE_MAP keys processed longest-first to prevent @builder.io/qwik prefix from overwriting already-replaced subpath specifiers
+- [Phase 01-upgrade-command]: pm.x() failures in migration pipeline warn and continue rather than abort — partial migration better than hard failure
+- [Phase 02-multi-framework-add-flow]: Counter.tsx template has no pragma — pragma prepended at scaffold time based on strategy choice
+- [Phase 02-multi-framework-add-flow]: determineJsxStrategy is pure logic — interactive prompt wiring deferred to Phase 3 CLI integration
+- [Phase 02-multi-framework-add-flow]: magic-string prependRight for empty-arg calls (react()) — overwrite on zero-length range throws; appendLeft for existing-args calls
+- [Phase 02-multi-framework-add-flow]: rewriteConfig returns null for non-safe DetectionOutcome values — caller uses generateWarning for user-facing messaging
+- [Phase 01-upgrade-command]: UpgradeResults.configChanges is an array of {file, replacements} objects so printSummary can list the exact config file path
+- [Phase 01-upgrade-command]: sourceFilesChanged merges rewriteImports and rewritePragmaComments results via Set deduplication — files touched by both steps appear once in summary
+- [Phase 01-upgrade-command]: printSummary calls this.outro() internally so dry-run and actual run get distinct outro messages
+- [Phase 03-integration]: rewriteConfig actual signature is 2-param (source, result) — used actual implementation not plan interface
+- [Phase 03-integration]: subcommand detection uses args.slice(2).find(not-flag) to correctly skip flags before finding subcommand name
+- [Phase 03-integration]: tsdown entry points required alongside package.json exports — test runner resolves to dist/ which must be explicitly built
+- [Phase quick-fix]: Framework include patterns scoped to src/components/{name}/**/* to prevent Qwik file routing through wrong frameworks
+- [Phase quick-fix]: Safe auto-config uses add-exclude (not add-include) so existing frameworks keep processing files in all directories they already handle
+- [Phase quick-fix]: @builder.io/qwik-city excluded from upgrade OLD_PACKAGES — no router migration logic exists
+- [Quick-10]: isQwikRegistered uses conservative detection (inline defineConfig only) — false negatives are safe, false positives would wrongly skip astro add
+
+### Pending Todos
+
+None yet.
+
+### Blockers/Concerns
+
+None yet.
+
+### Quick Tasks Completed
+
+| # | Description | Date | Commit | Directory |
+|---|-------------|------|--------|-----------|
+| 1 | Fix P1/P2 issues from Codex review on add/upgrade CLI commands | 2026-03-27 | e148752 | [1-fix-p1-p2-issues-from-codex-review-on-ad](./quick/1-fix-p1-p2-issues-from-codex-review-on-ad/) |
+| 2 | Fix P1/P2 CLI bugs: add-flow JSX ownership, JSONC tsconfig, upgrade abort, test script typo | 2026-03-27 | c3a4940 | [2-fix-p1-p2-cli-bugs-add-flow-scoping-jsx-](./quick/2-fix-p1-p2-cli-bugs-add-flow-scoping-jsx-/) |
+| 3 | Fix add-flow safe mode: switch from add-include to add-exclude, fix test runner source import | 2026-03-27 | 5c62ec7 | [3-fix-add-flow-safe-auto-config-breaking-e](./quick/3-fix-add-flow-safe-auto-config-breaking-e/) |
+| 4 | Fix test imports to use relative source paths, update unsafe warning to match add-exclude strategy | 2026-03-27 | 1ceaa22 | [4-fix-test-imports-to-not-depend-on-dist-a](./quick/4-fix-test-imports-to-not-depend-on-dist-a/) |
+| 5 | Fix all biome lint errors (23 errors, 2 warnings) across create-qwikdev-astro/src | 2026-03-27 | 9c7991d | [5-fix-all-biome-lint-issues](./quick/5-fix-all-biome-lint-issues/) |
+| 6 | Fix TS2345 boolean\|undefined errors in rewrite-config.test.ts | 2026-03-27 | a608196 | [6-fix-ts2345-errors-in-rewrite-config-test](./quick/6-fix-ts2345-errors-in-rewrite-config-test/) |
+| 7 | Evaluate magic-regexp adoption — verdict: do not adopt (12 regex patterns, 8 trivial, net-negative ROI) | 2026-03-27 | n/a (eval only) | [7-is-there-enough-regex-present-that-it-wo](./quick/7-is-there-enough-regex-present-that-it-wo/) |
+| 9 | Add @builder.io/qwik npm alias install and ecosystem warning to upgrade script | 2026-03-27 | faa77f4 | [9-add-builder-io-qwik-npm-alias-to-upgrade](./quick/9-add-builder-io-qwik-npm-alias-to-upgrade/) |
+| 10 | Fix duplicate qwik() integration entry when --add on already-configured project | 2026-03-27 | 3b4a499 | [10-fix-duplicate-qwik-astro-addition-when-a](./quick/10-fix-duplicate-qwik-astro-addition-when-a/) |
+| 11 | Unify --add flag flow with add subcommand multi-framework detection | 2026-03-27 | 5eefd54 | [11-unify-add-and-add-flows-so-documented-pa](./quick/11-unify-add-and-add-flows-so-documented-pa/) |
+| 12 | Fix persistTsconfigForAdd to strip JSONC comments before parsing; extract stripJsonComments to utils.ts | 2026-03-27 | 37d2498 | [12-fix-persisttsconfigforadd-comment-stripp](./quick/12-fix-persisttsconfigforadd-comment-stripp/) |
+| 13 | Fix scaffold.ts Counter.tsx template path — import shared __dirname from utils.ts, single .. traversal | 2026-03-27 | c64565b | [13-fix-scaffold-ts-counter-tsx-template-pat](./quick/13-fix-scaffold-ts-counter-tsx-template-pat/) |
+| 15 | Fix unchecked panam results (assertPmResult) in upgrade.ts/app.ts; JSONC tsconfig parsing in upgrade-rewrite.ts | 2026-03-27 | e8d1f61 | [15-fix-production-readiness-issues-assertpm](./quick/15-fix-production-readiness-issues-assertpm/) |
+| 16 | Harden upgrade full test to require success unconditionally; add React-only e2e --add test with real install | 2026-03-27 | 99e89f2 | [16-harden-upgrade-test-to-require-success-a](./quick/16-harden-upgrade-test-to-require-success-a/) |
+
+## Session Continuity
+
+Last session: 2026-03-27T00:00:00Z
+Stopped at: Completed quick task 16
+Resume file: None

.planning/quick/10-fix-duplicate-qwik-astro-addition-when-a/10-SUMMARY.md

@@ -0,0 +1,84 @@
+---
+phase: quick
+plan: "10"
+subsystem: create-qwikdev-astro/add-flow
+tags: [bug-fix, ast, detect-config, add-flow, regression-test]
+dependency_graph:
+  requires: []
+  provides: [isQwikRegistered, duplicate-prevention]
+  affects:
+    - libs/create-qwikdev-astro/src/add-flow/detect-config.ts
+    - libs/create-qwikdev-astro/src/app.ts
+    - libs/create-qwikdev-astro/src/add-flow/command.ts
+    - libs/create-qwikdev-astro/tests/add-existing-qwik.spec.ts
+tech_stack:
+  added: []
+  patterns: [oxc-parser AST walking, conservative-detection]
+key_files:
+  created: []
+  modified:
+    - libs/create-qwikdev-astro/src/add-flow/detect-config.ts
+    - libs/create-qwikdev-astro/src/app.ts
+    - libs/create-qwikdev-astro/src/add-flow/command.ts
+    - libs/create-qwikdev-astro/tests/add-existing-qwik.spec.ts
+decisions:
+  - isQwikRegistered uses conservative detection — only returns true for inline defineConfig with literal array; variable-exported and callback configs return false (safe fallback so astro add still runs)
+  - installQwik in command.ts receives qwikRegistered as a boolean parameter rather than re-reading config, keeping the detection logic in execute()
+  - Pre-install (hasQwikImport) still runs even when qwikRegistered is true — avoids crash if the package is missing from node_modules
+metrics:
+  duration: "~4 min"
+  completed: "2026-03-27"
+  tasks_completed: 3
+  files_modified: 4
+---
+
+# Phase Quick Plan 10: Fix Duplicate qwik() Addition When Already Registered Summary
+
+**One-liner:** AST-based `isQwikRegistered()` prevents duplicate `qwik()` integration entries by skipping `astro add` when the integration is already present in the config.
+
+## What Was Built
+
+Fixed a bug where running `--add` on a project that already had `qwik()` in its `integrations` array would cause `astro add @qwik.dev/astro` to run again, inserting a second `qwikDev()` call alongside the existing `qwik()`.
+
+**Root cause:** Both `app.ts:runAdd` and `command.ts:installQwik` unconditionally called `astro add` even when the integration was already registered.
+
+**Fix:** Added `isQwikRegistered(configSource: string): boolean` to `detect-config.ts` that uses the existing oxc-parser AST walking pattern to check if a `@qwik.dev/astro` binding is called in the `integrations` array. Both add paths now check this before running `astro add`.
+
+## Tasks Completed
+
+| Task | Description | Commit |
+|------|-------------|--------|
+| 1 | Add `isQwikRegistered()` to detect-config.ts | 4010aa8 |
+| 2 | Use `isQwikRegistered` in app.ts and command.ts to conditionally skip astro add | fce7c3a |
+| 3 | Add `isQwikRegistered` unit tests and regression test | 3b4a499 |
+
+## Key Design Decisions
+
+**Conservative detection** — `isQwikRegistered` only returns `true` for the most common config pattern: `export default defineConfig({ integrations: [qwik()] })`. Variable-exported configs (`const config = defineConfig(...); export default config`) and callback configs (`defineConfig(() => ({...}))`) return `false`. This is intentional: false negatives are safe (astro add runs harmlessly on a fresh project or adds the integration if missing), while false positives would incorrectly skip needed setup.
+
+**Pre-install still runs when registered** — `hasQwikImport` check for pre-install is preserved even when `isQwikRegistered` is true. If the package is somehow missing from node_modules but the import exists, `astro add` would crash. Pre-installing first prevents that crash, and then we skip the redundant `astro add` call.
+
+**Parameter threading** — `installQwik` in `command.ts` receives `qwikRegistered` as a boolean, keeping detection logic centralized in `execute()` where `configSource` is already available.
+
+## Test Coverage
+
+- 5 unit tests for `isQwikRegistered` covering all config shapes
+- Regression test asserting config has exactly 1 `qwik()` call (and no `qwikDev` alias) after `--add` on a project with `INLINE_CONFIG`
+- All 14 tests pass (9 previous + 5 new `isQwikRegistered` + 1 new regression)
+
+## Deviations from Plan
+
+None — plan executed exactly as written.
+
+## Self-Check
+
+- [x] `detect-config.ts` modified — confirmed
+- [x] `app.ts` modified — confirmed
+- [x] `command.ts` modified — confirmed
+- [x] `add-existing-qwik.spec.ts` modified — confirmed
+- [x] Commit 4010aa8 exists — confirmed
+- [x] Commit fce7c3a exists — confirmed
+- [x] Commit 3b4a499 exists — confirmed
+- [x] All 14 tests pass — confirmed
+
+## Self-Check: PASSED

.planning/quick/11-unify-add-and-add-flows-so-documented-pa/11-SUMMARY.md

@@ -0,0 +1,111 @@
+---
+phase: quick-11
+plan: 01
+subsystem: cli
+tags: [multi-framework, jsx-strategy, config-rewrite, scaffold]
+
+requires:
+  - phase: 02-multi-framework-add-flow
+    provides: detectConfigFrameworks, rewriteConfig, scaffoldQwikComponent, determineJsxStrategy
+  - phase: quick-10
+    provides: isQwikRegistered duplicate prevention
+provides:
+  - Unified --add flag flow with multi-framework detection, JSX strategy, config rewriting, component scaffolding
+affects: [create-qwikdev-astro, cli]
+
+tech-stack:
+  added: []
+  patterns: [unified-add-flow, multi-framework-detection-in-app]
+
+key-files:
+  created:
+    - libs/create-qwikdev-astro/tests/add-flow-unification.spec.ts
+  modified:
+    - libs/create-qwikdev-astro/src/app.ts
+
+key-decisions:
+  - "Fixture includes qwik() registration to skip astro add in test (avoids needing @astrojs/react installed)"
+  - "persistTsconfigForAdd mirrors AddCommand.persistTsconfig but uses fs/path from app.ts scope"
+  - "scanChoice defaults to 'primary' in non-interactive mode; intercept overrides in tests"
+
+patterns-established:
+  - "runAdd delegates to add-flow modules for multi-framework concerns"
+
+requirements-completed: [QUICK-11]
+
+duration: 5min
+completed: 2026-03-27
+---
+
+# Quick Task 11: Unify --add and add Flows Summary
+
+**--add flag flow now calls detectConfigFrameworks, prompts JSX strategy, rewrites config with exclude patterns, and scaffolds Counter.tsx with pragma**
+
+## Performance
+
+- **Duration:** 5 min
+- **Started:** 2026-03-27T19:22:22Z
+- **Completed:** 2026-03-27T19:27:01Z
+- **Tasks:** 3
+- **Files modified:** 2
+
+## Accomplishments
+- Unified Application.runAdd with AddCommand.execute multi-framework logic
+- Added regression test proving --add on React+Astro project triggers framework detection
+- All 120 tests pass with no regressions
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Write failing regression test** - `6c234bb` (test)
+2. **Task 2: Unify runAdd implementation** - `5eefd54` (feat)
+3. **Task 3: Full test suite verification** - no commit (verification only)
+
+## Files Created/Modified
+- `libs/create-qwikdev-astro/tests/add-flow-unification.spec.ts` - Regression test proving --add invokes multi-framework detection
+- `libs/create-qwikdev-astro/src/app.ts` - Unified runAdd with detectConfigFrameworks, rewriteConfig, scaffoldQwikComponent, persistTsconfigForAdd
+
+## Decisions Made
+- Fixture config includes both react() and qwik() in integrations so isQwikRegistered returns true and astro add is skipped during test (avoids needing @astrojs/react actually installed)
+- Assert `react(` instead of `react()` since rewriteConfig transforms `react()` to `react({ exclude: [...] })`
+- persistTsconfigForAdd uses simple JSON.parse (no JSONC stripping) since existing projects have valid JSON tsconfig
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] Fixed test fixture to include qwik registration**
+- **Found during:** Task 1/2
+- **Issue:** Test fixture with only react() in config caused astro add to fail (can't load @astrojs/react which isn't installed in test /tmp dir)
+- **Fix:** Added qwik import and registration to fixture config so isQwikRegistered returns true, skipping astro add
+- **Files modified:** libs/create-qwikdev-astro/tests/add-flow-unification.spec.ts
+- **Verification:** Test passes, all assertions confirmed
+- **Committed in:** 5eefd54 (Task 2 commit)
+
+**2. [Rule 1 - Bug] Fixed react() assertion after config rewrite**
+- **Found during:** Task 2
+- **Issue:** Test asserted `react()` but rewriteConfig transforms it to `react({ exclude: ... })`
+- **Fix:** Changed assertion to `react(` to match the rewritten form
+- **Files modified:** libs/create-qwikdev-astro/tests/add-flow-unification.spec.ts
+- **Verification:** Test passes
+- **Committed in:** 5eefd54 (Task 2 commit)
+
+---
+
+**Total deviations:** 2 auto-fixed (2 bugs in test expectations)
+**Impact on plan:** Both fixes necessary for test correctness. Core implementation matches plan exactly.
+
+## Issues Encountered
+None beyond the test fixture adjustments documented above.
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- --add and add subcommand now share the same multi-framework detection pipeline
+- Both paths handle React/Preact/Solid detection, JSX strategy prompting, config rewriting, and component scaffolding
+
+---
+*Quick Task: 11*
+*Completed: 2026-03-27*