@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.210

package/dist/_chunks/cli-check-ajNY3B2e.js

@@ -0,0 +1,252 @@
+import { n as scanRoutes } from "./scanner-DmqdxzbW.js";
+import { a as ENV_DTS_FILENAME, i as CODEGEN_OUTPUT, n as formatConventionWarnings, r as lintConventions, s as writeRouteCodegen } from "./convention-lint-DLmhGsRS.js";
+import { resolveTimberContext } from "./cli-context-By7k2xVo.js";
+import { dirname, join, resolve } from "node:path";
+import { createRequire } from "node:module";
+import { existsSync, readFileSync } from "node:fs";
+//#region src/cli-check.ts
+/**
+* `timber check` — the implementation behind the CLI command.
+*
+* Two passes, in order:
+*
+* 1. **Routes.** Resolve the project through Vite — so root, `appDir`, and
+*    `pageExtensions` are the ones `timber build` uses, including config
+*    passed inline to `timber()` — then scan, run the convention linter, and
+*    write the route codegen (`.timber/timber-routes.d.ts`,
+*    `.timber/segment-types.d.ts`, `timber-env.d.ts`).
+*
+*    Codegen runs *before* the type pass on purpose: those
+*    files are what give `<Link href>`, `useSegmentParams()` and
+*    `MiddlewareContext` their per-route types (design/09-typescript.md
+*    §"Typed Routes"), and they are build artifacts — a fresh clone that has
+*    never run `timber dev` or `timber build` does not have them, so a type
+*    pass on its own would report errors about correct code. A clone whose
+*    routes changed since the last build has the same problem with stale ones.
+* 2. **Types.** `tsgo --noEmit` over the project.
+*
+* tsgo is spawned as `node <@typescript/native-preview>/lib/tsgo.js`, never as
+* a bare `tsgo` off PATH — the package is an *optional peer dependency*, so
+* there is no reason for its shim to be on a user's PATH, and the shim is a
+* `.cmd` on Windows which cannot be spawned without a shell. `shell: true`
+* would then concatenate the argv into an unescaped command string, so a
+* project path containing a space would break on exactly the platform the
+* shell was there to support. This mirrors `scripts/build-types.js`, whose
+* header comment is the specification for the pattern.
+*
+* Design docs: 11-platform.md §CLI, 09-typescript.md, 28-npm-packaging.md
+*/
+/** The npm package that provides tsgo. Named in the missing-tool message. */
+var TSGO_PACKAGE = "@typescript/native-preview";
+/**
+* The two generated declaration paths, relative to the project root, as they
+* appear in a resolved tsconfig file list. Derived from the writer's own
+* constants — a rename there cannot leave this check hunting for a file nothing
+* writes.
+*/
+var GENERATED_TYPE_PATHS = [ENV_DTS_FILENAME, CODEGEN_OUTPUT];
+/**
+* Locate `@typescript/native-preview`'s JS entry.
+*
+* Resolution is attempted from this package first (it is declared an optional
+* peer dependency, so a package manager links it here when the user installs
+* it) and then from the project root (covering a hoisted install, or a user who
+* added it without the peer link). Throws if neither finds it.
+*/
+function resolveTsgoEntry(root, resolveFrom = (from, specifier) => createRequire(from).resolve(specifier)) {
+	const candidates = [import.meta.url, join(root, "package.json")];
+	let lastError;
+	for (const from of candidates) try {
+		const manifest = resolveFrom(from, `${TSGO_PACKAGE}/package.json`);
+		return join(dirname(manifest), "lib", "tsgo.js");
+	} catch (err) {
+		lastError = err;
+	}
+	throw new Error(`[timber] Cannot find ${TSGO_PACKAGE}, which \`timber check\` uses to type-check.\n\n  Install it as a dev dependency:\n\n    pnpm add -D ${TSGO_PACKAGE}\n\n  (resolution failed: ${lastError instanceof Error ? lastError.message : String(lastError)})`);
+}
+/**
+* Resolve root, appDir and pageExtensions the way `timber build` resolves them
+* — through Vite, never by re-reading `timber.config.ts` (see `cli-context.ts`).
+* Inline `timber({ pageExtensions: [...] })` is the case that bites: a scan
+* that re-read the file would silently use default page extensions and write a
+* route map missing the app's pages. `examples/next-playground-migration` is
+* exactly this shape.
+*/
+async function resolveRouteInputs(options = {}, deps = {}) {
+	const ctx = await resolveTimberContext("check", options.viteConfigFile, deps.resolveViteConfig);
+	return {
+		root: ctx.root,
+		appDir: ctx.appDir,
+		pageExtensions: ctx.config.pageExtensions
+	};
+}
+/**
+* Resolve the app directory, scan it, fail on proven-fatal route
+* misconfigurations, print warnings, and write the route codegen the type pass
+* depends on.
+*
+* Error-level lint findings throw rather than print, matching what
+* `plugins/routing.ts` does at build time: the tree is not fit to publish, so
+* it must not reach codegen either. Warnings are printed and do not fail the
+* command — same severity contract as dev and build, so `timber check` cannot
+* disagree with them about what a valid app is.
+*/
+async function checkRoutes(options = {}, deps = {}) {
+	const inputs = await resolveRouteInputs(options, deps);
+	const { root, appDir, pageExtensions } = inputs;
+	const tree = scanRoutes(appDir, { pageExtensions });
+	const warnings = lintConventions(tree, appDir);
+	const fatal = warnings.filter((w) => w.level === "error");
+	if (fatal.length > 0) throw new Error(formatConventionWarnings(fatal, { color: false }));
+	if (warnings.length > 0) process.stderr.write(`${formatConventionWarnings(warnings)}\n`);
+	try {
+		await writeRouteCodegen(tree, appDir, root);
+	} catch (err) {
+		throw new Error(`[timber] Failed to write the generated route types, which the type check reads: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	verifyCodegenImports(root);
+	return inputs;
+}
+/**
+* Verify that the import specifiers in the generated route types resolve on the
+* filesystem. A `.d.ts` whose import fails does NOT produce a TypeScript error —
+* every type that depends on it silently becomes `any`. The generated file
+* contains type-level `_AssertSchemaNotAny` / `_AssertCodecTypeNotAny` guards
+* that catch this at typecheck time, but a diagnostic here fires earlier and
+* names the exact import that is broken rather than leaving the user to decode
+* a constraint error.
+*/
+function verifyCodegenImports(root) {
+	const dtsPath = join(root, CODEGEN_OUTPUT);
+	let content;
+	try {
+		content = readFileSync(dtsPath, "utf-8");
+	} catch {
+		return;
+	}
+	const dtsDir = dirname(dtsPath);
+	const RELATIVE_IMPORT_RE = /^import\s+type\s+\w+\s+from\s+'(\.\.?\/[^']+)'/gm;
+	const EXTENSIONS = [
+		".ts",
+		".tsx",
+		".js",
+		".jsx",
+		"/index.ts",
+		"/index.tsx"
+	];
+	let match;
+	while ((match = RELATIVE_IMPORT_RE.exec(content)) !== null) {
+		const specifier = match[1];
+		const base = join(dtsDir, specifier);
+		if (!(existsSync(base) || EXTENSIONS.some((ext) => existsSync(base + ext)))) process.stderr.write(`[timber] WARNING: the generated ${CODEGEN_OUTPUT} imports '${specifier}',\n  but no file resolves at ${base}{${EXTENSIONS.join(",")}}.\n  Every type that depends on this import will silently become \`any\`.\n\n  Check that your app/ directory is where timber expects it.\n\n`);
+	}
+}
+/**
+* The production `RunTsgo`: spawn the compiler with its stdio inherited, so its
+* diagnostics stream to the terminal as they are produced (and are not capped
+* by a buffer, as `execFile` output would be).
+*/
+var spawnTsgo = async (command, args, cwd) => {
+	const { spawn } = await import("node:child_process");
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, args, {
+			stdio: "inherit",
+			cwd
+		});
+		child.on("error", reject);
+		child.on("close", (code) => resolve(code));
+	});
+};
+/**
+* The production `ReadTsgoConfig`: `--showConfig`, with stdout captured.
+*
+* `maxBuffer` is raised well past `execFile`'s 1 MB default because the output
+* is one line per file in the program — a large app can exceed that, and
+* overflowing it would make this advisory go quiet on exactly the projects
+* where a misconfigured `include` costs the most. A size-dependent silence is
+* indistinguishable from "everything is fine".
+*/
+var execTsgoConfig = async (command, args, cwd) => {
+	const { execFile } = await import("node:child_process");
+	return new Promise((resolve, reject) => {
+		execFile(command, args, {
+			cwd,
+			maxBuffer: 67108864
+		}, (err, stdout) => err ? reject(err) : resolve(stdout));
+	});
+};
+/**
+* Warn when the generated route declarations will not reach the type checker.
+*
+* Writing `.timber/timber-routes.d.ts` and `timber-env.d.ts` is only half the
+* job: TypeScript loads them only if the project's `include`/`files` actually
+* pull `timber-env.d.ts` in (it is what `/// <reference>`s the route map). A
+* tsconfig with an explicit `include` that lists only source directories —
+* `["app", "*.config.ts"]`, which is what `create-timber-app` shipped before
+* TIM-1332 — silently omits it, and every `<Link href>` then type-checks
+* against the empty placeholder instead of the generated route union. The
+* check would pass while answering the wrong question.
+*
+* The resolved file list comes from `tsgo --showConfig` rather than from our
+* own reading of the tsconfig: `include`, `exclude`, `files`, and `extends`
+* compose in ways that are the compiler's to decide, and a second
+* implementation of them would be a duplicate that drifts. `--showConfig` only
+* resolves globs, so it costs no type checking.
+*
+* This warns rather than fails. An app that never uses typed routes is
+* correct without those declarations, and a hard error would refuse it — the
+* one outcome a check must not produce for a working project. When the answer
+* cannot be determined (tsgo errored, output was not the expected JSON), the
+* warning is skipped: an advisory that fires on an unknown is noise.
+*/
+async function warnIfRouteTypesUnreachable(tsgoEntry, configArgs, cwd, readConfig) {
+	let files;
+	try {
+		const raw = await readConfig(process.execPath, [
+			tsgoEntry,
+			"--showConfig",
+			...configArgs
+		], cwd);
+		files = JSON.parse(raw).files;
+	} catch {
+		return;
+	}
+	if (!Array.isArray(files)) return;
+	if (files.some((file) => {
+		if (typeof file !== "string") return false;
+		const normalized = file.replace(/\\/g, "/");
+		return GENERATED_TYPE_PATHS.some((path) => normalized === path || normalized.endsWith(`/${path}`));
+	})) return;
+	process.stderr.write("[timber] The generated route types are not part of this TypeScript project, so\n  `<Link href>` and `useSegmentParams()` are being checked against empty\n  placeholders. Your tsconfig's \"include\" does not pull in timber-env.d.ts.\n\n  To fix: add it to \"include\":\n\n    \"include\": [\"app\", \"*.config.ts\", \"timber-env.d.ts\"]\n\n");
+}
+/**
+* Run `tsgo --noEmit`, streaming its output.
+*
+* Rejects with the real numeric exit status on type errors. A failure to *start*
+* the compiler is reported separately — the historical bug this replaces
+* surfaced ENOENT as "Type check failed with exit code undefined", which read
+* as a type error and sent users looking at their own code.
+*/
+async function runTypeCheck(options = {}, deps = {}) {
+	const root = options.root ?? process.cwd();
+	const tsgoEntry = (deps.resolveTsgoEntry ?? (() => resolveTsgoEntry(root)))();
+	const runTsgo = deps.runTsgo ?? spawnTsgo;
+	const configArgs = options.config ? ["--project", resolve(process.cwd(), options.config)] : [];
+	await warnIfRouteTypesUnreachable(tsgoEntry, configArgs, root, deps.readTsgoConfig ?? execTsgoConfig);
+	let code;
+	try {
+		code = await runTsgo(process.execPath, [
+			tsgoEntry,
+			"--noEmit",
+			...configArgs
+		], root);
+	} catch (err) {
+		throw new Error(`[timber] Failed to start the type checker: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (code === 0) return;
+	throw new Error(code === null ? "Type check terminated before it finished" : `Type check failed with exit code ${code}`);
+}
+//#endregion
+export { checkRoutes, runTypeCheck };
+
+//# sourceMappingURL=cli-check-ajNY3B2e.js.map

package/dist/_chunks/cli-check-ajNY3B2e.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-check-ajNY3B2e.js","names":[],"sources":["../../src/cli-check.ts"],"sourcesContent":["/**\n * `timber check` — the implementation behind the CLI command.\n *\n * Two passes, in order:\n *\n * 1. **Routes.** Resolve the project through Vite — so root, `appDir`, and\n *    `pageExtensions` are the ones `timber build` uses, including config\n *    passed inline to `timber()` — then scan, run the convention linter, and\n *    write the route codegen (`.timber/timber-routes.d.ts`,\n *    `.timber/segment-types.d.ts`, `timber-env.d.ts`).\n *\n *    Codegen runs *before* the type pass on purpose: those\n *    files are what give `<Link href>`, `useSegmentParams()` and\n *    `MiddlewareContext` their per-route types (design/09-typescript.md\n *    §\"Typed Routes\"), and they are build artifacts — a fresh clone that has\n *    never run `timber dev` or `timber build` does not have them, so a type\n *    pass on its own would report errors about correct code. A clone whose\n *    routes changed since the last build has the same problem with stale ones.\n * 2. **Types.** `tsgo --noEmit` over the project.\n *\n * tsgo is spawned as `node <@typescript/native-preview>/lib/tsgo.js`, never as\n * a bare `tsgo` off PATH — the package is an *optional peer dependency*, so\n * there is no reason for its shim to be on a user's PATH, and the shim is a\n * `.cmd` on Windows which cannot be spawned without a shell. `shell: true`\n * would then concatenate the argv into an unescaped command string, so a\n * project path containing a space would break on exactly the platform the\n * shell was there to support. This mirrors `scripts/build-types.js`, whose\n * header comment is the specification for the pattern.\n *\n * Design docs: 11-platform.md §CLI, 09-typescript.md, 28-npm-packaging.md\n */\n\nimport { createRequire } from 'node:module';\nimport { existsSync, readFileSync } from 'node:fs';\nimport { dirname, join, resolve } from 'node:path';\nimport { scanRoutes } from './routing/scanner.ts';\nimport { lintConventions, formatConventionWarnings } from './routing/convention-lint.ts';\nimport { writeRouteCodegen, CODEGEN_OUTPUT, ENV_DTS_FILENAME } from './routing/codegen-write.ts';\nimport { resolveTimberContext, type ResolveViteConfig } from './cli-context.ts';\n\n/** The npm package that provides tsgo. Named in the missing-tool message. */\nconst TSGO_PACKAGE = '@typescript/native-preview';\n\n/**\n * The two generated declaration paths, relative to the project root, as they\n * appear in a resolved tsconfig file list. Derived from the writer's own\n * constants — a rename there cannot leave this check hunting for a file nothing\n * writes.\n */\nconst GENERATED_TYPE_PATHS = [ENV_DTS_FILENAME, CODEGEN_OUTPUT];\n\n/**\n * Run the compiler to completion.\n *\n * Resolves with its exit status (`null` when a signal killed it) and rejects\n * only when the process could not be started — the two outcomes `runTypeCheck`\n * has to keep apart. The seam is this narrow on purpose: a test double is a\n * plain async function, with no `ChildProcess` shape to imitate.\n */\nexport type RunTsgo = (command: string, args: string[], cwd: string) => Promise<number | null>;\n\n/**\n * Run the compiler and capture its stdout — used for `--showConfig`, whose\n * output is data we read rather than diagnostics the user reads.\n */\nexport type ReadTsgoConfig = (command: string, args: string[], cwd: string) => Promise<string>;\n\n/** @internal Dependency injection for testing. */\nexport interface CheckDeps {\n  /**\n   * Resolve tsgo's own JS entry point. Throws when the package is not\n   * installed — the caller turns that into an install instruction.\n   */\n  resolveTsgoEntry?: () => string;\n  runTsgo?: RunTsgo;\n  readTsgoConfig?: ReadTsgoConfig;\n  resolveViteConfig?: ResolveViteConfig;\n}\n\nexport interface CheckOptions {\n  /** Project root, for resolving tsgo. Defaults to `process.cwd()`. */\n  root?: string;\n  /**\n   * Path to a **tsconfig**, forwarded to tsgo as `--project` and sourced from\n   * the CLI's own `--project`. The route pass takes no part in it: it resolves\n   * the app's configuration through Vite, as `timber build` does.\n   */\n  config?: string;\n}\n\n/**\n * Locate `@typescript/native-preview`'s JS entry.\n *\n * Resolution is attempted from this package first (it is declared an optional\n * peer dependency, so a package manager links it here when the user installs\n * it) and then from the project root (covering a hoisted install, or a user who\n * added it without the peer link). Throws if neither finds it.\n */\nexport function resolveTsgoEntry(\n  root: string,\n  resolveFrom: (from: string, specifier: string) => string = (from, specifier) =>\n    createRequire(from).resolve(specifier)\n): string {\n  // `createRequire` takes a filename or a file URL; a plain absolute path is\n  // the portable spelling for the project root (a `file://` prefix on a Windows\n  // path is not a valid URL). Same form as `checkPeerDependencies`.\n  const candidates = [import.meta.url, join(root, 'package.json')];\n  let lastError: unknown;\n\n  for (const from of candidates) {\n    try {\n      // The package exports no subpath for its entry, so resolve the manifest\n      // and walk to the module its `bin/tsgo` shim imports.\n      const manifest = resolveFrom(from, `${TSGO_PACKAGE}/package.json`);\n      return join(dirname(manifest), 'lib', 'tsgo.js');\n    } catch (err) {\n      lastError = err;\n    }\n  }\n\n  throw new Error(\n    `[timber] Cannot find ${TSGO_PACKAGE}, which \\`timber check\\` uses to type-check.\\n\\n` +\n      `  Install it as a dev dependency:\\n\\n` +\n      `    pnpm add -D ${TSGO_PACKAGE}\\n\\n` +\n      `  (resolution failed: ${lastError instanceof Error ? lastError.message : String(lastError)})`\n  );\n}\n\n/** What the route pass needs from the command line. */\nexport interface RouteOptions {\n  /**\n   * Path to a **Vite** config file, from `--config`. Undefined means Vite's own\n   * discovery, the same as `timber dev`/`build` without the flag. A project\n   * that builds with a custom Vite config has to be checkable with it too, or\n   * `check` resolves a different app than `build` does (TIM-1332, round 4).\n   */\n  viteConfigFile?: string;\n}\n\n/** Everything the route scan needs, as the build itself resolves it. */\nexport interface RouteInputs {\n  root: string;\n  appDir: string;\n  pageExtensions: string[] | undefined;\n}\n\n/**\n * Resolve root, appDir and pageExtensions the way `timber build` resolves them\n * — through Vite, never by re-reading `timber.config.ts` (see `cli-context.ts`).\n * Inline `timber({ pageExtensions: [...] })` is the case that bites: a scan\n * that re-read the file would silently use default page extensions and write a\n * route map missing the app's pages. `examples/next-playground-migration` is\n * exactly this shape.\n */\nexport async function resolveRouteInputs(\n  options: RouteOptions = {},\n  deps: CheckDeps = {}\n): Promise<RouteInputs> {\n  const ctx = await resolveTimberContext('check', options.viteConfigFile, deps.resolveViteConfig);\n  return { root: ctx.root, appDir: ctx.appDir, pageExtensions: ctx.config.pageExtensions };\n}\n\n/**\n * Resolve the app directory, scan it, fail on proven-fatal route\n * misconfigurations, print warnings, and write the route codegen the type pass\n * depends on.\n *\n * Error-level lint findings throw rather than print, matching what\n * `plugins/routing.ts` does at build time: the tree is not fit to publish, so\n * it must not reach codegen either. Warnings are printed and do not fail the\n * command — same severity contract as dev and build, so `timber check` cannot\n * disagree with them about what a valid app is.\n */\nexport async function checkRoutes(\n  options: RouteOptions = {},\n  deps: CheckDeps = {}\n): Promise<RouteInputs> {\n  const inputs = await resolveRouteInputs(options, deps);\n  const { root, appDir, pageExtensions } = inputs;\n\n  const tree = scanRoutes(appDir, { pageExtensions });\n\n  const warnings = lintConventions(tree, appDir);\n  const fatal = warnings.filter((w) => w.level === 'error');\n  if (fatal.length > 0) {\n    throw new Error(formatConventionWarnings(fatal, { color: false }));\n  }\n  if (warnings.length > 0) {\n    process.stderr.write(`${formatConventionWarnings(warnings)}\\n`);\n  }\n\n  // Awaited, unlike the dev/build path: the type pass reads these files, so a\n  // failed write would be reported as type errors in the user's own code.\n  // Reported as a codegen failure rather than surfaced as a bare `EROFS`/\n  // `EACCES` from somewhere unnamed — the raw error says which path could not\n  // be written but not which pass wanted it.\n  try {\n    await writeRouteCodegen(tree, appDir, root);\n  } catch (err) {\n    throw new Error(\n      `[timber] Failed to write the generated route types, which the type check reads: ` +\n        `${err instanceof Error ? err.message : String(err)}`\n    );\n  }\n\n  verifyCodegenImports(root);\n\n  // Returned so the type pass runs against the same root these files landed in.\n  return inputs;\n}\n\n/**\n * Verify that the import specifiers in the generated route types resolve on the\n * filesystem. A `.d.ts` whose import fails does NOT produce a TypeScript error —\n * every type that depends on it silently becomes `any`. The generated file\n * contains type-level `_AssertSchemaNotAny` / `_AssertCodecTypeNotAny` guards\n * that catch this at typecheck time, but a diagnostic here fires earlier and\n * names the exact import that is broken rather than leaving the user to decode\n * a constraint error.\n */\nexport function verifyCodegenImports(root: string): void {\n  const dtsPath = join(root, CODEGEN_OUTPUT);\n  let content: string;\n  try {\n    content = readFileSync(dtsPath, 'utf-8');\n  } catch {\n    return;\n  }\n\n  const dtsDir = dirname(dtsPath);\n\n  // Check relative imports (default imports only — the generated codegen uses\n  // `import type schema from '...'` for relative paths). Named imports from\n  // relative paths are not emitted today; if codegen adds them, extend this.\n  const RELATIVE_IMPORT_RE = /^import\\s+type\\s+\\w+\\s+from\\s+'(\\.\\.?\\/[^']+)'/gm;\n  const EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '/index.ts', '/index.tsx'];\n  let match;\n  while ((match = RELATIVE_IMPORT_RE.exec(content)) !== null) {\n    const specifier = match[1];\n    const base = join(dtsDir, specifier);\n    const resolves = existsSync(base) || EXTENSIONS.some((ext) => existsSync(base + ext));\n    if (!resolves) {\n      process.stderr.write(\n        `[timber] WARNING: the generated ${CODEGEN_OUTPUT} imports '${specifier}',\\n` +\n          `  but no file resolves at ${base}{${EXTENSIONS.join(',')}}.\\n` +\n          `  Every type that depends on this import will silently become \\`any\\`.\\n\\n` +\n          `  Check that your app/ directory is where timber expects it.\\n\\n`\n      );\n    }\n  }\n\n  // Bare-specifier imports (`@timber-js/app/params`) are NOT checked here.\n  // They are all dependencies of @timber-js/app itself — if timber is installed,\n  // they resolve. And createRequire uses CJS resolution which cannot follow\n  // ESM-only subpath exports, producing false warnings (TIM-1348 review).\n}\n\n/**\n * The production `RunTsgo`: spawn the compiler with its stdio inherited, so its\n * diagnostics stream to the terminal as they are produced (and are not capped\n * by a buffer, as `execFile` output would be).\n */\nconst spawnTsgo: RunTsgo = async (command, args, cwd) => {\n  const { spawn } = await import('node:child_process');\n  return new Promise<number | null>((resolve, reject) => {\n    // No `shell: true`: Node would concatenate the argv into an unescaped\n    // command string, so a project path containing a space would break.\n    const child = spawn(command, args, { stdio: 'inherit', cwd });\n    child.on('error', reject);\n    child.on('close', (code) => resolve(code));\n  });\n};\n\n/**\n * The production `ReadTsgoConfig`: `--showConfig`, with stdout captured.\n *\n * `maxBuffer` is raised well past `execFile`'s 1 MB default because the output\n * is one line per file in the program — a large app can exceed that, and\n * overflowing it would make this advisory go quiet on exactly the projects\n * where a misconfigured `include` costs the most. A size-dependent silence is\n * indistinguishable from \"everything is fine\".\n */\nconst execTsgoConfig: ReadTsgoConfig = async (command, args, cwd) => {\n  const { execFile } = await import('node:child_process');\n  return new Promise<string>((resolve, reject) => {\n    execFile(command, args, { cwd, maxBuffer: 64 * 1024 * 1024 }, (err, stdout) =>\n      err ? reject(err) : resolve(stdout)\n    );\n  });\n};\n\n/**\n * Warn when the generated route declarations will not reach the type checker.\n *\n * Writing `.timber/timber-routes.d.ts` and `timber-env.d.ts` is only half the\n * job: TypeScript loads them only if the project's `include`/`files` actually\n * pull `timber-env.d.ts` in (it is what `/// <reference>`s the route map). A\n * tsconfig with an explicit `include` that lists only source directories —\n * `[\"app\", \"*.config.ts\"]`, which is what `create-timber-app` shipped before\n * TIM-1332 — silently omits it, and every `<Link href>` then type-checks\n * against the empty placeholder instead of the generated route union. The\n * check would pass while answering the wrong question.\n *\n * The resolved file list comes from `tsgo --showConfig` rather than from our\n * own reading of the tsconfig: `include`, `exclude`, `files`, and `extends`\n * compose in ways that are the compiler's to decide, and a second\n * implementation of them would be a duplicate that drifts. `--showConfig` only\n * resolves globs, so it costs no type checking.\n *\n * This warns rather than fails. An app that never uses typed routes is\n * correct without those declarations, and a hard error would refuse it — the\n * one outcome a check must not produce for a working project. When the answer\n * cannot be determined (tsgo errored, output was not the expected JSON), the\n * warning is skipped: an advisory that fires on an unknown is noise.\n */\nasync function warnIfRouteTypesUnreachable(\n  tsgoEntry: string,\n  configArgs: string[],\n  cwd: string,\n  readConfig: ReadTsgoConfig\n): Promise<void> {\n  let files: unknown;\n  try {\n    const raw = await readConfig(process.execPath, [tsgoEntry, '--showConfig', ...configArgs], cwd);\n    files = (JSON.parse(raw) as { files?: unknown }).files;\n  } catch {\n    return;\n  }\n  if (!Array.isArray(files)) return;\n\n  // Suffix match, not path resolution: `--showConfig` prints paths relative to\n  // whichever tsconfig the compiler *found*, which for a bare `timber check`\n  // is a directory we never learn. Over-matching only suppresses an advisory.\n  //\n  // The bare form is matched as well as the `/`-prefixed one. tsgo emits\n  // `./timber-env.d.ts` today, but a leading `./` is cosmetic and an emitter\n  // that dropped it would turn this into a warning printed at every correctly\n  // configured project — the failure direction that trains people to ignore it.\n  const reaches = files.some((file) => {\n    if (typeof file !== 'string') return false;\n    const normalized = file.replace(/\\\\/g, '/');\n    return GENERATED_TYPE_PATHS.some(\n      (path) => normalized === path || normalized.endsWith(`/${path}`)\n    );\n  });\n  if (reaches) return;\n\n  process.stderr.write(\n    `[timber] The generated route types are not part of this TypeScript project, so\\n` +\n      `  \\`<Link href>\\` and \\`useSegmentParams()\\` are being checked against empty\\n` +\n      `  placeholders. Your tsconfig's \"include\" does not pull in timber-env.d.ts.\\n\\n` +\n      `  To fix: add it to \"include\":\\n\\n` +\n      `    \"include\": [\"app\", \"*.config.ts\", \"timber-env.d.ts\"]\\n\\n`\n  );\n}\n\n/**\n * Run `tsgo --noEmit`, streaming its output.\n *\n * Rejects with the real numeric exit status on type errors. A failure to *start*\n * the compiler is reported separately — the historical bug this replaces\n * surfaced ENOENT as \"Type check failed with exit code undefined\", which read\n * as a type error and sent users looking at their own code.\n */\nexport async function runTypeCheck(\n  options: CheckOptions = {},\n  deps: CheckDeps = {}\n): Promise<void> {\n  // The *resolved* root, handed over by the route pass — not `process.cwd()`.\n  // The two differ whenever `--config` names a Vite config elsewhere, and the\n  // route pass wrote `.timber/*` and `timber-env.d.ts` under the resolved one.\n  // Running tsgo from cwd would then discover a different tsconfig entirely and\n  // type-check a different project than the one just validated (TIM-1332, round\n  // 5) — routes checked for the app, types checked for the monorepo around it.\n  const root = options.root ?? process.cwd();\n  const tsgoEntry = (deps.resolveTsgoEntry ?? (() => resolveTsgoEntry(root)))();\n  const runTsgo = deps.runTsgo ?? spawnTsgo;\n\n  // An explicit `--project` is a path the user typed at their own prompt, so it\n  // is resolved against *their* cwd before the compiler is moved to the project\n  // root. Without `--project`, tsgo discovers `tsconfig.json` from `root`,\n  // which is where the declarations it needs were just written.\n  const configArgs = options.config ? ['--project', resolve(process.cwd(), options.config)] : [];\n\n  // Before checking: say so if the declarations the route pass just wrote will\n  // not be part of the program. Otherwise the check passes while `<Link href>`\n  // is measured against a placeholder. Same root and same argv as the check\n  // itself, or it would inspect a different program than the one tsgo reads.\n  await warnIfRouteTypesUnreachable(\n    tsgoEntry,\n    configArgs,\n    root,\n    deps.readTsgoConfig ?? execTsgoConfig\n  );\n\n  let code: number | null;\n  try {\n    code = await runTsgo(process.execPath, [tsgoEntry, '--noEmit', ...configArgs], root);\n  } catch (err) {\n    // Could not start the compiler at all. Kept distinct from a nonzero exit:\n    // the version this replaced reported ENOENT as \"Type check failed with\n    // exit code undefined\", which reads as a verdict on the user's types.\n    throw new Error(\n      `[timber] Failed to start the type checker: ${err instanceof Error ? err.message : String(err)}`\n    );\n  }\n\n  if (code === 0) return;\n\n  // A null code means a signal killed the process rather than it exiting.\n  // Say so instead of printing \"exit code null\".\n  throw new Error(\n    code === null\n      ? 'Type check terminated before it finished'\n      : `Type check failed with exit code ${code}`\n  );\n}\n"],"mappings":"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"}

package/dist/_chunks/cli-context-By7k2xVo.js

@@ -0,0 +1,70 @@
+import { i as isTimberPluginApi } from "./plugin-context-BPBPc3lL.js";
+//#region src/cli-context.ts
+/**
+* Resolve timber's configuration the way `timber build` resolves it, for CLI
+* commands that run outside the build: `timber check` and `timber preview`.
+*
+* Reading `timber.config.ts` directly is **not** equivalent, which is the whole
+* reason this goes through Vite (TIM-1332, review round 3; TIM-1531):
+*
+* - Config passed inline — `timber({ pageExtensions, adapter, output })` in
+*   `vite.config.ts` — lives only in the plugin's closure. Nothing that
+*   re-reads the config file can see it.
+* - `root` is Vite's resolved root, not the caller's cwd, and the two differ in
+*   the monorepo layouts TIM-498 describes.
+* - The build directory can come from Vite's `build.outDir`, which only a
+*   resolved Vite config knows.
+* - `--config` names a Vite config file; only Vite can load it.
+*
+* There is no fallback to a second, hand-rolled resolution. A project whose
+* Vite config does not produce the timber plugin cannot be built either, so a
+* command that quietly proceeded on a guess would act on an app that does not
+* exist.
+*
+* Design docs: 11-platform.md §CLI
+*/
+/** The plugin that publishes timber's resolved context on its Vite `api`. */
+var TIMBER_ROOT_SYNC_PLUGIN = "timber-root-sync";
+/**
+* Ask Vite for the resolved config, which is what carries timber's context.
+*
+* `resolveConfig` runs the whole config pipeline — config file discovery,
+* `config` and `configResolved` hooks — so the context it produces is the one
+* `timber build` would use. Measured at ~300-400ms on a real app.
+*/
+var defaultResolveViteConfig = async (inlineConfig, command, defaultMode, defaultNodeEnv) => {
+	const { resolveConfig } = await import("vite");
+	return resolveConfig(inlineConfig, command, defaultMode, defaultNodeEnv);
+};
+/**
+* The mode defaults `timber build` resolves under.
+*
+* `resolveConfig`'s own defaults are `'development'` for both, but nothing
+* reaches it with those on a build: `createBuilder` goes through Vite's
+* internal `resolveConfigToBuild`, which calls
+* `resolveConfig(inlineConfig, 'build', 'production', 'production')`. A config
+* written as `defineConfig(({ mode }) => …)`, or one that loads `.env.production`,
+* therefore resolves to a *different* app under the two. Passing the defaults
+* explicitly is what makes "check validates what build builds" — and "preview
+* serves what build wrote" — true rather than true-by-coincidence for configs
+* that ignore mode (TIM-1332, round 6).
+*/
+var BUILD_MODE_DEFAULTS = ["production", "production"];
+/**
+* Resolve the project through Vite and return timber's context as
+* `timber build` would see it.
+*
+* @param command The CLI command asking, named in the error message.
+* @param viteConfigFile `--config`. Undefined means Vite's own discovery, the
+*   same as `timber build` without the flag.
+*/
+async function resolveTimberContext(command, viteConfigFile, resolveViteConfig = defaultResolveViteConfig) {
+	const { plugins } = await resolveViteConfig({ configFile: viteConfigFile }, "build", ...BUILD_MODE_DEFAULTS);
+	const rootSync = plugins.find((plugin) => plugin.name === TIMBER_ROOT_SYNC_PLUGIN);
+	if (!rootSync || !isTimberPluginApi(rootSync.api)) throw new Error(`[timber] Could not read the resolved timber configuration from your Vite config.\n\n  \`timber ${command}\` resolves your project through Vite so it sees the same\n  configuration \`timber build\` uses — including config passed inline to timber().\n\n  Check that vite.config.ts exists and lists the timber plugin:\n\n    import { timber } from '@timber-js/app';\n    export default { plugins: [timber()] };\n`);
+	return rootSync.api.getContext();
+}
+//#endregion
+export { resolveTimberContext };
+
+//# sourceMappingURL=cli-context-By7k2xVo.js.map

package/dist/_chunks/cli-context-By7k2xVo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-context-By7k2xVo.js","names":[],"sources":["../../src/cli-context.ts"],"sourcesContent":["/**\n * Resolve timber's configuration the way `timber build` resolves it, for CLI\n * commands that run outside the build: `timber check` and `timber preview`.\n *\n * Reading `timber.config.ts` directly is **not** equivalent, which is the whole\n * reason this goes through Vite (TIM-1332, review round 3; TIM-1531):\n *\n * - Config passed inline — `timber({ pageExtensions, adapter, output })` in\n *   `vite.config.ts` — lives only in the plugin's closure. Nothing that\n *   re-reads the config file can see it.\n * - `root` is Vite's resolved root, not the caller's cwd, and the two differ in\n *   the monorepo layouts TIM-498 describes.\n * - The build directory can come from Vite's `build.outDir`, which only a\n *   resolved Vite config knows.\n * - `--config` names a Vite config file; only Vite can load it.\n *\n * There is no fallback to a second, hand-rolled resolution. A project whose\n * Vite config does not produce the timber plugin cannot be built either, so a\n * command that quietly proceeded on a guess would act on an app that does not\n * exist.\n *\n * Design docs: 11-platform.md §CLI\n */\n\nimport { isTimberPluginApi, type PluginContext } from './plugin-context.ts';\n\n/** The plugin that publishes timber's resolved context on its Vite `api`. */\nconst TIMBER_ROOT_SYNC_PLUGIN = 'timber-root-sync';\n\n/** The subset of a resolved Vite plugin this module reads. */\nexport interface PluginWithApi {\n  name: string;\n  api?: unknown;\n}\n\n/**\n * Vite's own `resolveConfig`, narrowed to what this module passes and reads.\n *\n * The seam sits at `resolveConfig` rather than at \"give me the plugins\" so the\n * *arguments* are the thing under test: which config file, which command, and\n * which mode defaults. Those arguments have been wrong three separate times\n * (TIM-1332 rounds 4-6), and a double that answered \"here are the plugins\"\n * could not see any of it. The double returns what Vite returns — plugins with\n * an opaque `api` — so the lookup and narrowing under test stay the real ones.\n */\nexport type ResolveViteConfig = (\n  inlineConfig: { configFile: string | undefined },\n  command: 'build',\n  defaultMode: string,\n  defaultNodeEnv: string\n) => Promise<{ plugins: readonly PluginWithApi[] }>;\n\n/**\n * Ask Vite for the resolved config, which is what carries timber's context.\n *\n * `resolveConfig` runs the whole config pipeline — config file discovery,\n * `config` and `configResolved` hooks — so the context it produces is the one\n * `timber build` would use. Measured at ~300-400ms on a real app.\n */\nconst defaultResolveViteConfig: ResolveViteConfig = async (\n  inlineConfig,\n  command,\n  defaultMode,\n  defaultNodeEnv\n) => {\n  const { resolveConfig } = await import('vite');\n  return resolveConfig(inlineConfig, command, defaultMode, defaultNodeEnv);\n};\n\n/**\n * The mode defaults `timber build` resolves under.\n *\n * `resolveConfig`'s own defaults are `'development'` for both, but nothing\n * reaches it with those on a build: `createBuilder` goes through Vite's\n * internal `resolveConfigToBuild`, which calls\n * `resolveConfig(inlineConfig, 'build', 'production', 'production')`. A config\n * written as `defineConfig(({ mode }) => …)`, or one that loads `.env.production`,\n * therefore resolves to a *different* app under the two. Passing the defaults\n * explicitly is what makes \"check validates what build builds\" — and \"preview\n * serves what build wrote\" — true rather than true-by-coincidence for configs\n * that ignore mode (TIM-1332, round 6).\n */\nconst BUILD_MODE_DEFAULTS = ['production', 'production'] as const;\n\n/**\n * Resolve the project through Vite and return timber's context as\n * `timber build` would see it.\n *\n * @param command The CLI command asking, named in the error message.\n * @param viteConfigFile `--config`. Undefined means Vite's own discovery, the\n *   same as `timber build` without the flag.\n */\nexport async function resolveTimberContext(\n  command: string,\n  viteConfigFile: string | undefined,\n  resolveViteConfig: ResolveViteConfig = defaultResolveViteConfig\n): Promise<PluginContext> {\n  // `configFile: undefined` is Vite's own \"discover it\" value, so the default\n  // path stays exactly what Vite does for `timber build` without `--config`.\n  const { plugins } = await resolveViteConfig(\n    { configFile: viteConfigFile },\n    'build',\n    ...BUILD_MODE_DEFAULTS\n  );\n\n  const rootSync = plugins.find((plugin) => plugin.name === TIMBER_ROOT_SYNC_PLUGIN);\n  if (!rootSync || !isTimberPluginApi(rootSync.api)) {\n    throw new Error(\n      `[timber] Could not read the resolved timber configuration from your Vite config.\\n\\n` +\n        `  \\`timber ${command}\\` resolves your project through Vite so it sees the same\\n` +\n        `  configuration \\`timber build\\` uses — including config passed inline to timber().\\n\\n` +\n        `  Check that vite.config.ts exists and lists the timber plugin:\\n\\n` +\n        `    import { timber } from '@timber-js/app';\\n` +\n        `    export default { plugins: [timber()] };\\n`\n    );\n  }\n\n  return rootSync.api.getContext();\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,IAAM,0BAA0B;;;;;;;;AAgChC,IAAM,2BAA8C,OAClD,cACA,SACA,aACA,mBACG;CACH,MAAM,EAAE,kBAAkB,MAAM,OAAO;CACvC,OAAO,cAAc,cAAc,SAAS,aAAa,cAAc;AACzE;;;;;;;;;;;;;;AAeA,IAAM,sBAAsB,CAAC,cAAc,YAAY;;;;;;;;;AAUvD,eAAsB,qBACpB,SACA,gBACA,oBAAuC,0BACf;CAGxB,MAAM,EAAE,YAAY,MAAM,kBACxB,EAAE,YAAY,eAAe,GAC7B,SACA,GAAG,mBACL;CAEA,MAAM,WAAW,QAAQ,MAAM,WAAW,OAAO,SAAS,uBAAuB;CACjF,IAAI,CAAC,YAAY,CAAC,kBAAkB,SAAS,GAAG,GAC9C,MAAM,IAAI,MACR,kGACgB,QAAQ,iTAK1B;CAGF,OAAO,SAAS,IAAI,WAAW;AACjC"}