create-convex-monorepo 0.2.0

package/docs/verification.md

@@ -0,0 +1,78 @@
+# v0.1 verification
+
+Executed on 2026-09-09 on macOS with Node 24.17.0 and pnpm 10.34.5. Results refer to the implementation in this repository, not every future upstream release.
+
+## Repository checks
+
+| Command                          | Result                                                                                                                                                    |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pnpm install --frozen-lockfile` | Passed                                                                                                                                                    |
+| `pnpm lint`                      | Passed                                                                                                                                                    |
+| `pnpm format:check`              | Passed                                                                                                                                                    |
+| `pnpm typecheck`                 | Passed                                                                                                                                                    |
+| `pnpm test`                      | 98 passed: 41 core, 13 generator/golden, 14 setup, 11 blank, 14 release, 5 backend                                                                        |
+| `pnpm build`                     | Passed                                                                                                                                                    |
+| `pnpm pack`                      | Passed                                                                                                                                                    |
+| `node scripts/pack-smoke.mjs`    | Installed the tarball outside the checkout and generated Next + Expo + Clerk through its bin; official generated assets and standalone URL linking passed |
+
+The twelve golden combinations cover every requested fixture plus Vite + Clerk and Start + Clerk. An additional regression test covers numeric-leading names, matching native auth redirects, ten applications, dev concurrency and tracked environment examples. Filesystem tests cover traversal, symlinks, existing content, cancellation, collisions, and failed install/git recovery.
+
+Backend tests execute generated functions with `convex-test`. They check persistence, trimming, input length, the fifty-message bound, unauthenticated rejection and isolation between identities.
+
+## Generated-project checks
+
+`pnpm test:e2e` generates into a fresh OS temporary directory, installs dependencies, and runs root `pnpm typecheck`, `pnpm lint` and `pnpm build`. It supplies syntactically valid public test configuration so bundlers compile the actual providers. Test Clerk keys are synthetic and cannot authenticate. Set `CCM_APPS` and `CCM_AUTH` to choose the case. A failed fixture is retained and its path printed; successful fixtures are removed unless `CCM_KEEP_FIXTURE` is set.
+
+Completed all-four-framework workspaces with both `none` and `clerk`. Next builds used Turbopack; Vite produced client bundles; Start produced client and server bundles. Expo exported iOS and Android Metro/Hermes bundles using isolated pnpm workspace links and the default Metro resolver. Client output scans also reject the backend index name, backend validation text and synthetic server-secret marker in shipped JavaScript or Hermes bundles. Each frontend's standalone TypeScript program checked the concrete shared API argument, document and return types, plus negative API-key assertions.
+
+The six definition-of-done combinations are also checked individually: Next, Vite, Start, Expo, Next + Expo, and Next + Expo + Clerk. The GitHub Actions matrix repeats these combinations and adds Vite + Start + Clerk. CI has been authored but has not run on a hosted GitHub runner in this session.
+
+## Live checks
+
+`CONVEX_AGENT_MODE=anonymous convex dev --once` compiled and pushed the example to a local deployment using Convex 1.45.0. The unmodified official generated files were captured from that workflow. The generated workspace's `pnpm convex:setup` also pushed successfully from packages/backend.
+
+The generated all-four workspace's `pnpm dev` started Convex, Next, Vite, Start and Metro together with streamed logs. A `ConvexHttpClient` sent and queried a message; a separate `ConvexClient` subscription observed that mutation. The Next, Vite and Start development servers each returned HTTP 200. Creating environment files during a Start server restart caused one transient request failure; a subsequent request succeeded.
+
+The interactive CLI was exercised in a PTY and created a Next + Expo project. The noninteractive CLI and installed tarball bin were also exercised.
+
+## Limits
+
+No browser was available through the browser-control tool, so page interaction and visual review were not performed. Fable was unavailable; no independent UI/UX review is claimed. Fresh technical review found scheme and task-concurrency defects, which were fixed and checked again.
+
+Real Clerk sessions, Google OAuth, MFA/session tasks, native Xcode/Gradle builds and physical devices were not tested. Metro exports prove JavaScript module resolution and bundling, not native binary execution. Start's Convex data is client-driven; authenticated server prefetching is not configured. Optional upstream peer warnings are recorded in research.md.
+
+Windows and Node 22 checks are configured in CI but were not executed locally. No npm publication, remote repository creation or production deployment occurred.
+
+## Initialization and release automation checks
+
+The initialization follow-up passed repository install, lint, formatting, typecheck, all 73 tests, build, pack, and installed-tarball smoke checks. Setup tests cover option conflicts, dependency ordering, preserving failed projects, all four environment prefixes, existing multiline settings, secret exclusion, invalid URLs, symlinks, child-process failure, and cancellation. The tarball test runs the copied URL linker without installing the generated project's dependencies.
+
+Ran the built CLI with `--apps web:next,admin:vite,app:tanstack-start,mobile:expo --auth none --init-convex --no-git` in a fresh temporary directory with `CONVEX_AGENT_MODE=anonymous`. It installed dependencies, pushed to a real local Convex deployment and linked every frontend. Each generated environment file contained exactly its public URL assignment. Re-running `pnpm convex:link` preserved their modification times. The resulting root `pnpm typecheck`, `pnpm lint` and `pnpm build` passed for all four apps, including iOS and Android Metro/Hermes exports.
+
+A separate PTY run accepted the new initialization prompt for Next + Expo. Dependencies installed automatically, Convex pushed successfully, and both URLs linked. Anonymous mode exercised local setup; browser account login and cloud project selection were not tested.
+
+Fresh technical review reproduced a cancellation race during URL linking. The fix passes the abort signal through the linking stage and checks it before each write and before reporting completion. A focused reviewer follow-up reran the reproduction and confirmed rejection after cancellation, with the remaining app untouched. Partial completed writes stay available and linking can be rerun.
+
+The release-please configuration passed validation against its upstream schema, and the PR-title rule accepted five valid titles and rejected five invalid titles. CLI and generated metadata versions now come from package.json. GitHub Actions, repository permissions and release creation have not been exercised on a remote repository.
+
+## Blank starter checks
+
+The blank starter follow-up passed lint, formatting, typecheck, all 84 tests, build, pack, and the installed-tarball smoke test for both starter choices. Eleven new tests cover selection/defaults, invalid values, all four frameworks individually, and combined workspaces with no auth and Clerk. They check for absent demo files and stale imports while retaining providers and auth configuration.
+
+`CCM_EXAMPLE=none CCM_AUTH=none pnpm test:e2e` and `CCM_EXAMPLE=none CCM_AUTH=clerk pnpm test:e2e` both passed installation, typecheck, lint and build for all four frameworks. Builds included Next, Vite, Start client/server, and Expo iOS/Android Metro exports. The test runner injected exact empty API/table-name assertions, non-any assertions and negative unknown-module assertions into each disposable frontend. Those test files are not included in normal blank generation. Clerk build configuration was synthetic; real sign-in remains untested.
+
+The empty schema and unmodified generated assets came from a successful official `convex dev --once` run. A generated blank workspace then completed its own `pnpm convex:setup` against an anonymous local deployment and linked all four frontend URLs. The interactive starter-content prompt also created a blank Next + Expo project in a PTY.
+
+Fresh technical review independently compiled the empty API/data-model assertions and found a Windows path-separator error in the new file assertions. That error was fixed before the final test run. Windows execution and hosted CI remain untested locally.
+
+## npm publishing preparation
+
+On 2026-09-10, the publishing follow-up passed frozen installation, lint, formatting, typecheck, all 98 tests, build, package smoke tests and `actionlint`. The packed CLI ran through npx and pnpm dlx using the local tarball. The release package validator checked its real manifest and registry status, and `npm publish --dry-run --ignore-scripts --access public` accepted the archive without publishing.
+
+Fresh review checked the release dispatch, provenance commit identity, bootstrap flow, artifact transfer and publishing permissions. It identified a cross-version publishing race; the publish job now serializes npm updates across releases. The repository was created at `adamtrip-solutions/create-convex-monorepo`, with the npm environment restricted to release tags and automated npm publishing disabled pending account/trust setup. Hosted [CI run 34415619159](https://github.com/adamtrip-solutions/create-convex-monorepo/actions/runs/34415619159) passed all jobs on release infrastructure commit `3e1943b`, including Windows and Linux generator checks and every generated-project build. The first hosted run exposed CRLF checkout formatting on Windows; `.gitattributes` now fixes LF endings across platforms. The automatically generated changelog uses release-please formatting and is excluded from Prettier. Actual npm OIDC publication remains untested until account and trusted-publisher setup is complete.
+
+## CI bootstrap publishing
+
+Compared both the local checkout and GitHub workflow of `adamtrip-solutions/convex-cloudflare-email`, whose first npm release workflow succeeded. Its publish step supports `NPM_BOOTSTRAP_TOKEN` for initial package creation. This repository now supports the same token-to-OIDC transition and no longer gates publishing behind `NPM_PUBLISHING_ENABLED`. The token is passed only to the final npm publish step. No secret values were read or transferred from the reference repository, and this package has not been published.
+
+A later Windows run exposed an intermittent cancellation failure: setup rejected on the child's abort error before the process closed, leaving the backend directory locked during cleanup. The regression test reproduced the early return locally. Setup now waits for the child close event before settling, preserving the original error. The corrected test and all 98 repository tests passed, together with typecheck, lint, formatting, build, and package smoke checks. Hosted Windows confirmation of this fix is pending.

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "create-convex-monorepo",
+  "version": "0.2.0",
+  "description": "Generate typed Convex monorepos with composable frontend and authentication adapters.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-convex-monorepo": "dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "assets",
+    "docs",
+    "README.md",
+    "CONTRIBUTING.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "1.8.0",
+    "cross-spawn": "7.0.6"
+  },
+  "devDependencies": {
+    "@types/cross-spawn": "6.0.6",
+    "@types/node": "24.12.2",
+    "convex": "1.45.0",
+    "convex-test": "0.0.54",
+    "eslint": "10.10.0",
+    "prettier": "3.8.3",
+    "tsx": "4.21.0",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.70.0",
+    "vite": "8.2.2",
+    "vitest": "5.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adamtrip-solutions/create-convex-monorepo.git"
+  },
+  "homepage": "https://github.com/adamtrip-solutions/create-convex-monorepo#readme",
+  "bugs": {
+    "url": "https://github.com/adamtrip-solutions/create-convex-monorepo/issues"
+  },
+  "keywords": [
+    "convex",
+    "monorepo",
+    "create",
+    "turborepo",
+    "nextjs",
+    "expo",
+    "vite",
+    "tanstack"
+  ],
+  "scripts": {
+    "dev": "tsx src/cli/index.ts",
+    "build": "tsc -p tsconfig.build.json && node scripts/executable.mjs",
+    "typecheck": "tsx scripts/backend-fixtures.ts && tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run && pnpm test:backend",
+    "test:e2e": "node scripts/e2e.mjs",
+    "test:backend": "tsx scripts/backend-fixtures.ts && vitest run --config vitest.backend.config.ts",
+    "test:package": "node scripts/pack-smoke.mjs"
+  }
+}