@homeflare/kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Timothy Schneider <tim@taslabs.net>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# @homeflare/kit
+
+Shared primitives for the HomeFlare estate. Bun-native to author, runtime-neutral to
+consume — the published bundle runs on Cloudflare Workers, Node and Bun alike.
+
+```sh
+bun add @homeflare/kit     # or: pnpm add @homeflare/kit
+```
+
+## Usage
+
+```ts
+import { parseEnv } from '@homeflare/kit';
+
+const config = parseEnv(
+  {
+    API_URL: { type: 'string' },
+    PORT: { type: 'number', default: 8787 },
+    DEBUG: { type: 'boolean', default: false },
+  },
+  env, // a Worker's env binding, or process.env
+);
+
+config.PORT; // number
+config.DEBUG; // boolean — 'false' parses as false, not as a truthy string
+```
+
+`parseEnv` throws `EnvError` on the first key that is missing or malformed. The error
+names the key and never the value.
+
+## Development
+
+```sh
+bun install
+bun run check    # lint + types + build + tests
+bun run smoke    # pack, install and use the real tarball under bun AND node
+bun run verify   # check + smoke — the full pre-publish gate
+```
+
+Changes are versioned with [changesets](https://github.com/changesets/changesets):
+
+```sh
+bun run changeset   # describe the change; commit the file with your PR
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the workflow and the gates, and
+[AGENTS.md](./AGENTS.md) for the toolchain rationale behind them.
+
+Found a vulnerability? Please don't open a public issue — see
+[SECURITY.md](./SECURITY.md).
+
+## License
+
+MIT © Timothy Schneider

package/SECURITY.md

@@ -0,0 +1,44 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Email **security@homeflare.dev**. Please do not open a public issue for a security
+vulnerability — a public report is a disclosure, and it reaches attackers at the same
+moment it reaches us.
+
+Include what you have:
+
+- a description of the issue
+- steps to reproduce
+- affected version(s) or commit SHAs
+- your assessment of severity
+
+We acknowledge reports within 72 hours and aim to ship fixes for high-severity issues
+within 30 days.
+
+## Supported versions
+
+The latest published release on npm is the only supported version. Older tags are
+point-in-time references; fixes are not backported.
+
+## What is in scope
+
+This package is a **library**. It holds no credentials, opens no sockets, and reads no
+files — `parseEnv` is handed a plain object by its caller and returns a plain object.
+The realistic vulnerability classes here are:
+
+- a parsing result that misrepresents its input (for example, a value that should have
+  been rejected being returned as valid)
+- a supply-chain issue in what we publish: the built `dist/`, the tarball's contents, or
+  the release workflow that produces them
+
+⚠️ **Configuration values are the caller's secrets, not ours.** Nothing in this package
+logs a parsed value, and `EnvError` names only the offending key. If you find any path
+where a value reaches a log, a message, or a stack trace, treat it as a vulnerability and
+report it here.
+
+## Disclosure
+
+We follow coordinated disclosure. Once a fix ships, reporters are welcome to publish
+their findings, and we are happy to credit you in the release notes — tell us how you
+would like to be named, or if you would rather not be.

package/dist/env.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Environment parsing — the one thing every HomeFlare app does before anything else.
+ *
+ * ★ WHY THIS EXISTS RATHER THAN zod. A Worker reads its config from a plain object
+ *   (`env`), not from `process.env`, and it does so on every request. Pulling a schema
+ *   library in for that costs bundle size on a hot path to validate perhaps six keys.
+ *   This is deliberately small and dependency-free; when a shape genuinely needs
+ *   unions, refinement or codecs, reach for zod in the consuming app instead of
+ *   growing this.
+ *
+ * ⚠️ THIS VALIDATES SHAPE, NOT SECRECY. A value arriving here has already been handed
+ *   over by the platform — a Worker binding, an OpenBao-minted lease. Nothing in this
+ *   file should ever log a value, and callers should not either: a thrown error names
+ *   the KEY that was wrong and never what it contained.
+ */
+/** How one environment key is read, and what it becomes. */
+export type EnvSpec = {
+    readonly type: 'string';
+    readonly optional?: boolean;
+    readonly default?: string;
+} | {
+    readonly type: 'number';
+    readonly optional?: boolean;
+    readonly default?: number;
+} | {
+    readonly type: 'boolean';
+    readonly optional?: boolean;
+    readonly default?: boolean;
+};
+/** A description of every key an app needs, keyed by the name it appears under. */
+export type EnvSchema = Readonly<Record<string, EnvSpec>>;
+/** What a schema produces once parsed: each key narrowed to its declared type. */
+type Parsed<S extends EnvSchema> = {
+    readonly [K in keyof S]: S[K] extends {
+        type: 'number';
+    } ? number : S[K] extends {
+        type: 'boolean';
+    } ? boolean : string;
+};
+/** Raised when a key is missing or cannot be read as its declared type. */
+export declare class EnvError extends Error {
+    /** The offending key. Never the value — see the file header. */
+    readonly key: string;
+    constructor(key: string, reason: string);
+}
+/**
+ * ⛔ THE THREE VALUES THAT MEAN "ABSENT", AND WHY IT IS NOT JUST THE EMPTY STRING.
+ *   An unbound workerd binding does NOT arrive as undefined — `fromEnvironment` produces
+ *   the four-character STRING "null", because the binding is present and String(null) is
+ *   truthy. Code that checks only for '' therefore accepts it, and the request goes out
+ *   as `Authorization: Bearer null`.
+ * 🔴 MEASURED IN THIS ESTATE, 2026-09-02. Twenty hand-rolled clients; this guard was in
+ *   four of them. The other sixteen surfaced a bare 401 from upstream — which reads as
+ *   "the token is wrong" and sends an operator to rotate a perfectly good credential.
+ *   The litellm server spent a day authenticating with nothing while /health answered 200.
+ *   Ported from house/mcp-servers/packages/kit/src/http.ts, where it was paid for once.
+ */
+export declare function isUnset(value: string): boolean;
+/**
+ * Read `source` against `schema`, throwing `EnvError` on the first key that is missing
+ * or malformed.
+ *
+ * ★ THROWS RATHER THAN RETURNING A RESULT, deliberately: this runs once at startup or
+ *   at the top of a fetch handler, where a misconfigured deployment should fail loudly
+ *   and immediately rather than produce a half-configured app that fails later somewhere
+ *   less obvious.
+ */
+export declare function parseEnv<const S extends EnvSchema>(schema: S, source: Readonly<Record<string, unknown>>): Parsed<S>;
+export {};
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,4DAA4D;AAC5D,MAAM,MAAM,OAAO,GACf;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACnF;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACnF;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAE1F,mFAAmF;AACnF,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAE1D,kFAAkF;AAClF,KAAK,MAAM,CAAC,CAAC,SAAS,SAAS,IAAI;IACjC,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS;QAAE,IAAI,EAAE,QAAQ,CAAA;KAAE,GACpD,MAAM,GACN,CAAC,CAAC,CAAC,CAAC,SAAS;QAAE,IAAI,EAAE,SAAS,CAAA;KAAE,GAC9B,OAAO,GACP,MAAM;CACb,CAAC;AAEF,2EAA2E;AAC3E,qBAAa,QAAS,SAAQ,KAAK;IACjC,gEAAgE;IAChE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB,YAAY,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAItC;CACF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE9C;AAWD;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,KAAK,CAAC,CAAC,SAAS,SAAS,EAChD,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,MAAM,CAAC,CAAC,CAAC,CAuCX"}

package/dist/errors.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Errors a CALLER can act on — an agent, a retry loop, or a person reading a log.
+ *
+ * ★ PORTED FROM house/mcp-servers/packages/kit/src/errors.ts, where 34 packages proved
+ *   the shape. Generalised: the estate version is MCP-specific (`HouseToolError`), this
+ *   one is not, so a Worker or a script can use the same vocabulary.
+ *
+ * ⛔ THE RULE THIS ENFORCES: a failure must never be silent, and never ambiguous with a
+ *   DIFFERENT failure. Both halves were learned from incidents, not from principle:
+ *   - An Access provider read its token at module scope and, when that failed, silently
+ *     omitted the auth header. Cloudflare answered a bare 401 — indistinguishable from a
+ *     bad credential — and sent an operator to debug the wrong subsystem. Omitting is
+ *     worse than throwing.
+ *   - A gate reported success on a corrupted file because it compared the file to itself.
+ *     A check that cannot fail is worse than no check, because it is trusted.
+ *
+ * ⚠️ THE AUDIENCE MAY BE AN AGENT, not a human with a debugger. An agent cannot open a
+ *   dashboard or ask a colleague, so everything it needs to pick its next action must be
+ *   in the error. One that reads "permission denied" retries forever; one that reads
+ *   "the token lacks Grafana Read; ask an operator to widen the grant" stops and reports.
+ */
+/** Which class of failure this is. Callers branch on it, so the set stays small. */
+export type ErrorKind = 
+/** Not who it claims, or claims nothing. Retrying unchanged fails. */
+'unauthenticated'
+/** Known, but lacks the grant. ⛔ NEVER retry — a human must widen a scope. */
+ | 'forbidden'
+/** The upstream said no. The caller may be able to fix its arguments and retry. */
+ | 'upstream_rejected'
+/**
+ * Over a rate limit. The IDENTICAL call succeeds after the stated delay.
+ * 🔴 A DISTINCT KIND BECAUSE IT WAS LANDING AS `bad_arguments`, measured 2026-09-07 in
+ *   the estate: a 429 mapped to "your arguments are wrong", so a throttled agent
+ *   rewrote a correct call, was throttled again, and concluded the tool was broken.
+ *   This is the refusal agents meet most — Cloudflare frontier models are 20 rpm.
+ */
+ | 'rate_limited'
+/** Could not be reached at all. Usually transient; a retry may work. */
+ | 'upstream_unreachable'
+/** Called with arguments it cannot accept. Correct them and retry. */
+ | 'bad_arguments'
+/** We are misconfigured. ⛔ A caller cannot fix this; it must report it. */
+ | 'misconfigured';
+/**
+ * What each kind means, for anything that has to explain them.
+ *
+ * ⛔ TYPED AS Record<ErrorKind, string>, WHICH IS THE POINT: adding a kind above without
+ *   describing it here is a COMPILE ERROR. A hand-kept list beside a union goes stale,
+ *   and a documented error contract with a missing case is worse than none — it is
+ *   trusted.
+ */
+export declare const KIND_DESCRIPTIONS: Record<ErrorKind, string>;
+export interface KitErrorOptions {
+    /** Which system failed. ⛔ Name it — "request failed" tells a caller nothing. */
+    readonly system: string;
+    /** What would make it work. This is what stops an agent retrying forever. */
+    readonly remedy?: string;
+    /** For `rate_limited`: how long to wait, in milliseconds. */
+    readonly retryAfterMs?: number;
+    readonly cause?: unknown;
+}
+/** A failure with enough shape for a caller to decide what to do next. */
+export declare class KitError extends Error {
+    readonly kind: ErrorKind;
+    readonly system: string;
+    readonly remedy: string | undefined;
+    readonly retryAfterMs: number | undefined;
+    constructor(kind: ErrorKind, message: string, options: KitErrorOptions);
+    /** True when retrying the identical call could plausibly succeed. */
+    get retryable(): boolean;
+}
+/**
+ * Map an HTTP status to a kind.
+ *
+ * ⚠️ 429 IS CHECKED EXPLICITLY, not left to fall through. It used to reach
+ *   `upstream_rejected` here and `bad_arguments` elsewhere — both of which tell a caller
+ *   to CHANGE ITS ARGUMENTS, which is precisely wrong for a throttle.
+ */
+export declare function kindForStatus(status: number): ErrorKind;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,oFAAoF;AACpF,MAAM,MAAM,SAAS;AACnB,sEAAsE;AACpE,iBAAiB;AACnB,8EAA8E;GAC5E,WAAW;AACb,mFAAmF;GACjF,mBAAmB;AACrB;;;;;;GAMG;GACD,cAAc;AAChB,wEAAwE;GACtE,sBAAsB;AACxB,sEAAsE;GACpE,eAAe;AACjB,2EAA2E;GACzE,eAAe,CAAC;AAEpB;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAQvD,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,0EAA0E;AAC1E,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IAE1C,YAAY,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAOrE;IAED,qEAAqE;IACrE,IAAI,SAAS,IAAI,OAAO,CAEvB;CACF;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAMvD"}

package/dist/http.d.ts

@@ -0,0 +1,45 @@
+/**
+ * HTTP client — a configured `ky`, not a wrapper around it.
+ *
+ * ★ WHY ky AND NOT A HAND-ROLLED fetch+retry. Retry, timeout and backoff are each easy
+ *   to write and easy to write subtly wrong (retrying a POST, retrying a 4xx, a timeout
+ *   that leaks the AbortController). ky is zero-dependency, TypeScript-native and
+ *   fetch-based — measured 2026-09-15: `npm view ky dependencies` is empty — so it adds
+ *   nothing to a consumer's tree.
+ *   ⚠️ ky is described as browser-first, which matters only in that it assumes a global
+ *     `fetch`. workerd, Node 18+ and Bun all provide one, so there is nothing to polyfill.
+ *   ⛔ NOT ofetch (pulls destr + node-fetch-native) and NOT wretch, which is BROKEN on
+ *     Workers out of the box: Cloudflare's Response has no `.type` and wretch throws
+ *     reading it, needing a middleware patch to work at all.
+ *
+ * ★ THIS MODULE IS DELIBERATELY THIN. It re-exports ky's own types rather than inventing
+ *   parallel ones, so a caller who needs something not covered here uses ky directly and
+ *   loses nothing.
+ */
+import { HTTPError, TimeoutError, type KyInstance, type Options } from 'ky';
+export { HTTPError, TimeoutError };
+export type { KyInstance, Options };
+/**
+ * The house defaults.
+ *
+ * ⚠️ ky retries only IDEMPOTENT methods by default (GET/PUT/HEAD/DELETE/OPTIONS/TRACE) —
+ *   POST is excluded, which is the behaviour you want and the one a hand-rolled retry
+ *   usually gets wrong. Retried status codes are 408/413/429/500/502/503/504.
+ * ⚠️ `timeout` is PER ATTEMPT, not for the whole call. With limit 3 and a 10s timeout the
+ *   worst case is ~30s plus backoff — shorten both for a Worker on a request path, where
+ *   the CPU-time limit is unforgiving.
+ */
+export declare const http: KyInstance;
+/**
+ * A client bound to one base URL, for talking to a specific service.
+ *
+ *     const linear = client('https://api.linear.app', { headers: { authorization } });
+ *     const issues = await linear.get('/graphql').json<Issues>();
+ *
+ * ⚠️ `baseUrl`, NOT `prefixUrl`. ky 2.x renamed the option and changed its semantics:
+ *   `baseUrl` resolves per the URL standard, so a leading slash is fine and an absolute
+ *   input bypasses the base. (ky 1.x had `prefixUrl`, which threw on a leading slash —
+ *   measured 2026-09-15, the old name is a type error, not a silent no-op.)
+ */
+export declare function client(baseUrl: string, options?: Options): KyInstance;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAW,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,KAAK,OAAO,EAAE,MAAM,IAAI,CAAC;AAEhF,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC;AACnC,YAAY,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;AAEpC;;;;;;;;;GASG;AACH,eAAO,MAAM,IAAI,EAAE,UAGjB,CAAC;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,UAAU,CAErE"}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @homeflare/kit — the estate's shared primitives.
+ *
+ * ⛔ THIS ENTRYPOINT STAYS RUNTIME-NEUTRAL. Bun is how the kit is authored, built and
+ *   tested; it is not what consumers run. The monorepo ships this code to Cloudflare
+ *   Workers, so anything reaching for `bun:*`, `node:fs` or a filesystem belongs behind
+ *   its own subpath export (`@homeflare/kit/<area>`), never here.
+ *   The failure this prevents is a deploy-time one: a `bun:sqlite` import that resolves
+ *   fine on a laptop and fails only in workerd, where the stack trace names the bundler
+ *   rather than this file.
+ *
+ * ★ isolatedDeclarations is on, so every exported symbol below carries an explicit
+ *   return type. That is not style — `bun build` cannot emit .d.ts, so declarations come
+ *   from a separate tsc pass, and explicit types are what keep the two in agreement.
+ */
+export { VERSION } from './version.ts';
+export { EnvError, isUnset, parseEnv, type EnvSchema, type EnvSpec } from './env.ts';
+export { KIND_DESCRIPTIONS, KitError, kindForStatus, type ErrorKind, type KitErrorOptions, } from './errors.ts';
+export { client, http, HTTPError, TimeoutError, type KyInstance, type Options } from './http.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,SAAS,EAAE,KAAK,OAAO,EAAE,MAAM,UAAU,CAAC;AACrF,OAAO,EACL,iBAAiB,EACjB,QAAQ,EACR,aAAa,EACb,KAAK,SAAS,EACd,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,114 @@
+// src/version.ts
+var VERSION = "0.1.0";
+// src/env.ts
+class EnvError extends Error {
+  key;
+  constructor(key, reason) {
+    super(`env ${key}: ${reason}`);
+    this.name = "EnvError";
+    this.key = key;
+  }
+}
+function isUnset(value) {
+  return value === "" || value === "null" || value === "undefined";
+}
+var TRUE = new Set(["1", "true", "yes", "on"]);
+var FALSE = new Set(["0", "false", "no", "off"]);
+function parseEnv(schema, source) {
+  const out = {};
+  for (const key of Object.keys(schema)) {
+    const spec = schema[key];
+    const raw = source[key];
+    if (raw === undefined || raw === null || isUnset(String(raw).trim())) {
+      if (spec.default !== undefined) {
+        out[key] = spec.default;
+        continue;
+      }
+      if (spec.optional === true)
+        continue;
+      throw new EnvError(key, "required but not set");
+    }
+    const text = String(raw).trim();
+    if (spec.type === "number") {
+      const n = Number(text);
+      if (!Number.isFinite(n))
+        throw new EnvError(key, "expected a number");
+      out[key] = n;
+    } else if (spec.type === "boolean") {
+      const lowered = text.toLowerCase();
+      if (TRUE.has(lowered))
+        out[key] = true;
+      else if (FALSE.has(lowered))
+        out[key] = false;
+      else
+        throw new EnvError(key, "expected one of 1/true/yes/on or 0/false/no/off");
+    } else {
+      out[key] = text;
+    }
+  }
+  return out;
+}
+// src/errors.ts
+var KIND_DESCRIPTIONS = {
+  unauthenticated: "The credential was missing, malformed, or rejected.",
+  forbidden: "The credential is valid but lacks the required grant. Do not retry.",
+  upstream_rejected: "The upstream refused the request as made.",
+  rate_limited: "Throttled. The identical call succeeds after the stated delay.",
+  upstream_unreachable: "The upstream could not be reached. A retry may succeed.",
+  bad_arguments: "The arguments were not acceptable. Correct them and retry.",
+  misconfigured: "This service is misconfigured and cannot serve the request."
+};
+
+class KitError extends Error {
+  kind;
+  system;
+  remedy;
+  retryAfterMs;
+  constructor(kind, message, options) {
+    super(`${options.system}: ${message}`, { cause: options.cause });
+    this.name = "KitError";
+    this.kind = kind;
+    this.system = options.system;
+    this.remedy = options.remedy;
+    this.retryAfterMs = options.retryAfterMs;
+  }
+  get retryable() {
+    return this.kind === "rate_limited" || this.kind === "upstream_unreachable";
+  }
+}
+function kindForStatus(status) {
+  if (status === 401)
+    return "unauthenticated";
+  if (status === 403)
+    return "forbidden";
+  if (status === 429)
+    return "rate_limited";
+  if (status >= 500)
+    return "upstream_unreachable";
+  return "upstream_rejected";
+}
+// src/http.ts
+import ky, { HTTPError, TimeoutError } from "ky";
+var http = ky.extend({
+  retry: { limit: 3, backoffLimit: 3000 },
+  timeout: 1e4
+});
+function client(baseUrl, options) {
+  return http.extend({ ...options, baseUrl });
+}
+export {
+  EnvError,
+  HTTPError,
+  KIND_DESCRIPTIONS,
+  KitError,
+  TimeoutError,
+  VERSION,
+  client,
+  http,
+  isUnset,
+  kindForStatus,
+  parseEnv
+};
+
+//# debugId=A318350C97DF929364756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,13 @@
+{
+  "version": 3,
+  "sources": ["../src/version.ts", "../src/env.ts", "../src/errors.ts", "../src/http.ts"],
+  "sourcesContent": [
+    "// ⛔ GENERATED by scripts/sync-versions.ts — do not edit. Source: package.json.\nexport const VERSION: string = '0.1.0';\n",
+    "/**\n * Environment parsing — the one thing every HomeFlare app does before anything else.\n *\n * ★ WHY THIS EXISTS RATHER THAN zod. A Worker reads its config from a plain object\n *   (`env`), not from `process.env`, and it does so on every request. Pulling a schema\n *   library in for that costs bundle size on a hot path to validate perhaps six keys.\n *   This is deliberately small and dependency-free; when a shape genuinely needs\n *   unions, refinement or codecs, reach for zod in the consuming app instead of\n *   growing this.\n *\n * ⚠️ THIS VALIDATES SHAPE, NOT SECRECY. A value arriving here has already been handed\n *   over by the platform — a Worker binding, an OpenBao-minted lease. Nothing in this\n *   file should ever log a value, and callers should not either: a thrown error names\n *   the KEY that was wrong and never what it contained.\n */\n\n/** How one environment key is read, and what it becomes. */\nexport type EnvSpec =\n  | { readonly type: 'string'; readonly optional?: boolean; readonly default?: string }\n  | { readonly type: 'number'; readonly optional?: boolean; readonly default?: number }\n  | { readonly type: 'boolean'; readonly optional?: boolean; readonly default?: boolean };\n\n/** A description of every key an app needs, keyed by the name it appears under. */\nexport type EnvSchema = Readonly<Record<string, EnvSpec>>;\n\n/** What a schema produces once parsed: each key narrowed to its declared type. */\ntype Parsed<S extends EnvSchema> = {\n  readonly [K in keyof S]: S[K] extends { type: 'number' }\n    ? number\n    : S[K] extends { type: 'boolean' }\n      ? boolean\n      : string;\n};\n\n/** Raised when a key is missing or cannot be read as its declared type. */\nexport class EnvError extends Error {\n  /** The offending key. Never the value — see the file header. */\n  readonly key: string;\n\n  constructor(key: string, reason: string) {\n    super(`env ${key}: ${reason}`);\n    this.name = 'EnvError';\n    this.key = key;\n  }\n}\n\n/**\n * ⛔ THE THREE VALUES THAT MEAN \"ABSENT\", AND WHY IT IS NOT JUST THE EMPTY STRING.\n *   An unbound workerd binding does NOT arrive as undefined — `fromEnvironment` produces\n *   the four-character STRING \"null\", because the binding is present and String(null) is\n *   truthy. Code that checks only for '' therefore accepts it, and the request goes out\n *   as `Authorization: Bearer null`.\n * 🔴 MEASURED IN THIS ESTATE, 2026-09-02. Twenty hand-rolled clients; this guard was in\n *   four of them. The other sixteen surfaced a bare 401 from upstream — which reads as\n *   \"the token is wrong\" and sends an operator to rotate a perfectly good credential.\n *   The litellm server spent a day authenticating with nothing while /health answered 200.\n *   Ported from house/mcp-servers/packages/kit/src/http.ts, where it was paid for once.\n */\nexport function isUnset(value: string): boolean {\n  return value === '' || value === 'null' || value === 'undefined';\n}\n\n/**\n * ⚠️ 'false' IS TRUTHY AS A STRING, and that is the bug this function exists to stop.\n *   `Boolean(env.FEATURE)` on the string 'false' is `true`, so a flag turned off in a\n *   dashboard stays on in production and nothing in the logs says why. Only the listed\n *   spellings are accepted; anything else throws rather than guessing.\n */\nconst TRUE = new Set(['1', 'true', 'yes', 'on']);\nconst FALSE = new Set(['0', 'false', 'no', 'off']);\n\n/**\n * Read `source` against `schema`, throwing `EnvError` on the first key that is missing\n * or malformed.\n *\n * ★ THROWS RATHER THAN RETURNING A RESULT, deliberately: this runs once at startup or\n *   at the top of a fetch handler, where a misconfigured deployment should fail loudly\n *   and immediately rather than produce a half-configured app that fails later somewhere\n *   less obvious.\n */\nexport function parseEnv<const S extends EnvSchema>(\n  schema: S,\n  source: Readonly<Record<string, unknown>>,\n): Parsed<S> {\n  const out: Record<string, string | number | boolean> = {};\n\n  for (const key of Object.keys(schema)) {\n    const spec = schema[key] as EnvSpec;\n    const raw = source[key];\n\n    // ⛔ isUnset, not `=== ''`. See its comment: \"null\" is what an unbound workerd\n    //   binding actually looks like, and treating it as a value is a day-long debug.\n    if (raw === undefined || raw === null || isUnset(String(raw).trim())) {\n      if (spec.default !== undefined) {\n        out[key] = spec.default;\n        continue;\n      }\n      if (spec.optional === true) continue;\n      throw new EnvError(key, 'required but not set');\n    }\n\n    // ⚠️ Trimmed: a rendered env file with a trailing newline is the common case, and an\n    //   untrimmed token fails upstream with the same unhelpful 401.\n    const text = String(raw).trim();\n\n    if (spec.type === 'number') {\n      const n = Number(text);\n      // ⚠️ Number('') is 0 and Number(' ') is 0; the empty check above is what makes\n      //   this safe. NaN is the only remaining failure and it is caught here.\n      if (!Number.isFinite(n)) throw new EnvError(key, 'expected a number');\n      out[key] = n;\n    } else if (spec.type === 'boolean') {\n      const lowered = text.toLowerCase();\n      if (TRUE.has(lowered)) out[key] = true;\n      else if (FALSE.has(lowered)) out[key] = false;\n      else throw new EnvError(key, 'expected one of 1/true/yes/on or 0/false/no/off');\n    } else {\n      out[key] = text;\n    }\n  }\n\n  return out as Parsed<S>;\n}\n",
+    "/**\n * Errors a CALLER can act on — an agent, a retry loop, or a person reading a log.\n *\n * ★ PORTED FROM house/mcp-servers/packages/kit/src/errors.ts, where 34 packages proved\n *   the shape. Generalised: the estate version is MCP-specific (`HouseToolError`), this\n *   one is not, so a Worker or a script can use the same vocabulary.\n *\n * ⛔ THE RULE THIS ENFORCES: a failure must never be silent, and never ambiguous with a\n *   DIFFERENT failure. Both halves were learned from incidents, not from principle:\n *   - An Access provider read its token at module scope and, when that failed, silently\n *     omitted the auth header. Cloudflare answered a bare 401 — indistinguishable from a\n *     bad credential — and sent an operator to debug the wrong subsystem. Omitting is\n *     worse than throwing.\n *   - A gate reported success on a corrupted file because it compared the file to itself.\n *     A check that cannot fail is worse than no check, because it is trusted.\n *\n * ⚠️ THE AUDIENCE MAY BE AN AGENT, not a human with a debugger. An agent cannot open a\n *   dashboard or ask a colleague, so everything it needs to pick its next action must be\n *   in the error. One that reads \"permission denied\" retries forever; one that reads\n *   \"the token lacks Grafana Read; ask an operator to widen the grant\" stops and reports.\n */\n\n/** Which class of failure this is. Callers branch on it, so the set stays small. */\nexport type ErrorKind =\n  /** Not who it claims, or claims nothing. Retrying unchanged fails. */\n  | 'unauthenticated'\n  /** Known, but lacks the grant. ⛔ NEVER retry — a human must widen a scope. */\n  | 'forbidden'\n  /** The upstream said no. The caller may be able to fix its arguments and retry. */\n  | 'upstream_rejected'\n  /**\n   * Over a rate limit. The IDENTICAL call succeeds after the stated delay.\n   * 🔴 A DISTINCT KIND BECAUSE IT WAS LANDING AS `bad_arguments`, measured 2026-09-07 in\n   *   the estate: a 429 mapped to \"your arguments are wrong\", so a throttled agent\n   *   rewrote a correct call, was throttled again, and concluded the tool was broken.\n   *   This is the refusal agents meet most — Cloudflare frontier models are 20 rpm.\n   */\n  | 'rate_limited'\n  /** Could not be reached at all. Usually transient; a retry may work. */\n  | 'upstream_unreachable'\n  /** Called with arguments it cannot accept. Correct them and retry. */\n  | 'bad_arguments'\n  /** We are misconfigured. ⛔ A caller cannot fix this; it must report it. */\n  | 'misconfigured';\n\n/**\n * What each kind means, for anything that has to explain them.\n *\n * ⛔ TYPED AS Record<ErrorKind, string>, WHICH IS THE POINT: adding a kind above without\n *   describing it here is a COMPILE ERROR. A hand-kept list beside a union goes stale,\n *   and a documented error contract with a missing case is worse than none — it is\n *   trusted.\n */\nexport const KIND_DESCRIPTIONS: Record<ErrorKind, string> = {\n  unauthenticated: 'The credential was missing, malformed, or rejected.',\n  forbidden: 'The credential is valid but lacks the required grant. Do not retry.',\n  upstream_rejected: 'The upstream refused the request as made.',\n  rate_limited: 'Throttled. The identical call succeeds after the stated delay.',\n  upstream_unreachable: 'The upstream could not be reached. A retry may succeed.',\n  bad_arguments: 'The arguments were not acceptable. Correct them and retry.',\n  misconfigured: 'This service is misconfigured and cannot serve the request.',\n};\n\nexport interface KitErrorOptions {\n  /** Which system failed. ⛔ Name it — \"request failed\" tells a caller nothing. */\n  readonly system: string;\n  /** What would make it work. This is what stops an agent retrying forever. */\n  readonly remedy?: string;\n  /** For `rate_limited`: how long to wait, in milliseconds. */\n  readonly retryAfterMs?: number;\n  readonly cause?: unknown;\n}\n\n/** A failure with enough shape for a caller to decide what to do next. */\nexport class KitError extends Error {\n  readonly kind: ErrorKind;\n  readonly system: string;\n  readonly remedy: string | undefined;\n  readonly retryAfterMs: number | undefined;\n\n  constructor(kind: ErrorKind, message: string, options: KitErrorOptions) {\n    super(`${options.system}: ${message}`, { cause: options.cause });\n    this.name = 'KitError';\n    this.kind = kind;\n    this.system = options.system;\n    this.remedy = options.remedy;\n    this.retryAfterMs = options.retryAfterMs;\n  }\n\n  /** True when retrying the identical call could plausibly succeed. */\n  get retryable(): boolean {\n    return this.kind === 'rate_limited' || this.kind === 'upstream_unreachable';\n  }\n}\n\n/**\n * Map an HTTP status to a kind.\n *\n * ⚠️ 429 IS CHECKED EXPLICITLY, not left to fall through. It used to reach\n *   `upstream_rejected` here and `bad_arguments` elsewhere — both of which tell a caller\n *   to CHANGE ITS ARGUMENTS, which is precisely wrong for a throttle.\n */\nexport function kindForStatus(status: number): ErrorKind {\n  if (status === 401) return 'unauthenticated';\n  if (status === 403) return 'forbidden';\n  if (status === 429) return 'rate_limited';\n  if (status >= 500) return 'upstream_unreachable';\n  return 'upstream_rejected';\n}\n",
+    "/**\n * HTTP client — a configured `ky`, not a wrapper around it.\n *\n * ★ WHY ky AND NOT A HAND-ROLLED fetch+retry. Retry, timeout and backoff are each easy\n *   to write and easy to write subtly wrong (retrying a POST, retrying a 4xx, a timeout\n *   that leaks the AbortController). ky is zero-dependency, TypeScript-native and\n *   fetch-based — measured 2026-09-15: `npm view ky dependencies` is empty — so it adds\n *   nothing to a consumer's tree.\n *   ⚠️ ky is described as browser-first, which matters only in that it assumes a global\n *     `fetch`. workerd, Node 18+ and Bun all provide one, so there is nothing to polyfill.\n *   ⛔ NOT ofetch (pulls destr + node-fetch-native) and NOT wretch, which is BROKEN on\n *     Workers out of the box: Cloudflare's Response has no `.type` and wretch throws\n *     reading it, needing a middleware patch to work at all.\n *\n * ★ THIS MODULE IS DELIBERATELY THIN. It re-exports ky's own types rather than inventing\n *   parallel ones, so a caller who needs something not covered here uses ky directly and\n *   loses nothing.\n */\nimport ky, { HTTPError, TimeoutError, type KyInstance, type Options } from 'ky';\n\nexport { HTTPError, TimeoutError };\nexport type { KyInstance, Options };\n\n/**\n * The house defaults.\n *\n * ⚠️ ky retries only IDEMPOTENT methods by default (GET/PUT/HEAD/DELETE/OPTIONS/TRACE) —\n *   POST is excluded, which is the behaviour you want and the one a hand-rolled retry\n *   usually gets wrong. Retried status codes are 408/413/429/500/502/503/504.\n * ⚠️ `timeout` is PER ATTEMPT, not for the whole call. With limit 3 and a 10s timeout the\n *   worst case is ~30s plus backoff — shorten both for a Worker on a request path, where\n *   the CPU-time limit is unforgiving.\n */\nexport const http: KyInstance = ky.extend({\n  retry: { limit: 3, backoffLimit: 3_000 },\n  timeout: 10_000,\n});\n\n/**\n * A client bound to one base URL, for talking to a specific service.\n *\n *     const linear = client('https://api.linear.app', { headers: { authorization } });\n *     const issues = await linear.get('/graphql').json<Issues>();\n *\n * ⚠️ `baseUrl`, NOT `prefixUrl`. ky 2.x renamed the option and changed its semantics:\n *   `baseUrl` resolves per the URL standard, so a leading slash is fine and an absolute\n *   input bypasses the base. (ky 1.x had `prefixUrl`, which threw on a leading slash —\n *   measured 2026-09-15, the old name is a type error, not a silent no-op.)\n */\nexport function client(baseUrl: string, options?: Options): KyInstance {\n  return http.extend({ ...options, baseUrl });\n}\n"
+  ],
+  "mappings": ";AACO,IAAM,UAAkB;;ACkCxB,MAAM,iBAAiB,MAAM;AAAA,EAEzB;AAAA,EAET,WAAW,CAAC,KAAa,QAAgB;AAAA,IACvC,MAAM,OAAO,QAAQ,QAAQ;AAAA,IAC7B,KAAK,OAAO;AAAA,IACZ,KAAK,MAAM;AAAA;AAEf;AAcO,SAAS,OAAO,CAAC,OAAwB;AAAA,EAC9C,OAAO,UAAU,MAAM,UAAU,UAAU,UAAU;AAAA;AASvD,IAAM,OAAO,IAAI,IAAI,CAAC,KAAK,QAAQ,OAAO,IAAI,CAAC;AAC/C,IAAM,QAAQ,IAAI,IAAI,CAAC,KAAK,SAAS,MAAM,KAAK,CAAC;AAW1C,SAAS,QAAmC,CACjD,QACA,QACW;AAAA,EACX,MAAM,MAAiD,CAAC;AAAA,EAExD,WAAW,OAAO,OAAO,KAAK,MAAM,GAAG;AAAA,IACrC,MAAM,OAAO,OAAO;AAAA,IACpB,MAAM,MAAM,OAAO;AAAA,IAInB,IAAI,QAAQ,aAAa,QAAQ,QAAQ,QAAQ,OAAO,GAAG,EAAE,KAAK,CAAC,GAAG;AAAA,MACpE,IAAI,KAAK,YAAY,WAAW;AAAA,QAC9B,IAAI,OAAO,KAAK;AAAA,QAChB;AAAA,MACF;AAAA,MACA,IAAI,KAAK,aAAa;AAAA,QAAM;AAAA,MAC5B,MAAM,IAAI,SAAS,KAAK,sBAAsB;AAAA,IAChD;AAAA,IAIA,MAAM,OAAO,OAAO,GAAG,EAAE,KAAK;AAAA,IAE9B,IAAI,KAAK,SAAS,UAAU;AAAA,MAC1B,MAAM,IAAI,OAAO,IAAI;AAAA,MAGrB,IAAI,CAAC,OAAO,SAAS,CAAC;AAAA,QAAG,MAAM,IAAI,SAAS,KAAK,mBAAmB;AAAA,MACpE,IAAI,OAAO;AAAA,IACb,EAAO,SAAI,KAAK,SAAS,WAAW;AAAA,MAClC,MAAM,UAAU,KAAK,YAAY;AAAA,MACjC,IAAI,KAAK,IAAI,OAAO;AAAA,QAAG,IAAI,OAAO;AAAA,MAC7B,SAAI,MAAM,IAAI,OAAO;AAAA,QAAG,IAAI,OAAO;AAAA,MACnC;AAAA,cAAM,IAAI,SAAS,KAAK,iDAAiD;AAAA,IAChF,EAAO;AAAA,MACL,IAAI,OAAO;AAAA;AAAA,EAEf;AAAA,EAEA,OAAO;AAAA;;ACpEF,IAAM,oBAA+C;AAAA,EAC1D,iBAAiB;AAAA,EACjB,WAAW;AAAA,EACX,mBAAmB;AAAA,EACnB,cAAc;AAAA,EACd,sBAAsB;AAAA,EACtB,eAAe;AAAA,EACf,eAAe;AACjB;AAAA;AAaO,MAAM,iBAAiB,MAAM;AAAA,EACzB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAET,WAAW,CAAC,MAAiB,SAAiB,SAA0B;AAAA,IACtE,MAAM,GAAG,QAAQ,WAAW,WAAW,EAAE,OAAO,QAAQ,MAAM,CAAC;AAAA,IAC/D,KAAK,OAAO;AAAA,IACZ,KAAK,OAAO;AAAA,IACZ,KAAK,SAAS,QAAQ;AAAA,IACtB,KAAK,SAAS,QAAQ;AAAA,IACtB,KAAK,eAAe,QAAQ;AAAA;AAAA,MAI1B,SAAS,GAAY;AAAA,IACvB,OAAO,KAAK,SAAS,kBAAkB,KAAK,SAAS;AAAA;AAEzD;AASO,SAAS,aAAa,CAAC,QAA2B;AAAA,EACvD,IAAI,WAAW;AAAA,IAAK,OAAO;AAAA,EAC3B,IAAI,WAAW;AAAA,IAAK,OAAO;AAAA,EAC3B,IAAI,WAAW;AAAA,IAAK,OAAO;AAAA,EAC3B,IAAI,UAAU;AAAA,IAAK,OAAO;AAAA,EAC1B,OAAO;AAAA;;ACzFT;AAeO,IAAM,OAAmB,GAAG,OAAO;AAAA,EACxC,OAAO,EAAE,OAAO,GAAG,cAAc,KAAM;AAAA,EACvC,SAAS;AACX,CAAC;AAaM,SAAS,MAAM,CAAC,SAAiB,SAA+B;AAAA,EACrE,OAAO,KAAK,OAAO,KAAK,SAAS,QAAQ,CAAC;AAAA;",
+  "debugId": "A318350C97DF929364756E2164756E21",
+  "names": []
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const VERSION: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,OAAO,EAAE,MAAgB,CAAC"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@homeflare/kit",
+  "version": "0.1.0",
+  "description": "Runtime-neutral HomeFlare primitives: env parsing, errors, logging, HTTP.",
+  "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/kit#readme",
+  "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
+  "license": "MIT",
+  "author": "Timothy Schneider",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taslabs-net/homeflare-kit.git",
+    "directory": "packages/kit"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun run build:js && bun run build:types",
+    "build:js": "bun build ./src/index.ts --outdir dist --target node --format esm --packages external --sourcemap=linked",
+    "build:types": "tsc --project tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "test": "bun test",
+    "smoke": "bun run scripts/smoke.ts",
+    "prepublishOnly": "bun run clean && bun run build",
+    "types": "tsc --noEmit"
+  },
+  "dependencies": {
+    "ky": "2.1.0"
+  }
+}

package/src/env.ts

@@ -0,0 +1,123 @@
+/**
+ * Environment parsing — the one thing every HomeFlare app does before anything else.
+ *
+ * ★ WHY THIS EXISTS RATHER THAN zod. A Worker reads its config from a plain object
+ *   (`env`), not from `process.env`, and it does so on every request. Pulling a schema
+ *   library in for that costs bundle size on a hot path to validate perhaps six keys.
+ *   This is deliberately small and dependency-free; when a shape genuinely needs
+ *   unions, refinement or codecs, reach for zod in the consuming app instead of
+ *   growing this.
+ *
+ * ⚠️ THIS VALIDATES SHAPE, NOT SECRECY. A value arriving here has already been handed
+ *   over by the platform — a Worker binding, an OpenBao-minted lease. Nothing in this
+ *   file should ever log a value, and callers should not either: a thrown error names
+ *   the KEY that was wrong and never what it contained.
+ */
+
+/** How one environment key is read, and what it becomes. */
+export type EnvSpec =
+  | { readonly type: 'string'; readonly optional?: boolean; readonly default?: string }
+  | { readonly type: 'number'; readonly optional?: boolean; readonly default?: number }
+  | { readonly type: 'boolean'; readonly optional?: boolean; readonly default?: boolean };
+
+/** A description of every key an app needs, keyed by the name it appears under. */
+export type EnvSchema = Readonly<Record<string, EnvSpec>>;
+
+/** What a schema produces once parsed: each key narrowed to its declared type. */
+type Parsed<S extends EnvSchema> = {
+  readonly [K in keyof S]: S[K] extends { type: 'number' }
+    ? number
+    : S[K] extends { type: 'boolean' }
+      ? boolean
+      : string;
+};
+
+/** Raised when a key is missing or cannot be read as its declared type. */
+export class EnvError extends Error {
+  /** The offending key. Never the value — see the file header. */
+  readonly key: string;
+
+  constructor(key: string, reason: string) {
+    super(`env ${key}: ${reason}`);
+    this.name = 'EnvError';
+    this.key = key;
+  }
+}
+
+/**
+ * ⛔ THE THREE VALUES THAT MEAN "ABSENT", AND WHY IT IS NOT JUST THE EMPTY STRING.
+ *   An unbound workerd binding does NOT arrive as undefined — `fromEnvironment` produces
+ *   the four-character STRING "null", because the binding is present and String(null) is
+ *   truthy. Code that checks only for '' therefore accepts it, and the request goes out
+ *   as `Authorization: Bearer null`.
+ * 🔴 MEASURED IN THIS ESTATE, 2026-09-02. Twenty hand-rolled clients; this guard was in
+ *   four of them. The other sixteen surfaced a bare 401 from upstream — which reads as
+ *   "the token is wrong" and sends an operator to rotate a perfectly good credential.
+ *   The litellm server spent a day authenticating with nothing while /health answered 200.
+ *   Ported from house/mcp-servers/packages/kit/src/http.ts, where it was paid for once.
+ */
+export function isUnset(value: string): boolean {
+  return value === '' || value === 'null' || value === 'undefined';
+}
+
+/**
+ * ⚠️ 'false' IS TRUTHY AS A STRING, and that is the bug this function exists to stop.
+ *   `Boolean(env.FEATURE)` on the string 'false' is `true`, so a flag turned off in a
+ *   dashboard stays on in production and nothing in the logs says why. Only the listed
+ *   spellings are accepted; anything else throws rather than guessing.
+ */
+const TRUE = new Set(['1', 'true', 'yes', 'on']);
+const FALSE = new Set(['0', 'false', 'no', 'off']);
+
+/**
+ * Read `source` against `schema`, throwing `EnvError` on the first key that is missing
+ * or malformed.
+ *
+ * ★ THROWS RATHER THAN RETURNING A RESULT, deliberately: this runs once at startup or
+ *   at the top of a fetch handler, where a misconfigured deployment should fail loudly
+ *   and immediately rather than produce a half-configured app that fails later somewhere
+ *   less obvious.
+ */
+export function parseEnv<const S extends EnvSchema>(
+  schema: S,
+  source: Readonly<Record<string, unknown>>,
+): Parsed<S> {
+  const out: Record<string, string | number | boolean> = {};
+
+  for (const key of Object.keys(schema)) {
+    const spec = schema[key] as EnvSpec;
+    const raw = source[key];
+
+    // ⛔ isUnset, not `=== ''`. See its comment: "null" is what an unbound workerd
+    //   binding actually looks like, and treating it as a value is a day-long debug.
+    if (raw === undefined || raw === null || isUnset(String(raw).trim())) {
+      if (spec.default !== undefined) {
+        out[key] = spec.default;
+        continue;
+      }
+      if (spec.optional === true) continue;
+      throw new EnvError(key, 'required but not set');
+    }
+
+    // ⚠️ Trimmed: a rendered env file with a trailing newline is the common case, and an
+    //   untrimmed token fails upstream with the same unhelpful 401.
+    const text = String(raw).trim();
+
+    if (spec.type === 'number') {
+      const n = Number(text);
+      // ⚠️ Number('') is 0 and Number(' ') is 0; the empty check above is what makes
+      //   this safe. NaN is the only remaining failure and it is caught here.
+      if (!Number.isFinite(n)) throw new EnvError(key, 'expected a number');
+      out[key] = n;
+    } else if (spec.type === 'boolean') {
+      const lowered = text.toLowerCase();
+      if (TRUE.has(lowered)) out[key] = true;
+      else if (FALSE.has(lowered)) out[key] = false;
+      else throw new EnvError(key, 'expected one of 1/true/yes/on or 0/false/no/off');
+    } else {
+      out[key] = text;
+    }
+  }
+
+  return out as Parsed<S>;
+}

package/src/errors.ts

@@ -0,0 +1,109 @@
+/**
+ * Errors a CALLER can act on — an agent, a retry loop, or a person reading a log.
+ *
+ * ★ PORTED FROM house/mcp-servers/packages/kit/src/errors.ts, where 34 packages proved
+ *   the shape. Generalised: the estate version is MCP-specific (`HouseToolError`), this
+ *   one is not, so a Worker or a script can use the same vocabulary.
+ *
+ * ⛔ THE RULE THIS ENFORCES: a failure must never be silent, and never ambiguous with a
+ *   DIFFERENT failure. Both halves were learned from incidents, not from principle:
+ *   - An Access provider read its token at module scope and, when that failed, silently
+ *     omitted the auth header. Cloudflare answered a bare 401 — indistinguishable from a
+ *     bad credential — and sent an operator to debug the wrong subsystem. Omitting is
+ *     worse than throwing.
+ *   - A gate reported success on a corrupted file because it compared the file to itself.
+ *     A check that cannot fail is worse than no check, because it is trusted.
+ *
+ * ⚠️ THE AUDIENCE MAY BE AN AGENT, not a human with a debugger. An agent cannot open a
+ *   dashboard or ask a colleague, so everything it needs to pick its next action must be
+ *   in the error. One that reads "permission denied" retries forever; one that reads
+ *   "the token lacks Grafana Read; ask an operator to widen the grant" stops and reports.
+ */
+
+/** Which class of failure this is. Callers branch on it, so the set stays small. */
+export type ErrorKind =
+  /** Not who it claims, or claims nothing. Retrying unchanged fails. */
+  | 'unauthenticated'
+  /** Known, but lacks the grant. ⛔ NEVER retry — a human must widen a scope. */
+  | 'forbidden'
+  /** The upstream said no. The caller may be able to fix its arguments and retry. */
+  | 'upstream_rejected'
+  /**
+   * Over a rate limit. The IDENTICAL call succeeds after the stated delay.
+   * 🔴 A DISTINCT KIND BECAUSE IT WAS LANDING AS `bad_arguments`, measured 2026-09-07 in
+   *   the estate: a 429 mapped to "your arguments are wrong", so a throttled agent
+   *   rewrote a correct call, was throttled again, and concluded the tool was broken.
+   *   This is the refusal agents meet most — Cloudflare frontier models are 20 rpm.
+   */
+  | 'rate_limited'
+  /** Could not be reached at all. Usually transient; a retry may work. */
+  | 'upstream_unreachable'
+  /** Called with arguments it cannot accept. Correct them and retry. */
+  | 'bad_arguments'
+  /** We are misconfigured. ⛔ A caller cannot fix this; it must report it. */
+  | 'misconfigured';
+
+/**
+ * What each kind means, for anything that has to explain them.
+ *
+ * ⛔ TYPED AS Record<ErrorKind, string>, WHICH IS THE POINT: adding a kind above without
+ *   describing it here is a COMPILE ERROR. A hand-kept list beside a union goes stale,
+ *   and a documented error contract with a missing case is worse than none — it is
+ *   trusted.
+ */
+export const KIND_DESCRIPTIONS: Record<ErrorKind, string> = {
+  unauthenticated: 'The credential was missing, malformed, or rejected.',
+  forbidden: 'The credential is valid but lacks the required grant. Do not retry.',
+  upstream_rejected: 'The upstream refused the request as made.',
+  rate_limited: 'Throttled. The identical call succeeds after the stated delay.',
+  upstream_unreachable: 'The upstream could not be reached. A retry may succeed.',
+  bad_arguments: 'The arguments were not acceptable. Correct them and retry.',
+  misconfigured: 'This service is misconfigured and cannot serve the request.',
+};
+
+export interface KitErrorOptions {
+  /** Which system failed. ⛔ Name it — "request failed" tells a caller nothing. */
+  readonly system: string;
+  /** What would make it work. This is what stops an agent retrying forever. */
+  readonly remedy?: string;
+  /** For `rate_limited`: how long to wait, in milliseconds. */
+  readonly retryAfterMs?: number;
+  readonly cause?: unknown;
+}
+
+/** A failure with enough shape for a caller to decide what to do next. */
+export class KitError extends Error {
+  readonly kind: ErrorKind;
+  readonly system: string;
+  readonly remedy: string | undefined;
+  readonly retryAfterMs: number | undefined;
+
+  constructor(kind: ErrorKind, message: string, options: KitErrorOptions) {
+    super(`${options.system}: ${message}`, { cause: options.cause });
+    this.name = 'KitError';
+    this.kind = kind;
+    this.system = options.system;
+    this.remedy = options.remedy;
+    this.retryAfterMs = options.retryAfterMs;
+  }
+
+  /** True when retrying the identical call could plausibly succeed. */
+  get retryable(): boolean {
+    return this.kind === 'rate_limited' || this.kind === 'upstream_unreachable';
+  }
+}
+
+/**
+ * Map an HTTP status to a kind.
+ *
+ * ⚠️ 429 IS CHECKED EXPLICITLY, not left to fall through. It used to reach
+ *   `upstream_rejected` here and `bad_arguments` elsewhere — both of which tell a caller
+ *   to CHANGE ITS ARGUMENTS, which is precisely wrong for a throttle.
+ */
+export function kindForStatus(status: number): ErrorKind {
+  if (status === 401) return 'unauthenticated';
+  if (status === 403) return 'forbidden';
+  if (status === 429) return 'rate_limited';
+  if (status >= 500) return 'upstream_unreachable';
+  return 'upstream_rejected';
+}

package/src/http.ts

@@ -0,0 +1,52 @@
+/**
+ * HTTP client — a configured `ky`, not a wrapper around it.
+ *
+ * ★ WHY ky AND NOT A HAND-ROLLED fetch+retry. Retry, timeout and backoff are each easy
+ *   to write and easy to write subtly wrong (retrying a POST, retrying a 4xx, a timeout
+ *   that leaks the AbortController). ky is zero-dependency, TypeScript-native and
+ *   fetch-based — measured 2026-09-15: `npm view ky dependencies` is empty — so it adds
+ *   nothing to a consumer's tree.
+ *   ⚠️ ky is described as browser-first, which matters only in that it assumes a global
+ *     `fetch`. workerd, Node 18+ and Bun all provide one, so there is nothing to polyfill.
+ *   ⛔ NOT ofetch (pulls destr + node-fetch-native) and NOT wretch, which is BROKEN on
+ *     Workers out of the box: Cloudflare's Response has no `.type` and wretch throws
+ *     reading it, needing a middleware patch to work at all.
+ *
+ * ★ THIS MODULE IS DELIBERATELY THIN. It re-exports ky's own types rather than inventing
+ *   parallel ones, so a caller who needs something not covered here uses ky directly and
+ *   loses nothing.
+ */
+import ky, { HTTPError, TimeoutError, type KyInstance, type Options } from 'ky';
+
+export { HTTPError, TimeoutError };
+export type { KyInstance, Options };
+
+/**
+ * The house defaults.
+ *
+ * ⚠️ ky retries only IDEMPOTENT methods by default (GET/PUT/HEAD/DELETE/OPTIONS/TRACE) —
+ *   POST is excluded, which is the behaviour you want and the one a hand-rolled retry
+ *   usually gets wrong. Retried status codes are 408/413/429/500/502/503/504.
+ * ⚠️ `timeout` is PER ATTEMPT, not for the whole call. With limit 3 and a 10s timeout the
+ *   worst case is ~30s plus backoff — shorten both for a Worker on a request path, where
+ *   the CPU-time limit is unforgiving.
+ */
+export const http: KyInstance = ky.extend({
+  retry: { limit: 3, backoffLimit: 3_000 },
+  timeout: 10_000,
+});
+
+/**
+ * A client bound to one base URL, for talking to a specific service.
+ *
+ *     const linear = client('https://api.linear.app', { headers: { authorization } });
+ *     const issues = await linear.get('/graphql').json<Issues>();
+ *
+ * ⚠️ `baseUrl`, NOT `prefixUrl`. ky 2.x renamed the option and changed its semantics:
+ *   `baseUrl` resolves per the URL standard, so a leading slash is fine and an absolute
+ *   input bypasses the base. (ky 1.x had `prefixUrl`, which threw on a leading slash —
+ *   measured 2026-09-15, the old name is a type error, not a silent no-op.)
+ */
+export function client(baseUrl: string, options?: Options): KyInstance {
+  return http.extend({ ...options, baseUrl });
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+/**
+ * @homeflare/kit — the estate's shared primitives.
+ *
+ * ⛔ THIS ENTRYPOINT STAYS RUNTIME-NEUTRAL. Bun is how the kit is authored, built and
+ *   tested; it is not what consumers run. The monorepo ships this code to Cloudflare
+ *   Workers, so anything reaching for `bun:*`, `node:fs` or a filesystem belongs behind
+ *   its own subpath export (`@homeflare/kit/<area>`), never here.
+ *   The failure this prevents is a deploy-time one: a `bun:sqlite` import that resolves
+ *   fine on a laptop and fails only in workerd, where the stack trace names the bundler
+ *   rather than this file.
+ *
+ * ★ isolatedDeclarations is on, so every exported symbol below carries an explicit
+ *   return type. That is not style — `bun build` cannot emit .d.ts, so declarations come
+ *   from a separate tsc pass, and explicit types are what keep the two in agreement.
+ */
+
+export { VERSION } from './version.ts';
+export { EnvError, isUnset, parseEnv, type EnvSchema, type EnvSpec } from './env.ts';
+export {
+  KIND_DESCRIPTIONS,
+  KitError,
+  kindForStatus,
+  type ErrorKind,
+  type KitErrorOptions,
+} from './errors.ts';
+export { client, http, HTTPError, TimeoutError, type KyInstance, type Options } from './http.ts';

package/src/version.ts

@@ -0,0 +1,2 @@
+// ⛔ GENERATED by scripts/sync-versions.ts — do not edit. Source: package.json.
+export const VERSION: string = '0.1.0';