@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.180

package/src/cli-schema-sync.ts

@@ -0,0 +1,401 @@
+/**
+ * `timber schema sync` — scan filesystem for dynamic segments, append
+ * missing entries with `codec.string` defaults, and remove stale entries
+ * whose segments no longer exist in the filesystem.
+ *
+ * Design doc: design/41-global-params.md §Auto-Scaffolding
+ */
+
+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';
+
+function toBracketKey(node: SegmentNode): string {
+  if (node.paramPrefix || node.paramSuffix) return `[${node.paramName}]`;
+  switch (node.segmentType) {
+    case 'catch-all':
+      return `[...${node.paramName}]`;
+    case 'optional-catch-all':
+      return `[[...${node.paramName}]]`;
+    default:
+      return `[${node.paramName}]`;
+  }
+}
+
+/**
+ * Collect all unique bracket-keyed dynamic segment names from the route tree.
+ * Returns entries like '[artistSlug]', '[...slug]', '[[...topic]]'.
+ */
+export function collectDynamicSegments(appDir: string): string[] {
+  const tree = scanRoutes(appDir);
+  const segments = new Set<string>();
+  walkSegments(tree.root, segments);
+  return [...segments].sort();
+}
+
+function walkSegments(node: SegmentNode, segments: Set<string>): void {
+  if (node.paramName) {
+    // Use bare bracket form for schema keys — affixed segments like
+    // `img-[id].png` register as `[id]`, matching runtime codec lookup.
+    segments.add(toBracketKey(node));
+  }
+  for (const child of node.children) {
+    walkSegments(child, segments);
+  }
+  for (const slot of Object.values(node.slots)) {
+    walkSegments(slot, segments);
+  }
+}
+
+/**
+ * Replace comment bodies (and optionally string contents) with spaces,
+ * preserving length and newlines so every index maps 1:1 to the original.
+ * Lets the structural scanning below ignore `segmentParams` mentions and
+ * braces inside comments/strings without a TS parser (fine pre-alpha,
+ * see TIM-1066).
+ *
+ * With `maskStrings`, string contents are blanked too — except literal
+ * 'segmentParams' strings, kept so a quoted property key stays findable.
+ */
+function maskSource(content: string, maskStrings: boolean): string {
+  const out = content.split('');
+  const n = content.length;
+  let i = 0;
+
+  const blank = (from: number, to: number): void => {
+    for (let j = from; j < to; j++) {
+      if (content[j] !== '\n') out[j] = ' ';
+    }
+  };
+
+  while (i < n) {
+    const ch = content[i];
+    const next = content[i + 1];
+    if (ch === '/' && next === '/') {
+      const start = i;
+      while (i < n && content[i] !== '\n') i++;
+      blank(start, i);
+    } else if (ch === '/' && next === '*') {
+      const start = i;
+      i += 2;
+      while (i < n && !(content[i] === '*' && content[i + 1] === '/')) i++;
+      i = Math.min(i + 2, n);
+      blank(start, i);
+    } else if (ch === '"' || ch === "'" || ch === '`') {
+      const start = i;
+      i++;
+      while (i < n && content[i] !== ch) {
+        if (content[i] === '\\') i++;
+        i++;
+      }
+      const end = i; // at closing quote (or n if unterminated)
+      if (maskStrings && content.slice(start + 1, end) !== 'segmentParams') {
+        blank(start + 1, end);
+      }
+      i++;
+    } else {
+      i++;
+    }
+  }
+  return out.join('');
+}
+
+/**
+ * Locate the `segmentParams: { ... }` block in a schema file.
+ * Returns the indices of the opening and matching closing brace, or null
+ * if no segmentParams property is found. Comments and strings are masked
+ * first, so a JSDoc example mentioning `segmentParams: { ... }` above the
+ * real defineSchema call is not mistaken for the block, and braces inside
+ * comments/strings don't skew the depth count. The search is anchored to
+ * the `defineSchema(` call when present, so helper objects with their own
+ * segmentParams property earlier in the file are skipped.
+ */
+export function findSegmentParamsBlock(
+  content: string
+): { openBrace: number; closeBrace: number } | null {
+  const masked = maskSource(content, true);
+
+  const defineCall = /\bdefineSchema\s*\(/.exec(masked);
+  const keyRe = /(['"]?)segmentParams\1\s*:\s*\{/g;
+  keyRe.lastIndex = defineCall ? defineCall.index + defineCall[0].length : 0;
+  const keyMatch = keyRe.exec(masked);
+  if (!keyMatch) return null;
+
+  const openBrace = keyMatch.index + keyMatch[0].length - 1;
+  let depth = 1;
+  let i = openBrace + 1;
+  while (i < masked.length && depth > 0) {
+    if (masked[i] === '{') depth++;
+    else if (masked[i] === '}') depth--;
+    i++;
+  }
+  if (depth > 0) return null;
+  // i now points to just after the closing brace
+  return { openBrace, closeBrace: i - 1 };
+}
+
+/**
+ * Parse existing bracket keys from an app/schema.ts file.
+ * Scoped to the segmentParams: { ... } block — bracket keys elsewhere in
+ * the file (unrelated objects, comments above defineSchema) are ignored.
+ * Comments inside the block are masked, so a commented-out entry does not
+ * count as registered.
+ *
+ * The key charset matches the route classifier (segment-classify.ts):
+ * any character except `]`, so hyphenated params like '[my-param]' parse.
+ */
+export function parseExistingSchemaKeys(content: string): string[] {
+  const block = findSegmentParamsBlock(content);
+  if (!block) return [];
+
+  const blockContent = maskSource(content, false).slice(block.openBrace, block.closeBrace);
+  const keys: string[] = [];
+  // Match quoted bracket keys like '[artistSlug]', '[...slug]', '[[...topic]]'
+  const re = /['"](\[{1,2}(?:\.{3})?[^\]]+\]{1,2})['"]\s*:/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(blockContent)) !== null) {
+    keys.push(m[1]);
+  }
+  return keys;
+}
+
+/** Schema file extensions to check. */
+const SCHEMA_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
+
+/**
+ * Find the schema file path if it exists.
+ */
+export function findSchemaFile(appDir: string): string | undefined {
+  for (const ext of SCHEMA_EXTENSIONS) {
+    const p = join(appDir, `schema${ext}`);
+    if (existsSync(p)) return p;
+  }
+  return undefined;
+}
+
+export function defaultCodecForSegment(seg: string): string {
+  if (seg.startsWith('[[...')) return 'codec.optionalCatchAll(codec.string)';
+  if (seg.startsWith('[...')) return 'codec.stringArray';
+  return 'codec.string';
+}
+
+/**
+ * Generate the content for a new app/schema.ts with the given segment keys.
+ */
+function generateNewSchema(segments: string[]): string {
+  const lines: string[] = [];
+  lines.push("import { defineSchema } from '@timber-js/app/params';");
+  lines.push("import { codec } from '@timber-js/app/codec';");
+  lines.push('');
+  lines.push('export default defineSchema({');
+  lines.push('  segmentParams: {');
+  for (const seg of segments) {
+    lines.push(`    '${seg}': ${defaultCodecForSegment(seg)},`);
+  }
+  lines.push('  },');
+  lines.push('});');
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Append missing segment entries to an existing schema file.
+ * Inserts new entries before the closing `}` of segmentParams.
+ */
+const CODEC_IMPORT = "import { codec } from '@timber-js/app/codec';";
+
+function hasCodecImport(content: string): boolean {
+  return /import\s+\{[^}]*\bcodec\b[^}]*\}\s+from\s+['"]@timber-js\/app\/codec['"]/.test(content);
+}
+
+function ensureCodecImport(content: string): string {
+  if (hasCodecImport(content)) return content;
+
+  // Insert after the last existing import statement
+  const lines = content.split('\n');
+  let lastImportIndex = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^\s*import\s/.test(lines[i])) lastImportIndex = i;
+  }
+
+  if (lastImportIndex === -1) {
+    return CODEC_IMPORT + '\n' + content;
+  }
+
+  lines.splice(lastImportIndex + 1, 0, CODEC_IMPORT);
+  return lines.join('\n');
+}
+
+function appendToSchema(content: string, newSegments: string[]): string {
+  content = ensureCodecImport(content);
+
+  const block = findSegmentParamsBlock(content);
+  if (!block) {
+    throw new Error(
+      '[timber] Could not find segmentParams in schema file. ' +
+        'Expected a defineSchema({ segmentParams: { ... } }) call.'
+    );
+  }
+  const { openBrace, closeBrace } = block;
+
+  // Detect indentation from existing entries
+  const existingLine = content.slice(openBrace, closeBrace).match(/^(\s+)['"]\[/m);
+  const indent = existingLine ? existingLine[1] : '    ';
+
+  // Build insertion text
+  const insertion = newSegments
+    .map((seg) => `${indent}'${seg}': ${defaultCodecForSegment(seg)},`)
+    .join('\n');
+
+  // Insert before the closing brace
+  const before = content.slice(0, closeBrace);
+  const after = content.slice(closeBrace);
+
+  // Add newline if the content before doesn't end with one
+  const separator = before.trimEnd().endsWith(',') ? '\n' : '\n';
+
+  return before + separator + insertion + '\n' + after;
+}
+
+/**
+ * Remove entries from the segmentParams block whose keys match `staleSegments`.
+ * Removes the entire entry including trailing comma/whitespace. Scoped to
+ * the segmentParams block — identical keys in unrelated objects elsewhere
+ * in the file are left untouched.
+ */
+function removeFromSchema(content: string, staleSegments: string[]): string {
+  const block = findSegmentParamsBlock(content);
+  if (!block) return content;
+
+  let blockContent = content.slice(block.openBrace, block.closeBrace);
+  // Key matching and the entry walk run on a comment-masked copy (same
+  // length, indices align) so commented-out entries are never removed.
+  // Both copies are spliced in sync to keep indices valid.
+  let blockMasked = maskSource(blockContent, false);
+
+  for (const seg of staleSegments) {
+    const escaped = seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const keyRe = new RegExp(`^[ \t]*['"]${escaped}['"][ \t]*:`, 'gm');
+    let m: RegExpExecArray | null;
+    while ((m = keyRe.exec(blockMasked)) !== null) {
+      const start = m.index;
+      let i = m.index + m[0].length;
+      let depth = 0;
+      let inString: string | null = null;
+
+      while (i < blockMasked.length) {
+        const ch = blockMasked[i];
+        if (inString) {
+          if (ch === '\\') {
+            i++;
+          } else if (ch === inString) {
+            inString = null;
+          }
+        } else if (ch === '"' || ch === "'" || ch === '`') {
+          inString = ch;
+        } else if (ch === '(' || ch === '{' || ch === '[') {
+          depth++;
+        } else if (ch === ')' || ch === '}' || ch === ']') {
+          depth--;
+        } else if (depth === 0 && ch === ',') {
+          i++;
+          break;
+        } else if (depth === 0 && (ch === '\n' || ch === '}')) {
+          break;
+        }
+        i++;
+      }
+
+      // Consume trailing newline
+      if (i < blockMasked.length && blockMasked[i] === '\n') i++;
+
+      blockContent = blockContent.slice(0, start) + blockContent.slice(i);
+      blockMasked = blockMasked.slice(0, start) + blockMasked.slice(i);
+      keyRe.lastIndex = start;
+    }
+  }
+
+  return content.slice(0, block.openBrace) + blockContent + content.slice(block.closeBrace);
+}
+
+export interface SchemaSyncResult {
+  /** Segments found in the filesystem. */
+  filesystemSegments: string[];
+  /** Segments already defined in app/schema.ts. */
+  existingSegments: string[];
+  /** Segments that were added. */
+  addedSegments: string[];
+  /** Segments that were removed (no longer in filesystem). */
+  removedSegments: string[];
+  /** Whether a new schema file was created. */
+  created: boolean;
+}
+
+/**
+ * Run the schema sync: scan filesystem, diff against schema, append missing.
+ */
+export function runSchemaSync(projectRoot: string): SchemaSyncResult {
+  const appDir = resolveAppDir(projectRoot);
+
+  const filesystemSegments = collectDynamicSegments(appDir);
+
+  const schemaPath = findSchemaFile(appDir);
+
+  if (filesystemSegments.length === 0 && !schemaPath) {
+    return {
+      filesystemSegments: [],
+      existingSegments: [],
+      addedSegments: [],
+      removedSegments: [],
+      created: false,
+    };
+  }
+
+  if (!schemaPath) {
+    // Create new schema file
+    const newPath = join(appDir, 'schema.ts');
+    writeFileSync(newPath, generateNewSchema(filesystemSegments), 'utf-8');
+    return {
+      filesystemSegments,
+      existingSegments: [],
+      addedSegments: filesystemSegments,
+      removedSegments: [],
+      created: true,
+    };
+  }
+
+  // Read existing schema and diff
+  const content = readFileSync(schemaPath, 'utf-8');
+  const existingSegments = parseExistingSchemaKeys(content);
+  const missing = filesystemSegments.filter((seg) => !existingSegments.includes(seg));
+  const stale = existingSegments.filter((seg) => !filesystemSegments.includes(seg));
+
+  if (missing.length === 0 && stale.length === 0) {
+    return {
+      filesystemSegments,
+      existingSegments,
+      addedSegments: [],
+      removedSegments: [],
+      created: false,
+    };
+  }
+
+  let updated = content;
+  if (stale.length > 0) {
+    updated = removeFromSchema(updated, stale);
+  }
+  if (missing.length > 0) {
+    updated = appendToSchema(updated, missing);
+  }
+  writeFileSync(schemaPath, updated, 'utf-8');
+
+  return {
+    filesystemSegments,
+    existingSegments,
+    addedSegments: missing,
+    removedSegments: stale,
+    created: false,
+  };
+}

package/src/cli.ts

@@ -11,12 +11,14 @@
 //   timber preview  — Serve the production build
 //   timber check    — Validate types + routes without building
 
-const COMMANDS = ['dev', 'build', 'preview', 'check'] as const;
+const COMMANDS = ['dev', 'build', 'preview', 'check', 'schema', 'init'] as const;
 type Command = (typeof COMMANDS)[number];
 
 export interface ParsedArgs {
   command: Command;
   config: string | undefined;
+  /** Positional arguments after the command (used by `timber schema sync`). */
+  rest: string[];
 }
 
 export interface CommandOptions {
@@ -26,11 +28,16 @@ export interface CommandOptions {
 /**
  * Parse CLI arguments into a structured command + options.
  * Accepts: timber <command> [--config|-c <path>]
+ *
+ * Unknown flags are an error, not silently ignored — `timber dev --port 4000`
+ * starting on the default port would contradict fail-loudly. The CLI surface
+ * is intentionally --config-only (design/11-platform.md §CLI); port selection
+ * goes through the PORT env var or server.port in vite.config.ts.
  */
 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> [--config <path>]'
     );
   }
 
@@ -40,16 +47,31 @@ export function parseArgs(args: string[]): ParsedArgs {
   }
 
   let config: string | undefined;
+  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.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 only accepts --config <path>.${portHint}`
+      );
+    } else if (command === 'schema' || command === 'init') {
+      rest.push(arg);
+    } else {
+      throw new Error(`Unexpected argument: ${arg}. Usage: timber ${command} [--config <path>]`);
     }
   }
 
-  return { command: command as Command, config };
+  return { command: command as Command, config, rest };
 }
 
 // ─── Command Implementations ─────────────────────────────────────────────────
@@ -63,7 +85,12 @@ export interface ViteDeps {
 
 /**
  * Start the Vite dev server.
- * Middleware re-runs on file change via HMR wiring in timber-routing.
+ *
+ * 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.
  */
 export async function runDev(options: CommandOptions, _deps?: ViteDeps): Promise<void> {
   const createServer = _deps?.createServer ?? (await import('vite')).createServer;
@@ -100,46 +127,25 @@ export function resolvePreviewStrategy(
   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.
+ *
+ * Uses the same loadTimberConfigFile loader as dev/build — one loader,
+ * one set of module semantics. A config file that exists but fails to
+ * load throws (naming the file) instead of silently degrading to plain
+ * Vite preview. See TIM-1066.
  */
 export async function runPreview(options: CommandOptions, _deps?: ViteDeps): Promise<void> {
-  const { join } = await import('node:path');
+  const { loadTimberConfigFile, resolveBuildDir } = await import('./plugin-context.js');
 
-  // Try to load timber config for adapter-specific preview
   const root = process.cwd();
-  const config = await loadTimberConfig(root).catch(() => null);
+  const config = loadTimberConfigFile(root);
   const adapter = config?.adapter as import('./adapters/types').TimberPlatformAdapter | undefined;
 
   if (resolvePreviewStrategy(adapter) === 'adapter') {
-    const buildDir = join(root, 'dist');
+    const buildDir = resolveBuildDir(root, config?.buildDir);
     const timberConfig = { output: (config?.output ?? 'server') as 'server' | 'static' };
     await adapter!.preview!(timberConfig, buildDir);
     return;
@@ -174,6 +180,127 @@ export async function runCheck(options: CommandOptions): Promise<void> {
   });
 }
 
+// ─── 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.js');
+  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> {
@@ -193,6 +320,12 @@ async function main(): Promise<void> {
     case 'check':
       await runCheck(options);
       break;
+    case 'schema':
+      await runSchema(parsed.rest);
+      break;
+    case 'init':
+      await runInit();
+      break;
   }
 }