@happyvertical/smrt-svelte 0.30.0

package/dist/components/workspace/server/compose-availability.js

@@ -0,0 +1,114 @@
+/**
+ * Server-side dock availability gate composer.
+ *
+ * Consumer's `fetchAvailability` endpoint calls `composeDockAvailability`
+ * with the registered tools, a caller-supplied context, and a map of
+ * gate evaluators (typically wrapping `PermissionResolver` from
+ * smrt-users and `FeatureResolver` from smrt-features). It returns the
+ * filtered `AvailableTool[]` the dock's client-side `fetchAvailability`
+ * resolves to.
+ *
+ * Server-side by design: no Svelte / DOM imports, no client-only state.
+ * See happyvertical/smrt#1226 (Phase 4c) and #1235 for the registry
+ * audit that motivated this server-first pattern.
+ */
+/**
+ * Compose the `availableTools` list for a tools dock by evaluating each
+ * tool's `gates` against the provided evaluators. Tools where ALL gates
+ * resolve to `true` are included (AND semantics).
+ *
+ * Tools without `gates` (or with an empty `gates` array) are
+ * unconditionally included — gating is opt-in, existing tool definitions
+ * keep working.
+ *
+ * Throws if a gate's prefix doesn't match any registered evaluator —
+ * misconfiguration should fail loudly, not silently leak tools to users
+ * who shouldn't see them.
+ *
+ * Gate evaluation is parallel within a tool and across tools (`Promise.all`
+ * fan-out), so a slow evaluator on one gate doesn't block unrelated tools.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   composeDockAvailability,
+ *   type GateEvaluationContext,
+ * } from '@happyvertical/smrt-svelte/workspace/server';
+ * import { PermissionResolver } from '@happyvertical/smrt-users';
+ * import { FeatureResolver } from '@happyvertical/smrt-features';
+ *
+ * // Caller narrows the context shape so evaluators get typed access
+ * // without casts:
+ * interface MyContext extends GateEvaluationContext {
+ *   userId: string;
+ *   tenantId: string;
+ * }
+ *
+ * const available = await composeDockAvailability<MyContext>({
+ *   tools: [
+ *     { id: 'governance', label: 'Claim Audit', gates: ['permission:content.governance.view'] },
+ *     { id: 'video-gen',  label: 'Video',       gates: ['feature:video-tools'] },
+ *     { id: 'chat',       label: 'Chat' }, // no gates → always visible
+ *   ],
+ *   context: { userId: 'user-1', tenantId: 'tenant-1' },
+ *   evaluators: {
+ *     permission: async (gateId, ctx) => {
+ *       const [, slug] = gateId.split(':', 2);
+ *       return permissionResolver.hasPermission(ctx.userId, ctx.tenantId, slug);
+ *     },
+ *     feature: async (gateId, ctx) => {
+ *       const [, key] = gateId.split(':', 2);
+ *       return featureResolver.isEnabled(key, { tenantId: ctx.tenantId });
+ *     },
+ *   },
+ * });
+ * // → AvailableTool[] filtered by gates
+ * ```
+ */
+export async function composeDockAvailability(options) {
+    const { tools, context, evaluators } = options;
+    const evaluations = await Promise.all(tools.map(async (tool) => {
+        if (!tool.gates || tool.gates.length === 0) {
+            return tool; // no gates → visible
+        }
+        const gateResults = await Promise.all(tool.gates.map(async (gateId) => {
+            const prefix = gateId.split(':', 1)[0];
+            // Use Object.hasOwn() + a function-type guard so a gate like
+            // `constructor:foo` or `toString:foo` doesn't resolve to an
+            // inherited `Object.prototype` property and silently pass — the
+            // contract is fail-loud on unknown prefix. The function-type
+            // check is belt-and-suspenders: a consumer that accidentally
+            // wires a non-function evaluator should also throw here.
+            const evaluator = Object.hasOwn(evaluators, prefix)
+                ? evaluators[prefix]
+                : undefined;
+            if (typeof evaluator !== 'function') {
+                const availablePrefixes = Object.keys(evaluators).join(', ') || '(none)';
+                throw new Error(`[composeDockAvailability] No evaluator registered for gate prefix "${prefix}" ` +
+                    `(tool "${tool.id}", gate "${gateId}"). Available prefixes: ${availablePrefixes}.`);
+            }
+            return evaluator(gateId, context);
+        }));
+        // Strict equality: only literal `true` passes a gate. Any non-boolean
+        // return value (string, object, undefined, etc.) fails-closed —
+        // defensive against untyped evaluators that return wrapped objects or
+        // sentinel strings instead of plain booleans. `Boolean(...)` would
+        // pass `'false'`, `{}`, `[]`, and any truthy garbage, fail-OPEN.
+        return gateResults.every((result) => result === true) ? tool : null;
+    }));
+    return evaluations
+        .filter((t) => t !== null)
+        .map((tool) => {
+        // Preserve absence: omitting `label` / `badge` here lets
+        // `defineToolsDock.applyAvailability` fall back to the registered
+        // `ToolDef` metadata. Materializing `label: ''` would blank the rail
+        // button, and `badge: null` would explicitly clear any registered
+        // default badge.
+        const out = { id: tool.id };
+        if (tool.label !== undefined)
+            out.label = tool.label;
+        if (tool.badge !== undefined)
+            out.badge = tool.badge;
+        return out;
+    });
+}

package/dist/components/workspace/server/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @happyvertical/smrt-svelte/workspace/server
+ *
+ * Server-only utilities for the workspace shell — currently the dock
+ * availability gate composer (Phase 4c per happyvertical/smrt#1226).
+ *
+ * Node-safe: no Svelte component imports, no browser-only APIs. Import
+ * this subpath from `+server.ts` endpoints, REST handlers, or anywhere
+ * else outside the client bundle.
+ */
+export { composeDockAvailability } from './compose-availability.js';
+export type { AvailableTool, ComposeDockAvailabilityOptions, GatedToolSummary, GateEvaluationContext, GateEvaluator, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/workspace/server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/components/workspace/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,YAAY,EACV,aAAa,EACb,8BAA8B,EAC9B,gBAAgB,EAChB,qBAAqB,EACrB,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/components/workspace/server/index.js

@@ -0,0 +1,11 @@
+/**
+ * @happyvertical/smrt-svelte/workspace/server
+ *
+ * Server-only utilities for the workspace shell — currently the dock
+ * availability gate composer (Phase 4c per happyvertical/smrt#1226).
+ *
+ * Node-safe: no Svelte component imports, no browser-only APIs. Import
+ * this subpath from `+server.ts` endpoints, REST handlers, or anywhere
+ * else outside the client bundle.
+ */
+export { composeDockAvailability } from './compose-availability.js';

package/dist/components/workspace/server/types.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Types for the server-side dock availability gate composer.
+ *
+ * See `compose-availability.ts` for the runtime utility and
+ * happyvertical/smrt#1226 (Phase 4c) / #1235 for design context.
+ *
+ * This module is intentionally Node-safe — no Svelte component imports,
+ * no `window`/`document`, no browser-only APIs — so consumers can call it
+ * from server endpoints (`+server.ts`, REST handlers, etc.).
+ */
+import type { AvailableTool } from '../types.js';
+/**
+ * Context passed to each gate evaluator. Consumer-defined keys (userId,
+ * tenantId, contentId, etc.) carry the data evaluators need to resolve
+ * a gate to a boolean. The composer doesn't introspect this — it's a
+ * pass-through.
+ */
+export type GateEvaluationContext = Record<string, unknown>;
+/**
+ * Resolves a gate ID to a boolean (visible / not visible). May be async
+ * (DB query, network call, permission resolver). Sync evaluators that
+ * return a plain boolean are also fine.
+ *
+ * Generic over the caller's context shape so evaluators get typed access
+ * to context fields without casting. Defaults to the permissive
+ * `GateEvaluationContext` so existing call sites keep compiling.
+ *
+ * The constraint is a self-mapped `{ [K in keyof TCtx]: unknown }` rather
+ * than `Record<string, unknown>`. This accepts interface-style consumer
+ * contexts without an explicit string index signature — the same trap
+ * Copilot flagged on `TActions` in #1239. A bare `Record<string, unknown>`
+ * constraint rejects interfaces (which have no index signature) under
+ * strict TS, forcing consumers to use type aliases or add
+ * `[key: string]: unknown`.
+ *
+ * @param gateId Full gate id, including the prefix (e.g. `'permission:articles.publish'`).
+ *               Evaluators typically split on `:` to extract the identifier.
+ * @param context The caller-supplied context blob (see {@link GateEvaluationContext}).
+ */
+export type GateEvaluator<TCtx extends {
+    [K in keyof TCtx]: unknown;
+} = GateEvaluationContext> = (gateId: string, context: TCtx) => Promise<boolean> | boolean;
+/**
+ * Tool definition shape required by `composeDockAvailability`. A subset of
+ * the full {@link ToolDef} that drops Svelte-specific fields (`component`,
+ * `iconComponent`) so the composer stays server-side-safe. Consumers
+ * typically derive this from their registered `ToolDef[]` by picking the
+ * fields they want to surface in `availableTools`.
+ */
+export interface GatedToolSummary {
+    id: string;
+    label?: string;
+    badge?: number | string | null;
+    gates?: string[];
+}
+/**
+ * Options for {@link composeDockAvailability}.
+ *
+ * Generic over the caller's context shape (`TCtx`) so evaluators get
+ * typed access to context fields without casting. Defaults to the
+ * permissive `GateEvaluationContext` so existing call sites keep
+ * compiling.
+ *
+ * The constraint is a self-mapped `{ [K in keyof TCtx]: unknown }` so
+ * interface-style contexts (no string index signature) are accepted —
+ * see the doc on {@link GateEvaluator} for the rationale.
+ *
+ * @example
+ * ```ts
+ * interface MyContext {
+ *   userId: string;
+ *   tenantId: string;
+ * }
+ *
+ * await composeDockAvailability<MyContext>({
+ *   tools: [...],
+ *   context: { userId: 'u-1', tenantId: 't-1' },
+ *   evaluators: {
+ *     permission: async (gateId, ctx) => {
+ *       // ctx.userId and ctx.tenantId are typed `string` — no cast needed
+ *       const [, slug] = gateId.split(':', 2);
+ *       return resolver.hasPermission(ctx.userId, ctx.tenantId, slug);
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export interface ComposeDockAvailabilityOptions<TCtx extends {
+    [K in keyof TCtx]: unknown;
+} = GateEvaluationContext> {
+    /** Registered tools (or a subset thereof — typically derived from `ToolDef[]`). */
+    tools: ReadonlyArray<GatedToolSummary>;
+    /**
+     * Caller-supplied context (userId, tenantId, contentId, etc.). Passed
+     * through unchanged to each evaluator. The composer doesn't inspect it.
+     */
+    context: TCtx;
+    /**
+     * Map of gate-prefix → evaluator. The prefix is the part of the gate ID
+     * before the first `:`. e.g., `'permission'`, `'feature'`, `'myapp'`.
+     *
+     * Tools whose gates reference an unregistered prefix throw at composition
+     * time — misconfiguration should fail loudly, not silently leak tools.
+     */
+    evaluators: Record<string, GateEvaluator<TCtx>>;
+}
+export type { AvailableTool };
+//# sourceMappingURL=types.d.ts.map

package/dist/components/workspace/server/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/components/workspace/server/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAW,MAAM,aAAa,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,aAAa,CACvB,IAAI,SAAS;KAAG,CAAC,IAAI,MAAM,IAAI,GAAG,OAAO;CAAE,GAAG,qBAAqB,IACjE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,8BAA8B,CAC7C,IAAI,SAAS;KAAG,CAAC,IAAI,MAAM,IAAI,GAAG,OAAO;CAAE,GAAG,qBAAqB;IAEnE,mFAAmF;IACnF,KAAK,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;IACvC;;;OAGG;IACH,OAAO,EAAE,IAAI,CAAC;IACd;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC;CACjD;AAKD,YAAY,EAAE,aAAa,EAAE,CAAC"}

package/dist/components/workspace/server/types.js

@@ -0,0 +1,11 @@
+/**
+ * Types for the server-side dock availability gate composer.
+ *
+ * See `compose-availability.ts` for the runtime utility and
+ * happyvertical/smrt#1226 (Phase 4c) / #1235 for design context.
+ *
+ * This module is intentionally Node-safe — no Svelte component imports,
+ * no `window`/`document`, no browser-only APIs — so consumers can call it
+ * from server endpoints (`+server.ts`, REST handlers, etc.).
+ */
+export {};