waterplane 0.0.0-stage → 0.1.6

package/packages/host/dist/installlog.js

@@ -0,0 +1,137 @@
+/**
+ * **Which version of what is on which phone** — the desktop's copy of what the
+ * devices installed.
+ *
+ * This exists because of an asymmetry the rest of the download path does not
+ * have: **there is one host and there may be many clients.** A build is
+ * produced here, fetched by every phone whose allow-list names its package, and
+ * installed on each of them by `ShellPullService` with the app closed. Every
+ * account of that install is on the phone that did it — so "is the new Tiptoi on
+ * both phones, and when did the second one get it?" is a question no device can
+ * answer and this desktop can.
+ *
+ * The store is deliberately dumb, in `settings.ts`'s posture:
+ *
+ *  - **It records, it never decides.** Nothing here installs anything, refuses
+ *    anything, or tells a phone what to do. It is an account of what already
+ *    happened (`CLAUDE.md`: nothing applies itself).
+ *  - **A report is a re-statement.** Phones re-send their whole history on every
+ *    connect, because the install worth having in the log is usually the one
+ *    that happened at 3 a.m. with the tunnel down. The merge is keyed and
+ *    idempotent (`@waterplane/shared`'s `mergeInstallLog`), so reconnecting a hundred
+ *    times adds nothing — and it is the shared module rather than a local copy
+ *    precisely because losing or duplicating a history is invisible until
+ *    somebody goes looking for a date.
+ *  - **The host stamps only its own clock.** `at` — when the install actually
+ *    finished — belongs to the phone, and an older shell that cannot say leaves
+ *    it absent rather than getting the report time substituted for it.
+ *
+ * Persisted to `<STATE_DIR>/installs.json`, tmp+rename, debounced, flushed on
+ * shutdown: the same arrangement as `settings.ts` and `sentlog.ts`, and for the
+ * same reason — `npm run restart` is routine here, and a log that a restart
+ * wipes is not a log.
+ */
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { cleanInstallEntry, entryAt, INSTALL_LOG_CAP, installDevices, MAX_REPORT_ENTRIES, mergeInstallLog } from "@waterplane/shared";
+import { hostStateDir } from "./branddirs.js";
+import { readJsonGuarded, writeJsonAtomic } from "./jsonstore.js";
+const SAVE_DEBOUNCE_MS = 500;
+export class InstallLogStore {
+    path;
+    entries = [];
+    timer = null;
+    constructor(root) {
+        this.path = join(hostStateDir(root), "installs.json");
+        try {
+            if (existsSync(this.path)) {
+                const parsed = readJsonGuarded(this.path, null);
+                const rows = Array.isArray(parsed)
+                    ? parsed
+                    : (parsed && typeof parsed === "object" ? parsed.entries : null);
+                if (Array.isArray(rows)) {
+                    // Re-cleaned on the way IN as well as on the way out. The file is
+                    // plain JSON on a desktop somebody may hand-edit, and a row that
+                    // cannot say what was installed is a gap pretending to be a log line
+                    // wherever it is read.
+                    for (const row of rows) {
+                        const r = row;
+                        if (!r)
+                            continue;
+                        // **A row with no usable `reportedAt` is dropped, not stamped with
+                        // now.** That field is this host's own record of when it was told,
+                        // and substituting the boot instant would sort a hand-edited row to
+                        // the top of the log and then persist the invention — the same
+                        // wrong-number-for-an-absent-one this module refuses for `at`.
+                        const told = r.reportedAt;
+                        if (typeof told !== "number" || !Number.isFinite(told) || told <= 0)
+                            continue;
+                        const clean = cleanInstallEntry(r, { id: String(r.deviceId ?? ""), name: r.deviceName, model: r.deviceModel }, Math.floor(told));
+                        if (clean)
+                            this.entries.push(clean);
+                    }
+                    this.entries = mergeInstallLog([], this.entries).entries;
+                }
+            }
+        }
+        catch { /* corrupt or unreadable → start empty rather than throw */ }
+    }
+    /** Everything, for `install.log`. The devices are DERIVED on every read
+     *  (`installDevices`) rather than kept beside the entries: a device list that
+     *  can disagree with the log is one nobody can trust. */
+    doc() {
+        return { entries: this.entries, devices: installDevices(this.entries), total: this.entries.length };
+    }
+    /**
+     * Fold one phone's report in.
+     *
+     * Answers what CHANGED, so the route can stay quiet when a reconnect
+     * re-states a history the host already holds — which is the common case and
+     * would otherwise broadcast the whole log to every socket on every handshake.
+     */
+    report(reporter, rows) {
+        const now = Date.now();
+        const incoming = [];
+        for (const row of rows) {
+            const clean = cleanInstallEntry(row, reporter, now);
+            if (clean)
+                incoming.push(clean);
+        }
+        // Truncation keeps the NEWEST, not whichever the sender happened to list
+        // first. A phone holding more terminal rows than one report may carry would
+        // otherwise lose the same entries on every report for ever — and which ones
+        // would depend on the order of a list this module has never seen.
+        if (incoming.length > MAX_REPORT_ENTRIES) {
+            incoming.sort((a, b) => entryAt(b) - entryAt(a));
+            incoming.length = MAX_REPORT_ENTRIES;
+        }
+        if (!incoming.length)
+            return { added: 0, updated: 0 };
+        const merged = mergeInstallLog(this.entries, incoming, INSTALL_LOG_CAP);
+        this.entries = merged.entries;
+        if (merged.added || merged.updated)
+            this.schedule();
+        return { added: merged.added, updated: merged.updated };
+    }
+    flush() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.persist();
+    }
+    schedule() {
+        if (this.timer)
+            return;
+        this.timer = setTimeout(() => { this.timer = null; this.persist(); }, SAVE_DEBOUNCE_MS);
+        this.timer.unref?.(); // never hold the daemon open for a log file
+    }
+    persist() {
+        try {
+            mkdirSync(join(this.path, ".."), { recursive: true });
+            writeJsonAtomic(this.path, { entries: this.entries }, { space: 2 });
+        }
+        catch { /* a log that cannot be written must not take the daemon down */ }
+    }
+}
+//# sourceMappingURL=installlog.js.map

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

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

package/packages/host/dist/intents/adapters.d.ts

@@ -0,0 +1,285 @@
+import { type BacklogItem, type BudgetPass, type BudgetWaiver, type BuildRun, type Intent, type IntentDraft, type ItemCategory, type LaunchIntent, type LaunchOpts, type ScheduleEntry, type SessionBudget } from "@waterplane/shared";
+/**
+ * The five vocabularies as filters over one store.
+ *
+ * They used to be DEFINED here, which was right while the host was the only
+ * reader of an `Intent`. It stopped being right when the phone became one: the
+ * DTOs below are lossy — none of them carries `state`, `blockReason` or
+ * `blockDetail` — so a client reading only DTOs had to reconstruct a lifecycle
+ * the host had already decided. Now the classification lives in `@waterplane/shared`
+ * beside the model it classifies, both ends use it, and the reconstruction is
+ * deleted rather than kept in step. Re-exported so no host call site moved.
+ */
+export { isLaunchRow, isScheduleRow, isBacklogRow, isFanoutRow, isBuildRow, isAssessRow, isTimedWorkRow, timedWorkKey, intentKind, ORIGIN_FANOUT_RUN, ORIGIN_FANOUT_TARGET, ORIGIN_FANOUT_FOLLOWUP, } from "@waterplane/shared";
+/**
+ * A `session.create` that names files it cannot run without.
+ *
+ * The id is the create op's own ackId, which is what makes a replayed op upsert
+ * rather than park a second session, and what lets `op.ack` answer with the
+ * same `launchId` both times.
+ */
+export declare function createToIntent(p: {
+    id: string;
+    cwd: string;
+    prompt: string;
+    needs: string[];
+    now: number;
+    cols?: number;
+    rows?: number;
+    title?: string;
+    launch?: unknown;
+    replaceSessionId?: string;
+    budget?: SessionBudget;
+}): IntentDraft;
+/**
+ * One intent as the `LaunchIntent` a client already renders.
+ *
+ * The lifecycle mapping is where the two vocabularies meet, and only one arm of
+ * it is interesting: `running` and `done` both render as `done`, because a
+ * launch's `done` never meant "the turn finished" — it meant the session exists
+ * and the first prompt was handed to `deliverPrompt`.
+ */
+export declare function intentToLaunch(i: Intent): LaunchIntent;
+/** The legacy `launches.json`, converted. Only rows that were still WAITING
+ *  carry work; a settled one is imported too, because its row is the only
+ *  account of what happened to it. */
+export declare function launchesToDrafts(raw: unknown[], now: number): IntentDraft[];
+/**
+ * One saved schedule, as an intent.
+ *
+ * The action maps DIRECTLY onto the intent's own target, which is the sentence
+ * that made `schedule.ts` deletable: a fan-out is a `repos` target, a backlog
+ * add is this repo. The one place it is not literal is that a backlog add takes
+ * `fresh: true` — it needs no session to be ready, because the work item it
+ * queues does that waiting itself — and is routed to the backlog by its
+ * `origin`. See `ORIGIN_SCHEDULE_WORK`.
+ *
+ * `entry` is sanitized through `cleanEntry`'s own helpers first, so a rule from
+ * a hand-edited file or a client one version ahead cannot get in unchecked.
+ *
+ * **The rule is carried WHOLE, both ways, and that is the only reason quiet
+ * hours and the headroom guard need nothing here.** `hours` and `guardWindow`
+ * are clauses on `ScheduleRule`, so they arrive inside `cleanRule(e.rule)` and
+ * leave inside `intentToSchedule`'s `rule: i.trigger.rule` — there is no field
+ * list in this file for them to be forgotten from. That is deliberate and it is
+ * what a round trip is tested for (`intentsched.test.mjs`): the alternative,
+ * naming each clause on the way past, is a file that silently drops whichever
+ * one was added most recently, and a user whose "not before 07:00" vanished the
+ * first time they edited the schedule's name.
+ */
+export declare function scheduleToIntent(raw: unknown, now: number): IntentDraft | null;
+/**
+ * An intent back as the `ScheduleEntry` the sheet edits — for the rows that
+ * sheet can still say something true about.
+ *
+ * A non-`at` row was always `null` here: the schedules list is a view, and a
+ * row it has no vocabulary for is not an entry with fields missing, it is not
+ * an entry. **A TIMED WORK row is now the same answer for the same reason**
+ * (`isTimedWorkRow`): a one-off aimed at one repo has no recurrence to pause,
+ * no next occurrence to skip and no arm/disarm switch that means anything after
+ * its one run — it is a backlog row wearing a clock, and it appears in
+ * `backlog.list` carrying `BacklogItem.at`.
+ *
+ * **`scheduleToIntent` is deliberately unchanged, and so is `schedule.save`.**
+ * The wire is untouched: an APK pinned to an old bundle still saves a one-off
+ * through the schedule vocabulary and still gets its *saved · next run in 2h*
+ * ack (which carries `intentId`). Only the row's CLASSIFICATION moved, which is
+ * derived — so the same entry saved today and edited to *every week* tomorrow
+ * walks back into this function with nothing migrated.
+ */
+export declare function intentToSchedule(i: Intent): ScheduleEntry | null;
+/** The legacy `schedules.json`, converted. */
+export declare function schedulesToDrafts(raw: unknown[], now: number): IntentDraft[];
+/** One line for logs and notifications: what fired, and on what rule. */
+export declare function describeSchedule(i: Intent): string;
+/**
+ * Rows the `backlog.*` messages speak for.
+ *
+ * There is no `origin` marker and deliberately so: a work item is not a special
+ * KIND of intent, it is the plain one — prose, for this repo or one of its
+ * sessions, to run as soon as that session can take it. Anything that fits that
+ * description belongs in the backlog list whoever posted it, which is what makes
+ * the sheet a view of the store rather than a second store with a view.
+ *
+ * The exclusions are the rows that have their own surface and would appear
+ * twice: a parked create (`files`), a standing rule (`at`), a build, and a
+ * fan-out's targets — those belong to their run.
+ */
+/** The check/validate verdicts, which are not lifecycle and do not live on the
+ *  intent — see `review.ts`. Merged in here so the wire DTO still carries them
+ *  exactly where `BacklogItem` did. */
+export type ReviewSidecar = Partial<Pick<BacklogItem, "checkStatus" | "checkNote" | "checkDetail" | "checkedAt" | "validateStatus" | "validateNote" | "validateDetail" | "validateSteps" | "validatedAt">>;
+/**
+ * One intent as the `BacklogItem` a client already renders.
+ *
+ * The lifecycle mapping is where the two vocabularies meet, and the interesting
+ * arms are the ends: `starting` is `running` (the item HAS been picked up — the
+ * screen said "running" while `deliverPrompt` was typing long before this
+ * store existed), and `canceled` is `failed`, because the backlog never had a
+ * third terminal word and a row that vanished into an unknown status would be
+ * the one thing this rework exists to prevent.
+ */
+export declare function intentToBacklogItem(i: Intent, review?: ReviewSidecar): BacklogItem;
+/**
+ * A new work item, as an intent.
+ *
+ * Four decisions ride on the row: WHERE (a named session, or — the default now —
+ * a session opened FOR this item), whether that new session picks up the repo's
+ * last conversation (`resume`), whether the global auto-fire switch has a say
+ * (`pinned` — see `Intent.pinned`), and the whole chain if there is one.
+ *
+ * `steps` is the WHOLE chain and `steps[0]` repeats `text`, so a caller that
+ * knows nothing about chains still gets the one-turn item it always got. It is
+ * ONE item carrying N turns rather than N items: `deliverChain` puts them on
+ * separate turns in the order given, and N rows would have been N sessions.
+ *
+ * `serial` is set for a repo-target row and only for one, which is the whole of
+ * "one at a time in this repo". It was free while every item in a repo shared
+ * one session — rung 5 would not type a second prompt into a session already
+ * holding an intent — and it stopped being free the moment each item opened its
+ * own: nothing in the ladder would otherwise stop five due items in one repo
+ * spawning five agents into one worktree at the same instant. A `session`-target
+ * row does NOT get it: those still serialize on the session itself, and holding
+ * them for the whole repo would make *queue here* wait on work it has nothing to
+ * do with.
+ */
+export declare function backlogDraft(p: {
+    id: string;
+    cwd: string;
+    text: string;
+    label?: string;
+    targetSessionId?: string;
+    autoFire?: boolean;
+    order: number;
+    steps?: readonly string[];
+    resume?: boolean;
+    /** Close the session this item opens once done; absent follows the global
+     *  setting (`Intent.closeWhenDone`). `false` is kept — it is an answer. */
+    closeWhenDone?: boolean;
+    /** Flag the session for follow up once done (`Intent.flagWhenDone`); absent = off. */
+    flagWhenDone?: boolean;
+    /** The budget the session this item opens is born with (`Intent.budget`).
+     *  Meaningless on a row aimed at a live session, so it is dropped there. */
+    budget?: SessionBudget;
+    /** The model/effort/backend the session this item opens starts with
+     *  (`Intent.launch`). Dropped on a row aimed at a live session, like the
+     *  budget: that session is already running whatever it runs. */
+    launch?: LaunchOpts;
+    /**
+     * The other half of *wait until it's free*, when the item is being created BY
+     * a row that was ticked that way — a schedule, today (F14).
+     *
+     * Only one half travels, because the other is already here: a repo-target
+     * item is `serial` by construction (below), so a schedule's `serial` is
+     * satisfied before it is asked for. `holdForHost` is the flag that had
+     * nothing to carry it. A schedule ticked *wait until it's free* whose action
+     * is "add a backlog item" was holding the creation of the ROW — which is
+     * instantaneous and never busy — and the item it created then fired into
+     * whatever else the desktop was doing, with nothing holding it at all. The
+     * tick gated the wrong event.
+     */
+    holdForHost?: boolean;
+    /** A waiver a person already gave (`Intent.pastBudget`), window and all —
+     *  carried by the row the HOST makes out of a row that had one: a
+     *  recurring rule's child. */
+    pastBudget?: BudgetWaiver;
+    /** The before-reset lift a recurring rule's occurrence carries
+     *  (`Intent.budgetPass`, stamped by `workItemInherits`). */
+    budgetPass?: BudgetPass;
+    /** A leftover of this reset week (`Intent.leftoverOf`) — host-written only;
+     *  `intent.post` strips it off the wire. */
+    leftoverOf?: number;
+    /**
+     * What to CALL the row, for the one caller that is making a row nobody typed:
+     * an assessment posting a merge or a genuinely new item.
+     *
+     * `nameBy` travels with the pair rather than being defaulted here, because a
+     * value with no author is a title that cannot say whether it may be replaced
+     * (`naming.ts`) — and defaulting it would be this file deciding who wrote
+     * something, which is the one thing nothing but a call site knows. Absent
+     * `nameBy`, or absent words, and the row is posted with no name at all: that
+     * is the honest shape for `add()`'s rows, where the words ARE the person's.
+     */
+    headline?: string;
+    category?: ItemCategory;
+    nameBy?: "assess" | "name";
+}): IntentDraft;
+/**
+ * What a RECURRING schedule's *add a backlog item* action hands to the item it
+ * creates, once per occurrence.
+ *
+ * Recurring is now the whole of its scope: a one-off with a backlog action is
+ * an `isTimedWorkRow` and runs ITSELF (`manager.execute`), so it has no child
+ * to hand anything to. A standing rule still does — the rule outlives each
+ * occurrence, so each occurrence needs a row of its own to be the account of.
+ *
+ * A seam rather than three lines inside the executor, because it is the whole
+ * of F14 and F14 was invisible: the parent row is where the tick is set and the
+ * CHILD is where the work happens, so a gate that stays on the parent gates the
+ * making of a row — instantaneous, never busy, always allowed — while the work
+ * it was written for runs into whatever else the desktop was doing. Nothing on
+ * a screen says so; the parent reports "queued" and is telling the truth.
+ *
+ * Three things travel and one deliberately does not. The CHAIN travels whole
+ * (`steps`), because only `steps[0]` used to reach the child and a scheduled
+ * three-step prompt silently became a one-step one. `resume` travels because it
+ * is a statement about the conversation the work runs in, and `closeWhenDone`
+ * beside it because it is a statement about the session that conversation is in. `holdForHost`
+ * travels because nothing else carries it. `serial` does NOT need to: every
+ * repo-target item is serial by construction (`backlogDraft`), so it is
+ * satisfied before it is asked for — and a schedule aimed at a repo has no
+ * other shape of child.
+ *
+ * `pastBudget` travels for `holdForHost`'s reason: a person who let the rule
+ * past the budget meant the WORK, and the work is the child — with the same
+ * `until`, so the child is let past THAT window and no later one. The parent's
+ * own waiver is cleared once the fire that mints the child returns
+ * (`manager.fire`), so it covers exactly this one occurrence.
+ *
+ * `budgetPass` travels too, and is STAMPED rather than inherited as a flag: a
+ * `before`-edge window rule's occurrence may run past that window's ceiling
+ * until the reset it was timed ahead of (`budgetPassOf` on the parent's own
+ * clock). The child has no clock to read it off, so it gets the occurrence and
+ * the reset from `lastOccurrence` — written before the executor, so it IS the
+ * occurrence being fired — or the cap the parent was exempt from would hold
+ * the work it was exempt for. Nothing for any other rule.
+ */
+export declare function workItemInherits(i: Intent): {
+    steps: readonly string[];
+    resume?: boolean;
+    closeWhenDone?: boolean;
+    flagWhenDone?: boolean;
+    budget?: SessionBudget;
+    launch?: LaunchOpts;
+    holdForHost?: boolean;
+    pastBudget?: BudgetWaiver;
+    budgetPass?: BudgetPass;
+};
+/**
+ * The legacy `<repoDir>/.waterplane/backlog.json`, converted.
+ *
+ * Everything is carried: a settled item keeps its verdict and its timestamps,
+ * because that row is the only account of what happened to it. The two fields
+ * that are NOT carried are the two the old loader already dropped on every
+ * boot — a per-boot `targetSessionId` and the per-item auto flag that was bound
+ * to it — for the reason it gave: they meant "in THAT session", and that
+ * session died with the process that wrote the file.
+ */
+export declare function backlogToDrafts(raw: unknown, repoDir: string | null, now: number): IntentDraft[];
+/** The check/validate fields of a legacy item, which move to the review
+ *  sidecar rather than onto the intent — they are verdicts about work that has
+ *  settled, not lifecycle. */
+export declare function backlogReviews(raw: unknown): Record<string, ReviewSidecar>;
+/** `fanoutRuns` MOVED to `@waterplane/shared` — the phone rebuilds runs from the same
+ *  rows now, so the aggregate is computed once from one implementation instead
+ *  of being projected here and shipped alongside the rows it came from. */
+export { fanoutRuns } from "@waterplane/shared";
+/**
+ * One intent as the `BuildRun` the sheet streams output into.
+ *
+ * `runId` is the intent id, which is what keeps `build.output` frames — keyed by
+ * run — unchanged on the wire. The name, command and working dir come off the
+ * payload rather than off today's `builds.json`, because a run row that renames
+ * itself when the config is edited is a lie about what ran.
+ */
+export declare function intentToBuildRun(i: Intent): BuildRun;