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

package/src/cli.ts

@@ -10,27 +10,65 @@
 //   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)
 
-const COMMANDS = ['dev', 'build', 'preview', 'check'] as const;
+// 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.ts';
+import type { ResolveViteConfig } from './cli-context.ts';
+
+export type { CheckDeps };
+
+const COMMANDS = ['dev', 'build', 'preview', 'check', 'schema', 'init', 'graph'] as const;
 type Command = (typeof COMMANDS)[number];
 
 export interface ParsedArgs {
   command: Command;
   config: string | undefined;
+  /** `--project`: the tsconfig `timber check` passes to tsgo. */
+  project: string | undefined;
+  /** `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[];
 }
 
 export interface CommandOptions {
+  /** Path to a Vite config file. Means the same thing for every command. */
   config?: string;
+  /** `timber check` only: the tsconfig to type-check. */
+  project?: string;
 }
 
 /**
  * Parse CLI arguments into a structured command + options.
- * Accepts: timber <command> [--config|-c <path>]
+ * Accepts: timber <command> [--config|-c <path>] [--project <path>]
+ *
+ * `--config` names a **Vite** config file for every command, `check` included
+ * (TIM-1332): `check` resolves the project through Vite, so a project that
+ * builds with `--config ./custom.vite.config.ts` has to be checkable the same
+ * way. `--project` names the tsconfig, spelled as tsgo and tsc spell it, and
+ * is meaningful only for `check`.
+ *
+ * Before TIM-1332 `--config` meant the tsconfig for `check` alone — one flag
+ * with two meanings, which the docs had to carry a note to explain and which
+ * left custom Vite configs unreachable from `check` entirely.
+ *
+ * Unknown flags are an error, not silently ignored — `timber dev --port 4000`
+ * 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> [--config <path>]'
+      'No command provided. Usage: timber <dev|build|preview|check|schema|init|graph> [--config <path>]'
     );
   }
 
@@ -40,16 +78,60 @@ 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++) {
-    if (args[i] === '--config' || args[i] === '-c') {
+    const arg = args[i];
+    if (arg === '--config' || arg === '-c') {
       config = args[++i];
       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(
+          `--project is only valid for \`timber check\` (it names the tsconfig to type-check). ` +
+            `To point \`timber ${command}\` at a different Vite config, use --config <path>.`
+        );
+      }
+      project = args[++i];
+      if (!project) {
+        throw new Error('--project requires a path argument');
+      }
+    } else if (arg.startsWith('-')) {
+      const portHint =
+        arg === '--port' || arg === '-p'
+          ? ' To change the port, set the PORT environment variable (PORT=4000 timber dev) ' +
+            'or server.port in vite.config.ts.'
+          : '';
+      throw new Error(
+        `Unknown option: ${arg}. The timber CLI accepts --config <path>` +
+          ` (and --project <path> for \`check\`).${portHint}`
+      );
+    } 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 };
+  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 ─────────────────────────────────────────────────
@@ -59,19 +141,79 @@ export interface ViteDeps {
   createServer?: typeof import('vite').createServer;
   createBuilder?: typeof import('vite').createBuilder;
   preview?: typeof import('vite').preview;
+  resolveViteConfig?: ResolveViteConfig;
 }
 
 /**
- * Start the Vite dev server.
- * Middleware re-runs on file change via HMR wiring in timber-routing.
+ * Start the Vite dev server with a supervisor that respawns the process
+ * when timber.config.ts changes. Node's require cache for ESM modules
+ * loaded via require() cannot be evicted, so an in-process restart
+ * serves stale config. The supervisor forks a worker; when the worker
+ * exits with RESTART_EXIT_CODE (set by timber-dev-server on config file
+ * change), the supervisor spawns a fresh worker with a clean cache.
+ *
+ * The timber plugin binds the port immediately with a holding page
+ * (in rootSync's config hook) so browsers see a "starting..." page
+ * instead of ERR_CONNECTION_REFUSED during initialization.
+ *
+ * See design/21-dev-server.md, TIM-665, TIM-1444.
  */
 export async function runDev(options: CommandOptions, _deps?: ViteDeps): Promise<void> {
-  const createServer = _deps?.createServer ?? (await import('vite')).createServer;
-  const server = await createServer({
-    configFile: options.config,
-  });
-  await server.listen();
-  server.printUrls();
+  // Worker mode: run the dev server directly (forked by supervisor below)
+  if (process.env.__TIMBER_DEV_WORKER) {
+    const createServer = _deps?.createServer ?? (await import('vite')).createServer;
+    const server = await createServer({
+      configFile: options.config,
+    });
+    await server.listen();
+    server.printUrls();
+    return;
+  }
+
+  // Supervisor mode: fork a worker and respawn on config changes.
+  const { fork } = await import('node:child_process');
+  const { RESTART_EXIT_CODE } = await import('./plugins/dev-server.ts');
+
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const result = await new Promise<{ code: number | null; signal: NodeJS.Signals | null }>(
+      (resolve) => {
+        const child = fork(process.argv[1], process.argv.slice(2), {
+          stdio: 'inherit',
+          env: { ...process.env, __TIMBER_DEV_WORKER: '1' },
+        });
+
+        // Forward signals to the child. SIGINT from Ctrl+C is sent to
+        // the entire process group, but a targeted SIGTERM (from a
+        // process manager or test teardown) only reaches the parent.
+        const onSigint = () => child.kill('SIGINT');
+        const onSigterm = () => child.kill('SIGTERM');
+        process.on('SIGINT', onSigint);
+        process.on('SIGTERM', onSigterm);
+
+        child.on('exit', (code, signal) => {
+          process.off('SIGINT', onSigint);
+          process.off('SIGTERM', onSigterm);
+          resolve({ code, signal });
+        });
+      }
+    );
+
+    if (result.code === RESTART_EXIT_CODE) {
+      continue;
+    }
+
+    // Child was killed by a signal (e.g. SIGTERM) — re-raise on ourselves
+    if (result.signal) {
+      process.kill(process.pid, result.signal);
+    }
+
+    if (result.code != null && result.code !== 0) {
+      process.exit(result.code);
+    }
+
+    break;
+  }
 }
 
 /**
@@ -87,61 +229,31 @@ export async function runBuild(options: CommandOptions, _deps?: ViteDeps): Promi
   await builder.buildApp();
 }
 
-/**
- * Determine whether to use the adapter's preview or Vite's built-in preview.
- * Exported for testing — the actual runPreview function uses this internally.
- */
-export function resolvePreviewStrategy(
-  adapter: import('./adapters/types').TimberPlatformAdapter | undefined
-): 'adapter' | 'vite' {
-  if (adapter && typeof adapter.preview === 'function') {
-    return 'adapter';
-  }
-  return 'vite';
-}
-
-/**
- * Load timber.config.ts from the project root.
- * Returns the config object with adapter, output, etc.
- * Returns null if no config file is found.
- */
-async function loadTimberConfig(
-  root: string
-): Promise<{ adapter?: import('./adapters/types').TimberPlatformAdapter; output?: string } | null> {
-  const { existsSync } = await import('node:fs');
-  const { join } = await import('node:path');
-  const { pathToFileURL } = await import('node:url');
-
-  const configNames = ['timber.config.ts', 'timber.config.js', 'timber.config.mjs'];
-
-  for (const name of configNames) {
-    const configPath = join(root, name);
-    if (existsSync(configPath)) {
-      // Use Vite's built-in config loading to handle TypeScript
-      const mod = await import(pathToFileURL(configPath).href);
-      return mod.default ?? mod;
-    }
-  }
-  return null;
-}
-
 /**
  * Serve the production build for local testing.
  * If the adapter provides a preview() method, it takes priority.
  * Otherwise falls back to Vite's built-in preview server.
+ *
+ * The project is resolved through Vite, as `timber check` resolves it
+ * (`cli-context.ts`), so the adapter, the output mode, and the build
+ * directory are the ones `timber build` used — including `--config`, inline
+ * `timber({ ... })` options, Vite's `root`, and `build.outDir`, none of which
+ * a re-read of `timber.config.ts` can see (TIM-1531). A config file that
+ * exists but fails to load throws (naming the file) instead of silently
+ * degrading to plain Vite preview (TIM-1066).
  */
 export async function runPreview(options: CommandOptions, _deps?: ViteDeps): Promise<void> {
-  const { join } = await import('node:path');
+  const { resolveTimberContext } = await import('./cli-context.ts');
+  const { adapterConfig, contextAdapter } = await import('./plugin-context.ts');
 
-  // Try to load timber config for adapter-specific preview
-  const root = process.cwd();
-  const config = await loadTimberConfig(root).catch(() => null);
-  const adapter = config?.adapter as import('./adapters/types').TimberPlatformAdapter | undefined;
+  const ctx = await resolveTimberContext('preview', options.config, _deps?.resolveViteConfig);
+  const adapter = contextAdapter(ctx);
 
-  if (resolvePreviewStrategy(adapter) === 'adapter') {
-    const buildDir = join(root, 'dist');
-    const timberConfig = { output: (config?.output ?? 'server') as 'server' | 'static' };
-    await adapter!.preview!(timberConfig, buildDir);
+  if (typeof adapter?.preview === 'function') {
+    await adapter.preview(adapterConfig(ctx), {
+      output: ctx.config.output ?? 'server',
+      outputDir: ctx.buildDir,
+    });
     return;
   }
 
@@ -154,31 +266,153 @@ export async function runPreview(options: CommandOptions, _deps?: ViteDeps): Pro
 }
 
 /**
- * Validate types and routes without producing build output.
- * Runs tsgo --noEmit for type checking.
+ * Validate routes and types without producing build output.
+ *
+ * Runs the route pass first — resolve the project through Vite, scan it, fail
+ * on proven-fatal convention errors, print warnings, and regenerate the route
+ * types — then `tsgo --noEmit`. Codegen has to precede the type pass: the
+ * generated `.timber/*.d.ts` files are what type `<Link href>` and
+ * `useSegmentParams()`, and a fresh clone has never produced them. See
+ * `cli-check.ts` for the full reasoning.
+ *
+ * `--config` names the **Vite** config, as it does for every other command, so
+ * an app that builds with a custom one is checkable the same way.
+ * `--project` names the tsconfig handed to tsgo.
  */
-export async function runCheck(options: CommandOptions): Promise<void> {
-  const { execFile } = await import('node:child_process');
-
-  await new Promise<void>((resolve, reject) => {
-    const configArgs = options.config ? ['--project', options.config] : [];
-    execFile('tsgo', ['--noEmit', ...configArgs], (err, stdout, stderr) => {
-      if (stdout) process.stdout.write(stdout);
-      if (stderr) process.stderr.write(stderr);
-      if (err) {
-        reject(new Error(`Type check failed with exit code ${err.code}`));
-      } else {
-        resolve();
-      }
-    });
-  });
+export async function runCheck(options: CommandOptions, _deps?: CheckDeps): Promise<void> {
+  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.
+  await runTypeCheck({ root, config: options.project }, _deps);
+}
+
+// ─── Schema Subcommand ───────────────────────────────────────────────────────
+
+/**
+ * `timber schema sync` — scan filesystem for dynamic segments, diff against
+ * app/schema.ts, and append missing entries with type-appropriate codec defaults.
+ *
+ * See design/41-global-params.md §Auto-Scaffolding
+ */
+export async function runSchema(args: string[]): Promise<void> {
+  const subcommand = args[0];
+
+  if (subcommand !== 'sync') {
+    throw new Error(
+      `Unknown schema subcommand: ${subcommand ?? '(none)'}. Usage: timber schema sync`
+    );
+  }
+
+  const { runSchemaSync, defaultCodecForSegment } = await import('./cli-schema-sync.ts');
+  const result = runSchemaSync(process.cwd());
+
+  if (result.filesystemSegments.length === 0) {
+    console.log('[timber] No dynamic segments found in app/.');
+    return;
+  }
+
+  if (result.created) {
+    console.log(`[timber] Created app/schema.ts with ${result.addedSegments.length} segment(s):`);
+    for (const seg of result.addedSegments) {
+      console.log(`  + ${seg}: ${defaultCodecForSegment(seg)}`);
+    }
+    return;
+  }
+
+  if (result.addedSegments.length === 0 && result.removedSegments.length === 0) {
+    console.log('[timber] Schema is up to date — all segments are registered.');
+    return;
+  }
+
+  if (result.addedSegments.length > 0) {
+    console.log(`[timber] Added ${result.addedSegments.length} segment(s) to app/schema.ts:`);
+    for (const seg of result.addedSegments) {
+      console.log(`  + ${seg}: ${defaultCodecForSegment(seg)}`);
+    }
+  }
+
+  if (result.removedSegments.length > 0) {
+    console.log(
+      `[timber] Removed ${result.removedSegments.length} stale segment(s) from app/schema.ts:`
+    );
+    for (const seg of result.removedSegments) {
+      console.log(`  - ${seg}`);
+    }
+  }
+}
+
+// ─── Init Subcommand ─────────────────────────────────────────────────────────
+
+/**
+ * `timber init` — write AGENTS.md (and a CLAUDE.md symlink to it) to the
+ * project root so AI coding agents can discover timber.js documentation and
+ * conventions.
+ *
+ * The content is read from the installed @timber-js/app package itself, so it
+ * stays in sync with the installed version.
+ */
+export async function runInit(): Promise<void> {
+  const { readFileSync, writeFileSync, existsSync, symlinkSync } = await import('node:fs');
+  const { resolve, dirname } = await import('node:path');
+  const { fileURLToPath } = await import('node:url');
+
+  const root = process.cwd();
+  const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+  const agentSkillPath = resolve(packageRoot, 'agent-skill.md');
+  if (!existsSync(agentSkillPath)) {
+    throw new Error(
+      'agent-skill.md not found in @timber-js/app package. ' +
+        'This may be a development install — try reinstalling.'
+    );
+  }
+
+  const agentSkill = readFileSync(agentSkillPath, 'utf-8');
+
+  const agentsPath = resolve(root, 'AGENTS.md');
+  const claudePath = resolve(root, 'CLAUDE.md');
+
+  const wrote: string[] = [];
+
+  if (existsSync(agentsPath)) {
+    console.log('[timber] AGENTS.md already exists — skipping (delete it first to regenerate)');
+  } else {
+    writeFileSync(agentsPath, agentSkill);
+    wrote.push('AGENTS.md');
+  }
+
+  if (existsSync(claudePath)) {
+    console.log('[timber] CLAUDE.md already exists — skipping (delete it first to regenerate)');
+  } else {
+    try {
+      // Relative target so the link survives the project directory moving.
+      // The 'file' type argument is required for Windows (ignored elsewhere).
+      symlinkSync('AGENTS.md', claudePath, 'file');
+      wrote.push('CLAUDE.md (symlink)');
+    } catch {
+      // Windows without Developer Mode or admin rights can't create symlinks
+      // (EPERM) — fall back to a plain pointer file.
+      writeFileSync(claudePath, 'Read AGENTS.md for project context and conventions.\n');
+      wrote.push('CLAUDE.md');
+    }
+  }
+
+  if (wrote.length > 0) {
+    console.log(
+      `[timber] Created ${wrote.join(' and ')} — AI agents can now discover timber.js docs.`
+    );
+    console.log('[timber] Full documentation: node_modules/@timber-js/app/docs/');
+  } else {
+    console.log('[timber] Nothing to do — both files already exist.');
+  }
 }
 
 // ─── Main Entry Point ────────────────────────────────────────────────────────
 
 async function main(): Promise<void> {
   const parsed = parseArgs(process.argv.slice(2));
-  const options: CommandOptions = { config: parsed.config };
+  const options: CommandOptions = { config: parsed.config, project: parsed.project };
 
   switch (parsed.command) {
     case 'dev':
@@ -193,6 +427,24 @@ async function main(): Promise<void> {
     case 'check':
       await runCheck(options);
       break;
+    case 'schema':
+      await runSchema(parsed.rest);
+      break;
+    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;
+    }
   }
 }