waterplane 0.0.1 → 0.1.6

package/packages/host/dist/artifacts.js

@@ -0,0 +1,315 @@
+/**
+ * What a build leaves behind — the disk half.
+ *
+ * `@waterplane/shared`'s `artifacts.ts` holds every RULE (what a collected file is
+ * called, which two files are the same bytes, what a prune may remove) and the
+ * measurement behind them. This module is what touches the filesystem: reading
+ * a project's own version, linking a deliverable into `.claude/outbox/`,
+ * fingerprinting two candidates, deleting the builds a prune condemned.
+ *
+ * Three things it deliberately does not do:
+ *
+ *  - **It never touches what the build wrote.** Gradle's `app-debug.apk` stays
+ *    exactly where gradle put it; the outbox gets a HARD LINK to the same bytes
+ *    where the filesystem allows one, so a 227 MB APK costs 227 MB, not 454 —
+ *    and the link survives the next `gradle clean` that removes the original.
+ *  - **It never deletes outside `.claude/outbox/`**, and inside it only files
+ *    whose `familyKey` matches something this very run produced. Deletion goes
+ *    through `files.ts`' `deleteArtifact`, which is the one containment guard
+ *    for that directory — never a second `rmSync` with its own idea of safe.
+ *  - **It never fails a build.** Every step is best-effort and SAYS what it
+ *    did into the run's own output; a repo on a filesystem that refuses links,
+ *    a read-only outbox or a vanished file degrades to "collected nothing",
+ *    which is exactly where this feature started.
+ */
+import { createHash } from "node:crypto";
+import { closeSync, constants, copyFileSync, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, statSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { DEFAULT_ARTIFACT_POLICY, artifactName, cleanArtifactPolicy, familyKey, foldDuplicates, inOutbox, pruneVictims, logTag, } from "@waterplane/shared";
+import { repoStateDir } from "./branddirs.js";
+import { deleteArtifact, OUTBOX_SUBDIRS } from "./files.js";
+import { targetId } from "./repos.js";
+import { writeJsonAtomic } from "./jsonstore.js";
+/** Where a collected artifact goes. The first of `files.ts`' outbox dirs is the
+ *  canonical one — `.outbox` is only recognised for reading. */
+const OUTBOX = OUTBOX_SUBDIRS[0];
+/** How much of a file is hashed to decide two paths hold the same bytes: the
+ *  first and last 64 KB, plus the size. Reading 227 MB twice to answer a
+ *  question about a name would cost more than the duplicate download it saves;
+ *  a head+tail hash of an APK (a zip — its central directory is in the tail)
+ *  is conclusive in every case this has to tell apart. */
+const FINGERPRINT_BYTES = 64 * 1024;
+/** The policy file, beside `builds.json` and `autopull.json` for the same
+ *  reason those are there: how a project names and keeps its deliverables is a
+ *  property of the project. */
+function policyPath(repoDir) { return join(repoStateDir(repoDir), "artifacts.json"); }
+/** This repo's policy (the defaults when there is no file — the feature is on
+ *  by default, see `DEFAULT_ARTIFACT_POLICY`). */
+export function artifactPolicy(repoDir) {
+    try {
+        return cleanArtifactPolicy(JSON.parse(readFileSync(policyPath(repoDir), "utf8")));
+    }
+    catch {
+        return { ...DEFAULT_ARTIFACT_POLICY };
+    }
+}
+/** Persist a repo's policy; returns what was actually written. */
+export function saveArtifactPolicy(repoDir, p) {
+    const clean = cleanArtifactPolicy(p);
+    try {
+        const path = policyPath(repoDir);
+        mkdirSync(dirname(path), { recursive: true });
+        writeJsonAtomic(path, clean, { space: 2 });
+    }
+    catch { /* best-effort — an unwritable repo just doesn't remember the policy */ }
+    return clean;
+}
+/**
+ * The project's own version, if it says one anywhere this can read cheaply.
+ *
+ * Four manifests, in the order that answers first for the repos here: Flutter
+ * (`pubspec.yaml`), node (`package.json`), Gradle (`versionName` + optional
+ * `versionCode`, both android modules and the root), and Cargo. Everything is
+ * a plain regex over at most a few KB — nothing is executed, and a manifest
+ * that does not parse is simply not an answer.
+ *
+ * Absent is a normal outcome, not a failure: the name falls back to the git
+ * sha, and then to the clock.
+ */
+export function projectVersion(repoDir) {
+    const read = (rel) => {
+        try {
+            const full = join(repoDir, rel);
+            if (!existsSync(full) || statSync(full).size > 256 * 1024)
+                return null;
+            return readFileSync(full, "utf8");
+        }
+        catch {
+            return null;
+        }
+    };
+    const pubspec = read("pubspec.yaml");
+    const pubv = pubspec?.match(/^version:\s*([0-9][^\s#]*)/m)?.[1];
+    if (pubv)
+        return pubv;
+    const pkg = read("package.json");
+    if (pkg) {
+        try {
+            const v = JSON.parse(pkg).version;
+            if (typeof v === "string" && /\d/.test(v))
+                return v;
+        }
+        catch { /* a package.json that doesn't parse is not a version */ }
+    }
+    for (const g of ["app/build.gradle", "app/build.gradle.kts", "android/app/build.gradle", "android/app/build.gradle.kts", "build.gradle", "build.gradle.kts"]) {
+        const text = read(g);
+        if (!text)
+            continue;
+        const name = text.match(/versionName\s*[=\s]\s*["']([^"']+)["']/)?.[1];
+        const code = text.match(/versionCode\s*[=\s]\s*(\d+)/)?.[1];
+        if (name)
+            return code ? `${name}+${code}` : name;
+        if (code)
+            return code;
+    }
+    const cargo = read("Cargo.toml");
+    const cv = cargo?.match(/^\s*version\s*=\s*"([^"]+)"/m)?.[1];
+    if (cv)
+        return cv;
+    return undefined;
+}
+/** The commit this was built from, short, `-dirty` when the tree was not clean.
+ *  A repo that is not a git checkout simply has no sha to offer. */
+export function gitStamp(repoDir) {
+    const git = (args) => {
+        try {
+            return execFileSync("git", ["-C", repoDir, ...args], { encoding: "utf8", timeout: 2000, stdio: ["ignore", "pipe", "ignore"] }).trim();
+        }
+        catch {
+            return null;
+        }
+    };
+    const sha = git(["rev-parse", "--short=8", "HEAD"]);
+    if (!sha)
+        return undefined;
+    const dirty = git(["status", "--porcelain", "--untracked-files=no"]);
+    return dirty ? `${sha}-dirty` : sha;
+}
+/** Size + a hash of the first and last 64 KB. Absent when the file cannot be
+ *  read, which means "never folded with anything" — a fold that cannot be
+ *  justified must not be made. */
+function fingerprint(full, size) {
+    let fd;
+    try {
+        fd = openSync(full, "r");
+        const h = createHash("sha1");
+        const buf = Buffer.alloc(Math.min(FINGERPRINT_BYTES, Math.max(size, 1)));
+        const head = readSync(fd, buf, 0, buf.length, 0);
+        h.update(buf.subarray(0, head));
+        if (size > FINGERPRINT_BYTES) {
+            const tail = readSync(fd, buf, 0, Math.min(FINGERPRINT_BYTES, size), Math.max(0, size - FINGERPRINT_BYTES));
+            h.update(buf.subarray(0, tail));
+        }
+        return h.digest("hex").slice(0, 16);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined)
+            try {
+                closeSync(fd);
+            }
+            catch { /* already gone */ }
+    }
+}
+/**
+ * Put a copy of `from` at `to`, as cheaply as the filesystem allows.
+ *
+ * `COPYFILE_FICLONE` asks for a copy-on-write clone (APFS here, btrfs/xfs
+ * elsewhere) and silently falls back to a real copy where the filesystem has
+ * no such thing — so a 227 MB APK usually costs no extra bytes until something
+ * diverges, and always costs at most one copy.
+ *
+ * A HARD LINK would be cheaper still and is wrong, which this learned the
+ * expensive way: `flutter build`, `cp -f` and `printf >` all rewrite their
+ * output IN PLACE, and a link means that rewrite lands inside the artifact
+ * already collected from the PREVIOUS build. The whole point of keeping the
+ * last three is that they are the last three, not three names for whatever the
+ * newest build most recently wrote.
+ */
+function place(from, to) {
+    try {
+        copyFileSync(from, to, constants.COPYFILE_FICLONE);
+        return true;
+    }
+    catch { /* fall through */ }
+    try {
+        copyFileSync(from, to);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** `name.apk` → `name_2.apk` → `name_3.apk`. The `_N` spelling is files.ts's
+ *  uniquifier and `familyKey` folds it, so a collision is still the same
+ *  artifact for the prune and for the phone's download queue. */
+function freeName(dir, wanted) {
+    const ext = extname(wanted);
+    const stem = wanted.slice(0, wanted.length - ext.length);
+    if (!existsSync(join(dir, wanted)))
+        return wanted;
+    for (let i = 2; i < 100; i++) {
+        const n = `${stem}_${i}${ext}`;
+        if (!existsSync(join(dir, n)))
+            return n;
+    }
+    return `${stem}_${Date.now()}${ext}`;
+}
+/** Every file currently in the repo's outbox, with its clock — what a prune
+ *  chooses its victims from. */
+function outboxFiles(repoDir) {
+    const dir = join(repoDir, ...OUTBOX.split("/"));
+    const out = [];
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const e of entries) {
+        if (!e.isFile() || e.name.startsWith("."))
+            continue;
+        try {
+            out.push({ relPath: `${OUTBOX}/${e.name}`, mtime: statSync(join(dir, e.name)).mtimeMs });
+        }
+        catch { /* gone */ }
+    }
+    return out;
+}
+/**
+ * Collect, name, fold and prune what a run produced.
+ *
+ * Returns the artifact list the run should REPORT — which is the point as much
+ * as the disk changes are: after this, "the build produced this" and "this is
+ * what the phone is offered" are the same list, with one entry per artifact
+ * rather than one per path the same bytes happen to sit at.
+ *
+ * `say` receives one line per action, already newline-terminated for a PTY, and
+ * it is the only account of this a person gets — a file that appears in the
+ * outbox and an older one that stops existing must both be sentences somebody
+ * can read afterwards.
+ */
+export function collectArtifacts(repoDir, artifacts, policy, say, now = new Date()) {
+    if (!artifacts.length)
+        return artifacts;
+    const root = resolve(repoDir);
+    const repoId = targetId(repoDir);
+    // ── 1. the same bytes under two names are ONE artifact ──────────────────
+    const fps = artifacts.map((a) => {
+        const full = join(root, ...a.relPath.split("/"));
+        return { ...a, fingerprint: fingerprint(full, a.size) };
+    });
+    const { kept, folded } = foldDuplicates(fps);
+    for (const f of folded) {
+        for (const d of f.dropped)
+            say(`${logTag} same file twice: ${d.relPath} is ${f.kept.relPath} — offering it once\r\n`);
+    }
+    if (!policy.collect)
+        return kept.map(({ fingerprint: _fp, ...a }) => a);
+    // ── 2. everything that is not already where a person looks, collected ───
+    const outDir = join(root, ...OUTBOX.split("/"));
+    try {
+        mkdirSync(outDir, { recursive: true });
+    }
+    catch { /* handled by the place() below failing */ }
+    const version = projectVersion(repoDir);
+    const sha = gitStamp(repoDir);
+    const repoName = basename(root);
+    const out = [];
+    const produced = [];
+    for (const a of kept) {
+        const { fingerprint: _fp, ...art } = a;
+        if (inOutbox(art.relPath) || art.stale) {
+            // Already where it belongs — or a file this run did not write, which must
+            // not be copied anywhere under a name claiming this build made it.
+            out.push(art);
+            if (inOutbox(art.relPath) && !art.stale)
+                produced.push(art.relPath);
+            continue;
+        }
+        const ext = extname(art.name).toLowerCase();
+        const wanted = artifactName({ repoName, stem: art.name.slice(0, art.name.length - ext.length), ext, version, sha, when: now });
+        const name = freeName(outDir, wanted);
+        const placed = place(join(root, ...art.relPath.split("/")), join(outDir, name));
+        if (!placed) {
+            say(`${logTag} could not collect ${art.relPath} into ${OUTBOX} — offering it where it is\r\n`);
+            out.push(art);
+            continue;
+        }
+        const relPath = `${OUTBOX}/${name}`;
+        let mtime = art.mtime;
+        try {
+            mtime = statSync(join(outDir, name)).mtimeMs;
+        }
+        catch { /* keep the source's clock */ }
+        say(`${logTag} artifact: ${relPath} (from ${art.relPath})\r\n`);
+        out.push({ repoId, name, relPath, size: art.size, mtime });
+        produced.push(relPath);
+    }
+    // ── 3. older builds of exactly what was just produced ───────────────────
+    if (policy.prune && produced.length) {
+        const victims = pruneVictims(outboxFiles(repoDir), produced, policy.keep);
+        for (const v of victims) {
+            if (deleteArtifact(root, v.relPath))
+                say(`${logTag} removed older build: ${v.relPath} (keeping the newest ${policy.keep})\r\n`);
+        }
+    }
+    return out;
+}
+/** Re-exported so a caller does not have to know which module owns which half. */
+export { familyKey };
+//# sourceMappingURL=artifacts.js.map

package/packages/host/dist/artifacts.js.map

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

package/packages/host/dist/askbox.d.ts

@@ -0,0 +1,116 @@
+export interface AskOption {
+    label: string;
+    desc?: string;
+}
+export interface AskQuestion {
+    /**
+     * This question's identity: the pending call's `tool_use` id, plus which of
+     * its questions this is (`<toolUseId>#<n>`).
+     *
+     * The CLI mints the id, it is in the log before anyone answers, and it is the
+     * one thing about a box on screen that a repaint cannot change — which is
+     * exactly what `prompt.ts`'s `sameBox` needs and could not otherwise get.
+     * Everything scrapeable moves: a box taller than the terminal loses its
+     * question row, and what the detector then joins above option 1 is whatever
+     * happens to be there.
+     *
+     * The `#n` is not decoration. One `AskUserQuestion` may carry several
+     * questions and the TUI draws them one at a time with Tab between them, so
+     * the tool_use id alone would call two different boxes one box.
+     */
+    id: string;
+    question: string;
+    header?: string;
+    multi?: boolean;
+    options: AskOption[];
+}
+/**
+ * Every `AskUserQuestion` in the log's tail that has no `tool_result` yet.
+ *
+ * "No result" is what makes it the box currently on screen. The pairing is done
+ * over the tail only: a tool_use older than the window is invisible here, which
+ * yields no enrichment — never a WRONG one, since a result always follows its
+ * call and both would be in the window together.
+ */
+export declare function pendingAskQuestions(cwd: string, claudeSessionId: string | undefined): AskQuestion[];
+/**
+ * The newest log record carrying an `AskUserQuestion` call, as the raw line —
+ * the input to the `askbox.enrich` fixture capture, which keeps only its
+ * skeleton (`clifixtures.ts`). Null when there is none.
+ */
+export declare function pendingAskRecord(cwd: string, claudeSessionId: string | undefined): string | null;
+/**
+ * The questions of ONE call, from its input as a `PreToolUse` hook carried it —
+ * the source while the log does not hold the call yet. Unless the log already
+ * shows it ANSWERED: then the box on screen is not this call's.
+ */
+export declare function asksFromCall(cwd: string, claudeSessionId: string | undefined, call: {
+    id: string;
+    input: unknown;
+}): AskQuestion[];
+/**
+ * Does this logged question describe the box we scraped?
+ *
+ * Matched on LABELS, not on the question text: the question is exactly the row
+ * that scrolls off a tall box, so requiring it would fail precisely when the
+ * enrichment matters most.
+ *
+ * Two labels have to agree, and they have to be a majority of the SMALLER side.
+ * One is never enough — two questions in a row can both offer "Yes", and putting
+ * the previous box's paragraphs under this one's buttons is worse than showing
+ * no paragraphs at all. The smaller side is what keeps the rule usable in both
+ * directions the two lists differ: the TUI appends rows the tool never sent
+ * ("Type something."), and a truncated screen shows only the tail of the tool's.
+ */
+export declare function askMatches(ask: AskQuestion, labels: readonly string[]): boolean;
+/**
+ * WHICH logged question is the box on screen — or nothing, if two of them
+ * could be.
+ *
+ * `asks.find(askMatches)` took the FIRST question of the call that overlapped,
+ * and one `AskUserQuestion` may carry several. Two questions sharing two labels
+ * is not exotic — "Yes"/"No" appear in both halves of most pairs — so after a
+ * Tab to question 2 the matcher could hand back question 1, which then supplied
+ * question 1's `askId` (so `sameBox` called the new box the old one), question
+ * 1's descriptions, and question 1's first options as the "recovered" head that
+ * a digit would select. Every one of those is a wrong number where the rule is
+ * that a heuristic degrades to absent.
+ *
+ * So: score every candidate and require a UNIQUE winner. A tie means the screen
+ * does not say which question it is showing, and the honest answer to that is
+ * no enrichment at all — the box is still published, with the labels as the
+ * terminal cut them.
+ */
+export declare function pickAsk(asks: readonly AskQuestion[], labels: readonly string[]): AskQuestion | null;
+/**
+ * The options a TALL box scrolled off the top, recovered from the log.
+ *
+ * A box with six options and a description each is taller than a phone's
+ * terminal, so the CLI scrolls its own top away and the strict pass publishes a
+ * run starting at 4. The card then says "options above 4 are off the screen" and
+ * offers three buttons for a six-option question — the complaint this answers.
+ *
+ * The recovery is EXACT rather than heuristic, because the TUI's numbering is
+ * the tool's own: measured on claude 2.1.267, the list it draws is
+ * `[...the tool's options, "Other", ("Chat about this")]` numbered from 1, so
+ * the log's option *i* is the row a keystroke of *i* selects. What comes back is
+ * the head (indices 1..first-1) with the words the tool wrote, prepended to the
+ * run exactly as it was scraped.
+ *
+ * Two rules keep it honest:
+ *
+ *   • it must be PROVED, not assumed. At least one index the two lists share has
+ *     to agree (prefix-wise, since the screen cuts a label and the log does
+ *     not), and no shared index may disagree. A run made up entirely of the
+ *     TUI's own appended rows overlaps nothing and returns null — absent, never
+ *     a wrong number.
+ *   • it only ever ADDS. A label already on screen is left exactly as scraped,
+ *     because `promptFingerprint` is built from the labels and rewriting one
+ *     would make an answer already queued against this box read as stale.
+ */
+export declare function recoverHead(ask: AskQuestion, options: readonly {
+    index: number;
+    label: string;
+}[]): AskOption[] | null;
+/** The description the log holds for a scraped label, if any. */
+export declare function descFor(ask: AskQuestion, label: string): string | undefined;