@warlock.js/core 5.30.0 → 5.32.0

package/esm/errors/error-codes.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.mjs","names":[],"sources":["../../../../../../../../packages/core/src/errors/error-codes.ts"],"sourcesContent":["/**\n * The registry of stable Warlock error codes.\n *\n * Every framework error core throws, every `warlock doctor` finding and every\n * `warlock check` problem carries one of these codes, so a person or an agent\n * can look the code up instead of interpreting the message. `warlock explain\n * <CODE>` prints an entry; the docs page `cli/error-codes` lists all of them.\n *\n * THE SCHEME: `WL` followed by four digits. The first digit is the area:\n *\n * | Range  | Area        | Meaning                                              |\n * | ------ | ----------- | ---------------------------------------------------- |\n * | WL1xxx | config      | a configuration value is missing or invalid          |\n * | WL2xxx | boot        | the app could not boot: modules, connectors, services |\n * | WL3xxx | routing     | route registration and lookup                        |\n * | WL4xxx | validation  | request validation schemas                           |\n * | WL5xxx | http        | the HTTP layer at runtime                            |\n * | WL6xxx | database    | migrations, seeders and database code                |\n * | WL7xxx | cli         | CLI usage, and problems `warlock check` finds in code |\n * | WL8xxx | environment | this machine: Node, tools, services, ports           |\n * | WL9xxx | convention  | framework conventions and release hygiene            |\n *\n * STABILITY: a code, once released, keeps its meaning forever. Its `title`,\n * `fix` and links may be reworded; a code is never reused for a different\n * problem and never renumbered. A retired code stays in this table with\n * `retired: true`.\n *\n * `category` splits \"your code\" from \"this machine\": `environment` problems are\n * the ones `warlock check` reports with exit code 2, so an agent stops editing\n * code to fix a missing Redis server.\n *\n * This module is part of the side-effect-free `@warlock.js/core/errors` entry:\n * it imports nothing.\n */\n\n/** The area a code belongs to, matching its first digit. */\nexport type ErrorCodeArea =\n  | \"config\"\n  | \"boot\"\n  | \"routing\"\n  | \"validation\"\n  | \"http\"\n  | \"database\"\n  | \"cli\"\n  | \"environment\"\n  | \"convention\";\n\n/**\n * Who has to act: `code` problems are fixed in the project's source or config,\n * `environment` problems on the machine running it.\n */\nexport type ErrorCodeCategory = \"code\" | \"environment\";\n\n/** One registry entry. */\nexport type ErrorCodeDefinition = {\n  /** The stable code, e.g. `\"WL3001\"`. */\n  readonly code: string;\n  /** The area, matching the first digit. */\n  readonly area: ErrorCodeArea;\n  /** Whether the project or the machine has to change. */\n  readonly category: ErrorCodeCategory;\n  /** One-line name of the problem. */\n  readonly title: string;\n  /** One-line \"what to do\". */\n  readonly fix: string;\n  /** Slug of the skill that explains the fix (`packages/<pkg>/skills/<slug>/SKILL.md`). */\n  readonly skill: string;\n  /** Names of the error classes that carry this code, when an error class does. */\n  readonly errorNames?: readonly string[];\n  /** Set when the code is no longer emitted. Retired codes are never reused. */\n  readonly retired?: true;\n};\n\n/** Base URL of the error-code reference; each code is an anchor on that page. */\nexport const ERROR_CODES_DOCS_URL = \"https://warlock.js.org/v/latest/core/cli/error-codes/\";\n\n/** The registry, keyed by code. */\nexport const ERROR_CODES = {\n  // ── WL1xxx config ────────────────────────────────────────────────────────\n  WL1001: {\n    code: \"WL1001\",\n    area: \"config\",\n    category: \"code\",\n    title: \"A required config section is missing\",\n    fix: \"Add the missing file under src/config/ (for example src/config/app.ts) exporting the section.\",\n    skill: \"configure-app\",\n  },\n  WL1002: {\n    code: \"WL1002\",\n    area: \"config\",\n    category: \"code\",\n    title: \"No JWT signing secret is configured\",\n    fix: \"Run `warlock jwt.generate` (writes JWT_SECRET to .env) and read it as auth.accessToken.secret in src/config/auth.ts.\",\n    skill: \"configure-app\",\n  },\n  WL1003: {\n    code: \"WL1003\",\n    area: \"config\",\n    category: \"code\",\n    title: \"The rate-limit store cannot use the configured cache driver\",\n    fix: 'Use a redis, pg or memory cache driver for http.rateLimit store \"cache\", or set store: \"memory\".',\n    skill: \"configure-app\",\n    errorNames: [\"UnsupportedRateLimitDriverError\"],\n  },\n  WL1004: {\n    code: \"WL1004\",\n    area: \"config\",\n    category: \"code\",\n    title: \"An http.csp directive value is invalid\",\n    fix: \"Fix the directive value named in the message in your http config; quotes must balance and values may not contain ';'.\",\n    skill: \"configure-app\",\n    errorNames: [\"InvalidCspDirectiveError\"],\n  },\n  WL1005: {\n    code: \"WL1005\",\n    area: \"config\",\n    category: \"code\",\n    title: \"The uploads.images configuration is invalid\",\n    fix: \"Correct the uploads.images variant settings named in the message.\",\n    skill: \"upload-file\",\n    errorNames: [\"ImageVariantsConfigError\"],\n  },\n  WL1006: {\n    code: \"WL1006\",\n    area: \"config\",\n    category: \"code\",\n    title: \"warlock.config.ts sets a build option the builder refuses\",\n    fix: \"Remove the named option from the build block of warlock.config.ts; change tsconfig.json instead.\",\n    skill: \"run-app\",\n    errorNames: [\"ForbiddenBuildOptionError\"],\n  },\n  WL1007: {\n    code: \"WL1007\",\n    area: \"config\",\n    category: \"code\",\n    title: \"A locale dictionary file cannot be parsed\",\n    fix: \"Fix the key named in the message in the locales.json file it names.\",\n    skill: \"use-localization\",\n    errorNames: [\"LocaleDictionaryError\"],\n  },\n  WL1008: {\n    code: \"WL1008\",\n    area: \"config\",\n    category: \"code\",\n    title: \"A locale outside app.localeCodes was requested\",\n    fix: \"Add the locale to app.localeCodes in src/config/app.ts, or pass a configured locale.\",\n    skill: \"use-localization\",\n    errorNames: [\"UnknownLocaleError\"],\n  },\n  WL1009: {\n    code: \"WL1009\",\n    area: \"config\",\n    category: \"code\",\n    title: \"warlock.config.ts > connectors was refused\",\n    fix: \"Give every connector in warlock.config.ts a unique name that is not a built-in connector name.\",\n    skill: \"add-connector\",\n  },\n\n  // ── WL2xxx boot ──────────────────────────────────────────────────────────\n  WL2001: {\n    code: \"WL2001\",\n    area: \"boot\",\n    category: \"code\",\n    title: \"An app module failed to load\",\n    fix: \"Open the file named in the message and fix the error it throws on import; its routes and listeners are missing until then.\",\n    skill: \"warlock-doctor\",\n    errorNames: [\"ModuleLoadError\"],\n  },\n  WL2002: {\n    code: \"WL2002\",\n    area: \"boot\",\n    category: \"code\",\n    title: \"The app's source files could not be discovered\",\n    fix: \"Run the command from the project root and check that src/ exists and is readable.\",\n    skill: \"warlock-doctor\",\n  },\n  WL2003: {\n    code: \"WL2003\",\n    area: \"boot\",\n    category: \"code\",\n    title: \"A connector failed to boot\",\n    fix: \"Read the connector's message; it usually names the config value or package it needs.\",\n    skill: \"add-connector\",\n  },\n  WL2004: {\n    code: \"WL2004\",\n    area: \"boot\",\n    category: \"code\",\n    title: \"A container key was read before it was registered\",\n    fix: \"Register the key (container.set) before reading it, or read it after the connector that sets it has booted.\",\n    skill: \"use-app-context\",\n    errorNames: [\"ContainerKeyMissingError\"],\n  },\n  WL2005: {\n    code: \"WL2005\",\n    area: \"boot\",\n    category: \"code\",\n    title: \"A boot precondition failed\",\n    fix: \"Fix the condition named in the message; restarting does not help until it changes.\",\n    skill: \"run-app\",\n    errorNames: [\"BootPreconditionError\"],\n  },\n  WL2006: {\n    code: \"WL2006\",\n    area: \"boot\",\n    category: \"code\",\n    title: \"Storage was used before the storage connector ran\",\n    fix: 'Add src/config/storage.ts; in a custom command add \"storage\" to preload.connectors.',\n    skill: \"store-file\",\n    errorNames: [\"StorageNotInitializedError\"],\n  },\n  WL2007: {\n    code: \"WL2007\",\n    area: \"boot\",\n    category: \"code\",\n    title: \"A configured driver's package is not installed\",\n    fix: \"Install the package named in the message (for example `pnpm add sharp`), or stop configuring the driver.\",\n    skill: \"update-packages\",\n  },\n\n  // ── WL3xxx routing ───────────────────────────────────────────────────────\n  WL3001: {\n    code: \"WL3001\",\n    area: \"routing\",\n    category: \"code\",\n    title: \"A route name is already taken\",\n    fix: 'Rename one of the two routes with the \"name\" route option; pages and API routes share one namespace.',\n    skill: \"register-route\",\n    errorNames: [\"RouteNameTakenError\"],\n  },\n  WL3002: {\n    code: \"WL3002\",\n    area: \"routing\",\n    category: \"code\",\n    title: \"A route points at a controller method that does not exist\",\n    fix: \"Fix the [controller, action] pair: the action must be a method on the controller.\",\n    skill: \"register-route\",\n  },\n  WL3003: {\n    code: \"WL3003\",\n    area: \"routing\",\n    category: \"code\",\n    title: \"A URL was built for a route name that is not registered\",\n    fix: \"Check the name passed to router.route(); `warlock routes --name <part>` lists the registered names.\",\n    skill: \"warlock-routes\",\n  },\n  WL3004: {\n    code: \"WL3004\",\n    area: \"routing\",\n    category: \"code\",\n    title: \"A URL was built without one of the route's path parameters\",\n    fix: \"Pass every :param of the route path when building the URL.\",\n    skill: \"warlock-routes\",\n  },\n  WL3005: {\n    code: \"WL3005\",\n    area: \"routing\",\n    category: \"code\",\n    title: \"Route modules loaded but registered no routes\",\n    fix: \"Make sure routes.ts calls router.get/post/... at module level and is not wrapped in an unused function.\",\n    skill: \"register-route\",\n  },\n  WL3006: {\n    code: \"WL3006\",\n    area: \"routing\",\n    category: \"code\",\n    title: \"A handler uses the v4 (request, response) signature\",\n    fix: \"Rewrite the handler as async ({ request, response }) => { ... }.\",\n    skill: \"create-controller\",\n  },\n\n  // ── WL4xxx validation ────────────────────────────────────────────────────\n  WL4001: {\n    code: \"WL4001\",\n    area: \"validation\",\n    category: \"code\",\n    title: \"A validation schema cannot be described as JSON Schema\",\n    fix: \"Use Seal validators with a static shape for validation.schema/params; custom validate middleware is not described.\",\n    skill: \"validate-input\",\n  },\n\n  // ── WL5xxx http ──────────────────────────────────────────────────────────\n  WL5001: {\n    code: \"WL5001\",\n    area: \"http\",\n    category: \"code\",\n    title: \"A cookie was read but the cookie plugin is not registered\",\n    fix: \"Register @fastify/cookie on the server before reading cookies by name.\",\n    skill: \"send-response\",\n    errorNames: [\"CookieJarUnavailableError\"],\n  },\n  WL5002: {\n    code: \"WL5002\",\n    area: \"http\",\n    category: \"code\",\n    title: \"An app route claims a health-probe path\",\n    fix: \"Move the app route, or rename the probe with http.health.path / http.health.readinessPath.\",\n    skill: \"health-checks\",\n  },\n  WL5003: {\n    code: \"WL5003\",\n    area: \"http\",\n    category: \"code\",\n    title: \"Health probes are enabled but not registered\",\n    fix: \"Check that the http connector booted and that nothing removed the probe routes.\",\n    skill: \"health-checks\",\n  },\n  WL5004: {\n    code: \"WL5004\",\n    area: \"http\",\n    category: \"code\",\n    title: \"Devtools recorded no timeline for the traced request\",\n    fix: \"Keep http.requestId enabled (its echoed header is how the request is found) and retry; a path under the devtools prefix is never recorded.\",\n    skill: \"warlock-trace\",\n  },\n\n  // ── WL6xxx database ──────────────────────────────────────────────────────\n  WL6001: {\n    code: \"WL6001\",\n    area: \"database\",\n    category: \"code\",\n    title: \"A seeder depends on a seeder that is not registered\",\n    fix: \"Fix the dependsOn name, or register the missing seeder.\",\n    skill: \"write-seeder\",\n    errorNames: [\"UnknownSeederDependencyError\"],\n  },\n  WL6002: {\n    code: \"WL6002\",\n    area: \"database\",\n    category: \"code\",\n    title: \"Seeder dependencies form a cycle\",\n    fix: \"Remove one dependsOn edge from the cycle printed in the message.\",\n    skill: \"write-seeder\",\n    errorNames: [\"SeederDependencyCycleError\"],\n  },\n\n  // ── WL7xxx cli and checked code ──────────────────────────────────────────\n  WL7001: {\n    code: \"WL7001\",\n    area: \"cli\",\n    category: \"code\",\n    title: \"A boolean CLI option received a value it cannot read\",\n    fix: \"Pass true/false/1/0/yes/no, or the flag on its own for true.\",\n    skill: \"write-cli-command\",\n    errorNames: [\"CliOptionValueError\"],\n  },\n  WL7002: {\n    code: \"WL7002\",\n    area: \"cli\",\n    category: \"code\",\n    title: \"Generated code imports a package the app does not declare\",\n    fix: \"Add the named package to the app's dependencies, or import it through @warlock.js/core.\",\n    skill: \"run-app\",\n    errorNames: [\"UndeclaredGeneratedImportError\"],\n  },\n  WL7003: {\n    code: \"WL7003\",\n    area: \"cli\",\n    category: \"code\",\n    title: \"A command needs an optional package that is not installed\",\n    fix: \"Install the packages named in the message as dev dependencies (warlock mcp needs @warlock.js/ai-tools and @warlock.js/ai).\",\n    skill: \"warlock-mcp\",\n  },\n  WL7004: {\n    code: \"WL7004\",\n    area: \"cli\",\n    category: \"code\",\n    title: \"warlock mcp was asked to listen off loopback without a token\",\n    fix: \"Pass --token (or set WARLOCK_MCP_TOKEN) when --host is not 127.0.0.1, ::1 or localhost, or keep the default loopback host.\",\n    skill: \"warlock-mcp\",\n  },\n  WL7005: {\n    code: \"WL7005\",\n    area: \"cli\",\n    category: \"code\",\n    title: \"An MCP tool that writes files was called on a read-only server\",\n    fix: \"Restart the server with --allow-writes to let generate tools write; without it they only return the diff.\",\n    skill: \"warlock-mcp\",\n  },\n  WL7101: {\n    code: \"WL7101\",\n    area: \"cli\",\n    category: \"code\",\n    title: \"TypeScript reports a type error\",\n    fix: \"Fix the type error at the reported position; the TypeScript code (TS1234) is in `rule`.\",\n    skill: \"warlock-check\",\n  },\n  WL7102: {\n    code: \"WL7102\",\n    area: \"cli\",\n    category: \"code\",\n    title: \"tsconfig.json is missing or invalid\",\n    fix: \"Fix tsconfig.json at the project root; the message names the problem.\",\n    skill: \"warlock-check\",\n  },\n  WL7201: {\n    code: \"WL7201\",\n    area: \"cli\",\n    category: \"code\",\n    title: \"The linter reports an error\",\n    fix: \"Fix the lint error at the reported position; the rule id is in `rule`.\",\n    skill: \"warlock-check\",\n  },\n  WL7202: {\n    code: \"WL7202\",\n    area: \"cli\",\n    category: \"code\",\n    title: \"The linter reports a warning\",\n    fix: \"Fix the warning, or change the rule's severity in the lint config if it does not apply.\",\n    skill: \"warlock-check\",\n  },\n  WL7301: {\n    code: \"WL7301\",\n    area: \"cli\",\n    category: \"code\",\n    title: \"A test failed\",\n    fix: \"Run the test file alone, read the assertion message and fix the code or the test.\",\n    skill: \"warlock-check\",\n  },\n  WL7302: {\n    code: \"WL7302\",\n    area: \"cli\",\n    category: \"code\",\n    title: \"A test file failed before its tests ran\",\n    fix: \"Fix the import or setup error named in the message; none of the file's tests ran.\",\n    skill: \"warlock-check\",\n  },\n  WL7401: {\n    code: \"WL7401\",\n    area: \"cli\",\n    category: \"code\",\n    title: \"The agent board is not initialized\",\n    fix: \"Run `warlock board init` at the project root first.\",\n    skill: \"warlock-board\",\n  },\n  WL7402: {\n    code: \"WL7402\",\n    area: \"cli\",\n    category: \"code\",\n    title: \"A board item does not exist\",\n    fix: \"Run `warlock board status` to list the item ids.\",\n    skill: \"warlock-board\",\n  },\n  WL7403: {\n    code: \"WL7403\",\n    area: \"cli\",\n    category: \"code\",\n    title: \"A board item cannot move to the requested state\",\n    fix: \"Use one of the next states listed in the message; `warlock board status <id>` shows the item's current state.\",\n    skill: \"warlock-board\",\n  },\n  WL7404: {\n    code: \"WL7404\",\n    area: \"cli\",\n    category: \"code\",\n    title: \"No board message arrived before the watch timed out\",\n    fix: \"Run `warlock board watch` again, or raise --timeout.\",\n    skill: \"warlock-board\",\n  },\n  WL7501: {\n    code: \"WL7501\",\n    area: \"cli\",\n    category: \"code\",\n    title: \"AGENTS.md has malformed generated-section markers\",\n    fix: \"Keep one `<!-- warlock:generated:start -->` line followed by one `<!-- warlock:generated:end -->` line, or remove both.\",\n    skill: \"warlock-agents-md\",\n  },\n\n  // ── WL8xxx environment ───────────────────────────────────────────────────\n  WL8001: {\n    code: \"WL8001\",\n    area: \"environment\",\n    category: \"environment\",\n    title: \"The Node.js version is not supported\",\n    fix: \"Switch to a Node.js version that satisfies the engines range in the message (for example with nvm).\",\n    skill: \"update-packages\",\n  },\n  WL8002: {\n    code: \"WL8002\",\n    area: \"environment\",\n    category: \"environment\",\n    title: \"A tool the project is configured to use is not installed\",\n    fix: \"Install the tool named in the message (pnpm install), or remove its config file.\",\n    skill: \"warlock-check\",\n  },\n  WL8003: {\n    code: \"WL8003\",\n    area: \"environment\",\n    category: \"environment\",\n    title: \"A service the code needs is unreachable\",\n    fix: \"Start the service named in the message (database, Redis, ...) or point the config at a running one.\",\n    skill: \"warlock-check\",\n  },\n  WL8004: {\n    code: \"WL8004\",\n    area: \"environment\",\n    category: \"environment\",\n    title: \"A port is already in use\",\n    fix: \"Stop whatever listens on the port, or use another port (port 0 in tests).\",\n    skill: \"run-app\",\n    errorNames: [\"PortInUseError\"],\n  },\n  WL8005: {\n    code: \"WL8005\",\n    area: \"environment\",\n    category: \"environment\",\n    title: \"esbuild's native binary is not installed\",\n    fix: \"Run `pnpm approve-builds`, then reinstall dependencies without skipping install scripts.\",\n    skill: \"run-app\",\n    errorNames: [\"EsbuildBinaryMissingError\"],\n  },\n  WL8006: {\n    code: \"WL8006\",\n    area: \"environment\",\n    category: \"environment\",\n    title: \"Git cannot list the changed files\",\n    fix: \"Run inside a git repository with git on PATH, or run the command without --changed.\",\n    skill: \"warlock-check\",\n  },\n  WL8007: {\n    code: \"WL8007\",\n    area: \"environment\",\n    category: \"environment\",\n    title: \"A tool crashed, timed out or ran out of memory\",\n    fix: \"Re-run the step; if it repeats, raise the memory limit (NODE_OPTIONS=--max-old-space-size) or use --changed.\",\n    skill: \"warlock-check\",\n  },\n  WL8008: {\n    code: \"WL8008\",\n    area: \"environment\",\n    category: \"environment\",\n    title: \"The dev server is not running\",\n    fix: \"Start `warlock dev` in this project, or pass --url with the address of a running dev server.\",\n    skill: \"warlock-trace\",\n  },\n  WL8009: {\n    code: \"WL8009\",\n    area: \"environment\",\n    category: \"environment\",\n    title: \"Devtools is not running in the dev server\",\n    fix: \"Install it with `warlock add devtools` and restart `warlock dev`; devtools answers loopback requests in development only.\",\n    skill: \"warlock-trace\",\n  },\n\n  // ── WL9xxx conventions and hygiene ───────────────────────────────────────\n  WL9001: {\n    code: \"WL9001\",\n    area: \"convention\",\n    category: \"code\",\n    title: \"An auto-loaded file is imported\",\n    fix: \"Remove the import: routes.ts, main.ts, worker.ts and events/ files are loaded by the framework.\",\n    skill: \"warlock-conventions\",\n  },\n  WL9002: {\n    code: \"WL9002\",\n    area: \"convention\",\n    category: \"code\",\n    title: \"An import path ends in .js\",\n    fix: \"Drop the .js extension from the import path.\",\n    skill: \"warlock-conventions\",\n  },\n  WL9003: {\n    code: \"WL9003\",\n    area: \"convention\",\n    category: \"code\",\n    title: \"A relative import reaches into another module\",\n    fix: \"Import across modules through the app/<module>/... alias instead of ../../.\",\n    skill: \"warlock-conventions\",\n  },\n  WL9004: {\n    code: \"WL9004\",\n    area: \"convention\",\n    category: \"code\",\n    title: \"tsconfig.json enables legacy experimentalDecorators\",\n    fix: 'Remove \"experimentalDecorators\": true from tsconfig.json; Cascade uses standard decorators.',\n    skill: \"lower-stage3-decorators\",\n  },\n  WL9005: {\n    code: \"WL9005\",\n    area: \"convention\",\n    category: \"code\",\n    title: \"`request.all()` is passed to a query, a service or inApp()\",\n    fix: \"Give the route a validation schema and pass `request.validated()`, which holds only the fields the schema accepted (mass assignment otherwise).\",\n    skill: \"warlock-conventions\",\n  },\n  WL9006: {\n    code: \"WL9006\",\n    area: \"convention\",\n    category: \"code\",\n    title: \"A mutating route has no auth guard and is not marked public\",\n    fix: \"Register the POST/PUT/PATCH/DELETE route inside `guarded()` (or with auth middleware), or pass `{ public: true }` if it is meant to be open.\",\n    skill: \"warlock-conventions\",\n  },\n  WL9007: {\n    code: \"WL9007\",\n    area: \"convention\",\n    category: \"code\",\n    title: \"A redirect or link target comes from request input\",\n    fix: \"Wrap the target in `safeRedirect()` (server, @warlock.js/core) or `safeRedirectTarget()` (pages, @warlock.js/web), or check it with `isSafeRedirect()` first.\",\n    skill: \"warlock-conventions\",\n  },\n  WL9008: {\n    code: \"WL9008\",\n    area: \"convention\",\n    category: \"code\",\n    title: \"A raw email, credential or request body is logged\",\n    fix: \"Pass the value through `maskEmail()`, `redact()`, `escapeLogValue()` or `request.toLogSnapshot()`, or log it under a key the logger censors (`token`, `password`, ...).\",\n    skill: \"warlock-conventions\",\n  },\n  WL9009: {\n    code: \"WL9009\",\n    area: \"convention\",\n    category: \"code\",\n    title: \"A regex with an unbounded quantifier runs on request input\",\n    fix: \"Bound the repetition (`{1,256}` instead of `+` or `*`) or cap the input length before matching.\",\n    skill: \"warlock-conventions\",\n  },\n  WL9010: {\n    code: \"WL9010\",\n    area: \"convention\",\n    category: \"code\",\n    title: \"`await` on a synchronous log call\",\n    fix: \"Remove the `await`: `log.info()` and its siblings return the logger; `await log.flush()` waits for delivery.\",\n    skill: \"warlock-conventions\",\n  },\n  WL9011: {\n    code: \"WL9011\",\n    area: \"convention\",\n    category: \"code\",\n    title: \"A file defines more than one controller\",\n    fix: \"Move each extra controller into its own `<name>.controller.ts` file.\",\n    skill: \"warlock-conventions\",\n  },\n  WL9012: {\n    code: \"WL9012\",\n    area: \"convention\",\n    category: \"code\",\n    title: \"A tagged union uses `kind` as its discriminator\",\n    fix: \"Rename the discriminator to `type` and update the code that narrows on it.\",\n    skill: \"warlock-conventions\",\n  },\n  WL9101: {\n    code: \"WL9101\",\n    area: \"convention\",\n    category: \"code\",\n    title: \"A module still uses the deprecated utils/locales.ts\",\n    fix: \"Run `warlock doctor --fix` to convert it to locales.json, or convert it by hand.\",\n    skill: \"use-localization\",\n  },\n  WL9102: {\n    code: \"WL9102\",\n    area: \"convention\",\n    category: \"code\",\n    title: \"package.json version and CHANGELOG.md disagree\",\n    fix: \"Add a CHANGELOG.md heading for the package.json version, or fix the version.\",\n    skill: \"warlock-doctor\",\n  },\n  WL9103: {\n    code: \"WL9103\",\n    area: \"convention\",\n    category: \"code\",\n    title: \"CHANGELOG.md is missing or has no version heading\",\n    fix: \"Add a CHANGELOG.md with a `## x.y.z` heading for the current version.\",\n    skill: \"warlock-doctor\",\n  },\n} as const satisfies Record<string, ErrorCodeDefinition>;\n\n/** Every registered code, as a union. */\nexport type WarlockErrorCode = keyof typeof ERROR_CODES;\n\n/** Whether `value` is a registered code. */\nexport function isWarlockErrorCode(value: unknown): value is WarlockErrorCode {\n  return typeof value === \"string\" && Object.prototype.hasOwnProperty.call(ERROR_CODES, value);\n}\n\n/**\n * The registry entry for a code, or `undefined` for an unknown one. Case and\n * surrounding whitespace are ignored, so `explainErrorCode(\" wl3001 \")` works.\n */\nexport function explainErrorCode(code: string): ErrorCodeDefinition | undefined {\n  const normalized = code.trim().toUpperCase();\n\n  return isWarlockErrorCode(normalized) ? ERROR_CODES[normalized] : undefined;\n}\n\n/** The docs URL of a code: the reference page with the code as its anchor. */\nexport function errorCodeDocsUrl(code: WarlockErrorCode): string {\n  return `${ERROR_CODES_DOCS_URL}#${code.toLowerCase()}`;\n}\n\n/** Node errno codes that mean \"the machine\", mapped to the Warlock code. */\nconst SYSTEM_ERROR_CODES: Readonly<Record<string, WarlockErrorCode>> = {\n  ECONNREFUSED: \"WL8003\",\n  ENOTFOUND: \"WL8003\",\n  EHOSTUNREACH: \"WL8003\",\n  ETIMEDOUT: \"WL8003\",\n  EADDRINUSE: \"WL8004\",\n  ERR_OUT_OF_MEMORY: \"WL8007\",\n};\n\nfunction readStringProperty(value: object, key: string): string | undefined {\n  const property = Reflect.get(value, key);\n\n  return typeof property === \"string\" ? property : undefined;\n}\n\n/**\n * The Warlock code of a thrown value, or `undefined` when it has none.\n *\n * Reads, in order: a registered `code` property (framework errors carry one);\n * the error's `name`, for classes whose `code` property already means\n * something else (`PortInUseError.code` is Node's `\"EADDRINUSE\"`); a Node\n * system errno such as `ECONNREFUSED`; then the same checks on `cause`. Reading\n * by name rather than `instanceof` keeps the answer right when two copies of\n * core are loaded.\n */\nexport function errorCodeOf(error: unknown): WarlockErrorCode | undefined {\n  const seen = new Set<unknown>();\n  let current: unknown = error;\n\n  while (typeof current === \"object\" && current !== null && !seen.has(current)) {\n    seen.add(current);\n\n    const code = readStringProperty(current, \"code\");\n\n    if (isWarlockErrorCode(code)) {\n      return code;\n    }\n\n    const name = readStringProperty(current, \"name\");\n\n    if (name) {\n      for (const definition of Object.values(ERROR_CODES) as ErrorCodeDefinition[]) {\n        if (definition.errorNames?.includes(name) && isWarlockErrorCode(definition.code)) {\n          return definition.code;\n        }\n      }\n    }\n\n    if (code && SYSTEM_ERROR_CODES[code]) {\n      return SYSTEM_ERROR_CODES[code];\n    }\n\n    current = Reflect.get(current, \"cause\");\n  }\n\n  return undefined;\n}\n"],"mappings":"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"}

package/esm/errors/esbuild-binary-missing-error.mjs

@@ -11,6 +11,7 @@
 var EsbuildBinaryMissingError = class extends Error {
 	constructor(options) {
 		super("esbuild's native binary is not installed or linked for this platform, so `warlock dev` / `warlock build` cannot run.\n\nThis usually happens when a platform package such as `@esbuild/win32-x64` was never installed, or the package manager skipped esbuild's postinstall script that links it. Fix it with:\n\n  pnpm approve-builds\n\nthen reinstall dependencies (do not skip install scripts), or reinstall with your package manager's equivalent of allowing build scripts.", options);
+		this.code = "WL8005";
 		this.name = "EsbuildBinaryMissingError";
 	}
 };

package/esm/errors/esbuild-binary-missing-error.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"esbuild-binary-missing-error.mjs","names":[],"sources":["../../../../../../../../packages/core/src/errors/esbuild-binary-missing-error.ts"],"sourcesContent":["/**\n * Raised when `warlock dev` / `warlock build` cannot use esbuild because its\n * platform-native binary was never installed or linked.\n *\n * The message names what is missing and the exact fix — reinstall with the\n * package manager without skipping install scripts — so the failure is\n * actionable at the point it is thrown, instead of surfacing later as an\n * opaque low-level error from deep inside the bundler.\n */\nexport class EsbuildBinaryMissingError extends Error {\n  public constructor(options?: { cause?: unknown }) {\n    super(\n      \"esbuild's native binary is not installed or linked for this platform, so \" +\n        \"`warlock dev` / `warlock build` cannot run.\\n\\n\" +\n        \"This usually happens when a platform package such as `@esbuild/win32-x64` \" +\n        \"was never installed, or the package manager skipped esbuild's postinstall \" +\n        \"script that links it. Fix it with:\\n\\n\" +\n        \"  pnpm approve-builds\\n\\n\" +\n        \"then reinstall dependencies (do not skip install scripts), \" +\n        \"or reinstall with your package manager's equivalent of allowing build scripts.\",\n      options,\n    );\n\n    this.name = \"EsbuildBinaryMissingError\";\n  }\n}\n"],"mappings":";;;;;;;;;;AASA,IAAa,4BAAb,cAA+C,MAAM;CACnD,AAAO,YAAY,SAA+B;EAChD,MACE,wdAQA,OACF;EAEA,KAAK,OAAO;CACd;AACF"}
+{"version":3,"file":"esbuild-binary-missing-error.mjs","names":[],"sources":["../../../../../../../../packages/core/src/errors/esbuild-binary-missing-error.ts"],"sourcesContent":["/**\n * Raised when `warlock dev` / `warlock build` cannot use esbuild because its\n * platform-native binary was never installed or linked.\n *\n * The message names what is missing and the exact fix — reinstall with the\n * package manager without skipping install scripts — so the failure is\n * actionable at the point it is thrown, instead of surfacing later as an\n * opaque low-level error from deep inside the bundler.\n */\nexport class EsbuildBinaryMissingError extends Error {\n  /** Stable Warlock error code; `warlock explain WL8005` prints the fix. */\n  public readonly code = \"WL8005\";\n\n  public constructor(options?: { cause?: unknown }) {\n    super(\n      \"esbuild's native binary is not installed or linked for this platform, so \" +\n        \"`warlock dev` / `warlock build` cannot run.\\n\\n\" +\n        \"This usually happens when a platform package such as `@esbuild/win32-x64` \" +\n        \"was never installed, or the package manager skipped esbuild's postinstall \" +\n        \"script that links it. Fix it with:\\n\\n\" +\n        \"  pnpm approve-builds\\n\\n\" +\n        \"then reinstall dependencies (do not skip install scripts), \" +\n        \"or reinstall with your package manager's equivalent of allowing build scripts.\",\n      options,\n    );\n\n    this.name = \"EsbuildBinaryMissingError\";\n  }\n}\n"],"mappings":";;;;;;;;;;AASA,IAAa,4BAAb,cAA+C,MAAM;CAInD,AAAO,YAAY,SAA+B;EAChD,MACE,wdAQA,OACF;cAbqB;EAerB,KAAK,OAAO;CACd;AACF"}

package/esm/errors/index.d.mts

@@ -1,2 +1,4 @@
 import { BadRequestError, ConflictError, CookieJarUnavailableError, ForbiddenError, HttpError, NotAcceptableError, NotAllowedError, ResourceNotFoundError, ServerError, UnAuthorizedError } from "../http/errors/errors.mjs";
-export { BadRequestError, ConflictError, CookieJarUnavailableError, ForbiddenError, HttpError, NotAcceptableError, NotAllowedError, ResourceNotFoundError, ServerError, UnAuthorizedError };
+import { ERROR_CODES, ERROR_CODES_DOCS_URL, ErrorCodeArea, ErrorCodeCategory, ErrorCodeDefinition, WarlockErrorCode, errorCodeDocsUrl, errorCodeOf, explainErrorCode, isWarlockErrorCode } from "./error-codes.mjs";
+import { WarlockError } from "./warlock-error.mjs";
+export { BadRequestError, ConflictError, CookieJarUnavailableError, ERROR_CODES, ERROR_CODES_DOCS_URL, ErrorCodeArea, ErrorCodeCategory, ErrorCodeDefinition, ForbiddenError, HttpError, NotAcceptableError, NotAllowedError, ResourceNotFoundError, ServerError, UnAuthorizedError, WarlockError, WarlockErrorCode, errorCodeDocsUrl, errorCodeOf, explainErrorCode, isWarlockErrorCode };

package/esm/errors/index.mjs

@@ -1,3 +1,5 @@
 import { BadRequestError, ConflictError, CookieJarUnavailableError, ForbiddenError, HttpError, NotAcceptableError, NotAllowedError, ResourceNotFoundError, ServerError, UnAuthorizedError } from "../http/errors/errors.mjs";
+import { WarlockError } from "./warlock-error.mjs";
+import { ERROR_CODES, ERROR_CODES_DOCS_URL, errorCodeDocsUrl, errorCodeOf, explainErrorCode, isWarlockErrorCode } from "./error-codes.mjs";
 
-export { BadRequestError, ConflictError, CookieJarUnavailableError, ForbiddenError, HttpError, NotAcceptableError, NotAllowedError, ResourceNotFoundError, ServerError, UnAuthorizedError };
+export { BadRequestError, ConflictError, CookieJarUnavailableError, ERROR_CODES, ERROR_CODES_DOCS_URL, ForbiddenError, HttpError, NotAcceptableError, NotAllowedError, ResourceNotFoundError, ServerError, UnAuthorizedError, WarlockError, errorCodeDocsUrl, errorCodeOf, explainErrorCode, isWarlockErrorCode };

package/esm/errors/unknown-locale-error.mjs

@@ -16,6 +16,7 @@
 var UnknownLocaleError = class UnknownLocaleError extends Error {
 	constructor(locale, localeCodes) {
 		super(UnknownLocaleError.buildMessage(locale, localeCodes));
+		this.code = "WL1008";
 		this.name = "UnknownLocaleError";
 	}
 	static buildMessage(locale, localeCodes) {

package/esm/errors/unknown-locale-error.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"unknown-locale-error.mjs","names":[],"sources":["../../../../../../../../packages/core/src/errors/unknown-locale-error.ts"],"sourcesContent":["/**\n * Thrown by `response.setLocale(locale)` when `locale` is outside the\n * application's declared `app.localeCodes` allow-list.\n *\n * Silently writing a locale cookie for a locale the app cannot serve is a\n * NEW silent failure — `request.locale` would read the cookie back, fail its\n * own allow-list check (`Request.cacheLocale`), and fall back to the default\n * with nothing telling the caller why the switch never took. Failing here,\n * at the write, names the mistake at its source instead of downstream.\n *\n * Only raised when `app.localeCodes` is declared — with no list declared\n * there is nothing to fail against, matching `Request.cacheLocale`'s own\n * fail-open rule.\n */\nexport class UnknownLocaleError extends Error {\n  public constructor(locale: string, localeCodes: string[]) {\n    super(UnknownLocaleError.buildMessage(locale, localeCodes));\n    this.name = \"UnknownLocaleError\";\n  }\n\n  private static buildMessage(locale: string, localeCodes: string[]): string {\n    return (\n      `Cannot set locale \"${locale}\": it is not in the configured \"app.localeCodes\" list ` +\n      `(${localeCodes.map((code) => `\"${code}\"`).join(\", \")}). Add \"${locale}\" to ` +\n      `\"app.localeCodes\" or pass one of the configured locales instead.`\n    );\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AAcA,IAAa,qBAAb,MAAa,2BAA2B,MAAM;CAC5C,AAAO,YAAY,QAAgB,aAAuB;EACxD,MAAM,mBAAmB,aAAa,QAAQ,WAAW,CAAC;EAC1D,KAAK,OAAO;CACd;CAEA,OAAe,aAAa,QAAgB,aAA+B;EACzE,OACE,sBAAsB,OAAO,yDACzB,YAAY,KAAK,SAAS,IAAI,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,EAAE,UAAU,OAAO;CAG3E;AACF"}
+{"version":3,"file":"unknown-locale-error.mjs","names":[],"sources":["../../../../../../../../packages/core/src/errors/unknown-locale-error.ts"],"sourcesContent":["/**\n * Thrown by `response.setLocale(locale)` when `locale` is outside the\n * application's declared `app.localeCodes` allow-list.\n *\n * Silently writing a locale cookie for a locale the app cannot serve is a\n * NEW silent failure — `request.locale` would read the cookie back, fail its\n * own allow-list check (`Request.cacheLocale`), and fall back to the default\n * with nothing telling the caller why the switch never took. Failing here,\n * at the write, names the mistake at its source instead of downstream.\n *\n * Only raised when `app.localeCodes` is declared — with no list declared\n * there is nothing to fail against, matching `Request.cacheLocale`'s own\n * fail-open rule.\n */\nexport class UnknownLocaleError extends Error {\n  /** Stable Warlock error code; `warlock explain WL1008` prints the fix. */\n  public readonly code = \"WL1008\";\n\n  public constructor(locale: string, localeCodes: string[]) {\n    super(UnknownLocaleError.buildMessage(locale, localeCodes));\n    this.name = \"UnknownLocaleError\";\n  }\n\n  private static buildMessage(locale: string, localeCodes: string[]): string {\n    return (\n      `Cannot set locale \"${locale}\": it is not in the configured \"app.localeCodes\" list ` +\n      `(${localeCodes.map((code) => `\"${code}\"`).join(\", \")}). Add \"${locale}\" to ` +\n      `\"app.localeCodes\" or pass one of the configured locales instead.`\n    );\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AAcA,IAAa,qBAAb,MAAa,2BAA2B,MAAM;CAI5C,AAAO,YAAY,QAAgB,aAAuB;EACxD,MAAM,mBAAmB,aAAa,QAAQ,WAAW,CAAC;cAHrC;EAIrB,KAAK,OAAO;CACd;CAEA,OAAe,aAAa,QAAgB,aAA+B;EACzE,OACE,sBAAsB,OAAO,yDACzB,YAAY,KAAK,SAAS,IAAI,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,EAAE,UAAU,OAAO;CAG3E;AACF"}

package/esm/errors/warlock-error.d.mts

@@ -0,0 +1,21 @@
+import { WarlockErrorCode } from "./error-codes.mjs";
+//#region ../../packages/core/src/errors/warlock-error.d.ts
+/**
+ * A framework error with a stable {@link WarlockErrorCode}.
+ *
+ * Thrown where core used to throw a bare `Error`, so the failure can be looked
+ * up (`warlock explain <code>`) instead of matched by message. Still an
+ * `Error`: existing `catch` blocks and message assertions keep working.
+ *
+ * @example
+ * throw new WarlockError("WL3003", `Route name "${name}" not found`);
+ */
+export declare class WarlockError extends Error {
+  /** Stable Warlock error code; `warlock explain <code>` prints the fix. */
+  readonly code: WarlockErrorCode;
+  constructor(code: WarlockErrorCode, message: string, options?: {
+    cause?: unknown;
+  });
+}
+//#endregion
+//# sourceMappingURL=warlock-error.d.mts.map

package/esm/errors/warlock-error.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"warlock-error.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/errors/warlock-error.ts"],"mappings":";;;;;;;;;;;;qBAYa,qBAAqB;;WAEhB,MAAM;EAEtB,YAAmB,MAAM,kBAAkB,iBAAiB;IAAY"}

package/esm/errors/warlock-error.mjs

@@ -0,0 +1,22 @@
+//#region ../../packages/core/src/errors/warlock-error.ts
+/**
+* A framework error with a stable {@link WarlockErrorCode}.
+*
+* Thrown where core used to throw a bare `Error`, so the failure can be looked
+* up (`warlock explain <code>`) instead of matched by message. Still an
+* `Error`: existing `catch` blocks and message assertions keep working.
+*
+* @example
+* throw new WarlockError("WL3003", `Route name "${name}" not found`);
+*/
+var WarlockError = class extends Error {
+	constructor(code, message, options) {
+		super(message, options);
+		this.name = "WarlockError";
+		this.code = code;
+	}
+};
+
+//#endregion
+export { WarlockError };
+//# sourceMappingURL=warlock-error.mjs.map

package/esm/errors/warlock-error.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"warlock-error.mjs","names":[],"sources":["../../../../../../../../packages/core/src/errors/warlock-error.ts"],"sourcesContent":["import type { WarlockErrorCode } from \"./error-codes\";\n\n/**\n * A framework error with a stable {@link WarlockErrorCode}.\n *\n * Thrown where core used to throw a bare `Error`, so the failure can be looked\n * up (`warlock explain <code>`) instead of matched by message. Still an\n * `Error`: existing `catch` blocks and message assertions keep working.\n *\n * @example\n * throw new WarlockError(\"WL3003\", `Route name \"${name}\" not found`);\n */\nexport class WarlockError extends Error {\n  /** Stable Warlock error code; `warlock explain <code>` prints the fix. */\n  public readonly code: WarlockErrorCode;\n\n  public constructor(code: WarlockErrorCode, message: string, options?: { cause?: unknown }) {\n    super(message, options);\n    this.name = \"WarlockError\";\n    this.code = code;\n  }\n}\n"],"mappings":";;;;;;;;;;;AAYA,IAAa,eAAb,cAAkC,MAAM;CAItC,AAAO,YAAY,MAAwB,SAAiB,SAA+B;EACzF,MAAM,SAAS,OAAO;EACtB,KAAK,OAAO;EACZ,KAAK,OAAO;CACd;AACF"}

package/esm/generations/add-command.action.mjs

@@ -1,11 +1,12 @@
 import { rootPath, srcPath } from "../utils/paths.mjs";
 import "../utils/index.mjs";
 import { getWarlockVersion } from "../utils/framework-vesion.mjs";
+import { isGenerationDryRun, recordSkippedFile, setGenerationDetail } from "./generation-run.mjs";
+import { fileExistsAsync, getFileAsync, getJsonFileAsync, putFileAsync, putJsonFileAsync } from "./generation-fs.mjs";
 import { detectPackageManager, getAddCommand, getExactAddCommand } from "../updater/package-manager.mjs";
 import { featuresMap } from "./features/index.mjs";
 import { getPnpmVersion, isInsideParentPnpmWorkspace, mergeOnlyBuiltDependencies, mergePackageJsonBuildApprovals, mergePnpmSharpApproval, pnpmBuildApprovalLayout } from "./pnpm-build-approvals.mjs";
 import { colors } from "@mongez/copper";
-import { fileExistsAsync, getFileAsync, getJsonFileAsync, putFileAsync, putJsonFileAsync } from "@warlock.js/fs";
 import { execSync } from "node:child_process";
 
 //#region ../../packages/core/src/generations/add-command.action.ts
@@ -37,6 +38,10 @@ async function addCommandAction(options) {
 	const features = options.args;
 	const { packageManager, list, noInstall } = options.options;
 	if (list) {
+		setGenerationDetail("features", allowedFeatures.map((feature) => ({
+			name: feature,
+			description: featuresMap[feature]?.description ?? ""
+		})));
 		console.log("Available Features:");
 		for (const feature of allowedFeatures) {
 			const definition = featuresMap[feature];
@@ -73,13 +78,23 @@ async function addCommandAction(options) {
 		console.log(`${colors.yellowBright(devDependency)} is already installed, skipping...`);
 		delete devDependencies[devDependency];
 	}
-	if (noInstall) await recordDependencies(dependencies, devDependencies);
+	setGenerationDetail("features", resolvedFeatures);
+	setGenerationDetail("dependencies", { ...dependencies });
+	setGenerationDetail("devDependencies", { ...devDependencies });
+	if (isGenerationDryRun()) {
+		console.log(`Dry run: would install ${colors.magenta(Object.keys({
+			...dependencies,
+			...devDependencies
+		}).join(", ") || "nothing")}`);
+		await recordDependencies(dependencies, devDependencies);
+	} else if (noInstall) await recordDependencies(dependencies, devDependencies);
 	else {
 		if ((packageManager ?? await detectPackageManager()) === "pnpm" && dependencies.sharp !== void 0) await approvePnpmSharpBuild();
 		await installDependencies(packageManager, dependencies, devDependencies);
 	}
 	for (const [name, config] of Object.entries(ejectConfigs)) {
 		if (await fileExistsAsync(srcPath(`config/${name}.ts`))) {
+			recordSkippedFile(srcPath(`config/${name}.ts`), "exists");
 			console.log(`${colors.yellowBright(name)} config already exists, skipping...`);
 			continue;
 		}
@@ -91,6 +106,7 @@ async function addCommandAction(options) {
 		const featurePackages = featuresMap[feature];
 		if (featurePackages?.onExecuting) await featurePackages.onExecuting(options);
 	}
+	setGenerationDetail("scripts", { ...scripts });
 	if (Object.keys(scripts).length > 0) {
 		console.log(`Adding scripts ${colors.magenta(Object.keys(scripts).join(", "))}`);
 		const packageJsonPath = rootPath("package.json");
@@ -122,7 +138,8 @@ async function approvePnpmSharpBuild() {
 	const layout = pnpmBuildApprovalLayout(getPnpmVersion(rootPath()));
 	if (layout === "packageJson") {
 		const packageJsonPath = rootPath("package.json");
-		await putJsonFileAsync(packageJsonPath, mergePackageJsonBuildApprovals(await getJsonFileAsync(packageJsonPath), ["sharp"]));
+		const packageJson = await getJsonFileAsync(packageJsonPath);
+		await putJsonFileAsync(packageJsonPath, mergePackageJsonBuildApprovals(packageJson, ["sharp"]));
 		return;
 	}
 	const current = hasWorkspaceFile ? await getFileAsync(workspacePath) : "";
@@ -181,7 +198,7 @@ async function recordDependencies(dependencies, devDependencies) {
 	Object.assign(packageJson.devDependencies, devDependencies);
 	await putJsonFileAsync(packageJsonPath, packageJson);
 	const recorded = [...Object.keys(dependencies), ...Object.keys(devDependencies)];
-	console.log(`Recorded ${colors.green(recorded.join(", "))} in package.json (install skipped via --no-install)`);
+	console.log(`Recorded ${colors.green(recorded.join(", "))} in package.json (${isGenerationDryRun() ? "dry run: nothing installed" : "install skipped via --no-install"})`);
 }
 function validateFeatures(features) {
 	for (const feature of features) if (!allowedFeatures.includes(feature)) {
@@ -191,5 +208,5 @@ function validateFeatures(features) {
 }
 
 //#endregion
-export { addCommandAction };
+export { addCommandAction, allowedFeatures, featuresMap, installDependencies, resolveWarlockDependencyVersions };
 //# sourceMappingURL=add-command.action.mjs.map

package/esm/generations/add-command.action.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"add-command.action.mjs","names":[],"sources":["../../../../../../../../packages/core/src/generations/add-command.action.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\nimport {\n  fileExistsAsync,\n  getFileAsync,\n  getJsonFileAsync,\n  putFileAsync,\n  putJsonFileAsync,\n} from \"@warlock.js/fs\";\nimport { execSync } from \"node:child_process\";\nimport type { CommandActionData } from \"../commands/types\";\nimport {\n  detectPackageManager,\n  getAddCommand,\n  getExactAddCommand,\n  type PackageManager,\n} from \"../updater/package-manager\";\nimport { rootPath, srcPath } from \"../utils\";\nimport { getWarlockVersion } from \"../utils/framework-vesion\";\nimport { featuresMap } from \"./features\";\nimport {\n  getPnpmVersion,\n  isInsideParentPnpmWorkspace,\n  mergeOnlyBuiltDependencies,\n  mergePackageJsonBuildApprovals,\n  mergePnpmSharpApproval,\n  pnpmBuildApprovalLayout,\n} from \"./pnpm-build-approvals\";\n\nexport { featuresMap };\nexport type { FeatureDefinition } from \"./features\";\n\n/**\n * The parts of a project `package.json` this action reads or writes. Deliberately\n * partial — it describes what we touch, not the whole manifest.\n */\ntype ProjectPackageJson = {\n  dependencies?: Record<string, string>;\n  devDependencies?: Record<string, string>;\n  scripts?: Record<string, string>;\n};\n\nexport const allowedFeatures = Object.keys(featuresMap);\n\nfunction isWarlockPackage(packageName: string): boolean {\n  return packageName.startsWith(\"@warlock.js/\");\n}\n\n/**\n * Resolve the internal feature-map placeholder to the version of Core that is\n * actually executing the command. Every @warlock.js package is lockstep, so\n * Core is the single source of truth; non-Warlock dependencies are untouched.\n */\nexport function resolveWarlockDependencyVersions(\n  dependencies: Record<string, string>,\n  frameworkVersion: string,\n): void {\n  for (const dependency of Object.keys(dependencies)) {\n    if (isWarlockPackage(dependency)) {\n      dependencies[dependency] = frameworkVersion;\n    }\n  }\n}\n\nfunction resolveFeatures(features: string[], visited = new Set<string>()): string[] {\n  const resolved: string[] = [];\n\n  for (const feature of features) {\n    if (visited.has(feature)) continue;\n    visited.add(feature);\n\n    const def = featuresMap[feature];\n\n    // `addCommandAction` runs `validateFeatures()` before calling this, and the\n    // recursive calls below pass `requires` entries that come out of the map\n    // itself — so every lookup resolves. Skipping an unresolvable one keeps a\n    // typo from crashing the command with `Cannot read properties of\n    // undefined`, which names neither the feature nor the fact that it was the\n    // ARGUMENT that was wrong.\n    if (def === undefined) continue;\n\n    if (def.requires?.length) {\n      resolved.push(...resolveFeatures(def.requires, visited));\n    }\n\n    resolved.push(feature);\n  }\n\n  return resolved;\n}\n\nexport async function addCommandAction(options: CommandActionData) {\n  const features = options.args;\n  const { packageManager, list, noInstall } = options.options;\n\n  if (list) {\n    console.log(\"Available Features:\");\n\n    for (const feature of allowedFeatures) {\n      const definition = featuresMap[feature];\n\n      // `allowedFeatures` is derived from this same map, so this resolves.\n      if (definition === undefined) continue;\n\n      console.log(`- ${colors.yellowBright(feature)}: ${colors.green(definition.description)}`);\n    }\n\n    process.exit(0);\n  }\n\n  validateFeatures(features);\n\n  const resolvedFeatures = resolveFeatures(features);\n\n  const dependencies: Record<string, string> = {};\n  const devDependencies: Record<string, string> = {};\n  const ejectConfigs: Record<string, { content: string; name: string }> = {};\n  const scripts: Record<string, string> = {};\n\n  for (const feature of resolvedFeatures) {\n    const featurePackages = featuresMap[feature as keyof typeof featuresMap];\n\n    // Validated upstream; see the note in resolveFeatures above.\n    if (featurePackages === undefined) continue;\n\n    Object.assign(dependencies, featurePackages.dependencies);\n    if (featurePackages.devDependencies) {\n      Object.assign(devDependencies, featurePackages.devDependencies);\n    }\n\n    if (featurePackages.ejectConfig) {\n      ejectConfigs[featurePackages.ejectConfig.name] = featurePackages.ejectConfig;\n    }\n\n    if (featurePackages.script) {\n      Object.assign(scripts, featurePackages.script);\n    }\n  }\n\n  // Pin every @warlock.js/* feature package to the INSTALLED framework version so\n  // a scaffolded project's features match its core version instead of drifting to\n  // the feature map's static range.\n  const frameworkVersion = await getWarlockVersion();\n  resolveWarlockDependencyVersions(dependencies, frameworkVersion);\n  resolveWarlockDependencyVersions(devDependencies, frameworkVersion);\n\n  const currentPackageJson = await getJsonFileAsync<ProjectPackageJson>(rootPath(\"package.json\"));\n\n  // Fresh templates may omit one of the maps — guard before reading.\n  currentPackageJson.dependencies = currentPackageJson.dependencies ?? {};\n  currentPackageJson.devDependencies = currentPackageJson.devDependencies ?? {};\n\n  // Skip anything already present so we never downgrade an existing pin.\n  for (const dependency of Object.keys(dependencies)) {\n    if (currentPackageJson.dependencies[dependency]) {\n      console.log(`${colors.yellowBright(dependency)} is already installed, skipping...`);\n      delete dependencies[dependency];\n    }\n  }\n\n  for (const devDependency of Object.keys(devDependencies)) {\n    if (currentPackageJson.devDependencies[devDependency]) {\n      console.log(`${colors.yellowBright(devDependency)} is already installed, skipping...`);\n      delete devDependencies[devDependency];\n    }\n  }\n\n  if (noInstall) {\n    await recordDependencies(dependencies, devDependencies);\n  } else {\n    const resolvedPackageManager =\n      (packageManager as PackageManager | undefined) ?? (await detectPackageManager());\n    if (resolvedPackageManager === \"pnpm\" && dependencies.sharp !== undefined) {\n      await approvePnpmSharpBuild();\n    }\n    await installDependencies(\n      packageManager as PackageManager | undefined,\n      dependencies,\n      devDependencies,\n    );\n  }\n\n  for (const [name, config] of Object.entries(ejectConfigs)) {\n    if (await fileExistsAsync(srcPath(`config/${name}.ts`))) {\n      console.log(`${colors.yellowBright(name)} config already exists, skipping...`);\n      continue;\n    }\n\n    console.log(`Creating ${colors.magenta(name)} config...`);\n\n    await putFileAsync(srcPath(`config/${name}.ts`), config.content);\n\n    console.log(`${colors.green(name)} config created successfully`);\n  }\n\n  // now loop again over features to execute onExecuting\n  for (const feature of resolvedFeatures) {\n    const featurePackages = featuresMap[feature as keyof typeof featuresMap];\n\n    if (featurePackages?.onExecuting) {\n      await featurePackages.onExecuting(options);\n    }\n  }\n\n  if (Object.keys(scripts).length > 0) {\n    console.log(`Adding scripts ${colors.magenta(Object.keys(scripts).join(\", \"))}`);\n    const packageJsonPath = rootPath(\"package.json\");\n    const packageJson = await getJsonFileAsync<ProjectPackageJson>(packageJsonPath);\n    packageJson.scripts = { ...(packageJson.scripts ?? {}), ...scripts };\n    await putJsonFileAsync(packageJsonPath, packageJson);\n\n    console.log(`Scripts added successfully ${colors.green(Object.keys(scripts).join(\", \"))}`);\n  }\n}\n\n/**\n * Let pnpm run sharp's install script, written where the INSTALLED pnpm reads\n * approvals (see `pnpmBuildApprovalLayout`). pnpm 9 and 10.0–10.4 reject a\n * settings-only `pnpm-workspace.yaml`, so for them the approval goes into\n * package.json and no workspace file is created.\n *\n * An app inside a parent pnpm workspace gets no per-app policy: the parent's\n * workspace owns it, and a nested workspace file would make a second root.\n */\nasync function approvePnpmSharpBuild(): Promise<void> {\n  const workspacePath = rootPath(\"pnpm-workspace.yaml\");\n  const hasWorkspaceFile = await fileExistsAsync(workspacePath);\n\n  if (!hasWorkspaceFile && isInsideParentPnpmWorkspace(rootPath())) {\n    console.log(\n      `${colors.yellowBright(\"sharp\")} needs its install script approved in the parent pnpm workspace's settings.`,\n    );\n    return;\n  }\n\n  const layout = pnpmBuildApprovalLayout(getPnpmVersion(rootPath()));\n\n  if (layout === \"packageJson\") {\n    const packageJsonPath = rootPath(\"package.json\");\n    const packageJson = await getJsonFileAsync<ProjectPackageJson>(packageJsonPath);\n\n    await putJsonFileAsync(packageJsonPath, mergePackageJsonBuildApprovals(packageJson, [\"sharp\"]));\n    return;\n  }\n\n  const current = hasWorkspaceFile ? await getFileAsync(workspacePath) : \"\";\n  const updated =\n    layout === \"onlyBuiltDependencies\"\n      ? mergeOnlyBuiltDependencies(current, [\"sharp\"])\n      : mergePnpmSharpApproval(current);\n\n  if (updated !== current) await putFileAsync(workspacePath, updated);\n}\n\n/**\n * Install the resolved dependency sets through the project's package manager.\n * Runs two passes (prod then dev) so each lands in the correct section.\n */\nexport async function installDependencies(\n  packageManager: PackageManager | undefined,\n  dependencies: Record<string, string>,\n  devDependencies: Record<string, string>,\n  exec: (command: string, options: { cwd: string; stdio: \"inherit\" }) => unknown = execSync,\n) {\n  // `--package-manager` is optional; without it, fall back to the lockfile.\n  const resolvedPackageManager = packageManager ?? (await detectPackageManager());\n  const packageManagerCommand = getAddCommand(resolvedPackageManager);\n  const exactPackageManagerCommand = getExactAddCommand(resolvedPackageManager);\n\n  const installDependencySet = (dependencySet: Record<string, string>, development: boolean) => {\n    const regularSpecs: string[] = [];\n    const exactWarlockSpecs: string[] = [];\n\n    for (const [name, version] of Object.entries(dependencySet)) {\n      const spec = `${name}@${version}`;\n      (isWarlockPackage(name) ? exactWarlockSpecs : regularSpecs).push(spec);\n    }\n\n    const developmentFlag = development ? \" -D\" : \"\";\n    const runInstall = (command: string, specs: string[]) => {\n      if (specs.length === 0) return;\n\n      exec(`${command} ${specs.join(\" \")}${developmentFlag}`, {\n        cwd: process.cwd(),\n        stdio: \"inherit\",\n      });\n    };\n\n    runInstall(packageManagerCommand, regularSpecs);\n    runInstall(exactPackageManagerCommand, exactWarlockSpecs);\n  };\n\n  if (Object.keys(dependencies).length > 0) {\n    console.log(`Installing dependencies ${colors.magenta(Object.keys(dependencies).join(\", \"))}`);\n\n    installDependencySet(dependencies, false);\n\n    console.log(\n      `Dependencies installed successfully ${colors.green(Object.keys(dependencies).join(\", \"))}`,\n    );\n  }\n\n  if (Object.keys(devDependencies).length > 0) {\n    console.log(\n      `Installing dev dependencies ${colors.magenta(Object.keys(devDependencies).join(\", \"))}`,\n    );\n\n    installDependencySet(devDependencies, true);\n\n    console.log(\n      `Dev dependencies installed successfully ${colors.green(Object.keys(devDependencies).join(\", \"))}`,\n    );\n  }\n}\n\n/**\n * Write the resolved dependency sets into package.json without installing.\n * Used by `--no-install` so a scaffolder can batch every feature into one\n * install pass after the command returns. Versions come from the feature map.\n */\nasync function recordDependencies(\n  dependencies: Record<string, string>,\n  devDependencies: Record<string, string>,\n) {\n  if (Object.keys(dependencies).length === 0 && Object.keys(devDependencies).length === 0) {\n    return;\n  }\n\n  const packageJsonPath = rootPath(\"package.json\");\n  const packageJson = await getJsonFileAsync<ProjectPackageJson>(packageJsonPath);\n\n  packageJson.dependencies = packageJson.dependencies ?? {};\n  packageJson.devDependencies = packageJson.devDependencies ?? {};\n\n  Object.assign(packageJson.dependencies, dependencies);\n  Object.assign(packageJson.devDependencies, devDependencies);\n\n  await putJsonFileAsync(packageJsonPath, packageJson);\n\n  const recorded = [...Object.keys(dependencies), ...Object.keys(devDependencies)];\n\n  console.log(\n    `Recorded ${colors.green(recorded.join(\", \"))} in package.json (install skipped via --no-install)`,\n  );\n}\n\nfunction validateFeatures(features: string[]) {\n  for (const feature of features) {\n    if (!allowedFeatures.includes(feature)) {\n      console.log(\n        `Feature ${colors.redBright(feature)} is not allowed, allowed features are: ${colors.green(allowedFeatures.join(\", \"))}`,\n      );\n      process.exit(1);\n    }\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"add-command.action.mjs","names":[],"sources":["../../../../../../../../packages/core/src/generations/add-command.action.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\nimport {\n  fileExistsAsync,\n  getFileAsync,\n  getJsonFileAsync,\n  putFileAsync,\n  putJsonFileAsync,\n  recordSkippedFile,\n} from \"./generation-fs\";\nimport { isGenerationDryRun, setGenerationDetail } from \"./generation-run\";\nimport { execSync } from \"node:child_process\";\nimport type { CommandActionData } from \"../commands/types\";\nimport {\n  detectPackageManager,\n  getAddCommand,\n  getExactAddCommand,\n  type PackageManager,\n} from \"../updater/package-manager\";\nimport { rootPath, srcPath } from \"../utils\";\nimport { getWarlockVersion } from \"../utils/framework-vesion\";\nimport { featuresMap } from \"./features\";\nimport {\n  getPnpmVersion,\n  isInsideParentPnpmWorkspace,\n  mergeOnlyBuiltDependencies,\n  mergePackageJsonBuildApprovals,\n  mergePnpmSharpApproval,\n  pnpmBuildApprovalLayout,\n} from \"./pnpm-build-approvals\";\n\nexport { featuresMap };\nexport type { FeatureDefinition } from \"./features\";\n\n/**\n * The parts of a project `package.json` this action reads or writes. Deliberately\n * partial — it describes what we touch, not the whole manifest.\n */\ntype ProjectPackageJson = {\n  dependencies?: Record<string, string>;\n  devDependencies?: Record<string, string>;\n  scripts?: Record<string, string>;\n};\n\nexport const allowedFeatures = Object.keys(featuresMap);\n\nfunction isWarlockPackage(packageName: string): boolean {\n  return packageName.startsWith(\"@warlock.js/\");\n}\n\n/**\n * Resolve the internal feature-map placeholder to the version of Core that is\n * actually executing the command. Every @warlock.js package is lockstep, so\n * Core is the single source of truth; non-Warlock dependencies are untouched.\n */\nexport function resolveWarlockDependencyVersions(\n  dependencies: Record<string, string>,\n  frameworkVersion: string,\n): void {\n  for (const dependency of Object.keys(dependencies)) {\n    if (isWarlockPackage(dependency)) {\n      dependencies[dependency] = frameworkVersion;\n    }\n  }\n}\n\nfunction resolveFeatures(features: string[], visited = new Set<string>()): string[] {\n  const resolved: string[] = [];\n\n  for (const feature of features) {\n    if (visited.has(feature)) continue;\n    visited.add(feature);\n\n    const def = featuresMap[feature];\n\n    // `addCommandAction` runs `validateFeatures()` before calling this, and the\n    // recursive calls below pass `requires` entries that come out of the map\n    // itself — so every lookup resolves. Skipping an unresolvable one keeps a\n    // typo from crashing the command with `Cannot read properties of\n    // undefined`, which names neither the feature nor the fact that it was the\n    // ARGUMENT that was wrong.\n    if (def === undefined) continue;\n\n    if (def.requires?.length) {\n      resolved.push(...resolveFeatures(def.requires, visited));\n    }\n\n    resolved.push(feature);\n  }\n\n  return resolved;\n}\n\nexport async function addCommandAction(options: CommandActionData) {\n  const features = options.args;\n  const { packageManager, list, noInstall } = options.options;\n\n  if (list) {\n    setGenerationDetail(\n      \"features\",\n      allowedFeatures.map((feature) => ({\n        name: feature,\n        description: featuresMap[feature]?.description ?? \"\",\n      })),\n    );\n\n    console.log(\"Available Features:\");\n\n    for (const feature of allowedFeatures) {\n      const definition = featuresMap[feature];\n\n      // `allowedFeatures` is derived from this same map, so this resolves.\n      if (definition === undefined) continue;\n\n      console.log(`- ${colors.yellowBright(feature)}: ${colors.green(definition.description)}`);\n    }\n\n    process.exit(0);\n  }\n\n  validateFeatures(features);\n\n  const resolvedFeatures = resolveFeatures(features);\n\n  const dependencies: Record<string, string> = {};\n  const devDependencies: Record<string, string> = {};\n  const ejectConfigs: Record<string, { content: string; name: string }> = {};\n  const scripts: Record<string, string> = {};\n\n  for (const feature of resolvedFeatures) {\n    const featurePackages = featuresMap[feature as keyof typeof featuresMap];\n\n    // Validated upstream; see the note in resolveFeatures above.\n    if (featurePackages === undefined) continue;\n\n    Object.assign(dependencies, featurePackages.dependencies);\n    if (featurePackages.devDependencies) {\n      Object.assign(devDependencies, featurePackages.devDependencies);\n    }\n\n    if (featurePackages.ejectConfig) {\n      ejectConfigs[featurePackages.ejectConfig.name] = featurePackages.ejectConfig;\n    }\n\n    if (featurePackages.script) {\n      Object.assign(scripts, featurePackages.script);\n    }\n  }\n\n  // Pin every @warlock.js/* feature package to the INSTALLED framework version so\n  // a scaffolded project's features match its core version instead of drifting to\n  // the feature map's static range.\n  const frameworkVersion = await getWarlockVersion();\n  resolveWarlockDependencyVersions(dependencies, frameworkVersion);\n  resolveWarlockDependencyVersions(devDependencies, frameworkVersion);\n\n  const currentPackageJson = await getJsonFileAsync<ProjectPackageJson>(rootPath(\"package.json\"));\n\n  // Fresh templates may omit one of the maps — guard before reading.\n  currentPackageJson.dependencies = currentPackageJson.dependencies ?? {};\n  currentPackageJson.devDependencies = currentPackageJson.devDependencies ?? {};\n\n  // Skip anything already present so we never downgrade an existing pin.\n  for (const dependency of Object.keys(dependencies)) {\n    if (currentPackageJson.dependencies[dependency]) {\n      console.log(`${colors.yellowBright(dependency)} is already installed, skipping...`);\n      delete dependencies[dependency];\n    }\n  }\n\n  for (const devDependency of Object.keys(devDependencies)) {\n    if (currentPackageJson.devDependencies[devDependency]) {\n      console.log(`${colors.yellowBright(devDependency)} is already installed, skipping...`);\n      delete devDependencies[devDependency];\n    }\n  }\n\n  setGenerationDetail(\"features\", resolvedFeatures);\n  setGenerationDetail(\"dependencies\", { ...dependencies });\n  setGenerationDetail(\"devDependencies\", { ...devDependencies });\n\n  if (isGenerationDryRun()) {\n    // A preview installs nothing; package.json is \"edited\" in the overlay so\n    // the report lists it, and later steps read the previewed manifest.\n    console.log(\n      `Dry run: would install ${colors.magenta(Object.keys({ ...dependencies, ...devDependencies }).join(\", \") || \"nothing\")}`,\n    );\n    await recordDependencies(dependencies, devDependencies);\n  } else if (noInstall) {\n    await recordDependencies(dependencies, devDependencies);\n  } else {\n    const resolvedPackageManager =\n      (packageManager as PackageManager | undefined) ?? (await detectPackageManager());\n    if (resolvedPackageManager === \"pnpm\" && dependencies.sharp !== undefined) {\n      await approvePnpmSharpBuild();\n    }\n    await installDependencies(\n      packageManager as PackageManager | undefined,\n      dependencies,\n      devDependencies,\n    );\n  }\n\n  for (const [name, config] of Object.entries(ejectConfigs)) {\n    if (await fileExistsAsync(srcPath(`config/${name}.ts`))) {\n      recordSkippedFile(srcPath(`config/${name}.ts`), \"exists\");\n      console.log(`${colors.yellowBright(name)} config already exists, skipping...`);\n      continue;\n    }\n\n    console.log(`Creating ${colors.magenta(name)} config...`);\n\n    await putFileAsync(srcPath(`config/${name}.ts`), config.content);\n\n    console.log(`${colors.green(name)} config created successfully`);\n  }\n\n  // now loop again over features to execute onExecuting\n  for (const feature of resolvedFeatures) {\n    const featurePackages = featuresMap[feature as keyof typeof featuresMap];\n\n    if (featurePackages?.onExecuting) {\n      await featurePackages.onExecuting(options);\n    }\n  }\n\n  setGenerationDetail(\"scripts\", { ...scripts });\n\n  if (Object.keys(scripts).length > 0) {\n    console.log(`Adding scripts ${colors.magenta(Object.keys(scripts).join(\", \"))}`);\n    const packageJsonPath = rootPath(\"package.json\");\n    const packageJson = await getJsonFileAsync<ProjectPackageJson>(packageJsonPath);\n    packageJson.scripts = { ...(packageJson.scripts ?? {}), ...scripts };\n    await putJsonFileAsync(packageJsonPath, packageJson);\n\n    console.log(`Scripts added successfully ${colors.green(Object.keys(scripts).join(\", \"))}`);\n  }\n}\n\n/**\n * Let pnpm run sharp's install script, written where the INSTALLED pnpm reads\n * approvals (see `pnpmBuildApprovalLayout`). pnpm 9 and 10.0–10.4 reject a\n * settings-only `pnpm-workspace.yaml`, so for them the approval goes into\n * package.json and no workspace file is created.\n *\n * An app inside a parent pnpm workspace gets no per-app policy: the parent's\n * workspace owns it, and a nested workspace file would make a second root.\n */\nasync function approvePnpmSharpBuild(): Promise<void> {\n  const workspacePath = rootPath(\"pnpm-workspace.yaml\");\n  const hasWorkspaceFile = await fileExistsAsync(workspacePath);\n\n  if (!hasWorkspaceFile && isInsideParentPnpmWorkspace(rootPath())) {\n    console.log(\n      `${colors.yellowBright(\"sharp\")} needs its install script approved in the parent pnpm workspace's settings.`,\n    );\n    return;\n  }\n\n  const layout = pnpmBuildApprovalLayout(getPnpmVersion(rootPath()));\n\n  if (layout === \"packageJson\") {\n    const packageJsonPath = rootPath(\"package.json\");\n    const packageJson = await getJsonFileAsync<ProjectPackageJson>(packageJsonPath);\n\n    await putJsonFileAsync(packageJsonPath, mergePackageJsonBuildApprovals(packageJson, [\"sharp\"]));\n    return;\n  }\n\n  const current = hasWorkspaceFile ? await getFileAsync(workspacePath) : \"\";\n  const updated =\n    layout === \"onlyBuiltDependencies\"\n      ? mergeOnlyBuiltDependencies(current, [\"sharp\"])\n      : mergePnpmSharpApproval(current);\n\n  if (updated !== current) await putFileAsync(workspacePath, updated);\n}\n\n/**\n * Install the resolved dependency sets through the project's package manager.\n * Runs two passes (prod then dev) so each lands in the correct section.\n */\nexport async function installDependencies(\n  packageManager: PackageManager | undefined,\n  dependencies: Record<string, string>,\n  devDependencies: Record<string, string>,\n  exec: (command: string, options: { cwd: string; stdio: \"inherit\" }) => unknown = execSync,\n) {\n  // `--package-manager` is optional; without it, fall back to the lockfile.\n  const resolvedPackageManager = packageManager ?? (await detectPackageManager());\n  const packageManagerCommand = getAddCommand(resolvedPackageManager);\n  const exactPackageManagerCommand = getExactAddCommand(resolvedPackageManager);\n\n  const installDependencySet = (dependencySet: Record<string, string>, development: boolean) => {\n    const regularSpecs: string[] = [];\n    const exactWarlockSpecs: string[] = [];\n\n    for (const [name, version] of Object.entries(dependencySet)) {\n      const spec = `${name}@${version}`;\n      (isWarlockPackage(name) ? exactWarlockSpecs : regularSpecs).push(spec);\n    }\n\n    const developmentFlag = development ? \" -D\" : \"\";\n    const runInstall = (command: string, specs: string[]) => {\n      if (specs.length === 0) return;\n\n      exec(`${command} ${specs.join(\" \")}${developmentFlag}`, {\n        cwd: process.cwd(),\n        stdio: \"inherit\",\n      });\n    };\n\n    runInstall(packageManagerCommand, regularSpecs);\n    runInstall(exactPackageManagerCommand, exactWarlockSpecs);\n  };\n\n  if (Object.keys(dependencies).length > 0) {\n    console.log(`Installing dependencies ${colors.magenta(Object.keys(dependencies).join(\", \"))}`);\n\n    installDependencySet(dependencies, false);\n\n    console.log(\n      `Dependencies installed successfully ${colors.green(Object.keys(dependencies).join(\", \"))}`,\n    );\n  }\n\n  if (Object.keys(devDependencies).length > 0) {\n    console.log(\n      `Installing dev dependencies ${colors.magenta(Object.keys(devDependencies).join(\", \"))}`,\n    );\n\n    installDependencySet(devDependencies, true);\n\n    console.log(\n      `Dev dependencies installed successfully ${colors.green(Object.keys(devDependencies).join(\", \"))}`,\n    );\n  }\n}\n\n/**\n * Write the resolved dependency sets into package.json without installing.\n * Used by `--no-install` so a scaffolder can batch every feature into one\n * install pass after the command returns. Versions come from the feature map.\n */\nasync function recordDependencies(\n  dependencies: Record<string, string>,\n  devDependencies: Record<string, string>,\n) {\n  if (Object.keys(dependencies).length === 0 && Object.keys(devDependencies).length === 0) {\n    return;\n  }\n\n  const packageJsonPath = rootPath(\"package.json\");\n  const packageJson = await getJsonFileAsync<ProjectPackageJson>(packageJsonPath);\n\n  packageJson.dependencies = packageJson.dependencies ?? {};\n  packageJson.devDependencies = packageJson.devDependencies ?? {};\n\n  Object.assign(packageJson.dependencies, dependencies);\n  Object.assign(packageJson.devDependencies, devDependencies);\n\n  await putJsonFileAsync(packageJsonPath, packageJson);\n\n  const recorded = [...Object.keys(dependencies), ...Object.keys(devDependencies)];\n\n  console.log(\n    `Recorded ${colors.green(recorded.join(\", \"))} in package.json (${isGenerationDryRun() ? \"dry run: nothing installed\" : \"install skipped via --no-install\"})`,\n  );\n}\n\nfunction validateFeatures(features: string[]) {\n  for (const feature of features) {\n    if (!allowedFeatures.includes(feature)) {\n      console.log(\n        `Feature ${colors.redBright(feature)} is not allowed, allowed features are: ${colors.green(allowedFeatures.join(\", \"))}`,\n      );\n      process.exit(1);\n    }\n  }\n}\n"],"mappings":"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"}

package/esm/generations/features/access.feature.mjs

@@ -1,10 +1,10 @@
 import { srcPath } from "../../utils/paths.mjs";
 import "../../utils/index.mjs";
+import { ensureDirectoryAsync, fileExistsAsync, getFileAsync, putFileAsync } from "../generation-fs.mjs";
 import { accessConfigStub, accessResolverStub, accessRoleMigrationStub, accessRoleModelIndexStub, accessRoleModelStub, accessUserRoleMigrationStub, accessUserRoleModelIndexStub, accessUserRoleModelStub } from "../stubs.mjs";
 import { migrationTimestamp } from "./shared/migration-timestamp.mjs";
 import { INSTALLED_WARLOCK_VERSION } from "./types.mjs";
 import { colors } from "@mongez/copper";
-import { ensureDirectoryAsync, fileExistsAsync, getFileAsync, putFileAsync } from "@warlock.js/fs";
 
 //#region ../../packages/core/src/generations/features/access.feature.ts
 async function registerAccessLocale() {

package/esm/generations/features/access.feature.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"access.feature.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/generations/features/access.feature.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\nimport { ensureDirectoryAsync, fileExistsAsync, getFileAsync, putFileAsync } from \"@warlock.js/fs\";\nimport type { CommandActionData } from \"../../commands/types\";\nimport { srcPath } from \"../../utils\";\nimport {\n  accessConfigStub,\n  accessResolverStub,\n  accessRoleMigrationStub,\n  accessRoleModelIndexStub,\n  accessRoleModelStub,\n  accessUserRoleMigrationStub,\n  accessUserRoleModelIndexStub,\n  accessUserRoleModelStub,\n} from \"../stubs\";\nimport { migrationTimestamp } from \"./shared/migration-timestamp\";\nimport { type FeatureDefinition, INSTALLED_WARLOCK_VERSION } from \"./types\";\n\nasync function registerAccessLocale() {\n  const legacyLocalesPath = srcPath(\"app/shared/utils/locales.ts\");\n  const localesPath = srcPath(\"app/access/utils/locales.json\");\n  const forbidden = {\n    en: \"You do not have permission to perform this action.\",\n    ar: \"ليس لديك صلاحية لتنفيذ هذا الإجراء.\",\n  };\n\n  if (await fileExistsAsync(legacyLocalesPath)) {\n    const legacy = await getFileAsync(legacyLocalesPath);\n    if (legacy.includes(`groupedTranslations(\"access\"`)) {\n      console.log(`${colors.yellowBright(\"access\")} locale already registered, skipping...`);\n      return;\n    }\n  }\n\n  if (await fileExistsAsync(localesPath)) {\n    const current = await getFileAsync(localesPath);\n    let dictionary: Record<string, unknown>;\n    try {\n      const parsed: unknown = JSON.parse(current);\n      if (parsed === null || Array.isArray(parsed) || typeof parsed !== \"object\") throw new Error();\n      dictionary = parsed as Record<string, unknown>;\n    } catch {\n      console.log(\n        `${colors.yellowBright(\"access\")} locale JSON is invalid; add errors.forbidden to src/app/access/utils/locales.json manually.`,\n      );\n      return;\n    }\n\n    // A root `$group` renames the whole file's namespace; merging there would\n    // register the sentence under a key the access checks never read.\n    if (dictionary.$group !== undefined && dictionary.$group !== \"access\") {\n      console.log(\n        `${colors.yellowBright(\"access\")} locale JSON declares a different $group; add access.errors.forbidden manually.`,\n      );\n      return;\n    }\n\n    const errors = dictionary.errors;\n    if (\n      errors !== undefined &&\n      (errors === null || Array.isArray(errors) || typeof errors !== \"object\")\n    ) {\n      console.log(\n        `${colors.yellowBright(\"access\")} locale JSON cannot safely add errors.forbidden; update src/app/access/utils/locales.json manually.`,\n      );\n      return;\n    }\n    const entries = (errors ?? {}) as Record<string, unknown>;\n    if (entries.forbidden !== undefined) return;\n\n    entries.forbidden = forbidden;\n    dictionary.errors = entries;\n    await putFileAsync(localesPath, `${JSON.stringify(dictionary, null, 2)}\\n`);\n    console.log(\n      `${colors.green(\"✓\")} Registered the access locale in src/app/access/utils/locales.json`,\n    );\n    return;\n  }\n\n  await ensureDirectoryAsync(srcPath(\"app/access/utils\"));\n  await putFileAsync(localesPath, `${JSON.stringify({ errors: { forbidden } }, null, 2)}\\n`);\n  console.log(\n    `${colors.green(\"✓\")} Created src/app/access/utils/locales.json with the access locale`,\n  );\n}\n\nasync function scaffoldAccessFiles() {\n  // The resolver file is the sentinel for \"access already scaffolded\" — its\n  // presence means the role/user-role model folders and their timestamped\n  // migrations were created too, so we must not re-emit duplicate migrations on\n  // a second run.\n  const resolverPath = srcPath(\"app/access/services/access-resolver.ts\");\n\n  if (await fileExistsAsync(resolverPath)) {\n    console.log(\n      `${colors.yellowBright(\"src/app/access\")} already scaffolded, skipping resolver + role tables...`,\n    );\n\n    return;\n  }\n\n  // 1. Role catalog model folder (model + barrel + migration). The catalog row\n  //    is role name → granted permissions; managed at runtime in the DB.\n  await ensureDirectoryAsync(srcPath(\"app/access/models/role\"));\n  await putFileAsync(srcPath(\"app/access/models/role/role.model.ts\"), accessRoleModelStub);\n  await putFileAsync(srcPath(\"app/access/models/role/index.ts\"), accessRoleModelIndexStub);\n  console.log(`${colors.green(\"✓\")} Created src/app/access/models/role`);\n\n  await ensureDirectoryAsync(srcPath(\"app/access/models/role/migrations\"));\n\n  // Migration filenames carry a MM-DD-YYYY_HH-MM-SS prefix so cascade infers\n  // their createdAt and orders them deterministically (the migrate action\n  // discovers src/app/*/models/*/migrations/*). The two tables are independent\n  // (no FK between them), but the user-role migration is stamped a second later\n  // so the relative order is stable.\n  const roleMigrationFile = `${migrationTimestamp()}-role.migration.ts`;\n  await putFileAsync(\n    srcPath(\"app/access/models/role/migrations\", roleMigrationFile),\n    accessRoleMigrationStub,\n  );\n  console.log(\n    `${colors.green(\"✓\")} Created src/app/access/models/role/migrations/${roleMigrationFile}`,\n  );\n\n  // 2. UserRole assignment model folder (model + barrel + migration). The model\n  //    statics scope an unresolved tenant to GLOBAL rows only (security\n  //    invariant) — see the stub for the reasoning.\n  await ensureDirectoryAsync(srcPath(\"app/access/models/user-role\"));\n  await putFileAsync(\n    srcPath(\"app/access/models/user-role/user-role.model.ts\"),\n    accessUserRoleModelStub,\n  );\n  await putFileAsync(srcPath(\"app/access/models/user-role/index.ts\"), accessUserRoleModelIndexStub);\n  console.log(`${colors.green(\"✓\")} Created src/app/access/models/user-role`);\n\n  await ensureDirectoryAsync(srcPath(\"app/access/models/user-role/migrations\"));\n\n  const userRoleMigrationFile = `${migrationTimestamp(1)}-user-role.migration.ts`;\n  await putFileAsync(\n    srcPath(\"app/access/models/user-role/migrations\", userRoleMigrationFile),\n    accessUserRoleMigrationStub,\n  );\n  console.log(\n    `${colors.green(\"✓\")} Created src/app/access/models/user-role/migrations/${userRoleMigrationFile}`,\n  );\n\n  // 3. The DatabaseAccessResolver — the one required config seam, wired into\n  //    config/access.ts by the ejected stub.\n  await ensureDirectoryAsync(srcPath(\"app/access/services\"));\n  await putFileAsync(resolverPath, accessResolverStub);\n  console.log(`${colors.green(\"✓\")} Created src/app/access/services/access-resolver.ts`);\n}\n\nasync function completeAccessInstallation(_options: CommandActionData) {\n  await registerAccessLocale();\n  await scaffoldAccessFiles();\n}\n\nexport const accessFeature: FeatureDefinition = {\n  description:\n    \"Installs @warlock.js/access — authorization (RBAC + ABAC): permission checks, ABAC policies, and roles. Ejects config/access.ts, the DatabaseAccessResolver + Role/UserRole models and migrations into src/app/access, and registers the access locale in src/app/access/utils/locales.json\",\n  dependencies: {\n    \"@warlock.js/access\": INSTALLED_WARLOCK_VERSION,\n  },\n  ejectConfig: {\n    content: accessConfigStub,\n    name: \"access\",\n  },\n  onExecuting: completeAccessInstallation,\n};\n"],"mappings":"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"}
+{"version":3,"file":"access.feature.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/generations/features/access.feature.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\nimport {\n  ensureDirectoryAsync,\n  fileExistsAsync,\n  getFileAsync,\n  putFileAsync,\n} from \"../generation-fs\";\nimport type { CommandActionData } from \"../../commands/types\";\nimport { srcPath } from \"../../utils\";\nimport {\n  accessConfigStub,\n  accessResolverStub,\n  accessRoleMigrationStub,\n  accessRoleModelIndexStub,\n  accessRoleModelStub,\n  accessUserRoleMigrationStub,\n  accessUserRoleModelIndexStub,\n  accessUserRoleModelStub,\n} from \"../stubs\";\nimport { migrationTimestamp } from \"./shared/migration-timestamp\";\nimport { type FeatureDefinition, INSTALLED_WARLOCK_VERSION } from \"./types\";\n\nasync function registerAccessLocale() {\n  const legacyLocalesPath = srcPath(\"app/shared/utils/locales.ts\");\n  const localesPath = srcPath(\"app/access/utils/locales.json\");\n  const forbidden = {\n    en: \"You do not have permission to perform this action.\",\n    ar: \"ليس لديك صلاحية لتنفيذ هذا الإجراء.\",\n  };\n\n  if (await fileExistsAsync(legacyLocalesPath)) {\n    const legacy = await getFileAsync(legacyLocalesPath);\n    if (legacy.includes(`groupedTranslations(\"access\"`)) {\n      console.log(`${colors.yellowBright(\"access\")} locale already registered, skipping...`);\n      return;\n    }\n  }\n\n  if (await fileExistsAsync(localesPath)) {\n    const current = await getFileAsync(localesPath);\n    let dictionary: Record<string, unknown>;\n    try {\n      const parsed: unknown = JSON.parse(current);\n      if (parsed === null || Array.isArray(parsed) || typeof parsed !== \"object\") throw new Error();\n      dictionary = parsed as Record<string, unknown>;\n    } catch {\n      console.log(\n        `${colors.yellowBright(\"access\")} locale JSON is invalid; add errors.forbidden to src/app/access/utils/locales.json manually.`,\n      );\n      return;\n    }\n\n    // A root `$group` renames the whole file's namespace; merging there would\n    // register the sentence under a key the access checks never read.\n    if (dictionary.$group !== undefined && dictionary.$group !== \"access\") {\n      console.log(\n        `${colors.yellowBright(\"access\")} locale JSON declares a different $group; add access.errors.forbidden manually.`,\n      );\n      return;\n    }\n\n    const errors = dictionary.errors;\n    if (\n      errors !== undefined &&\n      (errors === null || Array.isArray(errors) || typeof errors !== \"object\")\n    ) {\n      console.log(\n        `${colors.yellowBright(\"access\")} locale JSON cannot safely add errors.forbidden; update src/app/access/utils/locales.json manually.`,\n      );\n      return;\n    }\n    const entries = (errors ?? {}) as Record<string, unknown>;\n    if (entries.forbidden !== undefined) return;\n\n    entries.forbidden = forbidden;\n    dictionary.errors = entries;\n    await putFileAsync(localesPath, `${JSON.stringify(dictionary, null, 2)}\\n`);\n    console.log(\n      `${colors.green(\"✓\")} Registered the access locale in src/app/access/utils/locales.json`,\n    );\n    return;\n  }\n\n  await ensureDirectoryAsync(srcPath(\"app/access/utils\"));\n  await putFileAsync(localesPath, `${JSON.stringify({ errors: { forbidden } }, null, 2)}\\n`);\n  console.log(\n    `${colors.green(\"✓\")} Created src/app/access/utils/locales.json with the access locale`,\n  );\n}\n\nasync function scaffoldAccessFiles() {\n  // The resolver file is the sentinel for \"access already scaffolded\" — its\n  // presence means the role/user-role model folders and their timestamped\n  // migrations were created too, so we must not re-emit duplicate migrations on\n  // a second run.\n  const resolverPath = srcPath(\"app/access/services/access-resolver.ts\");\n\n  if (await fileExistsAsync(resolverPath)) {\n    console.log(\n      `${colors.yellowBright(\"src/app/access\")} already scaffolded, skipping resolver + role tables...`,\n    );\n\n    return;\n  }\n\n  // 1. Role catalog model folder (model + barrel + migration). The catalog row\n  //    is role name → granted permissions; managed at runtime in the DB.\n  await ensureDirectoryAsync(srcPath(\"app/access/models/role\"));\n  await putFileAsync(srcPath(\"app/access/models/role/role.model.ts\"), accessRoleModelStub);\n  await putFileAsync(srcPath(\"app/access/models/role/index.ts\"), accessRoleModelIndexStub);\n  console.log(`${colors.green(\"✓\")} Created src/app/access/models/role`);\n\n  await ensureDirectoryAsync(srcPath(\"app/access/models/role/migrations\"));\n\n  // Migration filenames carry a MM-DD-YYYY_HH-MM-SS prefix so cascade infers\n  // their createdAt and orders them deterministically (the migrate action\n  // discovers src/app/*/models/*/migrations/*). The two tables are independent\n  // (no FK between them), but the user-role migration is stamped a second later\n  // so the relative order is stable.\n  const roleMigrationFile = `${migrationTimestamp()}-role.migration.ts`;\n  await putFileAsync(\n    srcPath(\"app/access/models/role/migrations\", roleMigrationFile),\n    accessRoleMigrationStub,\n  );\n  console.log(\n    `${colors.green(\"✓\")} Created src/app/access/models/role/migrations/${roleMigrationFile}`,\n  );\n\n  // 2. UserRole assignment model folder (model + barrel + migration). The model\n  //    statics scope an unresolved tenant to GLOBAL rows only (security\n  //    invariant) — see the stub for the reasoning.\n  await ensureDirectoryAsync(srcPath(\"app/access/models/user-role\"));\n  await putFileAsync(\n    srcPath(\"app/access/models/user-role/user-role.model.ts\"),\n    accessUserRoleModelStub,\n  );\n  await putFileAsync(srcPath(\"app/access/models/user-role/index.ts\"), accessUserRoleModelIndexStub);\n  console.log(`${colors.green(\"✓\")} Created src/app/access/models/user-role`);\n\n  await ensureDirectoryAsync(srcPath(\"app/access/models/user-role/migrations\"));\n\n  const userRoleMigrationFile = `${migrationTimestamp(1)}-user-role.migration.ts`;\n  await putFileAsync(\n    srcPath(\"app/access/models/user-role/migrations\", userRoleMigrationFile),\n    accessUserRoleMigrationStub,\n  );\n  console.log(\n    `${colors.green(\"✓\")} Created src/app/access/models/user-role/migrations/${userRoleMigrationFile}`,\n  );\n\n  // 3. The DatabaseAccessResolver — the one required config seam, wired into\n  //    config/access.ts by the ejected stub.\n  await ensureDirectoryAsync(srcPath(\"app/access/services\"));\n  await putFileAsync(resolverPath, accessResolverStub);\n  console.log(`${colors.green(\"✓\")} Created src/app/access/services/access-resolver.ts`);\n}\n\nasync function completeAccessInstallation(_options: CommandActionData) {\n  await registerAccessLocale();\n  await scaffoldAccessFiles();\n}\n\nexport const accessFeature: FeatureDefinition = {\n  description:\n    \"Installs @warlock.js/access — authorization (RBAC + ABAC): permission checks, ABAC policies, and roles. Ejects config/access.ts, the DatabaseAccessResolver + Role/UserRole models and migrations into src/app/access, and registers the access locale in src/app/access/utils/locales.json\",\n  dependencies: {\n    \"@warlock.js/access\": INSTALLED_WARLOCK_VERSION,\n  },\n  ejectConfig: {\n    content: accessConfigStub,\n    name: \"access\",\n  },\n  onExecuting: completeAccessInstallation,\n};\n"],"mappings":"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"}

package/esm/generations/features/bull-board.feature.mjs

@@ -1,8 +1,8 @@
 import { rootPath, srcPath } from "../../utils/paths.mjs";
 import "../../utils/index.mjs";
+import { fileExistsAsync, getFileAsync, getJsonFileAsync, putFileAsync } from "../generation-fs.mjs";
 import { insertQueueDashboardBlock } from "./shared/insert-queue-dashboard-block.mjs";
 import { colors } from "@mongez/copper";
-import { fileExistsAsync, getFileAsync, getJsonFileAsync, putFileAsync } from "@warlock.js/fs";
 
 //#region ../../packages/core/src/generations/features/bull-board.feature.ts
 /**
@@ -22,7 +22,8 @@ async function addDashboardConfigBlock() {
 `);
 		return;
 	}
-	const insertion = insertQueueDashboardBlock(await getFileAsync(configPath));
+	const current = await getFileAsync(configPath);
+	const insertion = insertQueueDashboardBlock(current);
 	if (insertion.status === "already-present") {
 		console.log(`${colors.yellowBright("dashboard")} config already present in src/config/queue.ts, skipping...`);
 		return;

package/esm/generations/features/bull-board.feature.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"bull-board.feature.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/generations/features/bull-board.feature.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\nimport { fileExistsAsync, getFileAsync, getJsonFileAsync, putFileAsync } from \"@warlock.js/fs\";\nimport type { CommandActionData } from \"../../commands/types\";\nimport { rootPath, srcPath } from \"../../utils\";\nimport { insertQueueDashboardBlock } from \"./shared/insert-queue-dashboard-block\";\nimport type { FeatureDefinition } from \"./types\";\n\n/** The parts of `package.json` this feature reads to check for its prerequisite. */\ntype ProjectPackageJson = {\n  dependencies?: Record<string, string>;\n  devDependencies?: Record<string, string>;\n};\n\n/**\n * Defensive floor: `requires: [\"queue\"]` normally installs queue first, so\n * this only fires when the dashboard step runs without it (e.g. called\n * directly), and then fails loudly instead of writing a half-wired config.\n */\nasync function isQueueInstalled(): Promise<boolean> {\n  const packageJson = await getJsonFileAsync<ProjectPackageJson>(rootPath(\"package.json\"));\n\n  return Boolean(\n    packageJson.dependencies?.[\"@warlock.js/queue\"] ||\n      packageJson.devDependencies?.[\"@warlock.js/queue\"],\n  );\n}\n\n/** Insert the `dashboard` block into `src/config/queue.ts`, without reformatting it. */\nasync function addDashboardConfigBlock(): Promise<void> {\n  const configPath = srcPath(\"config/queue.ts\");\n\n  if (!(await fileExistsAsync(configPath))) {\n    console.log(\n      `${colors.yellowBright(\"src/config/queue.ts\")} not found — add this to your queue config yourself:\\n` +\n        '  dashboard: { enabled: true, path: \"/admin/queues\", middleware: [] },\\n',\n    );\n\n    return;\n  }\n\n  const current = await getFileAsync(configPath);\n  const insertion = insertQueueDashboardBlock(current);\n\n  if (insertion.status === \"already-present\") {\n    console.log(\n      `${colors.yellowBright(\"dashboard\")} config already present in src/config/queue.ts, skipping...`,\n    );\n\n    return;\n  }\n\n  if (insertion.status === \"unrecognised\") {\n    console.log(\n      `${colors.yellowBright(\"!\")} src/config/queue.ts has no recognisable ${colors.yellowBright(\"queueConfig\")} object — ` +\n        \"add the dashboard block yourself:\\n\" +\n        '  dashboard: { enabled: true, path: \"/admin/queues\", middleware: [] },\\n',\n    );\n\n    return;\n  }\n\n  await putFileAsync(configPath, insertion.next);\n  console.log(`${colors.green(\"✓\")} Added dashboard config to src/config/queue.ts`);\n}\n\n/**\n * Wire the dashboard into the app: verify queue is installed, then add the\n * `dashboard` block to its config.\n */\nasync function completeBullBoardInstallation(_options: CommandActionData): Promise<void> {\n  if (!(await isQueueInstalled())) {\n    console.log(\n      `${colors.redBright(\"✗\")} @warlock.js/queue is not installed — run ` +\n        `${colors.yellowBright(\"warlock add queue\")} first, then ${colors.yellowBright(\"warlock add bull-board\")}.`,\n    );\n    process.exitCode = 1;\n\n    return;\n  }\n\n  await addDashboardConfigBlock();\n\n  console.log(\n    \"\\nNext: guard the dashboard with a middleware before it ships to production — an empty \" +\n      \"middleware list throws QueueDashboardUnguardedError at boot when NODE_ENV is \\\"production\\\".\",\n  );\n}\n\n/** `warlock add bull-board` — a config-driven bull-board dashboard for @warlock.js/queue. */\nexport const bullBoardFeature: FeatureDefinition = {\n  description:\n    \"Installs @bull-board/api and @bull-board/fastify and adds a dashboard block to src/config/queue.ts. Adds the queue feature first when it is missing.\",\n  requires: [\"queue\"],\n  dependencies: {\n    \"@bull-board/api\": \"^9.10.2\",\n    \"@bull-board/fastify\": \"^9.10.2\",\n  },\n  onExecuting: completeBullBoardInstallation,\n};\n"],"mappings":";;;;;;;;;;;;AAkBA,eAAe,mBAAqC;CAClD,MAAM,cAAc,MAAM,iBAAqC,SAAS,cAAc,CAAC;CAEvF,OAAO,QACL,YAAY,eAAe,wBACzB,YAAY,kBAAkB,oBAClC;AACF;;AAGA,eAAe,0BAAyC;CACtD,MAAM,aAAa,QAAQ,iBAAiB;CAE5C,IAAI,CAAE,MAAM,gBAAgB,UAAU,GAAI;EACxC,QAAQ,IACN,GAAG,OAAO,aAAa,qBAAqB,EAAE;CAEhD;EAEA;CACF;CAGA,MAAM,YAAY,0BAA0B,MADtB,aAAa,UAAU,CACM;CAEnD,IAAI,UAAU,WAAW,mBAAmB;EAC1C,QAAQ,IACN,GAAG,OAAO,aAAa,WAAW,EAAE,4DACtC;EAEA;CACF;CAEA,IAAI,UAAU,WAAW,gBAAgB;EACvC,QAAQ,IACN,GAAG,OAAO,aAAa,GAAG,EAAE,2CAA2C,OAAO,aAAa,aAAa,EAAE;;CAG5G;EAEA;CACF;CAEA,MAAM,aAAa,YAAY,UAAU,IAAI;CAC7C,QAAQ,IAAI,GAAG,OAAO,MAAM,GAAG,EAAE,+CAA+C;AAClF;;;;;AAMA,eAAe,8BAA8B,UAA4C;CACvF,IAAI,CAAE,MAAM,iBAAiB,GAAI;EAC/B,QAAQ,IACN,GAAG,OAAO,UAAU,GAAG,EAAE,4CACpB,OAAO,aAAa,mBAAmB,EAAE,eAAe,OAAO,aAAa,wBAAwB,EAAE,EAC7G;EACA,QAAQ,WAAW;EAEnB;CACF;CAEA,MAAM,wBAAwB;CAE9B,QAAQ,IACN,qLAEF;AACF;;AAGA,MAAa,mBAAsC;CACjD,aACE;CACF,UAAU,CAAC,OAAO;CAClB,cAAc;EACZ,mBAAmB;EACnB,uBAAuB;CACzB;CACA,aAAa;AACf"}
+{"version":3,"file":"bull-board.feature.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/generations/features/bull-board.feature.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\nimport { fileExistsAsync, getFileAsync, getJsonFileAsync, putFileAsync } from \"../generation-fs\";\nimport type { CommandActionData } from \"../../commands/types\";\nimport { rootPath, srcPath } from \"../../utils\";\nimport { insertQueueDashboardBlock } from \"./shared/insert-queue-dashboard-block\";\nimport type { FeatureDefinition } from \"./types\";\n\n/** The parts of `package.json` this feature reads to check for its prerequisite. */\ntype ProjectPackageJson = {\n  dependencies?: Record<string, string>;\n  devDependencies?: Record<string, string>;\n};\n\n/**\n * Defensive floor: `requires: [\"queue\"]` normally installs queue first, so\n * this only fires when the dashboard step runs without it (e.g. called\n * directly), and then fails loudly instead of writing a half-wired config.\n */\nasync function isQueueInstalled(): Promise<boolean> {\n  const packageJson = await getJsonFileAsync<ProjectPackageJson>(rootPath(\"package.json\"));\n\n  return Boolean(\n    packageJson.dependencies?.[\"@warlock.js/queue\"] ||\n    packageJson.devDependencies?.[\"@warlock.js/queue\"],\n  );\n}\n\n/** Insert the `dashboard` block into `src/config/queue.ts`, without reformatting it. */\nasync function addDashboardConfigBlock(): Promise<void> {\n  const configPath = srcPath(\"config/queue.ts\");\n\n  if (!(await fileExistsAsync(configPath))) {\n    console.log(\n      `${colors.yellowBright(\"src/config/queue.ts\")} not found — add this to your queue config yourself:\\n` +\n        '  dashboard: { enabled: true, path: \"/admin/queues\", middleware: [] },\\n',\n    );\n\n    return;\n  }\n\n  const current = await getFileAsync(configPath);\n  const insertion = insertQueueDashboardBlock(current);\n\n  if (insertion.status === \"already-present\") {\n    console.log(\n      `${colors.yellowBright(\"dashboard\")} config already present in src/config/queue.ts, skipping...`,\n    );\n\n    return;\n  }\n\n  if (insertion.status === \"unrecognised\") {\n    console.log(\n      `${colors.yellowBright(\"!\")} src/config/queue.ts has no recognisable ${colors.yellowBright(\"queueConfig\")} object — ` +\n        \"add the dashboard block yourself:\\n\" +\n        '  dashboard: { enabled: true, path: \"/admin/queues\", middleware: [] },\\n',\n    );\n\n    return;\n  }\n\n  await putFileAsync(configPath, insertion.next);\n  console.log(`${colors.green(\"✓\")} Added dashboard config to src/config/queue.ts`);\n}\n\n/**\n * Wire the dashboard into the app: verify queue is installed, then add the\n * `dashboard` block to its config.\n */\nasync function completeBullBoardInstallation(_options: CommandActionData): Promise<void> {\n  if (!(await isQueueInstalled())) {\n    console.log(\n      `${colors.redBright(\"✗\")} @warlock.js/queue is not installed — run ` +\n        `${colors.yellowBright(\"warlock add queue\")} first, then ${colors.yellowBright(\"warlock add bull-board\")}.`,\n    );\n    process.exitCode = 1;\n\n    return;\n  }\n\n  await addDashboardConfigBlock();\n\n  console.log(\n    \"\\nNext: guard the dashboard with a middleware before it ships to production — an empty \" +\n      'middleware list throws QueueDashboardUnguardedError at boot when NODE_ENV is \"production\".',\n  );\n}\n\n/** `warlock add bull-board` — a config-driven bull-board dashboard for @warlock.js/queue. */\nexport const bullBoardFeature: FeatureDefinition = {\n  description:\n    \"Installs @bull-board/api and @bull-board/fastify and adds a dashboard block to src/config/queue.ts. Adds the queue feature first when it is missing.\",\n  requires: [\"queue\"],\n  dependencies: {\n    \"@bull-board/api\": \"^9.10.2\",\n    \"@bull-board/fastify\": \"^9.10.2\",\n  },\n  onExecuting: completeBullBoardInstallation,\n};\n"],"mappings":";;;;;;;;;;;;AAkBA,eAAe,mBAAqC;CAClD,MAAM,cAAc,MAAM,iBAAqC,SAAS,cAAc,CAAC;CAEvF,OAAO,QACL,YAAY,eAAe,wBAC3B,YAAY,kBAAkB,oBAChC;AACF;;AAGA,eAAe,0BAAyC;CACtD,MAAM,aAAa,QAAQ,iBAAiB;CAE5C,IAAI,CAAE,MAAM,gBAAgB,UAAU,GAAI;EACxC,QAAQ,IACN,GAAG,OAAO,aAAa,qBAAqB,EAAE;CAEhD;EAEA;CACF;CAEA,MAAM,UAAU,MAAM,aAAa,UAAU;CAC7C,MAAM,YAAY,0BAA0B,OAAO;CAEnD,IAAI,UAAU,WAAW,mBAAmB;EAC1C,QAAQ,IACN,GAAG,OAAO,aAAa,WAAW,EAAE,4DACtC;EAEA;CACF;CAEA,IAAI,UAAU,WAAW,gBAAgB;EACvC,QAAQ,IACN,GAAG,OAAO,aAAa,GAAG,EAAE,2CAA2C,OAAO,aAAa,aAAa,EAAE;;CAG5G;EAEA;CACF;CAEA,MAAM,aAAa,YAAY,UAAU,IAAI;CAC7C,QAAQ,IAAI,GAAG,OAAO,MAAM,GAAG,EAAE,+CAA+C;AAClF;;;;;AAMA,eAAe,8BAA8B,UAA4C;CACvF,IAAI,CAAE,MAAM,iBAAiB,GAAI;EAC/B,QAAQ,IACN,GAAG,OAAO,UAAU,GAAG,EAAE,4CACpB,OAAO,aAAa,mBAAmB,EAAE,eAAe,OAAO,aAAa,wBAAwB,EAAE,EAC7G;EACA,QAAQ,WAAW;EAEnB;CACF;CAEA,MAAM,wBAAwB;CAE9B,QAAQ,IACN,qLAEF;AACF;;AAGA,MAAa,mBAAsC;CACjD,aACE;CACF,UAAU,CAAC,OAAO;CAClB,cAAc;EACZ,mBAAmB;EACnB,uBAAuB;CACzB;CACA,aAAa;AACf"}

package/esm/generations/features/mysql.feature.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"mysql.feature.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/generations/features/mysql.feature.ts"],"sourcesContent":["import type { FeatureDefinition } from \"./types\";\n\n/**\n * MySQL is not implemented by Cascade (`connectToDatabase` throws for it), so\n * installing `mysql2` would only produce an app that crashes on boot. No\n * dependencies are declared and running the feature fails loudly instead.\n */\nexport const mysqlFeature: FeatureDefinition = {\n  description: \"MySQL (not supported by @warlock.js/cascade yet)\",\n  onExecuting: async () => {\n    throw new Error(\n      \"MySQL is not supported by @warlock.js/cascade yet; use postgres or mongodb\",\n    );\n  },\n};\n"],"mappings":";;;;;;AAOA,MAAa,eAAkC;CAC7C,aAAa;CACb,aAAa,YAAY;EACvB,MAAM,IAAI,MACR,4EACF;CACF;AACF"}
+{"version":3,"file":"mysql.feature.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/generations/features/mysql.feature.ts"],"sourcesContent":["import type { FeatureDefinition } from \"./types\";\n\n/**\n * MySQL is not implemented by Cascade (`connectToDatabase` throws for it), so\n * installing `mysql2` would only produce an app that crashes on boot. No\n * dependencies are declared and running the feature fails loudly instead.\n */\nexport const mysqlFeature: FeatureDefinition = {\n  description: \"MySQL (not supported by @warlock.js/cascade yet)\",\n  onExecuting: async () => {\n    throw new Error(\"MySQL is not supported by @warlock.js/cascade yet; use postgres or mongodb\");\n  },\n};\n"],"mappings":";;;;;;AAOA,MAAa,eAAkC;CAC7C,aAAa;CACb,aAAa,YAAY;EACvB,MAAM,IAAI,MAAM,4EAA4E;CAC9F;AACF"}

package/esm/generations/features/notifications.feature.mjs

@@ -1,11 +1,12 @@
 import { srcPath } from "../../utils/paths.mjs";
 import "../../utils/index.mjs";
-import { listNotificationsControllerStub, listNotificationsSchemaStub, markAllNotificationsReadControllerStub, markNotificationReadControllerStub, markNotificationReadServiceStub, notificationControllerSpecStub, notificationLocalesStub, notificationMigrationStub, notificationModelStub, notificationResourceStub, notificationRoutesStub, notificationsConfigStub, notificationsRequestTypeStub, unreadNotificationsCountControllerStub } from "../stubs.mjs";
+import { recordSkippedFile } from "../generation-run.mjs";
+import { directoryExistsAsync, ensureDirectoryAsync, fileExistsAsync, getFileAsync, putFileAsync } from "../generation-fs.mjs";
+import { listNotificationsControllerStub, listNotificationsSchemaStub, markAllNotificationsReadControllerStub, markNotificationReadControllerStub, markNotificationReadServiceStub, notificationControllerSpecStub, notificationLocalesStub, notificationMigrationStub, notificationModelStub, notificationResourceStub, notificationRoutesStub, notificationTestFixtureStub, notificationsConfigStub, notificationsRequestTypeStub, unreadNotificationsCountControllerStub } from "../stubs.mjs";
 import { migrationTimestamp } from "./shared/migration-timestamp.mjs";
 import { INSTALLED_WARLOCK_VERSION } from "./types.mjs";
 import { dirname } from "node:path";
 import { colors } from "@mongez/copper";
-import { directoryExistsAsync, ensureDirectoryAsync, fileExistsAsync, getFileAsync, putFileAsync } from "@warlock.js/fs";
 
 //#region ../../packages/core/src/generations/features/notifications.feature.ts
 /**
@@ -49,6 +50,7 @@ async function writeModuleFile(relativePath, content, skipped) {
 	const path = srcPath("app/notifications", relativePath);
 	if (await fileExistsAsync(path)) {
 		skipped.push(relativePath);
+		recordSkippedFile(path, "exists");
 		return;
 	}
 	await ensureDirectoryAsync(dirname(path));
@@ -101,7 +103,8 @@ async function pointConfigAtLegacyModel() {
 }
 async function completeNotificationsInstallation(_options) {
 	const modelPath = srcPath("app/notifications/models/notification/notification.model.ts");
-	if (await fileExistsAsync(srcPath("app/notifications/notification.model.ts"))) {
+	const legacyModelPath = srcPath("app/notifications/notification.model.ts");
+	if (await fileExistsAsync(legacyModelPath)) {
 		if (!await fileExistsAsync(modelPath)) await pointConfigAtLegacyModel();
 		console.log(`${colors.yellowBright("src/app/notifications")} already scaffolded (5.29 layout), skipping...`);
 		return;
@@ -122,6 +125,7 @@ async function completeNotificationsInstallation(_options) {
 	await writeModuleFile("services/mark-notification-read.service.ts", markNotificationReadServiceStub, skipped);
 	await registerNotificationLocales(skipped);
 	const withSpecs = await fileExistsAsync(srcPath("test-setup.ts"));
+	if (withSpecs) await writeModuleFile("tests/notifications.fixture.ts", notificationTestFixtureStub, skipped);
 	for (const controller of notificationControllers) {
 		await writeModuleFile(`controllers/${controller.file}.ts`, controller.stub, skipped);
 		if (withSpecs) await writeModuleFile(`controllers/${controller.file}.spec.ts`, notificationControllerSpecStub(controller.method, controller.path), skipped);