@timber-js/app 0.2.0-alpha.191 → 0.2.0-alpha.194

package/src/analyze/scan.ts

@@ -0,0 +1,149 @@
+/**
+ * scan — project source-file disk scan shared by the crawl and the
+ * graph cache.
+ *
+ * One walker, one rule set: the crawl uses it to find files no graph
+ * reached (the provisional/pending set) and to bound graph membership,
+ * and the mtime-keyed graph cache fingerprints exactly the same file
+ * set — the three can never disagree about what "the project" is (a
+ * file the crawl classifies but the fingerprint ignores would make the
+ * cache silently stale).
+ *
+ * Skip rules are deliberately shallow: timber's router excludes only
+ * `_`-prefixed directories, so `app/.well-known/page.tsx` and
+ * `app/dist/page.tsx` are REAL routes — a rule that skipped `dist` or
+ * dot-directories at any depth would hide legitimate route files from
+ * the scan while the module graph still reached them (codex review,
+ * PR #1056). Therefore:
+ *
+ * - `node_modules` is skipped at ANY depth (never project source, and
+ *   graph membership excludes it identically)
+ * - dot-prefixed and build-output directories (`dist`, `coverage`, …)
+ *   are skipped only as the FIRST path segment under the root — that
+ *   is where `.git`, `.timber`, `.wrangler`, and real build outputs
+ *   live; deeper occurrences are walked
+ *
+ * Deliberately vite-free: the cache-hit path of `timber graph` reads
+ * this module without booting (or even importing) Vite.
+ *
+ * Design docs: 47-module-environment-tooling.md §2, §Cold-path policy.
+ */
+
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * Slash-normalize a Windows path — Vite's `normalizePath` for the
+ * vite-free callers (the graph cache-hit path must not import Vite).
+ * Same platform guard as Vite's: posix paths pass through untouched,
+ * so a filename containing a literal backslash is never corrupted.
+ */
+export const normalizeSlashes: (path: string) => string =
+  process.platform === 'win32' ? (path) => path.replace(/\\/g, '/') : (path) => path;
+
+/** A scan failure the caller records instead of swallowing. */
+export interface ScanFailure {
+  dir: string;
+  message: string;
+}
+
+/**
+ * Directories never scanned when they are the first path segment under
+ * the root. `node_modules` is additionally skipped at any depth.
+ */
+export const SCAN_IGNORED_DIRS = new Set(['node_modules', 'dist', 'test-results', 'coverage']);
+
+/**
+ * Single source of truth for builtin source extensions. Includes mdx —
+ * timber supports page.mdx via pageExtensions, so an unreferenced MDX
+ * page must not vanish from --all output.
+ */
+const BUILTIN_EXTENSIONS = ['ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs', 'mts', 'cts', 'mdx'] as const;
+
+/** Regex form of BUILTIN_EXTENSIONS for file-basename matching. */
+export const SOURCE_EXTENSIONS = new RegExp(`\\.(?:${BUILTIN_EXTENSIONS.join('|')})$`);
+
+/** Set form for O(1) membership checks. */
+const BUILTIN_EXTENSION_SET = new Set<string>(BUILTIN_EXTENSIONS);
+
+/**
+ * Build a regex that matches SOURCE_EXTENSIONS plus any extra
+ * extensions from the user's pageExtensions config. Returns the
+ * builtin regex unchanged when nothing new is added.
+ */
+export function buildSourceExtensions(pageExtensions?: readonly string[]): RegExp {
+  if (!pageExtensions) return SOURCE_EXTENSIONS;
+  const extras = pageExtensions.filter((ext) => !BUILTIN_EXTENSION_SET.has(ext));
+  if (extras.length === 0) return SOURCE_EXTENSIONS;
+  const escaped = extras.map((ext) => ext.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+  return new RegExp(`\\.(?:${BUILTIN_EXTENSIONS.join('|')}|${escaped.join('|')})$`);
+}
+
+/** Whether a directory SEGMENT is skipped at the given depth (0 = root child). */
+function isSkippedDirSegment(segment: string, depth: number): boolean {
+  if (segment === 'node_modules') return true;
+  if (depth === 0 && (segment.startsWith('.') || SCAN_IGNORED_DIRS.has(segment))) return true;
+  return false;
+}
+
+/** Whether a file basename is admitted as project source. */
+function isSourceBasename(base: string, depth: number, extensions?: RegExp): boolean {
+  if (depth === 0 && base.startsWith('.')) return false;
+  if (!(extensions ?? SOURCE_EXTENSIONS).test(base)) return false;
+  // Declaration files are types-only — they never run in any environment.
+  if (/\.d\.[mc]?ts$/.test(base)) return false;
+  return true;
+}
+
+/**
+ * Whether an absolute, slash-normalized path is one the scanner WOULD
+ * admit — the same segment rules the walker applies, so a
+ * directly-addressed path (`package.json`, `<root>/dist/generated.js`,
+ * `types.d.ts`, a nested node_modules file) is answered exactly the
+ * way the scan-based sweep would answer it: by exclusion. Existence
+ * and is-a-file checks remain the caller's (this is pure path logic).
+ */
+export function isScannableSourceFile(file: string, root: string, extensions?: RegExp): boolean {
+  if (!file.startsWith(root + '/')) return false;
+  const segments = file.slice(root.length + 1).split('/');
+  const base = segments[segments.length - 1];
+  for (let depth = 0; depth < segments.length - 1; depth++) {
+    if (isSkippedDirSegment(segments[depth], depth)) return false;
+  }
+  return isSourceBasename(base, segments.length - 1, extensions);
+}
+
+/**
+ * Recursively list project source files on disk.
+ *
+ * Unreadable directories are reported through `onFailure`, not thrown
+ * and not swallowed — this walker exists to keep files from silently
+ * vanishing, so a directory it cannot see must be visible too.
+ */
+export async function scanProjectSourceFiles(
+  dir: string,
+  out: string[],
+  onFailure: (failure: ScanFailure) => void,
+  depth = 0,
+  extensions?: RegExp
+): Promise<void> {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch (error) {
+    onFailure({
+      dir,
+      message: `directory scan failed: ${error instanceof Error ? error.message : String(error)}`,
+    });
+    return;
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (isSkippedDirSegment(entry.name, depth)) continue;
+      await scanProjectSourceFiles(full, out, onFailure, depth + 1, extensions);
+    } else if (entry.isFile() && isSourceBasename(entry.name, depth, extensions)) {
+      out.push(full);
+    }
+  }
+}

package/src/cache/cache-api.ts

@@ -1,10 +1,10 @@
-import type { CacheOptions } from './index';
-import type { PrebuiltComponentOptions } from '../server/prebuilt-runtime';
-import { createCache } from './timber-cache';
-import { getCacheHandler } from './handler-store';
-import { recordInvalidation } from './invalidation-epoch';
-import { writeTombstonesForTag } from '../server/prebuilt/overlay.js';
-import { getCdnPurgeHandler } from '../cdn/purge-store.js';
+import type { CacheOptions } from './index.ts';
+import type { PrebuiltComponentOptions } from '../server/prebuilt-runtime.ts';
+import { createCache } from './timber-cache.ts';
+import { getCacheHandler } from './handler-store.ts';
+import { recordInvalidation } from './invalidation-epoch.ts';
+import { writeTombstonesForTag } from '../server/prebuilt/overlay.ts';
+import { getCdnPurgeHandler } from '../cdn/purge-store.ts';
 
 const componentFallbackWarned = new WeakSet<object>();
 

package/src/cache/index.ts

@@ -1,6 +1,6 @@
 // @timber-js/app/cache — Caching primitives
 
-import { estimateByteSize } from './sizeof.js';
+import { estimateByteSize } from './sizeof.ts';
 
 export interface CacheHandler {
   get(key: string): Promise<{ value: unknown; stale: boolean } | null>;
@@ -166,18 +166,18 @@ export class MemoryCacheHandler implements CacheHandler {
   }
 }
 
-export { RedisCacheHandler } from './redis-handler';
-export type { RedisClient, RedisWriteOp } from './redis-handler';
-export { cache } from './cache-api';
-export { setCacheHandler, getCacheHandler } from './handler-store';
-export { setDefaultSingleflightTimeout } from './timber-cache';
+export { RedisCacheHandler } from './redis-handler.ts';
+export type { RedisClient, RedisWriteOp } from './redis-handler.ts';
+export { cache } from './cache-api.ts';
+export { setCacheHandler, getCacheHandler } from './handler-store.ts';
+export { setDefaultSingleflightTimeout } from './timber-cache.ts';
 // NOTE: registerCachedFunction (runtime for 'use cache' directive) removed.
 // Future feature pending design doc. See design/06-caching.md.
-export { estimateByteSize } from './sizeof';
+export { estimateByteSize } from './sizeof.ts';
 
 // --- Cache Store layering (design/46) ---
-export { TagAwareCacheHandler } from './tag-aware-handler';
-export type { CacheStore } from './store';
+export { TagAwareCacheHandler } from './tag-aware-handler.ts';
+export type { CacheStore } from './store.ts';
 // stableStringify, createSingleflight, and SingleflightTimeoutError are
 // internal utilities used by the cache implementation. They are not
 // re-exported here — import directly from the source files if needed

package/src/cache/redis-handler.ts

@@ -1,5 +1,5 @@
-import type { CacheHandler } from './index';
-import { warnLossyJsonValue } from './json-lossy-check.js';
+import type { CacheHandler } from './index.ts';
+import { warnLossyJsonValue } from './json-lossy-check.ts';
 
 /**
  * Minimal Redis client contract for `RedisCacheHandler`.

package/src/cache/stores/cloudflare-kv.ts

@@ -12,7 +12,7 @@
  * consistency model (use short TTLs for security-critical invalidation).
  */
 
-import type { CacheStore } from '../store';
+import type { CacheStore } from '../store.ts';
 
 export interface CloudflareKVNamespace {
   get(key: string, options?: { type?: string }): Promise<string | null>;

package/src/cache/stores/memory.ts

@@ -12,8 +12,8 @@
  * set size on invalidation, not to memory — stale memberships are just strings.
  */
 
-import type { CacheStore } from '../store';
-import { estimateByteSize } from '../sizeof.js';
+import type { CacheStore } from '../store.ts';
+import { estimateByteSize } from '../sizeof.ts';
 
 export interface MemoryStoreOptions {
   maxEntries?: number;

package/src/cache/stores/redis.ts

@@ -5,7 +5,7 @@
  * because this store provides sadd/smembers/srem/sdel.
  */
 
-import type { CacheStore } from '../store';
+import type { CacheStore } from '../store.ts';
 
 /**
  * Minimal Redis client contract. Same philosophy as the old RedisClient

package/src/cache/stores/vercel.ts

@@ -9,7 +9,7 @@
  * simultaneously. Available on all plans.
  */
 
-import type { CacheStore } from '../store';
+import type { CacheStore } from '../store.ts';
 
 /**
  * Vercel Runtime Cache contract — the subset we depend on.

package/src/cache/tag-aware-handler.ts

@@ -19,8 +19,8 @@
  * Implements the CacheHandler interface consumed by timber-cache.ts.
  */
 
-import type { CacheHandler } from './index';
-import type { CacheStore } from './store';
+import type { CacheHandler } from './index.ts';
+import type { CacheStore } from './store.ts';
 
 const DATA_PREFIX = 'd:';
 const TAG_SET_PREFIX = 'ts:';

package/src/cache/timber-cache.ts

@@ -1,15 +1,15 @@
-import type { CacheHandler, CacheOptions } from './index';
-import { stableStringify } from './stable-stringify';
-import { createSingleflight } from './singleflight';
+import type { CacheHandler, CacheOptions } from './index.ts';
+import { stableStringify } from './stable-stringify.ts';
+import { createSingleflight } from './singleflight.ts';
 import {
   currentInvalidationEpoch,
   lastInvalidationEpochFor,
   wasInvalidatedSince,
-} from './invalidation-epoch';
-import { addSpanEventSync } from '../server/tracing.js';
-import { logSwrRefetchFailed, swallow } from '../server/logger.js';
-import { getWaitUntil } from '../server/waituntil-bridge.js';
-import { fnv1aHash } from './fast-hash.js';
+} from './invalidation-epoch.ts';
+import { addSpanEventSync } from '../server/tracing.ts';
+import { logSwrRefetchFailed, swallow } from '../server/logger.ts';
+import { getWaitUntil } from '../server/waituntil-bridge.ts';
+import { fnv1aHash } from './fast-hash.ts';
 
 let defaultSingleflight = createSingleflight();
 

package/src/cdn/cloudflare-purge.ts

@@ -5,7 +5,7 @@
  * See https://developers.cloudflare.com/cache/how-to/purge-cache/purge-by-tags/
  */
 
-import type { CdnPurgeHandler } from './purge-store';
+import type { CdnPurgeHandler } from './purge-store.ts';
 
 export interface CloudflarePurgeOptions {
   /** Cloudflare zone ID. */

package/src/cdn/fastly-purge.ts

@@ -4,7 +4,7 @@
  * See https://www.fastly.com/documentation/reference/api/purging/
  */
 
-import type { CdnPurgeHandler } from './purge-store';
+import type { CdnPurgeHandler } from './purge-store.ts';
 
 export interface FastlyPurgeOptions {
   /** Fastly service ID. */

package/src/cdn/index.ts

@@ -3,11 +3,17 @@
 // Header utilities and purge handler for CDN caching. Developer-elected,
 // never automatic. See design/25-production-deployments.md §Layer 2.
 
-export { cacheControl, surrogateKey, surrogateControl, cdnCacheControl, cacheTag } from './headers';
-export type { CacheControlOptions, SurrogateControlOptions } from './headers';
+export {
+  cacheControl,
+  surrogateKey,
+  surrogateControl,
+  cdnCacheControl,
+  cacheTag,
+} from './headers.ts';
+export type { CacheControlOptions, SurrogateControlOptions } from './headers.ts';
 
-export { setCdnPurgeHandler, getCdnPurgeHandler } from './purge-store';
-export type { CdnPurgeHandler } from './purge-store';
+export { setCdnPurgeHandler, getCdnPurgeHandler } from './purge-store.ts';
+export type { CdnPurgeHandler } from './purge-store.ts';
 
 // Platform-specific purge handlers are at their own entry points:
 //   @timber-js/app/cdn/cloudflare         → CloudflarePurge (REST API, Enterprise)

package/src/cdn/workers-cache-purge.ts

@@ -5,13 +5,17 @@
  * Available on ALL Cloudflare plans (no Enterprise requirement).
  * No API token needed — uses the Workers runtime's built-in cache API.
  *
+ * ctx.cache.purge() operates on the same underlying Cloudflare CDN cache
+ * as caches.default — entries stored via cache.put() with matching
+ * Cache-Tag headers are purged (TIM-1172). See design/25 §TIM-1172.
+ *
  * Auto-wired by the Cloudflare adapter when no user-configured CDN
  * purge handler is set. Uses the Workers Cache ALS bridge to access
  * ctx.cache from within the request context.
  */
 
-import type { CdnPurgeHandler } from './purge-store';
-import { getWorkersCachePurgeCtx } from '../server/workers-cache-bridge.js';
+import type { CdnPurgeHandler } from './purge-store.ts';
+import { getWorkersCachePurgeCtx } from '../server/workers-cache-bridge.ts';
 
 export class WorkersCachePurge implements CdnPurgeHandler {
   async purgeTags(tags: string[]): Promise<void> {

package/src/cli-check.ts

@@ -31,11 +31,12 @@
  */
 
 import { createRequire } from 'node:module';
+import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
-import { scanRoutes } from './routing/scanner.js';
-import { lintConventions, formatConventionWarnings } from './routing/convention-lint.js';
-import { writeRouteCodegen, CODEGEN_OUTPUT, ENV_DTS_FILENAME } from './routing/codegen-write.js';
-import { isTimberPluginApi } from './plugin-context.js';
+import { scanRoutes } from './routing/scanner.ts';
+import { lintConventions, formatConventionWarnings } from './routing/convention-lint.ts';
+import { writeRouteCodegen, CODEGEN_OUTPUT, ENV_DTS_FILENAME } from './routing/codegen-write.ts';
+import { isTimberPluginApi } from './plugin-context.ts';
 
 /** The plugin that publishes timber's resolved context on its Vite `api`. */
 const TIMBER_ROOT_SYNC_PLUGIN = 'timber-root-sync';
@@ -292,10 +293,58 @@ export async function checkRoutes(
     );
   }
 
+  verifyCodegenImports(root);
+
   // Returned so the type pass runs against the same root these files landed in.
   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.
+ */
+export function verifyCodegenImports(root: string): void {
+  const dtsPath = join(root, CODEGEN_OUTPUT);
+  let content: string;
+  try {
+    content = readFileSync(dtsPath, 'utf-8');
+  } catch {
+    return;
+  }
+
+  const dtsDir = dirname(dtsPath);
+
+  // Check relative imports (default imports only — the generated codegen uses
+  // `import type schema from '...'` for relative paths). Named imports from
+  // relative paths are not emitted today; if codegen adds them, extend this.
+  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);
+    const resolves = existsSync(base) || EXTENSIONS.some((ext) => existsSync(base + ext));
+    if (!resolves) {
+      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`
+      );
+    }
+  }
+
+  // Bare-specifier imports (`@timber-js/app/params`) are NOT checked here.
+  // They are all dependencies of @timber-js/app itself — if timber is installed,
+  // they resolve. And createRequire uses CJS resolution which cannot follow
+  // ESM-only subpath exports, producing false warnings (TIM-1348 review).
+}
+
 /**
  * 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

package/src/cli-schema-sync.ts

@@ -8,9 +8,9 @@
 
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { scanRoutes } from './routing/scanner.js';
-import type { SegmentNode } from './routing/types.js';
-import { resolveAppDir } from './plugin-context.js';
+import { scanRoutes } from './routing/scanner.ts';
+import type { SegmentNode } from './routing/types.ts';
+import { resolveAppDir } from './plugin-context.ts';
 
 function toBracketKey(node: SegmentNode): string {
   if (node.paramPrefix || node.paramSuffix) return `[${node.paramName}]`;

package/src/cli.ts

@@ -10,14 +10,15 @@
 //   timber build    — Run multi-environment build via createBuilder/buildApp
 //   timber preview  — Serve the production build
 //   timber check    — Validate types + routes without building
+//   timber graph    — Classify a file's module environment(s) (design/47)
 
 // Type-only — the implementation is imported dynamically inside runCheck so the
 // CLI's other commands never load the route scanner.
-import type { CheckDeps } from './cli-check.js';
+import type { CheckDeps } from './cli-check.ts';
 
 export type { CheckDeps };
 
-const COMMANDS = ['dev', 'build', 'preview', 'check', 'schema', 'init'] as const;
+const COMMANDS = ['dev', 'build', 'preview', 'check', 'schema', 'init', 'graph'] as const;
 type Command = (typeof COMMANDS)[number];
 
 export interface ParsedArgs {
@@ -25,7 +26,11 @@ export interface ParsedArgs {
   config: string | undefined;
   /** `--project`: the tsconfig `timber check` passes to tsgo. */
   project: string | undefined;
-  /** Positional arguments after the command (used by `timber schema sync`). */
+  /** `timber graph` only: emit the machine-readable JSON contract. */
+  json: boolean;
+  /** `timber graph` only: classify the whole project. */
+  all: boolean;
+  /** Positional arguments after the command (`schema sync`, `graph <file>`). */
   rest: string[];
 }
 
@@ -54,11 +59,15 @@ export interface CommandOptions {
  * starting on the default port would contradict fail-loudly. The surface stays
  * deliberately small (design/11-platform.md §CLI); port selection goes through
  * the PORT env var or server.port in vite.config.ts.
+ *
+ * Each subcommand declares its exact flags (the `check --project` precedent,
+ * TIM-1332): `graph` additionally accepts a file positional plus `--json` and
+ * `--all`, and those two are rejected everywhere else.
  */
 export function parseArgs(args: string[]): ParsedArgs {
   if (args.length === 0) {
     throw new Error(
-      'No command provided. Usage: timber <dev|build|preview|check|schema|init> [--config <path>]'
+      'No command provided. Usage: timber <dev|build|preview|check|schema|init|graph> [--config <path>]'
     );
   }
 
@@ -69,6 +78,8 @@ export function parseArgs(args: string[]): ParsedArgs {
 
   let config: string | undefined;
   let project: string | undefined;
+  let json = false;
+  let all = false;
   const rest: string[] = [];
   for (let i = 1; i < args.length; i++) {
     const arg = args[i];
@@ -77,6 +88,14 @@ export function parseArgs(args: string[]): ParsedArgs {
       if (!config) {
         throw new Error('--config requires a path argument');
       }
+    } else if (arg === '--json' || arg === '--all') {
+      if (command !== 'graph') {
+        throw new Error(
+          `${arg} is only valid for \`timber graph\` (the module-environment query).`
+        );
+      }
+      if (arg === '--json') json = true;
+      else all = true;
     } else if (arg === '--project') {
       if (command !== 'check') {
         throw new Error(
@@ -98,14 +117,20 @@ export function parseArgs(args: string[]): ParsedArgs {
         `Unknown option: ${arg}. The timber CLI accepts --config <path>` +
           ` (and --project <path> for \`check\`).${portHint}`
       );
-    } else if (command === 'schema' || command === 'init') {
+    } else if (command === 'schema' || command === 'init' || command === 'graph') {
       rest.push(arg);
     } else {
       throw new Error(`Unexpected argument: ${arg}. Usage: timber ${command} [--config <path>]`);
     }
   }
 
-  return { command: command as Command, config, project, rest };
+  if (command === 'graph' && rest.length > 1) {
+    throw new Error(
+      `timber graph takes one file. Usage: timber graph <file> [--json], or timber graph --all --json`
+    );
+  }
+
+  return { command: command as Command, config, project, json, all, rest };
 }
 
 // ─── Command Implementations ─────────────────────────────────────────────────
@@ -153,7 +178,7 @@ export async function runBuild(options: CommandOptions, _deps?: ViteDeps): Promi
  * Exported for testing — the actual runPreview function uses this internally.
  */
 export function resolvePreviewStrategy(
-  adapter: import('./adapters/types').TimberPlatformAdapter | undefined
+  adapter: import('./adapters/types.ts').TimberPlatformAdapter | undefined
 ): 'adapter' | 'vite' {
   if (adapter && typeof adapter.preview === 'function') {
     return 'adapter';
@@ -172,11 +197,13 @@ export function resolvePreviewStrategy(
  * Vite preview. See TIM-1066.
  */
 export async function runPreview(options: CommandOptions, _deps?: ViteDeps): Promise<void> {
-  const { loadTimberConfigFile, resolveBuildDir } = await import('./plugin-context.js');
+  const { loadTimberConfigFile, resolveBuildDir } = await import('./plugin-context.ts');
 
   const root = process.cwd();
   const config = loadTimberConfigFile(root);
-  const adapter = config?.adapter as import('./adapters/types').TimberPlatformAdapter | undefined;
+  const adapter = config?.adapter as
+    | import('./adapters/types.ts').TimberPlatformAdapter
+    | undefined;
 
   if (resolvePreviewStrategy(adapter) === 'adapter') {
     const buildDir = resolveBuildDir(root, config?.buildDir);
@@ -208,7 +235,7 @@ export async function runPreview(options: CommandOptions, _deps?: ViteDeps): Pro
  * `--project` names the tsconfig handed to tsgo.
  */
 export async function runCheck(options: CommandOptions, _deps?: CheckDeps): Promise<void> {
-  const { checkRoutes, runTypeCheck } = await import('./cli-check.js');
+  const { checkRoutes, runTypeCheck } = await import('./cli-check.ts');
   const { root } = await checkRoutes({ viteConfigFile: options.config }, _deps);
   // tsgo runs from the root the route pass resolved, not from cwd — that is
   // where it just wrote the declarations tsgo has to read.
@@ -232,7 +259,7 @@ export async function runSchema(args: string[]): Promise<void> {
     );
   }
 
-  const { runSchemaSync, defaultCodecForSegment } = await import('./cli-schema-sync.js');
+  const { runSchemaSync, defaultCodecForSegment } = await import('./cli-schema-sync.ts');
   const result = runSchemaSync(process.cwd());
 
   if (result.filesystemSegments.length === 0) {
@@ -361,6 +388,18 @@ async function main(): Promise<void> {
     case 'init':
       await runInit();
       break;
+    case 'graph': {
+      // Lazy import — the graph implementation (and, on a cache miss,
+      // Vite + the crawl child) never loads for the other commands.
+      const { runGraph } = await import('./analyze/graph-command.ts');
+      await runGraph({
+        file: parsed.rest[0],
+        config: parsed.config,
+        json: parsed.json,
+        all: parsed.all,
+      });
+      break;
+    }
   }
 }
 

package/src/client/browser-dev.ts

@@ -8,7 +8,7 @@
  * See design/21-dev-server.md §"HMR Wiring"
  */
 
-import { isPageUnloading } from './unload-guard.js';
+import { isPageUnloading } from './unload-guard.ts';
 
 // ─── HMR Hot Interface ──────────────────────────────────────────────
 

package/src/client/browser-entry/action-dispatch.ts

@@ -14,12 +14,12 @@
  * See design/08-forms-and-actions.md §"Client-Side Form Mechanics"
  */
 
-import { setServerCallback, encodeReply, createFromFetch } from '../../rsc-runtime/browser.js';
+import { setServerCallback, encodeReply, createFromFetch } from '../../rsc-runtime/browser.ts';
 import { getRouter, getRouterOrNull } from '#client-internal';
-import { setHardNavigating } from '../navigation-root.js';
-import { getClientDeploymentId, DEPLOYMENT_ID_HEADER, RELOAD_HEADER } from '../rsc-fetch.js';
-import { markClientStale } from '../stale-client.js';
-import { RSC_CONTENT_TYPE } from '../../shared/rsc-media-type.js';
+import { setHardNavigating } from '../navigation-root.tsx';
+import { getClientDeploymentId, DEPLOYMENT_ID_HEADER, RELOAD_HEADER } from '../rsc-fetch.ts';
+import { markClientStale } from '../stale-client.ts';
+import { RSC_CONTENT_TYPE } from '../../shared/rsc-media-type.ts';
 export function setupServerActions(): void {
   setServerCallback(async (id: string, args: unknown[]) => {
     const body = await encodeReply(args);

package/src/client/browser-entry/hmr.ts

@@ -16,7 +16,7 @@ import {
   setupClientErrorForwarding,
   showCompilingOverlay,
   hideCompilingOverlay,
-} from '../browser-dev.js';
+} from '../browser-dev.ts';
 
 type HotApi = {
   on(event: string, cb: (...args: unknown[]) => void): void;