waterplane 0.0.1 → 0.1.11

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

@@ -0,0 +1,303 @@
+/**
+ * Settings that follow the USER, not the browser.
+ *
+ * Everything the app remembers has lived in localStorage, which was right for
+ * most of it — a send queue, a scroll watermark, a measured uplink rate all
+ * describe THIS device. But the same store also held the things the user
+ * AUTHORED: prompt templates (snippets), fan-out presets, header commands, the
+ * prompt pad, the toolbar layout, the default launch flags. Those are not
+ * properties of a browser, and keeping them there meant a phone, a desktop tab
+ * and the Android shell each had their own private copy — write a template on
+ * the phone and it does not exist anywhere else, reinstall the PWA and it is
+ * gone. There is exactly one host and it already persists far more valuable
+ * state, so that is where they belong.
+ *
+ * The design is deliberately dumb, because the alternative is a sync engine:
+ *
+ *  - **Opaque values.** The host stores the raw localStorage STRING per key and
+ *    never parses it. Shapes change with the client (`presets.ts`'s
+ *    `{ list, removed }` grew a field once already); a host that understood
+ *    them would have to be upgraded in lockstep with the UI it serves — which
+ *    it explicitly is not, since `webbundle.ts` lets the phone update its own
+ *    web bundle without touching the daemon.
+ *  - **Last write wins, per key, on a timestamp the WRITER stamps.** No
+ *    merging: two devices editing the same list concurrently is rare (one
+ *    person, one phone in hand) and a wrong merge of a prompt list is worse
+ *    than a lost edit that is still visible in the other client's UI until it
+ *    reloads. The pad is the one key whose CLIENT merges on adopt
+ *    (`shared/pad.ts`, per note, with tombstones): the host still stores a
+ *    string and still compares a `ts`, and this contract is unchanged.
+ *  - **An allow-list, not a mirror.** Syncing everything would drag the send
+ *    outbox, the paired host address and per-device cache state onto other
+ *    devices — the outbox especially, where a second device replaying another
+ *    device's queue is a prompt typed twice. Keys are opted IN, one at a time.
+ *
+ * The list below is the contract both ends check against, which is why it is
+ * here rather than in either package.
+ */
+import { lsKey } from "./brand.js";
+import { AGENT_LARGE_TOK } from "./sessioncost.js";
+/**
+ * The keys that follow the user.
+ *
+ * Every entry is content or a preference the user set ON PURPOSE and would be
+ * annoyed to re-create on another device. Anything describing the device, the
+ * link, or work in flight stays local — see the note below the list.
+ */
+export const SYNCED_SETTING_KEYS = [
+    /** Reusable prompt text the compose box appends — "prompt templates". */
+    lsKey("snippets"),
+    /** One-tap chips in the session header (`headerCmds.ts`). */
+    lsKey("headerCmds"),
+    /** Fan-out sweep presets (`presets.ts`). */
+    lsKey("fanout.presets"),
+    /** Terminal toolbar layout: order, hidden items, pinned header actions. */
+    lsKey("toolbar"),
+    /** Default launch flags (model / effort / permission mode) for new sessions. */
+    lsKey("launch"),
+    /**
+     * Ask which backend and model to run EVERY time a new session is started,
+     * instead of applying `<prefix>launch` silently.
+     *
+     * Synced beside the defaults it modifies, and for the same reason: "I want to
+     * be asked" is a statement about how this person works, not about the browser
+     * they happened to say it in. A phone that asked and a desktop tab that did
+     * not would make the same tap mean two different things.
+     */
+    lsKey("launchAsk"),
+    /**
+     * The spend warnings' thresholds (`spendwarn.ts`): orange and red as a share
+     * of the week, and in dollars where no week is calibrated. How much one
+     * session may spend before it is worth a mark is the person's budget, not a
+     * fact about the phone it was set on.
+     */
+    lsKey("spendWarn"),
+    /** The prompt pad — untargeted drafts, written on one device, sent from another. */
+    lsKey("pad"),
+    /** Repos hidden from the launcher list. */
+    lsKey("hiddenRepos"),
+    /** Enter submits vs. inserts a newline. */
+    lsKey("enterSends"),
+    /**
+     * The person's dictation vocabulary (`dictateterms.ts`) — words the
+     * transcriber keeps getting wrong. Unlike the dictation LANGUAGE, which is a
+     * fact about the phone being spoken into, this is a fact about the person's
+     * work: `BA3` is misheard the same way on every device they carry.
+     */
+    lsKey("dictate.terms"),
+    /** Drain the send queue automatically when the link returns. */
+    lsKey("autoSend"),
+    /** Check for waterplane and plugin updates once a day (a read; nothing applies itself). Default on. `host/updates/checker.ts` reads it. */
+    lsKey("updates.autoCheck"),
+    /**
+     * Run queued session-opens for one repo ONE AT A TIME rather than all at once
+     * (`shared/queue.ts`'s `serial`). A statement about how the person wants their
+     * account's usage spent and their repo edited, which is the same wherever they
+     * queue the work from — the phone that wrote the queue is rarely the device
+     * that watches it drain.
+     */
+    lsKey("serialSessions"),
+    /** Ask before draining text that was queued offline. */
+    lsKey("confirmQueue"),
+    /** Ask before closing a session with uncommitted or unmerged work. Default on. */
+    lsKey("confirmClose"),
+    /**
+     * Reader view: how much of a tool call is shown, and how much of it is even
+     * downloaded (`web/transcriptUtil.ts`). A preference about reading, which is
+     * the same on every device the same person reads on.
+     */
+    lsKey("readerTools"),
+    /**
+     * The image annotator moves, sizes and turns a mark by KNOBS on strings
+     * instead of by relative drag (`web/annKnobs.ts`). A way of pointing this
+     * person chose on purpose and asked to have remembered; the annotator opens on
+     * whichever device the picture happens to be on, and flipping it back every
+     * time is the annoyance. Relative drag stays what a new person starts on.
+     */
+    lsKey("annKnobs"),
+    /**
+     * The image annotator's toolbar as the person arranged it — which controls
+     * show, their order, rail or row (`web/annLayout.ts`). Authored, like the
+     * terminal toolbar's layout above, and for the same reason.
+     */
+    lsKey("annTools"),
+    /**
+     * Button hints: the mode, and which explanations have been dismissed
+     * (`web/hints.ts`). Synced because the whole point of dismissing one is not
+     * being told again — being re-taught on the desktop what you already read on
+     * the phone is the annoyance the feature exists to remove.
+     */
+    lsKey("hints"),
+    /**
+     * Which ring the per-repo identity colours come from, and every hue a person
+     * pinned over it (`shared/repocolor.ts`).
+     *
+     * Synced, unlike `<prefix>theme` two rules below — and the two look alike enough
+     * that the difference is worth stating. The theme is a fact about the DEVICE
+     * (a phone in a dark bedroom, a desktop under a window). Which colour a repo
+     * is, is a fact about the PERSON: it is the thing they use to recognise a
+     * group header at a glance and a tab at 85 px, and having it be one colour on
+     * the phone and another on the desktop would cost exactly the recognition the
+     * colour exists for.
+     */
+    lsKey("repoColors"),
+    /**
+     * Which apps a build downloaded from the desktop may install by itself
+     * (`web/installPolicy.ts`, mirrored into the Android shell).
+     *
+     * Synced for the same reason `<prefix>repoColors` is: it is a fact about the
+     * PERSON and their own apps — "Tiptoi and TalkingPictures are mine, put the
+     * new build on without asking" is the same answer on every phone they carry,
+     * and a second phone that had to be taught it again would be asked the one
+     * question this feature exists to stop asking.
+     *
+     * It grants nothing by itself. The phone's own "install unknown apps" access
+     * is per DEVICE and is not synced, cannot be, and is the thing that actually
+     * decides whether anything installs.
+     */
+    lsKey("installAllow"),
+    /**
+     * Close an AUTOMATIC session (`backlog · <repo> · <label>`, the one a fired
+     * item opens) once its work is done and it has lingered — `"1"` on, anything
+     * else (and absent) OFF. Read by the HOST, which is why it is a constant
+     * below rather than only a localStorage name: `closeWhenDoneSetting` is the
+     * one parse. An item's own `Intent.closeWhenDone` overrides it either way.
+     *
+     * Synced because it is a statement about how the person works — "leave what
+     * the machine did open until I have looked at it" — and the desktop is the
+     * one place it acts, whichever device said it.
+     */
+    lsKey("backlog.closeWhenDone"),
+    /**
+     * How many LOCAL-model coding sessions may be working at once on this
+     * desktop (`LOCAL_SESSIONS_KEY`, read by the HOST — `localSessionsSetting` is
+     * the one parse). A whole number; `"0"` is no cap; absent is the desktop's
+     * own default (`WATERPLANE_LOCAL_SESSIONS`, else 1). Synced because the cap
+     * acts on the desktop whichever device set it.
+     */
+    lsKey("local.maxSessions"),
+    /**
+     * The parallel-agent marks (`web/agentCount.ts`): above `warn` the strip's
+     * count turns amber, above `alarm` red, each rise one toast. Synced: how many
+     * agents at once is "too many" is the person's answer about their own desktop
+     * and account, not a fact about the phone it was set on.
+     */
+    lsKey("agentWarn"),
+    /**
+     * The context size, in tokens, at which a RUNNING subagent is called large
+     * (`AGENT_WINDOW_WARN_KEY`, `agentWindowWarnSetting` the one parse): the
+     * context sheet's line and the host's one push per agent. Synced because the
+     * host pushes on it whichever device set it.
+     */
+    lsKey("agentWindowWarn"),
+    /**
+     * The session-tab strip's order and its open history, SHARED — read in place
+     * of the per-device pair (`sessionTabs.order`, `sessionTabs.opens`) while a
+     * device has "sync tab order" on (`web/sessionTabs.ts`; the default). The
+     * owner asked for the strip to read the same on the phone and the desktop:
+     * "last opened first" answers "where was I", and that is the same answer
+     * whichever screen you were last on. The per-device pair stays, untouched,
+     * for a device switched off. The opens are merged on adopt, never
+     * last-write-wins — two devices bump different sessions at once.
+     */
+    lsKey("tabsShared.order"),
+    lsKey("tabsShared.opens"),
+];
+/** The synced key the host reads for the local-model session cap. */
+export const LOCAL_SESSIONS_KEY = lsKey("local.maxSessions");
+/** The biggest cap a person may type; anything above is "no cap" in practice. */
+export const LOCAL_SESSIONS_MAX = 16;
+/**
+ * The local-model cap off its raw string: a whole number 1..16 is that cap,
+ * `"0"` is NO cap (`null`), and absent, empty or garbage is `fallback` — the
+ * desktop's own default, never a guessed number.
+ */
+export function localSessionsSetting(raw, fallback) {
+    const v = (raw ?? "").trim();
+    if (!/^\d{1,2}$/.test(v))
+        return fallback;
+    const n = Number(v);
+    if (n === 0)
+        return null;
+    return n <= LOCAL_SESSIONS_MAX ? n : fallback;
+}
+/** The synced key the host and the phone read for the large-subagent line. */
+export const AGENT_WINDOW_WARN_KEY = lsKey("agentWindowWarn");
+/** The smallest and largest line a person may set, in tokens. */
+export const AGENT_WINDOW_WARN_MIN = 50_000;
+export const AGENT_WINDOW_WARN_MAX = 2_000_000;
+/**
+ * The large-subagent line off its raw synced string: a positive whole number
+ * of tokens within [50k, 2M] is that line; absent, empty, fractional, out of
+ * range or garbage is `AGENT_LARGE_TOK` — the default, never a guessed number.
+ */
+export function agentWindowWarnSetting(raw) {
+    const v = (raw ?? "").trim();
+    if (!/^\d{1,7}$/.test(v))
+        return AGENT_LARGE_TOK;
+    const n = Number(v);
+    return n >= AGENT_WINDOW_WARN_MIN && n <= AGENT_WINDOW_WARN_MAX ? n : AGENT_LARGE_TOK;
+}
+/** The synced key the host reads for the global close-when-done default. */
+export const CLOSE_WHEN_DONE_KEY = lsKey("backlog.closeWhenDone");
+/**
+ * The global *close automatic sessions when done* default, off the raw synced
+ * string. `"1"`/`"true"` is on (the client's flag spelling); absent, empty or
+ * anything else is OFF — the default the person chose: nothing closes a
+ * session they did not ask to have closed.
+ */
+export function closeWhenDoneSetting(raw) {
+    return raw === "1" || raw === "true";
+}
+/**
+ * Why the obvious candidates are NOT in the list above — kept as prose because
+ * the next person to add a key will ask exactly this.
+ *
+ *  - `<prefix>outbox` / `<prefix>compose.*` / `<prefix>deadUploads` — work in flight.
+ *    Replaying another device's queue types the same prompt twice; the ack
+ *    ledger de-dupes a RETRY of the same ackId, not a second device deciding to
+ *    send someone else's entry.
+ *  - `<prefix>hostBase`, `<prefix>deviceId` — what makes this device this device.
+ *  - `<prefix>dataSaver`, `<prefix>uploadScale`, `<prefix>upKbps` — properties of the
+ *    LINK. A phone on a DERP-relayed 5G path and a desktop on the LAN want
+ *    opposite answers, and copying one over the other makes the bad link worse.
+ *  - `<prefix>theme` — light, dark, or follow the OS (`web/theme.ts`). The one
+ *    that looks most like a fact about the PERSON and is not: the phone is held
+ *    in a dark bedroom and the desktop sits under an office window, the two
+ *    panels are different, and "dark on OLED" is a battery decision about one
+ *    of them. `system` — the DEFAULT — already carries the per-person answer,
+ *    since each OS is told the same thing by the same person; what an explicit
+ *    pick overrides is THIS device's OS, which is a fact about this device.
+ *    There is a second reason, learned while building it. Every synced key is
+ *    last-write-wins on a CLIENT-SUPPLIED timestamp, and a client that reports
+ *    a wrong clock parks that key for as long as the skew lasts: nothing ever
+ *    lowers a stored `ts`, so every later pick loses to it and is echoed back
+ *    undone. For the pad or the toolbar that risk buys a feature worth having.
+ *    For a setting whose whole job is one tap that changes what you are looking
+ *    at, a failure mode where the tap silently reverts is worse than not
+ *    syncing at all.
+ *  - `<prefix>netPulse` — the permanent connection strip (`web/netpulse.ts`). It
+ *    looks like a display preference, but switching it on spends THIS device's
+ *    radio on an extra ping every three seconds and THIS device's screen on
+ *    22 px: exactly the trade a phone on a bad tunnel wants to make and a
+ *    desktop on the LAN does not. Same reason as the row above.
+ *  - `<prefix>snap.*`, `<prefix>slashCache`, `<prefix>artMarks`, `<prefix>trSeen.*`,
+ *    `<prefix>pull.state`, `<prefix>netlog` — caches and per-device reading
+ *    positions, all re-derivable and all bigger than they look.
+ *  - `<prefix>dismiss*`, `<prefix>lastForcedReload`, `<prefix>webUpdate.*` — this
+ *    browser's own history with its own banners.
+ */
+/** Cheap membership test that also narrows the type. */
+export function isSyncedKey(key) {
+    return SYNCED_SETTING_KEYS.includes(key);
+}
+/**
+ * Per-value cap, sized ABOVE what the client's own caps can produce: a full
+ * preset list is 80 items × 8000 chars ≈ 640 KB, and a value the host refuses
+ * is the worst outcome available — the two ends then disagree with nothing on
+ * screen saying so. Anything past this is a client bug, not a big list.
+ */
+export const MAX_SETTING_BYTES = 1024 * 1024;
+/** Whole-document cap, so a misbehaving client cannot grow the file forever. */
+export const MAX_SETTINGS_BYTES = 4 * 1024 * 1024;
+//# sourceMappingURL=settings.js.map

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

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

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

@@ -0,0 +1,140 @@
+/**
+ * What a background shell is DOING, in words — the pure half of the "shells"
+ * feature (host reader: `packages/host/src/shells.ts`).
+ *
+ * A `SessionShell` is three raw readings (`cpuMs`/`cpuMovedAt`, `outputAt`,
+ * `workers`) and this file is what turns them into a bucket and a sentence,
+ * the same way `clihealth.ts` turns a run of misses into a rollup. Nothing
+ * here reads a clock of its own — `now` is always a parameter — so the phone
+ * and any test can pin a bucket without a live process to poll.
+ *
+ * The vocabulary is deliberately never "hung"/"stuck"/"dead" (CLAUDE.md): a
+ * shell that has been quiet for a day may be exactly what was asked for (an
+ * emulator, a dev server) or may be a loop that can never end on its own
+ * (`selfMatchOf`) — in neither case does this app know it is BROKEN, only
+ * that it is quiet, and the words say only that.
+ */
+import type { SessionShell } from "./wire/session.js";
+/** 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 declare const SHELL_QUIET_MS: number;
+/**
+ * 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 declare function shellBucket(sh: SessionShell, now: number, quietMs?: number): "working" | "waiting" | "quiet" | "unknown";
+/**
+ * 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 declare function selfMatchOf(command: string): boolean;
+/** The literal pattern `selfMatchOf` found, for the sentence that names it.
+ *  Null exactly when `selfMatchOf` is false. */
+export declare function selfMatchPattern(command: string): string | null;
+export declare function serverLikeOf(command: string): boolean;
+/**
+ * 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 declare function shellWords(sh: SessionShell, now: number): string;
+export interface ShellsSummary {
+    working: number;
+    waiting: number;
+    quiet: number;
+    unknown: number;
+    /** Wrappers that are the running turn's OWN command, not background shells
+     *  at all — never folded into the four buckets above or into `total`,
+     *  which is a count of background shells only. */
+    foreground: number;
+    total: number;
+}
+/** 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 declare function shellsSummary(list: SessionShell[], now: number, quietMs?: number): ShellsSummary;
+/** "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 declare function shellsChipText(s: ShellsSummary): string;
+/**
+ * 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 declare function shellCloseWords(summary: ShellsSummary, list: SessionShell[]): string;
+/**
+ * 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 declare function glueCompanions<T extends {
+    id: string;
+    companionOf?: string;
+}>(list: readonly T[]): T[];
+/**
+ * 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 declare function companionToggle<T extends {
+    id: string;
+    companionOf?: string;
+    createdAt?: number;
+}>(active: T, list: readonly T[]): {
+    target: T;
+    to: "cli" | "shell";
+} | null;