waterplane 0.0.1 → 0.1.11

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

@@ -0,0 +1,209 @@
+/**
+ * The rows and sentences of the always-on context feature, worded ONCE for the phone and the
+ * VS Code extension: what a repo and this desktop put in every turn (`alwaysOnRows`,
+ * `alwaysOnTotalsWords`) and what one conversation's first request carried (`carriedRows`,
+ * `carriedWords`, `carriedRemainder`).
+ *
+ * Rules (CLAUDE.md, skill `web-numbers`): a total is never said without its split; chars are the
+ * fact and tokens per part are an estimate, always worded `~`/"about"; an unsized row is NAMED,
+ * never counted as 0; nothing here refuses or applies anything.
+ */
+import { countedByThreshold, claudeWeightInput, MCP_UNSIZED } from "./agentfiles.js";
+import { CHARS_PER_TOKEN, weighContext } from "./contextweight.js";
+import { fmtCount } from "./tokens.js";
+import { CARRIED_KINDS } from "./wire/alwayson.js";
+const tokOf = (chars) => Math.round(chars / CHARS_PER_TOKEN);
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+/** One row per inventory row, in the inventory's order. */
+export function alwaysOnRows(files) {
+    return files.map((f) => {
+        const readers = [...new Set(f.parts.flatMap((p) => p.readers))];
+        const sum = (k) => (f.unsized ? null : f.parts.filter((p) => p.when.kind === k).reduce((n, p) => n + p.chars, 0));
+        const row = {
+            path: f.path, kind: f.kind, scope: f.scope ?? "repo", readers,
+            always: sum("always"), scoped: sum("scoped"), onDemand: sum("on-demand"),
+            counted: countedByThreshold(f) && readers.includes("claude"),
+        };
+        if (f.unsized)
+            row.unsized = f.unsized;
+        if (f.off)
+            row.off = f.off;
+        return row;
+    });
+}
+/**
+ * Claude Code's every-turn chars over a set of rows, how many sized files that is, how many MCP
+ * servers send schemas nobody can size, and how many other rows have no number (a plugin pack not
+ * on disk, a source that could not be read, a server declined here) — never called servers.
+ */
+function claudeAlways(files) {
+    let chars = 0, n = 0, servers = 0, other = 0;
+    for (const f of files) {
+        if (f.unsized) {
+            if (f.unsized === MCP_UNSIZED)
+                servers++;
+            else
+                other++;
+            continue;
+        }
+        const mine = f.parts.filter((p) => p.readers.includes("claude") && p.when.kind === "always");
+        if (!mine.length)
+            continue;
+        n++;
+        chars += mine.reduce((s, p) => s + p.chars, 0);
+    }
+    return { chars, files: n, servers, other };
+}
+const unsizedWords = (c, where) => (c.servers ? ` ${plural(c.servers, "MCP server")} ${where}add tool schemas nobody can size from here.` : "")
+    + (c.other ? ` ${plural(c.other, "more row")} ${c.other === 1 ? "has" : "have"} no size here; each says why.` : "");
+/**
+ * The list's lead: what Claude Code carries every turn from the repo's files, how much of that
+ * the threshold row counts (and which families), then this desktop's rows the same way. The total
+ * never stands without the split; unsized rows are counted by name, never as 0.
+ */
+export function alwaysOnTotalsWords(files, fmt = fmtCount) {
+    const repo = files.filter((f) => f.scope !== "desktop");
+    const desk = files.filter((f) => f.scope === "desktop");
+    const out = [];
+    const r = claudeAlways(repo);
+    if (r.files) {
+        const counted = weighContext(claudeWeightInput(repo)).alwaysOnChars;
+        const listed = r.chars - counted;
+        const split = listed > 0
+            ? `; the threshold row counts ${fmt(counted)} of those (CLAUDE.md, its imports, rules, skill descriptions), the other ${fmt(listed)} are listed beside it (CLAUDE.local.md, subagent descriptions)`
+            : "; the threshold row counts all of them (CLAUDE.md, its imports, rules, skill descriptions)";
+        out.push(`Claude Code carries ~${fmt(tokOf(r.chars))} tokens (${fmt(r.chars)} chars) from ${plural(r.files, "repo file")} on every turn${split}.${unsizedWords(r, "")}`);
+    }
+    else if (repo.length) {
+        out.push(`Claude Code carries nothing from this repo's files on every turn.${unsizedWords(r, "")}`);
+    }
+    const d = claudeAlways(desk);
+    if (d.files) {
+        out.push(`This desktop adds ~${fmt(tokOf(d.chars))} tokens (${fmt(d.chars)} chars) from ${plural(d.files, "file")} to every session, whatever the repo; the threshold row counts none of it.${unsizedWords(d, "of this desktop's ")}`);
+    }
+    else if (desk.length && (d.servers || d.other)) {
+        out.push(unsizedWords(d, "of this desktop's ").trim());
+    }
+    return out.join(" ");
+}
+/** The CLI config dir as words when the reader did not say (`RepoInstructionsDoc.configDir` absent: an older host). */
+export const DEFAULT_CONFIG_DIR_WORDS = "~/.claude";
+/**
+ * A desktop row's path as words, ONE rule for the phone and VS Code: a config-dir-relative path gets
+ * the config dir in front; a `~` or absolute path (`~/.claude.json`, a plugin installed elsewhere)
+ * is already words; the managed-plugins row has no path at all.
+ */
+export function desktopPathWords(p, configDirWords = DEFAULT_CONFIG_DIR_WORDS) {
+    if (!p)
+        return "not on disk";
+    if (p.startsWith("~") || p.startsWith("/") || /^[A-Za-z]:[\\/]/.test(p) || p.startsWith("\\\\"))
+        return p;
+    return `${configDirWords.replace(/[\\/]+$/, "")}/${p}`;
+}
+/** Whether an unsized row is an MCP server whose schemas arrive at connect time (the When column says "every request" only for those). */
+export const isUnsizedServer = (f) => f.unsized === MCP_UNSIZED;
+export const CARRIED_REMAINDER_LABEL = "everything else in the first request: your prompt, and whatever the harness sent that the log does not record (≈)";
+const UNDOC = "(undocumented record)";
+function carriedLabel(p) {
+    const n = p.count;
+    switch (p.kind) {
+        case "instructions": return "instruction files";
+        case "skill_listing": return n != null ? `skill listing (${plural(n, "skill")})` : "skill listing";
+        case "mcp_instructions": return n != null ? `MCP instructions (${plural(n, "server")})` : "MCP instructions";
+        case "deferred_tools": return n != null ? `deferred tool names (${n})` : "deferred tool names";
+        case "agent_listing": return n != null ? `subagent listing (${n})` : "subagent listing";
+        case "hook_context": return n != null && n > 1 ? `hook context (${n})` : "hook context";
+        case "system_prompt": return `system prompt ${UNDOC}`;
+        case "tool_schemas": return `tool schemas ${UNDOC}`;
+    }
+}
+const charsWords = (chars, fmt) => `~${fmt(tokOf(chars))} tokens · ${fmt(chars)} chars`;
+const partsTok = (c) => Math.round(c.parts.reduce((n, p) => n + p.chars, 0) / CHARS_PER_TOKEN);
+/**
+ * `firstRequestTok` minus the parts' estimated tokens; null without the anchor, and null — never 0 —
+ * when the estimate already exceeds the request (JSON schemas tokenise denser than ~4 chars a token,
+ * so a tool-heavy request can overshoot): the remainder then cannot be placed, and `carriedWords`
+ * says so. An estimate by construction (the parts are chars), so it is always worded `≈`.
+ */
+export function carriedRemainder(c) {
+    if (c.firstRequestTok == null)
+        return null;
+    const rest = c.firstRequestTok - partsTok(c);
+    return rest >= 0 ? rest : null;
+}
+/** The sentence beside a remainder that could not be placed. */
+export const CARRIED_REMAINDER_UNPLACED = "The parts' estimate already exceeds the request, so the rest (your prompt among it) cannot be placed.";
+/** The parts in `CarriedKind` order, then the remainder row when the first request has been answered and the remainder could be placed (`carriedRemainder`). */
+export function carriedRows(c, fmt = fmtCount) {
+    const order = (k) => CARRIED_KINDS.indexOf(k);
+    const rows = [...c.parts].sort((a, b) => order(a.kind) - order(b.kind)).map((p) => {
+        const row = { key: p.kind, label: carriedLabel(p), chars: p.chars, tok: tokOf(p.chars), words: charsWords(p.chars, fmt) };
+        if (p.files)
+            row.files = p.files.map((f) => ({ label: `${f.path} · ${f.type}`, path: f.path, type: f.type, chars: f.chars, words: charsWords(f.chars, fmt) }));
+        if (p.names)
+            row.names = p.names;
+        if (p.undocumented)
+            row.undocumented = true;
+        return row;
+    });
+    const rest = carriedRemainder(c);
+    if (rest != null)
+        rows.push({ key: "remainder", label: CARRIED_REMAINDER_LABEL, chars: null, tok: rest, words: `≈${fmt(rest)} tokens` });
+    return rows;
+}
+const PART_NOUN = {
+    instructions: "the instruction files",
+    skill_listing: "the skill listing",
+    mcp_instructions: "MCP instructions",
+    deferred_tools: "deferred tool names",
+    agent_listing: "the subagent listing",
+    hook_context: "hook context",
+    system_prompt: "the system prompt",
+    tool_schemas: "tool schemas",
+};
+const capital = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+const andList = (xs) => (xs.length <= 1 ? xs.join("") : `${xs.slice(0, -1).join(", ")} and ${xs[xs.length - 1]}`);
+/**
+ * The section's lead: the whole first request, then how much of it the documented attachments
+ * explain (chars, and tokens as "about"), what the undocumented snapshot adds where it was seen,
+ * and what the rest is. Later deltas are counted in one sentence, never folded in.
+ * `unplacedShown`: the caller draws `CARRIED_REMAINDER_UNPLACED`'s fact itself (the phone's strip
+ * caption), so the lead leaves it out rather than saying it twice.
+ */
+export function carriedWords(c, fmt = fmtCount, opts = {}) {
+    const kinds = new Set(c.parts.map((p) => p.kind));
+    const documented = CARRIED_KINDS.filter((k) => kinds.has(k) && k !== "system_prompt" && k !== "tool_schemas");
+    const docChars = c.parts.filter((p) => !p.undocumented && p.kind !== "system_prompt" && p.kind !== "tool_schemas").reduce((n, p) => n + p.chars, 0);
+    const named = (c.laterKinds ?? []).filter((k) => k in PART_NOUN);
+    const later = named.length
+        ? ` ${capital(andList(named.map((k) => PART_NOUN[k])))} changed later in the conversation; the change is not folded in.`
+        : c.laterDeltas > 0
+            ? ` ${c.laterDeltas === 1 ? "One kind" : `${c.laterDeltas} kinds`} of these changed later in the conversation; the change is not folded in.`
+            : "";
+    if (c.firstRequestTok == null) {
+        return `No request has been answered yet; these are the attachments the CLI has written so far (chars).${later}`;
+    }
+    const out = [`The first request carried ${fmt(c.firstRequestTok)} tokens.`];
+    if (documented.length)
+        out.push(`About ${fmt(tokOf(docChars))} of them (${fmt(docChars)} chars) are ${andList(documented.map((k) => PART_NOUN[k]))} the CLI attached;`);
+    const snap = ["system_prompt", "tool_schemas"].filter((k) => kinds.has(k));
+    const unknown = ["system_prompt", "tool_schemas"].filter((k) => !kinds.has(k)).map((k) => PART_NOUN[k]);
+    if (snap.length) {
+        const said = snap.map((k) => {
+            const chars = c.parts.filter((p) => p.kind === k).reduce((n, p) => n + p.chars, 0);
+            return `${PART_NOUN[k]} at about ${fmt(tokOf(chars))} tokens (${fmt(chars)} chars)`;
+        });
+        out.push(`${documented.length ? "an" : "An"} undocumented record puts ${andList(said)};`);
+    }
+    const lead = out[out.length - 1].endsWith(";");
+    if (carriedRemainder(c) == null) {
+        if (!opts.unplacedShown)
+            out.push(lead ? CARRIED_REMAINDER_UNPLACED.replace(/^The/, "the") : CARRIED_REMAINDER_UNPLACED);
+        else if (lead)
+            out[out.length - 1] = out[out.length - 1].replace(/;$/, ".");
+    }
+    else
+        out.push(`${lead ? "the" : "The"} rest is ${andList([...unknown, "your prompt with what the harness added to it"])}.`);
+    return out.join(" ") + later;
+}
+//# sourceMappingURL=alwaysonwords.js.map

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

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

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

@@ -0,0 +1,213 @@
+/**
+ * What a build leaves behind, and what it is called.
+ *
+ * Every rule here exists because of the same measured failure, seen across nine
+ * repos on this desktop at once: a build button runs `./gradlew assembleDebug`,
+ * the deliverable is `app-debug.apk` in `build/outputs/…`, and that is what the
+ * phone is offered. Three things are wrong with it and none of them are visible
+ * on the phone:
+ *
+ *  - **The name says nothing.** Three repos here produce a file called exactly
+ *    `app-debug.apk`. The download list, the install log and the outbox all
+ *    show one word that identifies neither the app nor the build.
+ *  - **Nothing is ever removed.** 6.8 GB of transport files across fourteen
+ *    repos was the measurement that produced the sweep; a build that appends a
+ *    130 MB APK per tap is where most of it came from.
+ *  - **The same bytes arrive twice.** A script that copies its output somewhere
+ *    friendlier leaves the original in place, both are detected, both are
+ *    queued, and the phone spends 454 MB fetching one 227 MB APK.
+ *
+ * The answer is host-side and not per-repo: nine repos cannot each be taught
+ * this, and the tenth is written by an agent that has never read the other
+ * nine. So a build's outputs are COLLECTED into `.claude/outbox/` under a name
+ * that carries a version, older builds of the same artifact are pruned, and
+ * duplicates are folded — by default, for every build, in every repo, unless
+ * this project's policy says otherwise.
+ *
+ * This module is the rules half: pure, node-tested, and shared so the phone can
+ * word the switches with the same vocabulary the host acts on. The disk half is
+ * `host/artifacts.ts`.
+ */
+/**
+ * What a repo does with what its builds produce. Stored per repo in
+ * `<repoDir>/.waterplane/artifacts.json` — next to `builds.json` and
+ * `autopull.json`, and for the same reason those live there: how a project
+ * names and keeps its deliverables is a property of the project, not of the
+ * desktop or of the phone that tapped the button.
+ */
+export interface ArtifactPolicy {
+    /** Copy a build's outputs into `.claude/outbox/` under a versioned name. */
+    collect: boolean;
+    /** After collecting, delete older builds of the same artifact from the outbox. */
+    prune: boolean;
+    /** How many builds of one artifact survive a prune (the newest ones). */
+    keep: number;
+}
+/**
+ * On, on, and three.
+ *
+ * Both switches default ON because the failure they fix is invisible: nobody
+ * reports a file called `app-debug.apk` or a 130 MB copy nobody removed, they
+ * just live with them. `keep: 3` is the smallest number that still answers
+ * "does the previous build work?" — the question an unnamed APK made
+ * unanswerable in the first place.
+ */
+export declare const DEFAULT_ARTIFACT_POLICY: ArtifactPolicy;
+/** Hard ceiling on `keep`: past this the switch is not "tidy up" any more. */
+export declare const MAX_ARTIFACT_KEEP = 50;
+/** Sanitize a persisted/phone-supplied policy — this file is hand-editable and
+ *  an agent writes the one beside it. An unreadable field falls back to the
+ *  DEFAULT rather than to `false`: a policy nobody can parse must not silently
+ *  turn the feature off. */
+export declare function cleanArtifactPolicy(v: unknown): ArtifactPolicy;
+/** One line for a phone: what this repo will do with the next build's output. */
+export declare function artifactPolicyText(p: ArtifactPolicy): string;
+/**
+ * Is this name token the VARIABLE part of an artifact name — the bit that
+ * changes every time the same thing is produced again?
+ *
+ *  - all-digits (build number, epoch, `20260828`, a date component);
+ *  - a hex run of 6+ that contains a digit (a commit/content hash). The digit is
+ *    required so ordinary words that happen to be hex-only ("facade", "decade")
+ *    stay STABLE — folding those out would merge unrelated artifacts;
+ *  - a version (`v2`, `1.4.0` arrives pre-split as `1`, `4`, `0`).
+ *
+ * It only ever sees a token `NAME_SEP` produced, which is why that separator
+ * set is part of this rule rather than a detail of it.
+ */
+export declare function isVariableToken(tok: string): boolean;
+/**
+ * The separators an artifact name is built from.
+ *
+ * `+` and `~` are SEPARATORS, not letters. They are how the two commonest
+ * machine-written version strings attach a build to a release —
+ * `picture-app-1.1.0+343.apk` (semver build metadata, which is what Flutter,
+ * pub and Gradle's `versionName+versionCode` produce) and `app-1.1.0~rc1.apk`
+ * (the Debian spelling). Splitting on `[-_. ]` alone left the last version
+ * digit fused to the build number as one token, `0+343`, which is neither all
+ * digits nor hex and therefore read as a STABLE WORD: every build of that app
+ * was its own family, nothing ever superseded anything, and the phone fetched
+ * 130 MB again per build and kept the previous one queued beside it. The
+ * artifacts whose names carry a version are exactly the ones these rules exist
+ * for, so a separator they do not know about defeats them precisely where it
+ * matters most.
+ */
+export declare const NAME_SEP: RegExp;
+/**
+ * The supersede key: "which artifact IS this", independent of which BUILD of it.
+ *
+ * `tiptoi-debug-0f98c1ab.apk` and `tiptoi-debug-39a2f7e1.apk` are the same thing
+ * twice — queueing both means the phone spends 46 MB of a roaming link to end up
+ * with one file it wants and one it doesn't. `app-debug.apk` and
+ * `app-release.apk` are NOT the same thing, so only the tokens that actually
+ * vary are folded out; every stable word is kept, which is what stops a rule
+ * this aggressive from eating a sibling artifact.
+ *
+ * The directory and extension are part of the key for the same reason. When
+ * EVERY token is variable (`1000074170.jpg`) there is no name left to compare,
+ * so the key falls back to the exact path: a regeneration at the same path still
+ * supersedes (that is the common build-overwrites-its-output case), and two
+ * differently-named photos never do.
+ *
+ * Lives here rather than beside the download queue that first needed it,
+ * because the prune below asks the SAME question — "is this an older build of
+ * the thing I just made?" — and two answers to it would mean the phone
+ * de-duplicating one way while the desktop deletes another.
+ */
+export declare function familyKey(relPath: string): string;
+/** Does this stem already say WHICH build it is? A name with a variable token
+ *  in it has a version, a date or a hash in it already, and renaming it would
+ *  only make it longer and less like what the build printed. */
+export declare function hasVersionToken(stem: string): boolean;
+/** `MMDD-HHMM` in local time — the fallback identifier when a repo has neither a
+ *  version nor a git sha to offer. Local, not UTC: it is read beside a build row
+ *  that is already showing a local clock. */
+export declare function stampOf(when: Date): string;
+/** Everything a name can be built from. Every field but `stem`/`ext` is
+ *  optional, and a missing one is simply not said — a name is never padded with
+ *  "unknown". */
+export interface ArtifactNaming {
+    /** The repo's directory name — what a person calls the project. */
+    repoName: string;
+    /** The produced file's name without its extension (`app-debug`). */
+    stem: string;
+    /** Extension WITH the dot, lower-cased (`.apk`). */
+    ext: string;
+    /** The project's own version, if one could be read (`1.1.0+344`, `2.3`). */
+    version?: string;
+    /** Short git sha of the commit built, `-dirty` already appended if it was. */
+    sha?: string;
+    /** When the build finished. */
+    when: Date;
+}
+/**
+ * The name a collected artifact gets.
+ *
+ * Three rules, in this order:
+ *
+ *  1. **A name that already says which build it is, is kept.** Flutter's
+ *     `picture-app-debug-v1.1.0-344.apk` and a timestamped
+ *     `fp-functions-bundle-20260922-1042.tgz` are better than anything this
+ *     function would invent, and renaming them would break the link between
+ *     what the build printed and what arrived on the phone.
+ *  2. **The repo's name leads.** `app-debug.apk` exists in three repos here;
+ *     the download list is one list.
+ *  3. **Then the variant, then the version.** `app` and the repo's own name are
+ *     dropped from the variant — `picture-app` + `app-debug` reads
+ *     `picture-app-debug`, not `picture-app-app-debug`. The version is the
+ *     project's if one could be read, else the git sha, else the date; a repo
+ *     that can offer both gets both, because a version answers "which release"
+ *     and a sha answers "which code".
+ */
+export declare function artifactName(n: ArtifactNaming): string;
+/** One candidate for folding: enough of a file to say whether two of them are
+ *  the same artifact, and which name is worth keeping. */
+export interface FoldCandidate {
+    relPath: string;
+    size: number;
+    /** A cheap content fingerprint, supplied by the caller (`host/artifacts.ts`
+     *  hashes the head and tail). Absent ⇒ never folded with anything: a fold
+     *  this module cannot justify is one it must not make. */
+    fingerprint?: string;
+}
+/** Is this path inside the transport dir a person's phone reads? */
+export declare function inOutbox(relPath: string): boolean;
+/**
+ * Fold a run's outputs down to the DISTINCT artifacts among them.
+ *
+ * One `flutter build apk` plus a script that copies the result to a friendlier
+ * name is two detected files, 227 MB each, the same bytes — and the phone,
+ * which fetches one download at a time, spends 454 MB on it. Identity is size
+ * AND the caller's fingerprint, never size alone: two ABI splits of one app are
+ * within bytes of each other and folding them would silently drop a release.
+ *
+ * Returns the survivors in the input's order, plus what each of them absorbed,
+ * so the build log can SAY it rather than a file quietly not appearing.
+ */
+export declare function foldDuplicates<T extends FoldCandidate>(files: T[]): {
+    kept: T[];
+    folded: {
+        kept: T;
+        dropped: T[];
+    }[];
+};
+/** A file the prune may consider: an outbox entry with a clock on it. */
+export interface PruneCandidate {
+    relPath: string;
+    mtime: number;
+}
+/**
+ * Which older builds a finished run makes removable.
+ *
+ * Deliberately narrow, and narrower than the sweep: only files whose
+ * `familyKey` matches something this run just produced, only the ones older
+ * than the newest `keep` of that family, and never the artifacts of the run
+ * itself. A build cleans up after ITSELF — it never touches a family it did not
+ * just rebuild, which is what keeps "delete files automatically" from being the
+ * thing that removes the one APK you were about to install.
+ *
+ * `protect` is the run's own output (paths, not families): equal mtimes are
+ * routine when a build writes two files in one second, and an artifact this run
+ * produced must never be a victim of the same run's prune.
+ */
+export declare function pruneVictims(files: PruneCandidate[], produced: string[], keep: number, protect?: string[]): PruneCandidate[];