@timber-js/app 0.2.0-alpha.154 → 0.2.0-alpha.156

package/src/cli.ts

@@ -11,7 +11,7 @@
 //   timber preview  — Serve the production build
 //   timber check    — Validate types + routes without building
 
-const COMMANDS = ['dev', 'build', 'preview', 'check', 'schema'] as const;
+const COMMANDS = ['dev', 'build', 'preview', 'check', 'schema', 'init'] as const;
 type Command = (typeof COMMANDS)[number];
 
 export interface ParsedArgs {
@@ -37,7 +37,7 @@ export interface CommandOptions {
 export function parseArgs(args: string[]): ParsedArgs {
   if (args.length === 0) {
     throw new Error(
-      'No command provided. Usage: timber <dev|build|preview|check|schema> [--config <path>]'
+      'No command provided. Usage: timber <dev|build|preview|check|schema|init> [--config <path>]'
     );
   }
 
@@ -64,7 +64,7 @@ export function parseArgs(args: string[]): ParsedArgs {
       throw new Error(
         `Unknown option: ${arg}. The timber CLI only accepts --config <path>.${portHint}`
       );
-    } else if (command === 'schema') {
+    } else if (command === 'schema' || command === 'init') {
       rest.push(arg);
     } else {
       throw new Error(`Unexpected argument: ${arg}. Usage: timber ${command} [--config <path>]`);
@@ -235,6 +235,62 @@ export async function runSchema(args: string[]): Promise<void> {
   }
 }
 
+// ─── Init Subcommand ─────────────────────────────────────────────────────────
+
+/**
+ * `timber init` — write AGENTS.md (and CLAUDE.md pointer) 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 } = 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 {
+    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> {
@@ -257,6 +313,9 @@ async function main(): Promise<void> {
     case 'schema':
       await runSchema(parsed.rest);
       break;
+    case 'init':
+      await runInit();
+      break;
   }
 }
 

package/src/fonts/google.ts

@@ -21,6 +21,28 @@ import { join } from 'node:path';
 import type { ExtractedFont, FontFaceDescriptor } from './types.js';
 import { fontUrlPrefix } from './paths.js';
 
+/**
+ * Extract a recognizable error code (ETIMEDOUT, ENOTFOUND, etc.) from a
+ * network error's cause chain. Node's undici-based `fetch` wraps the
+ * system error inside `cause` (sometimes as an AggregateError).
+ */
+function extractNetworkErrorCode(err: unknown): string | undefined {
+  if (!(err instanceof Error)) return undefined;
+  const code = (err as NodeJS.ErrnoException).code;
+  if (code) return code;
+  const cause = (err as { cause?: unknown }).cause;
+  if (cause instanceof AggregateError) {
+    for (const inner of cause.errors) {
+      const innerCode = (inner as NodeJS.ErrnoException).code;
+      if (innerCode) return innerCode;
+    }
+  }
+  if (cause instanceof Error) {
+    return (cause as NodeJS.ErrnoException).code;
+  }
+  return undefined;
+}
+
 /** Google Fonts CSS API v2 base URL. */
 const GOOGLE_FONTS_API = 'https://fonts.googleapis.com/css2';
 
@@ -112,9 +134,20 @@ export function buildGoogleFontsUrl(font: ExtractedFont): string {
  * We parse each block to extract the font URL, unicode-range, and subset label.
  */
 export async function fetchGoogleFontsCss(url: string): Promise<GoogleFontFace[]> {
-  const response = await fetch(url, {
-    headers: { 'User-Agent': WOFF2_USER_AGENT },
-  });
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      headers: { 'User-Agent': WOFF2_USER_AGENT },
+    });
+  } catch (err) {
+    const code = extractNetworkErrorCode(err);
+    throw new Error(
+      `[timber] Failed to fetch Google Fonts CSS from ${url}` +
+        (code ? ` (${code})` : '') +
+        `. Build requires internet access for font optimization.` +
+        ` If building offline, set TIMBER_SKIP_FONTS=1 to skip font downloading.`
+    );
+  }
 
   if (!response.ok) {
     throw new Error(
@@ -205,7 +238,18 @@ export function cacheKey(face: GoogleFontFace): string {
  * Download a single font file from its URL.
  */
 export async function downloadFontFile(url: string): Promise<Buffer> {
-  const response = await fetch(url);
+  let response: Response;
+  try {
+    response = await fetch(url);
+  } catch (err) {
+    const code = extractNetworkErrorCode(err);
+    throw new Error(
+      `[timber] Failed to download font file from ${url}` +
+        (code ? ` (${code})` : '') +
+        `. Build requires internet access for font optimization.` +
+        ` If building offline, set TIMBER_SKIP_FONTS=1 to skip font downloading.`
+    );
+  }
   if (!response.ok) {
     throw new Error(`Failed to download font from ${url}: ${response.status}`);
   }
@@ -232,7 +276,14 @@ export async function downloadAndCacheFonts(
 
   for (const font of googleFonts) {
     const apiUrl = buildGoogleFontsUrl(font);
-    const faces = await fetchGoogleFontsCss(apiUrl);
+    let faces: GoogleFontFace[];
+    try {
+      faces = await fetchGoogleFontsCss(apiUrl);
+    } catch (err) {
+      throw new Error(
+        `[timber] Failed to download font '${font.family}': ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
     const filtered = filterBySubsets(faces, font.subsets);
 
     for (const face of filtered) {

package/src/plugins/fonts.ts

@@ -159,9 +159,15 @@ export function timberFonts(ctx: PluginContext): Plugin {
           return '';
         }
 
+        const skipFonts = process.env.TIMBER_SKIP_FONTS === '1';
+
         for (const font of pipeline.googleFonts()) {
           if (font.importer !== importer) continue;
           if (pipeline.hasFaces(font.id)) continue;
+          if (skipFonts && !ctx.dev) {
+            console.warn(`[timber-fonts] Skipping font "${font.family}" (TIMBER_SKIP_FONTS=1)`);
+            continue;
+          }
           try {
             if (ctx.dev) {
               const faces = await resolveDevFontFaces(font);

package/src/server/asset-headers.ts

@@ -8,9 +8,13 @@
  * Unhashed assets (e.g. /favicon.ico) get a shorter cache with revalidation:
  *   Cache-Control: public, max-age=3600, must-revalidate
  *
- * This is applied automatically by the framework for static assets served
- * from the build output. Page responses are NOT affected — those are
- * controlled by the developer via middleware.ts or proxy.ts.
+ * The `_headers` file lists hashed asset paths (/assets/*, /_timber/fonts/*) as
+ * wildcard rules and unhashed files as per-file rules. At runtime, adapters
+ * that see static file requests (nitro, preview) also set Cache-Control via
+ * `getAssetCacheControl()`. On Cloudflare Workers Static Assets, the worker
+ * never sees static file requests — the `_headers` file is the only mechanism.
+ * Page responses are NOT affected — those are controlled by the developer
+ * via middleware.ts or proxy.ts.
  *
  * Design docs: 18-build-system.md, 06-caching.md
  */

package/src/server/pipeline-phases.ts

@@ -290,13 +290,21 @@ export async function handleRequest(
         // immutable header bag (e.g. user returns Response.redirect()).
         if (handlerResult instanceof Response) {
           if (method === 'HEAD') {
+            const headHeaders = new Headers(handlerResult.headers);
+            if (handlerResult.ok && !headHeaders.has('Cache-Control')) {
+              headHeaders.set('Cache-Control', 'public, max-age=14400, must-revalidate');
+            }
             return new Response(null, {
               status: handlerResult.status,
               statusText: handlerResult.statusText,
-              headers: new Headers(handlerResult.headers),
+              headers: headHeaders,
             });
           }
-          return cloneWithMutableHeaders(handlerResult);
+          const res = cloneWithMutableHeaders(handlerResult);
+          if (res.ok && !res.headers.has('Cache-Control')) {
+            res.headers.set('Cache-Control', 'public, max-age=14400, must-revalidate');
+          }
+          return res;
         }
         // Otherwise, serialize based on content type. The type discriminator
         // here is the metadata route's declared content type (from the file

package/dist/_chunks/build-output-helper-B20ZuTSA.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"build-output-helper-B20ZuTSA.js","names":[],"sources":["../../src/adapters/shared.ts","../../src/adapters/build-output-helper.ts"],"sourcesContent":["// Shared adapter utilities — leaf module with zero deps on server/, client/,\n// or any Vite-dependent code.\n//\n// Adapters are loaded by Node at Vite startup time, before Vite's module\n// resolver is available. This module uses only Node built-ins and can be\n// imported by both adapters via a relative path.\n//\n// IMPORTANT: Do NOT add imports from ../server/, ../client/, ../plugins/,\n// or any module that transitively depends on Vite. A test in\n// tests/adapters/shared-no-forbidden-imports.test.ts enforces this.\n\n// ─── Static asset cache headers ──────────────────────────────────────────\n\n/** Cache-Control value for hashed (immutable) assets. */\nexport const IMMUTABLE_CACHE = 'public, max-age=31536000, immutable';\n\n/** Cache-Control value for unhashed static assets. */\nexport const STATIC_CACHE = 'public, max-age=3600, must-revalidate';\n\n/**\n * Generate a `_headers` file for static asset cache control.\n *\n * The `_headers` file is a platform convention supported by Cloudflare Workers\n * Static Assets, Cloudflare Pages, and Netlify. It maps URL patterns to\n * HTTP response headers.\n *\n * Vite places all hashed chunks under `/assets/` — these get immutable caching.\n * Everything else (favicon.ico, robots.txt, etc.) gets a shorter cache.\n */\nexport function generateHeadersFile(): string {\n  return `# Auto-generated by @timber-js/app — static asset cache headers.\n# See design/25-production-deployments.md §\"CDN / Edge Cache\"\n\n/assets/*\n  Cache-Control: ${IMMUTABLE_CACHE}\n\n/*\n  Cache-Control: ${STATIC_CACHE}\n`;\n}\n","// Shared build-output helper for adapter buildOutput() methods.\n//\n// Steps 1–5 of every adapter's buildOutput are platform-agnostic:\n//   1. Copy client assets to the public/static directory\n//   2. Write _headers file for static asset cache control\n//   3. Copy RSC + SSR server bundles\n//   4. Write manifest-init module (if present)\n//\n// Only the final steps (entry codegen, platform config) vary per adapter.\n//\n// IMPORTANT: This module must remain a leaf — no imports from ../server/,\n// ../client/, or Vite-dependent code. See adapters/shared.ts header.\n\nimport { writeFile, mkdir, cp, readdir, readFile } from 'node:fs/promises';\nimport { join, basename } from 'node:path';\nimport { generateHeadersFile } from './shared.js';\nimport type { TimberConfig } from './types';\n\n/** Options for the shared build output steps. */\nexport interface BuildOutputBaseOptions {\n  /** Resolved timber config. */\n  config: TimberConfig;\n  /** Root build directory (e.g. `.timber/build`). */\n  buildDir: string;\n  /** Adapter-specific output directory (e.g. `.timber/build/nitro`). */\n  outDir: string;\n  /**\n   * Name of the public/static directory within outDir.\n   * Nitro uses 'public', Cloudflare uses 'static'.\n   */\n  publicDirName: string;\n}\n\n/**\n * Run the platform-agnostic build output steps shared by all adapters:\n *\n * 1. Create the output directory\n * 2. Copy client assets to the public/static directory\n * 3. Write the `_headers` file for static asset cache control\n * 4. Copy RSC and SSR server bundles into the output directory\n * 5. Write the manifest-init module if present\n *\n * Returns the resolved public directory path for further adapter-specific use.\n */\nexport async function runSharedBuildSteps(opts: BuildOutputBaseOptions): Promise<string> {\n  const { config, buildDir, outDir, publicDirName } = opts;\n\n  // 1. Create the output directory.\n  await mkdir(outDir, { recursive: true });\n\n  // 2. Copy client assets to public/static directory.\n  // When client JavaScript is disabled, skip .js files — only CSS,\n  // fonts, images, and other static assets are needed.\n  const clientDir = join(buildDir, 'client');\n  const publicDir = join(outDir, publicDirName);\n  await mkdir(publicDir, { recursive: true });\n  // Find WASM files that are referenced by client JS (legitimate client WASM)\n  // vs orphaned server-only WASM (e.g. @takumi-rs for OG image generation).\n  // Only strip orphaned WASM to avoid breaking client-side WASM usage.\n  const referencedWasm = await findReferencedWasm(clientDir);\n\n  await cp(clientDir, publicDir, {\n    recursive: true,\n    filter: (src: string) => {\n      if (src.endsWith('.wasm') && !referencedWasm.has(basename(src))) {\n        return false;\n      }\n      if (config.clientJavascriptDisabled && src.endsWith('.js')) return false;\n      return true;\n    },\n  }).catch((e: NodeJS.ErrnoException) => {\n    // Client dir may not exist when client JavaScript is disabled\n    if (e.code !== 'ENOENT') throw e;\n  });\n\n  // 3. Write _headers file for static asset cache control.\n  await writeFile(join(publicDir, '_headers'), generateHeadersFile());\n\n  // 4. Copy RSC + SSR server bundles into the output directory.\n  await cp(join(buildDir, 'rsc'), join(outDir, 'rsc'), { recursive: true });\n  await cp(join(buildDir, 'ssr'), join(outDir, 'ssr'), { recursive: true }).catch(\n    (e: NodeJS.ErrnoException) => {\n      // SSR dir may not exist for static-only builds\n      if (e.code !== 'ENOENT') throw e;\n    }\n  );\n\n  // 5. Write manifest-init module if present.\n  if (config.manifestInit) {\n    await writeFile(join(outDir, '_timber-manifest-init.js'), config.manifestInit);\n  }\n\n  return publicDir;\n}\n\n/**\n * Scan client JS files for references to .wasm filenames.\n * Returns the set of WASM basenames that are actually imported/referenced\n * by client code and must be preserved in the static output.\n */\nasync function findReferencedWasm(clientDir: string): Promise<Set<string>> {\n  const referenced = new Set<string>();\n\n  let files: string[];\n  try {\n    files = await collectFiles(clientDir);\n  } catch {\n    return referenced;\n  }\n\n  const jsFiles = files.filter((f) => f.endsWith('.js'));\n  const wasmFiles = files.filter((f) => f.endsWith('.wasm')).map((f) => basename(f));\n  if (wasmFiles.length === 0) return referenced;\n\n  for (const jsFile of jsFiles) {\n    const content = await readFile(jsFile, 'utf-8');\n    for (const wasmName of wasmFiles) {\n      if (content.includes(wasmName)) {\n        referenced.add(wasmName);\n      }\n    }\n  }\n\n  return referenced;\n}\n\nasync function collectFiles(dir: string): Promise<string[]> {\n  const result: string[] = [];\n  const entries = await readdir(dir, { withFileTypes: true });\n  for (const entry of entries) {\n    const fullPath = join(dir, entry.name);\n    if (entry.isDirectory()) {\n      result.push(...(await collectFiles(fullPath)));\n    } else {\n      result.push(fullPath);\n    }\n  }\n  return result;\n}\n"],"mappings":";;;;AAcA,IAAa,kBAAkB;;AAG/B,IAAa,eAAe;;;;;;;;;;;AAY5B,SAAgB,sBAA8B;CAC5C,OAAO;;;;mBAIU,gBAAgB;;;mBAGhB,aAAa;;AAEhC;;;;;;;;;;;;;;ACKA,eAAsB,oBAAoB,MAA+C;CACvF,MAAM,EAAE,QAAQ,UAAU,QAAQ,kBAAkB;CAGpD,MAAM,MAAM,QAAQ,EAAE,WAAW,KAAK,CAAC;CAKvC,MAAM,YAAY,KAAK,UAAU,QAAQ;CACzC,MAAM,YAAY,KAAK,QAAQ,aAAa;CAC5C,MAAM,MAAM,WAAW,EAAE,WAAW,KAAK,CAAC;CAI1C,MAAM,iBAAiB,MAAM,mBAAmB,SAAS;CAEzD,MAAM,GAAG,WAAW,WAAW;EAC7B,WAAW;EACX,SAAS,QAAgB;GACvB,IAAI,IAAI,SAAS,OAAO,KAAK,CAAC,eAAe,IAAI,SAAS,GAAG,CAAC,GAC5D,OAAO;GAET,IAAI,OAAO,4BAA4B,IAAI,SAAS,KAAK,GAAG,OAAO;GACnE,OAAO;EACT;CACF,CAAC,EAAE,OAAO,MAA6B;EAErC,IAAI,EAAE,SAAS,UAAU,MAAM;CACjC,CAAC;CAGD,MAAM,UAAU,KAAK,WAAW,UAAU,GAAG,oBAAoB,CAAC;CAGlE,MAAM,GAAG,KAAK,UAAU,KAAK,GAAG,KAAK,QAAQ,KAAK,GAAG,EAAE,WAAW,KAAK,CAAC;CACxE,MAAM,GAAG,KAAK,UAAU,KAAK,GAAG,KAAK,QAAQ,KAAK,GAAG,EAAE,WAAW,KAAK,CAAC,EAAE,OACvE,MAA6B;EAE5B,IAAI,EAAE,SAAS,UAAU,MAAM;CACjC,CACF;CAGA,IAAI,OAAO,cACT,MAAM,UAAU,KAAK,QAAQ,0BAA0B,GAAG,OAAO,YAAY;CAG/E,OAAO;AACT;;;;;;AAOA,eAAe,mBAAmB,WAAyC;CACzE,MAAM,6BAAa,IAAI,IAAY;CAEnC,IAAI;CACJ,IAAI;EACF,QAAQ,MAAM,aAAa,SAAS;CACtC,QAAQ;EACN,OAAO;CACT;CAEA,MAAM,UAAU,MAAM,QAAQ,MAAM,EAAE,SAAS,KAAK,CAAC;CACrD,MAAM,YAAY,MAAM,QAAQ,MAAM,EAAE,SAAS,OAAO,CAAC,EAAE,KAAK,MAAM,SAAS,CAAC,CAAC;CACjF,IAAI,UAAU,WAAW,GAAG,OAAO;CAEnC,KAAK,MAAM,UAAU,SAAS;EAC5B,MAAM,UAAU,MAAM,SAAS,QAAQ,OAAO;EAC9C,KAAK,MAAM,YAAY,WACrB,IAAI,QAAQ,SAAS,QAAQ,GAC3B,WAAW,IAAI,QAAQ;CAG7B;CAEA,OAAO;AACT;AAEA,eAAe,aAAa,KAAgC;CAC1D,MAAM,SAAmB,CAAC;CAC1B,MAAM,UAAU,MAAM,QAAQ,KAAK,EAAE,eAAe,KAAK,CAAC;CAC1D,KAAK,MAAM,SAAS,SAAS;EAC3B,MAAM,WAAW,KAAK,KAAK,MAAM,IAAI;EACrC,IAAI,MAAM,YAAY,GACpB,OAAO,KAAK,GAAI,MAAM,aAAa,QAAQ,CAAE;OAE7C,OAAO,KAAK,QAAQ;CAExB;CACA,OAAO;AACT"}