create-warlock 5.0.2 → 5.2.2

package/esm/helpers/package-manager.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"package-manager.mjs","names":[],"sources":["../../../../../../create-warlock/src/helpers/package-manager.ts"],"sourcesContent":["import { exec, execSync } from \"child_process\";\r\nimport { promisify } from \"util\";\r\nimport detectPackageManager from \"which-pm-runs\";\r\n\r\nconst execAsync = promisify(exec);\r\n\r\nlet detectedPackageManager: string | undefined;\r\nlet cachedSystemManagers: string[] | undefined;\r\nlet cachedPreferredManager: string | undefined;\r\n\r\n/**\r\n * The only package managers `--pm` may select. This value reaches `spawn()`\r\n * as the executable to run and is spliced into the generated\r\n * `package.json`'s scripts — an allow-list here is a hard security\r\n * boundary, not just input hygiene, so it stays a fixed literal list\r\n * rather than anything derived from user input or the running environment.\r\n */\r\nexport const ALLOWED_PACKAGE_MANAGERS = [\"npm\", \"yarn\", \"pnpm\", \"bun\"] as const;\r\n\r\nexport type AllowedPackageManager = (typeof ALLOWED_PACKAGE_MANAGERS)[number];\r\n\r\n/** Whether `value` is one of the allow-listed package managers. */\r\nexport function isValidPackageManager(\r\n  value: string,\r\n): value is AllowedPackageManager {\r\n  return (ALLOWED_PACKAGE_MANAGERS as readonly string[]).includes(value);\r\n}\r\n\r\nexport function getPackageManager() {\r\n  if (detectedPackageManager) {\r\n    return detectedPackageManager;\r\n  }\r\n\r\n  return getPreferredPackageManager();\r\n}\r\n\r\n/**\r\n * Check if a package manager is installed\r\n */\r\nfunction isInstalled(manager: string): boolean {\r\n  try {\r\n    execSync(`${manager} --version`, { stdio: \"ignore\" });\r\n    return true;\r\n  } catch {\r\n    return false;\r\n  }\r\n}\r\n\r\n/**\r\n * Check if a package manager is installed (async)\r\n */\r\nasync function checkManager(manager: string): Promise<boolean> {\r\n  try {\r\n    await execAsync(`${manager} --version`);\r\n    return true;\r\n  } catch {\r\n    return false;\r\n  }\r\n}\r\n\r\n/**\r\n * Detect available package managers asynchronously and cache results\r\n */\r\nexport async function detectPackageManagers() {\r\n  const managers = [\"npm\"];\r\n  const checks = [checkManager(\"yarn\"), checkManager(\"pnpm\")];\r\n\r\n  const [hasYarn, hasPnpm] = await Promise.all(checks);\r\n\r\n  if (hasYarn) managers.push(\"yarn\");\r\n  if (hasPnpm) managers.push(\"pnpm\");\r\n\r\n  cachedSystemManagers = managers;\r\n\r\n  // Determine preference\r\n  const runningPm = detectPackageManager()?.name;\r\n  if (runningPm && runningPm !== \"npm\") {\r\n    cachedPreferredManager = runningPm;\r\n  } else if (hasYarn) {\r\n    cachedPreferredManager = \"yarn\";\r\n  } else if (hasPnpm) {\r\n    cachedPreferredManager = \"pnpm\";\r\n  } else {\r\n    cachedPreferredManager = \"npm\";\r\n  }\r\n}\r\n\r\n/**\r\n * Get available package managers on the system\r\n */\r\nexport function getSystemPackageManagers(): string[] {\r\n  if (cachedSystemManagers) return cachedSystemManagers;\r\n\r\n  const managers = [\"npm\"]; // npm is assumed to be always available\r\n\r\n  if (isInstalled(\"yarn\")) {\r\n    managers.push(\"yarn\");\r\n  }\r\n\r\n  if (isInstalled(\"pnpm\")) {\r\n    managers.push(\"pnpm\");\r\n  }\r\n\r\n  return managers;\r\n}\r\n\r\n/**\r\n * Get the preferred package manager based on priority\r\n */\r\nexport function getPreferredPackageManager(): string {\r\n  if (cachedPreferredManager) return cachedPreferredManager;\r\n\r\n  // Priority 1: The manager currently running the script\r\n  const runningPm = detectPackageManager()?.name;\r\n  if (runningPm && runningPm !== \"npm\") return runningPm;\r\n\r\n  // Priority 2: Yarn (if installed)\r\n  if (isInstalled(\"yarn\")) return \"yarn\";\r\n\r\n  // Priority 3: pnpm (if installed)\r\n  if (isInstalled(\"pnpm\")) return \"pnpm\";\r\n\r\n  // Priority 4: npm (default)\r\n  return \"npm\";\r\n}\r\n\r\nexport function setPackageManager(packageManager: string) {\r\n  detectedPackageManager = packageManager;\r\n}\r\n\r\nexport function installCommand() {\r\n  return `${getPackageManager()} install`;\r\n}\r\n\r\nexport function startCommand() {\r\n  if (getPackageManager() === \"npm\") return \"npm run dev\";\r\n\r\n  return `${getPackageManager()} dev`;\r\n}\r\n\r\nexport function runPackageManagerCommand(command: string) {\r\n  const packageManager = getPackageManager();\r\n\r\n  if (packageManager === \"npm\") return `npm run ${command}`;\r\n\r\n  return `${packageManager} ${command}`;\r\n}\r\n"],"mappings":";;;;;AAIA,MAAM,YAAY,UAAU,IAAI;AAEhC,IAAI;AACJ,IAAI;AACJ,IAAI;;;;;;;;AASJ,MAAa,2BAA2B;CAAC;CAAO;CAAQ;CAAQ;AAAK;;AAKrE,SAAgB,sBACd,OACgC;CAChC,OAAQ,yBAA+C,SAAS,KAAK;AACvE;AAEA,SAAgB,oBAAoB;CAClC,IAAI,wBACF,OAAO;CAGT,OAAO,2BAA2B;AACpC;;;;AAKA,SAAS,YAAY,SAA0B;CAC7C,IAAI;EACF,SAAS,GAAG,QAAQ,aAAa,EAAE,OAAO,SAAS,CAAC;EACpD,OAAO;CACT,QAAQ;EACN,OAAO;CACT;AACF;;;;AAKA,eAAe,aAAa,SAAmC;CAC7D,IAAI;EACF,MAAM,UAAU,GAAG,QAAQ,WAAW;EACtC,OAAO;CACT,QAAQ;EACN,OAAO;CACT;AACF;;;;AAKA,eAAsB,wBAAwB;CAC5C,MAAM,WAAW,CAAC,KAAK;CACvB,MAAM,SAAS,CAAC,aAAa,MAAM,GAAG,aAAa,MAAM,CAAC;CAE1D,MAAM,CAAC,SAAS,WAAW,MAAM,QAAQ,IAAI,MAAM;CAEnD,IAAI,SAAS,SAAS,KAAK,MAAM;CACjC,IAAI,SAAS,SAAS,KAAK,MAAM;CAEjC,uBAAuB;CAGvB,MAAM,YAAY,qBAAqB,CAAC,EAAE;CAC1C,IAAI,aAAa,cAAc,OAC7B,yBAAyB;MACpB,IAAI,SACT,yBAAyB;MACpB,IAAI,SACT,yBAAyB;MAEzB,yBAAyB;AAE7B;;;;AAKA,SAAgB,2BAAqC;CACnD,IAAI,sBAAsB,OAAO;CAEjC,MAAM,WAAW,CAAC,KAAK;CAEvB,IAAI,YAAY,MAAM,GACpB,SAAS,KAAK,MAAM;CAGtB,IAAI,YAAY,MAAM,GACpB,SAAS,KAAK,MAAM;CAGtB,OAAO;AACT;;;;AAKA,SAAgB,6BAAqC;CACnD,IAAI,wBAAwB,OAAO;CAGnC,MAAM,YAAY,qBAAqB,CAAC,EAAE;CAC1C,IAAI,aAAa,cAAc,OAAO,OAAO;CAG7C,IAAI,YAAY,MAAM,GAAG,OAAO;CAGhC,IAAI,YAAY,MAAM,GAAG,OAAO;CAGhC,OAAO;AACT;AAEA,SAAgB,kBAAkB,gBAAwB;CACxD,yBAAyB;AAC3B;AAYA,SAAgB,yBAAyB,SAAiB;CACxD,MAAM,iBAAiB,kBAAkB;CAEzC,IAAI,mBAAmB,OAAO,OAAO,WAAW;CAEhD,OAAO,GAAG,eAAe,GAAG;AAC9B"}
+{"version":3,"file":"package-manager.mjs","names":[],"sources":["../../../../../../create-warlock/src/helpers/package-manager.ts"],"sourcesContent":["import { exec, execSync } from \"child_process\";\r\nimport { promisify } from \"util\";\r\nimport detectPackageManager from \"which-pm-runs\";\r\n\r\nconst execAsync = promisify(exec);\r\n\r\nlet detectedPackageManager: string | undefined;\r\nlet cachedSystemManagers: string[] | undefined;\r\nlet cachedPreferredManager: string | undefined;\r\n\r\n/**\r\n * The only package managers `--pm` may select. This value reaches `spawn()`\r\n * as the executable to run and is spliced into the generated\r\n * `package.json`'s scripts — an allow-list here is a hard security\r\n * boundary, not just input hygiene, so it stays a fixed literal list\r\n * rather than anything derived from user input or the running environment.\r\n */\r\nexport const ALLOWED_PACKAGE_MANAGERS = [\"npm\", \"yarn\", \"pnpm\", \"bun\"] as const;\r\n\r\nexport type AllowedPackageManager = (typeof ALLOWED_PACKAGE_MANAGERS)[number];\r\n\r\n/** Whether `value` is one of the allow-listed package managers. */\r\nexport function isValidPackageManager(\r\n  value: string,\r\n): value is AllowedPackageManager {\r\n  return (ALLOWED_PACKAGE_MANAGERS as readonly string[]).includes(value);\r\n}\r\n\r\nexport function getPackageManager() {\r\n  if (detectedPackageManager) {\r\n    return detectedPackageManager;\r\n  }\r\n\r\n  return getPreferredPackageManager();\r\n}\r\n\r\n/**\r\n * Check if a package manager is installed\r\n */\r\nfunction isInstalled(manager: string): boolean {\r\n  try {\r\n    execSync(`${manager} --version`, { stdio: \"ignore\" });\r\n    return true;\r\n  } catch {\r\n    return false;\r\n  }\r\n}\r\n\r\n/**\r\n * Check if a package manager is installed (async)\r\n */\r\nasync function checkManager(manager: string): Promise<boolean> {\r\n  try {\r\n    await execAsync(`${manager} --version`);\r\n    return true;\r\n  } catch {\r\n    return false;\r\n  }\r\n}\r\n\r\n/**\r\n * Detect available package managers asynchronously and cache results\r\n */\r\nexport async function detectPackageManagers() {\r\n  const managers = [\"npm\"];\r\n  const checks = [checkManager(\"yarn\"), checkManager(\"pnpm\")];\r\n\r\n  const [hasYarn, hasPnpm] = await Promise.all(checks);\r\n\r\n  if (hasYarn) managers.push(\"yarn\");\r\n  if (hasPnpm) managers.push(\"pnpm\");\r\n\r\n  cachedSystemManagers = managers;\r\n\r\n  // Determine preference\r\n  const runningPm = detectPackageManager()?.name;\r\n  if (runningPm && runningPm !== \"npm\") {\r\n    cachedPreferredManager = runningPm;\r\n  } else if (hasYarn) {\r\n    cachedPreferredManager = \"yarn\";\r\n  } else if (hasPnpm) {\r\n    cachedPreferredManager = \"pnpm\";\r\n  } else {\r\n    cachedPreferredManager = \"npm\";\r\n  }\r\n}\r\n\r\n/**\r\n * Get available package managers on the system\r\n */\r\nexport function getSystemPackageManagers(): string[] {\r\n  if (cachedSystemManagers) return cachedSystemManagers;\r\n\r\n  const managers = [\"npm\"]; // npm is assumed to be always available\r\n\r\n  if (isInstalled(\"yarn\")) {\r\n    managers.push(\"yarn\");\r\n  }\r\n\r\n  if (isInstalled(\"pnpm\")) {\r\n    managers.push(\"pnpm\");\r\n  }\r\n\r\n  return managers;\r\n}\r\n\r\n/**\r\n * Get the preferred package manager based on priority\r\n */\r\nexport function getPreferredPackageManager(): string {\r\n  if (cachedPreferredManager) return cachedPreferredManager;\r\n\r\n  // Priority 1: The manager currently running the script\r\n  const runningPm = detectPackageManager()?.name;\r\n  if (runningPm && runningPm !== \"npm\") return runningPm;\r\n\r\n  // Priority 2: pnpm (if installed) — the framework's own package manager, so a\r\n  // scaffolded app defaults to the same tooling Warlock itself is developed with.\r\n  if (isInstalled(\"pnpm\")) return \"pnpm\";\r\n\r\n  // Priority 3: Yarn (if installed)\r\n  if (isInstalled(\"yarn\")) return \"yarn\";\r\n\r\n  // Priority 4: npm (default)\r\n  return \"npm\";\r\n}\r\n\r\nexport function setPackageManager(packageManager: string) {\r\n  detectedPackageManager = packageManager;\r\n}\r\n\r\nexport function installCommand() {\r\n  return `${getPackageManager()} install`;\r\n}\r\n\r\nexport function startCommand() {\r\n  if (getPackageManager() === \"npm\") return \"npm run dev\";\r\n\r\n  return `${getPackageManager()} dev`;\r\n}\r\n\r\nexport function runPackageManagerCommand(command: string) {\r\n  const packageManager = getPackageManager();\r\n\r\n  if (packageManager === \"npm\") return `npm run ${command}`;\r\n\r\n  return `${packageManager} ${command}`;\r\n}\r\n"],"mappings":";;;;;AAIA,MAAM,YAAY,UAAU,IAAI;AAEhC,IAAI;AACJ,IAAI;AACJ,IAAI;;;;;;;;AASJ,MAAa,2BAA2B;CAAC;CAAO;CAAQ;CAAQ;AAAK;;AAKrE,SAAgB,sBACd,OACgC;CAChC,OAAQ,yBAA+C,SAAS,KAAK;AACvE;AAEA,SAAgB,oBAAoB;CAClC,IAAI,wBACF,OAAO;CAGT,OAAO,2BAA2B;AACpC;;;;AAKA,SAAS,YAAY,SAA0B;CAC7C,IAAI;EACF,SAAS,GAAG,QAAQ,aAAa,EAAE,OAAO,SAAS,CAAC;EACpD,OAAO;CACT,QAAQ;EACN,OAAO;CACT;AACF;;;;AAKA,eAAe,aAAa,SAAmC;CAC7D,IAAI;EACF,MAAM,UAAU,GAAG,QAAQ,WAAW;EACtC,OAAO;CACT,QAAQ;EACN,OAAO;CACT;AACF;;;;AAKA,eAAsB,wBAAwB;CAC5C,MAAM,WAAW,CAAC,KAAK;CACvB,MAAM,SAAS,CAAC,aAAa,MAAM,GAAG,aAAa,MAAM,CAAC;CAE1D,MAAM,CAAC,SAAS,WAAW,MAAM,QAAQ,IAAI,MAAM;CAEnD,IAAI,SAAS,SAAS,KAAK,MAAM;CACjC,IAAI,SAAS,SAAS,KAAK,MAAM;CAEjC,uBAAuB;CAGvB,MAAM,YAAY,qBAAqB,GAAG;CAC1C,IAAI,aAAa,cAAc,OAC7B,yBAAyB;MACpB,IAAI,SACT,yBAAyB;MACpB,IAAI,SACT,yBAAyB;MAEzB,yBAAyB;AAE7B;;;;AAKA,SAAgB,2BAAqC;CACnD,IAAI,sBAAsB,OAAO;CAEjC,MAAM,WAAW,CAAC,KAAK;CAEvB,IAAI,YAAY,MAAM,GACpB,SAAS,KAAK,MAAM;CAGtB,IAAI,YAAY,MAAM,GACpB,SAAS,KAAK,MAAM;CAGtB,OAAO;AACT;;;;AAKA,SAAgB,6BAAqC;CACnD,IAAI,wBAAwB,OAAO;CAGnC,MAAM,YAAY,qBAAqB,GAAG;CAC1C,IAAI,aAAa,cAAc,OAAO,OAAO;CAI7C,IAAI,YAAY,MAAM,GAAG,OAAO;CAGhC,IAAI,YAAY,MAAM,GAAG,OAAO;CAGhC,OAAO;AACT;AAEA,SAAgB,kBAAkB,gBAAwB;CACxD,yBAAyB;AAC3B;AAYA,SAAgB,yBAAyB,SAAiB;CACxD,MAAM,iBAAiB,kBAAkB;CAEzC,IAAI,mBAAmB,OAAO,OAAO,WAAW;CAEhD,OAAO,GAAG,eAAe,GAAG;AAC9B"}

package/esm/helpers/project-builder-helpers.mjs

@@ -1,9 +1,9 @@
 import { executeCommand } from "./exec.mjs";
 import "./package-manager.mjs";
 import "./paths.mjs";
+import { copyDirectory, getFile, getJsonFile, putFile, putJsonFile, renameFile } from "@warlock.js/fs";
 import "@clack/prompts";
 import { colors } from "@mongez/copper";
-import { copyDirectory, getFile, getJsonFile, putFile, putJsonFile, renameFile } from "@warlock.js/fs";
 import path from "path";
 
 //#region ../create-warlock/src/helpers/project-builder-helpers.ts

package/esm/helpers/warlock-versions.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"warlock-versions.mjs","names":[],"sources":["../../../../../../create-warlock/src/helpers/warlock-versions.ts"],"sourcesContent":["/**\n * Resolving the version to stamp onto the generated project's `@warlock.js/*`\n * dependencies.\n *\n * ## Why this file exists\n *\n * The scaffolder used to stamp its OWN version onto every sibling package\n * (`\"@warlock.js/core\": \"4.16.2\"`). That is only correct while the scaffolder's\n * version is published — and it usually is not: the release tooling bumps the\n * source version on every build, including `--no-publish` builds, so between\n * publishes the working tree carries a version that exists nowhere on the\n * registry. Every project scaffolded in that window pinned eight dependencies\n * to a version npm cannot resolve, and the install died with `ETARGET`.\n *\n * ## The rule\n *\n * Never write a dependency version we have not established exists. Resolution\n * order, per package:\n *\n *   1. the scaffolder's own version, IF the registry has it published — this\n *      preserves the lockstep guarantee the pin was introduced for;\n *   2. otherwise the registry's `latest` — the newest thing that actually\n *      exists, with a note explaining the substitution;\n *   3. otherwise (registry unreachable) a caret range floored to the major,\n *      e.g. `^4.0.0` — always satisfiable by any published 4.x, and the\n *      scaffold-time install writes a lockfile that freezes the result anyway.\n *\n * A package that resolves to nothing (404 — never published) is reported, not\n * papered over: it is the difference between \"your install failed\" and \"the\n * feature you asked for does not exist yet\".\n */\n\nimport { getJsonFile } from \"@warlock.js/fs\";\nimport { packageRoot, template } from \"./paths\";\n\nexport type VersionSource =\n  \"own-version\" | \"registry-latest\" | \"range-fallback\";\n\nexport type ResolvedVersion = {\n  package: string;\n  /** The exact version or range to write into the generated package.json. */\n  version: string;\n  source: VersionSource;\n};\n\nexport type VersionResolution = {\n  /** package name -> version/range to stamp. */\n  versions: Record<string, string>;\n  /** Human-readable notes worth showing before the install runs. */\n  notes: string[];\n  /** Packages the registry does not know about at all. */\n  unpublished: string[];\n  /** True when the registry could not be reached and ranges were guessed. */\n  offline: boolean;\n};\n\nconst REGISTRY_TIMEOUT_MS = 6_000;\n\n/**\n * Registry to query. `npm_config_registry` is set by npm/npx when the\n * scaffolder runs through them, so a private mirror is honoured for free.\n */\nfunction registryUrl(): string {\n  const registry =\n    process.env.npm_config_registry?.trim() || \"https://registry.npmjs.org\";\n\n  return registry.replace(/\\/+$/, \"\");\n}\n\n/** `4.16.2` -> `^4.0.0`; anything unparseable -> `latest`. */\nexport function fallbackRange(version: string): string {\n  const major = /^\\s*v?(\\d+)\\./.exec(version)?.[1];\n\n  return major ? `^${major}.0.0` : \"latest\";\n}\n\ntype Packument = {\n  \"dist-tags\"?: Record<string, string>;\n  versions?: Record<string, unknown>;\n};\n\n/**\n * Fetch the abbreviated packument for a package. Returns `undefined` when the\n * registry cannot be reached (network / timeout) and `null` when the registry\n * answers that the package does not exist.\n */\nasync function fetchPackument(\n  packageName: string,\n): Promise<Packument | null | undefined> {\n  const url = `${registryUrl()}/${packageName.replace(\"/\", \"%2F\")}`;\n\n  try {\n    const response = await fetch(url, {\n      headers: { accept: \"application/vnd.npm.install-v1+json\" },\n      signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS),\n    });\n\n    // 404 (public) and 401 (scoped package the registry hides) both mean the\n    // same thing to us: there is nothing here to install.\n    if (response.status === 404 || response.status === 401) return null;\n\n    if (!response.ok) return undefined;\n\n    return (await response.json()) as Packument;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Resolve one package against the registry. Pure aside from the fetch, so the\n * decision table above is readable in one place.\n */\nasync function resolvePackage(\n  packageName: string,\n  ownVersion: string,\n): Promise<ResolvedVersion & { published: boolean; reachable: boolean }> {\n  const packument = await fetchPackument(packageName);\n\n  if (packument === undefined) {\n    return {\n      package: packageName,\n      version: fallbackRange(ownVersion),\n      source: \"range-fallback\",\n      published: true,\n      reachable: false,\n    };\n  }\n\n  if (packument === null) {\n    return {\n      package: packageName,\n      version: fallbackRange(ownVersion),\n      source: \"range-fallback\",\n      published: false,\n      reachable: true,\n    };\n  }\n\n  if (packument.versions?.[ownVersion]) {\n    return {\n      package: packageName,\n      version: ownVersion,\n      source: \"own-version\",\n      published: true,\n      reachable: true,\n    };\n  }\n\n  const latest = packument[\"dist-tags\"]?.latest;\n\n  if (latest) {\n    return {\n      package: packageName,\n      version: latest,\n      source: \"registry-latest\",\n      published: true,\n      reachable: true,\n    };\n  }\n\n  return {\n    package: packageName,\n    version: fallbackRange(ownVersion),\n    source: \"range-fallback\",\n    published: true,\n    reachable: true,\n  };\n}\n\n/**\n * Every `@warlock.js/*` dependency the template declares. Read from the\n * template rather than the copied project so resolution can start before (or\n * in parallel with) the copy.\n */\nexport function templateWarlockDependencies(): string[] {\n  const templatePackageJson = getJsonFile(\n    `${template(\"warlock\")}/package.json`,\n  ) as {\n    dependencies?: Record<string, string>;\n    devDependencies?: Record<string, string>;\n  };\n\n  const names = new Set<string>();\n\n  for (const field of [\"dependencies\", \"devDependencies\"] as const) {\n    for (const name of Object.keys(templatePackageJson[field] ?? {})) {\n      if (name.startsWith(\"@warlock.js/\")) names.add(name);\n    }\n  }\n\n  return [...names];\n}\n\n/** The scaffolder's own published version, i.e. the lockstep candidate. */\nexport function scaffolderVersion(): string {\n  return (getJsonFile(packageRoot(\"package.json\")) as { version: string })\n    .version;\n}\n\nlet cached: Promise<VersionResolution> | undefined;\n\n/**\n * Resolve the versions to stamp, once per process.\n *\n * Never throws and never blocks a scaffold: the worst case is the caret\n * fallback plus a note saying so.\n */\nexport function resolveWarlockVersions(\n  packages: string[] = templateWarlockDependencies(),\n  ownVersion: string = scaffolderVersion(),\n): Promise<VersionResolution> {\n  if (cached) return cached;\n\n  cached = (async (): Promise<VersionResolution> => {\n    const resolutions = await Promise.all(\n      packages.map(name => resolvePackage(name, ownVersion)),\n    );\n\n    const versions: Record<string, string> = {};\n    const notes: string[] = [];\n    const unpublished: string[] = [];\n    const substituted: ResolvedVersion[] = [];\n\n    let offline = false;\n\n    for (const resolution of resolutions) {\n      versions[resolution.package] = resolution.version;\n\n      if (!resolution.reachable) offline = true;\n      if (!resolution.published) unpublished.push(resolution.package);\n      if (resolution.source === \"registry-latest\") substituted.push(resolution);\n    }\n\n    if (offline) {\n      notes.push(\n        `Could not reach the npm registry — pinning @warlock.js/* to ${fallbackRange(ownVersion)} instead of an exact version.`,\n      );\n    }\n\n    if (substituted.length > 0) {\n      const latest = substituted[0].version;\n\n      notes.push(\n        `create-warlock ${ownVersion} is not published yet — pinning @warlock.js/* to the latest published version (${latest}).`,\n      );\n    }\n\n    if (unpublished.length > 0) {\n      notes.push(\n        `Not published on the registry: ${unpublished.join(\", \")} — the install will fail until they are released.`,\n      );\n    }\n\n    return { versions, notes, unpublished, offline };\n  })();\n\n  return cached;\n}\n\n/** Test/CLI seam: forget the memoized resolution. */\nexport function resetWarlockVersionsCache() {\n  cached = undefined;\n}\n"],"mappings":"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"}
+{"version":3,"file":"warlock-versions.mjs","names":[],"sources":["../../../../../../create-warlock/src/helpers/warlock-versions.ts"],"sourcesContent":["/**\n * Resolving the version to stamp onto the generated project's `@warlock.js/*`\n * dependencies.\n *\n * ## Why this file exists\n *\n * The scaffolder used to stamp its OWN version onto every sibling package\n * (`\"@warlock.js/core\": \"4.16.2\"`). That is only correct while the scaffolder's\n * version is published — and it usually is not: the release tooling bumps the\n * source version on every build, including `--no-publish` builds, so between\n * publishes the working tree carries a version that exists nowhere on the\n * registry. Every project scaffolded in that window pinned eight dependencies\n * to a version npm cannot resolve, and the install died with `ETARGET`.\n *\n * ## The rule\n *\n * Never write a dependency version we have not established exists. Resolution\n * order, per package:\n *\n *   1. the scaffolder's own version, IF the registry has it published — this\n *      preserves the lockstep guarantee the pin was introduced for;\n *   2. otherwise the registry's `latest` — the newest thing that actually\n *      exists, with a note explaining the substitution;\n *   3. otherwise (registry unreachable) a caret range floored to the major,\n *      e.g. `^4.0.0` — always satisfiable by any published 4.x, and the\n *      scaffold-time install writes a lockfile that freezes the result anyway.\n *\n * A package that resolves to nothing (404 — never published) is reported, not\n * papered over: it is the difference between \"your install failed\" and \"the\n * feature you asked for does not exist yet\".\n */\n\nimport { getJsonFile } from \"@warlock.js/fs\";\nimport { packageRoot, template } from \"./paths\";\n\nexport type VersionSource =\n  \"own-version\" | \"registry-latest\" | \"range-fallback\";\n\nexport type ResolvedVersion = {\n  package: string;\n  /** The exact version or range to write into the generated package.json. */\n  version: string;\n  source: VersionSource;\n};\n\nexport type VersionResolution = {\n  /** package name -> version/range to stamp. */\n  versions: Record<string, string>;\n  /** Human-readable notes worth showing before the install runs. */\n  notes: string[];\n  /** Packages the registry does not know about at all. */\n  unpublished: string[];\n  /** True when the registry could not be reached and ranges were guessed. */\n  offline: boolean;\n};\n\nconst REGISTRY_TIMEOUT_MS = 6_000;\n\n/**\n * Registry to query. `npm_config_registry` is set by npm/npx when the\n * scaffolder runs through them, so a private mirror is honoured for free.\n */\nfunction registryUrl(): string {\n  const registry =\n    process.env.npm_config_registry?.trim() || \"https://registry.npmjs.org\";\n\n  return registry.replace(/\\/+$/, \"\");\n}\n\n/** `4.16.2` -> `^4.0.0`; anything unparseable -> `latest`. */\nexport function fallbackRange(version: string): string {\n  const major = /^\\s*v?(\\d+)\\./.exec(version)?.[1];\n\n  return major ? `^${major}.0.0` : \"latest\";\n}\n\ntype Packument = {\n  \"dist-tags\"?: Record<string, string>;\n  versions?: Record<string, unknown>;\n};\n\n/**\n * Fetch the abbreviated packument for a package. Returns `undefined` when the\n * registry cannot be reached (network / timeout) and `null` when the registry\n * answers that the package does not exist.\n */\nasync function fetchPackument(\n  packageName: string,\n): Promise<Packument | null | undefined> {\n  const url = `${registryUrl()}/${packageName.replace(\"/\", \"%2F\")}`;\n\n  try {\n    const response = await fetch(url, {\n      headers: { accept: \"application/vnd.npm.install-v1+json\" },\n      signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS),\n    });\n\n    // 404 (public) and 401 (scoped package the registry hides) both mean the\n    // same thing to us: there is nothing here to install.\n    if (response.status === 404 || response.status === 401) return null;\n\n    if (!response.ok) return undefined;\n\n    return (await response.json()) as Packument;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Resolve one package against the registry. Pure aside from the fetch, so the\n * decision table above is readable in one place.\n */\nasync function resolvePackage(\n  packageName: string,\n  ownVersion: string,\n): Promise<ResolvedVersion & { published: boolean; reachable: boolean }> {\n  const packument = await fetchPackument(packageName);\n\n  if (packument === undefined) {\n    return {\n      package: packageName,\n      version: fallbackRange(ownVersion),\n      source: \"range-fallback\",\n      published: true,\n      reachable: false,\n    };\n  }\n\n  if (packument === null) {\n    return {\n      package: packageName,\n      version: fallbackRange(ownVersion),\n      source: \"range-fallback\",\n      published: false,\n      reachable: true,\n    };\n  }\n\n  if (packument.versions?.[ownVersion]) {\n    return {\n      package: packageName,\n      version: ownVersion,\n      source: \"own-version\",\n      published: true,\n      reachable: true,\n    };\n  }\n\n  const latest = packument[\"dist-tags\"]?.latest;\n\n  if (latest) {\n    return {\n      package: packageName,\n      version: latest,\n      source: \"registry-latest\",\n      published: true,\n      reachable: true,\n    };\n  }\n\n  return {\n    package: packageName,\n    version: fallbackRange(ownVersion),\n    source: \"range-fallback\",\n    published: true,\n    reachable: true,\n  };\n}\n\n/**\n * Every `@warlock.js/*` dependency the template declares. Read from the\n * template rather than the copied project so resolution can start before (or\n * in parallel with) the copy.\n */\nexport function templateWarlockDependencies(): string[] {\n  const templatePackageJson = getJsonFile(\n    `${template(\"warlock\")}/package.json`,\n  ) as {\n    dependencies?: Record<string, string>;\n    devDependencies?: Record<string, string>;\n  };\n\n  const names = new Set<string>();\n\n  for (const field of [\"dependencies\", \"devDependencies\"] as const) {\n    for (const name of Object.keys(templatePackageJson[field] ?? {})) {\n      if (name.startsWith(\"@warlock.js/\")) names.add(name);\n    }\n  }\n\n  return [...names];\n}\n\n/** The scaffolder's own published version, i.e. the lockstep candidate. */\nexport function scaffolderVersion(): string {\n  return (getJsonFile(packageRoot(\"package.json\")) as { version: string })\n    .version;\n}\n\nlet cached: Promise<VersionResolution> | undefined;\n\n/**\n * Resolve the versions to stamp, once per process.\n *\n * Never throws and never blocks a scaffold: the worst case is the caret\n * fallback plus a note saying so.\n */\nexport function resolveWarlockVersions(\n  packages: string[] = templateWarlockDependencies(),\n  ownVersion: string = scaffolderVersion(),\n): Promise<VersionResolution> {\n  if (cached) return cached;\n\n  cached = (async (): Promise<VersionResolution> => {\n    const resolutions = await Promise.all(\n      packages.map(name => resolvePackage(name, ownVersion)),\n    );\n\n    const versions: Record<string, string> = {};\n    const notes: string[] = [];\n    const unpublished: string[] = [];\n    const substituted: ResolvedVersion[] = [];\n\n    let offline = false;\n\n    for (const resolution of resolutions) {\n      versions[resolution.package] = resolution.version;\n\n      if (!resolution.reachable) offline = true;\n      if (!resolution.published) unpublished.push(resolution.package);\n      if (resolution.source === \"registry-latest\") substituted.push(resolution);\n    }\n\n    if (offline) {\n      notes.push(\n        `Could not reach the npm registry — pinning @warlock.js/* to ${fallbackRange(ownVersion)} instead of an exact version.`,\n      );\n    }\n\n    if (substituted.length > 0) {\n      const latest = substituted[0].version;\n\n      notes.push(\n        `create-warlock ${ownVersion} is not published yet — pinning @warlock.js/* to the latest published version (${latest}).`,\n      );\n    }\n\n    if (unpublished.length > 0) {\n      notes.push(\n        `Not published on the registry: ${unpublished.join(\", \")} — the install will fail until they are released.`,\n      );\n    }\n\n    return { versions, notes, unpublished, offline };\n  })();\n\n  return cached;\n}\n\n/** Test/CLI seam: forget the memoized resolution. */\nexport function resetWarlockVersionsCache() {\n  cached = undefined;\n}\n"],"mappings":"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"}

package/esm/index.d.mts

@@ -8,7 +8,13 @@ import { CliFlags } from "./commands/create-new-app/types.mjs";
  * create-warlock my-app --db=postgres --features=test,herald --ai=openai,anthropic --yes
  */
 declare function parseFlags(argv: string[]): CliFlags;
+/**
+ * Read this package's own `version` field. A plain JSON read — no network
+ * call, no write, nothing else touched — so `--version` stays a pure,
+ * side-effect-free exit.
+ */
+declare function packageVersion(): string;
 declare function createApp(): void;
 //#endregion
-export { createApp as default, parseFlags };
+export { createApp as default, packageVersion, parseFlags };
 //# sourceMappingURL=index.d.mts.map

package/esm/index.mjs

@@ -1,5 +1,7 @@
 import { NO_DATABASE } from "./features/database-drivers.mjs";
+import { packageRoot } from "./helpers/paths.mjs";
 import createNewApp from "./commands/create-new-app/index.mjs";
+import { getJsonFile } from "@warlock.js/fs";
 
 //#region ../create-warlock/src/index.ts
 const valueFlags = [
@@ -9,6 +11,28 @@ const valueFlags = [
 	"features",
 	"ai"
 ];
+const HELP_TEXT = `
+  create-warlock — scaffold a new Warlock.js project
+
+  Usage
+    $ create-warlock [project-name] [options]
+
+  Options
+    --name              Project name (or pass it as the first positional arg)
+    --db=<driver>        Database driver (e.g. postgres, mongodb)
+    --no-db               Skip database selection entirely
+    --features=<list>    Comma-separated feature keys (e.g. test,herald)
+    --ai=<list>           Comma-separated AI provider keys (e.g. openai,anthropic)
+    --pm=<manager>        Package manager to use (npm, yarn, pnpm)
+    --git / --no-git      Force-enable or force-disable git initialization
+    --jwt / --no-jwt      Force-enable or force-disable JWT secret generation
+    -y, --yes             Skip prompts and accept defaults for anything unset
+    -h, --help            Show this help message and exit
+    -v, --version         Show the installed create-warlock version and exit
+
+  Example
+    $ create-warlock my-app --db=postgres --features=test,herald --yes
+`;
 /**
 * Parse the scaffolder's own CLI flags for non-interactive mode.
 *
@@ -35,6 +59,14 @@ function parseFlags(argv) {
 			}
 		}
 		switch (key) {
+			case "help":
+			case "h":
+				flags.help = true;
+				break;
+			case "version":
+			case "v":
+				flags.version = true;
+				break;
 			case "yes":
 			case "y":
 				flags.yes = true;
@@ -78,8 +110,26 @@ function splitList(value) {
 	if (!value) return [];
 	return value.split(",").map((item) => item.trim()).filter(Boolean);
 }
+/**
+* Read this package's own `version` field. A plain JSON read — no network
+* call, no write, nothing else touched — so `--version` stays a pure,
+* side-effect-free exit.
+*/
+function packageVersion() {
+	return getJsonFile(packageRoot("package.json")).version;
+}
 function createApp() {
 	const flags = parseFlags(process.argv.slice(2));
+	if (flags.help) {
+		console.log(HELP_TEXT);
+		process.exit(0);
+		return;
+	}
+	if (flags.version) {
+		console.log(packageVersion());
+		process.exit(0);
+		return;
+	}
 	Promise.resolve(createNewApp(flags)).catch((error) => {
 		console.error();
 		console.error(`  create-warlock failed: ${error?.message ?? String(error)}`);
@@ -89,5 +139,5 @@ function createApp() {
 }
 
 //#endregion
-export { createApp as default, parseFlags };
+export { createApp as default, packageVersion, parseFlags };
 //# sourceMappingURL=index.mjs.map

package/esm/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../../../../create-warlock/src/index.ts"],"sourcesContent":["import createNewApp from \"./commands/create-new-app\";\nimport { CliFlags } from \"./commands/create-new-app/types\";\nimport { NO_DATABASE } from \"./features/database-drivers\";\n\nconst valueFlags = [\"name\", \"db\", \"pm\", \"features\", \"ai\"];\n\n/**\n * Parse the scaffolder's own CLI flags for non-interactive mode.\n *\n * @example\n * create-warlock my-app --db=postgres --features=test,herald --ai=openai,anthropic --yes\n */\nexport function parseFlags(argv: string[]): CliFlags {\n  const flags: CliFlags = {};\n  const positionals: string[] = [];\n\n  for (let i = 0; i < argv.length; i++) {\n    const arg = argv[i];\n\n    if (!arg.startsWith(\"-\")) {\n      positionals.push(arg);\n      continue;\n    }\n\n    const equalIndex = arg.indexOf(\"=\");\n    const key = (equalIndex === -1 ? arg : arg.slice(0, equalIndex)).replace(/^-+/, \"\");\n    let value: string | undefined = equalIndex === -1 ? undefined : arg.slice(equalIndex + 1);\n\n    // Value-taking flags may use either `--key=value` or `--key value`.\n    if (valueFlags.includes(key) && value === undefined) {\n      const next = argv[i + 1];\n\n      if (next && !next.startsWith(\"-\")) {\n        value = next;\n        i++;\n      }\n    }\n\n    switch (key) {\n      case \"yes\":\n      case \"y\":\n        flags.yes = true;\n        break;\n      case \"git\":\n        flags.git = true;\n        break;\n      case \"no-git\":\n        flags.git = false;\n        break;\n      case \"jwt\":\n        flags.jwt = true;\n        break;\n      case \"no-jwt\":\n        flags.jwt = false;\n        break;\n      case \"name\":\n        flags.name = value;\n        break;\n      case \"db\":\n        flags.db = value;\n        break;\n      case \"no-db\":\n        // Opt out of a database entirely — equivalent to `--db=none`.\n        flags.db = NO_DATABASE;\n        break;\n      case \"pm\":\n        flags.pm = value;\n        break;\n      case \"features\":\n        flags.features = splitList(value);\n        break;\n      case \"ai\":\n        flags.ai = splitList(value);\n        break;\n    }\n  }\n\n  if (!flags.name && positionals.length > 0) {\n    flags.name = positionals[0];\n  }\n\n  return flags;\n}\n\nfunction splitList(value: string | undefined): string[] {\n  if (!value) return [];\n\n  return value\n    .split(\",\")\n    .map(item => item.trim())\n    .filter(Boolean);\n}\n\nexport default function createApp() {\n  const flags = parseFlags(process.argv.slice(2));\n\n  // An unexpected throw must surface as a readable error AND a non-zero exit\n  // code — never as a stack trace the user scrolls past on the way to a green\n  // banner (there is no banner after this point).\n  Promise.resolve(createNewApp(flags)).catch((error: unknown) => {\n    console.error();\n    console.error(\n      `  create-warlock failed: ${(error as Error)?.message ?? String(error)}`,\n    );\n    console.error();\n\n    process.exit(1);\n  });\n}\n"],"mappings":";;;;AAIA,MAAM,aAAa;CAAC;CAAQ;CAAM;CAAM;CAAY;AAAI;;;;;;;AAQxD,SAAgB,WAAW,MAA0B;CACnD,MAAM,QAAkB,CAAC;CACzB,MAAM,cAAwB,CAAC;CAE/B,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;EACpC,MAAM,MAAM,KAAK;EAEjB,IAAI,CAAC,IAAI,WAAW,GAAG,GAAG;GACxB,YAAY,KAAK,GAAG;GACpB;EACF;EAEA,MAAM,aAAa,IAAI,QAAQ,GAAG;EAClC,MAAM,OAAO,eAAe,KAAK,MAAM,IAAI,MAAM,GAAG,UAAU,EAAC,CAAE,QAAQ,OAAO,EAAE;EAClF,IAAI,QAA4B,eAAe,KAAK,SAAY,IAAI,MAAM,aAAa,CAAC;EAGxF,IAAI,WAAW,SAAS,GAAG,KAAK,UAAU,QAAW;GACnD,MAAM,OAAO,KAAK,IAAI;GAEtB,IAAI,QAAQ,CAAC,KAAK,WAAW,GAAG,GAAG;IACjC,QAAQ;IACR;GACF;EACF;EAEA,QAAQ,KAAR;GACE,KAAK;GACL,KAAK;IACH,MAAM,MAAM;IACZ;GACF,KAAK;IACH,MAAM,MAAM;IACZ;GACF,KAAK;IACH,MAAM,MAAM;IACZ;GACF,KAAK;IACH,MAAM,MAAM;IACZ;GACF,KAAK;IACH,MAAM,MAAM;IACZ;GACF,KAAK;IACH,MAAM,OAAO;IACb;GACF,KAAK;IACH,MAAM,KAAK;IACX;GACF,KAAK;IAEH,MAAM,KAAK;IACX;GACF,KAAK;IACH,MAAM,KAAK;IACX;GACF,KAAK;IACH,MAAM,WAAW,UAAU,KAAK;IAChC;GACF,KAAK;IACH,MAAM,KAAK,UAAU,KAAK;IAC1B;EACJ;CACF;CAEA,IAAI,CAAC,MAAM,QAAQ,YAAY,SAAS,GACtC,MAAM,OAAO,YAAY;CAG3B,OAAO;AACT;AAEA,SAAS,UAAU,OAAqC;CACtD,IAAI,CAAC,OAAO,OAAO,CAAC;CAEpB,OAAO,MACJ,MAAM,GAAG,CAAC,CACV,KAAI,SAAQ,KAAK,KAAK,CAAC,CAAC,CACxB,OAAO,OAAO;AACnB;AAEA,SAAwB,YAAY;CAClC,MAAM,QAAQ,WAAW,QAAQ,KAAK,MAAM,CAAC,CAAC;CAK9C,QAAQ,QAAQ,aAAa,KAAK,CAAC,CAAC,CAAC,OAAO,UAAmB;EAC7D,QAAQ,MAAM;EACd,QAAQ,MACN,4BAA6B,OAAiB,WAAW,OAAO,KAAK,GACvE;EACA,QAAQ,MAAM;EAEd,QAAQ,KAAK,CAAC;CAChB,CAAC;AACH"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../../create-warlock/src/index.ts"],"sourcesContent":["import { getJsonFile } from \"@warlock.js/fs\";\nimport createNewApp from \"./commands/create-new-app\";\nimport { CliFlags } from \"./commands/create-new-app/types\";\nimport { NO_DATABASE } from \"./features/database-drivers\";\nimport { packageRoot } from \"./helpers/paths\";\n\nconst valueFlags = [\"name\", \"db\", \"pm\", \"features\", \"ai\"];\n\nconst HELP_TEXT = `\n  create-warlock — scaffold a new Warlock.js project\n\n  Usage\n    $ create-warlock [project-name] [options]\n\n  Options\n    --name              Project name (or pass it as the first positional arg)\n    --db=<driver>        Database driver (e.g. postgres, mongodb)\n    --no-db               Skip database selection entirely\n    --features=<list>    Comma-separated feature keys (e.g. test,herald)\n    --ai=<list>           Comma-separated AI provider keys (e.g. openai,anthropic)\n    --pm=<manager>        Package manager to use (npm, yarn, pnpm)\n    --git / --no-git      Force-enable or force-disable git initialization\n    --jwt / --no-jwt      Force-enable or force-disable JWT secret generation\n    -y, --yes             Skip prompts and accept defaults for anything unset\n    -h, --help            Show this help message and exit\n    -v, --version         Show the installed create-warlock version and exit\n\n  Example\n    $ create-warlock my-app --db=postgres --features=test,herald --yes\n`;\n\n/**\n * Parse the scaffolder's own CLI flags for non-interactive mode.\n *\n * @example\n * create-warlock my-app --db=postgres --features=test,herald --ai=openai,anthropic --yes\n */\nexport function parseFlags(argv: string[]): CliFlags {\n  const flags: CliFlags = {};\n  const positionals: string[] = [];\n\n  for (let i = 0; i < argv.length; i++) {\n    const arg = argv[i];\n\n    if (!arg.startsWith(\"-\")) {\n      positionals.push(arg);\n      continue;\n    }\n\n    const equalIndex = arg.indexOf(\"=\");\n    const key = (equalIndex === -1 ? arg : arg.slice(0, equalIndex)).replace(/^-+/, \"\");\n    let value: string | undefined = equalIndex === -1 ? undefined : arg.slice(equalIndex + 1);\n\n    // Value-taking flags may use either `--key=value` or `--key value`.\n    if (valueFlags.includes(key) && value === undefined) {\n      const next = argv[i + 1];\n\n      if (next && !next.startsWith(\"-\")) {\n        value = next;\n        i++;\n      }\n    }\n\n    switch (key) {\n      case \"help\":\n      case \"h\":\n        flags.help = true;\n        break;\n      case \"version\":\n      case \"v\":\n        flags.version = true;\n        break;\n      case \"yes\":\n      case \"y\":\n        flags.yes = true;\n        break;\n      case \"git\":\n        flags.git = true;\n        break;\n      case \"no-git\":\n        flags.git = false;\n        break;\n      case \"jwt\":\n        flags.jwt = true;\n        break;\n      case \"no-jwt\":\n        flags.jwt = false;\n        break;\n      case \"name\":\n        flags.name = value;\n        break;\n      case \"db\":\n        flags.db = value;\n        break;\n      case \"no-db\":\n        // Opt out of a database entirely — equivalent to `--db=none`.\n        flags.db = NO_DATABASE;\n        break;\n      case \"pm\":\n        flags.pm = value;\n        break;\n      case \"features\":\n        flags.features = splitList(value);\n        break;\n      case \"ai\":\n        flags.ai = splitList(value);\n        break;\n    }\n  }\n\n  if (!flags.name && positionals.length > 0) {\n    flags.name = positionals[0];\n  }\n\n  return flags;\n}\n\nfunction splitList(value: string | undefined): string[] {\n  if (!value) return [];\n\n  return value\n    .split(\",\")\n    .map(item => item.trim())\n    .filter(Boolean);\n}\n\n/**\n * Read this package's own `version` field. A plain JSON read — no network\n * call, no write, nothing else touched — so `--version` stays a pure,\n * side-effect-free exit.\n */\nexport function packageVersion(): string {\n  return (getJsonFile(packageRoot(\"package.json\")) as { version: string })\n    .version;\n}\n\nexport default function createApp() {\n  const flags = parseFlags(process.argv.slice(2));\n\n  // `--help` and `--version` must exit before anything that touches the\n  // filesystem, the network, or a prompt — they win over every other flag,\n  // including a positional project name.\n  if (flags.help) {\n    console.log(HELP_TEXT);\n    process.exit(0);\n    return;\n  }\n\n  if (flags.version) {\n    console.log(packageVersion());\n    process.exit(0);\n    return;\n  }\n\n  // An unexpected throw must surface as a readable error AND a non-zero exit\n  // code — never as a stack trace the user scrolls past on the way to a green\n  // banner (there is no banner after this point).\n  Promise.resolve(createNewApp(flags)).catch((error: unknown) => {\n    console.error();\n    console.error(\n      `  create-warlock failed: ${(error as Error)?.message ?? String(error)}`,\n    );\n    console.error();\n\n    process.exit(1);\n  });\n}\n"],"mappings":";;;;;;AAMA,MAAM,aAAa;CAAC;CAAQ;CAAM;CAAM;CAAY;AAAI;AAExD,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BlB,SAAgB,WAAW,MAA0B;CACnD,MAAM,QAAkB,CAAC;CACzB,MAAM,cAAwB,CAAC;CAE/B,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;EACpC,MAAM,MAAM,KAAK;EAEjB,IAAI,CAAC,IAAI,WAAW,GAAG,GAAG;GACxB,YAAY,KAAK,GAAG;GACpB;EACF;EAEA,MAAM,aAAa,IAAI,QAAQ,GAAG;EAClC,MAAM,OAAO,eAAe,KAAK,MAAM,IAAI,MAAM,GAAG,UAAU,GAAG,QAAQ,OAAO,EAAE;EAClF,IAAI,QAA4B,eAAe,KAAK,SAAY,IAAI,MAAM,aAAa,CAAC;EAGxF,IAAI,WAAW,SAAS,GAAG,KAAK,UAAU,QAAW;GACnD,MAAM,OAAO,KAAK,IAAI;GAEtB,IAAI,QAAQ,CAAC,KAAK,WAAW,GAAG,GAAG;IACjC,QAAQ;IACR;GACF;EACF;EAEA,QAAQ,KAAR;GACE,KAAK;GACL,KAAK;IACH,MAAM,OAAO;IACb;GACF,KAAK;GACL,KAAK;IACH,MAAM,UAAU;IAChB;GACF,KAAK;GACL,KAAK;IACH,MAAM,MAAM;IACZ;GACF,KAAK;IACH,MAAM,MAAM;IACZ;GACF,KAAK;IACH,MAAM,MAAM;IACZ;GACF,KAAK;IACH,MAAM,MAAM;IACZ;GACF,KAAK;IACH,MAAM,MAAM;IACZ;GACF,KAAK;IACH,MAAM,OAAO;IACb;GACF,KAAK;IACH,MAAM,KAAK;IACX;GACF,KAAK;IAEH,MAAM,KAAK;IACX;GACF,KAAK;IACH,MAAM,KAAK;IACX;GACF,KAAK;IACH,MAAM,WAAW,UAAU,KAAK;IAChC;GACF,KAAK;IACH,MAAM,KAAK,UAAU,KAAK;IAC1B;EACJ;CACF;CAEA,IAAI,CAAC,MAAM,QAAQ,YAAY,SAAS,GACtC,MAAM,OAAO,YAAY;CAG3B,OAAO;AACT;AAEA,SAAS,UAAU,OAAqC;CACtD,IAAI,CAAC,OAAO,OAAO,CAAC;CAEpB,OAAO,MACJ,MAAM,GAAG,EACT,KAAI,SAAQ,KAAK,KAAK,CAAC,EACvB,OAAO,OAAO;AACnB;;;;;;AAOA,SAAgB,iBAAyB;CACvC,OAAQ,YAAY,YAAY,cAAc,CAAC,EAC5C;AACL;AAEA,SAAwB,YAAY;CAClC,MAAM,QAAQ,WAAW,QAAQ,KAAK,MAAM,CAAC,CAAC;CAK9C,IAAI,MAAM,MAAM;EACd,QAAQ,IAAI,SAAS;EACrB,QAAQ,KAAK,CAAC;EACd;CACF;CAEA,IAAI,MAAM,SAAS;EACjB,QAAQ,IAAI,eAAe,CAAC;EAC5B,QAAQ,KAAK,CAAC;EACd;CACF;CAKA,QAAQ,QAAQ,aAAa,KAAK,CAAC,EAAE,OAAO,UAAmB;EAC7D,QAAQ,MAAM;EACd,QAAQ,MACN,4BAA6B,OAAiB,WAAW,OAAO,KAAK,GACvE;EACA,QAAQ,MAAM;EAEd,QAAQ,KAAK,CAAC;CAChB,CAAC;AACH"}

package/llms-full.txt

@@ -61,6 +61,8 @@ Pass `--yes` (or `-y`) to skip every prompt and build from flags with defaults.
 
 Value flags accept either `--db=postgres` or `--db postgres`. Unknown `--features` / `--ai` keys fail fast before any install.
 
+`--help`/`-h` and `--version`/`-v` short-circuit before anything else — no prompt, filesystem write, or network call, and `--help` wins even over a positional project name. `--version` prints the installed `create-warlock` version.
+
 ## Valid keys
 
 **Database drivers** (`--db`):
@@ -72,7 +74,7 @@ Value flags accept either `--db=postgres` or `--db postgres`. Unknown `--feature
 | `mysql`    | 3306         | coming soon (disabled in the wizard) |
 | `none`     | —            | opt out — no driver, no driver package, `src/config/database.ts` removed |
 
-**Features** (`--features`): `react`, `react-email`, `mail`, `ses`, `image`, `s3`, `redis`, `scheduler`, `herald`, `socket`, `swagger`, `postman`, `test`.
+**Features** (`--features`): `react`, `react-email`, `mail`, `ses`, `image`, `s3`, `redis`, `scheduler`, `herald`, `socket`, `test`, `access`, `web`, `tailwind`, `shadcn`, `notifications`.
 
 **AI providers / packages** (`--ai`): `ai-openai`, `ai-google`, `ai-anthropic`, `ai-bedrock`, `ai-ollama`, plus the capability packages `ai-tools`, `ai-panoptic`, `ai-workspace`. Any pick auto-pulls the core `@warlock.js/ai` package.
 

package/package.json

@@ -12,13 +12,13 @@
   "dependencies": {
     "@clack/prompts": "^0.7.0",
     "@mongez/copper": "^2.1.2",
-    "@warlock.js/fs": "5.0.2",
+    "@warlock.js/fs": "5.2.2",
     "@mongez/reinforcements": "^4.0.1",
     "cross-spawn": "^7.0.3",
     "rimraf": "^6.0.1",
     "which-pm-runs": "^1.1.0"
   },
-  "version": "5.0.2",
+  "version": "5.2.2",
   "type": "module",
   "main": "./esm/index.mjs",
   "module": "./esm/index.mjs",

package/skills/create-a-warlock-project/SKILL.md

@@ -11,7 +11,7 @@ description: 'Scaffold a brand-new Warlock.js project with `create-warlock` —
 
 ```bash
 # Interactive wizard (recommended for humans)
-yarn create warlock
+pnpm create warlock
 # or: npm create warlock@latest / pnpm create warlock / npx create-warlock
 
 # Non-interactive (CI, agents, reproducible setups) — one command scaffolds the whole app
@@ -53,6 +53,8 @@ Pass `--yes` (or `-y`) to skip every prompt and build from flags with defaults.
 
 Value flags accept either `--db=postgres` or `--db postgres`. Unknown `--features` / `--ai` keys fail fast before any install.
 
+`--help`/`-h` and `--version`/`-v` short-circuit before anything else — no prompt, filesystem write, or network call, and `--help` wins even over a positional project name. `--version` prints the installed `create-warlock` version.
+
 ## Valid keys
 
 **Database drivers** (`--db`):
@@ -64,7 +66,7 @@ Value flags accept either `--db=postgres` or `--db postgres`. Unknown `--feature
 | `mysql`    | 3306         | coming soon (disabled in the wizard) |
 | `none`     | —            | opt out — no driver, no driver package, `src/config/database.ts` removed |
 
-**Features** (`--features`): `react`, `react-email`, `mail`, `ses`, `image`, `s3`, `redis`, `scheduler`, `herald`, `socket`, `swagger`, `postman`, `test`.
+**Features** (`--features`): `react`, `react-email`, `mail`, `ses`, `image`, `s3`, `redis`, `scheduler`, `herald`, `socket`, `test`, `access`, `web`, `tailwind`, `shadcn`, `notifications`.
 
 **AI providers / packages** (`--ai`): `ai-openai`, `ai-google`, `ai-anthropic`, `ai-bedrock`, `ai-ollama`, plus the capability packages `ai-tools`, `ai-panoptic`, `ai-workspace`. Any pick auto-pulls the core `@warlock.js/ai` package.
 

package/templates/warlock/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "wow2",
+  "name": "name-set-by-scaffolder",
   "version": "1.0.0",
   "private": true,
   "type": "module",
@@ -35,14 +35,14 @@
     "@mongez/reinforcements": "^4.0.1",
     "@mongez/localization": "^3.4.7",
     "@mongez/supportive-is": "^2.1.4",
-    "@warlock.js/auth": "4.15.0",
-    "@warlock.js/cache": "4.15.0",
-    "@warlock.js/cascade": "4.15.0",
-    "@warlock.js/scheduler": "4.15.0",
-    "@warlock.js/core": "4.15.0",
-    "@warlock.js/fs": "4.15.0",
-    "@warlock.js/logger": "4.15.0",
-    "@warlock.js/seal": "4.15.0",
+    "@warlock.js/auth": "0.0.0-set-by-scaffolder",
+    "@warlock.js/cache": "0.0.0-set-by-scaffolder",
+    "@warlock.js/cascade": "0.0.0-set-by-scaffolder",
+    "@warlock.js/scheduler": "0.0.0-set-by-scaffolder",
+    "@warlock.js/core": "0.0.0-set-by-scaffolder",
+    "@warlock.js/fs": "0.0.0-set-by-scaffolder",
+    "@warlock.js/logger": "0.0.0-set-by-scaffolder",
+    "@warlock.js/seal": "0.0.0-set-by-scaffolder",
     "dayjs": "^1.11.19"
   },
   "devDependencies": {

package/templates/warlock/src/app/auth/controllers/logout-all.controller.ts

@@ -1,11 +1,14 @@
-import { t, type RequestHandler } from "@warlock.js/core";
+import { t } from "@warlock.js/core";
+import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
 import { logoutAllService } from "../services/auth.service";
 
 /**
  * Logout from all devices controller
  * POST /auth/logout-all
+ *
+ * Guarded route — see the note on `logoutController`.
  */
-export const logoutAllController: RequestHandler = async ({ request, response }) => {
+export const logoutAllController: GuardedRequestHandler = async ({ request, response }) => {
   await logoutAllService(request.user);
 
   return response.success({

package/templates/warlock/src/app/auth/controllers/logout.controller.ts

@@ -1,11 +1,16 @@
-import { t, type RequestHandler } from "@warlock.js/core";
+import { t } from "@warlock.js/core";
+import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
 import { logoutService } from "../services/auth.service";
 
 /**
  * Logout controller
  * POST /auth/logout
+ *
+ * Typed as `GuardedRequestHandler` because the route sits inside `guarded()`
+ * (see `../routes.ts`). A plain `RequestHandler` types `request.user` as
+ * `RequestUser | undefined`, which is not assignable to `logoutService`.
  */
-export const logoutController: RequestHandler = async ({ request, response }) => {
+export const logoutController: GuardedRequestHandler = async ({ request, response }) => {
   await logoutService(request.user);
 
   return response.success({

package/templates/warlock/src/app/auth/controllers/me.controller.ts

@@ -1,10 +1,15 @@
-import { type RequestHandler } from "@warlock.js/core";
+import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
 
 /**
  * Get current user controller
  * GET /auth/me
+ *
+ * Guarded route. As a plain `RequestHandler` this compiled without complaint
+ * while serializing `RequestUser | undefined` — i.e. the empty interface `{}` —
+ * so the response body was typed as nothing at all and no error was raised.
+ * `GuardedRequestHandler` types it as the app's `User` model.
  */
-export const meController: RequestHandler = async ({ request, response }) => {
+export const meController: GuardedRequestHandler = async ({ request, response }) => {
   return response.success({
     user: request.user,
   });

package/templates/warlock/src/app/auth/main.ts

@@ -7,3 +7,13 @@ scheduler.newJob("cleanup-expired-otps", cleanupExpiredOtpsService).everyHour();
 
 // Cleanup expired refresh tokens every hour
 scheduler.newJob("cleanup-expired-tokens", () => authService.cleanupExpiredTokens()).everyHour();
+
+// Registering jobs does not schedule them — without this, a fresh project's very
+// first `warlock dev` printed "scheduler.start() was never called" and neither
+// cleanup ever ran.
+//
+// Safe to call here: `start()` throws on an empty scheduler, and the two jobs
+// above are registered directly before it. Jobs registered later by other
+// modules still run — `addJob` prepares them when the scheduler is already
+// running.
+scheduler.start();

package/templates/warlock/src/app/shared/controllers/home-page.controller.tsx

@@ -1,6 +1,15 @@
 import { type RequestHandler } from "@warlock.js/core";
 import { HomePageComponent } from "../components/HomePageComponent";
 
+/**
+ * React-rendered welcome page — kept only when the `react` feature is selected.
+ *
+ * This file and its plain-JSON sibling (`home-page.controller.ts`) are a
+ * mutually exclusive PAIR: both export `homePageController`, and the scaffolder
+ * (`configureHomePage`) deletes exactly one at generation time, so a real
+ * project never contains both. They coexist here in the template on purpose —
+ * this is not resolver-order ambiguity, and neither file is dead code.
+ */
 export const homePageController: RequestHandler = async ({ response }) => {
   return response.render(<HomePageComponent />);
 };

package/templates/warlock/src/app/shared/tests/infrastructure.test.ts

@@ -1,7 +1,7 @@
 /**
  * Sample test to verify test infrastructure
  */
-import { testGet } from "@warlock.js/core";
+import { testGet } from "@warlock.js/core/tests";
 import { describe, expect, it } from "vitest";
 
 describe("Test Infrastructure", () => {

package/templates/warlock/src/app/users/models/user/migrations/11-12-2025_23-58-03-user.migration.ts

@@ -7,5 +7,6 @@ export default Migration.create(User, {
   password: string(255),
   image: string(500).nullable(),
   imageMetadata: json().nullable(),
+  lastLogin: timestamp().nullable(),
   deletedAt: timestamp().nullable(),
 });

package/templates/warlock/src/app/users/models/user/user.model.ts

@@ -9,6 +9,11 @@ export const userSchema = v.object({
   email: v.email().requiredIfEmpty("id"),
   image: v.string(),
   password: v.string().min(6).requiredIfEmpty("id").addTransformer(useHashedPassword()),
+  // Written by the social-login handler (`app/users/services/login-social.ts`).
+  // A field only reachable through `save({ merge })` still has to be declared
+  // here — `merge` is typed against this schema, so an undeclared key is a
+  // compile error, not a silent write.
+  lastLogin: v.date(),
 });
 
 export type UserSchema = Infer<typeof userSchema>;

package/templates/warlock/src/app/users/services/login-social.ts

@@ -13,8 +13,14 @@ const loginSocial: GuardedRequestHandler = async ({ request, response }) => {
 
   const auth = await user.generateAccessToken();
 
-  user.save({
-    lastLogin: new Date(),
+  // `save()` takes WriterOptions — the fields to write go under `merge`, typed
+  // against `userSchema`. Passing `{ lastLogin }` at the top level was not a
+  // write at all: it was an unknown option, and the value went nowhere.
+  // Awaited, so the write is not a floating promise racing the response.
+  await user.save({
+    merge: {
+      lastLogin: new Date(),
+    },
   });
 
   return response.success({

package/templates/warlock/src/config/cache.ts

@@ -7,6 +7,22 @@ import {
 } from "@warlock.js/cache";
 import { DatabaseCacheDriver, env, useRequestStore } from "@warlock.js/core";
 
+/**
+ * Namespace every cache key by the caller's domain, so two tenants hitting the
+ * same app never read each other's cached values.
+ *
+ * This used to branch on `request.client` first. That property does not exist:
+ * it survived from v4, where `Request` carried a `[key: string]: any` index
+ * signature that made any property name compile. v5 removed the index signature
+ * and the branch became a type error.
+ *
+ * It was deleted rather than renamed. The obvious "fix" — pointing it at
+ * `request.locals.client` — compiles and is worse than the bug: nothing in the
+ * framework populates `request.locals`, so the branch would be permanently
+ * `undefined` and silently dead. `originDomain` below is real (it is derived
+ * from the `Origin` header) and already covers the multi-tenant case, so the
+ * scaffold prefixes on that and models nothing the framework does not provide.
+ */
 const globalPrefix = () => {
   const { request } = useRequestStore();
 
@@ -14,12 +30,6 @@ const globalPrefix = () => {
 
   if (!request) return cachePrefix;
 
-  if (request.client) {
-    cachePrefix = `${cachePrefix}.${request.client.get("username")}`;
-
-    return cachePrefix;
-  }
-
   const domain = request.originDomain || request.header("domain") || request.input("domain");
 
   if (!domain) return cachePrefix;

package/templates/warlock/src/typings.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Project-wide type augmentations.
+ *
+ * This is where the app teaches the framework about ITS OWN types. Warlock's
+ * `Request` class no longer carries a `[key: string]: any` index signature —
+ * attaching arbitrary properties used to compile silently and hide real bugs
+ * behind `any` — so the sanctioned way to extend a request is to merge extra
+ * members into the framework's own interfaces from here.
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THIS FILE HAS `export {}` AT THE BOTTOM
+ * ---------------------------------------------------------------------------
+ * `declare module "x" { ... }` means two completely different things depending
+ * on whether the enclosing file is a module:
+ *
+ * - In a SCRIPT file (no top-level `import`/`export`), it declares an AMBIENT
+ *   module — it REPLACES the real typings of `@warlock.js/core` with whatever
+ *   is inside the braces, and every existing export vanishes.
+ * - In a MODULE file (has a top-level `import`/`export`), it is a MODULE
+ *   AUGMENTATION — it merges into the real typings, which is what we want.
+ *
+ * The trailing `export {}` is what makes this file a module. Do not delete it,
+ * and do not "clean it up" as an unused statement.
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THESE ARE `interface` AND NOT `type`
+ * ---------------------------------------------------------------------------
+ * This project's standard is "prefer `type` over `interface`". These
+ * declarations are a NAMED EXCEPTION to that standard: declaration merging is
+ * an interface-only feature. A `type RequestUser = { ... }` here does not merge
+ * with the framework's declaration — it is a duplicate-identifier error. Every
+ * augmentation in this file must stay an `interface`.
+ */
+
+declare module "@warlock.js/core" {
+  /**
+   * Arbitrary per-request data — `request.locals`.
+   *
+   * Populate it from a middleware and read it downstream in the same request.
+   *
+   * NOTE: the framework itself never writes to `request.locals`; it only
+   * initializes it to `{}` once per request. Anything you declare here is a
+   * promise YOU have to keep in a middleware, otherwise the property typechecks
+   * and is `undefined` forever at runtime. Declare a field here only once
+   * something actually assigns it.
+   *
+   * @example
+   * ```ts
+   * interface RequestLocals {
+   *   // set by a middleware that resolves the tenant from the request host
+   *   tenant?: Tenant;
+   * }
+   * ```
+   */
+  interface RequestLocals {}
+
+  /**
+   * The authenticated user — `request.user`.
+   *
+   * The auth middleware assigns the resolved user model here. Declaring its
+   * shape gives unguarded handlers (ones that may or may not have a user) a
+   * real type instead of `{}`.
+   *
+   * This does NOT make `request.user` non-optional: the framework declares it
+   * as `user?: RequestUser`, and augmentation can add members but cannot remove
+   * the `?`. For routes that are actually behind the auth guard, type the
+   * handler as `GuardedRequestHandler` (see
+   * `src/app/auth/requests/guarded.request.ts`) — that narrows `request.user`
+   * to the app's `User` model AND drops the `| undefined`.
+   *
+   * @example
+   * ```ts
+   * interface RequestUser {
+   *   id: string | number;
+   *   email: string;
+   * }
+   * ```
+   */
+  interface RequestUser {}
+}
+
+export {};

package/templates/warlock/tsconfig.json

@@ -10,18 +10,27 @@
     "downlevelIteration": true,
     "strict": true,
     "forceConsistentCasingInFileNames": true,
-    "typeRoots": ["./src/typings.d.ts"],
     "noFallthroughCasesInSwitch": true,
     "module": "ESNext",
     "jsx": "react-jsx",
     "isolatedModules": true,
-    "moduleResolution": "node",
+    // "bundler", not "node". The framework builds this project with esbuild, and
+    // every `@warlock.js/*` package ships an `exports` map with subpath entries
+    // (e.g. `@warlock.js/core/tests`). Classic "node" resolution ignores
+    // `exports` entirely, so those subpaths resolved to nothing and any import
+    // of one failed to typecheck even though it ran fine at runtime.
+    "moduleResolution": "bundler",
     "resolveJsonModule": true,
     "paths": {
       "app/*": ["./src/app/*"]
     },
     "noEmit": true
   },
-  "include": ["src", "warlock.config.ts", ".warlock/typings/*.d.ts"],
+  // `src/typings.d.ts` is listed explicitly even though "src" already covers it:
+  // it is the project's module-augmentation file, and a dangling reference to it
+  // here is exactly the bug this replaced (it used to sit under `typeRoots`,
+  // which takes DIRECTORIES of @types packages, not files — so the entry pointed
+  // at a path that did not exist and did nothing).
+  "include": ["src", "src/typings.d.ts", "warlock.config.ts", ".warlock/typings/*.d.ts"],
   "exclude": ["node_modules"]
 }