waterplane 0.0.1 → 0.1.11

package/node_modules/@waterplane/shared/dist/shells.js

@@ -0,0 +1,257 @@
+/** How long a shell may go without its CPU moving or its output growing and
+ *  still read as "working" — ten minutes, generous the same way
+ *  `WATERPLANE_AGENT_STALE_MS` is: a shell doing real work inside a slow build can
+ *  go quiet for minutes at a stretch with nothing wrong. */
+export const SHELL_QUIET_MS = 10 * 60_000;
+/**
+ * Which of four states a shell is in right now.
+ *
+ *   working — it has real workers, and its CPU moved or its output grew
+ *             within `quietMs`.
+ *   waiting — no real workers under it (`workers === 0`): a loop that only
+ *             sleeps between checks. This wins over `working` even when the
+ *             wrapper's OWN cpu ticked moments ago — a real polling loop
+ *             (`until … ; do sleep 10; done`) spends a few ms of CPU on every
+ *             pass around its `sleep`/`pgrep`, every couple of minutes, and
+ *             asking "did the CPU move within ten minutes" answered `working`
+ *             for a shell that has never once had anything running under it.
+ *   quiet   — no recent movement, and it DOES have workers: something is
+ *             running under it that has not been seen to move.
+ *   unknown — no reading has EVER moved (`cpuMovedAt` and `outputAt` both
+ *             absent) — the honest state for a shell seen only once, before
+ *             there is anything to compare against.
+ *
+ * `unknown` is checked first and wins outright: neither `working` nor
+ * `waiting` can be answered with no data at all.
+ */
+export function shellBucket(sh, now, quietMs = SHELL_QUIET_MS) {
+    if (sh.cpuMovedAt === undefined && sh.outputAt === undefined)
+        return "unknown";
+    if (sh.workers === 0)
+        return "waiting";
+    const movedAt = Math.max(sh.cpuMovedAt ?? 0, sh.outputAt ?? 0);
+    return now - movedAt < quietMs ? "working" : "quiet";
+}
+function fmtDuration(ms) {
+    const s = Math.max(0, Math.round(ms / 1000));
+    const d = Math.floor(s / 86400);
+    const h = Math.floor((s % 86400) / 3600);
+    const m = Math.floor((s % 3600) / 60);
+    const sec = s % 60;
+    if (d > 0)
+        return h > 0 ? `${d}d ${h}h` : `${d}d`;
+    if (h > 0)
+        return m > 0 ? `${h}h ${m}m` : `${h}h`;
+    if (m > 0)
+        return `${m}m`;
+    return `${sec}s`;
+}
+/** `pgrep -f "…"` / `pgrep -f '…'`, both quote styles, over a LITERAL pattern
+ *  (no `$`/regex metacharacters — see `selfMatchOf`). */
+const PGREP_RE = /pgrep\s+-f\s+(?:"([^"]*)"|'([^']*)')/g;
+const REGEX_SPECIAL_RE = /[$^.*+?()[\]{}|\\]/;
+/**
+ * The exit condition this shell is waiting on is `pgrep -f` over a pattern
+ * that is — by construction — already part of THIS process's own command
+ * line, so the search can never come back empty.
+ *
+ * The mechanism: the CLI runs the whole script as one `/bin/zsh -c '…'`
+ * argument, which is what `ps` shows as this process's command. `pgrep -f`
+ * matches a pattern against every process's FULL command line, this one
+ * included — and the pattern text sits right there, quoted, as the argument
+ * to the very `pgrep -f` call that is testing for it. A loop built as
+ * `until … ! pgrep -f "X" …; do sleep …; done` can therefore never see
+ * "nothing matches", because it always matches itself.
+ *
+ * `$`/regex metacharacters in the pattern withhold the claim on purpose: with
+ * a real anchor or wildcard in play, whether the pattern still matches the
+ * surrounding text is a real regex question this heuristic does not attempt,
+ * and asserting self-match anyway would be a wrong number, not an absent one.
+ */
+export function selfMatchOf(command) {
+    return selfMatchPattern(command) !== null;
+}
+/** The literal pattern `selfMatchOf` found, for the sentence that names it.
+ *  Null exactly when `selfMatchOf` is false. */
+export function selfMatchPattern(command) {
+    PGREP_RE.lastIndex = 0;
+    let m;
+    while ((m = PGREP_RE.exec(command))) {
+        const pat = m[1] ?? m[2] ?? "";
+        if (pat && !REGEX_SPECIAL_RE.test(pat))
+            return pat;
+    }
+    return null;
+}
+/** Long-running-by-design processes: quiet is the point, not a concern. Every
+ *  entry is matched as a case-insensitive substring, so `--watch` catches
+ *  `nodemon --watch` and `npm run dev` catches the wrapper script that runs
+ *  it either. */
+const SERVER_LIKE_WORDS = [
+    "emulator", "qemu", "vite", "webpack", "next dev", "npm run dev", "serve",
+    "--watch", "tail -f", "firebase emulators", "nodemon", "uvicorn --reload", "expo start",
+];
+export function serverLikeOf(command) {
+    const lower = command.toLowerCase();
+    return SERVER_LIKE_WORDS.some((w) => lower.includes(w));
+}
+/**
+ * One plain sentence for a shell — never "hung"/"stuck"/"dead" (CLAUDE.md).
+ *
+ * `foreground` outranks everything: this is not a background shell at all,
+ * only the running turn's own command wearing the same `ps` shape.
+ * `serverLike` outranks the bucket: a quiet emulator is not a concern and the
+ * words say so instead of reading as one. `selfMatch` outranks the bucket the
+ * same way — a self-matching wait loop gets its own sentence naming the
+ * pattern regardless of what bucket the CPU/output reading would otherwise
+ * put it in, because "waiting in a loop" is true but leaves out the one fact
+ * that matters: it will never end.
+ */
+export function shellWords(sh, now) {
+    if (sh.foreground)
+        return "a command this turn is running";
+    const age = fmtDuration(now - sh.startedAt);
+    if (sh.serverLike)
+        return `long-running by design · ${age}`;
+    if (sh.selfMatch) {
+        const pat = selfMatchPattern(sh.command);
+        if (pat)
+            return `waits for "${pat}" to end — its own command line matches that pattern, so this never ends`;
+    }
+    const bucket = shellBucket(sh, now);
+    if (bucket === "unknown")
+        return "can't tell yet";
+    if (bucket === "working") {
+        const movedAt = Math.max(sh.cpuMovedAt ?? 0, sh.outputAt ?? 0);
+        return `running · ${age} · CPU moved ${fmtDuration(now - movedAt)} ago`;
+    }
+    if (bucket === "waiting")
+        return `waiting in a loop · ${age} · only sleeps between checks`;
+    return `quiet ${age} · no CPU and no output`;
+}
+/** Never counts `unknown` as `quiet` — a shell this app has not watched long
+ *  enough to have an opinion about is not the same claim as one it watched go
+ *  silent. Never counts a `foreground` shell into any bucket or into `total`
+ *  either — it is not a background shell a person could act on from here. */
+export function shellsSummary(list, now, quietMs = SHELL_QUIET_MS) {
+    const s = { working: 0, waiting: 0, quiet: 0, unknown: 0, foreground: 0, total: 0 };
+    for (const sh of list) {
+        if (sh.foreground) {
+            s.foreground++;
+            continue;
+        }
+        s[shellBucket(sh, now, quietMs)]++;
+        s.total++;
+    }
+    return s;
+}
+/** "1 shell · quiet", "3 shells · 2 waiting" — the chip text. Names the most
+ *  notable bucket only (quiet, then waiting, then unknown, then working, the
+ *  order a person would want flagged first), never every count at once. */
+export function shellsChipText(s) {
+    const noun = s.total === 1 ? "shell" : "shells";
+    const base = `${s.total} ${noun}`;
+    if (!s.total)
+        return base;
+    const order = ["quiet", "waiting", "unknown", "working"];
+    const top = order.find((k) => s[k] > 0);
+    if (!top)
+        return base;
+    const word = top === "working" ? "running" : top;
+    return s.total === 1 ? `${base} · ${word}` : `${base} · ${s[top]} ${word}`;
+}
+/** description if present, else the first couple of words of the command —
+ *  for `shellCloseWords`' list. */
+function shellLabel(sh) {
+    if (sh.description)
+        return sh.description;
+    const words = sh.command.trim().split(/\s+/).slice(0, 3).join(" ");
+    return words || "shell";
+}
+/**
+ * One sentence for a close/stop confirm: "stops 3 background shells —
+ * emulator, 2 wait loops".
+ *
+ * `workers === 0` stands in for "wait loop" here rather than the time-based
+ * bucket, deliberately — there is no `now` on this signature, because a close
+ * confirm is about what WILL be stopped, not how long each has been quiet.
+ * Real workers get named individually (their own label); the rest are folded
+ * into one count, so a fan-out of ten idle wrapper shells does not bury the
+ * one that is actually running something. A `foreground` shell is left out
+ * entirely — closing the session ends the turn (and it) anyway, and it was
+ * never a background shell this sentence is about.
+ */
+export function shellCloseWords(summary, list) {
+    if (!summary.total)
+        return "";
+    const labels = [];
+    let waitLoops = 0;
+    for (const sh of list) {
+        if (sh.foreground)
+            continue;
+        if (sh.workers === 0) {
+            waitLoops++;
+            continue;
+        }
+        labels.push(shellLabel(sh));
+    }
+    if (waitLoops)
+        labels.push(waitLoops === 1 ? "1 wait loop" : `${waitLoops} wait loops`);
+    const noun = summary.total === 1 ? "background shell" : "background shells";
+    return `stops ${summary.total} ${noun}${labels.length ? ` — ${labels.join(", ")}` : ""}`;
+}
+/**
+ * Move every companion shell (`SessionInfo.companionOf`) to sit right after
+ * the session it belongs to — the tab strip and the launcher list both draw it
+ * there, so the pair reads as one thing rather than a shell stranded at the end
+ * of the list. A companion whose parent is not in `list` (hidden, filtered,
+ * gone) keeps its own place. Several companions of one parent keep their
+ * relative order. Pure; returns a new array.
+ */
+export function glueCompanions(list) {
+    const ids = new Set(list.map((s) => s.id));
+    const byParent = new Map();
+    for (const s of list) {
+        if (!s.companionOf || s.companionOf === s.id || !ids.has(s.companionOf))
+            continue;
+        const g = byParent.get(s.companionOf);
+        if (g)
+            g.push(s);
+        else
+            byParent.set(s.companionOf, [s]);
+    }
+    if (!byParent.size)
+        return [...list];
+    const glued = new Set([...byParent.values()].flat().map((s) => s.id));
+    const out = [];
+    const place = (s) => { out.push(s); for (const c of byParent.get(s.id) ?? [])
+        place(c); };
+    for (const s of list)
+        if (!glued.has(s.id))
+            place(s);
+    // A cycle (two sessions each naming the other) is not a shape the host
+    // makes; if one arrived, nothing in it was placed — keep them, not drop them.
+    if (out.length < list.length)
+        for (const s of list)
+            if (!out.includes(s))
+                out.push(s);
+    return out;
+}
+/**
+ * Where the header's parent ↔ companion toggle goes from `active`: to its
+ * parent when it IS a companion shell (`to: "cli"`), to its newest companion
+ * when it has one (`to: "shell"`), else nowhere. Only sessions in `list` count
+ * — a toggle to a session that is not there is a tap that does nothing.
+ */
+export function companionToggle(active, list) {
+    if (active.companionOf) {
+        const parent = list.find((s) => s.id === active.companionOf);
+        return parent ? { target: parent, to: "cli" } : null;
+    }
+    const kids = list.filter((s) => s.companionOf === active.id);
+    if (!kids.length)
+        return null;
+    const newest = kids.reduce((a, b) => ((b.createdAt ?? 0) > (a.createdAt ?? 0) ? b : a));
+    return { target: newest, to: "shell" };
+}
+//# sourceMappingURL=shells.js.map

package/node_modules/@waterplane/shared/dist/shells.js.map

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

package/node_modules/@waterplane/shared/dist/slash.d.ts

@@ -0,0 +1,47 @@
+/** True when `text` is one of the TUI-local commands above (args ignored).
+ *  **Not the same question as "does this start a turn"** — see `startsNoTurn`. */
+export declare function isLocalCommand(text: string): boolean;
+/**
+ * True when `text` starts no turn — a TUI-local view, or one of the commands
+ * above that submits and files something instead. **This is the host's
+ * question**: what `deliver.ts` may wait for as proof of delivery. The phone's
+ * question is `isLocalCommand`, which is narrower on purpose.
+ */
+export declare function startsNoTurn(text: string): boolean;
+/**
+ * True when `text` is answered ONLY in an overlay of the CLI's own and written
+ * to no record — `/btw` is the whole of it. **The reader does not try to copy
+ * that answer**: it is said to a working agent by design, so the capture it
+ * would be read from is the running turn's screen with the overlay painted over
+ * it, and every rule written to cut one out of the other (echo seams, repaint
+ * folding, the mid-turn guard) shipped and then missed again. The row says where
+ * the answer is and opens the CLI instead.
+ */
+export declare function answeredOnlyInCli(text: string): boolean;
+/**
+ * True when `text` submits and starts work that fires no hook — the HOST's
+ * third question, asked only by the submit ladder. Neither `isLocalCommand`
+ * (the phone's "is this a modal?") nor `startsNoTurn` (the host's "is there a
+ * turn to wait for at all?") answers it: there IS a turn's worth of work here,
+ * and nothing announces it.
+ */
+export declare function worksUnannounced(text: string): boolean;
+/**
+ * `/fork [title]` — the one command the HOST answers instead of the CLI.
+ *
+ * **The fifth category, and the only one that is never typed.** From 2.1.291 a
+ * `/fork` typed into the TUI no longer forks in place: the CLI hands the branch
+ * to its OWN background daemon (`~/.claude/daemon.log`: `bg claimed-spare …
+ * (slash)`, a job under `~/.claude/jobs/`) and prints `⎿ session waiting ·
+ * <title>`. That session runs in no tmux this host owns, so the phone never
+ * lists it, and its `SessionStart` hook lands on `/api/hook` as an unknown
+ * session and is dropped — a fork asked for from the phone that the phone can
+ * never see. So the host intercepts it (`routes/session.ts`) and opens the fork
+ * itself, as a tab, through the same `sessions.fork()` the toolbar's *fork*
+ * button uses (`--resume <id> --fork-session`).
+ *
+ * Returns `null` when `text` is not a `/fork`, else the title argument — one
+ * line, whitespace collapsed, capped — and `""` when there is none. A command
+ * NAMED like it (`/forked`, `/fork-it`) is not it.
+ */
+export declare function slashForkTitle(text: string): string | null;

package/node_modules/@waterplane/shared/dist/slash.js

@@ -0,0 +1,166 @@
+/**
+ * Which slash commands `claude` handles entirely inside its own TUI — a view, a
+ * picker, a settings toggle.
+ *
+ * **Why this is in `shared` and not in the host.** Both ends need the same
+ * answer for opposite reasons, and while only the host had it the phone could
+ * not ask the one question that mattered: *is this a command, or is this a
+ * view?*
+ *
+ *  - the HOST needs it because these never submit a prompt, so `UserPromptSubmit`
+ *    never fires and no turn ever starts: `deliver.ts` must not wait for (or
+ *    hammer Return trying to produce) a turn-start proof that cannot arrive.
+ *    The extra Returns land in the view the command just opened and dismiss it.
+ *  - the PHONE needs it because a view is not an interjection. Prose typed at a
+ *    working agent is a deliberate interjection and goes in at once, which is
+ *    exactly right for prose and exactly wrong for this: a local command opens a
+ *    MODAL over a session that is mid-turn, contests the composer that turn is
+ *    using, and is then dismissed by the next thing that touches the screen.
+ *    Reported from a phone as `/usage` followed by the CLI's own
+ *    *"Settings dialog dismissed"*, with the session 22 minutes into a turn —
+ *    and, from the other side, as a delivery that sat at "Sending… 10s" holding
+ *    the composer while the agent streamed underneath it.
+ *
+ * Positive list on purpose. Anything not named here — `/init`, `/compact`,
+ * `/review`, every custom `.md` command — really does start a turn and keeps the
+ * normal delivery contract.
+ */
+const LOCAL_ONLY = new Set([
+    // `usage` is the command; `cost` and `stats` are aliases the CLI still
+    // answers to (its own table reads `{ name: "usage", aliases: ["cost",
+    // "stats"] }`), which is why its menu entry draws as "/usage (cost)".
+    "/usage", "/cost", "/stats",
+    "/context", "/status", "/todos", "/help", "/release-notes",
+    "/config", "/model", "/output-style", "/statusline", "/vim", "/terminal-setup",
+    "/agents", "/mcp", "/hooks", "/permissions", "/sandbox", "/add-dir",
+    "/resume", "/rewind", "/clear", "/export", "/memory", "/bashes",
+    "/remote-control", "/ide", "/upgrade", "/bug", "/feedback",
+    "/privacy-settings", "/login", "/logout",
+    // Settings the CLI applies in place (`local-jsx` in its own command table,
+    // checked on the installed build 2026-10-15). `/effort high` was missing: it
+    // set the effort, printed its confirmation, and the host — waiting for a
+    // `UserPromptSubmit` a local command never fires — pressed Return five times
+    // and filed it as "typed, but Return was swallowed".
+    "/effort", "/fast", "/theme", "/color", "/keybindings", "/skills", "/plugin",
+    "/version", "/diff", "/copy",
+]);
+/** True when `text` is one of the TUI-local commands above (args ignored).
+ *  **Not the same question as "does this start a turn"** — see `startsNoTurn`. */
+export function isLocalCommand(text) {
+    return LOCAL_ONLY.has(text.trim().split(/\s+/)[0] ?? "");
+}
+/**
+ * Commands that SUBMIT and still start no turn.
+ *
+ * **A third category, and `/btw` is the whole of it so far.** The set above is
+ * "this opens a view"; an ordinary prompt is "this starts a turn". `/btw` is
+ * neither: it takes the composer's words, files them as a note for the agent to
+ * read at the end of the turn, clears the box — and never fires
+ * `UserPromptSubmit`. Every proof `deliver.ts` rests on for a prompt is
+ * therefore unavailable, and the failure is not subtle: the submit loop pressed
+ * Return five times waiting for a turn that cannot start, asked the conversation
+ * log (silent for a slash command by construction — `transcript.ts` measured
+ * `/btw` as writing NOTHING at all, not even an envelope), and filed the note as
+ * `unsubmitted`. Reported from a phone as a red row reading "it is sitting in
+ * the composer, unsent — do not retype it", about a note that had been filed
+ * perfectly.
+ *
+ * **Why it is not simply added to `LOCAL_ONLY`.** That list is also what the
+ * PHONE reads to decide a command is a view and must be held until the turn
+ * ends — and `/btw` exists precisely to be said to a working agent without
+ * interrupting it. Holding it until idle would defeat the only thing it is for.
+ * So the host's question ("what proves this landed?") and the phone's question
+ * ("is this an interjection or a modal?") stop being the same question here,
+ * and each asks its own.
+ */
+const NO_TURN_ONLY = new Set(["/btw"]);
+/**
+ * True when `text` starts no turn — a TUI-local view, or one of the commands
+ * above that submits and files something instead. **This is the host's
+ * question**: what `deliver.ts` may wait for as proof of delivery. The phone's
+ * question is `isLocalCommand`, which is narrower on purpose.
+ */
+export function startsNoTurn(text) {
+    const head = text.trim().split(/\s+/)[0] ?? "";
+    return LOCAL_ONLY.has(head) || NO_TURN_ONLY.has(head);
+}
+/**
+ * True when `text` is answered ONLY in an overlay of the CLI's own and written
+ * to no record — `/btw` is the whole of it. **The reader does not try to copy
+ * that answer**: it is said to a working agent by design, so the capture it
+ * would be read from is the running turn's screen with the overlay painted over
+ * it, and every rule written to cut one out of the other (echo seams, repaint
+ * folding, the mid-turn guard) shipped and then missed again. The row says where
+ * the answer is and opens the CLI instead.
+ */
+export function answeredOnlyInCli(text) {
+    return NO_TURN_ONLY.has(text.trim().split(/\s+/)[0] ?? "");
+}
+/**
+ * Commands that SUBMIT, do REAL work for minutes, and announce NONE of it.
+ *
+ * **The fourth category, and `/compact` is the whole of it.** It is not a view
+ * (`LOCAL_ONLY`) and it is not a filing clerk (`NO_TURN_ONLY`): the Return runs
+ * a real, expensive operation — "Compacting conversation… (35s) 32%" for as
+ * long as it takes — and fires neither `UserPromptSubmit` nor `Stop`. Every
+ * rung of `deliver.ts`'s submit ladder is therefore unavailable: no turn-start
+ * hook, no Stop counter moving, and nothing in the conversation log (the CLI
+ * writes a slash command as an envelope the transcript reader drops).
+ *
+ * So a `/compact` that had provably started — the phone's own screenshot shows
+ * "✳ Compacting conversation… 15%" in the terminal — came back as *"typed, but
+ * Return was swallowed — open the session and press Return"*, the one sentence
+ * this app writes to be acted on by hand. Pressing that Return again is at best
+ * a no-op and at worst a second compaction of a conversation that just lost its
+ * history.
+ *
+ * **The proof that fits is the one the host already takes for this command**:
+ * the CLI's own working line, read off the screen (`shared/working.ts`, the one
+ * matcher) and published as a turn marked `fromScreen`. `deliver.ts` refuses
+ * that evidence for an ordinary prompt on purpose — a spinner the host inferred
+ * says the CLI is busy and says nothing about a Return, because a `/compact`
+ * started before the delivery paints exactly the same line. Here the command IS
+ * the `/compact`, the session was idle before the keystroke, and the spinner
+ * appearing is the only thing that could have produced it.
+ *
+ * Kept apart from the two sets above because the phone reads those for its own
+ * question. A `/compact` is not a modal to be held until idle, and it is not a
+ * note to be slipped into a live turn; it is an ordinary submit whose receipt
+ * has to be read somewhere else.
+ */
+const NO_HOOK_WORK = new Set(["/compact"]);
+/**
+ * True when `text` submits and starts work that fires no hook — the HOST's
+ * third question, asked only by the submit ladder. Neither `isLocalCommand`
+ * (the phone's "is this a modal?") nor `startsNoTurn` (the host's "is there a
+ * turn to wait for at all?") answers it: there IS a turn's worth of work here,
+ * and nothing announces it.
+ */
+export function worksUnannounced(text) {
+    return NO_HOOK_WORK.has(text.trim().split(/\s+/)[0] ?? "");
+}
+/**
+ * `/fork [title]` — the one command the HOST answers instead of the CLI.
+ *
+ * **The fifth category, and the only one that is never typed.** From 2.1.291 a
+ * `/fork` typed into the TUI no longer forks in place: the CLI hands the branch
+ * to its OWN background daemon (`~/.claude/daemon.log`: `bg claimed-spare …
+ * (slash)`, a job under `~/.claude/jobs/`) and prints `⎿ session waiting ·
+ * <title>`. That session runs in no tmux this host owns, so the phone never
+ * lists it, and its `SessionStart` hook lands on `/api/hook` as an unknown
+ * session and is dropped — a fork asked for from the phone that the phone can
+ * never see. So the host intercepts it (`routes/session.ts`) and opens the fork
+ * itself, as a tab, through the same `sessions.fork()` the toolbar's *fork*
+ * button uses (`--resume <id> --fork-session`).
+ *
+ * Returns `null` when `text` is not a `/fork`, else the title argument — one
+ * line, whitespace collapsed, capped — and `""` when there is none. A command
+ * NAMED like it (`/forked`, `/fork-it`) is not it.
+ */
+export function slashForkTitle(text) {
+    const m = /^\/fork(?:\s+([\s\S]*))?$/.exec(text.trim());
+    if (!m)
+        return null;
+    return (m[1] ?? "").replace(/\s+/g, " ").trim().slice(0, 80);
+}
+//# sourceMappingURL=slash.js.map

package/node_modules/@waterplane/shared/dist/slash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slash.js","sourceRoot":"","sources":["../src/slash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC;IACzB,uEAAuE;IACvE,sEAAsE;IACtE,sEAAsE;IACtE,QAAQ,EAAE,OAAO,EAAE,QAAQ;IAC3B,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,gBAAgB;IAC1D,SAAS,EAAE,QAAQ,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,EAAE,iBAAiB;IAC9E,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,UAAU,EAAE,UAAU;IACnE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS;IAC/D,iBAAiB,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW;IAC1D,mBAAmB,EAAE,QAAQ,EAAE,SAAS;IACxC,2EAA2E;IAC3E,6EAA6E;IAC7E,yEAAyE;IACzE,6EAA6E;IAC7E,qDAAqD;IACrD,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,SAAS;IAC5E,UAAU,EAAE,OAAO,EAAE,OAAO;CAC7B,CAAC,CAAC;AAEH;kFACkF;AAClF,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC/C,OAAO,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,CAAC,GAAG,2BAA2B,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACxD,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC/D,CAAC"}

package/node_modules/@waterplane/shared/dist/sourceshape.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shape checks for what a 2.2 source slot answers (`backendsources.ts`: `mode`, `commands`,
+ * `tokens.session`, `context.compactions`, `SourceContextSample.window`). Pure, here so the
+ * host's consumers and the plugin testkit (`packages/plugin-testkit`, which imports shared's
+ * dist) judge an answer by ONE rule. Each returns sentences — empty = the answer may be used;
+ * a consumer that gets any drops the WHOLE answer to absent (absent beats wrong), never a
+ * clamped or partly-kept one. `null` is always fine: it is "cannot say".
+ */
+import type { PermissionMode } from "./wire/session.js";
+/** The most rows a `CommandSource.list` may answer; a longer list is refused whole. */
+export declare const SOURCE_COMMANDS_MAX = 200;
+/** The most compactions a `ContextSource.compactions` may answer; a longer list is refused whole. */
+export declare const SOURCE_COMPACTIONS_MAX = 300;
+/** A command name: a slash, then one word of at most 63 more characters (no space, no second slash first). */
+export declare const SOURCE_COMMAND_NAME_RE: RegExp;
+/** The longest `description` / `args` a command row may carry. */
+export declare const SOURCE_COMMAND_TEXT_MAX = 500;
+/** `ModeSource.current()`: one of the descriptor's `caps.permissionModes`, or null. */
+export declare function sourceModeProblem(m: unknown, modes: readonly PermissionMode[]): string | null;
+/** `CommandSource.list()`: at most `SOURCE_COMMANDS_MAX` rows, `/`-prefixed unique names, strings and a boolean. */
+export declare function sourceCommandsProblems(list: unknown): string[];
+/** `TokenSource.session()`: a stamp, then each stated figure finite and ≥ 0; `native` names its unit. */
+export declare function sourceSpendProblems(s: unknown): string[];
+/** `ContextSource.compactions()`: at most `SOURCE_COMPACTIONS_MAX`, oldest first, each stamped, stated fills finite and ≥ 0. */
+export declare function sourceCompactionsProblems(list: unknown): string[];
+/** `ContextSource.sample()`: a stamp and a fill; `window`, when stated, a positive whole number. */
+export declare function sourceContextSampleProblems(c: unknown): string[];