@decocms/start 2.25.0 → 2.27.0

package/src/sdk/cookie.ts

@@ -37,3 +37,93 @@ export function decodeCookie(cookieValue: string): any {
     return null;
   }
 }
+
+// ---------------------------------------------------------------------------
+// Server-side cookie helpers — Web-platform / Workers-friendly.
+//
+// These mirror the surface area of Deno's `@std/http/cookie`, which deco
+// storefronts depended on heavily before TanStack/Workers migration. Sites
+// can now import from "@decocms/start/sdk/cookie" instead of shipping a
+// per-site shim or pulling JSR.
+// ---------------------------------------------------------------------------
+
+export interface Cookie {
+  name: string;
+  value: string;
+  expires?: Date | number;
+  maxAge?: number;
+  domain?: string;
+  path?: string;
+  secure?: boolean;
+  httpOnly?: boolean;
+  sameSite?: "Strict" | "Lax" | "None";
+}
+
+/**
+ * Parse all cookies from a Request's `Cookie` header into a plain object.
+ * Returns `{}` when no cookies are present. Values are URL-decoded.
+ *
+ * Equivalent to `getCookies(req.headers)` from `@std/http/cookie`.
+ */
+export function getCookies(headers: Headers): Record<string, string> {
+  const cookie = headers.get("cookie");
+  if (!cookie) return {};
+  const out: Record<string, string> = {};
+  for (const pair of cookie.split(/;\s*/)) {
+    const eq = pair.indexOf("=");
+    if (eq === -1) continue;
+    const name = pair.slice(0, eq).trim();
+    if (!name) continue;
+    const value = pair.slice(eq + 1).trim();
+    try {
+      out[name] = decodeURIComponent(value);
+    } catch {
+      out[name] = value;
+    }
+  }
+  return out;
+}
+
+/**
+ * Serialize a cookie spec and append a `Set-Cookie` header to a Response's
+ * `Headers`. Equivalent to `setCookie(headers, cookie)` from `@std/http/cookie`.
+ *
+ * Note: this uses `headers.append`, not `set`, so multiple cookies stack
+ * correctly (a single `Set-Cookie` header cannot represent multiple cookies).
+ */
+export function setResponseCookie(headers: Headers, cookie: Cookie): void {
+  const parts = [`${cookie.name}=${cookie.value}`];
+  if (cookie.expires !== undefined) {
+    const date = cookie.expires instanceof Date
+      ? cookie.expires
+      : new Date(cookie.expires);
+    parts.push(`Expires=${date.toUTCString()}`);
+  }
+  if (cookie.maxAge !== undefined) parts.push(`Max-Age=${cookie.maxAge}`);
+  if (cookie.domain) parts.push(`Domain=${cookie.domain}`);
+  if (cookie.path) parts.push(`Path=${cookie.path}`);
+  if (cookie.secure) parts.push("Secure");
+  if (cookie.httpOnly) parts.push("HttpOnly");
+  if (cookie.sameSite) parts.push(`SameSite=${cookie.sameSite}`);
+  headers.append("Set-Cookie", parts.join("; "));
+}
+
+/**
+ * Append a delete instruction (`Max-Age=0` + epoch `Expires`) for a cookie.
+ * `path` and `domain` should match the original `setResponseCookie` call to
+ * actually clear the cookie in the browser.
+ */
+export function deleteResponseCookie(
+  headers: Headers,
+  name: string,
+  attributes: { path?: string; domain?: string } = {},
+): void {
+  setResponseCookie(headers, {
+    name,
+    value: "",
+    expires: new Date(0),
+    maxAge: 0,
+    path: attributes.path,
+    domain: attributes.domain,
+  });
+}

package/src/sdk/encoding.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+import {
+  decodeBase64,
+  decodeBase64Url,
+  encodeBase64,
+  encodeBase64Url,
+} from "./encoding";
+
+describe("encodeBase64 / decodeBase64", () => {
+  it("round-trips ASCII strings", () => {
+    const data = "hello, world";
+    const b64 = encodeBase64(data);
+    expect(b64).toBe("aGVsbG8sIHdvcmxk");
+    const decoded = new TextDecoder().decode(decodeBase64(b64));
+    expect(decoded).toBe(data);
+  });
+
+  it("round-trips multi-byte UTF-8", () => {
+    const data = "São Paulo — café ☕";
+    const b64 = encodeBase64(data);
+    const decoded = new TextDecoder().decode(decodeBase64(b64));
+    expect(decoded).toBe(data);
+  });
+
+  it("accepts Uint8Array input", () => {
+    const bytes = new Uint8Array([1, 2, 3, 4, 5]);
+    const b64 = encodeBase64(bytes);
+    expect(decodeBase64(b64)).toEqual(bytes);
+  });
+
+  it("accepts ArrayBuffer input", () => {
+    const buf = new Uint8Array([255, 254, 253]).buffer;
+    const b64 = encodeBase64(buf);
+    expect(Array.from(decodeBase64(b64))).toEqual([255, 254, 253]);
+  });
+
+  it("handles inputs larger than the chunking window", () => {
+    // 0x8000 + 7 bytes — forces the chunking branch.
+    const bytes = new Uint8Array(0x8000 + 7);
+    for (let i = 0; i < bytes.length; i++) bytes[i] = i & 0xff;
+    const b64 = encodeBase64(bytes);
+    expect(decodeBase64(b64)).toEqual(bytes);
+  });
+});
+
+describe("encodeBase64Url / decodeBase64Url", () => {
+  it("uses URL-safe alphabet and strips padding", () => {
+    // Inputs that produce '+', '/', and padding under standard base64.
+    const bytes = new Uint8Array([251, 255, 191, 251, 239, 254]);
+    const standard = encodeBase64(bytes);
+    const url = encodeBase64Url(bytes);
+    // Every '+' becomes '-', '/' becomes '_', trailing '=' is stripped.
+    expect(url).toBe(
+      standard.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""),
+    );
+    expect(url).not.toContain("+");
+    expect(url).not.toContain("/");
+    expect(url).not.toContain("=");
+  });
+
+  it("round-trips through the URL-safe pair", () => {
+    const data = new Uint8Array(64);
+    for (let i = 0; i < data.length; i++) data[i] = (i * 7) & 0xff;
+    expect(decodeBase64Url(encodeBase64Url(data))).toEqual(data);
+  });
+
+  it("decodes inputs missing their padding", () => {
+    // 'a' = 0x61. encodeBase64('a') = 'YQ==', URL form drops to 'YQ'.
+    expect(new TextDecoder().decode(decodeBase64Url("YQ"))).toBe("a");
+  });
+});

package/src/sdk/encoding.ts

@@ -0,0 +1,47 @@
+/**
+ * Web-platform base64 / base64url helpers.
+ *
+ * Replaces the surface area of Deno's `@std/encoding/base64` so deco
+ * storefronts on TanStack/Workers can drop the per-site shim.
+ *
+ * All implementations use the global `btoa` / `atob` (available in Workers,
+ * browsers, and Node 16+) so there is zero runtime dependency.
+ */
+
+function toBytes(data: ArrayBuffer | Uint8Array | string): Uint8Array {
+  if (typeof data === "string") return new TextEncoder().encode(data);
+  if (data instanceof ArrayBuffer) return new Uint8Array(data);
+  return data;
+}
+
+export function encodeBase64(data: ArrayBuffer | Uint8Array | string): string {
+  const bytes = toBytes(data);
+  // Build the binary string in chunks to avoid blowing the call stack on
+  // large inputs (`String.fromCharCode(...bytes)` spreads the entire array).
+  let bin = "";
+  const CHUNK = 0x8000;
+  for (let i = 0; i < bytes.byteLength; i += CHUNK) {
+    bin += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+  }
+  return btoa(bin);
+}
+
+export function decodeBase64(b64: string): Uint8Array {
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+export function encodeBase64Url(data: ArrayBuffer | Uint8Array | string): string {
+  return encodeBase64(data)
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+export function decodeBase64Url(b64url: string): Uint8Array {
+  const padded = b64url.replace(/-/g, "+").replace(/_/g, "/");
+  const padLen = (4 - (padded.length % 4)) % 4;
+  return decodeBase64(padded + "=".repeat(padLen));
+}

package/src/sdk/http.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+import { HttpError, STATUS_CODE, UserAgent } from "./http";
+
+describe("STATUS_CODE", () => {
+  it("exposes common codes with the IANA-canonical names", () => {
+    expect(STATUS_CODE.OK).toBe(200);
+    expect(STATUS_CODE.MovedPermanently).toBe(301);
+    expect(STATUS_CODE.NotFound).toBe(404);
+    expect(STATUS_CODE.TooManyRequests).toBe(429);
+    expect(STATUS_CODE.InternalServerError).toBe(500);
+  });
+
+  it("is readonly at the type level", () => {
+    // @ts-expect-error — assigning into the const map should not type-check.
+    STATUS_CODE.OK = 999;
+    // Even though the assignment is allowed at runtime (frozen-by-convention),
+    // we just want the type to flag it. The value is whatever JS allows.
+    expect(typeof STATUS_CODE.OK).toBe("number");
+  });
+});
+
+describe("UserAgent", () => {
+  it("accepts a string and exposes it via toString", () => {
+    const ua = new UserAgent("Mozilla/5.0 (test)");
+    expect(ua.toString()).toBe("Mozilla/5.0 (test)");
+  });
+
+  it("treats null as an empty UA string", () => {
+    const ua = new UserAgent(null);
+    expect(ua.toString()).toBe("");
+  });
+
+  it("exposes empty browser/os/cpu/device/engine accessors", () => {
+    const ua = new UserAgent("anything");
+    expect(ua.browser).toEqual({});
+    expect(ua.os).toEqual({});
+    expect(ua.cpu).toEqual({});
+    expect(ua.device).toEqual({});
+    expect(ua.engine).toEqual({});
+  });
+});
+
+describe("HttpError", () => {
+  it("captures status and message", () => {
+    const err = new HttpError(404, "Missing");
+    expect(err).toBeInstanceOf(Error);
+    expect(err.name).toBe("HttpError");
+    expect(err.status).toBe(404);
+    expect(err.message).toBe("Missing");
+  });
+
+  it("defaults the message from the status when not provided", () => {
+    const err = new HttpError(503);
+    expect(err.message).toBe("HTTP 503");
+  });
+
+  it("preserves an optional body payload for downstream handling", () => {
+    const body = { code: "rate_limited" };
+    const err = new HttpError(429, "Too Many Requests", body);
+    expect(err.body).toEqual(body);
+  });
+
+  it("supports `instanceof` discrimination", () => {
+    const err = new HttpError(304);
+    function isNotModified(e: unknown): e is HttpError {
+      return e instanceof HttpError && e.status === 304;
+    }
+    expect(isNotModified(err)).toBe(true);
+    expect(isNotModified(new Error("nope"))).toBe(false);
+  });
+});

package/src/sdk/http.ts

@@ -0,0 +1,124 @@
+/**
+ * HTTP constants and small typed helpers — replaces the parts of Deno's
+ * `@std/http` (other than cookies, which live in `./cookie.ts`) that deco
+ * storefronts touch.
+ *
+ * Currently exposes:
+ *   - `STATUS_CODE` — full IANA status-code map (parity with @std/http).
+ *   - `UserAgent`   — minimal class with the same shape; does not parse
+ *                     the UA string (sites only used `.toString()` and
+ *                     basic browser/os accessors in dev). Replace with a
+ *                     real parser like `ua-parser-js` if you actually
+ *                     depend on the parsed fields.
+ */
+
+export const STATUS_CODE = {
+  Continue: 100,
+  SwitchingProtocols: 101,
+  Processing: 102,
+  EarlyHints: 103,
+  OK: 200,
+  Created: 201,
+  Accepted: 202,
+  NonAuthoritativeInfo: 203,
+  NoContent: 204,
+  ResetContent: 205,
+  PartialContent: 206,
+  MultiStatus: 207,
+  AlreadyReported: 208,
+  IMUsed: 226,
+  MultipleChoices: 300,
+  MovedPermanently: 301,
+  Found: 302,
+  SeeOther: 303,
+  NotModified: 304,
+  UseProxy: 305,
+  TemporaryRedirect: 307,
+  PermanentRedirect: 308,
+  BadRequest: 400,
+  Unauthorized: 401,
+  PaymentRequired: 402,
+  Forbidden: 403,
+  NotFound: 404,
+  MethodNotAllowed: 405,
+  NotAcceptable: 406,
+  ProxyAuthRequired: 407,
+  RequestTimeout: 408,
+  Conflict: 409,
+  Gone: 410,
+  LengthRequired: 411,
+  PreconditionFailed: 412,
+  ContentTooLarge: 413,
+  URITooLong: 414,
+  UnsupportedMediaType: 415,
+  RangeNotSatisfiable: 416,
+  ExpectationFailed: 417,
+  Teapot: 418,
+  MisdirectedRequest: 421,
+  UnprocessableEntity: 422,
+  Locked: 423,
+  FailedDependency: 424,
+  TooEarly: 425,
+  UpgradeRequired: 426,
+  PreconditionRequired: 428,
+  TooManyRequests: 429,
+  RequestHeaderFieldsTooLarge: 431,
+  UnavailableForLegalReasons: 451,
+  InternalServerError: 500,
+  NotImplemented: 501,
+  BadGateway: 502,
+  ServiceUnavailable: 503,
+  GatewayTimeout: 504,
+  HTTPVersionNotSupported: 505,
+  VariantAlsoNegotiates: 506,
+  InsufficientStorage: 507,
+  LoopDetected: 508,
+  NotExtended: 510,
+  NetworkAuthenticationRequired: 511,
+} as const;
+
+export type StatusCode = typeof STATUS_CODE[keyof typeof STATUS_CODE];
+
+/**
+ * Minimal stand-in for Deno's `@std/http`'s `UserAgent`. Captures the raw
+ * UA string and exposes the same field shape; does NOT parse. Replace with
+ * a real parser when you start depending on parsed fields.
+ */
+export class UserAgent {
+  ua: string;
+  browser: { name?: string; version?: string };
+  os: { name?: string; version?: string };
+  device: { vendor?: string; model?: string; type?: string };
+  cpu: { architecture?: string };
+  engine: { name?: string; version?: string };
+
+  constructor(ua: string | null) {
+    this.ua = ua ?? "";
+    this.browser = {};
+    this.os = {};
+    this.device = {};
+    this.cpu = {};
+    this.engine = {};
+  }
+
+  toString(): string {
+    return this.ua;
+  }
+}
+
+/**
+ * Lightweight HTTP error class. Drop-in for the `HttpError` shape that
+ * `deco-cx/apps` exposes — sites use it as `error instanceof HttpError &&
+ * error.status === 304` and similar.
+ */
+export class HttpError extends Error {
+  status: number;
+  body?: unknown;
+
+  constructor(status: number, message?: string, body?: unknown) {
+    super(message ?? `HTTP ${status}`);
+    this.name = "HttpError";
+    this.status = status;
+    this.body = body;
+  }
+}

package/src/sdk/useScript.test.ts

@@ -1,5 +1,11 @@
-import { describe, expect, it } from "vitest";
-import { inlineScript, useScript } from "./useScript";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  HTMX_LEGACY_URL,
+  inlineScript,
+  usePartialSection,
+  useScript,
+  useSection,
+} from "./useScript";
 
 describe("inlineScript", () => {
   it("returns dangerouslySetInnerHTML with the provided string", () => {
@@ -51,3 +57,72 @@ describe("useScript", () => {
     expect(result).toMatch(/^\(.*\)\(\)$/);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Legacy HTMX stubs — useSection / usePartialSection
+// ---------------------------------------------------------------------------
+
+describe("useSection / usePartialSection (legacy HTMX stubs)", () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+  let prevNodeEnv: string | undefined;
+
+  beforeEach(() => {
+    // Reset the dedup set so each test sees a fresh warning fire.
+    delete (globalThis as any).__DECO_LEGACY_HTMX_WARNED;
+    prevNodeEnv = process.env.NODE_ENV;
+    process.env.NODE_ENV = "development";
+    warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+    if (prevNodeEnv === undefined) delete process.env.NODE_ENV;
+    else process.env.NODE_ENV = prevNodeEnv;
+  });
+
+  it("useSection returns a stable placeholder URL instead of throwing", () => {
+    expect(useSection()).toBe(HTMX_LEGACY_URL);
+    expect(useSection({ props: { x: 1 } })).toBe(HTMX_LEGACY_URL);
+  });
+
+  it("usePartialSection returns the same placeholder URL", () => {
+    expect(usePartialSection()).toBe(HTMX_LEGACY_URL);
+  });
+
+  it("warns on first call (in development)", () => {
+    useSection();
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy.mock.calls[0][0]).toMatch(/useSection/);
+    expect(warnSpy.mock.calls[0][0]).toMatch(/were removed/);
+    expect(warnSpy.mock.calls[0][0]).toMatch(/htmx-residue/);
+  });
+
+  it("dedups warnings: a second call to the same stub is silent", () => {
+    useSection();
+    useSection();
+    useSection();
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("tracks warnings per-stub: useSection and usePartialSection warn independently", () => {
+    useSection();
+    usePartialSection();
+    expect(warnSpy).toHaveBeenCalledTimes(2);
+    const messages = warnSpy.mock.calls.map((c) => c[0] as string);
+    expect(messages.some((m) => m.includes("useSection"))).toBe(true);
+    expect(messages.some((m) => m.includes("usePartialSection"))).toBe(true);
+  });
+
+  it("does NOT warn in production", () => {
+    process.env.NODE_ENV = "production";
+    useSection();
+    usePartialSection();
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("returns the placeholder URL even in production (still safe to embed)", () => {
+    process.env.NODE_ENV = "production";
+    expect(useSection()).toBe(HTMX_LEGACY_URL);
+    expect(usePartialSection()).toBe(HTMX_LEGACY_URL);
+  });
+});

package/src/sdk/useScript.ts

@@ -150,21 +150,61 @@ export function inlineScript(js: string) {
  * See: deco-to-tanstack-migration skill, "useComponent / partial sections"
  * section, for the per-pattern recipes.
  *
- * Both stubs throw at runtime (and at import time, if you call them at
- * module top level) so legacy code surfaces a clear error instead of a
- * silent no-op.
+ * ## SSR-safe stub behavior (since 2.27)
+ *
+ * Earlier versions threw on call. That broke SSR for the *entire page* if a
+ * single section still imported `useSection` — even sections that the user
+ * never interacts with (e.g. legacy login form on the homepage). React's
+ * error boundary would catch the throw and degrade the whole route to
+ * client rendering.
+ *
+ * The current behavior:
+ *   - returns a stable placeholder URL (`HTMX_LEGACY_URL`) so it can be
+ *     embedded in `hx-get` / `hx-post` attributes without crashing the
+ *     SSR pass,
+ *   - logs a deduped `console.warn` (in dev only) per call site so the
+ *     migration signal stays loud,
+ *   - the `htmx-residue` audit rule still catalogues every call site for
+ *     systematic rewrite.
+ *
+ * This is a deliberate trade-off: SSR success > strict-throw enforcement.
+ * Audit + skill docs do the enforcement instead.
  */
 const DEPRECATION_MESSAGE =
   "[@decocms/start] useSection / usePartialSection were removed. " +
   "The Fresh/Deno HTMX partial-section pattern does not apply on " +
   "TanStack Start / Cloudflare Workers. Replace call-sites with " +
   "createServerFn + useMutation, or local React state. See the " +
-  "deco-to-tanstack-migration skill for per-pattern recipes.";
+  "deco-to-tanstack-migration skill for per-pattern recipes. " +
+  "Run `deco-post-cleanup` and look for rule [9] htmx-residue to find " +
+  "every site call-site that still depends on this.";
+
+/**
+ * Stable placeholder URL returned by the legacy `useSection` /
+ * `usePartialSection` stubs. Hitting this URL surfaces a clear error.
+ * Exported so frameworks/tests can match against it.
+ */
+export const HTMX_LEGACY_URL = "/__deco_legacy_htmx_section__";
+
+function warnLegacyHtmx(name: string) {
+  if (typeof process !== "undefined" && process.env?.NODE_ENV === "production") {
+    return;
+  }
+  if (typeof (globalThis as any).__DECO_LEGACY_HTMX_WARNED === "undefined") {
+    (globalThis as any).__DECO_LEGACY_HTMX_WARNED = new Set<string>();
+  }
+  const set = (globalThis as any).__DECO_LEGACY_HTMX_WARNED as Set<string>;
+  if (set.has(name)) return;
+  set.add(name);
+  console.warn(`[${name}] ${DEPRECATION_MESSAGE}`);
+}
 
-export function usePartialSection(_props?: Record<string, unknown>): never {
-  throw new Error(DEPRECATION_MESSAGE);
+export function usePartialSection(_props?: Record<string, unknown>): string {
+  warnLegacyHtmx("usePartialSection");
+  return HTMX_LEGACY_URL;
 }
 
-export function useSection(_props?: Record<string, unknown>): never {
-  throw new Error(DEPRECATION_MESSAGE);
+export function useSection(_props?: Record<string, unknown>): string {
+  warnLegacyHtmx("useSection");
+  return HTMX_LEGACY_URL;
 }