waterplane 0.0.1 → 0.1.6

package/node_modules/@waterplane/shared/dist/wire/transcript.d.ts

@@ -0,0 +1,327 @@
+/** The reader view's document — the CLI's own conversation log, parsed. */
+/**
+ * ── Structured transcript (the "reader" view of a conversation) ───────
+ *
+ * Parsed from the claude CLI's OWN conversation log
+ * (`~/.claude/projects/<slug>/<conversation-uuid>.jsonl`) — NOT from PTY text.
+ * That's what makes this view exact where the terminal is approximate: real
+ * message boundaries, real tool names/inputs/results, no ANSI, no re-wrapping.
+ * The phone renders it as normal DOM, so scrolling/selection/find/links behave
+ * like a web page instead of a terminal grid.
+ */
+export type TranscriptBlock = 
+/** Assistant prose (markdown source, rendered client-side). */
+{
+    kind: "text";
+    text: string;
+}
+/** Extended-thinking block — collapsed by default in the UI. */
+ | {
+    kind: "thinking";
+    text: string;
+}
+/**
+ * TERMINAL TEXT — what the CLI printed on its own screen, ANSI-stripped.
+ *
+ * The reader's whole premise is that the conversation log is the exact
+ * record, and for everything the model says it is. A TUI-local command is the
+ * hole in that premise: `/btw`, `/goal`, `/usage` and friends are answered by
+ * the CLI itself, so either the log holds only their `<local-command-stdout>`
+ * envelope (which the parser used to drop as plumbing) or — for the ones the
+ * CLI never writes down at all — nothing. Read mode therefore showed a
+ * conversation with the command and its answer simply missing, while the
+ * terminal one tab away showed both.
+ *
+ * Rendered MONOSPACE and never as markdown: this is screen text, complete
+ * with box drawing and hint rows, and running it through a markdown renderer
+ * turns a `*` into emphasis and a table into soup.
+ */
+ | {
+    kind: "screen";
+    text: string;
+    /**
+     * The CLI drew this inside a panel it could SCROLL, so `text` is the rows
+     * that were painted and not the whole answer.
+     *
+     * A PTY capture is a replay of painted cells (host `render.ts`), and a TUI
+     * paints only the slice of a panel that is on screen — so what sat below
+     * the fold is in no record at all: not here, not in the scrollback, not in
+     * the conversation log the command never reached. It exists only inside
+     * the live CLI process, and only while that panel is still open.
+     *
+     * Set off the CLI's own "↑/↓ to scroll" footer, which is chrome the parser
+     * strips — so this is the one piece of that furniture kept as EVIDENCE.
+     * It says the panel was scrollable, not that text was definitely lost: the
+     * footer is printed whether or not the content overflowed. The reader
+     * words it that way.
+     */
+    scrollable?: boolean;
+}
+/** A tool call plus (when it came back) its result. */
+ | {
+    kind: "tool";
+    /** tool_use id — how the result is matched back to the call. */
+    id: string;
+    /** Tool name as the model called it (Bash, Edit, Task, …). */
+    name: string;
+    /** One-line gist of the input (the command, the file, the query). */
+    label: string;
+    /** Pretty-printed input, truncated. Absent in a `lite` document — see `omitted`. */
+    input?: string;
+    /** Tool output, truncated (see `resultTruncated`). Absent = still running / no
+     *  result recorded, OR withheld by a `lite` document — see `omitted`. */
+    result?: string;
+    /** False when the tool reported an error. Also the "a result came back at all"
+     *  signal a `lite` block has left: it is set exactly when a tool_result was
+     *  matched back, whether or not the text travelled with it. */
+    ok?: boolean;
+    resultTruncated?: boolean;
+    /**
+     * The call's input/result were deliberately LEFT OUT of this document, not
+     * missing from the log. Set on every tool block of a `lite` transcript —
+     * which is the default, because those two strings are ~95% of a busy
+     * conversation's bytes and almost none of what someone reads on a phone.
+     * The reader shows a placeholder and fetches the pair on demand
+     * (`GET /api/transcript/tools`). Never set in a `detail=full` document.
+     */
+    omitted?: boolean;
+};
+/** One user prompt and everything the assistant did in response. */
+export interface TranscriptTurn {
+    /** Stable id (the conversation-log uuid of the prompt record). */
+    id: string;
+    /**
+     * This turn is not a prompt somebody typed.
+     *
+     * `"compaction"` is opencode's own record of a conversation being compacted —
+     * a user-role row with no prompt text at all (measured: exactly the 43 rows
+     * that carry a compaction part are exactly the 43 user rows with no text).
+     * The reader draws a labelled divider for it. Without the marker those turns
+     * would render as prompts somebody sent and left blank, which is a claim
+     * about a person rather than about the tool.
+     */
+    marker?: "compaction";
+    /** 1-based turn number, for the outline. */
+    n: number;
+    /** Full prompt text. */
+    prompt: string;
+    /** Single-line, truncated prompt — the outline label. */
+    promptLabel: string;
+    /** ms epoch of the prompt / of the last record in the turn. */
+    sentAt?: number;
+    endedAt?: number;
+    blocks: TranscriptBlock[];
+    /** Heuristic one-liner from the turn's final assistant text (no AI call). */
+    summary?: string;
+    toolCount: number;
+    /** Unique repo-relative paths the turn wrote to (Edit/Write/NotebookEdit). */
+    files: string[];
+    /** Number of sub-agent (sidechain) records this turn produced. */
+    sidechains: number;
+    /**
+     * This turn is a command the CLI answered ITSELF — no model call, no turn in
+     * the usual sense — and where its text was recovered from.
+     *
+     * `"log"`: the conversation log wrote the `<command-name>`/`<command-args>`
+     * envelope and a `<local-command-stdout>` beside it, so the words are exact.
+     * `"screen"`: the log holds nothing at all (`/btw` is the measured case) and
+     * this was rebuilt from the PTY capture waterplane keeps per turn — approximate by
+     * construction, which is why it says so on the row rather than passing for a
+     * log record.
+     */
+    local?: "log" | "screen";
+    /**
+     * **Sent, and the CLI has not taken it yet.**
+     *
+     * A prompt typed into a session that is mid-turn is HELD by the TUI until the
+     * turn ends — it sits in the composer, visibly accepted, and the conversation
+     * log gets nothing until the CLI actually starts it (measured: a prompt sent
+     * at 09:57 reached the log at 10:04, behind a 131-tool turn). Every reader
+     * here is built on that log, so for those minutes the outline was missing the
+     * newest thing the person had sent and looked simply wrong — reported as "the
+     * last thing I sent is being worked on but does not show in the list".
+     *
+     * So the row is drawn from what waterplane itself delivered (`HistoryEntry`), and
+     * it says exactly that much: these words went in, nothing has started them.
+     * It carries no blocks, no tools and no summary, because there is no turn yet
+     * — the moment the log takes the prompt, the logged turn replaces it.
+     */
+    queued?: true;
+    /**
+     * **The CLI took these words into the turn that was already running.**
+     *
+     * The other half of `queued`. A prompt typed into a busy session is held by
+     * the TUI, and when the turn ends the CLI normally starts it as a turn of its
+     * own — a `user` record in the log, which every reader here is built on. But
+     * it may instead ABSORB it into the running turn, and then it writes no
+     * `user` record at all: the prompt exists in the log only as an `attachment`
+     * of type `queued_command`, and the answer to it is appended to the turn
+     * above.
+     *
+     * Measured on this desktop over seven days: 48 of 62 real queued prompts were
+     * recorded that way and no other. The reader therefore drew no turn for them,
+     * folded their answer into the previous prompt's turn, and — because nothing
+     * in the log ever matched those words — left waterplane's own `queued` row saying
+     * *the CLI has not started it yet* for ever, sorted BELOW the answer it had
+     * already given. The report was "read mode misses the last output of the CLI",
+     * and it was not the output that was missing: it was the boundary.
+     *
+     * So the attachment opens a turn, and this flag is what the row says about
+     * it — the words went in mid-turn, so the assistant text above may be
+     * answering the previous prompt as well. Exact, not approximate: the words
+     * and the instant are the CLI's own record of them.
+     */
+    absorbed?: true;
+    /**
+     * **What this turn's own requests would have cost, at list prices (USD).**
+     *
+     * Every main-thread assistant request between this prompt and the next,
+     * deduped by `message.id` and priced on its own model and day — the rule
+     * `ctxlog.ts` prices the session by, so these sum to the same accounting.
+     * Subagents are NOT in it (their logs are separate files; `sidechains` says
+     * whether there were any). Absent when the turn ran no request, and absent —
+     * never a partial sum — when any of its requests ran on an unpriced model.
+     */
+    costUsd?: number;
+    /**
+     * **The conversation's running total by the end of this turn**, same
+     * accounting as `costUsd`. Absent when the log was tail-read (the start of
+     * the conversation is not in hand, so any sum is short) and from the first
+     * unpriced request on.
+     */
+    cumCostUsd?: number;
+    /**
+     * **Context the turn's last request carried** — input + cache read + cache
+     * write, the number the window gauge measures. Tokens, not a percentage: the
+     * window is not in the log, and a guessed one would be a wrong number.
+     */
+    ctxTok?: number;
+    /**
+     * **This turn's own requests, by token kind** — the split behind `costUsd`,
+     * summed over the same deduped records (so a dollar figure is never printed
+     * without the four numbers it was priced from). `cacheWrite` is both tiers.
+     * Subagents are not in it, as they are not in `costUsd`. Absent when the
+     * turn ran no request; never zeros for "not measured".
+     */
+    tokens?: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+    /**
+     * **Which models this turn's own requests ran on**, by the alias
+     * (`normalizeModel`), in first-seen order. `tok` is all four kinds; `costUsd`
+     * is absent for a model with no published rate. Same records as `costUsd`,
+     * so the parts sum to it. Absent when the turn ran no request.
+     */
+    models?: {
+        id: string;
+        tok: number;
+        costUsd?: number;
+    }[];
+    /**
+     * **The subagents this turn STARTED, counted by kind** — each `Task`/`Agent`
+     * tool call's `subagent_type`, off the call itself (so exact even when the
+     * reader's document is `lite`). `"(no type)"` when the call named none.
+     * What they spent is `agentCostUsd`, never folded into `costUsd`.
+     */
+    agentTypes?: {
+        type: string;
+        n: number;
+    }[];
+    /**
+     * **What the subagents this turn started have spent SO FAR** — their own logs,
+     * nested agents included, priced per record (`turnagents.ts`, the same
+     * ledger as the header's total). Kept apart from `costUsd`, which stays this
+     * conversation's own requests. Absent when the turn started none that spent
+     * anything, or when the agent directory could not be read.
+     */
+    agentCostUsd?: number;
+    /** Agent tokens on a model with no published rate — in no dollar figure. */
+    agentUnpricedTok?: number;
+    /** The same spend by model alias, so the turn's bar can show who spent it. */
+    agentModels?: {
+        id: string;
+        tok: number;
+        costUsd?: number;
+    }[];
+    /**
+     * **How many of this turn's subagents are still running.** A background
+     * agent's call returns at once, so a turn looks finished long before its
+     * agents are, and `agentCostUsd` is then a floor. Absent = none running.
+     */
+    agentsRunning?: number;
+    /**
+     * The subagents' spend through this turn, running — `cumCostUsd`'s twin, so
+     * the two added are the header's session total. Absent whenever
+     * `cumCostUsd` is, and whenever any agent could not be placed on a turn.
+     */
+    cumAgentCostUsd?: number;
+}
+/** A whole conversation, ready to render. */
+export interface TranscriptDoc {
+    /** waterplane session id this was fetched for. */
+    sessionId: string;
+    /** claude conversation uuid (absent for the history fallback). */
+    claudeSessionId?: string;
+    /** "jsonl" = the CLI's own log (exact). "history" = fallback built from the
+     *  recorded prompt + ANSI-stripped PTY capture (approximate; used when the
+     *  conversation log isn't available yet, e.g. a stub binary). */
+    /**
+     * Where the document came from. `"store"` is EXACT, like `"jsonl"` — it is
+     * the backend's own dated record, read out of its store by the store reader
+     * the backend names (`PluginStoreReader`; it was spelt `"opencode"` while
+     * opencode's was the only one). Only `"history"` is
+     * approximate, and it is the one every client already special-cases, so an
+     * older phone treats an unknown source as exact, which is correct.
+     *
+     * `"backend"` is a backend's own `TranscriptSource` (a plugin's fold of its
+     * CLI's event log) for a backend with no core reader — exact for the same
+     * reason, and additive for the same reason.
+     */
+    source: "jsonl" | "history" | "store" | "backend";
+    turns: TranscriptTurn[];
+    /** True when the log was too big and only its tail was parsed. */
+    truncated: boolean;
+    /** Size of the source log in bytes (0 for the history fallback). */
+    bytes: number;
+    /** ms epoch of the log's last modification (so the client can poll cheaply). */
+    updatedAt: number;
+    /**
+     * How much of each tool call travelled. `"lite"` (the default the reader asks
+     * for) carries names, labels and ok/error but NOT inputs or results — see
+     * `omitted` on the tool block. `"full"` is the whole thing, for a caller that
+     * genuinely wants every byte. Absent on documents from an older host, which
+     * read as full — the fields are simply present.
+     */
+    detail?: "lite" | "full";
+}
+/** The two strings a `lite` tool block left behind, fetched on demand and keyed
+ *  by the tool_use id so a merge back into the document cannot mis-align. */
+export interface TranscriptToolDetail {
+    input?: string;
+    result?: string;
+    ok?: boolean;
+    resultTruncated?: boolean;
+}
+/**
+ * The reader's document as plain text — what the phone's select/copy sheet
+ * shows when no terminal is mounted.
+ *
+ * The xterm is UNMOUNTED in reader view, so the grid dump the sheet was built
+ * on (`TerminalHandle.getText()`) returns "" there and the sheet opened empty,
+ * looking like a broken button. That is also what you hit with the link down,
+ * because offline is precisely when you are reading the cached transcript
+ * rather than watching a live grid.
+ *
+ * It lives here, beside the types, rather than in the web package: it is a pure
+ * function of the wire document, and everything in `packages/web/src` that
+ * would host it imports `localStorage` helpers, which is what stops it being
+ * runnable under `node --test`.
+ *
+ * Tool inputs and results are usually absent — the reader asks for a `lite`
+ * document, whose tool blocks carry name + label only (see `omitted` above).
+ * The label is then all there is to copy, which is also all the reader shows.
+ */
+export declare function transcriptText(doc: TranscriptDoc): string;

package/node_modules/@waterplane/shared/dist/wire/transcript.js

@@ -0,0 +1,60 @@
+/** The reader view's document — the CLI's own conversation log, parsed. */
+/**
+ * The reader's document as plain text — what the phone's select/copy sheet
+ * shows when no terminal is mounted.
+ *
+ * The xterm is UNMOUNTED in reader view, so the grid dump the sheet was built
+ * on (`TerminalHandle.getText()`) returns "" there and the sheet opened empty,
+ * looking like a broken button. That is also what you hit with the link down,
+ * because offline is precisely when you are reading the cached transcript
+ * rather than watching a live grid.
+ *
+ * It lives here, beside the types, rather than in the web package: it is a pure
+ * function of the wire document, and everything in `packages/web/src` that
+ * would host it imports `localStorage` helpers, which is what stops it being
+ * runnable under `node --test`.
+ *
+ * Tool inputs and results are usually absent — the reader asks for a `lite`
+ * document, whose tool blocks carry name + label only (see `omitted` above).
+ * The label is then all there is to copy, which is also all the reader shows.
+ */
+export function transcriptText(doc) {
+    const indent = (t) => t.split("\n").map((l) => `    ${l}`).join("\n");
+    const clock = (ts) => ts ? new Date(ts).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" }) : "";
+    const out = [];
+    for (const turn of doc.turns) {
+        const when = clock(turn.sentAt);
+        out.push(`\u2500\u2500 #${turn.n}${when ? ` \u00b7 ${when}` : ""} \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
+        if (turn.prompt.trim()) {
+            out.push(turn.prompt.trim().split("\n").map((l) => `> ${l}`).join("\n"));
+        }
+        for (const b of turn.blocks) {
+            if (b.kind === "screen") {
+                if (!b.text.trim())
+                    continue;
+                out.push("", indent(b.text.trimEnd()));
+                continue;
+            }
+            if (b.kind === "text" || b.kind === "thinking") {
+                if (!b.text.trim())
+                    continue;
+                out.push("", b.kind === "thinking" ? `[thinking]\n${indent(b.text.trim())}` : b.text.trim());
+                continue;
+            }
+            out.push("", `[${b.name}]${b.label ? ` ${b.label}` : ""}${b.ok === false ? " \u2014 FAILED" : ""}`);
+            if (b.input)
+                out.push(indent(b.input));
+            if (b.result)
+                out.push(indent(b.result + (b.resultTruncated ? "\n\u2026(truncated)" : "")));
+            else if (b.omitted)
+                out.push("    (input and result not loaded \u2014 open the call in the reader first)");
+        }
+        out.push("");
+    }
+    // A document with no renderable content must come back as "" and not as a
+    // string of separators: the caller uses the empty string to decide whether to
+    // show its own "nothing cached yet" explanation instead.
+    const text = out.join("\n").replace(/\n{3,}/g, "\n\n").trim();
+    return /[^\s\u2500]/.test(text) ? text : "";
+}
+//# sourceMappingURL=transcript.js.map

package/node_modules/@waterplane/shared/dist/wire/transcript.js.map

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

package/node_modules/@waterplane/shared/dist/wire/updates.d.ts

@@ -0,0 +1,130 @@
+/**
+ * The updates view's DTOs: waterplane itself plus plugins from the waterplane org.
+ * Mirrors `UpdateInfo` (wire/repo.ts) for naming. Every optional field absent means the
+ * host did not say — never a guess. Nothing here applies itself: a check is a read.
+ */
+import type { PluginMaturityLevel } from "../pluginmaturity.js";
+export type SelfUpdateMode = "tarball" | "npm" | "checkout" | "unknown";
+/** What a plugin is installed as. `local` = put there by hand: shown, never updated by the manager. */
+export interface InstalledPlugin {
+    id: string;
+    version: string;
+    source: "manager" | "local";
+    /** The tag or branch the manager cloned. Absent on `local`. */
+    ref?: string;
+    commit?: string;
+    dir: string;
+}
+export interface CatalogLatest {
+    kind: "tag" | "branch";
+    ref: string;
+    commit?: string;
+    /** Release notes, display-only. */
+    notes?: string;
+}
+export interface CatalogEntry {
+    /** `owner/name` on GitHub. */
+    repo: string;
+    url: string;
+    name: string;
+    description: string;
+    maturity: PluginMaturityLevel;
+    /** null = nothing installable was found; see `problems`. */
+    latest: CatalogLatest | null;
+    installed: InstalledPlugin | null;
+    /**
+     * True only when `url` is on github.com under the `BRAND.githubOrg` org (judged by URL host plus
+     * org, never by the `repo` label). "from waterplane-dev" is shown only when this is true.
+     */
+    fromOrg: boolean;
+    /** Refusals in words: no manifest, has dependencies, apiVersion too new, id clash. */
+    problems: string[];
+}
+export interface SelfUpdateInfo {
+    mode: SelfUpdateMode;
+    current: string;
+    latest?: string;
+    notes?: string;
+    /** True only for a tarball install, where the verifying updater can run. */
+    canApply: boolean;
+    /** The exact command for npm/checkout installs. */
+    command?: string;
+    /** Why there is no button, in words. */
+    why?: string;
+    /** The version a roll-back would return to. */
+    rollbackTo?: string;
+    /** Receipt of the last apply/rollback, verbatim, kept across a restart. */
+    lastResult?: {
+        ok: boolean;
+        message: string;
+        at: number;
+    };
+}
+export interface UpdatesStatus {
+    self: SelfUpdateInfo;
+    catalog: CatalogEntry[];
+    /** ms since epoch of the last check; absent = never checked. */
+    checkedAt?: number;
+    /** The last check's failure as a sentence. */
+    error?: string;
+    autoCheck: boolean;
+    /** ms since epoch before which "check now" answers from the cache (10 min after an ok check, 30 s after a failed one); absent = a check is allowed now. */
+    nextCheckAt?: number;
+    /** The last apply (install, update, self, restart), verbatim; absent = none yet. */
+    lastApply?: UpdatesLastApply;
+}
+export type UpdatesTarget = {
+    kind: "self";
+} | {
+    kind: "self-rollback";
+} | {
+    kind: "plugin-install";
+    repo?: string;
+    url?: string;
+} | {
+    kind: "plugin-update";
+    id: string;
+}
+/** Restart this desktop's host (after a plugin update). Refused in words when nothing would start it again. */
+ | {
+    kind: "restart";
+};
+/**
+ * What an apply leaves to do.
+ *  - `restarting`: the host is restarting ITSELF now (self update, self rollback, the restart target);
+ *    the link drops and comes back.
+ *  - `offer`: a plugin update that needs a restart the host can do on request (`{kind:"restart"}`).
+ *  - `manual`: a person must restart the desktop (nothing supervises it).
+ *  - `none`: nothing to restart.
+ */
+export type UpdatesRestart = "restarting" | "offer" | "manual" | "none";
+/** The last apply of any kind, kept across a dropped link and a restart: what a reconnecting phone reads. */
+export interface UpdatesLastApply {
+    target: UpdatesTarget;
+    ok: boolean;
+    message: string;
+    restart: UpdatesRestart;
+    at: number;
+}
+/** One row of the updates view that counts as "an update". */
+export type UpdateDue = {
+    kind: "self";
+    current: string;
+    latest: string;
+} | {
+    kind: "plugin";
+    id: string;
+    repo: string;
+    from: string | undefined;
+    to: string;
+};
+/** True only when `b` is known to be newer than `a`; unparseable versions are never "newer". */
+export declare function newerVersion(a: string, b: string): boolean;
+/**
+ * THE bucketing function: which rows count as "an update". The count on the control and the list it
+ * opens both come from this, never two copies of the edge.
+ *  - self: `latest` newer than `current` AND (the button can apply it OR a command is given);
+ *  - plugin: manager-installed only (`local` is managed by the person), with a newer tag, or a
+ *    branch whose head commit is known on both sides and differs.
+ */
+export declare function updatesDue(status: Pick<UpdatesStatus, "self" | "catalog"> | null | undefined): UpdateDue[];

package/node_modules/@waterplane/shared/dist/wire/updates.js

@@ -0,0 +1,52 @@
+/**
+ * The updates view's DTOs: waterplane itself plus plugins from the waterplane org.
+ * Mirrors `UpdateInfo` (wire/repo.ts) for naming. Every optional field absent means the
+ * host did not say — never a guess. Nothing here applies itself: a check is a read.
+ */
+function ver(s) {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(s ?? "");
+    return m ? [+m[1], +m[2], +m[3]] : null;
+}
+/** True only when `b` is known to be newer than `a`; unparseable versions are never "newer". */
+export function newerVersion(a, b) {
+    const x = ver(a), y = ver(b);
+    if (!x || !y)
+        return false;
+    for (let i = 0; i < 3; i++)
+        if (x[i] !== y[i])
+            return y[i] > x[i];
+    return false;
+}
+/**
+ * THE bucketing function: which rows count as "an update". The count on the control and the list it
+ * opens both come from this, never two copies of the edge.
+ *  - self: `latest` newer than `current` AND (the button can apply it OR a command is given);
+ *  - plugin: manager-installed only (`local` is managed by the person), with a newer tag, or a
+ *    branch whose head commit is known on both sides and differs.
+ */
+export function updatesDue(status) {
+    const out = [];
+    if (!status)
+        return out;
+    const s = status.self;
+    if (s.latest && newerVersion(s.current, s.latest) && (s.canApply || !!s.command)) {
+        out.push({ kind: "self", current: s.current, latest: s.latest });
+    }
+    for (const e of status.catalog) {
+        const i = e.installed, l = e.latest;
+        if (!i || !l || i.source !== "manager" || e.problems.length > 0)
+            continue;
+        let newer;
+        if (l.kind === "tag") {
+            const a = ver(i.ref), b = ver(l.ref);
+            newer = !!i.ref && l.ref !== i.ref && (a && b ? newerVersion(i.ref, l.ref) : true);
+        }
+        else {
+            newer = !!l.commit && !!i.commit && l.commit !== i.commit;
+        }
+        if (newer)
+            out.push({ kind: "plugin", id: i.id, repo: e.repo, from: i.ref, to: l.ref });
+    }
+    return out;
+}
+//# sourceMappingURL=updates.js.map

package/node_modules/@waterplane/shared/dist/wire/updates.js.map

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