slopkit 0.3.0 → 0.4.0-rc.0

package/dist/server/cli.d.ts

@@ -0,0 +1,117 @@
+import type { WebConfig } from "./config.ts";
+import { Jobs } from "./jobs.ts";
+import type { Job, JobEnd } from "./jobs.ts";
+import { Log } from "./log.ts";
+import type { Logger } from "./log.ts";
+/** What a release says of itself: its version and the store schema it writes (`<name> version --json`). */
+export type ReleaseInfo = {
+    version: string;
+    schema: number;
+};
+export type Installed = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+    tail: string[];
+};
+/** The automatic rollback that put `version` in place, if it is the one running: what it replaced and when. */
+export declare function rolledBackTo(home: string, version: string): {
+    from: string;
+    at: string;
+} | null;
+/** Whether a server holds the home's lock, without creating the lock file. */
+export declare function running(home: string): boolean;
+/** What an update job leaves when done: the release it installed and the version it replaced. */
+export type UpdateResult = {
+    release?: string;
+    from?: string;
+};
+/** How one update job ended, as a server reports it. */
+export type UpdateRecord = {
+    job: number;
+    release: string;
+    from: string;
+    result: "installed" | "failed";
+    reason: string | null;
+    at: string;
+};
+/** An update job (`slopkit/server/jobs`, kind `update`): one open at a time; every tap while it is open joins it. */
+export declare const UPDATE_KIND = "update";
+/** An update job asked for, and whether it is still due to run. */
+export type AskedUpdate = {
+    id: number;
+    due: boolean;
+};
+/** Ask for an update to `release` from `version` (joins one already open): the job's id, and whether still due. */
+export declare function askUpdate(jobs: Jobs<UpdateResult>, release: string, version: string, by: {
+    client: string;
+    id: number;
+}, now?: number): AskedUpdate;
+/** Claim the asked update before the server stops: running, "installing <release> from <version>", committed. */
+export declare function beginUpdate(jobs: Jobs<UpdateResult>, version: string): {
+    id: number;
+    release: string;
+    from: string;
+} | undefined;
+/**
+ * At start, before serving: how an update job a stop left running is settled. The install began: installed when this
+ * is another version than the one it replaced (the reconciliation read), else failed as interrupted.
+ */
+export declare function recoverUpdate(job: Job<UpdateResult>, version: string): JobEnd<UpdateResult>;
+/** At start, after running jobs are settled: an update still due failed, nothing changed. Returns how many. */
+export declare function settleAskedUpdates(jobs: Jobs<UpdateResult>): number;
+/** The newest `kept` finished updates, newest first. */
+export declare function updateRecords(jobs: Jobs<UpdateResult>, kept: number): UpdateRecord[];
+/** The open update job's id, if one is asked or installing. */
+export declare function updating(jobs: Jobs<UpdateResult>): number | null;
+/** The newer `edge` commit when this is an edge build behind it; a hint only, nothing installs it. */
+export declare function newerEdge(root: URL | string, env?: Readonly<Record<string, string | undefined>>): Promise<string | undefined>;
+/** What an app's `serve` gets: its home, what it is, the log, the web settings, and a way to ask for an update. */
+export type ServeContext = {
+    home: string;
+    version: string;
+    log: Log;
+    /** The server's own log lines (`server`). */
+    say: Logger;
+    /** `web.json`, or why the web is off. */
+    web: WebConfig | {
+        off: string;
+    };
+    env: Readonly<Record<string, string | undefined>>;
+    /** Stop the server for the update the app's store has asked (`askUpdate`), then start the same command again. */
+    update: () => void;
+};
+/** What an app's `serve` hands back once it serves. */
+export type Served = {
+    /** Its web server's address, when it has one. */
+    url?: string;
+    close: () => Promise<void>;
+    /** The asked update job, claimed running before anything stops (`beginUpdate`). */
+    claim?: () => {
+        id: number;
+        release: string;
+    } | undefined;
+};
+export type CliOptions = {
+    /** The binary's name: `<NAME>_HOME`, `~/.<name>`, `<name>.sqlite`, `<name>.tgz`. */
+    name: string;
+    /** The installed package's directory (`new URL("../", import.meta.url)`). */
+    root: URL | string;
+    /** The store schema this release writes (`schemaVersion`). */
+    schema: number;
+    /** What `serve` does, for the help: "<name> serve: Run the server on the home: <serves>". */
+    serves: string;
+    serve: (context: ServeContext) => Promise<Served>;
+    /** The app's own commands, beside the kit's. */
+    commands?: Record<string, {
+        usage: string;
+        help: string;
+        run: (args: string[], home: string) => Promise<number>;
+    }>;
+    env?: Readonly<Record<string, string | undefined>>;
+    /** How long a server stays up before its release is proven here (default an hour). */
+    provenAfterMs?: number;
+};
+/** Run the command line: the exit code. */
+export declare function runCli(args: readonly string[], options: CliOptions): Promise<number>;