@timber-js/app 0.2.0-alpha.16 → 0.2.0-alpha.161

package/dist/cache/timber-cache.d.ts

@@ -1,21 +1,31 @@
 import type { CacheHandler, CacheOptions } from './index';
+/**
+ * Set the timeout for the module-level default singleflight.
+ * Called at framework boot with renderTimeoutMs from timber.config.ts so that
+ * cache calls without a per-call timeoutMs still get deadlock protection.
+ * See design/06-caching.md §"Singleflight Timeout — Deadlock Risk".
+ */
+export declare function setDefaultSingleflightTimeout(timeoutMs: number): void;
 /**
  * Creates a cached wrapper around an async function.
  *
- * - SHA-256 default keys with normalized JSON args
- * - Singleflight: concurrent misses → single execution
+ * - FNV-1a default keys with normalized JSON args
+ * - Singleflight: concurrent misses → single execution AND single
+ *   handler.set — the write happens inside the coalesced callback (TIM-1028)
+ * - Writes are skipped when the key/tags were invalidated while fn was in
+ *   flight, so explicit invalidation is never silently undone (TIM-1028)
  * - SWR: serve stale immediately, background refetch
  * - Tags as string[] or function of args
- * - No ALS dependency
+ * - The handler is resolved per invocation via `getHandler`, never captured
+ *   at wrapper-creation time — module-scope cache() wrappers created before
+ *   the framework's boot wiring calls setCacheHandler() still use the
+ *   configured handler once it arrives (TIM-1029)
+ * - No ALS dependency for correctness — cache() works outside a request
+ *   context. The waitUntil ALS bridge is read optionally so the SWR
+ *   background refetch survives handler return on Workers/Lambda.
  *
  * Cache hits/misses are recorded as OTEL span events on the enclosing
  * span (not child spans). The DevSpanProcessor reads these for dev log output.
  */
-export declare function createCache<Fn extends (...args: any[]) => Promise<any>>(fn: Fn, opts: CacheOptions<Fn>, handler: CacheHandler): (...args: Parameters<Fn>) => Promise<Awaited<ReturnType<Fn>>>;
-export declare namespace createCache {
-    var invalidate: (handler: CacheHandler, opts: {
-        key?: string;
-        tag?: string;
-    }) => Promise<void>;
-}
+export declare function createCache<Fn extends (...args: any[]) => Promise<any>>(fn: Fn, opts: CacheOptions<Fn>, getHandler: () => CacheHandler, stableId?: string): Fn;
 //# sourceMappingURL=timber-cache.d.ts.map

package/dist/cache/timber-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timber-cache.d.ts","sourceRoot":"","sources":["../../src/cache/timber-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAsC1D;;;;;;;;;;;GAWG;AAEH,wBAAgB,WAAW,CAAC,EAAE,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EACrE,EAAE,EAAE,EAAE,EACN,IAAI,EAAE,YAAY,CAAC,EAAE,CAAC,EACtB,OAAO,EAAE,YAAY,GACpB,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAyD/D;yBA7De,WAAW;8BAmEhB,YAAY,QACf;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,KACnC,OAAO,CAAC,IAAI,CAAC"}
+{"version":3,"file":"timber-cache.d.ts","sourceRoot":"","sources":["../../src/cache/timber-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAe1D;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAErE;AAoED;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,wBAAgB,WAAW,CAAC,EAAE,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EACrE,EAAE,EAAE,EAAE,EACN,IAAI,EAAE,YAAY,CAAC,EAAE,CAAC,EACtB,UAAU,EAAE,MAAM,YAAY,EAC9B,QAAQ,CAAC,EAAE,MAAM,GAChB,EAAE,CA8GJ"}

package/dist/cdn/cloudflare-purge.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Cloudflare CDN purge handler — purges by cache tag via the Cloudflare API.
+ *
+ * Requires Cloudflare Enterprise for tag-based purging.
+ * See https://developers.cloudflare.com/cache/how-to/purge-cache/purge-by-tags/
+ */
+import type { CdnPurgeHandler } from './purge-store';
+export interface CloudflarePurgeOptions {
+    /** Cloudflare zone ID. */
+    zoneId: string;
+    /** API token with Cache Purge permission. */
+    apiToken: string;
+    /** Override fetch for testing. */
+    fetch?: typeof globalThis.fetch;
+}
+export declare class CloudflarePurge implements CdnPurgeHandler {
+    private readonly zoneId;
+    private readonly apiToken;
+    private readonly _fetch;
+    constructor(opts: CloudflarePurgeOptions);
+    purgeTags(tags: string[]): Promise<void>;
+}
+//# sourceMappingURL=cloudflare-purge.d.ts.map

package/dist/cdn/cloudflare-purge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare-purge.d.ts","sourceRoot":"","sources":["../../src/cdn/cloudflare-purge.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,MAAM,WAAW,sBAAsB;IACrC,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED,qBAAa,eAAgB,YAAW,eAAe;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;gBAErC,IAAI,EAAE,sBAAsB;IAMlC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAoB/C"}

package/dist/cdn/fastly-purge.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Fastly CDN purge handler — purges by surrogate key via the Fastly API.
+ *
+ * See https://www.fastly.com/documentation/reference/api/purging/
+ */
+import type { CdnPurgeHandler } from './purge-store';
+export interface FastlyPurgeOptions {
+    /** Fastly service ID. */
+    serviceId: string;
+    /** Fastly API token with purge permission. */
+    apiToken: string;
+    /** Use soft purge (marks as stale instead of immediate delete). Default: false. */
+    softPurge?: boolean;
+    /** Override fetch for testing. */
+    fetch?: typeof globalThis.fetch;
+}
+export declare class FastlyPurge implements CdnPurgeHandler {
+    private readonly serviceId;
+    private readonly apiToken;
+    private readonly softPurge;
+    private readonly _fetch;
+    constructor(opts: FastlyPurgeOptions);
+    purgeTags(tags: string[]): Promise<void>;
+}
+//# sourceMappingURL=fastly-purge.d.ts.map

package/dist/cdn/fastly-purge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fastly-purge.d.ts","sourceRoot":"","sources":["../../src/cdn/fastly-purge.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,MAAM,WAAW,kBAAkB;IACjC,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,mFAAmF;IACnF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,kCAAkC;IAClC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED,qBAAa,WAAY,YAAW,eAAe;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAU;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;gBAErC,IAAI,EAAE,kBAAkB;IAO9B,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CA8B/C"}

package/dist/cdn/headers.d.ts

@@ -0,0 +1,97 @@
+/**
+ * CDN header helpers — pure functions that build Cache-Control,
+ * CDN-Cache-Control, Surrogate-Control, and Surrogate-Key header values.
+ *
+ * These are developer-elected utilities for wiring CDN caching in
+ * proxy.ts / middleware.ts. The framework never sets these automatically.
+ * See design/25-production-deployments.md §Layer 2.
+ */
+export interface CacheControlOptions {
+    /** Mark the response as publicly cacheable (CDN, shared caches). */
+    public?: boolean;
+    /** Mark the response as private (browser cache only, not CDN). */
+    private?: boolean;
+    /** Max freshness in seconds for the browser/client. */
+    maxAge?: number;
+    /** Max freshness in seconds for shared caches (CDN, proxy). Overrides maxAge for CDNs. */
+    sMaxAge?: number;
+    /** Serve stale while revalidating in the background (seconds). */
+    staleWhileRevalidate?: number;
+    /** Serve stale on upstream error (seconds). */
+    staleIfError?: number;
+    /** Response must not be stored by any cache. */
+    noStore?: boolean;
+    /** Caches must revalidate before using a stored response. */
+    noCache?: boolean;
+    /** Caches must revalidate once stale — no serving stale without checking origin. */
+    mustRevalidate?: boolean;
+    /** Response will not change — allows aggressive caching. Pair with hashed URLs. */
+    immutable?: boolean;
+}
+/**
+ * Build a `Cache-Control` header value.
+ *
+ * ```ts
+ * ctx.headers.set('Cache-Control', cacheControl({
+ *   public: true,
+ *   maxAge: 300,
+ *   staleWhileRevalidate: 60,
+ * }));
+ * ```
+ */
+export declare function cacheControl(opts: CacheControlOptions): string;
+export interface SurrogateControlOptions {
+    /** Max freshness in seconds for the surrogate (CDN). */
+    maxAge?: number;
+    /** Do not store in surrogate cache. */
+    noStore?: boolean;
+    /** Serve stale while revalidating (seconds). */
+    staleWhileRevalidate?: number;
+    /** Serve stale on error (seconds). */
+    staleIfError?: number;
+}
+/**
+ * Build a `Surrogate-Control` header value (Fastly, Akamai, Varnish).
+ *
+ * ```ts
+ * ctx.headers.set('Surrogate-Control', surrogateControl({ maxAge: 3600 }));
+ * ```
+ */
+export declare function surrogateControl(opts: SurrogateControlOptions): string;
+/**
+ * Build a `CDN-Cache-Control` header value (Cloudflare).
+ * Same directive syntax as Surrogate-Control but recognized by Cloudflare.
+ *
+ * ```ts
+ * ctx.headers.set('CDN-Cache-Control', cdnCacheControl({ maxAge: 3600 }));
+ * ```
+ */
+export declare function cdnCacheControl(opts: SurrogateControlOptions): string;
+/**
+ * Build a `Surrogate-Key` header value — space-separated tags for CDN
+ * tag-based purging (Fastly, Cloudflare Enterprise, Akamai).
+ *
+ * Tags are deduplicated. Tags must not contain spaces or double quotes
+ * (these are separators/delimiters in the header format).
+ *
+ * ```ts
+ * ctx.headers.set('Surrogate-Key', surrogateKey(['products', `product:${id}`]));
+ * ```
+ */
+export declare function surrogateKey(tags: string[]): string;
+/**
+ * Build a `Cache-Tag` header value — comma-separated tags for Cloudflare
+ * Workers Cache tag-based purging. Available on ALL Cloudflare plans.
+ *
+ * Tags are deduplicated. Tags must not contain commas (the delimiter).
+ * Maximum tag length is 1024 characters per Cloudflare's limits.
+ *
+ * Use this instead of `surrogateKey()` when using Cloudflare Workers Cache
+ * (ctx.cache.purge). Workers Cache reads `Cache-Tag`, not `Surrogate-Key`.
+ *
+ * ```ts
+ * ctx.headers.set('Cache-Tag', cacheTag(['products', `product:${id}`]));
+ * ```
+ */
+export declare function cacheTag(tags: string[]): string;
+//# sourceMappingURL=headers.d.ts.map

package/dist/cdn/headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.d.ts","sourceRoot":"","sources":["../../src/cdn/headers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,mBAAmB;IAClC,oEAAoE;IACpE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kEAAkE;IAClE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,+CAA+C;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,oFAAoF;IACpF,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mFAAmF;IACnF,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAuB9D;AAED,MAAM,WAAW,uBAAuB;IACtC,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gDAAgD;IAChD,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,sCAAsC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,uBAAuB,GAAG,MAAM,CAQtE;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,uBAAuB,GAAG,MAAM,CAErE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAOnD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAU/C"}

package/dist/cdn/index.d.ts

@@ -0,0 +1,5 @@
+export { cacheControl, surrogateKey, surrogateControl, cdnCacheControl, cacheTag } from './headers';
+export type { CacheControlOptions, SurrogateControlOptions } from './headers';
+export { setCdnPurgeHandler, getCdnPurgeHandler } from './purge-store';
+export type { CdnPurgeHandler } from './purge-store';
+//# sourceMappingURL=index.d.ts.map

package/dist/cdn/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cdn/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACpG,YAAY,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AAE9E,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACvE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/dist/cdn/purge-store.d.ts

@@ -0,0 +1,23 @@
+/**
+ * CDN purge handler singleton — same pattern as cache/handler-store.ts.
+ *
+ * Set via timber.config.ts or setCdnPurgeHandler() at boot. When set,
+ * cache.invalidate({ tag }) also triggers CDN purge for the invalidated
+ * tags, so revalidateTag() composes with CDN caching out of the box.
+ *
+ * See design/25-production-deployments.md §Layer 2.
+ */
+export interface CdnPurgeHandler {
+    /**
+     * Purge the given cache tags from the CDN.
+     * Called by cache.invalidate when a tag is invalidated.
+     */
+    purgeTags(tags: string[]): Promise<void>;
+}
+/** Install a CDN purge handler. Called by the framework at boot from timber.config.ts. */
+export declare function setCdnPurgeHandler(h: CdnPurgeHandler): void;
+/** Get the current CDN purge handler, if configured. */
+export declare function getCdnPurgeHandler(): CdnPurgeHandler | undefined;
+/** @internal — reset for tests only. */
+export declare function _resetCdnPurgeHandler(): void;
+//# sourceMappingURL=purge-store.d.ts.map

package/dist/cdn/purge-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"purge-store.d.ts","sourceRoot":"","sources":["../../src/cdn/purge-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C;AAID,0FAA0F;AAC1F,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,eAAe,GAAG,IAAI,CAE3D;AAED,wDAAwD;AACxD,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,SAAS,CAEhE;AAED,wCAAwC;AACxC,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C"}

package/dist/cdn/workers-cache-purge.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Cloudflare Workers Cache purge handler — purges by cache tag via
+ * ctx.cache.purge() on the ExecutionContext.
+ *
+ * Available on ALL Cloudflare plans (no Enterprise requirement).
+ * No API token needed — uses the Workers runtime's built-in cache API.
+ *
+ * Auto-wired by the Cloudflare adapter when no user-configured CDN
+ * purge handler is set. Uses the Workers Cache ALS bridge to access
+ * ctx.cache from within the request context.
+ */
+import type { CdnPurgeHandler } from './purge-store';
+export declare class WorkersCachePurge implements CdnPurgeHandler {
+    purgeTags(tags: string[]): Promise<void>;
+}
+//# sourceMappingURL=workers-cache-purge.d.ts.map

package/dist/cdn/workers-cache-purge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workers-cache-purge.d.ts","sourceRoot":"","sources":["../../src/cdn/workers-cache-purge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGrD,qBAAa,iBAAkB,YAAW,eAAe;IACjD,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAa/C"}

package/dist/cli-schema-sync.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `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
+ */
+/**
+ * Collect all unique bracket-keyed dynamic segment names from the route tree.
+ * Returns entries like '[artistSlug]', '[...slug]', '[[...topic]]'.
+ */
+export declare function collectDynamicSegments(appDir: string): string[];
+/**
+ * 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 declare function findSegmentParamsBlock(content: string): {
+    openBrace: number;
+    closeBrace: number;
+} | null;
+/**
+ * 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 declare function parseExistingSchemaKeys(content: string): string[];
+/**
+ * Find the schema file path if it exists.
+ */
+export declare function findSchemaFile(appDir: string): string | undefined;
+export declare function defaultCodecForSegment(seg: string): string;
+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 declare function runSchemaSync(projectRoot: string): SchemaSyncResult;
+//# sourceMappingURL=cli-schema-sync.d.ts.map

package/dist/cli-schema-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-schema-sync.d.ts","sourceRoot":"","sources":["../src/cli-schema-sync.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAK/D;AAoED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,GACd;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAoBlD;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAajE;AAKD;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMjE;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI1D;AA6ID,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,iDAAiD;IACjD,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,gCAAgC;IAChC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,4DAA4D;IAC5D,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,6CAA6C;IAC7C,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,CA8DnE"}

package/dist/cli.d.ts

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
-declare const COMMANDS: readonly ["dev", "build", "preview", "check"];
+declare const COMMANDS: readonly ["dev", "build", "preview", "check", "schema", "init"];
 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 {
     config?: string;
@@ -11,6 +13,11 @@ 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 declare function parseArgs(args: string[]): ParsedArgs;
 /** @internal Dependency injection for testing. */
@@ -21,7 +28,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 declare function runDev(options: CommandOptions, _deps?: ViteDeps): Promise<void>;
 /**
@@ -39,6 +51,11 @@ export declare function resolvePreviewStrategy(adapter: import('./adapters/types
  * 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 declare function runPreview(options: CommandOptions, _deps?: ViteDeps): Promise<void>;
 /**
@@ -46,5 +63,20 @@ export declare function runPreview(options: CommandOptions, _deps?: ViteDeps): P
  * Runs tsgo --noEmit for type checking.
  */
 export declare function runCheck(options: CommandOptions): Promise<void>;
+/**
+ * `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 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,+CAAgD,CAAC;AAC/D,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;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAuBpD;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;;;GAGG;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;AA2BD;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBzF;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAerE"}
+{"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

@@ -4,29 +4,48 @@ var COMMANDS = [
 	"dev",
 	"build",
 	"preview",
-	"check"
+	"check",
+	"schema",
+	"init"
 ];
 /**
 * 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.
 */
 function parseArgs(args) {
-	if (args.length === 0) throw new Error("No command provided. Usage: timber <dev|build|preview|check> [--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;
-	for (let i = 1; i < args.length; i++) if (args[i] === "--config" || args[i] === "-c") {
-		config = args[++i];
-		if (!config) throw new Error("--config requires a path argument");
+	const rest = [];
+	for (let i = 1; i < args.length; i++) {
+		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("-")) 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" || command === "init") rest.push(arg);
+		else throw new Error(`Unexpected argument: ${arg}. Usage: timber ${command} [--config <path>]`);
 	}
 	return {
 		command,
-		config
+		config,
+		rest
 	};
 }
 /**
 * 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.
 */
 async function runDev(options, _deps) {
 	const server = await (_deps?.createServer ?? (await import("vite")).createServer)({ configFile: options.config });
@@ -50,39 +69,22 @@ function resolvePreviewStrategy(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) {
-	const { existsSync } = await import("node:fs");
-	const { join } = await import("node:path");
-	const { pathToFileURL } = await import("node:url");
-	for (const name of [
-		"timber.config.ts",
-		"timber.config.js",
-		"timber.config.mjs"
-	]) {
-		const configPath = join(root, name);
-		if (existsSync(configPath)) {
-			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.
 */
 async function runPreview(options, _deps) {
-	const { join } = await import("node:path");
+	const { loadTimberConfigFile, resolveBuildDir } = await import("./_chunks/plugin-context-DeAxFRMq.js").then((n) => n.i);
 	const root = process.cwd();
-	const config = await loadTimberConfig(root).catch(() => null);
+	const config = loadTimberConfigFile(root);
 	const adapter = config?.adapter;
 	if (resolvePreviewStrategy(adapter) === "adapter") {
-		const buildDir = join(root, "dist");
+		const buildDir = resolveBuildDir(root, config?.buildDir);
 		const timberConfig = { output: config?.output ?? "server" };
 		await adapter.preview(timberConfig, buildDir);
 		return;
@@ -104,6 +106,72 @@ async function runCheck(options) {
 		});
 	});
 }
+/**
+* `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
+*/
+async function runSchema(args) {
+	const subcommand = args[0];
+	if (subcommand !== "sync") throw new Error(`Unknown schema subcommand: ${subcommand ?? "(none)"}. Usage: timber schema sync`);
+	const { runSchemaSync, defaultCodecForSegment } = await import("./_chunks/cli-schema-sync-NfLbLnDw.js").then((n) => n.t);
+	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}`);
+	}
+}
+/**
+* `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 };
@@ -120,6 +188,12 @@ async function main() {
 		case "check":
 			await runCheck(options);
 			break;
+		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) => {
@@ -127,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 };
+export { parseArgs, resolvePreviewStrategy, runBuild, runCheck, runDev, runInit, runPreview, runSchema };
 
 //# sourceMappingURL=cli.js.map