@jini-ai/cms 0.5.2 → 0.5.4

package/dist/redirects/matcher.js

@@ -0,0 +1,144 @@
+const MIN_PATTERN_LENGTH = 1;
+const MAX_PATTERN_LENGTH = 2048;
+/** Precedence order, highest first — index doubles as the sort key. */
+const PRECEDENCE_ORDER = {
+    exact: 0,
+    prefix: 1,
+    wildcard: 2,
+    regex: 3, // never actually reachable — validatePattern always rejects it at write time.
+};
+/**
+ * Write-time pattern safety gate (REQ-07/19/20/22). Total — never throws.
+ *
+ * @complexity O(1).
+ */
+export function validatePattern(required, _optional = {}) {
+    const { matchType, fromPattern } = required;
+    if (matchType === "regex") {
+        return { ok: false, reason: "matchType 'regex' is not enabled in v1 (REQ-22)" };
+    }
+    const length = fromPattern.length;
+    if (length < MIN_PATTERN_LENGTH || length > MAX_PATTERN_LENGTH) {
+        return {
+            ok: false,
+            reason: `fromPattern must be ${MIN_PATTERN_LENGTH}-${MAX_PATTERN_LENGTH} characters (got ${length})`,
+        };
+    }
+    if (!fromPattern.startsWith("/")) {
+        return { ok: false, reason: "fromPattern must start with '/'" };
+    }
+    return { ok: true };
+}
+function matchExact(rule, path) {
+    if (rule.matchType !== "exact")
+        return null;
+    if (rule.fromPattern !== path)
+        return null;
+    return { rule, location: rule.toTarget, specificity: rule.fromPattern.length };
+}
+function matchPrefix(rule, path) {
+    if (rule.matchType !== "prefix")
+        return null;
+    const pattern = rule.fromPattern;
+    const isExactPrefix = path === pattern;
+    const isNestedPrefix = path.startsWith(pattern.endsWith("/") ? pattern : `${pattern}/`);
+    if (!isExactPrefix && !isNestedPrefix)
+        return null;
+    const tail = isExactPrefix ? "" : path.slice(pattern.length);
+    return { rule, location: `${rule.toTarget}${tail}`, specificity: pattern.length };
+}
+/** Compile a `*`-glob wildcard pattern into an anchored, non-backtracking capture regex. */
+function compileWildcard(pattern) {
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+    const withCaptures = escaped.replace(/\*/g, "([^/]+)");
+    return new RegExp(`^${withCaptures}$`);
+}
+function interpolate(template, captures) {
+    return template.replace(/\$(\d+)/g, (whole, indexStr) => {
+        const index = Number(indexStr) - 1;
+        return index >= 0 && index < captures.length ? captures[index] : whole;
+    });
+}
+function matchWildcard(rule, path) {
+    if (rule.matchType !== "wildcard")
+        return null;
+    const regex = compileWildcard(rule.fromPattern);
+    const result = regex.exec(path);
+    if (!result)
+        return null;
+    const captures = result.slice(1);
+    return {
+        rule,
+        location: interpolate(rule.toTarget, captures),
+        specificity: rule.fromPattern.length,
+    };
+}
+function matchOne(rule, path) {
+    switch (rule.matchType) {
+        case "exact":
+            return matchExact(rule, path);
+        case "prefix":
+            return matchPrefix(rule, path);
+        case "wildcard":
+            return matchWildcard(rule, path);
+        case "regex":
+            // Deferred (ADR-033 §8) — never authored in v1 (validatePattern rejects it at write
+            // time), so no live rule should ever carry this matchType. Defensive no-match.
+            return null;
+        default:
+            return null;
+    }
+}
+/**
+ * Tie-break comparator (behavior.spec.md §2.1/§6.1): higher `priority` wins;
+ * else more recent `updatedAt` (falling back to `createdAt`) wins; else the
+ * lexicographically smaller `id` wins. Returns <0 if `a` should win over `b`.
+ */
+function compareTieBreak(a, b) {
+    if (a.rule.priority !== b.rule.priority)
+        return b.rule.priority - a.rule.priority;
+    const aRecency = a.rule.updatedAt || a.rule.createdAt;
+    const bRecency = b.rule.updatedAt || b.rule.createdAt;
+    if (aRecency !== bRecency)
+        return aRecency > bRecency ? -1 : 1;
+    return a.rule.id < b.rule.id ? -1 : a.rule.id > b.rule.id ? 1 : 0;
+}
+/** Within a precedence band, longest/most-specific `fromPattern` wins first, then the tie-break chain. */
+function compareWithinBand(a, b) {
+    if (a.specificity !== b.specificity)
+        return b.specificity - a.specificity;
+    return compareTieBreak(a, b);
+}
+/**
+ * Resolve the highest-precedence, tie-broken match for `request.path` among
+ * `rules` (behavior.spec.md §1.1, §2.1, §2.2, §6.1). Total — never throws.
+ *
+ * @complexity O(n) in `rules.length`.
+ */
+export const match = (required, _optional = {}) => {
+    const { request, rules } = required;
+    const candidates = [];
+    for (const rule of rules) {
+        const candidate = matchOne(rule, request.path);
+        if (candidate)
+            candidates.push(candidate);
+    }
+    if (candidates.length === 0)
+        return { matched: false };
+    candidates.sort((a, b) => {
+        const precedenceDelta = PRECEDENCE_ORDER[a.rule.matchType] - PRECEDENCE_ORDER[b.rule.matchType];
+        if (precedenceDelta !== 0)
+            return precedenceDelta;
+        return compareWithinBand(a, b);
+    });
+    const winner = candidates[0];
+    return {
+        matched: true,
+        redirectId: winner.rule.id,
+        location: winner.location,
+        statusCode: winner.rule.statusCode,
+        matchType: winner.rule.matchType,
+    };
+};
+export const redirectMatcher = { match, validatePattern };
+//# sourceMappingURL=matcher.js.map

package/dist/redirects/order.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @file The rule orderings both `RedirectRepoPort` adapters apply (`repo.ts` on SQL, `repo.memory.ts`
+ * in memory). One module so the two adapters cannot drift: the shared contract suite
+ * (`repo.contract.test.ts`) only checks the cases it seeds, while every comparator arm is pinned
+ * here directly (`order.test.ts`).
+ */
+import type { RedirectRecord } from "./types.js";
+/**
+ * Shared tie-break between rules that match equally well: higher `priority` first, then the more
+ * recent `updatedAt` (falling back to `createdAt` when `updatedAt` is empty), then `id` ascending.
+ * Returns 0 only for the same id, as a sort comparator must.
+ */
+export declare function compareTieBreak({ a, b }: {
+    a: RedirectRecord;
+    b: RedirectRecord;
+}, _optional?: Record<string, never>): number;
+/** Longest pattern first, then the shared tie-break (`lookupLongestPrefix`, `listDynamic`). */
+export declare function compareLongestFirst({ a, b }: {
+    a: RedirectRecord;
+    b: RedirectRecord;
+}, _optional?: Record<string, never>): number;
+/**
+ * `findByFromPattern`'s order among active rules sharing one `fromPattern`: an `exact` rule before
+ * any other match type, then `id` ascending.
+ */
+export declare function compareSamePatternExactFirst({ a, b }: {
+    a: RedirectRecord;
+    b: RedirectRecord;
+}, _optional?: Record<string, never>): number;
+//# sourceMappingURL=order.d.ts.map

package/dist/redirects/order.js

@@ -0,0 +1,26 @@
+/**
+ * Shared tie-break between rules that match equally well: higher `priority` first, then the more
+ * recent `updatedAt` (falling back to `createdAt` when `updatedAt` is empty), then `id` ascending.
+ * Returns 0 only for the same id, as a sort comparator must.
+ */
+export function compareTieBreak({ a, b }, _optional = {}) {
+    if (a.priority !== b.priority)
+        return b.priority - a.priority;
+    const aRecency = a.updatedAt || a.createdAt;
+    const bRecency = b.updatedAt || b.createdAt;
+    if (aRecency !== bRecency)
+        return aRecency > bRecency ? -1 : 1;
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+/** Longest pattern first, then the shared tie-break (`lookupLongestPrefix`, `listDynamic`). */
+export function compareLongestFirst({ a, b }, _optional = {}) {
+    return b.fromPattern.length - a.fromPattern.length || compareTieBreak({ a, b }, {});
+}
+/**
+ * `findByFromPattern`'s order among active rules sharing one `fromPattern`: an `exact` rule before
+ * any other match type, then `id` ascending.
+ */
+export function compareSamePatternExactFirst({ a, b }, _optional = {}) {
+    return (a.matchType === "exact" ? 0 : 1) - (b.matchType === "exact" ? 0 : 1) || (a.id < b.id ? -1 : 1);
+}
+//# sourceMappingURL=order.js.map

package/dist/redirects/ports.d.ts

@@ -0,0 +1,242 @@
+/**
+ * @file Port + seam contracts for the `redirects` Tier-2 library (ADR-033).
+ *
+ * ADR-006 accounting (rule-of-two):
+ * - `RedirectRepoPort` is a genuine port — it rides the ADR-015 seam with two
+ *   adapters built now (in-memory for tests + Drizzle/SQLite for persistence),
+ *   matching every other feature in `src/features/*`.
+ * - `RedirectMatcher` and `RedirectHitSink` are declared here as ordinary
+ *   INTERNAL SEAMS, not ADR-006 ports. Neither has a second adapter under
+ *   construction today: the matcher's plausible-second is an edge/CDN compiler
+ *   (emit an nginx `map` / Cloudflare ruleset), the hit sink's is an external
+ *   analytics store — both real, neither built now. Per ADR-006 they stay
+ *   ordinary code with a documented seam, promoted to a port the day the second
+ *   adapter is real. They are typed as interfaces purely for testability.
+ *
+ * Architectural role:
+ * INTERFACES ONLY — no feature logic.
+ *
+ * Grounding: ADR-006 (rule-of-two), ADR-015 (repo behind a port), ADR-009
+ * (typed calls / outbox / hooks), ADR-022 (chokepoint writes record a revision
+ * in the same tx; bounded matching = the totality/bounded-cost trust primitive),
+ * ADR-021 (permission strings enforced by the calling gateway, not the repo).
+ */
+import type { ISODateTime, UUID } from "@jini-ai/core/primitives";
+import type { RedirectLocationRefusalReason } from "./target-gate.js";
+import type { DomainEvent } from "../core/index.js";
+import type { ListRedirectsFilter, RedirectHitStats, RedirectRecord, RedirectRequest, RedirectResolution, RedirectRevision } from "./types.js";
+/**
+ * Persistence port for redirect rules + their revision ledger + tombstones.
+ * The single write chokepoint (ADR-022 §4a): `save` MUST persist the record and
+ * its {@link RedirectRevision} in one transaction; no other module writes the
+ * `redirects` / `redirect_revisions` tables (CI import-graph canary, ADR-027
+ * precedent).
+ */
+export interface RedirectRepoPort {
+    findById(required: {
+        workspaceId: UUID;
+        id: UUID;
+    }, optional?: Record<string, never>): Promise<RedirectRecord | null>;
+    /** Index-backed O(1) exact-path lookup (active rules only). */
+    lookupExact(required: {
+        workspaceId: UUID;
+        path: string;
+        includeOverrideOnly: boolean;
+    }, optional?: Record<string, never>): Promise<RedirectRecord | null>;
+    /** Longest-prefix match over active `prefix` rules (index/trie-backed). */
+    lookupLongestPrefix(required: {
+        workspaceId: UUID;
+        path: string;
+        includeOverrideOnly: boolean;
+    }, optional?: Record<string, never>): Promise<RedirectRecord | null>;
+    /**
+     * The bounded "dynamic" set: active `wildcard` + `regex` rules in evaluation
+     * order (specificity → priority → recency). Returned capped; callers evaluate
+     * them through {@link RedirectMatcher} only after exact/prefix miss.
+     */
+    listDynamic(required: {
+        workspaceId: UUID;
+        includeOverrideOnly: boolean;
+        limit: number;
+    }, optional?: Record<string, never>): Promise<RedirectRecord[]>;
+    list(filter: ListRedirectsFilter, optional?: Record<string, never>): Promise<RedirectRecord[]>;
+    /**
+     * Resolve where an existing rule with the given `fromPattern` already points,
+     * used at write time for cycle detection + chain collapsing (ADR-033 §6).
+     */
+    findByFromPattern(required: {
+        workspaceId: UUID;
+        fromPattern: string;
+    }, optional?: Record<string, never>): Promise<RedirectRecord | null>;
+    /** Chokepoint write: upsert the record and append its revision in one tx. */
+    save(required: {
+        record: RedirectRecord;
+        revision: RedirectRevision;
+    }, optional?: Record<string, never>): Promise<void>;
+    /** Tombstone (soft-delete): flip status + append a tombstone revision in one tx. */
+    tombstone(required: {
+        workspaceId: UUID;
+        id: UUID;
+        revision: RedirectRevision;
+    }, optional?: Record<string, never>): Promise<void>;
+}
+/**
+ * INTERNAL SEAM (not an ADR-006 port). Pure, bounded matching of a request
+ * against the dynamic rule set. Implementations MUST be total and
+ * bounded-cost — linear-time / RE2 semantics, an anchored pattern, and a
+ * per-request evaluation cap — because this is the request-hot-path expression
+ * evaluator ADR-022's amendment designates a trust-boundary primitive. No
+ * backtracking regex engine may back this.
+ */
+export interface RedirectMatcher {
+    /**
+     * Return the first matching rule with captures interpolated into `location`,
+     * or `{ matched: false }`. `rules` is the already-ordered, already-capped
+     * dynamic set from {@link RedirectRepoPort.listDynamic}.
+     */
+    match(required: {
+        request: RedirectRequest;
+        rules: RedirectRecord[];
+    }, optional?: Record<string, never>): RedirectResolution;
+    /**
+     * Compile-time validation of a single pattern (called at the write
+     * chokepoint): rejects unbounded/backtracking constructs before a rule is
+     * ever stored, so an unsafe pattern cannot reach the hot path.
+     */
+    validatePattern(required: {
+        matchType: RedirectRecord["matchType"];
+        fromPattern: string;
+    }, optional?: Record<string, never>): {
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    };
+}
+/**
+ * INTERNAL SEAM (not an ADR-006 port). Best-effort, off-hot-path hit
+ * aggregation. The resolver emits a {@link RedirectHitEvent} via the outbox
+ * (ADR-009 async lane); an idempotent handler folds it into the
+ * `redirect_hits` sidecar through this sink. A dropped increment loses a
+ * statistic, never a redirect.
+ */
+export interface RedirectHitSink {
+    record(required: {
+        workspaceId: UUID;
+        redirectId: UUID;
+        at: ISODateTime;
+    }, optional?: Record<string, never>): Promise<void>;
+    getStats(required: {
+        workspaceId: UUID;
+        redirectId: UUID;
+    }, optional?: Record<string, never>): Promise<RedirectHitStats | null>;
+    listStats(required: {
+        workspaceId: UUID;
+    }, optional?: Record<string, never>): Promise<RedirectHitStats[]>;
+}
+/**
+ * Application service consulted by the routing resolution chain. It is invoked
+ * twice per request lifecycle: `pre_content` (override rules only) and
+ * `post_content` (the 404-fill pass). The exact registration contract with the
+ * (not-yet-designed) `routing` library is OWED by the future routing ADR —
+ * ADR-033 §4 specifies the redirects side and flags the seam as co-dependent.
+ */
+export interface RedirectResolver {
+    resolve(request: RedirectRequest, optional?: Record<string, never>): Promise<RedirectResolution>;
+}
+export interface RedirectMutatedEventPayload {
+    workspaceId: UUID;
+    redirectId: UUID;
+    change: "created" | "updated" | "tombstoned";
+}
+export type RedirectMutatedEvent = DomainEvent<RedirectMutatedEventPayload>;
+export interface RedirectHitEventPayload {
+    workspaceId: UUID;
+    redirectId: UUID;
+    at: ISODateTime;
+}
+export type RedirectHitEvent = DomainEvent<RedirectHitEventPayload>;
+/**
+ * Sync filter hook (ADR-009 lane 3): lets a plugin transform or short-circuit a
+ * resolution — e.g. an i18n plugin rewriting the target per locale, or an SEO
+ * plugin adding canonicalization. Declared-before-attached; ordered by explicit
+ * priority. Conditional (geo/device/auth) redirects are the named v1-deferred
+ * feature that lands ON this hook, not in core.
+ */
+export interface RedirectResolveHookContext {
+    request: RedirectRequest;
+    /** The resolution core computed; the hook returns it unchanged or replaces it. */
+    resolution: RedirectResolution;
+}
+export type RedirectResolveHook = (ctx: RedirectResolveHookContext) => RedirectResolution | Promise<RedirectResolution>;
+export interface RouteResolveContext {
+    readonly workspaceId: UUID;
+    readonly siteId?: string;
+    readonly locale?: string;
+    readonly originKey?: string;
+    /**
+     * TODO(ADR-040): compose canonicalUrl from OriginRegistryPort.canonicalOrigin(ctx)
+     * once src/origin exists. Until then, a caller that knows the verified origin
+     * may pass it here; absent, canonicalUrl falls back to the relative path.
+     */
+    readonly originOverride?: string;
+}
+/** Terminal decision a phase resolver may return; anything else falls through. */
+export type RouteResolvePhaseOutcome = {
+    readonly kind: "redirect";
+    readonly location: string;
+    readonly statusCode: number;
+} | {
+    readonly kind: "resolved";
+    readonly path: string;
+} | {
+    readonly kind: "not_found";
+};
+/** Payload handed to the bound {@link SlugChangeCapture} inside the rename transaction. */
+export interface SlugChangeCaptureInput {
+    readonly workspaceId: UUID;
+    readonly entryId: UUID;
+    readonly oldPath: string;
+    readonly newPath: string;
+    readonly actor: UUID;
+    readonly changeSetId?: UUID;
+}
+/**
+ * The single named slot content's write chokepoint calls inside the rename
+ * transaction (ADR-039 §4). Declared here by routing (content knows nothing of
+ * redirects); implemented by the redirects library; wired by the composition
+ * root. **No slot implementation may be plugin-supplied** (Round-2 amendment 1
+ * — the slot is core-resident by definition).
+ *
+ * Constraints on any bound implementation (Round-2 amendment 2): idempotent by
+ * `changeSetId`, no external I/O, no in-tx publish (an outbox row may be
+ * written in-tx per the transactional-outbox pattern, but dispatch happens
+ * post-commit), and a strict lock order of content row before redirect rows.
+ *
+ * Fail-closed nuance (Round-2 amendment 3, not enforced by this library):
+ * absent binding is a no-op only before Redirects is installed, or while
+ * slug-preservation is disabled for the workspace. Once link-preservation is
+ * enabled, a slug-changing rename with no bound capture MUST fail
+ * `LINK_PRESERVATION_UNAVAILABLE` rather than silently skip the redirect. That
+ * enforcement belongs to the content write chokepoint (which knows whether
+ * preservation is enabled) and to Redirects (which doesn't exist yet in this
+ * repo) — this library only exposes the registration slot.
+ */
+export interface SlugChangeCapture {
+    onSlugChange(input: SlugChangeCaptureInput, optional?: Record<string, never>): Promise<void>;
+}
+/** Refusal evidence never exposes a redirect that bypassed the INV-03 gate. */
+export interface RedirectRefusal {
+    redirectId: UUID;
+    location: string;
+    reason: RedirectLocationRefusalReason;
+}
+export interface RedirectResolutionReport {
+    resolution: RedirectResolution;
+    refused: RedirectRefusal[];
+}
+/** The legacy resolver plus refusal evidence for adapters that must report declines. */
+export interface RedirectResolverWithRefusals extends RedirectResolver {
+    resolveWithRefusals(request: RedirectRequest, optional?: Record<string, never>): Promise<RedirectResolutionReport>;
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/redirects/ports.internal.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @file Package-private shared insert helper for the `redirects` write path
+ * (ADR-PIPE-009 Decision A).
+ *
+ * Purpose:
+ * `insertRedirectAndRevision` is the sole path INV-01 depends on: exactly one
+ * `redirects` row write + one `redirect_revisions` row write, in call order,
+ * against whatever `RedirectDbHandle` the caller passes in. It performs NO
+ * transaction control of its own (no `BEGIN`/`COMMIT`) — atomicity is the
+ * CALLER's responsibility: `redirects.ts`'s chokepoint wraps a call to this
+ * function in its own `BEGIN IMMEDIATE`/`COMMIT`; `capture.ts` calls it
+ * directly, relying on the (future) content chokepoint's already-open ambient
+ * transaction on the same single-connection `better-sqlite3` handle
+ * (ADR-PIPE-009 Decision A, EC-05).
+ *
+ * Import-graph note: the domain-logic callers of this function are
+ * `redirects.ts` and `capture.ts` only (ADR-PIPE-009/tasks.md T012) — no route
+ * handler or UI code may import it. `repo.memory.ts`/`repo.sqlite.ts` import
+ * only the `RedirectDbHandle` TYPE (not this function) to declare the shape
+ * their own storage satisfies; they do not call `insertRedirectAndRevision`
+ * themselves (each adapter's own `save`/`tombstone` port methods write via
+ * their own direct storage calls, independently testable by the
+ * `RedirectRepoPort` contract suite, T007). This keeps the chokepoint
+ * boundary (INV-07) at {`redirects.ts`, `capture.ts`, `ports.internal.ts`},
+ * matching the Enforcement section's review-time check.
+ *
+ * Architectural role:
+ * Package-private. NOT exported from `index.ts` (ADR-PIPE-009 Migration
+ * Safety / File Map).
+ */
+import type { RedirectRecord, RedirectRevision } from "./types.js";
+/**
+ * The minimal storage seam `insertRedirectAndRevision` writes through.
+ * Deliberately narrower than `RedirectRepoPort` (no reads, no transaction
+ * control) — both `repo.memory.ts` and `repo.sqlite.ts` (or a small internal
+ * handle each of them owns) satisfy this shape so `redirects.ts`/`capture.ts`
+ * can share one write path regardless of which adapter is active.
+ */
+export interface RedirectDbHandle {
+    insertRedirect(record: RedirectRecord, optional?: Record<string, never>): void | Promise<void>;
+    insertRevision(revision: RedirectRevision, optional?: Record<string, never>): void | Promise<void>;
+}
+export interface InsertRedirectAndRevisionRequired {
+    db: RedirectDbHandle;
+    record: RedirectRecord;
+    revision: RedirectRevision;
+}
+/**
+ * Insert a `redirects` row and its paired `redirect_revisions` row, in that
+ * order, against `db`. Never opens or closes a transaction; any error from
+ * `db` propagates uncaught so the caller's own transaction (or lack thereof)
+ * decides the outcome.
+ *
+ * @complexity O(1) — two writes, no I/O beyond what `db` itself performs.
+ */
+export declare function insertRedirectAndRevision(required: InsertRedirectAndRevisionRequired, _optional?: Record<string, never>): Promise<void>;
+//# sourceMappingURL=ports.internal.d.ts.map

package/dist/redirects/ports.internal.js

@@ -0,0 +1,14 @@
+/**
+ * Insert a `redirects` row and its paired `redirect_revisions` row, in that
+ * order, against `db`. Never opens or closes a transaction; any error from
+ * `db` propagates uncaught so the caller's own transaction (or lack thereof)
+ * decides the outcome.
+ *
+ * @complexity O(1) — two writes, no I/O beyond what `db` itself performs.
+ */
+export async function insertRedirectAndRevision(required, _optional = {}) {
+    const { db, record, revision } = required;
+    await db.insertRedirect(record);
+    await db.insertRevision(revision);
+}
+//# sourceMappingURL=ports.internal.js.map

package/dist/redirects/ports.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ports.js.map