@netnodeag/kraftwerk 0.76.0 → 0.78.0

package/dist/server/cloud.d.ts

@@ -1,53 +1,124 @@
+import { type Credentials, type CloudUrlSource, type InviteResponse } from "../core/cloud.js";
 /**
- * The cloud manager client: kraftwerk.yml `cloud:` makes this instance
- * register with the kraftwerk cloud when the inspector starts and heartbeat
- * while it runs — the same record ~/.kraftwerk/instances holds locally,
- * kept on a server so an admin (and, with an account token, the user)
- * sees every instance across machines.
+ * The machine client: the daemon registers THIS MACHINE with the kraftwerk
+ * cloud once and heartbeats while it runs; the workspaces it serves ride
+ * along as children of that record (see core/cloud.ts for the contract and
+ * the settings). One per process, and only the daemon starts it
+ * (startMachineCloud from `kraftwerk daemon`): a standalone `kraftwerk ui`
+ * and test fixtures never talk to the cloud.
  *
- * Identity: the first registration hands out an id + secret, stored under
- * ~/.kraftwerk/cloud/<hash(url, root)>.json and presented on every later
- * call, so a restart updates the record instead of creating a new one.
- * When the cloud does not recognise the id (data reset) it hands out a
- * fresh one and the file is rewritten.
- *
- * Everything is best-effort: a cloud that is down never affects the UI.
- * The status is reported in /api/meta so the UI can show it.
+ *   start      ensure the machine key (relay.json, relay stays off), drop the
+ *              retired per-workspace identities (~/.kraftwerk/cloud/), and,
+ *              unless cloud.json or KRAFTWERK_CLOUD_URL=off says no, register
+ *              — anonymous: the answer carries a claim code until someone
+ *              claims the machine (`kraftwerk login`, or the code in the UI)
+ *   heartbeat  every `interval` the cloud asked for; the workspace list rides
+ *              along whenever it changed (opened, closed, vetoed, claimed).
+ *              A claim made in the cloud arrives in the answer
+ *   privacy    while unclaimed, entries carry name/slug/ws-id only — no
+ *              roots; once claimed, roots too, and the routines that ran
+ *              here (`routines`, sent when it changed; private ones never)
+ *   members    the machine's credentials and the served workspaces are
+ *              what member sessions over the relay are verified with
+ *              (server/members.ts), and what `kraftwerk invite` asks the
+ *              cloud with (createWorkspaceInvite)
+ *   recovery   a cloud that no longer knows the machine (data reset) gets a
+ *              fresh registration; a cloud that is down is retried at the
+ *              same cadence and never affects the UI
+ *   goodbye    on shutdown (bounded), and when `kraftwerk cloud off` reaches
+ *              the running daemon
  */
 export type CloudState = "off" | "connecting" | "connected" | "error";
 export interface CloudStatus {
     url: string;
     state: CloudState;
-    /** Last error message while connecting or heartbeating. */
+    /** Why it is off, when it is. */
+    reason?: string;
+    /** Where the URL came from (env, cloud.json, a deprecated kraftwerk.yml cloud.url, the default). */
+    source?: CloudUrlSource;
+    /** Last error message while registering or heartbeating. */
     error?: string;
-    /** Instance id in the cloud once registered. */
+    /** The machine's id in the cloud (its relay id). */
     id?: string;
-    /** Email of the linked kraftwerk account, when a token was presented and accepted. */
+    /** This machine's handle@machine. */
+    machine?: string;
+    /** Email of the account that claimed the machine; null while unclaimed. */
     account?: string | null;
-    /** Effective seconds between heartbeats (the cloud may raise the configured one). */
+    /** Effective seconds between heartbeats (what the cloud asked for). */
     interval?: number;
+    /** Last successful register or heartbeat. */
     lastSeen?: string;
-    /** XXXX-XXXX the user types into the cloud UI to claim this instance; null once claimed. */
+    /** XXXX-XXXX that claims this machine in the cloud; null once claimed. */
     claimCode?: string | null;
-    /** The cloud page that claims this instance after sign-in. */
+    /** The cloud page that claims this machine after sign-in. */
     claimUrl?: string | null;
+    /** Workspaces reported (vetoed ones left out). */
+    workspaces?: number;
 }
+/** What the daemon serves right now; `ws` runs code inside that workspace (the routine report reads its state). */
+export type WorkspaceSource = () => Array<{
+    root: string;
+    slug: string;
+    name: string;
+    ws?: {
+        run<T>(fn: () => T): T;
+    };
+}>;
 export declare const cloudStatus: () => CloudStatus;
 /**
- * Start the client once the inspector listens. Resolves after the first
- * registration attempt (success or not); the heartbeat loop runs on its
- * own afterwards.
+ * Start the machine client (the daemon, once its workspaces are open).
+ * Resolves after the first registration attempt; the heartbeat runs on its
+ * own afterwards. A second start in the same process is ignored.
+ */
+export declare function startMachineCloud(opts: {
+    version: string;
+    workspaces: WorkspaceSource;
+    owner?: unknown;
+}): Promise<CloudStatus>;
+/**
+ * Settings changed (`kraftwerk cloud on|off`, a URL): turn the client on or
+ * off to match; off says goodbye first. Without a started client (a
+ * standalone server) nothing happens.
+ */
+export declare function applyMachineCloud(): Promise<CloudStatus>;
+/** A round now (the CLI's `login` waits for a claim): registers when needed, else heartbeats. */
+export declare function syncMachineCloud(): Promise<CloudStatus>;
+/** Release the claim (`kraftwerk logout`): the cloud hands out a fresh claim code. */
+export declare function unlinkMachineCloud(): Promise<CloudStatus>;
+/**
+ * Stop the client and tell the cloud the machine is going away (bounded:
+ * an exit handler waits for this). `owner`: only the client that owner
+ * started (a hub stopping in a test leaves another's alone).
+ */
+export declare function stopMachineCloud(owner?: unknown): Promise<void>;
+/**
+ * What member verification needs (server/members.ts): the cloud's origin,
+ * this machine's credentials. Null when no machine client runs (a
+ * standalone server, the cloud turned off).
  */
-export declare function startCloudSync(url: string, version: string): Promise<void>;
-/** Stop the heartbeat loop (server close, tests). */
-export declare function stopCloudSync(): void;
+export declare function machineLink(): {
+    url: string;
+    creds: Credentials;
+    version: string;
+} | null;
+/** The served workspace whose kraftwerk.yml `id` is `id` (vetoed ones not), or null. */
+export declare function servedWorkspace(id: string): Promise<{
+    slug: string;
+    name: string;
+    root: string;
+} | null>;
 /**
- * Tell the cloud we are going away, so the record flips to "stopped" now
- * instead of after the grace period. Bounded: an exit handler waits for
- * this, and a slow cloud must not hold the process.
+ * An invite to a served workspace (`kraftwerk invite`): the cloud's machine
+ * path, so only a claimed machine that reports the workspace gets one.
+ * `which` is the workspace's slug or root.
  */
-export declare function cloudGoodbye(): Promise<void>;
-/** Every served workspace: stop its heartbeat (the server closes). */
-export declare function stopAllCloudSync(): void;
-/** Every served workspace says goodbye, in parallel (still bounded per workspace). */
-export declare function cloudGoodbyeAll(): Promise<void>;
+export declare function createWorkspaceInvite(which: {
+    slug?: string;
+    root?: string;
+}, role?: "owner" | "member"): Promise<InviteResponse & {
+    workspace: {
+        id: string;
+        slug: string;
+        name: string;
+    };
+}>;