test: add a local env example file - #25
Merged
Merged
Conversation
These settings actually work with clerk_go out of the box because we have a pre-configured oauth app and because fosite does not validate ports for loopback redirects
wyattjoh
reviewed
Mar 10, 2026
wyattjoh
approved these changes
Mar 10, 2026
rafa-thayto
added a commit
that referenced
this pull request
Mar 24, 2026
- Extract utility helpers from index.ts into heuristics.ts (jfoshee #18) - Extract text transformations into transformations.ts (jfoshee #19) - Fix wrapBodyWithProvider whitespace/formatting bug (jfoshee #20) - Refactor tests to use semantic path lookups instead of positional array indexing (jfoshee #13/#17) - Add doc comment to helpers.ts clarifying shared usage (jfoshee #15) - Update astro.md NEVER rules to start with "Never" (jfoshee #25) - Remove section banner comments from init command files
rafa-thayto
added a commit
that referenced
this pull request
Mar 24, 2026
…mpts (#38) * chore: add magicast dependency for AST-based code manipulation Used by the init command's framework scaffolders to safely add imports and modify config files without breaking existing code. * refactor: fix framework SDK names and detection priority - Fix @clerk/clerk-react → @clerk/react - Fix @clerk/tanstack-start → @clerk/tanstack-react-start - Remove standalone vite detection (covered by react) - Reorder priority: scaffoldable frameworks first, then expo, react, express, fastify - Export readDeps for use by init context module * feat(init): add project context gathering Detects framework, TypeScript, src/ directory convention, package manager, Next.js router variant, middleware filename, layout path, and existing Clerk SDK installation. * feat(init): add scaffold system with framework-specific scaffolders Add idempotent scaffolders for Next.js (App + Pages Router), React, React Router, Nuxt, TanStack Start, Astro, and Vue. Each scaffolder generates framework-appropriate boilerplate (middleware, providers, auth pages) while preserving existing user code. Shared helpers handle AST-based import injection (magicast with string fallback), middleware composition, and auth page creation. * feat(init): add scan, format, preview, and agent prompt modules - scan: detect competing auth libraries pre-scaffold and scan for hardcoded keys/leftover imports post-scaffold - format: run Prettier/Biome on generated files - preview: show planned file changes and confirm before writing - prompts: framework-specific agent mode prompts with exact code snippets and file paths * feat(init): rewrite init command with scaffold and scan flow Replace the minimal init (login + link + install + env pull) with a full orchestrator that also scaffolds framework boilerplate and scans for issues. Skips login/link when already authenticated and linked. * docs(init): update README with scaffolding docs and framework table - Add Agent Mode section - Add env var column to framework detection table - Add Expo, Express, Fastify to detection table - Document scaffolding actions for all 8 supported frameworks - Note that Expo/Express/Fastify are detected but not scaffolded * refactor(init): restructure agent prompts into markdown templates Replace monolithic prompts.ts with individual .md template files per framework, matching the clerk-docs structured format (sections, rules, deprecated patterns, verification checklists). - Move prompts to src/commands/init/prompts/*.md with {{PLACEHOLDER}} interpolation - Add prompts for expo, express, and fastify frameworks - Merge DOCS_URLS + TEMPLATE_MAP into single FRAMEWORK_PROMPTS record - Extract shared pmInstallCommand, remove duplicate pmAddCommand - Fix formatter-escaped underscores (\_app, \_\_root) in template loader - Add "After Setup" section to all prompts (matching clerk-docs) * refactor(init): make FileAction a discriminated union and extend FrameworkScaffold FileAction is now a proper discriminated union with a dedicated `skip` variant that has no `content` field, enforced at the type level. The FrameworkScaffold interface gains `dep`, `variant`, `minMajorVersion`, `matches()`, and optional `enrichContext()` so each scaffolder is self-describing. Enrichment fields (variant, layoutPath, middlewareBasename) become optional on ProjectContext since they are populated after gatherContext. * refactor(init): extract Next.js context enrichment to frameworks/nextjs-context Move parseNextMajorVersion, detectMiddlewareBasename, detectNextjsVariant, and detectLayoutPath from context.ts into a dedicated nextjs-context.ts module. This isolates framework-specific logic behind the enrichContext hook on FrameworkScaffold rather than coupling it to gatherContext. Parallelize dirExists calls with Promise.all in both files. * refactor(init): replace scaffold key map with matches() dispatch and version check Replace the Record<string, FrameworkScaffold> keyed map with an array using satisfies and matches()-based lookup. Add enrichProjectContext() that delegates to each scaffolder's enrichContext hook. Add minMajorVersion guard that checks the framework dep version before scaffolding. * refactor(init): add shared helpers and flatten scaffoldNextjsMiddleware Add parseMajorVersion, insertAfterLastImport, wrapBodyWithProvider, and resolveNextjsMiddlewareBasename to helpers. Use proper skip FileAction in scaffoldAuthPage and scaffoldNextjsMiddleware. Flatten nested ifs with early returns and store BunFile reference once. The middleware fallback now resolves from the actual Next.js version in deps. * refactor(init): update all scaffolders with skip actions, dep/matches, and minMajorVersion Each scaffolder now exports dep, matches(), and minMajorVersion. All skip cases use the proper FileAction skip variant. Flatten nested ifs with early returns across scaffoldLayout, scaffoldApp, scaffoldMiddleware, and scaffoldConfig. Use shared wrapBodyWithProvider (nextjs-app, tanstack-start), insertAfterLastImport (react-router, vue), and extract wrapWithClerkProvider in react.ts. Store BunFile references to avoid duplicate creation. * refactor(init): remove findings cap, precompile regexes, and unexport internal types Remove MAX_FINDINGS so no context is lost. Convert IGNORE_DIRS to a Set for O(1) lookups. Precompile CODE_SCANS regexes once at module level. Inline matchesFramework guard. Convert AuthLibraryScan and CodeScan from exported interfaces to local types since they are not imported elsewhere. * refactor(init): replace readFileSync with static text imports for compiled binaries Use Bun's `import ... with { type: "text" }` to embed markdown prompt templates at build time. This replaces the runtime readFileSync + import.meta.dir approach that would break in compiled Bun binaries. Remove the template cache since imports are already static. * refactor(init): abstract formatter config into data-driven array Replace inline if-checks for prettier/biome with a FormatterConfig type and a FORMATTERS array. The runFormatters loop now iterates the config, making it trivial to add new formatters. * test(init): update tests for discriminated union, enrichContext, and version check Update context tests to call enrichProjectContext separately from gatherContext and import parseMajorVersion from helpers. Add tests for scaffold version check (below minimum, meets minimum, Next.js 16 proxy). Update nextjs-app tests to assert on the skip type instead of skipReason field. Update scan test to verify all findings are returned without cap. * chore: update bun.lock with magicast dependency * refactor(init): extract shared auth and config scaffolding helpers Add jsxAuthPageContent with type-safe JsxClerkPackage union, scaffoldConfigFile generic for the find→check→modify pattern, authComponentName, and inline capitalize. These shared helpers eliminate duplication across framework scaffolders. * refactor(init): use shared helpers in framework scaffolders Replace duplicated authRouteContent/nextjsAuthPageContent with jsxAuthPageContent, replace per-framework scaffoldConfig with scaffoldConfigFile in astro, nuxt, and react-router. Remove unused imports and add enableV8Middleware documentation. * refactor(init): restructure preview, prompts, and scan modules Update preview formatting to use switch on discriminated union, restructure prompts/index.ts with typed template resolution and variable building, and minor scan.ts cleanup. * test(init): add framework scaffolder and scan tests Add tests for nextjs-app (middleware composition, provider wrapping, src/ paths, proxy basename), react-router (root modification, loader merge), tanstack-start (base dir detection), and scan (no findings cap). * chore(init): add markdown type declaration for static text imports * feat(init): add framework lookup utility with aliases Export FRAMEWORK_MAP and add lookupFramework() to resolve framework names or aliases (e.g. "tanstack-start" → "@tanstack/react-start") along with FRAMEWORK_NAMES for validation and display. * feat(init): add i18nLocaleDir to ProjectContext type Add optional i18nLocaleDir field to ProjectContext for frameworks that detect locale-based routing directories (e.g. [locale], [lang]). * refactor(init): extract previewPlan display function Split preview logic into previewPlan() (display only) and previewAndConfirm() (display + prompt) to support --yes mode without duplicating the plan rendering code. * feat(init): add shared scaffolding helpers for auth, env, and i18n Add reusable helpers for all framework scaffolders: - authFileSpecs() factory for sign-in/sign-up file generation - scaffoldEnvVars() and SIGN_ROUTE_ENV_VARS for env file management - htmlAuthComponentMarkup() and jsxAuthComponentMarkup() with Tailwind/plain CSS variants - hasTailwindStyles() for style detection - i18n middleware detection, composition, and routing helpers (detectI18nMiddlewareLib, composeWithI18nMiddleware, etc.) - findFirstDirMatch() for generic directory scanning * feat(init): detect i18n locale directory in Next.js context Add detectI18nLocaleDir() to identify App Router locale directories (e.g. [locale], [lang]) by checking for layout files inside dynamic segments. Populate i18nLocaleDir in enrichNextjsContext() so scaffolders can place auth pages inside locale-prefixed paths. * feat(init): support framework override in context gathering Accept optional frameworkOverride parameter in gatherContext() to skip auto-detection when the user specifies --framework explicitly. * feat(init): wire --framework, --yes, and --prompt CLI options Register --framework <name>, -y/--yes, and --prompt options on the init command. Wire them through to framework override resolution, preview-only plan display, and agent prompt output respectively. * refactor(init): migrate framework scaffolders to shared helpers Update all six framework scaffolders (Astro, Next.js App/Pages, Nuxt, React Router, TanStack Start) to use the shared helpers: - authFileSpecs() factory for sign-in/sign-up generation - scaffoldEnvVars() for .env file management - hasTailwindStyles() for consistent style detection - i18n-aware auth page placement using locale directory detection - htmlAuthComponentMarkup()/jsxAuthComponentMarkup() for rendering * test(init): add i18n detection and locale routing tests Add tests for i18n support across frameworks: - Context: locale directory detection ([locale], [lang]) with layout file validation and src/ convention support - Next.js App Router: i18n auth page placement, composed Clerk + next-intl middleware, expression export handling, env var scaffolding - React Router: ($locale) prefix detection for auth routes - TanStack Start: {-$locale} directory detection for auth routes * docs(init): document new CLI options and update help output Add --framework, --yes, and --prompt options to init command README with usage examples. Update root README help output with --verbose flag documentation. * refactor(init): address PR review comments - Extract utility helpers from index.ts into heuristics.ts (jfoshee #18) - Extract text transformations into transformations.ts (jfoshee #19) - Fix wrapBodyWithProvider whitespace/formatting bug (jfoshee #20) - Refactor tests to use semantic path lookups instead of positional array indexing (jfoshee #13/#17) - Add doc comment to helpers.ts clarifying shared usage (jfoshee #15) - Update astro.md NEVER rules to start with "Never" (jfoshee #25) - Remove section banner comments from init command files * test(init): add missing framework scaffolder tests Add test coverage for the 5 framework scaffolders that were missing tests (jfoshee #21/#22): - astro.test.ts (10 tests) - nuxt.test.ts (8 tests) - vue.test.ts (6 tests) - react.test.ts (7 tests) - nextjs-pages.test.ts (10 tests) All tests use semantic path-based lookups via findAction() helper.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
These settings actually work with clerk_go out of the box because we have a pre-configured oauth app and because fosite does not validate ports for loopback redirects