@somewhatintelligent/kit 0.0.1-beta.1783705886.297c5be

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@somewhatintelligent/kit",
+  "version": "0.0.1-beta.1783705886.297c5be",
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/apostolos-geyer/platform.git",
+    "directory": "packages/kit"
+  },
+  "exports": {
+    "./ids": "./src/ids/index.ts",
+    "./roles": "./src/roles.ts",
+    "./log": "./src/log/index.ts",
+    "./request-context": "./src/request-context/index.ts",
+    "./version": "./src/version/index.ts",
+    "./react": "./src/react/index.ts",
+    "./react-start": "./src/react-start/index.ts",
+    "./react-start/client": "./src/react-start/client.ts",
+    "./execution-context": "./src/execution-context/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@somewhatintelligent/auth": "^0.0.0",
+    "ulidx": "^2.4.1"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4",
+    "@tanstack/react-start": "1.168.18",
+    "@types/node": "^25.5.2",
+    "@types/react": "^19.2.14",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "typescript": "5.9.2",
+    "vitest": "^4.1.10"
+  },
+  "peerDependencies": {
+    "@tanstack/react-start": "1.168.18",
+    "react": "19.2.4"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/react-start": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  }
+}

package/src/execution-context/index.ts

@@ -0,0 +1,16 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/** Minimal structural view of Cloudflare's ExecutionContext — avoids a
+ *  @cloudflare/workers-types dependency in @somewhatintelligent/kit. The real
+ *  ExecutionContext (worker-configuration.d.ts in each worker) is
+ *  structurally assignable to this. */
+export interface WaitUntilContext {
+  waitUntil(promise: Promise<unknown>): void;
+}
+
+export const executionContext = new AsyncLocalStorage<WaitUntilContext>();
+
+export const runWithExecutionContext = <T>(
+  ctx: WaitUntilContext,
+  fn: () => Promise<T>,
+): Promise<T> => executionContext.run(ctx, fn);

package/src/ids/__tests__/index.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, test } from "vitest";
+import { decodeTime, id, isValid, ulid } from "../index";
+
+describe("ulid", () => {
+  test("returns a 26-char Crockford base32 string", () => {
+    const value = ulid();
+    expect(value).toHaveLength(26);
+    expect(value).toMatch(/^[0-9A-HJKMNP-TV-Z]{26}$/);
+  });
+
+  test("is monotonic within the same millisecond (CF Workers correctness)", () => {
+    // Same sync block — Date.now() returns the same value for all calls.
+    // Without monotonicFactory, lex order would be random; with it, strictly increasing.
+    const batch = Array.from({ length: 100 }, () => ulid());
+    const sorted = [...batch].sort();
+    expect(batch).toEqual(sorted);
+    expect(new Set(batch).size).toBe(100);
+  });
+});
+
+describe("id (prefixed)", () => {
+  test("composes prefix + monotonic ulid with hyphen separator", () => {
+    const value = id("grant");
+    expect(value).toMatch(/^grant-[0-9A-HJKMNP-TV-Z]{26}$/);
+  });
+
+  test("rejects invalid prefixes", () => {
+    expect(() => id("Grant")).toThrow();
+    expect(() => id("9bad")).toThrow();
+    expect(() => id("toolongprefix1")).toThrow();
+    expect(() => id("with-hyphen")).toThrow();
+    expect(() => id("")).toThrow();
+  });
+
+  test("is monotonic within the same millisecond per prefix", () => {
+    const batch = Array.from({ length: 50 }, () => id("act"));
+    const sorted = [...batch].sort();
+    expect(batch).toEqual(sorted);
+  });
+});
+
+describe("decodeTime", () => {
+  test("decodes plain ULID timestamp", () => {
+    const before = Date.now();
+    const value = ulid();
+    const after = Date.now();
+    const decoded = decodeTime(value);
+    expect(decoded).toBeGreaterThanOrEqual(before);
+    expect(decoded).toBeLessThanOrEqual(after);
+  });
+
+  test("decodes prefixed ULID timestamp", () => {
+    const before = Date.now();
+    const value = id("trk");
+    const after = Date.now();
+    const decoded = decodeTime(value);
+    expect(decoded).toBeGreaterThanOrEqual(before);
+    expect(decoded).toBeLessThanOrEqual(after);
+  });
+});
+
+describe("isValid", () => {
+  test("accepts plain and prefixed ULIDs", () => {
+    expect(isValid(ulid())).toBe(true);
+    expect(isValid(id("grant"))).toBe(true);
+  });
+
+  test("rejects garbage", () => {
+    expect(isValid("not-a-ulid")).toBe(false);
+    expect(isValid("")).toBe(false);
+    expect(isValid("01HZX5F7ABCDEF123456GHJKM")).toBe(false); // 25 chars
+  });
+
+  test("expectedPrefix asserts entity match", () => {
+    const grantId = id("grant");
+    expect(isValid(grantId, "grant")).toBe(true);
+    expect(isValid(grantId, "trk")).toBe(false);
+    expect(isValid(ulid(), "grant")).toBe(false); // unprefixed value
+  });
+});

package/src/ids/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Monotonic ULID factory + entity-prefixed IDs.
+ *
+ * On Cloudflare Workers, `Date.now()` is pinned at the start of a request and
+ * does not advance until the next I/O. Multiple ULIDs minted in the same sync
+ * block therefore share a timestamp; without a monotonic factory, each draws
+ * an independent random suffix and lex ordering is no longer guaranteed.
+ * `ulidx`'s own docs flag plain `ulid()` as unsafe in this runtime — the
+ * factory must be a per-isolate singleton, declared once at module scope.
+ */
+import { monotonicFactory, decodeTime as ulidDecodeTime, isValid as ulidIsValid } from "ulidx";
+
+const monotonic = monotonicFactory();
+
+/** Mint a monotonic ULID (26 chars, Crockford base32). Module-singleton factory. */
+export function ulid(): string {
+  return monotonic();
+}
+
+const PREFIX_RE = /^[a-z][a-z0-9]{0,9}$/;
+
+/**
+ * Mint a prefixed ID of the form `<prefix>-<monotonic-ulid>`.
+ * Prefix must be lowercase alphanumeric, start with a letter, ≤10 chars.
+ *
+ * Example: `id("grant")` → `"grant-01HZX5F7ABCDEF123456GHJKMN"`.
+ */
+export function id(prefix: string): string {
+  if (!PREFIX_RE.test(prefix)) {
+    throw new Error(
+      `Invalid id prefix: ${prefix}. Must be lowercase alphanumeric, start with a letter, ≤10 chars.`,
+    );
+  }
+  return `${prefix}-${monotonic()}`;
+}
+
+/** Decode the timestamp (ms) embedded in a plain or prefixed ULID. */
+export function decodeTime(value: string): number {
+  const idx = value.indexOf("-");
+  const body = idx === -1 ? value : value.slice(idx + 1);
+  return ulidDecodeTime(body);
+}
+
+/**
+ * Validate that `value` is a (possibly prefixed) ULID.
+ * Pass `expectedPrefix` to assert a specific entity prefix.
+ */
+export function isValid(value: string, expectedPrefix?: string): boolean {
+  const idx = value.indexOf("-");
+  if (expectedPrefix !== undefined) {
+    if (idx === -1) return false;
+    if (value.slice(0, idx) !== expectedPrefix) return false;
+    return ulidIsValid(value.slice(idx + 1));
+  }
+  if (idx === -1) return ulidIsValid(value);
+  return ulidIsValid(value.slice(idx + 1));
+}
+
+/** Escape hatch — the underlying monotonic factory, for callers that need raw access. */
+export { monotonic };

package/src/log/__tests__/http.test.ts

@@ -0,0 +1,109 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { requireRequestLog } from "../index";
+import { withRequestLog } from "../http";
+
+let logSpy: ReturnType<typeof vi.spyOn>;
+let errorSpy: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+  errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  logSpy.mockRestore();
+  errorSpy.mockRestore();
+});
+
+const baseConfig = {
+  service: "guestlist",
+  resolveContext: (req: Request) => ({
+    requestId: req.headers.get("cf-request-id") ?? "fallback",
+    actorKind: "anonymous",
+    actorId: null,
+  }),
+};
+
+describe("withRequestLog", () => {
+  test("emits event=http line with method/path auto-added", async () => {
+    const req = new Request("https://example.com/api/sign-in", {
+      method: "POST",
+      headers: { "cf-request-id": "req_42" },
+    });
+
+    await withRequestLog(baseConfig, req, async () => new Response("ok"));
+
+    expect(logSpy).toHaveBeenCalledTimes(1);
+    expect(logSpy.mock.calls[0]![0]).toMatchObject({
+      service: "guestlist",
+      event: "http",
+      operation: "http.post",
+      method: "POST",
+      path: "/api/sign-in",
+      request_id: "req_42",
+    });
+  });
+
+  test("default operation derives from method", async () => {
+    const get = new Request("https://example.com/x", { method: "GET" });
+    const post = new Request("https://example.com/x", { method: "POST" });
+
+    await withRequestLog(baseConfig, get, async () => new Response());
+    await withRequestLog(baseConfig, post, async () => new Response());
+
+    expect(logSpy.mock.calls[0]![0]).toMatchObject({ operation: "http.get" });
+    expect(logSpy.mock.calls[1]![0]).toMatchObject({ operation: "http.post" });
+  });
+
+  test("deriveOperation override produces route-aware op names", async () => {
+    const req = new Request("https://example.com/api/upload", { method: "POST" });
+    await withRequestLog(
+      {
+        ...baseConfig,
+        deriveOperation: (r) => `roadie.${new URL(r.url).pathname.split("/").pop()}`,
+      },
+      req,
+      async () => new Response(),
+    );
+    expect(logSpy.mock.calls[0]![0]).toMatchObject({ operation: "roadie.upload" });
+  });
+
+  test("middleware can add status + outcome via the builder", async () => {
+    const req = new Request("https://example.com/x", { method: "POST" });
+    await withRequestLog(baseConfig, req, async (log) => {
+      const status = 404;
+      log.add({ status });
+      log.outcome(`http_${status}`);
+      return new Response(null, { status });
+    });
+    expect(logSpy.mock.calls[0]![0]).toMatchObject({
+      status: 404,
+      outcome: "http_404",
+    });
+  });
+
+  test("requireRequestLog inside fn captures domain fields", async () => {
+    const req = new Request("https://example.com/x", { method: "POST" });
+    await withRequestLog(baseConfig, req, async () => {
+      requireRequestLog().add({ user_id: "u1", session_age_ms: 12345 });
+      return new Response();
+    });
+    expect(logSpy.mock.calls[0]![0]).toMatchObject({
+      user_id: "u1",
+      session_age_ms: 12345,
+    });
+  });
+
+  test("throw → internal_error + rethrow", async () => {
+    const req = new Request("https://example.com/x", { method: "POST" });
+    await expect(
+      withRequestLog(baseConfig, req, async () => {
+        throw new Error("kaboom");
+      }),
+    ).rejects.toThrow("kaboom");
+    expect(errorSpy.mock.calls[0]![0]).toMatchObject({
+      outcome: "internal_error",
+      error_message: "kaboom",
+    });
+  });
+});

package/src/log/__tests__/index.test.ts

@@ -0,0 +1,254 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { describeThrown, getRequestLog, requireRequestLog, withCanonicalLog } from "../index";
+
+const baseCtx = {
+  service: "test_service",
+  event: "rpc",
+  operation: "test.op",
+  requestId: "req_01",
+  actorKind: "user",
+  actorId: "user_01",
+  callerApp: "test_app",
+};
+
+let logSpy: ReturnType<typeof vi.spyOn>;
+let warnSpy: ReturnType<typeof vi.spyOn>;
+let errorSpy: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+  warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+  errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  logSpy.mockRestore();
+  warnSpy.mockRestore();
+  errorSpy.mockRestore();
+});
+
+describe("withCanonicalLog", () => {
+  test("emits one info-level line on normal return with outcome=ok", async () => {
+    const value = await withCanonicalLog(baseCtx, async () => 42);
+    expect(value).toBe(42);
+    expect(logSpy).toHaveBeenCalledTimes(1);
+    expect(errorSpy).not.toHaveBeenCalled();
+    const line = logSpy.mock.calls[0]![0] as Record<string, unknown>;
+    expect(line).toMatchObject({
+      service: "test_service",
+      event: "rpc",
+      operation: "test.op",
+      outcome: "ok",
+      request_id: "req_01",
+      caller_app: "test_app",
+      actor_kind: "user",
+      actor_id: "user_01",
+    });
+    expect(typeof line.duration_ms).toBe("number");
+    expect(typeof line.time).toBe("string");
+  });
+
+  test("emits at error level when outcome is in errorOutcomes set", async () => {
+    await withCanonicalLog(baseCtx, async (log) => {
+      log.outcome("backend_unavailable");
+    });
+    expect(errorSpy).toHaveBeenCalledTimes(1);
+    expect(logSpy).not.toHaveBeenCalled();
+    expect(errorSpy.mock.calls[0]![0]).toMatchObject({ outcome: "backend_unavailable" });
+  });
+
+  test("emits at info level for non-error outcomes (e.g. expected client errors)", async () => {
+    await withCanonicalLog(baseCtx, async (log) => {
+      log.outcome("not_found");
+    });
+    expect(logSpy).toHaveBeenCalledTimes(1);
+    expect(errorSpy).not.toHaveBeenCalled();
+    expect(logSpy.mock.calls[0]![0]).toMatchObject({ outcome: "not_found" });
+  });
+
+  test("on throw: emits internal_error at error level + rethrows", async () => {
+    await expect(
+      withCanonicalLog(baseCtx, async () => {
+        throw new Error("boom");
+      }),
+    ).rejects.toThrow("boom");
+    expect(errorSpy).toHaveBeenCalledTimes(1);
+    expect(errorSpy.mock.calls[0]![0]).toMatchObject({
+      outcome: "internal_error",
+      error_message: "boom",
+    });
+  });
+
+  test("merges builder.add() fields into the line", async () => {
+    await withCanonicalLog(baseCtx, async (log) => {
+      log.add({ resource_id: "res_01", part_number: 3 });
+    });
+    expect(logSpy.mock.calls[0]![0]).toMatchObject({
+      resource_id: "res_01",
+      part_number: 3,
+    });
+  });
+
+  test("strips forbidden fields by exact name and prefix", async () => {
+    await withCanonicalLog(baseCtx, async (log) => {
+      log.add({
+        password: "hunter2",
+        cookie: "session=abc",
+        R2_BUCKET: "secret",
+        S3_ACCESS_KEY_ID: "AKIA...",
+        safe_field: "kept",
+      });
+    });
+    const line = logSpy.mock.calls[0]![0] as Record<string, unknown>;
+    expect(line.password).toBeUndefined();
+    expect(line.cookie).toBeUndefined();
+    expect(line.R2_BUCKET).toBeUndefined();
+    expect(line.S3_ACCESS_KEY_ID).toBeUndefined();
+    expect(line.safe_field).toBe("kept");
+  });
+
+  test("custom errorOutcomes / forbiddenFields override defaults", async () => {
+    await withCanonicalLog(
+      {
+        ...baseCtx,
+        errorOutcomes: new Set(["custom_failure"]),
+        forbiddenFields: new Set(["my_secret"]),
+        forbiddenPrefixes: ["INTERNAL_"],
+      },
+      async (log) => {
+        log.add({ my_secret: "x", INTERNAL_KEY: "y", password: "still-here" });
+        log.outcome("custom_failure");
+      },
+    );
+    expect(errorSpy).toHaveBeenCalledTimes(1);
+    const line = errorSpy.mock.calls[0]![0] as Record<string, unknown>;
+    expect(line.my_secret).toBeUndefined();
+    expect(line.INTERNAL_KEY).toBeUndefined();
+    expect(line.password).toBe("still-here"); // default list overridden
+  });
+
+  test("duration_ms reflects elapsed time", async () => {
+    await withCanonicalLog(baseCtx, async () => {
+      await new Promise((r) => setTimeout(r, 20));
+    });
+    const line = logSpy.mock.calls[0]![0] as Record<string, unknown>;
+    expect(line.duration_ms).toBeGreaterThanOrEqual(15);
+  });
+
+  test("last builder.outcome() call wins", async () => {
+    await withCanonicalLog(baseCtx, async (log) => {
+      log.outcome("first");
+      log.outcome("second");
+    });
+    expect(logSpy.mock.calls[0]![0]).toMatchObject({ outcome: "second" });
+  });
+});
+
+describe("AsyncLocalStorage propagation", () => {
+  test("getRequestLog() returns the active builder inside scope", async () => {
+    let captured: ReturnType<typeof getRequestLog> = null;
+    await withCanonicalLog(baseCtx, async () => {
+      captured = getRequestLog();
+    });
+    expect(captured).not.toBeNull();
+  });
+
+  test("getRequestLog() returns null outside any scope", () => {
+    expect(getRequestLog()).toBeNull();
+  });
+
+  test("requireRequestLog() throws outside any scope", () => {
+    expect(() => requireRequestLog()).toThrow(/outside any withCanonicalLog scope/);
+  });
+
+  test("fields accrued via getRequestLog() in nested awaits land on the line", async () => {
+    async function deep() {
+      await new Promise((r) => setTimeout(r, 5));
+      requireRequestLog().add({ from_deep: true });
+    }
+    async function middle() {
+      requireRequestLog().add({ from_middle: 1 });
+      await deep();
+    }
+    await withCanonicalLog(baseCtx, async () => {
+      await middle();
+    });
+    expect(logSpy.mock.calls[0]![0]).toMatchObject({
+      from_middle: 1,
+      from_deep: true,
+    });
+  });
+
+  test("outcome set via getRequestLog() in deep call is honored", async () => {
+    async function deep() {
+      requireRequestLog().outcome("not_found");
+    }
+    await withCanonicalLog(baseCtx, async () => {
+      await deep();
+    });
+    expect(logSpy.mock.calls[0]![0]).toMatchObject({ outcome: "not_found" });
+  });
+
+  test("nested withCanonicalLog scopes are independent (inner does not leak to outer)", async () => {
+    await withCanonicalLog({ ...baseCtx, operation: "outer" }, async (outerLog) => {
+      outerLog.add({ at: "outer" });
+      await withCanonicalLog({ ...baseCtx, operation: "inner" }, async (innerLog) => {
+        innerLog.add({ at: "inner" });
+        // requireRequestLog inside inner scope returns inner's builder
+        expect(requireRequestLog()).toBe(innerLog);
+      });
+      // Back in outer scope, requireRequestLog returns outer's builder
+      expect(requireRequestLog()).toBe(outerLog);
+    });
+    expect(logSpy).toHaveBeenCalledTimes(2);
+    const innerLine = logSpy.mock.calls.find(
+      (c: unknown[]) => (c[0] as Record<string, unknown>).operation === "inner",
+    )![0] as Record<string, unknown>;
+    const outerLine = logSpy.mock.calls.find(
+      (c: unknown[]) => (c[0] as Record<string, unknown>).operation === "outer",
+    )![0] as Record<string, unknown>;
+    expect(innerLine.at).toBe("inner");
+    expect(outerLine.at).toBe("outer");
+    // Outer line does NOT carry the inner field
+    expect(outerLine.from_inner).toBeUndefined();
+  });
+});
+
+describe("describeThrown", () => {
+  test("Error → message + stack", () => {
+    const err = new Error("boom");
+    const d = describeThrown(err);
+    expect(d.message).toBe("boom");
+    expect(d.stack).toBe(err.stack);
+  });
+
+  test("thrown Response → named by status, never '[object Response]'", () => {
+    const d = describeThrown(new Response(null, { status: 307 }));
+    expect(d.message).toBe("thrown Response (status 307)");
+    expect(d.stack).toBeUndefined();
+  });
+
+  test("plain object → JSON, never '[object Object]'", () => {
+    expect(describeThrown({ isNotFound: true }).message).toBe('{"isNotFound":true}');
+  });
+
+  test("primitive → String()", () => {
+    expect(describeThrown("nope").message).toBe("nope");
+  });
+});
+
+describe("withCanonicalLog thrown-Response serialization", () => {
+  test("a thrown Response emits a readable error_message", async () => {
+    await expect(
+      withCanonicalLog(baseCtx, async () => {
+        throw new Response(null, { status: 307, headers: { location: "/sign-in" } });
+      }),
+    ).rejects.toBeInstanceOf(Response);
+    expect(errorSpy).toHaveBeenCalledTimes(1);
+    expect(errorSpy.mock.calls[0]![0]).toMatchObject({
+      outcome: "internal_error",
+      error_message: "thrown Response (status 307)",
+      error_stack: "thrown Response (status 307)",
+    });
+  });
+});