@w6w/embed 0.0.0-stage → 0.1.1

package/dist/lib/rail-settings.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Pure decisions behind the right rail's Settings tool (`src/ui/rail/SettingsTool.tsx`,
+ * `id: "aliases"`, `title: "Settings"` since T3.1.2 — the tool widened past aliases alone
+ * into a resource Settings panel: a metadata block and, for Functions and Endpoints, an
+ * Export / Edit JSON action row (T3.3.1 — the definition itself no longer renders in the
+ * panel, only the two buttons that open it in a modal), alongside the alias list
+ * `../lib/alias-rail.ts` already decides). Split out so `node --test` can gate them
+ * directly — same reasoning as
+ * `alias-rail.ts`'s own header: `node --test` throws `ERR_UNKNOWN_FILE_EXTENSION` on
+ * anything reaching the `@w6w/ui` / `Layout.tsx` import graph, and `src/ui/workspace.tsx`
+ * sits one hop from that barrel through `Layout.tsx`'s import graph. So this module
+ * declares its own structural mirror of the kinds it cares about instead of importing
+ * `WorkspaceKind`, and takes only `import type` throughout.
+ *
+ * T4.1.1 widens this file's scope past the Settings tool itself: `restoreRailState`
+ * (A2, `RightRail.tsx`'s persisted-state read path) and `isRowArchived`/`visibleRows`
+ * (A6, the three listing pages' "Show archived" toggle) are pure decisions with the
+ * exact same `node --test`-reachability constraint, so they land here rather than in
+ * a new sibling module the contract's `inputs.touch` list didn't ask for.
+ */
+/** Structural mirror of `WorkspaceCallable["kind"]` (`src/ui/workspace.tsx`) — every kind
+ *  the rail can have open, not only the two this tool's action-row/metadata sections
+ *  apply to. */
+export type RailSettingsKind = "workflow" | "function" | "endpoint" | "connection";
+/**
+ * A4/T3.1.1: which metadata rows the Settings panel shows for this kind. `id` always
+ * (every kind the tool is available on carries one). `key` for `function`/`endpoint`
+ * (unchanged) AND, since T3.1.1, `workflow` too — `GET /workflows` now carries `key`
+ * on every row (`string | null`, D-1: nullable, no backfill), and the panel renders it
+ * as an editable control for `function`/`workflow` and the existing read-only `<code>`
+ * for `endpoint` (`SettingsTool.tsx` gates that render choice on `ctx.kind` directly,
+ * never on this array — an Endpoint's `key` entry here must not be read as "editable").
+ * `updatedAt` stays `function`/`endpoint`-only: nothing asks for a Workflow Updated row,
+ * and adding one would be a second, unrelated rail row. Deliberately never `createdAt`
+ * (note 6): neither `GET /functions/:id` nor `GET /endpoints/:id` returns it, so
+ * surfacing it would take a server change for one cosmetic field — this function's own
+ * absence of a `createdAt` arm is half of that gate, the other half is the negative
+ * assertion in the caller's markup.
+ */
+export declare function metadataFieldsForKind(kind: RailSettingsKind): ReadonlyArray<"id" | "key" | "updatedAt">;
+/**
+ * A2/A5: the Export / Edit JSON action row exists for `function`/`endpoint` only. A
+ * Workflow already has its own read-only Definition card
+ * (`pages/WorkflowDetailPage.tsx:371-388`); a Connection has no stored definition shaped
+ * like these two to show at all. (T3.3.1: renamed from the panel's earlier JSON-section
+ * name — there is no JSON section left in the panel to describe, only the two buttons
+ * that open one in a modal.)
+ */
+export declare function hasDefinitionActions(kind: RailSettingsKind): boolean;
+/**
+ * A1/T3.1.1: does this kind have a version-history browser (the read-only browse list plus
+ * Publish and Enable/Disable) in the Settings panel? `true` for `function`/`workflow`/`endpoint`,
+ * `false` for `connection` — written as a `switch` naming every one of the four `RailSettingsKind`
+ * arms explicitly, with no `default:`, matching {@link specCollectionForKind}'s shape and the
+ * reason its own docblock gives (`:69` below — "every one of the four `RailSettingsKind` arms is
+ * named explicitly below" so a kind can never silently fall through). Deliberately NOT derived
+ * from {@link hasDefinitionActions}, which is `function`/`endpoint`-only: History covers Workflow
+ * too, so deriving one from the other would silently drop it.
+ */
+export declare function hasVersionHistory(kind: RailSettingsKind): boolean;
+/**
+ * A1/T1.3.1: does this kind get a Delete (or, for `workflow`, Archive-then-Delete) affordance at
+ * the bottom of the Settings panel? `true` for `function`/`workflow`/`endpoint`, `false` for
+ * `connection` — written as a named `switch` naming every one of the four `RailSettingsKind` arms
+ * explicitly, with no `default:`, matching {@link hasVersionHistory}'s exact shape (`:72-81` above)
+ * for the same reason its own doc comment gives: a kind can never silently fall through. Deliberately
+ * NOT derived from {@link hasVersionHistory} even though the two currently agree on every arm — a
+ * future kind that gets history but not deletion (or vice versa) must not silently inherit the
+ * wrong answer from a sibling predicate.
+ */
+export declare function hasDelete(kind: RailSettingsKind): boolean;
+/**
+ * A4: which `/<collection>/:id/spec` route the Export button's `useSpecQuery`
+ * (`../repos/spec-export.ts`) must call for this kind — `null` for the two kinds A2's
+ * action row never renders on. Kept in lockstep with {@link hasDefinitionActions}
+ * (both are `function`/`endpoint`-only) but expressed as its own total function rather
+ * than derived from it, so a Function can never be exported through
+ * `/endpoints/:id/spec` by a wrong `if`/`else` fallthrough — every one of the four
+ * `RailSettingsKind` arms is named explicitly below.
+ */
+export declare function specCollectionForKind(kind: RailSettingsKind): "functions" | "endpoints" | null;
+/** What A8's `evaluateEdit` needs to know about the row already on screen — deliberately
+ *  narrower than a whole `FunctionDef`/`EndpointDef`: the two fields a hand-edit must not
+ *  be allowed to change out from under the row it opened on. */
+export interface EditStored {
+    id: string;
+    key: string;
+}
+/** A8's total function's result: the parsed body (when parseable and a plain object, even
+ *  if it goes on to fail arm 2 or 3 — the modal still has something to inspect for the
+ *  render, just never something Save may submit) plus the one reason Save is refused, or
+ *  `null` when the edit is allowed through. */
+export interface EditEvaluation {
+    parsed: Record<string, unknown> | null;
+    blockedReason: string | null;
+}
+/**
+ * A8: is this edited text a Save the rail may submit? A total function over the modal's
+ * OWN text state — never `JsonEditor`'s `onValidityChange` (note 10: the only browser
+ * harness this repo has stubs `JsonEditor` with a callback that is wired but never
+ * invoked, so a Save gated on it would look gated and be inert; parsing `text` here is
+ * behaviourally identical and fully observable by a page guard).
+ *
+ * Three refusals, evaluated in order, each named for the near-miss it kills:
+ *   1. the text does not parse as JSON, or parses to something that is not a plain object
+ *      (`null` and an array both fail here, not a dedicated fourth arm — a
+ *      `FunctionDef`/`EndpointDef` is never legitimately either);
+ *   2. `parsed.id !== stored.id` (note 9 — `FunctionsRepo.upsert` selects the row by
+ *      `definition.id`, so an edited id does not edit this row, it creates or hijacks a
+ *      different one);
+ *   3. `parsed.key !== stored.key` (note 8 — `POST /endpoints` 409s on a changed key while
+ *      `POST /functions` silently accepts one; locking it here keeps both kinds behaving
+ *      the same from this one modal).
+ */
+export declare function evaluateEdit(text: string, stored: EditStored): EditEvaluation;
+/** A7/D-3's total function's result: may the save proceed, and if not, why —
+ *  rendered verbatim in `WorkflowsPage.tsx`'s existing error/banner idiom. */
+export interface KeyEditEvaluation {
+    allowed: boolean;
+    reason: string | null;
+}
+/**
+ * D-3: is a Workflow save carrying this `key` one `WorkflowsPage.tsx`'s raw-JSON
+ * editor may submit? The right rail's Key control (`SettingsTool.tsx`) is the ONLY
+ * path allowed to assign or change a workflow's key (see this project's Requirement);
+ * this total function is what keeps a hand-edit of the JSON — via the Save button OR
+ * auto-save, both of which must fold this in (see `WorkflowsPage.tsx`'s `canSave`) —
+ * from doing it silently instead.
+ *
+ * `loadedKey` is the key `WorkflowsPage.tsx` most recently loaded FROM THE SERVER
+ * (its own `loadedKeyRef`, captured at both of its load sites — the initial `editId`
+ * effect and `reloadFromServer`). `undefined` means nothing has loaded yet, which
+ * refuses unconditionally: there is nothing yet to compare the parsed text against,
+ * so allowing the save through would let an unloaded/stale comparison pass by
+ * accident. Once loaded, `loadedKey` is `string | null` (P5's unset state, D-1).
+ *
+ * `parsedKey` is whatever the parsed JSON text's own `key` field currently holds.
+ * `undefined` (the field is absent from the text) is treated exactly like an
+ * explicit `null` — both mean "no key" on the wire, and a definition that dropped
+ * the field entirely must be refused exactly like one that changed it, never waved
+ * through as "nothing to compare".
+ */
+export declare function workflowKeyEditAllowed(loadedKey: string | null | undefined, parsedKey: unknown): KeyEditEvaluation;
+/**
+ * T4.1.1/A2: the shape actually written to `localStorage` for the right
+ * rail's persisted state (`RightRail.tsx`'s `PersistedRail`) — `activeTool`
+ * ONLY. `open` is deliberately absent from this interface, not merely
+ * unwritten: {@link restoreRailState} below has nothing to read it FROM, so
+ * a pre-existing `{"open":true,…}` value written before this task cannot
+ * reopen the rail even by accident.
+ */
+export interface StoredRailState {
+    activeTool: string | null;
+}
+/**
+ * A2: parses `localStorage`'s raw rail entry into {@link StoredRailState}.
+ * Missing/unparsable input, or a non-string `activeTool`, all fall back to
+ * `{ activeTool: null }` — the same defensive shape `RightRail.tsx`'s own
+ * `readStoredState` used before this task, minus the `open` field entirely.
+ * `RightRail.tsx` is the one caller; it combines this result with a hardcoded
+ * `open: false` on every read (D-I0-2) — that combination happens there, not
+ * here, because `open`'s absence from THIS function's return type is the
+ * proof a page guard can pin: there is no `open` member left to misread.
+ */
+export declare function restoreRailState(raw: string | null): StoredRailState;
+/**
+ * A6: a listing row either Workflow, Function or Endpoint's list carries —
+ * whichever archived signal the row's own kind uses. Workflow rows signal
+ * archived via the existing `status === "archived"` (`WorkflowSummary`);
+ * Function/Endpoint rows via the new `archivedAt` column T1.1.1 ships
+ * (`string | null`). Both fields optional so one predicate below covers all
+ * three wire shapes without a per-kind branch at each listing page's call
+ * site.
+ */
+export interface ArchivableRow {
+    status?: string;
+    archivedAt?: string | null;
+}
+/**
+ * A6: is this row archived? `status` takes priority when the row carries one
+ * (Workflow rows always do) — falls back to `archivedAt` otherwise (Function/
+ * Endpoint rows, which have no `status` field at all).
+ */
+export declare function isRowArchived(row: ArchivableRow): boolean;
+/**
+ * A6: which rows a listing page's "Show archived" toggle should render.
+ * `showArchived` false (the default) drops every archived row; `true`
+ * reveals them ALONGSIDE the live ones — an include, never a toggle that
+ * hides the rest (the contract's mutation M6: a toggle that hides LIVE rows
+ * once ON must fail the "both a live and an archived row survive together"
+ * case below; M7: defaulting to showing archived rows must fail the
+ * toggle-OFF case). One pure function shared by `WorkflowsPage.tsx`,
+ * `FunctionsPage.tsx` and `EndpointsPage.tsx` rather than three inline
+ * `.filter`s.
+ */
+export declare function visibleRows<T extends ArchivableRow>(rows: readonly T[], showArchived: boolean): T[];

package/dist/lib/save-invalidation.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared invalidation for a whole-definition save (T3.1.1). `useSaveFunctionMutation` and
+ * `useSaveEndpointMutation` (`src/repos/functions.ts`, `src/repos/endpoints.ts`) both route their
+ * `onSuccess` through this one helper rather than inlining the two `invalidateQueries` calls at
+ * each site — so a save invalidates the LIST key (both list pages and the editor depend on it)
+ * *and* the saved resource's own single-resource key (`functionKey(id)` / `endpointKey(id)`),
+ * never just the list.
+ *
+ * No value imports on purpose: `node --test` throws `ERR_UNKNOWN_FILE_EXTENSION` on anything that
+ * reaches the `@w6w/ui` / `Layout.tsx` import graph, and `src/repos/*.ts` reaches it through
+ * `../api/apiClient.tsx` (JSX). This module has none of that, so it is loadable by `node --test`
+ * directly — see `src/lib/alias-rail.ts`'s docstring for the same reasoning.
+ */
+export interface QueryInvalidator {
+    invalidateQueries(filters: {
+        queryKey: readonly unknown[];
+    }): unknown;
+}
+/**
+ * Invalidate the list key, then the saved resource's own key. List first: both keys are
+ * invalidated regardless of order, but the order is asserted (see the unit test) so a future edit
+ * that drops one call is a diff a reviewer can spot in a single line.
+ */
+export declare function invalidateSavedCallable(qc: QueryInvalidator, listKey: readonly unknown[], callableKey: readonly unknown[]): void;

package/dist/lib/sdk-snippets.d.ts

@@ -0,0 +1,96 @@
+import { TriggerPreviewFieldDef } from './trigger-preview.ts';
+/**
+ * One declared input of a Function or Endpoint, as a snippet needs it.
+ *
+ * A BARE STRING is treated as REQUIRED. That is the shape this file took before
+ * it knew about optionality, when every input rendered active — so a caller that
+ * only has keys keeps its existing output rather than silently having every
+ * field commented out.
+ */
+export type SnippetInput = string | {
+    key: string;
+    required?: boolean;
+};
+/** What the caller is looking at. Mirrors the four runnable URN arms plus assets. */
+export type SnippetCallable = {
+    kind: "workflow";
+    id: string;
+    displayName?: string;
+    key?: string;
+    alias?: string;
+} | {
+    kind: "function";
+    id: string;
+    key?: string;
+    inputs?: readonly SnippetInput[];
+    alias?: string;
+}
+/**
+ * An Endpoint. `invokeUrl` / `invokeUrlByKey` are the two SERVER-rendered
+ * forms of its public address, passed straight through from the endpoints
+ * envelope; `urlForm` is which of them the page currently has selected, so a
+ * raw-HTTP sample follows the toggle the reader can see. All three are
+ * optional — an Endpoint with no URL in hand simply gets no HTTP snippet.
+ * `inputs` are the target's input parameter keys, resolved from the Function
+ * or Workflow the Endpoint dispatches to.
+ */
+ | {
+    kind: "endpoint";
+    id: string;
+    key?: string;
+    invokeUrl?: string;
+    invokeUrlByKey?: string;
+    urlForm?: "id" | "key";
+    alias?: string;
+    inputs?: readonly SnippetInput[];
+}
+/** One app action, invoked through a connection — the `conn_` URN arm. */
+ | {
+    kind: "connection";
+    id: string;
+    action: string;
+    params?: string[];
+} | {
+    kind: "var";
+    name: string;
+} | {
+    kind: "document";
+    key: string;
+};
+export interface Snippet {
+    /** Runnable TypeScript against `@w6w/sdk`. */
+    node: string;
+    /** A single `w6w …` invocation. */
+    cli: string;
+    /** Runnable Python against `w6w` (PyPI). */
+    python: string;
+    /**
+     * A raw-HTTP (`curl`) call against the resource's own public URL — OPTIONAL,
+     * and emitted only where such a URL exists and was handed in (today: an
+     * Endpoint). Optional rather than required so the other five `case` arms of
+     * {@link buildSnippet} are untouched, and so the tab strip can render only
+     * the tabs a built snippet actually carries.
+     */
+    curl?: string;
+    /** The contract operation this maps to, shown so the snippet is checkable. */
+    operation: string;
+}
+/**
+ * Can this id be passed to `client.run({urn})` at all?
+ *
+ * Ids are host-issued and carry a kind prefix (rfcs/function.md §id — "host-issued
+ * opaque id (`fn_…`)"), but the create routes do not *enforce* it, so a
+ * hand-authored id can reach the database without one. Such a resource is
+ * reachable through the studio and through its own `/invoke` route, but NOT
+ * through the URN operation the wrappers expose — and a snippet is a promise
+ * that the code in it runs.
+ */
+export declare function isUrnAddressable(id: string): boolean;
+/**
+ * Build the Node + CLI snippet for one resource, or `null` when the contract
+ * has no operation for it (today: a function or endpoint whose id carries no
+ * runnable prefix).
+ */
+export declare function buildSnippet(resource: SnippetCallable, triggerFields?: readonly TriggerPreviewFieldDef[]): Snippet | null;
+/** Why no snippet exists, phrased for the reader rather than for a log. */
+export declare function unavailableReason(resource: SnippetCallable): string;

package/dist/lib/settings-rail.d.ts

@@ -0,0 +1,68 @@
+import { CallableOnError, ErrorReroute, RetryPolicy } from '@w6w/sdk/console';
+/** Structural mirror of `WorkspaceCallable` (`src/ui/workspace.tsx`) — only
+ *  the fields this module reads. `onPolicyChange` is the WORKFLOW arm's
+ *  injected writer (see {@link isAvailable}); the two callable arms have no
+ *  such member and never read it. */
+export type SettingsCallable = {
+    kind: string;
+    id: string;
+    onPolicyChange?: (policy: CallablePolicy) => void;
+} | null;
+/** The three fields this tool owns on a Function/Endpoint definition —
+ *  TC2's pinned shape, shared by both `Fn` and `Endpoint`. */
+export interface CallablePolicy {
+    retry?: RetryPolicy;
+    onError?: CallableOnError;
+    reroute?: ErrorReroute;
+}
+/** A definition carrying (at least) the three fields above, plus whatever
+ *  else `Fn`/`Endpoint` declares — `definitionWithPolicy` preserves every
+ *  field this type doesn't name. */
+export type CallableDefinition = CallablePolicy;
+/**
+ * Is the Error handling tool meaningful for this context?
+ *
+ * A Function and an Endpoint: always — the panel owns their whole
+ * read-modify-write, because nothing else on the page is editing the same
+ * definition at the same time.
+ *
+ * A Workflow: only when the publishing page injects `onPolicyChange` (core
+ * Workflow RFC — *Amendment — 2026-08-21: the run-level error handler*). This
+ * is not fussiness. The workflow canvas holds the definition as JSON TEXT it
+ * owns, and auto-saves it (`settings.autoSave` defaults to ON), so a rail
+ * panel doing its own read-modify-write against the server would be racing the
+ * editor: whichever wrote last would silently drop the other's edit, and the
+ * loser would most often be the rail, since the canvas re-sends its whole
+ * buffer on the next keystroke. Injecting the writer instead means the rail
+ * edits the SAME buffer the canvas is about to save. A page that does not own
+ * that buffer (the run-detail page) publishes no writer, and the tool simply
+ * does not appear there.
+ *
+ * A Connection has no run-level policy at all. `null` (no resource published)
+ * fails closed, house style (mirrors `code-rail.ts`'s `isAvailable`).
+ */
+export declare function isAvailable(ctx: SettingsCallable): boolean;
+/**
+ * Read a definition's `{retry, onError, reroute}` into the shape the panel's
+ * local editing state starts from. Normalizes the same way
+ * `definitionWithPolicy` writes: a stored `onError: "fail"` (never written by
+ * this tool, but defensive against a hand-edited or older definition) reads
+ * back as absent, matching how `NodeConfigForm` already treats `"fail"` as
+ * its own default.
+ */
+export declare function policyFromDefinition(def: CallableDefinition): CallablePolicy;
+/**
+ * Read-modify-write: apply `policy`'s `{retry, onError, reroute}` onto `def`,
+ * preserving every OTHER field untouched (`impl`/`inputs`/`key` on a
+ * Function, `target`/`input`/`key` on an Endpoint, …) — the save this tool
+ * issues is never a bare `{retry, onError, reroute}` object. A field whose
+ * value is the default is OMITTED entirely, not written as `undefined`:
+ * `policy.onError === "fail"` (or absent) drops the key, matching
+ * `NodeConfigForm`'s own "fail" -> absent convention for the field it edits
+ * in place. Built by destructuring the three fields OUT of `def` and
+ * conditionally re-spreading them, rather than `delete`, so the key is
+ * genuinely absent from the returned object, not merely `undefined`-valued —
+ * `node:assert/strict`'s deep-equal distinguishes the two (this module's own
+ * test pins it).
+ */
+export declare function definitionWithPolicy<T extends CallableDefinition>(def: T, policy: CallablePolicy): T;

package/dist/lib/slug.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Slug rules — the ONE place in `studio/src` that owns one.
+ *
+ * Two rules live here and they are deliberately NOT the same rule:
+ *
+ * · `slugify()` turns a human display name into a machine key. It is the
+ *   fallback the Endpoint and Function editors use when the operator leaves
+ *   `key` blank, and it is permissive on purpose: whatever it returns is a
+ *   legal resource key, digits-first and two characters included.
+ * · `ACCOUNT_SLUG_RE` / `isValidAccountSlug()` decide whether a string is a
+ *   legal ACCOUNT slug — the account segment a key-form invoke URL is
+ *   addressed by. That rule is stricter: it must start with a letter and run to
+ *   at least three characters, so `2024-team` and `ab` are both perfectly good
+ *   keys and both invalid account slugs.
+ *
+ * The regex is exported rather than re-typed by each caller. A second copy is
+ * exactly how a form comes to accept a value the server rejects, so the literal
+ * appears in this file and nowhere else in `src/`.
+ *
+ * Why `src/lib` and why this module imports nothing: `src/lib/*.ts` is the only
+ * place studio's `node --test` suite can reach. A rule living inside a `.tsx`
+ * page cannot be unit-tested at all (Node's type-stripping does not parse JSX),
+ * and a `src/lib` module that imports `@w6w/ui` throws
+ * `ERR_UNKNOWN_FILE_EXTENSION` under the same runner because the barrel
+ * re-exports `.tsx`. Same constraint documented at
+ * `src/lib/workflow-validity.ts:11-20`.
+ */
+/** Kebab-case a display name into a machine key (the fallback when key is blank). */
+export declare function slugify(s: string): string;
+/**
+ * A legal account slug: lowercase, opens with a LETTER, then two or more
+ * letters/digits/hyphens — three characters minimum.
+ *
+ * Note this is NOT the server's `tenants.ts` `SLUG_RE`
+ * (`/^[a-z0-9][a-z0-9_-]*$/`), which governs tenant ids and is a different,
+ * more permissive rule. Do not merge the two.
+ */
+export declare const ACCOUNT_SLUG_RE: RegExp;
+/** Does `s` satisfy {@link ACCOUNT_SLUG_RE}? */
+export declare function isValidAccountSlug(s: string): boolean;
+/**
+ * A legal Endpoint `key` — mirrors the server's rule VERBATIM, not
+ * {@link ACCOUNT_SLUG_RE} above: that one is `{2,}` with no 39-character cap
+ * and encodes neither the `--` rule nor the trailing-`-` rule, so a form that
+ * validated a key with it would accept a value the server rejects.
+ *
+ * Source of truth: `packages/server/packages/bll/accounts.ts:72`
+ * (`ACCOUNT_SLUG_RE = /^[a-z][a-z0-9-]{2,38}$/`) + `:216-218` (`isAccountSlug`),
+ * reached from `packages/server/packages/api/invoke-address.ts:55-57`
+ * (`isEndpointKey = isAccountSlug`). There is no reserved-word check on an
+ * Endpoint key server-side — `isAccountSlug` only, never
+ * `RESERVED_ACCOUNT_SLUGS` — so none is added here either.
+ */
+export declare function isEndpointKey(s: string): boolean;
+/**
+ * Filters a keystroke into a key input down to what {@link isEndpointKey}'s
+ * grammar can ever accept: lowercase letters, digits, hyphens — nothing
+ * else, capped at the grammar's own 39-character ceiling. A space or any
+ * other disallowed character is dropped outright rather than folded into a
+ * `-` ({@link slugify}'s job, for the one-time displayName-to-key fallback —
+ * this is a LIVE filter on a field the operator is typing directly into, so
+ * silently substituting a different character would be its own surprise).
+ * Positional rules the grammar also enforces (must START with a letter, no
+ * `--`, no trailing `-`) are left to {@link isEndpointKey} at Save time —
+ * blocking those mid-keystroke would refuse a caller who is one keystroke
+ * away from a valid value (e.g. typing `"2"` before backspacing to start
+ * over).
+ */
+export declare function filterKeyInput(raw: string): string;

package/dist/lib/spec-import-invalidation.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The extracted decision behind `useImportSpecMutation`'s `onSuccess` (T1.2.1, AC-3): given the
+ * KIND of document that was just imported, which single list-query key must be invalidated — and
+ * only that one.
+ *
+ * The bug this exists to kill: `src/repos/spec-import.ts` used to run an unconditional
+ * `qc.invalidateQueries({ queryKey: functionsKey })` on every import — invisible to `tsc`, only
+ * visible when a human imports an Endpoint or Workflow and its OWN list stays stale while
+ * Functions gets pointlessly invalidated.
+ *
+ * The three real list keys live in `src/repos/functions.ts` / `endpoints.ts` / `workflows.ts`, and
+ * this module cannot import them as VALUES: `node --test` throws `ERR_UNKNOWN_FILE_EXTENSION` on
+ * anything reaching the `@w6w/ui` / JSX import graph, and `src/repos/*.ts` reaches it through
+ * `../api/apiClient.tsx` — see `src/lib/save-invalidation.ts`'s docstring for the identical
+ * constraint. So the caller (`spec-import.ts`, which already imports all three) hands them in; this
+ * module owns only the DISPATCH — which kind picks which key — not the keys' own values. That keeps
+ * the two ends impossible to drift apart on the workflow arm's shape in particular: `workflowsKey`
+ * is `(project?: string) => ["workflows", project]`, NOT a bare constant like the other two, and
+ * `WorkflowsPage`'s list branch (`CallableList`, `pages/CallablePage.tsx`) reads its cache through
+ * `useCallableListQuery("workflow", …, projectId)` — an invalidation that drops the project id hits
+ * a DIFFERENT cache entry and the imported row would not appear without a manual refresh, which is
+ * the exact bug this module exists to prevent.
+ */
+export type SpecImportKind = "function" | "endpoint" | "workflow";
+/** Mirrors `src/lib/save-invalidation.ts`'s `QueryInvalidator` — re-declared, not imported, so this
+ *  module's zero-value-import rule needs no exception (a structural type has no runtime cost either
+ *  way; TanStack Query's real `QueryClient` satisfies both). */
+export interface QueryInvalidator {
+    invalidateQueries(filters: {
+        queryKey: readonly unknown[];
+    }): unknown;
+}
+/** The three list-key producers, handed in by the caller — see the module docblock for why this
+ *  module cannot hold them itself. `workflowsKey` is a function, not a value, because it is scoped
+ *  by project. */
+export interface SpecImportListKeys {
+    functionsKey: readonly unknown[];
+    endpointsKey: readonly unknown[];
+    workflowsKey: (projectId: string | undefined) => readonly unknown[];
+}
+/**
+ * Total: exhaustively switched over the three spec kinds (mirrors `specCollectionForKind`'s idiom
+ * in `src/lib/rail-settings.ts` — a plain switch with no default arm, so an unhandled kind is a
+ * compile error rather than a silent fallthrough).
+ */
+export declare function specImportListKey(kind: SpecImportKind, keys: SpecImportListKeys, projectId: string | undefined): readonly unknown[];
+/** Invalidate the ONE list key the imported document's own kind reads — never more than one. */
+export declare function invalidateImportedCallable(qc: QueryInvalidator, kind: SpecImportKind, keys: SpecImportListKeys, projectId: string | undefined): void;

package/dist/lib/tag-editor.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pure decision logic behind `../components/TagEditor.tsx` — kept out of the
+ * component so `node --test` can exercise it directly
+ * (`__tests__/tag-editor.test.ts`) without touching React, mirroring
+ * `alias-rail.ts`/`rail-settings.ts`'s own split. Carries over the retiring
+ * `WorkflowsPage.tsx`'s retired tags-editing modal's data contract verbatim:
+ * `string[]`, trim, dedupe-on-add, drop empties.
+ */
+/**
+ * Applies a chip input's freeform text to the committed tag list. Called on
+ * every change to the trailing, not-yet-committed input — `typed` is always
+ * the FULL current value of just that one input, which resets to `""` after
+ * a commit, so a single keystroke never carries more than the one character
+ * just typed.
+ *
+ * A comma anywhere in `typed` is the commit signal: every comma-delimited
+ * segment is trimmed and, if non-empty and not already present, appended as
+ * a chip — in order, regardless of whether it sits before or after the last
+ * comma. That is what makes both shapes work from the one rule: typing
+ * `"alpha,"` one character at a time commits `"alpha"` the moment the comma
+ * lands, and pasting `"a,b,c"` in one go (no trailing comma at all) still
+ * commits all three, because nothing here treats "the last segment" as
+ * special. The returned `typed` is always `""` once a comma triggered a
+ * commit. With no comma present at all, nothing commits and `typed` passes
+ * through unchanged, so the caller can just store it as the next draft.
+ */
+export declare function commitTag(tags: string[], typed: string): {
+    tags: string[];
+    typed: string;
+};
+/**
+ * Removes exactly one tag by VALUE, never by position — a list carrying both
+ * a tag and a second tag that merely contains it as a prefix (`["ab", "b"]`)
+ * only ever loses the exact match.
+ */
+export declare function removeTag(tags: string[], tag: string): string[];

package/dist/lib/trigger-preview.d.ts

@@ -0,0 +1,89 @@
+/**
+ * "Call from code" trigger preview (T2.2.1, HITL-2/HITL-4 pinned):
+ *
+ * > one tab per MANUAL (`@w6w/trigger`) trigger step, in declared order,
+ * > labelled `step.displayName ?? step.id`. Webhook/scheduler steps are
+ * > excluded — they declare named params, never a generic `fields` array.
+ *
+ * Pure and testable by design, same shape as `workflow-validity.ts`:
+ * `WorkflowDetailPage.tsx`/`WorkflowsPage.tsx` are JSX, which Node 24's
+ * type-stripping cannot parse, so nothing in it can be loaded by
+ * `node --test`. This module cannot import `@w6w/ui`/`@w6w/ui/flow` either
+ * way (`ERR_UNKNOWN_FILE_EXTENSION` — see `workflow-validity.ts`'s docstring).
+ * Instead, "is this step a MANUAL trigger" and "read a trigger's declared
+ * `fields`" are **caller-injected** on `TriggerPreviewContext` —
+ * `WorkflowsPage.tsx`/`WorkflowDetailPage.tsx` import the real
+ * `TRIGGER_APP`/`asFieldDefs` from `@w6w/ui/flow` and pass them in. This file
+ * contains no `@w6w/*` app-id string literal.
+ *
+ * Deliberately narrower than `@w6w/ui/flow`'s own `isTriggerApp`, which also
+ * matches `@w6w/webhook`/`@w6w/scheduler` (all three are "entry nodes" for the
+ * canvas). Those two kinds declare named params, not a generic `fields`
+ * array, so they cannot be previewed the same way — the injected predicate a
+ * caller supplies here is expected to be the MANUAL-only check
+ * (`app === TRIGGER_APP`), not the broader `isTriggerApp`.
+ */
+/** One field a trigger declares — just enough of `@w6w/ui/flow`'s
+ *  `TriggerFieldDef` for this preview (structurally compatible, not imported). */
+export interface TriggerPreviewFieldDef {
+    key?: string;
+    type?: string;
+    required?: boolean;
+    default?: unknown;
+}
+/** A workflow graph step, just enough of it for this preview. */
+export interface WorkflowStepLike {
+    id: string;
+    /** Human-facing step name, when the author set one. Falls back to `id`. */
+    displayName?: string;
+    uses?: {
+        app?: string;
+        action?: string;
+    };
+    with?: Record<string, unknown>;
+}
+/** A workflow definition, just enough of it for this preview. */
+export interface WorkflowLike {
+    steps?: WorkflowStepLike[];
+}
+/**
+ * Everything `triggerPreviews` needs that this pure module cannot compute or
+ * import itself — see the module docstring for why each field is
+ * caller-injected rather than derived in here.
+ */
+export interface TriggerPreviewContext {
+    /** Is this step's `uses.app` a MANUAL trigger (`@w6w/trigger`)? Webhook and
+     *  scheduler steps must answer `false` here even though they are also
+     *  "entry nodes" — they have no generic `fields` array to preview. */
+    isManualTrigger: (app: string) => boolean;
+    /** `@w6w/ui/flow`'s `asFieldDefs`, injected — reads a step's `with.fields`
+     *  param value as an array of field definitions. */
+    asFieldDefs: (fields: unknown) => TriggerPreviewFieldDef[];
+}
+/** One manual trigger's declared fields, ready for the modal's picker. */
+export interface TriggerPreview {
+    id: string;
+    /** `step.displayName ?? step.id`. */
+    label: string;
+    fields: TriggerPreviewFieldDef[];
+}
+/**
+ * One `TriggerPreview` per manual trigger step in `workflow.steps`, in
+ * declared order. Non-manual steps (including webhook/scheduler entry nodes)
+ * are excluded. A field with a missing/blank `key` is dropped — mirrors
+ * `@w6w/ui/flow`'s `fieldsToParams`, which does the same before turning
+ * `TriggerFieldDef[]` into a fillable form.
+ */
+export declare function triggerPreviews(workflow: WorkflowLike, ctx: TriggerPreviewContext): TriggerPreview[];
+/**
+ * A start-payload skeleton for one manual trigger — every declared field at its
+ * declared default, so the Run panel opens with the shape the workflow actually
+ * expects instead of an empty object the author has to reconstruct by hand.
+ *
+ * Mirrors `@w6w/ui/flow`'s `seedValues` (which this module cannot import — see
+ * the header): an explicit `default` wins; otherwise the empty value for the
+ * declared type. Unknown types fall to `""`, matching that function.
+ *
+ * `undefined` in → `{}`, so a caller can pass a still-loading preview.
+ */
+export declare function triggerInputSeed(preview: TriggerPreview | undefined): Record<string, unknown>;