waterplane 0.0.1 → 0.1.6

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

@@ -0,0 +1,36 @@
+/**
+ * The Android background link: a socket that is only there to raise alerts.
+ *
+ * The APK's native `ShellLinkService` holds its own WebSocket so notifications
+ * arrive with the app closed, and acts on exactly three inbound frames. Every
+ * other frame the host sends it wakes the phone's radio and CPU only to be
+ * thrown away — and that socket never sleeps. So the host marks it, and sends
+ * it the allow-list below and nothing else (`server/clients.ts`'s `send`).
+ *
+ * Two ways a socket becomes one, the explicit one winning:
+ * - `hello.role: "notify"` (an APK built after 2026-10-13);
+ * - a `User-Agent` starting `okhttp/` at the upgrade — the WebView sends a
+ *   Chrome UA, OkHttp its own. That is what covers every APK already installed,
+ *   which says nothing about its role and does not update with the bundle.
+ */
+/** The one role a socket may declare today. Absent ⇒ a full client. */
+export type ClientRole = "notify";
+/**
+ * What a notify link is sent. The three `ShellLinkService.onFrame` reads, plus
+ * `pong` — sent only when the socket ASKED with `{t:"ping"}`, so a link that
+ * keeps a JSON heartbeat is not torn down for lack of an answer. No
+ * `notification.list`: the service posts each `notification` as it comes and
+ * dedupes by tag; it never replays a feed.
+ */
+export declare const NOTIFY_LINK_FRAMES: ReadonlySet<string>;
+/** The client frames a notify link may send. Anything else (an attach above
+ *  all) is ignored, so the link can never count as somebody watching. */
+export declare const NOTIFY_LINK_INBOUND: ReadonlySet<string>;
+/** May a socket in this role be sent a frame of this type? */
+export declare function roleAllows(role: ClientRole | undefined, t: string): boolean;
+/** May a socket in this role send this client frame? */
+export declare function roleAccepts(role: ClientRole | undefined, t: string): boolean;
+/** The role guessed at upgrade, before any frame: OkHttp is the native link. */
+export declare function roleFromUserAgent(ua: string | string[] | undefined): ClientRole | undefined;
+/** The role after `hello`: an explicit one wins, else whatever the upgrade said. */
+export declare function roleAfterHello(declared: unknown, upgraded: ClientRole | undefined): ClientRole | undefined;

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

@@ -0,0 +1,44 @@
+/**
+ * The Android background link: a socket that is only there to raise alerts.
+ *
+ * The APK's native `ShellLinkService` holds its own WebSocket so notifications
+ * arrive with the app closed, and acts on exactly three inbound frames. Every
+ * other frame the host sends it wakes the phone's radio and CPU only to be
+ * thrown away — and that socket never sleeps. So the host marks it, and sends
+ * it the allow-list below and nothing else (`server/clients.ts`'s `send`).
+ *
+ * Two ways a socket becomes one, the explicit one winning:
+ * - `hello.role: "notify"` (an APK built after 2026-10-13);
+ * - a `User-Agent` starting `okhttp/` at the upgrade — the WebView sends a
+ *   Chrome UA, OkHttp its own. That is what covers every APK already installed,
+ *   which says nothing about its role and does not update with the bundle.
+ */
+/**
+ * What a notify link is sent. The three `ShellLinkService.onFrame` reads, plus
+ * `pong` — sent only when the socket ASKED with `{t:"ping"}`, so a link that
+ * keeps a JSON heartbeat is not torn down for lack of an answer. No
+ * `notification.list`: the service posts each `notification` as it comes and
+ * dedupes by tag; it never replays a feed.
+ */
+export const NOTIFY_LINK_FRAMES = new Set(["notification", "authRequired", "pull.new", "pong"]);
+/** The client frames a notify link may send. Anything else (an attach above
+ *  all) is ignored, so the link can never count as somebody watching. */
+export const NOTIFY_LINK_INBOUND = new Set(["hello", "ping"]);
+/** May a socket in this role be sent a frame of this type? */
+export function roleAllows(role, t) {
+    return role !== "notify" || NOTIFY_LINK_FRAMES.has(t);
+}
+/** May a socket in this role send this client frame? */
+export function roleAccepts(role, t) {
+    return role !== "notify" || NOTIFY_LINK_INBOUND.has(t);
+}
+/** The role guessed at upgrade, before any frame: OkHttp is the native link. */
+export function roleFromUserAgent(ua) {
+    const s = Array.isArray(ua) ? ua[0] : ua;
+    return typeof s === "string" && /^okhttp\//i.test(s) ? "notify" : undefined;
+}
+/** The role after `hello`: an explicit one wins, else whatever the upgrade said. */
+export function roleAfterHello(declared, upgraded) {
+    return declared === "notify" ? "notify" : upgraded;
+}
+//# sourceMappingURL=notifylink.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"notifylink.js","sourceRoot":"","sources":["../../src/wire/notifylink.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAwB,IAAI,GAAG,CAAC,CAAC,cAAc,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;AAErH;yEACyE;AACzE,MAAM,CAAC,MAAM,mBAAmB,GAAwB,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;AAEnF,8DAA8D;AAC9D,MAAM,UAAU,UAAU,CAAC,IAA4B,EAAE,CAAS;IAChE,OAAO,IAAI,KAAK,QAAQ,IAAI,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AACxD,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,WAAW,CAAC,IAA4B,EAAE,CAAS;IACjE,OAAO,IAAI,KAAK,QAAQ,IAAI,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AACzD,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,iBAAiB,CAAC,EAAiC;IACjE,MAAM,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACzC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9E,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,cAAc,CAAC,QAAiB,EAAE,QAAgC;IAChF,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;AACrD,CAAC"}

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

@@ -0,0 +1,121 @@
+/**
+ * The first-app onboarding job on the wire (`docs/analysis/first-app-plan.md`, WP6).
+ *
+ * One host-side job (`packages/host/src/onboard.ts`) turns three answers and one consent screen
+ * into a repo, a build and a session. The phone reads the PLAN before the consent screen
+ * (`GET /api/onboard/plan`), starts the job (`POST /api/onboard`), and follows it as
+ * `onboard.progress` frames over the one socket, or `GET /api/onboard` after a reconnect. Every
+ * step is a sentence; a stopped step names its fix.
+ */
+/** Which journey: an Android app (template `android-hello`) or a web page (`web-hello`). */
+export type OnboardPath = "android" | "web";
+/** The person's answers from the three questions. */
+export interface OnboardAnswers {
+    /** The app name; becomes the folder `<root>/<name>` and the package segment. */
+    name: string;
+    path: OnboardPath;
+    /** "Describe what you want": becomes the new session's FIRST prompt, after the first build. */
+    description?: string;
+    /** "Set this repo up for waterplane" (default on): the setup checklist's one-tap fixes, as one step. */
+    setup?: boolean;
+}
+/**
+ * The consent screen's ticks, one per line it showed. The host REFUSES a start whose plan needs a
+ * line that is not `true` (`repo` always; `toolchain` and `signingKey` when the plan lists them).
+ * `session: false` is allowed: that step is then skipped, said so, and nothing runs `claude`.
+ * `installApps` is the phone's own (the allow-list and Android's setting); the host records it.
+ */
+export interface OnboardConsent {
+    repo?: boolean;
+    /** Download and install the toolchain AND accept Google's SDK licence on the person's behalf. */
+    toolchain?: boolean;
+    signingKey?: boolean;
+    installApps?: boolean;
+    session?: boolean;
+}
+export type OnboardConsentId = "repo" | "toolchain" | "signingKey" | "installApps" | "session";
+/** One line of the consent screen: shown only if it applies to this desktop. */
+export interface OnboardConsentLine {
+    id: OnboardConsentId;
+    /** What it does, in one sentence the screen shows as is. */
+    what: string;
+    /** Where it lands on this desktop (a folder), when it writes anything. */
+    where?: string;
+    /** About how much is downloaded (derived, an estimate shown as "about"). */
+    bytes?: number;
+    /** The licence text, for the line that accepts one. */
+    link?: string;
+    /** The start is refused without this tick. */
+    required: boolean;
+    /** Acted on by the phone, not the desktop. */
+    phone?: boolean;
+}
+export type OnboardStepId = "probe" | "toolchain" | "scaffold" | "signing-key" | "setup" | "build" | "session";
+export type OnboardStepStatus = "pending" | "running" | "done" | "skipped" | "failed" | "needs-you" | "needs-consent";
+export interface OnboardStep {
+    id: OnboardStepId;
+    status: OnboardStepStatus;
+    /** What the step does, said before it runs ("First build: the slow one, about 5 minutes"). */
+    what: string;
+    /** What happened, or why it stopped. */
+    note?: string;
+    /** `needs-you`: the exact command the person must run; `failed`: the do-it-yourself command.
+     *  Never run by the host. */
+    command?: string;
+    startedAt?: number;
+    endedAt?: number;
+}
+/** What `GET /api/onboard/plan` answers: the steps that apply here, and the consent lines. */
+export interface OnboardPlan {
+    ok: boolean;
+    /** The refusal in words (bad name, folder exists, broken key…); `ok:false`. */
+    error?: string;
+    path: OnboardPath;
+    /** The cleaned name and the folder it becomes. */
+    name: string;
+    folder: string;
+    /** Android only. */
+    packageId?: string;
+    steps: Array<{
+        id: OnboardStepId;
+        needed: boolean;
+        what: string;
+    }>;
+    consent: OnboardConsentLine[];
+    /** What the session's first prompt will be (the description), or the suggestion offered. */
+    firstPrompt?: string;
+    suggestedPrompt: string;
+    /** Set when claude is NOT signed in on this desktop: the sentence saying how to sign in from
+     *  the phone. The job still runs; its session would stop at the sign-in screen. Absent when
+     *  signed in, when the answer could not be read, and from an older desktop. */
+    signIn?: string;
+    /** One-shot token for `POST /api/onboard` `{ answers, consent, confirm }`, bound to this path and
+     *  to the consent ids listed above (`host/confirmgate.ts`). Absent from an older desktop. */
+    confirm?: string;
+}
+export type OnboardJobState = "running" | "done" | "stopped";
+export interface OnboardJob {
+    id: string;
+    state: OnboardJobState;
+    answers: OnboardAnswers;
+    consent: OnboardConsent;
+    name: string;
+    folder: string;
+    packageId?: string;
+    steps: OnboardStep[];
+    /** Set once the scaffold step made it. */
+    repoDir?: string;
+    repoId?: string;
+    /** The first build's run (`build.output`/`build.run` frames carry the same id). */
+    buildRunId?: string;
+    /** Repo-relative path of what the build left for the phone (the APK or the HTML in the outbox). */
+    artifact?: string;
+    /** The session opened in the new repo, once known; `intentId` when it opens through the store. */
+    sessionId?: string;
+    intentId?: string;
+    suggestedPrompt: string;
+    /** One sentence: where the job is. */
+    summary: string;
+    createdAt: number;
+    updatedAt: number;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * The first-app onboarding job on the wire (`docs/analysis/first-app-plan.md`, WP6).
+ *
+ * One host-side job (`packages/host/src/onboard.ts`) turns three answers and one consent screen
+ * into a repo, a build and a session. The phone reads the PLAN before the consent screen
+ * (`GET /api/onboard/plan`), starts the job (`POST /api/onboard`), and follows it as
+ * `onboard.progress` frames over the one socket, or `GET /api/onboard` after a reconnect. Every
+ * step is a sentence; a stopped step names its fix.
+ */
+export {};
+//# sourceMappingURL=onboard.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"onboard.js","sourceRoot":"","sources":["../../src/wire/onboard.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}