@pithy-sh/core 0.1.2 → 0.1.4

package/dist/kv/kv.js

@@ -0,0 +1,261 @@
+import { InternalError, NotFoundError, messageOf } from "../error/pithyError.js";
+import { noopLogger } from "../logger/logger.js";
+//#region src/kv/kv.ts
+/** Cloudflare's hard limit on a KV entry's metadata, in bytes. */
+const KV_METADATA_MAX_BYTES = 1024;
+const encoder = new TextEncoder();
+function byteLength(value) {
+	return encoder.encode(value).length;
+}
+/**
+* Wrap a metadata schema with KV's size limit.
+*
+* WARNING: metadata travels with **every** `list` entry and is capped at
+* {@link KV_METADATA_MAX_BYTES} bytes serialized. It is for small, list-time
+* fields you want without reading each value — a status flag, a type, a
+* timestamp — never a payload. This refinement fails a value that would exceed
+* the cap, turning a late KV rejection into an early, clear validation error.
+*/
+function kvMetadata(schema) {
+	return schema.refine((value) => byteLength(JSON.stringify(value)) <= KV_METADATA_MAX_BYTES, { message: `KV metadata exceeds ${KV_METADATA_MAX_BYTES} bytes serialized. Keep it tiny — it rides on every list entry.` });
+}
+/**
+* Validate a {@link TypedKvConfig} at construction — config is a boundary, so it
+* is checked, not trusted. Catches the misconfigurations the type system can't
+* (or won't, for JS callers and casts): an empty namespace, a separator that
+* collides with the prefix, a key with no segments, `deriveMetadata` without a
+* `metadata` schema to validate against, or a non-positive default TTL.
+*/
+function assertValidConfig(config) {
+	if (config.prefix.length === 0) throw new InternalError({ message: "TypedKv config: prefix must be a non-empty capability namespace." });
+	const separator = config.separator ?? ":";
+	if (separator.length === 0) throw new InternalError({ message: "TypedKv config: separator must be a non-empty string." });
+	if (config.prefix.includes(separator)) throw new InternalError({ message: `TypedKv config: prefix "${config.prefix}" must not contain the separator "${separator}".` });
+	if (Object.keys(config.key.shape).length === 0) throw new InternalError({ message: "TypedKv config: key must declare at least one segment." });
+	if (config.deriveMetadata !== void 0 && config.metadata === void 0) throw new InternalError({ message: "TypedKv config: deriveMetadata requires a metadata schema to validate the derived value." });
+	if (config.ttlSeconds !== void 0 && config.ttlSeconds <= 0) throw new InternalError({ message: "TypedKv config: ttlSeconds must be positive." });
+}
+/**
+* Typed, validated access to one Workers KV namespace.
+*
+* Keys are structured: a fixed capability `prefix` followed by ordered,
+* Zod-validated segments — so a single store models `pages:<uuid>` or
+* `assets:<assetType>:<uuid>` and `list` can scope by any leading run of those
+* segments. Values are validated on the way in and out; there is no untyped
+* `JSON.parse`. Metadata is validated too and rides along with `list`; with
+* `deriveMetadata` the value is the source of truth and `list` rebuilds metadata
+* that external edits have dropped.
+*/
+var TypedKv = class {
+	#namespace;
+	#prefix;
+	#keySchema;
+	#valueSchema;
+	#metadataSchema;
+	#deriveMetadata;
+	#separator;
+	#defaultTtlSeconds;
+	#segmentNames;
+	#logger;
+	constructor(namespace, config, options) {
+		assertValidConfig(config);
+		this.#namespace = namespace;
+		this.#prefix = config.prefix;
+		this.#keySchema = config.key;
+		this.#valueSchema = config.value;
+		this.#metadataSchema = config.metadata;
+		this.#deriveMetadata = config.deriveMetadata;
+		this.#separator = config.separator ?? ":";
+		this.#defaultTtlSeconds = config.ttlSeconds;
+		this.#segmentNames = Object.keys(config.key.shape);
+		this.#logger = options?.logger ?? noopLogger;
+	}
+	/** Build the full physical KV key (name) from validated segments. */
+	name(key) {
+		const parsed = this.#keySchema.parse(key);
+		const segments = this.#segmentNames.map((segment) => this.#segment(segment, parsed[segment]));
+		return [this.#prefix, ...segments].join(this.#separator);
+	}
+	/**
+	* Read and validate the value at `key`. Returns `null` on a miss. The stored
+	* JSON is parsed and validated against the schema before it is returned.
+	*/
+	async get(key) {
+		const raw = await this.#namespace.get(this.name(key), "text");
+		return raw === null ? null : this.#parseValue(raw);
+	}
+	/** Read the value at `key` together with its validated metadata. `null` on a miss. */
+	async getWithMetadata(key) {
+		const result = await this.#namespace.getWithMetadata(this.name(key), "text");
+		if (result.value === null) return null;
+		return {
+			value: this.#parseValue(result.value),
+			metadata: this.#parseMetadata(result.metadata)
+		};
+	}
+	/**
+	* Validate `value` (and any `metadata`) against their schemas, then store the
+	* value as JSON under the namespaced key. With `deriveMetadata`, metadata is
+	* computed from the value unless overridden per call. Throws (before writing)
+	* on an invalid value, invalid metadata, or metadata over
+	* {@link KV_METADATA_MAX_BYTES}. A per-call `ttlSeconds` overrides the default.
+	*/
+	async put(key, value, options = {}) {
+		const validated = this.#valueSchema.parse(value);
+		const putOptions = {};
+		const ttlSeconds = options.ttlSeconds ?? this.#defaultTtlSeconds;
+		if (ttlSeconds !== void 0) putOptions.expirationTtl = ttlSeconds;
+		const metadata = this.#resolveMetadata(validated, options.metadata);
+		if (metadata !== void 0) putOptions.metadata = metadata;
+		await this.#namespace.put(this.name(key), JSON.stringify(validated), putOptions);
+	}
+	/**
+	* Partially update the value at `key`: read it, merge `changes` over the
+	* current fields, validate the merged result, and write it back. Returns the
+	* merged value. Throws if the key does not exist — there is nothing to merge.
+	*
+	* Metadata stays correct: a `deriveMetadata` store recomputes it from the
+	* merged value; an explicit-metadata store preserves the current metadata
+	* (pass `metadata` to override). TTL resets to the store default unless
+	* `ttlSeconds` is given.
+	*
+	* WARNING: KV has no compare-and-set, so this read-modify-write is
+	* last-write-wins. Concurrent patches to the same key can lose updates — do
+	* not use it where atomicity matters.
+	*/
+	async patch(key, changes, options = {}) {
+		const existing = await this.getWithMetadata(key);
+		if (existing === null) throw new NotFoundError({ message: `Cannot patch ${this.name(key)}: no value to update.` });
+		const merged = this.#valueSchema.parse({
+			...existing.value,
+			...changes
+		});
+		const putOptions = { ...options };
+		if (this.#deriveMetadata === void 0 && options.metadata === void 0 && existing.metadata !== null) putOptions.metadata = existing.metadata;
+		await this.put(key, merged, putOptions);
+		return merged;
+	}
+	/** Delete the value at `key`. A miss is a no-op. */
+	async delete(key) {
+		await this.#namespace.delete(this.name(key));
+	}
+	/**
+	* List entries under a leading run of key segments. Each entry carries its
+	* parsed key segments and validated metadata — no value reads, unless
+	* `deriveMetadata` is configured and an entry's metadata is missing, in which
+	* case it is rebuilt from the value and written back. Pass `options.prefix` to
+	* scope (e.g. `{ assetType: "photo" }`); omit to list the whole namespace.
+	*/
+	async list(options = {}) {
+		const result = await this.#namespace.list({
+			prefix: this.#listPrefix(options.prefix),
+			limit: options.limit,
+			cursor: options.cursor
+		});
+		return {
+			keys: await Promise.all(result.keys.map(async (entry) => ({
+				name: entry.name,
+				key: this.#splitKey(entry.name),
+				metadata: await this.#resolveListMetadata(entry),
+				expiration: entry.expiration
+			}))),
+			cursor: result.list_complete ? void 0 : result.cursor,
+			listComplete: result.list_complete
+		};
+	}
+	/**
+	* Resolve one list entry's metadata: parse what is stored, else self-heal it
+	* from the value when `deriveMetadata` is configured. A single entry with
+	* corrupt or schema-incompatible metadata/value must not abort the whole
+	* listing — it degrades to `null` metadata while the key is still returned.
+	*/
+	async #resolveListMetadata(entry) {
+		try {
+			const stored = this.#parseMetadata(entry.metadata);
+			if (stored !== null) return stored;
+			const derive = this.#deriveMetadata;
+			const metadataSchema = this.#metadataSchema;
+			if (derive === void 0 || metadataSchema === void 0) return null;
+			return await this.#rebuildMetadata(entry.name, entry.expiration, derive, metadataSchema);
+		} catch {
+			return null;
+		}
+	}
+	/** Resolve the metadata to store: explicit wins, else derive, else none. */
+	#resolveMetadata(value, explicit) {
+		if (this.#metadataSchema === void 0) return void 0;
+		let candidate;
+		if (explicit !== void 0) candidate = explicit;
+		else if (this.#deriveMetadata !== void 0) candidate = this.#deriveMetadata(value);
+		else return void 0;
+		return this.#validateMetadata(this.#metadataSchema, candidate);
+	}
+	/** Read the value, re-derive metadata, and write it back — preserving value bytes and expiration. */
+	async #rebuildMetadata(name, expiration, derive, metadataSchema) {
+		const raw = await this.#namespace.get(name, "text");
+		if (raw === null) return null;
+		const derived = derive(this.#parseValue(raw));
+		if (derived === null || derived === void 0) return null;
+		const metadata = this.#validateMetadata(metadataSchema, derived);
+		try {
+			const putOptions = { metadata };
+			if (expiration !== void 0) putOptions.expiration = expiration;
+			await this.#namespace.put(name, raw, putOptions);
+		} catch (error) {
+			this.#logger.warn("kv metadata heal write-back failed", {
+				key: name,
+				detail: messageOf(error)
+			});
+		}
+		return metadata;
+	}
+	/** Decode a stored value: JSON-parse, then validate against the value schema. */
+	#parseValue(raw) {
+		return this.#valueSchema.parse(JSON.parse(raw));
+	}
+	/** Validate a metadata candidate against the schema and the KV size cap. */
+	#validateMetadata(schema, candidate) {
+		const parsed = schema.parse(candidate);
+		const bytes = byteLength(JSON.stringify(parsed));
+		if (bytes > 1024) throw new InternalError({ message: `KV metadata is ${bytes} bytes; the limit is ${KV_METADATA_MAX_BYTES}. Keep metadata small.` });
+		return parsed;
+	}
+	/** Stringify and guard one key segment. */
+	#segment(name, value) {
+		const segment = String(value);
+		if (segment.includes(this.#separator)) throw new InternalError({
+			message: `Key segment "${name}" must not contain the separator "${this.#separator}".`,
+			detail: `Offending value for "${name}": ${segment}`
+		});
+		return segment;
+	}
+	/** Build the physical prefix string for a `list`, enforcing a proper, contiguous leading run. */
+	#listPrefix(parts) {
+		const trailing = `${this.#prefix}${this.#separator}`;
+		if (!parts) return trailing;
+		const provided = this.#keySchema.partial().parse(parts);
+		const present = this.#segmentNames.filter((name) => provided[name] !== void 0);
+		if (present.length === 0) return trailing;
+		if (present.length === this.#segmentNames.length) throw new InternalError({ message: "list prefix is a full key; use get() or getWithMetadata() for an exact key." });
+		const leading = this.#segmentNames.slice(0, present.length);
+		if (present.join(this.#separator) !== leading.join(this.#separator)) throw new InternalError({ message: `list prefix must be a leading run of key segments [${this.#segmentNames.join(", ")}]; got [${present.join(", ")}].` });
+		const segments = leading.map((name) => this.#segment(name, provided[name]));
+		return `${[this.#prefix, ...segments].join(this.#separator)}${this.#separator}`;
+	}
+	/** Split a physical key back into its named segments. Safe: segments never contain the separator. */
+	#splitKey(name) {
+		const segments = name.slice(this.#prefix.length + this.#separator.length).split(this.#separator);
+		const out = {};
+		this.#segmentNames.forEach((segmentName, index) => {
+			out[segmentName] = segments[index] ?? "";
+		});
+		return out;
+	}
+	/** Validate stored metadata against the schema; `null` when absent or unconfigured. */
+	#parseMetadata(raw) {
+		if (this.#metadataSchema === void 0 || raw === null || raw === void 0) return null;
+		return this.#metadataSchema.parse(raw);
+	}
+};
+//#endregion
+export { KV_METADATA_MAX_BYTES, TypedKv, assertValidConfig, kvMetadata };

package/dist/kv/namespaces.d.ts

@@ -0,0 +1,58 @@
+import type { z } from "zod";
+import type { Capability } from "../capability/capability";
+import { type BindingGroup } from "../capability/compose";
+import type { Logger } from "../logger/logger";
+import { TypedKv, type TypedKvConfig } from "./kv";
+/**
+ * One typed store within a KV namespace — a {@link TypedKvConfig} (prefix, key, value, metadata).
+ * The peer of a D1 table: the binding lives on the enclosing namespace, not the store.
+ */
+export type KvStoreSpec<V extends z.ZodType = z.ZodType, K extends z.ZodObject = z.ZodObject, M extends z.ZodType = z.ZodType> = TypedKvConfig<V, K, M>;
+/** A capability's stores for one namespace: store name → {@link KvStoreSpec}. */
+export type KvStoreSpecMap = Record<string, KvStoreSpec>;
+/**
+ * One named KV namespace a capability registers — the peer of a {@link DatabaseSpec}: the `binding`
+ * it lives in plus the named stores it holds. `createBackend` serves each store as a live
+ * {@link TypedKv} on `c.var.kv.<namespace>.<store>`. Capabilities targeting the same namespace name
+ * merge their stores.
+ */
+export interface KvNamespaceSpec<Stores extends KvStoreSpecMap = KvStoreSpecMap> {
+    /** The KV binding name in the Worker env this namespace lives in. */
+    binding: string;
+    /** The named typed stores in this namespace (store name → spec). */
+    stores: Stores;
+}
+/** A capability's KV namespaces: namespace name → {@link KvNamespaceSpec}. */
+export type KvNamespaceSpecMap = Record<string, KvNamespaceSpec>;
+/**
+ * The typed KV registry exposed on `c.var.kv`: namespace name → store name → live {@link TypedKv},
+ * preserving each store's value/key/metadata types — so `c.var.kv.cms.pages.get(...)` returns the
+ * page type, validated, and `c.var.kv.audit.pages` is a distinct store with no name conflict.
+ */
+export type KvRegistry<Namespaces extends KvNamespaceSpecMap> = {
+    [Ns in keyof Namespaces]: Namespaces[Ns] extends KvNamespaceSpec<infer Stores> ? {
+        [S in keyof Stores]: Stores[S] extends KvStoreSpec<infer V, infer K, infer M> ? TypedKv<V, K, M> : never;
+    } : never;
+};
+/** The merged namespaces: each namespace name → its binding and the union of every capability's stores. */
+export type MergedKvNamespaces = Record<string, BindingGroup<KvStoreSpec>>;
+/**
+ * Merge every capability's `kvNamespaces` into one map keyed by namespace name. Capabilities
+ * targeting the same name union their stores; a store claimed twice in one namespace, or a namespace
+ * name bound to two bindings, throws at assembly. Mirrors `composeDatabases`.
+ */
+export declare function composeKv(capabilities: Capability[]): MergedKvNamespaces;
+/** A registry of live stores keyed by namespace then store name; the per-request value of `c.var.kv`. */
+type LiveStore = TypedKv<z.ZodType, z.ZodObject, z.ZodType>;
+type LiveKvRegistry = Record<string, Record<string, LiveStore>>;
+/**
+ * Build the per-request KV registry from the merged namespaces and the request's env. Each store is
+ * constructed lazily on first access — a request that never touches `c.var.kv.cms.fragments` never
+ * builds it (mirroring Leed's lazy `KVProvider` getters) — and the namespace's binding is read from
+ * the per-request env at access time. `logger` is the request logger (`c.var.log`) each store routes
+ * its observable best-effort failures through — notably the `list` self-heal write-back; it defaults to
+ * the no-op logger so a store built outside a request still constructs.
+ */
+export declare function buildKvRegistry(env: Record<string, unknown>, namespaces: MergedKvNamespaces, logger?: Logger): LiveKvRegistry;
+export {};
+//# sourceMappingURL=namespaces.d.ts.map

package/dist/kv/namespaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"namespaces.d.ts","sourceRoot":"","sources":["../../src/kv/namespaces.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,KAAK,YAAY,EAA2C,MAAM,uBAAuB,CAAC;AACnG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE/C,OAAO,EAAE,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,MAAM,CAAC;AAEnD;;;GAGG;AACH,MAAM,MAAM,WAAW,CACrB,CAAC,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,EAC/B,CAAC,SAAS,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,EACnC,CAAC,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,IAC7B,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AAE3B,iFAAiF;AACjF,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,MAAM,SAAS,cAAc,GAAG,cAAc;IAC7E,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,8EAA8E;AAC9E,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAEjE;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,UAAU,SAAS,kBAAkB,IAAI;KAC7D,EAAE,IAAI,MAAM,UAAU,GAAG,UAAU,CAAC,EAAE,CAAC,SAAS,eAAe,CAAC,MAAM,MAAM,CAAC,GAC1E;SAAG,CAAC,IAAI,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,SAAS,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK;KAAE,GAC5G,KAAK;CACV,CAAC;AAEF,2GAA2G;AAC3G,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,WAAW,CAAC,CAAC,CAAC;AAE3E;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,YAAY,EAAE,UAAU,EAAE,GAAG,kBAAkB,CAOxE;AAED,yGAAyG;AACzG,KAAK,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;AAC5D,KAAK,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;AAEhE;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,UAAU,EAAE,kBAAkB,EAC9B,MAAM,GAAE,MAAmB,GAC1B,cAAc,CAiBhB"}

package/dist/kv/namespaces.js

@@ -0,0 +1,40 @@
+import { bindingGroupsFrom, composeBindingGroups } from "../capability/compose.js";
+import { noopLogger } from "../logger/logger.js";
+import { TypedKv } from "./kv.js";
+//#region src/kv/namespaces.ts
+/**
+* Merge every capability's `kvNamespaces` into one map keyed by namespace name. Capabilities
+* targeting the same name union their stores; a store claimed twice in one namespace, or a namespace
+* name bound to two bindings, throws at assembly. Mirrors `composeDatabases`.
+*/
+function composeKv(capabilities) {
+	return composeBindingGroups(capabilities, (cap) => bindingGroupsFrom(cap.kvNamespaces, (ns) => ns.stores), "KV namespace", "store");
+}
+/**
+* Build the per-request KV registry from the merged namespaces and the request's env. Each store is
+* constructed lazily on first access — a request that never touches `c.var.kv.cms.fragments` never
+* builds it (mirroring Leed's lazy `KVProvider` getters) — and the namespace's binding is read from
+* the per-request env at access time. `logger` is the request logger (`c.var.log`) each store routes
+* its observable best-effort failures through — notably the `list` self-heal write-back; it defaults to
+* the no-op logger so a store built outside a request still constructs.
+*/
+function buildKvRegistry(env, namespaces, logger = noopLogger) {
+	const registry = {};
+	for (const [namespace, group] of Object.entries(namespaces)) {
+		const stores = {};
+		for (const [name, spec] of Object.entries(group.items)) {
+			let instance;
+			Object.defineProperty(stores, name, {
+				enumerable: true,
+				get() {
+					if (!instance) instance = new TypedKv(env[group.binding], spec, { logger });
+					return instance;
+				}
+			});
+		}
+		registry[namespace] = stores;
+	}
+	return registry;
+}
+//#endregion
+export { buildKvRegistry, composeKv };

package/dist/logger/local.d.ts

@@ -0,0 +1,41 @@
+import { type Logger } from "./logger";
+import type { LogLevel } from "./record";
+/**
+ * Mode 1 — local diagnostics. One unified diagnostic layer for the `pithy` CLI process and a Worker
+ * running under `pithy dev` / `wrangler dev`. Human-readable and (optionally) colorized for a person at
+ * a terminal, or a `--json` structured line stream for agents and CI. This is *diagnostic logging only*
+ * — interactive CLI UX (prompts, spinners, `PithyError` rendering) stays on the CLI's `style.ts`.
+ */
+/**
+ * Level-keyed color functions the local adapter paints with. Injected, not hard-coded: core stays free
+ * of ANSI, and the CLI passes its `style.ts` seam so all CLI color still flows through one place. Every
+ * entry is optional; a missing one renders plain.
+ */
+export interface LocalPalette {
+    debug?: (text: string) => string;
+    info?: (text: string) => string;
+    warn?: (text: string) => string;
+    error?: (text: string) => string;
+    /** Dimmed secondary text — the namespace, fields, and error detail. */
+    dim?: (text: string) => string;
+}
+/** Options for {@link createLocalLogger}. */
+export interface LocalLoggerOptions {
+    /** The threshold. Defaults to `debug` — local diagnostics are verbose by default. */
+    level?: LogLevel;
+    /** Emit each record as a `JSON.stringify` line instead of the human format — the agent/CI stream. */
+    json?: boolean;
+    /** Where a formatted line goes. Defaults to `console.error` (stderr under Node), so diagnostics never pollute a command's stdout. */
+    write?: (line: string) => void;
+    /** Optional color functions (the CLI injects its `style.ts` seam). Omitted → plain text. */
+    palette?: LocalPalette;
+    /** The clock, injectable for tests. */
+    now?: () => number;
+}
+/**
+ * Build a Mode 1 local logger. Same interface as every other Pithy logger; the sink either renders a
+ * human line (default, colorized when a palette is injected) or a `--json` structured line. Writes to
+ * `stderr` by default so a command's machine-readable stdout stays clean.
+ */
+export declare function createLocalLogger(options?: LocalLoggerOptions): Logger;
+//# sourceMappingURL=local.d.ts.map

package/dist/logger/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/logger/local.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAa,MAAM,UAAU,CAAC;AAGpD;;;;;GAKG;AAEH;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACjC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAChC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAChC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACjC,uEAAuE;IACvE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CAChC;AAED,6CAA6C;AAC7C,MAAM,WAAW,kBAAkB;IACjC,qFAAqF;IACrF,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,qGAAqG;IACrG,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,qIAAqI;IACrI,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,4FAA4F;IAC5F,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,uCAAuC;IACvC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAkCD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB,GAAG,MAAM,CAW1E"}

package/dist/logger/local.js

@@ -0,0 +1,45 @@
+import { serializeRecord } from "./record.js";
+import { createLogger } from "./logger.js";
+//#region src/logger/local.ts
+/** Render one field value: strings verbatim, everything else as compact JSON — never throwing on a cycle/BigInt. */
+function renderValue(value) {
+	if (typeof value === "string") return value;
+	try {
+		return JSON.stringify(value) ?? String(value);
+	} catch {
+		return String(value);
+	}
+}
+/** `key=value key=value` for the record's fields, in insertion order. */
+function renderFields(fields) {
+	return Object.entries(fields).map(([key, value]) => `${key}=${renderValue(value)}`).join(" ");
+}
+/** Format one record for a terminal: `LEVEL (name) msg key=val … code detail`, colorized when a palette is set. */
+function renderHuman(record, palette) {
+	const paint = palette?.[record.level] ?? ((text) => text);
+	const dim = palette?.dim ?? ((text) => text);
+	const parts = [paint(record.level.toUpperCase())];
+	if (record.name) parts.push(dim(`(${record.name})`));
+	parts.push(record.msg);
+	if (record.fields) parts.push(dim(renderFields(record.fields)));
+	if (record.error) {
+		const detail = record.error.detail ? ` ${record.error.detail}` : "";
+		parts.push(dim(`${record.error.code}${detail}`));
+	}
+	return parts.join(" ");
+}
+/**
+* Build a Mode 1 local logger. Same interface as every other Pithy logger; the sink either renders a
+* human line (default, colorized when a palette is injected) or a `--json` structured line. Writes to
+* `stderr` by default so a command's machine-readable stdout stays clean.
+*/
+function createLocalLogger(options = {}) {
+	const write = options.write ?? ((line) => console.error(line));
+	return createLogger({
+		level: options.level ?? "debug",
+		now: options.now,
+		sink: (record) => write(options.json ? serializeRecord(record) : renderHuman(record, options.palette))
+	});
+}
+//#endregion
+export { createLocalLogger };

package/dist/logger/logger.d.ts

@@ -0,0 +1,56 @@
+import { type LogFields, type LogLevel, type LogRecord } from "./record";
+/**
+ * The `Logger` seam. Four levels, each taking a message plus **structured fields** (not a formatted
+ * string), and `child(name)` to derive a namespaced sub-logger. Shared across runtimes: the same
+ * interface backs the `pithy` CLI process, a Worker running locally, and a deployed Worker — only the
+ * adapter behind it differs. Resolve it from the request context (`c.var.log`) or the CLI process
+ * logger; never reach for `console`.
+ *
+ * The reserved `error` field on any call may carry a `PithyError` or `ErrorPayload` — the engine lifts
+ * it into the record's `error`, `detail` and all. A log is internal; this is the inverse of the HTTP
+ * codec, which strips `detail`. The logger must never be wired to a client-facing surface.
+ */
+export interface Logger {
+    /** Dev-time diagnostics. Dropped unless the logger's level is `debug`. */
+    debug(msg: string, fields?: LogFields): void;
+    /** Normal operational events. */
+    info(msg: string, fields?: LogFields): void;
+    /** A recoverable problem worth attention. */
+    warn(msg: string, fields?: LogFields): void;
+    /** A failure that was observed. Pass `{ error }` (a PithyError) to carry its full payload. */
+    error(msg: string, fields?: LogFields): void;
+    /**
+     * A namespaced sub-logger. `name` composes as `parent:child`; bound `fields` merge into every record
+     * the child emits. Omit `name` (pass `undefined`) to bind fields only — how request-correlation
+     * attaches `request`/`method`/`path` without renaming the logger.
+     */
+    child(name?: string, fields?: LogFields): Logger;
+}
+/** A sink receives a finished {@link LogRecord}. Adapters supply one; the engine builds records and calls it. */
+export type LogSink = (record: LogRecord) => void;
+/** Inputs to {@link createLogger}: the level threshold, the sink, and optional bound name/fields/clock. */
+export interface CreateLoggerOptions {
+    /** The threshold; records below it are dropped. */
+    level: LogLevel;
+    /** Where finished records go. */
+    sink: LogSink;
+    /** A starting namespace for this logger, if any. */
+    name?: string;
+    /** Fields bound onto every record this logger emits. */
+    fields?: LogFields;
+    /** The clock, injectable for tests. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * The shared logger engine. Both adapters build on it: they supply a {@link LogSink} and a level, and
+ * this handles level filtering, `child` namespacing, field merging, and error lifting — one place, so
+ * every adapter behaves identically.
+ */
+export declare function createLogger(options: CreateLoggerOptions): Logger;
+/**
+ * The safe default: a logger that drops every record. Shipped so a capability that does nothing still
+ * has a `c.var.log` to call, and a KV store built without a logger still logs to *somewhere*. Both
+ * adapters replace it; nothing has to null-check `log`.
+ */
+export declare const noopLogger: Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logger/logger.ts"],"names":[],"mappings":"AAKA,OAAO,EAAmB,KAAK,SAAS,EAAE,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1F;;;;;;;;;;GAUG;AACH,MAAM,WAAW,MAAM;IACrB,0EAA0E;IAC1E,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAC7C,iCAAiC;IACjC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAC5C,6CAA6C;IAC7C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAC5C,8FAA8F;IAC9F,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAC7C;;;;OAIG;IACH,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;CAClD;AAED,iHAAiH;AACjH,MAAM,MAAM,OAAO,GAAG,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,CAAC;AAElD,2GAA2G;AAC3G,MAAM,WAAW,mBAAmB;IAClC,mDAAmD;IACnD,KAAK,EAAE,QAAQ,CAAC;IAChB,iCAAiC;IACjC,IAAI,EAAE,OAAO,CAAC;IACd,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAoED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAQjE;AAED;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,MAMxB,CAAC"}

package/dist/logger/logger.js

@@ -0,0 +1,83 @@
+import { PithyError } from "../error/pithyError.js";
+import { LOG_LEVEL_ORDER } from "./record.js";
+//#region src/logger/logger.ts
+/**
+* Duck-type an `ErrorPayload`: a **namespaced** `code` (`domain/reason`) plus an HTTP-range `status`.
+* Cheap — no per-call Zod parse. The `/` and status-range checks keep an ordinary field that happens to
+* be named `error` (e.g. `{ code: "retry", status: 3 }`) from being mistaken for a payload and lifted.
+*/
+function isErrorPayloadLike(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const { code, status } = value;
+	return typeof code === "string" && code.includes("/") && typeof status === "number" && Number.isInteger(status) && status >= 100 && status <= 599;
+}
+/** Build a logger over `state`: level-filters, merges bound + call fields, lifts a carried error. */
+function makeLogger(state) {
+	const emit = (level, msg, callFields) => {
+		if (LOG_LEVEL_ORDER[level] < LOG_LEVEL_ORDER[state.level]) return;
+		const merged = {
+			...state.fields,
+			...callFields
+		};
+		let error;
+		const carried = merged.error;
+		if (carried instanceof PithyError) {
+			error = carried.payload;
+			delete merged.error;
+		} else if (isErrorPayloadLike(carried)) {
+			error = carried;
+			delete merged.error;
+		}
+		const record = {
+			level,
+			msg,
+			time: state.now()
+		};
+		if (state.name) record.name = state.name;
+		if (Object.keys(merged).length > 0) record.fields = merged;
+		if (error) record.error = error;
+		state.sink(record);
+	};
+	return {
+		debug: (msg, fields) => emit("debug", msg, fields),
+		info: (msg, fields) => emit("info", msg, fields),
+		warn: (msg, fields) => emit("warn", msg, fields),
+		error: (msg, fields) => emit("error", msg, fields),
+		child: (name, fields) => makeLogger({
+			...state,
+			name: name ? state.name ? `${state.name}:${name}` : name : state.name,
+			fields: {
+				...state.fields,
+				...fields
+			}
+		})
+	};
+}
+/**
+* The shared logger engine. Both adapters build on it: they supply a {@link LogSink} and a level, and
+* this handles level filtering, `child` namespacing, field merging, and error lifting — one place, so
+* every adapter behaves identically.
+*/
+function createLogger(options) {
+	return makeLogger({
+		level: options.level,
+		sink: options.sink,
+		name: options.name,
+		fields: options.fields,
+		now: options.now ?? (() => Date.now())
+	});
+}
+/**
+* The safe default: a logger that drops every record. Shipped so a capability that does nothing still
+* has a `c.var.log` to call, and a KV store built without a logger still logs to *somewhere*. Both
+* adapters replace it; nothing has to null-check `log`.
+*/
+const noopLogger = {
+	debug: () => {},
+	info: () => {},
+	warn: () => {},
+	error: () => {},
+	child: () => noopLogger
+};
+//#endregion
+export { createLogger, noopLogger };