@clossys/butler 0.1.1

package/dist/web/internal/peer-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-version.d.ts","sourceRoot":"","sources":["../../../src/web/internal/peer-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AA6FH,MAAM,WAAW,sBAAsB;IACrC,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,aAAa,EAAE,MAAM,CAAC;IACtB,4FAA4F;IAC5F,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,IAAI,CAcrE"}

package/dist/web/internal/peer-version.js

@@ -0,0 +1,136 @@
+/**
+ * `assertPeerVersion` — the runtime half of `./web`'s "optional peer, no
+ * install-time signal in either direction" problem. `react`/`react-dom` are
+ * declared `peerDependenciesMeta: { optional: true }` (see package.json) so
+ * a consumer can install `@clossys/butler` (the root, provider-
+ * neutral core) without ever installing React — only `./web` needs it. But
+ * an ABSENT or OUT-OF-RANGE `react` produces no signal of any kind without
+ * this guard: a consumer on an incompatible React version would otherwise
+ * learn about it from whatever `./web` happened to crash on deep inside
+ * React itself, with nothing naming a version range as the cause. See
+ * `web/index.ts`'s own guard call, evaluated once at import time via
+ * `react`'s own exported `version`, for where this is wired in.
+ *
+ * This is the same obligation this repository's own contribution guide
+ * states for every requirement this workspace takes on: requiring a
+ * prerequisite is legitimate; failing silently when it is unmet is not,
+ * because that turns a setup error into a debugging session inside
+ * somebody else's codebase.
+ *
+ * PORTED, NOT SHARED, from `packages/consent/src/web/internal/peer-version.ts`
+ * — identical algorithm, copied rather than imported across a package
+ * boundary for the structural reason that file's own header gives: that
+ * package does not expose this as part of its public API surface, and even
+ * if it did, `@clossys/butler` would gain nothing by taking a real
+ * runtime dependency on a sibling just to reach one shared utility, and its
+ * "zero runtime dependencies" claim would then be wrong. Keep the copies in
+ * sync by hand if the ported range algorithm ever changes.
+ *
+ * DELIBERATELY PURE — NO `node:*` IMPORTS IN THIS FILE. `./web`'s entry
+ * point is reachable from a browser bundle (a client component rendering
+ * a preference surface), not just a Node process, so the version check reads
+ * `react`'s own exported `version` directly rather than any Node-only
+ * fs-based resolver.
+ */
+/** Strict x.y.z only — same as scripts/check-workspace-links.mjs's parseVersion(). */
+function parseVersion(version) {
+    const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(String(version).trim());
+    if (!m)
+        return null;
+    return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) };
+}
+function compareVersions(a, b) {
+    return a.major - b.major || a.minor - b.minor || a.patch - b.patch;
+}
+/**
+ * An exact pin, a caret range, or a tilde range against a plain x.y.z. For
+ * `0.y.z`, BOTH `^` and `~` are minor-locked; above `0.y.z`, `^` is
+ * major-locked and only `~` is minor-locked. Returns `null` —
+ * unparseable — for anything else, including the `>=`/`<` forms
+ * `parseGteForm` below understands instead.
+ */
+function parsePinCaretTilde(range) {
+    const m = /^(\^|~)?(\d+)\.(\d+)\.(\d+)$/.exec(String(range).trim());
+    if (!m)
+        return null;
+    const prefix = m[1] ?? "";
+    const major = Number(m[2]);
+    const minor = Number(m[3]);
+    const patch = Number(m[4]);
+    if (prefix === "")
+        return { lower: { major, minor, patch }, upper: { major, minor, patch: patch + 1 } };
+    if (major === 0)
+        return { lower: { major, minor, patch }, upper: { major, minor: minor + 1, patch: 0 } };
+    if (prefix === "^")
+        return { lower: { major, minor, patch }, upper: { major: major + 1, minor: 0, patch: 0 } };
+    return { lower: { major, minor, patch }, upper: { major, minor: minor + 1, patch: 0 } }; // "~"
+}
+/**
+ * A bounded `>=x[.y[.z]] <a[.b[.c]]>` range or an unbounded `>=x[.y[.z]]`
+ * range — the shape this package's own `peerDependencies` uses for React
+ * (`">=18"`). A version segment omitted from either side defaults to its
+ * lowest value (`18` reads as `18.0.0`), matching ordinary semver range
+ * convention. Returns `null` — unparseable — for anything else.
+ */
+function parseGteForm(range) {
+    const trimmed = String(range).trim();
+    const segment = "(\\d+)(?:\\.(\\d+))?(?:\\.(\\d+))?";
+    const bounded = new RegExp(`^>=\\s*${segment}\\s+<\\s*${segment}$`).exec(trimmed);
+    if (bounded) {
+        const [, lMaj, lMin, lPat, uMaj, uMin, uPat] = bounded;
+        return {
+            lower: { major: Number(lMaj), minor: Number(lMin ?? "0"), patch: Number(lPat ?? "0") },
+            upper: { major: Number(uMaj), minor: Number(uMin ?? "0"), patch: Number(uPat ?? "0") },
+        };
+    }
+    const unbounded = new RegExp(`^>=\\s*${segment}$`).exec(trimmed);
+    if (unbounded) {
+        const [, maj, min, pat] = unbounded;
+        return { lower: { major: Number(maj), minor: Number(min ?? "0"), patch: Number(pat ?? "0") }, upper: null };
+    }
+    return null;
+}
+/**
+ * Returns `{ evaluated: false, reason }` when either side could not be
+ * parsed — a finding, never assumed satisfied — or `{ evaluated: true, ok
+ * }` once both sides parsed cleanly.
+ */
+function satisfiesRange(versionStr, rangeStr) {
+    const bound = parsePinCaretTilde(rangeStr) ?? parseGteForm(rangeStr);
+    if (!bound) {
+        return {
+            evaluated: false,
+            reason: `"${rangeStr}" is not a range form this guard parses (an exact pin, ^x.y.z, ~x.y.z, ">=x.y.z <a.b.c>", or ">=x.y.z" are supported)`,
+        };
+    }
+    const version = parseVersion(versionStr);
+    if (!version) {
+        return { evaluated: false, reason: `the installed version "${versionStr}" is not a plain x.y.z semver this guard can compare` };
+    }
+    const geLower = compareVersions(version, bound.lower) >= 0;
+    const ltUpper = bound.upper === null ? true : compareVersions(version, bound.upper) < 0;
+    return { evaluated: true, ok: geLower && ltUpper };
+}
+/**
+ * Throws a named, actionable error naming the package, the declared range,
+ * and the version actually found. Never returns a boolean — a guard must
+ * state where control goes when it declines. A missing peer and an
+ * out-of-range peer throw genuinely DIFFERENT messages — "not installed"
+ * and "installed but incompatible" are different problems with different
+ * fixes. An unparseable declared range or installed version is a third,
+ * equally loud error, never an assumed pass.
+ */
+export function assertPeerVersion(input) {
+    const { peer, declaredRange, foundVersion } = input;
+    if (foundVersion === undefined) {
+        throw new Error(`${peer} is required for this import but is not installed. Install ${peer}@"${declaredRange}" — see this package's README for its optional-peer setup.`);
+    }
+    const outcome = satisfiesRange(foundVersion, declaredRange);
+    if (!outcome.evaluated) {
+        throw new Error(`Could not verify ${peer}@${foundVersion} against this package's declared range "${declaredRange}": ${outcome.reason}. Refusing to assume this is compatible.`);
+    }
+    if (!outcome.ok) {
+        throw new Error(`${peer}@${foundVersion} is installed, but this package requires ${peer}@"${declaredRange}". Installed but incompatible — install a version of ${peer} that satisfies "${declaredRange}".`);
+    }
+}
+//# sourceMappingURL=peer-version.js.map

package/dist/web/internal/peer-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-version.js","sourceRoot":"","sources":["../../../src/web/internal/peer-version.ts"],"names":[],"mappings":"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"}

package/dist/web/useStandingWants.d.ts

@@ -0,0 +1,75 @@
+import type { CurrencyWindow, PolicyVersion, StandingAction, StandingEvaluation, StandingEvaluationPolicy, StandingInstruction, StandingTopic } from "../schema.js";
+/**
+ * The client-side counterpart to `StandingInstructionStore`.
+ *
+ * `StandingInstructionStore` is `Promise`-based host-implemented I/O, most
+ * naturally implemented behind a server boundary — a database read, a
+ * server-side session — that a browser cannot call directly as a plain
+ * async function. A hook that genuinely reads and writes standing
+ * instructions needs a client-shaped port instead: something a browser
+ * really can call, typically a `fetch` to a host-owned route that itself
+ * runs `decideStandingChange` and writes both the instruction and the
+ * audit event server-side. This is that port — still host-implemented,
+ * still carrying no opinion about transport, but shaped for the side of
+ * the boundary that actually runs in a browser.
+ */
+export interface StandingWantsClient {
+    /** Reads every stored instruction for `subjectId`, however the host's own API/storage boundary is reached. */
+    read(subjectId: string): Promise<readonly StandingInstruction[]>;
+    /**
+     * Applies one decided action and returns the durably-stored instruction.
+     * The host is expected to run `decideStandingChange` (or equivalent) on
+     * its own server and write both the instruction and the audit event
+     * before resolving — this hook never computes or stores anything itself.
+     */
+    apply(subjectId: string, action: StandingAction): Promise<StandingInstruction>;
+}
+export interface UseStandingWantsOptions {
+    subjectId: string;
+    /** The topics this preference surface manages. Determines the keys of `evaluations`. */
+    topics: readonly StandingTopic[];
+    policyVersion: PolicyVersion;
+    /** The window written onto any instruction this surface decides. No default — see `CurrencyWindow`. */
+    currency: CurrencyWindow;
+    /** No default — see `StandingEvaluationPolicy`; the host must decide this explicitly. */
+    evaluationPolicy: StandingEvaluationPolicy;
+    /** The moment to evaluate currency against, as an ISO timestamp. Supplied by the caller so a surface renders the same answer on the server and on the client rather than drifting with an ambient clock. */
+    now: string;
+    client: StandingWantsClient;
+}
+export interface UseStandingWantsResult {
+    /** One evaluation per requested topic. A topic with no stored instruction evaluates to `absent`, never to a falsy value that could read as a denial or as permission. */
+    evaluations: Readonly<Record<StandingTopic, StandingEvaluation>>;
+    /** `true` while the initial `client.read` call is in flight. */
+    loading: boolean;
+    /** The error thrown by the most recent `client.read`/`client.apply` call, if any. Never thrown by this hook itself. */
+    error: unknown;
+    grant(topic: StandingTopic): Promise<void>;
+    deny(topic: StandingTopic): Promise<void>;
+    /**
+     * Withdraw is reachable through the SAME call shape as grant and deny —
+     * one topic, one promise, one function on the same object. That is
+     * withdrawal parity enforced structurally at the API surface, not
+     * asserted in prose: there is no separate, harder-to-reach function and
+     * no extra argument for revoking a want than for giving one. The
+     * `withdrawal-parity` gate measures the same property one layer out, in
+     * a consumer's real interface, where this hook cannot see.
+     */
+    withdraw(topic: StandingTopic): Promise<void>;
+}
+/**
+ * Manages a preference surface's standing wants: reads every stored
+ * instruction for `subjectId` once on mount, evaluates each of `topics`
+ * against `policyVersion` AND the supplied `now`, and exposes
+ * `grant`/`deny`/`withdraw` as identically-shaped async functions backed by
+ * the same `client.apply` call.
+ *
+ * The evaluation is currency-aware, which is the whole difference between
+ * this and a hook that reads a row: an instruction that exists, and was
+ * granted, and is a year past its own declared window comes back `stale`,
+ * not `granted`. Rendering a surface off `evaluations` therefore re-asks
+ * on its own rather than quietly continuing to act on an answer nobody has
+ * checked since it was written.
+ */
+export declare function useStandingWants(options: UseStandingWantsOptions): UseStandingWantsResult;
+//# sourceMappingURL=useStandingWants.d.ts.map

package/dist/web/useStandingWants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStandingWants.d.ts","sourceRoot":"","sources":["../../src/web/useStandingWants.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,wBAAwB,EACxB,mBAAmB,EACnB,aAAa,EACd,MAAM,cAAc,CAAC;AAEtB;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,mBAAmB;IAClC,8GAA8G;IAC9G,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC,CAAC;IACjE;;;;;OAKG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAChF;AAED,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,wFAAwF;IACxF,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;IACjC,aAAa,EAAE,aAAa,CAAC;IAC7B,uGAAuG;IACvG,QAAQ,EAAE,cAAc,CAAC;IACzB,yFAAyF;IACzF,gBAAgB,EAAE,wBAAwB,CAAC;IAC3C,4MAA4M;IAC5M,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,mBAAmB,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACrC,yKAAyK;IACzK,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,aAAa,EAAE,kBAAkB,CAAC,CAAC,CAAC;IACjE,gEAAgE;IAChE,OAAO,EAAE,OAAO,CAAC;IACjB,uHAAuH;IACvH,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,IAAI,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,sBAAsB,CAmDzF"}

package/dist/web/useStandingWants.js

@@ -0,0 +1,66 @@
+import { useCallback, useEffect, useState } from "react";
+import { evaluateStandingInstruction } from "../contract.js";
+/**
+ * Manages a preference surface's standing wants: reads every stored
+ * instruction for `subjectId` once on mount, evaluates each of `topics`
+ * against `policyVersion` AND the supplied `now`, and exposes
+ * `grant`/`deny`/`withdraw` as identically-shaped async functions backed by
+ * the same `client.apply` call.
+ *
+ * The evaluation is currency-aware, which is the whole difference between
+ * this and a hook that reads a row: an instruction that exists, and was
+ * granted, and is a year past its own declared window comes back `stale`,
+ * not `granted`. Rendering a surface off `evaluations` therefore re-asks
+ * on its own rather than quietly continuing to act on an answer nobody has
+ * checked since it was written.
+ */
+export function useStandingWants(options) {
+    const { subjectId, topics, policyVersion, currency, evaluationPolicy, now, client } = options;
+    const [instructions, setInstructions] = useState({});
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(undefined);
+    useEffect(() => {
+        let cancelled = false;
+        setLoading(true);
+        setError(undefined);
+        client
+            .read(subjectId)
+            .then((all) => {
+            if (cancelled)
+                return;
+            const byTopic = {};
+            for (const instruction of all)
+                byTopic[instruction.topic] = instruction;
+            setInstructions(byTopic);
+        })
+            .catch((caught) => {
+            if (!cancelled)
+                setError(caught);
+        })
+            .finally(() => {
+            if (!cancelled)
+                setLoading(false);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [client, subjectId]);
+    const applyAction = useCallback(async (action) => {
+        try {
+            const instruction = await client.apply(subjectId, action);
+            setInstructions((previous) => ({ ...previous, [instruction.topic]: instruction }));
+        }
+        catch (caught) {
+            setError(caught);
+        }
+    }, [client, subjectId]);
+    const grant = useCallback((topic) => applyAction({ kind: "grant", topic, policyVersion, currency }), [applyAction, policyVersion, currency]);
+    const deny = useCallback((topic) => applyAction({ kind: "deny", topic, policyVersion, currency }), [applyAction, policyVersion, currency]);
+    const withdraw = useCallback((topic) => applyAction({ kind: "withdraw", topic, policyVersion, currency }), [applyAction, policyVersion, currency]);
+    const evaluations = {};
+    for (const topic of topics) {
+        evaluations[topic] = evaluateStandingInstruction(instructions[topic], policyVersion, evaluationPolicy, now);
+    }
+    return { evaluations, loading, error, grant, deny, withdraw };
+}
+//# sourceMappingURL=useStandingWants.js.map

package/dist/web/useStandingWants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStandingWants.js","sourceRoot":"","sources":["../../src/web/useStandingWants.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@clossys/butler",
+  "version": "0.1.1",
+  "private": false,
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./inbound": {
+      "types": "./dist/inbound/index.d.ts",
+      "import": "./dist/inbound/index.js"
+    },
+    "./web": {
+      "types": "./dist/web/index.d.ts",
+      "import": "./dist/web/index.js"
+    }
+  },
+  "bin": {
+    "butler-check": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "description": "The butler role: do we have what this person wants — this request in their own confirmation, and their standing instructions, still current? Dependency-free machinery for a consumer's own want records: a three-state standing model (absent/denied/granted) plus a stale evaluation status, structured intents carrying a confidence read against a declared floor, host-supplied storage and audit ports, an isolated ./inbound admission subpath, an optional ./web subpath whose React peer is asserted at import time, and three gates behind one butler-check bin — confirmation-completeness, which fails when an acted-on intent has no confirmation record, when it was acted on against a misread or unclear read-back, or when an intent below the declared confidence floor was acted on with no explicit hand-off; currency, which fails when a standing instruction is relied on past its declared window, after a policy version superseded it, or when nothing was on record to rely on at all; and withdrawal-parity, which fails when withdrawing takes more steps than granting or demands a contact or an account the matching grant path never required. Ships the schema and the checkers; every consumer authors its own values.",
+  "keywords": [
+    "butler",
+    "consent",
+    "intent",
+    "confirmation",
+    "currency",
+    "preferences",
+    "gate",
+    "typescript"
+  ],
+  "author": "Calvin Hung",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clossys/foundry.git",
+    "directory": "packages/butler"
+  },
+  "bugs": {
+    "url": "https://github.com/clossys/foundry/issues"
+  },
+  "homepage": "https://github.com/clossys/foundry/tree/main/packages/butler#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "node ../../scripts/check-name-collision.mjs . && npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "jsdom": "^26.1.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "typescript": "~6.0.0",
+    "vitest": "^4.1.9"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}

package/src/audit-shape.check.ts

@@ -0,0 +1,37 @@
+/**
+ * Compile-time proof that `StandingAuditEvent` (`./schema.ts`) carries no
+ * raw personal-data field — no email, name, phone, address, or IP — only
+ * the opaque `subjectId` and the separately-opaque `actorId`.
+ *
+ * Named `*.check.ts`, not `*.test.ts`, so it is part of the REAL `tsc` run
+ * (`npm run typecheck`) rather than only being transpiled, never
+ * type-checked, by vitest — see this repository's own contribution
+ * guide, "Type-level assertions live in `.check.ts(x)` files" entry, and
+ * `scripts/check-typechecked-assertions.mjs` for the gate that enforces it.
+ * Nothing here is ever imported by `index.ts` or any runtime code; its only
+ * job is to fail `tsc` if the contract regresses.
+ *
+ * `ExactKeys` fails to compile unless `Keys` is EXACTLY the allowed set —
+ * neither a subset (a required field silently dropped) nor a superset (a
+ * new field silently added, personal-data-shaped or not, without a human
+ * deciding it belongs here).
+ *
+ * `subjectId` and `actorId` are both in the allowed set, deliberately and
+ * separately. Merging them into one id would still pass a personal-data
+ * scan and would still be wrong: the whole point of this package is
+ * telling "the person asked for this" apart from "something acted on its
+ * own reading", and a single conflated identifier makes that distinction
+ * unrecoverable after the fact.
+ */
+import type { StandingAuditEvent } from "./schema.js";
+
+type ExactKeys<Keys extends string, Allowed extends string> = [Allowed] extends [Keys] ? ([Keys] extends [Allowed] ? true : never) : never;
+
+const ALLOWED_KEYS = ["subjectId", "actorId", "topic", "type", "policyVersion", "occurredAt", "previousPolicyVersion"] as const;
+type AllowedKey = (typeof ALLOWED_KEYS)[number];
+
+// If `StandingAuditEvent` ever gains or loses a key relative to
+// `ALLOWED_KEYS` above, this assignment stops compiling — including if
+// someone adds an `email`, `name`, `ip`, `phone`, or `address`-shaped
+// field, and including if `actorId` is ever folded into `subjectId`.
+export const auditEventKeysAreExactlyTheAllowedSet: ExactKeys<keyof StandingAuditEvent, AllowedKey> = true;