@timber-js/app 0.2.0-alpha.153 → 0.2.0-alpha.155

package/agent-skill.md

@@ -0,0 +1,344 @@
+# timber.js — AI Agent Skill
+
+Use this skill when building, modifying, or debugging a timber.js application. timber.js is a Vite-native React framework with file-system routing, React Server Components, and real HTTP status codes.
+
+timber.js is inspired by, but is NOT Next.js. Do not assume Next.js features, APIs, or conventions work in timber. The routing structure is similar, but the APIs, rendering model, and conventions diverge significantly. Always consult timber docs, not Next.js docs.
+
+Full documentation is available in `node_modules/@timber-js/app/docs/` (MDX files). Read the relevant doc before implementing a feature. This skill covers the essential patterns — the docs go deeper.
+
+## Project structure
+
+```
+app/
+  layout.tsx        # Root layout (required) — wraps all pages
+  page.tsx          # Home page (/)
+  globals.css       # Global styles
+  about/
+    page.tsx        # /about
+  blog/
+    layout.tsx      # Blog layout — wraps blog pages
+    page.tsx        # /blog
+    [slug]/
+      page.tsx      # /blog/:slug
+timber.config.ts    # Framework config (output mode, adapter, cache)
+vite.config.ts      # Vite config — imports timber()
+tsconfig.json
+```
+
+## Segment convention files
+
+Each directory in `app/` is a **segment**. These files have special meaning:
+
+| File            | Purpose                                                       |
+| --------------- | ------------------------------------------------------------- |
+| `page.tsx`      | Route leaf — renders at this URL                              |
+| `layout.tsx`    | Persistent shell — wraps children, survives client navigation |
+| `access.ts`     | Auth gate — runs inside React tree, supports slot degradation |
+| `middleware.ts` | Pre-render hook — headers, redirects, cache warming           |
+| `schema.ts`     | Segment & search param codecs                                 |
+| `error.tsx`     | Error boundary for this subtree                               |
+| `404.tsx`       | Custom 404 page (must be a client component)                  |
+
+There is NO `loading.tsx`. Use `<Suspense>` with the flush point model instead.
+
+## Key imports
+
+```ts
+// Server (server components, middleware, access, actions)
+import { deny, redirect, getHeaders, getCookieJar, getSegmentParams,
+         createActionClient, ActionError, revalidatePath, revalidateTag,
+         waitUntil, getTraceId, withSpan } from '@timber-js/app/server';
+
+// Client (client components)
+import { Link, useRouter, usePathname, useActionState,
+         useSegmentParams, usePendingNavigation, useLinkStatus,
+         useSelectedLayoutSegment } from '@timber-js/app/client';
+
+// Typed params
+import { defineSchema } from '@timber-js/app/params';
+import { codec } from '@timber-js/app/codec';
+import { defineSearchParams } from '@timber-js/app/search-params';
+import { defineCookie } from '@timber-js/app/cookies';
+
+// Caching
+import { cache } from '@timber-js/app/cache';
+
+// Generated segment module (typed params, segment path)
+import { SEGMENT_PATH } from './$segment';
+```
+
+## Pages and layouts
+
+Pages are server components by default — async, server-only, zero client JS:
+
+```tsx
+// app/products/[id]/page.tsx
+import { SEGMENT_PATH } from './$segment';
+import { deny, getSegmentParams } from '@timber-js/app/server';
+
+export default async function ProductPage() {
+  const { id } = getSegmentParams(SEGMENT_PATH);
+  const product = await db.products.find(id);
+  if (!product) return deny(404); // Real HTTP 404
+  return <h1>{product.name}</h1>;
+}
+```
+
+Layouts receive `{ children }` and persist across navigation:
+
+```tsx
+// app/layout.tsx — root layout (required)
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+## Server and client components
+
+**Server components** (default): async, access secrets/DB, zero client JS cost.
+**Client components** (`'use client'`): `useState`, `useEffect`, event handlers, browser APIs.
+
+```tsx
+// app/counter.tsx
+'use client';
+import { useState } from 'react';
+export function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
+}
+```
+
+Server components can render client components as children. Client components cannot import server components (pass them as `children` or props instead).
+
+## deny() and redirect()
+
+`deny()` produces real HTTP status codes. `redirect()` sends HTTP redirects.
+
+```ts
+deny();           // 403 (default)
+deny(404);        // 404 Not Found
+deny(503, data);  // 503 with data for error boundary
+
+redirect('/login');                     // 307 temporary
+redirect('/new-page', { permanent: true }); // 308 permanent
+```
+
+## Forms and server actions
+
+Actions use `createActionClient` for reusable middleware:
+
+```ts
+// lib/action.ts
+'use server';
+import { createActionClient, ActionError } from '@timber-js/app/server';
+
+export const actionClient = createActionClient({
+  middleware: async () => {
+    const user = await getUser();
+    if (!user) throw new ActionError('UNAUTHORIZED');
+    return { user };
+  },
+});
+```
+
+```ts
+// app/todos/actions.ts
+'use server';
+import { z } from 'zod/v4';
+import { action } from '@/lib/action';
+import { revalidatePath } from '@timber-js/app/server';
+
+export const createTodo = actionClient
+  .schema(z.object({ title: z.string().min(1) }))
+  .action(async ({ input, ctx }) => {
+    await db.todos.create({ ...input, userId: ctx.user.id });
+    return revalidatePath('/todos');
+  });
+```
+
+```tsx
+// app/todos/todo-form.tsx
+'use client';
+import { useActionState } from '@timber-js/app/client';
+import { createTodo } from './actions';
+
+export function TodoForm() {
+  const [state, formAction, pending, errors] = useActionState(createTodo, null);
+  return (
+    <form action={formAction}>
+      <input name="title" required />
+      {errors.getFieldError('title') && <p>{errors.getFieldError('title')}</p>}
+      <button disabled={pending}>{pending ? 'Adding...' : 'Add'}</button>
+    </form>
+  );
+}
+```
+
+Forms work without JavaScript — they submit as standard POST. With JS, `useActionState` enhances with pending state.
+
+## Access control (access.ts)
+
+```ts
+// app/(authenticated)/access.ts
+import { getCookieJar, redirect } from '@timber-js/app/server';
+
+export default async function access() {
+  const session = getSession(getCookieJar());
+  if (!session) return redirect('/login');
+}
+```
+
+Access runs inside the React tree. It shares `React.cache` scope with layouts. For parallel routes (slots), denied slots degrade gracefully while the rest of the page renders.
+
+## Middleware
+
+Two layers: `proxy.ts` (global, has `next()`) and `middleware.ts` (per-segment, no `next()`).
+
+```ts
+// app/dashboard/middleware.ts
+import { redirect } from '@timber-js/app/server';
+import type { MiddlewareContext } from '@timber-js/app/server';
+
+export default async function middleware(ctx: MiddlewareContext) {
+  const session = await getSession(ctx.req);
+  if (!session) redirect('/login');
+  ctx.headers.set('x-custom', 'value'); // Set response headers
+}
+```
+
+Use middleware for headers, redirects, cache warming. Use `access.ts` for auth.
+
+## Typed params
+
+Define codecs in `app/schema.ts`:
+
+```ts
+// app/schema.ts
+import { defineSchema } from '@timber-js/app/params';
+import { codec } from '@timber-js/app/codec';
+
+export default defineSchema({
+  segmentParams: {
+    '[id]': codec.integer,
+    '[slug]': codec.string,
+  },
+});
+```
+
+## Search params
+
+```ts
+// app/products/search-params.ts
+import { defineSearchParams } from '@timber-js/app/search-params';
+import { codec } from '@timber-js/app/codec';
+
+export const { searchParams } = defineSearchParams({
+  q: codec.string.optional,
+  page: codec.integer.default(1),
+});
+```
+
+Server: `searchParams.get()`. Client: `searchParams.useQueryStates()`.
+
+## Caching
+
+No implicit caching. `fetch()` is never patched. Use `timber.cache()` for cross-request caching:
+
+```ts
+import { cache } from '@timber-js/app/cache';
+
+const getProducts = cache(
+  async () => db.products.findMany(),
+  { ttl: 60, tags: ['products'] }
+);
+```
+
+Use `React.cache` for single-request deduplication.
+
+## The flush point
+
+timber holds the HTTP response until the shell (everything outside `<Suspense>`) resolves. This means:
+
+- Data fetched outside `<Suspense>` can affect the status code (`deny(404)` works)
+- Data inside `<Suspense>` streams after the shell flushes
+- There is no `loading.tsx` — use `<Suspense>` with a fallback explicitly
+
+## Configuration
+
+```ts
+// timber.config.ts
+import { cloudflare } from '@timber-js/app/adapters/cloudflare';
+
+export default {
+  output: 'server',        // or 'static'
+  adapter: cloudflare(),   // or nitro({ preset: 'node-server' })
+};
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { timber } from '@timber-js/app';
+
+export default defineConfig({
+  plugins: [timber()],
+});
+```
+
+## Client navigation
+
+```tsx
+import { Link } from '@timber-js/app/client';
+
+<Link href="/about">About</Link>
+<Link href="/products/123" prefetch>Product</Link>
+```
+
+```tsx
+const router = useRouter();
+router.push('/dashboard');
+router.replace('/settings');
+router.refresh();
+```
+
+## Route patterns
+
+- `(group)/` — route group (no URL segment)
+- `_private/` — excluded from routing
+- `[param]/` — dynamic segment
+- `[...catchAll]/` — catch-all segment
+- `@slot/` — parallel route (named slot)
+- `(.)path/` — intercepting route
+
+## Common mistakes to avoid
+
+1. **No `loading.tsx`** — timber doesn't have it. Use `<Suspense>` explicitly.
+2. **Don't patch fetch** — `fetch()` is never cached. Use `timber.cache()` or `React.cache`.
+3. **`deny()` not `throw new Error`** — use `deny(404)` for proper status codes, not error throwing.
+4. **Server actions need `'use server'`** — at the top of the file or the function.
+5. **`access.ts` exports a default function** — not a named export.
+6. **Root layout must include `<html>` and `<body>`** — timber doesn't add these.
+7. **`getSegmentParams` uses ALS** — works in server components, middleware, access, actions. No prop drilling needed.
+8. **`useActionState` returns 4 values** — `[state, formAction, isPending, errors]`. The 4th is timber-specific with `errors.getFieldError()`, `errors.fieldErrors`, `errors.serverError`.
+9. **Middleware has one arg** — `middleware(ctx: MiddlewareContext)`, not `(req, res)`.
+10. **Don't use `next/` imports** — use `@timber-js/app/server`, `@timber-js/app/client`, etc.
+
+## Commands
+
+```bash
+pnpm dev          # Start dev server
+pnpm build        # Production build
+pnpm preview      # Preview production build
+```
+
+## Further reading
+
+Full docs are in `node_modules/@timber-js/app/docs/`. Key files:
+
+- `docs/learn/` — Core concepts (pages, data fetching, forms, caching, middleware)
+- `docs/more/` — Advanced topics (routing, metadata, MDX, content collections, security)
+- `docs/api/` — API reference for every export

package/dist/cli.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-declare const COMMANDS: readonly ["dev", "build", "preview", "check", "schema"];
+declare const COMMANDS: readonly ["dev", "build", "preview", "check", "schema", "init"];
 type Command = (typeof COMMANDS)[number];
 export interface ParsedArgs {
     command: Command;
@@ -70,5 +70,13 @@ export declare function runCheck(options: CommandOptions): Promise<void>;
  * See design/41-global-params.md §Auto-Scaffolding
  */
 export declare function runSchema(args: string[]): Promise<void>;
+/**
+ * `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 declare function runInit(): Promise<void>;
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAaA,QAAA,MAAM,QAAQ,yDAA0D,CAAC;AACzE,KAAK,OAAO,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzC,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,6EAA6E;IAC7E,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAsCpD;AAID,kDAAkD;AAClD,MAAM,WAAW,QAAQ;IACvB,YAAY,CAAC,EAAE,cAAc,MAAM,EAAE,YAAY,CAAC;IAClD,aAAa,CAAC,EAAE,cAAc,MAAM,EAAE,aAAa,CAAC;IACpD,OAAO,CAAC,EAAE,cAAc,MAAM,EAAE,OAAO,CAAC;CACzC;AAED;;;;;;;;GAQG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAOrF;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAMvF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,kBAAkB,EAAE,qBAAqB,GAAG,SAAS,GACpE,SAAS,GAAG,MAAM,CAKpB;AAED;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBzF;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAerE;AAID;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA6C7D"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAaA,QAAA,MAAM,QAAQ,iEAAkE,CAAC;AACjF,KAAK,OAAO,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzC,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,6EAA6E;IAC7E,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAsCpD;AAID,kDAAkD;AAClD,MAAM,WAAW,QAAQ;IACvB,YAAY,CAAC,EAAE,cAAc,MAAM,EAAE,YAAY,CAAC;IAClD,aAAa,CAAC,EAAE,cAAc,MAAM,EAAE,aAAa,CAAC;IACpD,OAAO,CAAC,EAAE,cAAc,MAAM,EAAE,OAAO,CAAC;CACzC;AAED;;;;;;;;GAQG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAOrF;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAMvF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,kBAAkB,EAAE,qBAAqB,GAAG,SAAS,GACpE,SAAS,GAAG,MAAM,CAKpB;AAED;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBzF;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAerE;AAID;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA6C7D;AAID;;;;;;GAMG;AACH,wBAAsB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CA6C7C"}

package/dist/cli.js

@@ -5,7 +5,8 @@ var COMMANDS = [
 	"build",
 	"preview",
 	"check",
-	"schema"
+	"schema",
+	"init"
 ];
 /**
 * Parse CLI arguments into a structured command + options.
@@ -17,7 +18,7 @@ var COMMANDS = [
 * goes through the PORT env var or server.port in vite.config.ts.
 */
 function parseArgs(args) {
-	if (args.length === 0) throw new Error("No command provided. Usage: timber <dev|build|preview|check|schema> [--config <path>]");
+	if (args.length === 0) throw new Error("No command provided. Usage: timber <dev|build|preview|check|schema|init> [--config <path>]");
 	const command = args[0];
 	if (!COMMANDS.includes(command)) throw new Error(`Unknown command: ${command}. Available commands: ${COMMANDS.join(", ")}`);
 	let config;
@@ -28,7 +29,7 @@ function parseArgs(args) {
 			config = args[++i];
 			if (!config) throw new Error("--config requires a path argument");
 		} else if (arg.startsWith("-")) throw new Error(`Unknown option: ${arg}. The timber CLI only accepts --config <path>.${arg === "--port" || arg === "-p" ? " To change the port, set the PORT environment variable (PORT=4000 timber dev) or server.port in vite.config.ts." : ""}`);
-		else if (command === "schema") rest.push(arg);
+		else if (command === "schema" || command === "init") rest.push(arg);
 		else throw new Error(`Unexpected argument: ${arg}. Usage: timber ${command} [--config <path>]`);
 	}
 	return {
@@ -138,6 +139,39 @@ async function runSchema(args) {
 		for (const seg of result.removedSegments) console.log(`  - ${seg}`);
 	}
 }
+/**
+* `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.
+*/
+async function runInit() {
+	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 agentSkillPath = resolve(resolve(dirname(fileURLToPath(import.meta.url)), ".."), "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 = [];
+	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.");
+}
 async function main() {
 	const parsed = parseArgs(process.argv.slice(2));
 	const options = { config: parsed.config };
@@ -157,6 +191,9 @@ async function main() {
 		case "schema":
 			await runSchema(parsed.rest);
 			break;
+		case "init":
+			await runInit();
+			break;
 	}
 }
 if (typeof process !== "undefined" && process.argv[1] && (import.meta.url.endsWith(process.argv[1]) || process.argv[1].endsWith("bin/timber.mjs") || process.argv[1].endsWith("bin/timber"))) main().catch((err) => {
@@ -164,6 +201,6 @@ if (typeof process !== "undefined" && process.argv[1] && (import.meta.url.endsWi
 	process.exit(1);
 });
 //#endregion
-export { parseArgs, resolvePreviewStrategy, runBuild, runCheck, runDev, runPreview, runSchema };
+export { parseArgs, resolvePreviewStrategy, runBuild, runCheck, runDev, runInit, runPreview, runSchema };
 
 //# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n\n// timber.js CLI\n//\n// Wraps Vite commands with timber-specific behavior.\n// See design/18-build-system.md §\"CLI\".\n//\n// Commands:\n//   timber dev      — Start Vite dev server with HMR\n//   timber build    — Run multi-environment build via createBuilder/buildApp\n//   timber preview  — Serve the production build\n//   timber check    — Validate types + routes without building\n\nconst COMMANDS = ['dev', 'build', 'preview', 'check', 'schema'] as const;\ntype Command = (typeof COMMANDS)[number];\n\nexport interface ParsedArgs {\n  command: Command;\n  config: string | undefined;\n  /** Positional arguments after the command (used by `timber schema sync`). */\n  rest: string[];\n}\n\nexport interface CommandOptions {\n  config?: string;\n}\n\n/**\n * Parse CLI arguments into a structured command + options.\n * Accepts: timber <command> [--config|-c <path>]\n *\n * Unknown flags are an error, not silently ignored — `timber dev --port 4000`\n * starting on the default port would contradict fail-loudly. The CLI surface\n * is intentionally --config-only (design/11-platform.md §CLI); port selection\n * goes through the PORT env var or server.port in vite.config.ts.\n */\nexport function parseArgs(args: string[]): ParsedArgs {\n  if (args.length === 0) {\n    throw new Error(\n      'No command provided. Usage: timber <dev|build|preview|check|schema> [--config <path>]'\n    );\n  }\n\n  const command = args[0];\n  if (!COMMANDS.includes(command as Command)) {\n    throw new Error(`Unknown command: ${command}. Available commands: ${COMMANDS.join(', ')}`);\n  }\n\n  let config: string | undefined;\n  const rest: string[] = [];\n  for (let i = 1; i < args.length; i++) {\n    const arg = args[i];\n    if (arg === '--config' || arg === '-c') {\n      config = args[++i];\n      if (!config) {\n        throw new Error('--config requires a path argument');\n      }\n    } else if (arg.startsWith('-')) {\n      const portHint =\n        arg === '--port' || arg === '-p'\n          ? ' To change the port, set the PORT environment variable (PORT=4000 timber dev) ' +\n            'or server.port in vite.config.ts.'\n          : '';\n      throw new Error(\n        `Unknown option: ${arg}. The timber CLI only accepts --config <path>.${portHint}`\n      );\n    } else if (command === 'schema') {\n      rest.push(arg);\n    } else {\n      throw new Error(`Unexpected argument: ${arg}. Usage: timber ${command} [--config <path>]`);\n    }\n  }\n\n  return { command: command as Command, config, rest };\n}\n\n// ─── Command Implementations ─────────────────────────────────────────────────\n\n/** @internal Dependency injection for testing. */\nexport interface ViteDeps {\n  createServer?: typeof import('vite').createServer;\n  createBuilder?: typeof import('vite').createBuilder;\n  preview?: typeof import('vite').preview;\n}\n\n/**\n * Start the Vite dev server.\n *\n * The timber plugin binds the port immediately with a holding page\n * (in rootSync's config hook) so browsers see a \"starting...\" page\n * instead of ERR_CONNECTION_REFUSED during initialization.\n *\n * See design/21-dev-server.md, TIM-665.\n */\nexport async function runDev(options: CommandOptions, _deps?: ViteDeps): Promise<void> {\n  const createServer = _deps?.createServer ?? (await import('vite')).createServer;\n  const server = await createServer({\n    configFile: options.config,\n  });\n  await server.listen();\n  server.printUrls();\n}\n\n/**\n * Run the production build using createBuilder + buildApp.\n * Direct build() calls do NOT trigger the RSC plugin's multi-environment\n * pipeline — createBuilder/buildApp is required.\n */\nexport async function runBuild(options: CommandOptions, _deps?: ViteDeps): Promise<void> {\n  const createBuilder = _deps?.createBuilder ?? (await import('vite')).createBuilder;\n  const builder = await createBuilder({\n    configFile: options.config,\n  });\n  await builder.buildApp();\n}\n\n/**\n * Determine whether to use the adapter's preview or Vite's built-in preview.\n * Exported for testing — the actual runPreview function uses this internally.\n */\nexport function resolvePreviewStrategy(\n  adapter: import('./adapters/types').TimberPlatformAdapter | undefined\n): 'adapter' | 'vite' {\n  if (adapter && typeof adapter.preview === 'function') {\n    return 'adapter';\n  }\n  return 'vite';\n}\n\n/**\n * Serve the production build for local testing.\n * If the adapter provides a preview() method, it takes priority.\n * Otherwise falls back to Vite's built-in preview server.\n *\n * Uses the same loadTimberConfigFile loader as dev/build — one loader,\n * one set of module semantics. A config file that exists but fails to\n * load throws (naming the file) instead of silently degrading to plain\n * Vite preview. See TIM-1066.\n */\nexport async function runPreview(options: CommandOptions, _deps?: ViteDeps): Promise<void> {\n  const { loadTimberConfigFile, resolveBuildDir } = await import('./plugin-context.js');\n\n  const root = process.cwd();\n  const config = loadTimberConfigFile(root);\n  const adapter = config?.adapter as import('./adapters/types').TimberPlatformAdapter | undefined;\n\n  if (resolvePreviewStrategy(adapter) === 'adapter') {\n    const buildDir = resolveBuildDir(root, config?.buildDir);\n    const timberConfig = { output: (config?.output ?? 'server') as 'server' | 'static' };\n    await adapter!.preview!(timberConfig, buildDir);\n    return;\n  }\n\n  // Fallback: Vite's built-in preview server\n  const preview = _deps?.preview ?? (await import('vite')).preview;\n  const server = await preview({\n    configFile: options.config,\n  });\n  server.printUrls();\n}\n\n/**\n * Validate types and routes without producing build output.\n * Runs tsgo --noEmit for type checking.\n */\nexport async function runCheck(options: CommandOptions): Promise<void> {\n  const { execFile } = await import('node:child_process');\n\n  await new Promise<void>((resolve, reject) => {\n    const configArgs = options.config ? ['--project', options.config] : [];\n    execFile('tsgo', ['--noEmit', ...configArgs], (err, stdout, stderr) => {\n      if (stdout) process.stdout.write(stdout);\n      if (stderr) process.stderr.write(stderr);\n      if (err) {\n        reject(new Error(`Type check failed with exit code ${err.code}`));\n      } else {\n        resolve();\n      }\n    });\n  });\n}\n\n// ─── Schema Subcommand ───────────────────────────────────────────────────────\n\n/**\n * `timber schema sync` — scan filesystem for dynamic segments, diff against\n * app/schema.ts, and append missing entries with type-appropriate codec defaults.\n *\n * See design/41-global-params.md §Auto-Scaffolding\n */\nexport async function runSchema(args: string[]): Promise<void> {\n  const subcommand = args[0];\n\n  if (subcommand !== 'sync') {\n    throw new Error(\n      `Unknown schema subcommand: ${subcommand ?? '(none)'}. Usage: timber schema sync`\n    );\n  }\n\n  const { runSchemaSync, defaultCodecForSegment } = await import('./cli-schema-sync.js');\n  const result = runSchemaSync(process.cwd());\n\n  if (result.filesystemSegments.length === 0) {\n    console.log('[timber] No dynamic segments found in app/.');\n    return;\n  }\n\n  if (result.created) {\n    console.log(`[timber] Created app/schema.ts with ${result.addedSegments.length} segment(s):`);\n    for (const seg of result.addedSegments) {\n      console.log(`  + ${seg}: ${defaultCodecForSegment(seg)}`);\n    }\n    return;\n  }\n\n  if (result.addedSegments.length === 0 && result.removedSegments.length === 0) {\n    console.log('[timber] Schema is up to date — all segments are registered.');\n    return;\n  }\n\n  if (result.addedSegments.length > 0) {\n    console.log(`[timber] Added ${result.addedSegments.length} segment(s) to app/schema.ts:`);\n    for (const seg of result.addedSegments) {\n      console.log(`  + ${seg}: ${defaultCodecForSegment(seg)}`);\n    }\n  }\n\n  if (result.removedSegments.length > 0) {\n    console.log(\n      `[timber] Removed ${result.removedSegments.length} stale segment(s) from app/schema.ts:`\n    );\n    for (const seg of result.removedSegments) {\n      console.log(`  - ${seg}`);\n    }\n  }\n}\n\n// ─── Main Entry Point ────────────────────────────────────────────────────────\n\nasync function main(): Promise<void> {\n  const parsed = parseArgs(process.argv.slice(2));\n  const options: CommandOptions = { config: parsed.config };\n\n  switch (parsed.command) {\n    case 'dev':\n      await runDev(options);\n      break;\n    case 'build':\n      await runBuild(options);\n      break;\n    case 'preview':\n      await runPreview(options);\n      break;\n    case 'check':\n      await runCheck(options);\n      break;\n    case 'schema':\n      await runSchema(parsed.rest);\n      break;\n  }\n}\n\n// Run main when executed as a CLI (not imported in tests).\n// The bin shim (bin/timber.mjs) does `import '../dist/cli.js'`, so\n// process.argv[1] points to the shim, not this file. We check both:\n// direct execution AND being imported by the timber bin shim.\nconst isDirectExecution =\n  typeof process !== 'undefined' &&\n  process.argv[1] &&\n  (import.meta.url.endsWith(process.argv[1]) ||\n    process.argv[1].endsWith('bin/timber.mjs') ||\n    process.argv[1].endsWith('bin/timber'));\n\nif (isDirectExecution) {\n  main().catch((err) => {\n    console.error(err.message);\n    process.exit(1);\n  });\n}\n"],"mappings":";;AAaA,IAAM,WAAW;CAAC;CAAO;CAAS;CAAW;CAAS;AAAQ;;;;;;;;;;AAuB9D,SAAgB,UAAU,MAA4B;CACpD,IAAI,KAAK,WAAW,GAClB,MAAM,IAAI,MACR,uFACF;CAGF,MAAM,UAAU,KAAK;CACrB,IAAI,CAAC,SAAS,SAAS,OAAkB,GACvC,MAAM,IAAI,MAAM,oBAAoB,QAAQ,wBAAwB,SAAS,KAAK,IAAI,GAAG;CAG3F,IAAI;CACJ,MAAM,OAAiB,CAAC;CACxB,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;EACpC,MAAM,MAAM,KAAK;EACjB,IAAI,QAAQ,cAAc,QAAQ,MAAM;GACtC,SAAS,KAAK,EAAE;GAChB,IAAI,CAAC,QACH,MAAM,IAAI,MAAM,mCAAmC;EAEvD,OAAO,IAAI,IAAI,WAAW,GAAG,GAM3B,MAAM,IAAI,MACR,mBAAmB,IAAI,gDALvB,QAAQ,YAAY,QAAQ,OACxB,oHAEA,IAGN;OACK,IAAI,YAAY,UACrB,KAAK,KAAK,GAAG;OAEb,MAAM,IAAI,MAAM,wBAAwB,IAAI,kBAAkB,QAAQ,mBAAmB;CAE7F;CAEA,OAAO;EAAW;EAAoB;EAAQ;CAAK;AACrD;;;;;;;;;;AAoBA,eAAsB,OAAO,SAAyB,OAAiC;CAErF,MAAM,SAAS,OADM,OAAO,iBAAiB,MAAM,OAAO,SAAS,cACjC,EAChC,YAAY,QAAQ,OACtB,CAAC;CACD,MAAM,OAAO,OAAO;CACpB,OAAO,UAAU;AACnB;;;;;;AAOA,eAAsB,SAAS,SAAyB,OAAiC;CAKvF,OAAM,OAJgB,OAAO,kBAAkB,MAAM,OAAO,SAAS,eACjC,EAClC,YAAY,QAAQ,OACtB,CAAC,GACa,SAAS;AACzB;;;;;AAMA,SAAgB,uBACd,SACoB;CACpB,IAAI,WAAW,OAAO,QAAQ,YAAY,YACxC,OAAO;CAET,OAAO;AACT;;;;;;;;;;;AAYA,eAAsB,WAAW,SAAyB,OAAiC;CACzF,MAAM,EAAE,sBAAsB,oBAAoB,MAAM,OAAO;CAE/D,MAAM,OAAO,QAAQ,IAAI;CACzB,MAAM,SAAS,qBAAqB,IAAI;CACxC,MAAM,UAAU,QAAQ;CAExB,IAAI,uBAAuB,OAAO,MAAM,WAAW;EACjD,MAAM,WAAW,gBAAgB,MAAM,QAAQ,QAAQ;EACvD,MAAM,eAAe,EAAE,QAAS,QAAQ,UAAU,SAAiC;EACnF,MAAM,QAAS,QAAS,cAAc,QAAQ;EAC9C;CACF;CAOA,CAAA,OAJgB,OAAO,YAAY,MAAM,OAAO,SAAS,SAC5B,EAC3B,YAAY,QAAQ,OACtB,CAAC,GACM,UAAU;AACnB;;;;;AAMA,eAAsB,SAAS,SAAwC;CACrE,MAAM,EAAE,aAAa,MAAM,OAAO;CAElC,MAAM,IAAI,SAAe,SAAS,WAAW;EAE3C,SAAS,QAAQ,CAAC,YAAY,GADX,QAAQ,SAAS,CAAC,aAAa,QAAQ,MAAM,IAAI,CAAC,CAC1B,IAAI,KAAK,QAAQ,WAAW;GACrE,IAAI,QAAQ,QAAQ,OAAO,MAAM,MAAM;GACvC,IAAI,QAAQ,QAAQ,OAAO,MAAM,MAAM;GACvC,IAAI,KACF,uBAAO,IAAI,MAAM,oCAAoC,IAAI,MAAM,CAAC;QAEhE,QAAQ;EAEZ,CAAC;CACH,CAAC;AACH;;;;;;;AAUA,eAAsB,UAAU,MAA+B;CAC7D,MAAM,aAAa,KAAK;CAExB,IAAI,eAAe,QACjB,MAAM,IAAI,MACR,8BAA8B,cAAc,SAAS,4BACvD;CAGF,MAAM,EAAE,eAAe,2BAA2B,MAAM,OAAO;CAC/D,MAAM,SAAS,cAAc,QAAQ,IAAI,CAAC;CAE1C,IAAI,OAAO,mBAAmB,WAAW,GAAG;EAC1C,QAAQ,IAAI,6CAA6C;EACzD;CACF;CAEA,IAAI,OAAO,SAAS;EAClB,QAAQ,IAAI,uCAAuC,OAAO,cAAc,OAAO,aAAa;EAC5F,KAAK,MAAM,OAAO,OAAO,eACvB,QAAQ,IAAI,OAAO,IAAI,IAAI,uBAAuB,GAAG,GAAG;EAE1D;CACF;CAEA,IAAI,OAAO,cAAc,WAAW,KAAK,OAAO,gBAAgB,WAAW,GAAG;EAC5E,QAAQ,IAAI,8DAA8D;EAC1E;CACF;CAEA,IAAI,OAAO,cAAc,SAAS,GAAG;EACnC,QAAQ,IAAI,kBAAkB,OAAO,cAAc,OAAO,8BAA8B;EACxF,KAAK,MAAM,OAAO,OAAO,eACvB,QAAQ,IAAI,OAAO,IAAI,IAAI,uBAAuB,GAAG,GAAG;CAE5D;CAEA,IAAI,OAAO,gBAAgB,SAAS,GAAG;EACrC,QAAQ,IACN,oBAAoB,OAAO,gBAAgB,OAAO,sCACpD;EACA,KAAK,MAAM,OAAO,OAAO,iBACvB,QAAQ,IAAI,OAAO,KAAK;CAE5B;AACF;AAIA,eAAe,OAAsB;CACnC,MAAM,SAAS,UAAU,QAAQ,KAAK,MAAM,CAAC,CAAC;CAC9C,MAAM,UAA0B,EAAE,QAAQ,OAAO,OAAO;CAExD,QAAQ,OAAO,SAAf;EACE,KAAK;GACH,MAAM,OAAO,OAAO;GACpB;EACF,KAAK;GACH,MAAM,SAAS,OAAO;GACtB;EACF,KAAK;GACH,MAAM,WAAW,OAAO;GACxB;EACF,KAAK;GACH,MAAM,SAAS,OAAO;GACtB;EACF,KAAK;GACH,MAAM,UAAU,OAAO,IAAI;GAC3B;CACJ;AACF;AAaA,IANE,OAAO,YAAY,eACnB,QAAQ,KAAK,OACZ,OAAO,KAAK,IAAI,SAAS,QAAQ,KAAK,EAAE,KACvC,QAAQ,KAAK,GAAG,SAAS,gBAAgB,KACzC,QAAQ,KAAK,GAAG,SAAS,YAAY,IAGvC,KAAK,EAAE,OAAO,QAAQ;CACpB,QAAQ,MAAM,IAAI,OAAO;CACzB,QAAQ,KAAK,CAAC;AAChB,CAAC"}
+{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n\n// timber.js CLI\n//\n// Wraps Vite commands with timber-specific behavior.\n// See design/18-build-system.md §\"CLI\".\n//\n// Commands:\n//   timber dev      — Start Vite dev server with HMR\n//   timber build    — Run multi-environment build via createBuilder/buildApp\n//   timber preview  — Serve the production build\n//   timber check    — Validate types + routes without building\n\nconst COMMANDS = ['dev', 'build', 'preview', 'check', 'schema', 'init'] as const;\ntype Command = (typeof COMMANDS)[number];\n\nexport interface ParsedArgs {\n  command: Command;\n  config: string | undefined;\n  /** Positional arguments after the command (used by `timber schema sync`). */\n  rest: string[];\n}\n\nexport interface CommandOptions {\n  config?: string;\n}\n\n/**\n * Parse CLI arguments into a structured command + options.\n * Accepts: timber <command> [--config|-c <path>]\n *\n * Unknown flags are an error, not silently ignored — `timber dev --port 4000`\n * starting on the default port would contradict fail-loudly. The CLI surface\n * is intentionally --config-only (design/11-platform.md §CLI); port selection\n * goes through the PORT env var or server.port in vite.config.ts.\n */\nexport function parseArgs(args: string[]): ParsedArgs {\n  if (args.length === 0) {\n    throw new Error(\n      'No command provided. Usage: timber <dev|build|preview|check|schema|init> [--config <path>]'\n    );\n  }\n\n  const command = args[0];\n  if (!COMMANDS.includes(command as Command)) {\n    throw new Error(`Unknown command: ${command}. Available commands: ${COMMANDS.join(', ')}`);\n  }\n\n  let config: string | undefined;\n  const rest: string[] = [];\n  for (let i = 1; i < args.length; i++) {\n    const arg = args[i];\n    if (arg === '--config' || arg === '-c') {\n      config = args[++i];\n      if (!config) {\n        throw new Error('--config requires a path argument');\n      }\n    } else if (arg.startsWith('-')) {\n      const portHint =\n        arg === '--port' || arg === '-p'\n          ? ' To change the port, set the PORT environment variable (PORT=4000 timber dev) ' +\n            'or server.port in vite.config.ts.'\n          : '';\n      throw new Error(\n        `Unknown option: ${arg}. The timber CLI only accepts --config <path>.${portHint}`\n      );\n    } else if (command === 'schema' || command === 'init') {\n      rest.push(arg);\n    } else {\n      throw new Error(`Unexpected argument: ${arg}. Usage: timber ${command} [--config <path>]`);\n    }\n  }\n\n  return { command: command as Command, config, rest };\n}\n\n// ─── Command Implementations ─────────────────────────────────────────────────\n\n/** @internal Dependency injection for testing. */\nexport interface ViteDeps {\n  createServer?: typeof import('vite').createServer;\n  createBuilder?: typeof import('vite').createBuilder;\n  preview?: typeof import('vite').preview;\n}\n\n/**\n * Start the Vite dev server.\n *\n * The timber plugin binds the port immediately with a holding page\n * (in rootSync's config hook) so browsers see a \"starting...\" page\n * instead of ERR_CONNECTION_REFUSED during initialization.\n *\n * See design/21-dev-server.md, TIM-665.\n */\nexport async function runDev(options: CommandOptions, _deps?: ViteDeps): Promise<void> {\n  const createServer = _deps?.createServer ?? (await import('vite')).createServer;\n  const server = await createServer({\n    configFile: options.config,\n  });\n  await server.listen();\n  server.printUrls();\n}\n\n/**\n * Run the production build using createBuilder + buildApp.\n * Direct build() calls do NOT trigger the RSC plugin's multi-environment\n * pipeline — createBuilder/buildApp is required.\n */\nexport async function runBuild(options: CommandOptions, _deps?: ViteDeps): Promise<void> {\n  const createBuilder = _deps?.createBuilder ?? (await import('vite')).createBuilder;\n  const builder = await createBuilder({\n    configFile: options.config,\n  });\n  await builder.buildApp();\n}\n\n/**\n * Determine whether to use the adapter's preview or Vite's built-in preview.\n * Exported for testing — the actual runPreview function uses this internally.\n */\nexport function resolvePreviewStrategy(\n  adapter: import('./adapters/types').TimberPlatformAdapter | undefined\n): 'adapter' | 'vite' {\n  if (adapter && typeof adapter.preview === 'function') {\n    return 'adapter';\n  }\n  return 'vite';\n}\n\n/**\n * Serve the production build for local testing.\n * If the adapter provides a preview() method, it takes priority.\n * Otherwise falls back to Vite's built-in preview server.\n *\n * Uses the same loadTimberConfigFile loader as dev/build — one loader,\n * one set of module semantics. A config file that exists but fails to\n * load throws (naming the file) instead of silently degrading to plain\n * Vite preview. See TIM-1066.\n */\nexport async function runPreview(options: CommandOptions, _deps?: ViteDeps): Promise<void> {\n  const { loadTimberConfigFile, resolveBuildDir } = await import('./plugin-context.js');\n\n  const root = process.cwd();\n  const config = loadTimberConfigFile(root);\n  const adapter = config?.adapter as import('./adapters/types').TimberPlatformAdapter | undefined;\n\n  if (resolvePreviewStrategy(adapter) === 'adapter') {\n    const buildDir = resolveBuildDir(root, config?.buildDir);\n    const timberConfig = { output: (config?.output ?? 'server') as 'server' | 'static' };\n    await adapter!.preview!(timberConfig, buildDir);\n    return;\n  }\n\n  // Fallback: Vite's built-in preview server\n  const preview = _deps?.preview ?? (await import('vite')).preview;\n  const server = await preview({\n    configFile: options.config,\n  });\n  server.printUrls();\n}\n\n/**\n * Validate types and routes without producing build output.\n * Runs tsgo --noEmit for type checking.\n */\nexport async function runCheck(options: CommandOptions): Promise<void> {\n  const { execFile } = await import('node:child_process');\n\n  await new Promise<void>((resolve, reject) => {\n    const configArgs = options.config ? ['--project', options.config] : [];\n    execFile('tsgo', ['--noEmit', ...configArgs], (err, stdout, stderr) => {\n      if (stdout) process.stdout.write(stdout);\n      if (stderr) process.stderr.write(stderr);\n      if (err) {\n        reject(new Error(`Type check failed with exit code ${err.code}`));\n      } else {\n        resolve();\n      }\n    });\n  });\n}\n\n// ─── Schema Subcommand ───────────────────────────────────────────────────────\n\n/**\n * `timber schema sync` — scan filesystem for dynamic segments, diff against\n * app/schema.ts, and append missing entries with type-appropriate codec defaults.\n *\n * See design/41-global-params.md §Auto-Scaffolding\n */\nexport async function runSchema(args: string[]): Promise<void> {\n  const subcommand = args[0];\n\n  if (subcommand !== 'sync') {\n    throw new Error(\n      `Unknown schema subcommand: ${subcommand ?? '(none)'}. Usage: timber schema sync`\n    );\n  }\n\n  const { runSchemaSync, defaultCodecForSegment } = await import('./cli-schema-sync.js');\n  const result = runSchemaSync(process.cwd());\n\n  if (result.filesystemSegments.length === 0) {\n    console.log('[timber] No dynamic segments found in app/.');\n    return;\n  }\n\n  if (result.created) {\n    console.log(`[timber] Created app/schema.ts with ${result.addedSegments.length} segment(s):`);\n    for (const seg of result.addedSegments) {\n      console.log(`  + ${seg}: ${defaultCodecForSegment(seg)}`);\n    }\n    return;\n  }\n\n  if (result.addedSegments.length === 0 && result.removedSegments.length === 0) {\n    console.log('[timber] Schema is up to date — all segments are registered.');\n    return;\n  }\n\n  if (result.addedSegments.length > 0) {\n    console.log(`[timber] Added ${result.addedSegments.length} segment(s) to app/schema.ts:`);\n    for (const seg of result.addedSegments) {\n      console.log(`  + ${seg}: ${defaultCodecForSegment(seg)}`);\n    }\n  }\n\n  if (result.removedSegments.length > 0) {\n    console.log(\n      `[timber] Removed ${result.removedSegments.length} stale segment(s) from app/schema.ts:`\n    );\n    for (const seg of result.removedSegments) {\n      console.log(`  - ${seg}`);\n    }\n  }\n}\n\n// ─── Init Subcommand ─────────────────────────────────────────────────────────\n\n/**\n * `timber init` — write AGENTS.md (and CLAUDE.md pointer) to the project root\n * so AI coding agents can discover timber.js documentation and conventions.\n *\n * The content is read from the installed @timber-js/app package itself, so it\n * stays in sync with the installed version.\n */\nexport async function runInit(): Promise<void> {\n  const { readFileSync, writeFileSync, existsSync } = await import('node:fs');\n  const { resolve, dirname } = await import('node:path');\n  const { fileURLToPath } = await import('node:url');\n\n  const root = process.cwd();\n  const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');\n\n  const agentSkillPath = resolve(packageRoot, 'agent-skill.md');\n  if (!existsSync(agentSkillPath)) {\n    throw new Error(\n      'agent-skill.md not found in @timber-js/app package. ' +\n        'This may be a development install — try reinstalling.'\n    );\n  }\n\n  const agentSkill = readFileSync(agentSkillPath, 'utf-8');\n\n  const agentsPath = resolve(root, 'AGENTS.md');\n  const claudePath = resolve(root, 'CLAUDE.md');\n\n  const wrote: string[] = [];\n\n  if (existsSync(agentsPath)) {\n    console.log('[timber] AGENTS.md already exists — skipping (delete it first to regenerate)');\n  } else {\n    writeFileSync(agentsPath, agentSkill);\n    wrote.push('AGENTS.md');\n  }\n\n  if (existsSync(claudePath)) {\n    console.log('[timber] CLAUDE.md already exists — skipping (delete it first to regenerate)');\n  } else {\n    writeFileSync(claudePath, 'Read AGENTS.md for project context and conventions.\\n');\n    wrote.push('CLAUDE.md');\n  }\n\n  if (wrote.length > 0) {\n    console.log(\n      `[timber] Created ${wrote.join(' and ')} — AI agents can now discover timber.js docs.`\n    );\n    console.log('[timber] Full documentation: node_modules/@timber-js/app/docs/');\n  } else {\n    console.log('[timber] Nothing to do — both files already exist.');\n  }\n}\n\n// ─── Main Entry Point ────────────────────────────────────────────────────────\n\nasync function main(): Promise<void> {\n  const parsed = parseArgs(process.argv.slice(2));\n  const options: CommandOptions = { config: parsed.config };\n\n  switch (parsed.command) {\n    case 'dev':\n      await runDev(options);\n      break;\n    case 'build':\n      await runBuild(options);\n      break;\n    case 'preview':\n      await runPreview(options);\n      break;\n    case 'check':\n      await runCheck(options);\n      break;\n    case 'schema':\n      await runSchema(parsed.rest);\n      break;\n    case 'init':\n      await runInit();\n      break;\n  }\n}\n\n// Run main when executed as a CLI (not imported in tests).\n// The bin shim (bin/timber.mjs) does `import '../dist/cli.js'`, so\n// process.argv[1] points to the shim, not this file. We check both:\n// direct execution AND being imported by the timber bin shim.\nconst isDirectExecution =\n  typeof process !== 'undefined' &&\n  process.argv[1] &&\n  (import.meta.url.endsWith(process.argv[1]) ||\n    process.argv[1].endsWith('bin/timber.mjs') ||\n    process.argv[1].endsWith('bin/timber'));\n\nif (isDirectExecution) {\n  main().catch((err) => {\n    console.error(err.message);\n    process.exit(1);\n  });\n}\n"],"mappings":"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"}

package/dist/client/browser-entry/action-dispatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action-dispatch.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/action-dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AASH,wBAAgB,kBAAkB,IAAI,IAAI,CA+FzC"}
+{"version":3,"file":"action-dispatch.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/action-dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AASH,wBAAgB,kBAAkB,IAAI,IAAI,CA6GzC"}

package/dist/server/internal.js

@@ -1786,7 +1786,8 @@ async function serveStaticMetadataFile(metaMatch) {
 	const body = await readFile(file.filePath);
 	const headers = {
 		"Content-Type": isText ? `${contentType}; charset=utf-8` : contentType,
-		"Content-Length": String(body.byteLength)
+		"Content-Length": String(body.byteLength),
+		"Cache-Control": "public, max-age=14400, must-revalidate"
 	};
 	return new Response(body, {
 		status: 200,
@@ -2211,7 +2212,10 @@ async function handleRequest(config, req, method, path, pathIsCanonical) {
 			else body = String(handlerResult);
 			return new Response(body, {
 				status: 200,
-				headers: { "Content-Type": `${contentType}; charset=utf-8` }
+				headers: {
+					"Content-Type": `${contentType}; charset=utf-8`,
+					"Cache-Control": "public, max-age=14400, must-revalidate"
+				}
 			});
 		} catch (error) {
 			if (error instanceof RedirectSignal) return new Response(null, {