@greatwait/cli 0.1.0-alpha.3

package/dist/runtime.d.ts

@@ -0,0 +1,63 @@
+import type { FetchLike } from "@greatwait/api-client";
+/**
+ * Everything this command touches that is not a pure function.
+ *
+ * **A parameter rather than an import, and the reason is criterion 7.** The
+ * cases this story has to answer are a browser that will not open, a callback
+ * that never arrives, a Ctrl-C halfway through a wait, a deadline passing, and
+ * a configuration directory on a platform the test is not running on. Every one
+ * of those is a fact about the surroundings, and a suite that could not
+ * construct them would be asserting the happy path and calling it coverage.
+ */
+export interface CliRuntime {
+    readonly argv: readonly string[];
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly fetch: FetchLike;
+    /** The user's home directory, for the configuration path. */
+    readonly home: string;
+    /** Whether standard input is a terminal, which decides prompting. */
+    readonly interactive: boolean;
+    /** Opens a loopback listener for one authorization redirect. */
+    readonly listen: () => Promise<LoopbackListener>;
+    readonly now: () => number;
+    /** Hands a URL to the platform's browser. Rejects when there is none. */
+    readonly openBrowser: (url: string) => Promise<void>;
+    readonly platform: string;
+    /** Reads one line without echoing it. Only ever used for a secret. */
+    readonly promptSecret: (question: string) => Promise<string>;
+    readonly randomBytes: (length: number) => Uint8Array;
+    readonly randomUuid: () => string;
+    /** Everything piped in, for a secret supplied non-interactively. */
+    readonly readStdin: () => Promise<string>;
+    /** Aborted on Ctrl-C. Every wait in this command is bound to it. */
+    readonly signal: AbortSignal;
+    readonly sleep: (milliseconds: number, signal: AbortSignal) => Promise<void>;
+    readonly stderr: (text: string) => void;
+    readonly stdout: (text: string) => void;
+    /** `undefined` where a file mode says nothing about who may read it. */
+    readonly uid: number | undefined;
+}
+export interface LoopbackListener {
+    /** Resolves with the redirect's query, or rejects if the wait is abandoned. */
+    readonly received: Promise<URLSearchParams>;
+    readonly close: () => void;
+    readonly redirectUri: string;
+}
+/** Raised where the reason is already a sentence a person can act on. */
+export declare class CliError extends Error {
+    readonly exit: "authentication" | "authorization" | "internal" | "retryable" | "timeout" | "usage" | "validation";
+    readonly nextMove: string | undefined;
+    constructor(message: string, exit: CliError["exit"], nextMove?: string);
+}
+/** Raised when the abort signal fires, so every wait ends the same way. */
+export declare class InterruptedError extends Error {
+    constructor();
+}
+/**
+ * Waits, and gives up when the signal fires rather than when the timer ends.
+ *
+ * The whole reason Ctrl-C is a criterion: a poll that only checks its signal
+ * between sleeps leaves a person holding a terminal for up to one interval
+ * after they asked it to stop, and the published interval here is five seconds.
+ */
+export declare function sleepOrAbort(runtime: CliRuntime, milliseconds: number): Promise<void>;

package/dist/runtime.js

@@ -0,0 +1,32 @@
+/** Raised where the reason is already a sentence a person can act on. */
+export class CliError extends Error {
+    exit;
+    nextMove;
+    constructor(message, exit, nextMove) {
+        super(message);
+        this.name = "CliError";
+        this.exit = exit;
+        this.nextMove = nextMove;
+    }
+}
+/** Raised when the abort signal fires, so every wait ends the same way. */
+export class InterruptedError extends Error {
+    constructor() {
+        super("interrupted");
+        this.name = "InterruptedError";
+    }
+}
+/**
+ * Waits, and gives up when the signal fires rather than when the timer ends.
+ *
+ * The whole reason Ctrl-C is a criterion: a poll that only checks its signal
+ * between sleeps leaves a person holding a terminal for up to one interval
+ * after they asked it to stop, and the published interval here is five seconds.
+ */
+export async function sleepOrAbort(runtime, milliseconds) {
+    if (runtime.signal.aborted)
+        throw new InterruptedError();
+    await runtime.sleep(milliseconds, runtime.signal);
+    if (runtime.signal.aborted)
+        throw new InterruptedError();
+}

package/dist/session.d.ts

@@ -0,0 +1,66 @@
+import { type DefaultGreatwaitClient } from "@greatwait/api-client";
+import { type CredentialStore } from "./config.js";
+import { type CliRuntime } from "./runtime.js";
+/**
+ * Which service this command is talking to, and what it presents to it.
+ *
+ * **Two questions, resolved separately and both refusable.** Merging them is
+ * how a command ends up presenting a staging credential to production: a single
+ * "current context" that carried both would be one value to get wrong, and the
+ * value that must never be wrong is which origin a secret is sent to. So the
+ * origin is chosen first, and the credential is whatever that origin has.
+ */
+/** Environment names, stated once so nothing else spells one. */
+export declare const ENVIRONMENT_NAMES: {
+    readonly apiKey: "GREATWAIT_API_KEY";
+    readonly apiUrl: "GREATWAIT_API_URL";
+};
+export interface ResolvedOrigin {
+    readonly origin: string;
+    /** Where the origin came from, for `doctor` and for a refusal that explains. */
+    readonly source: "argument" | "environment" | "selection" | "sole";
+}
+/**
+ * The origin, or a refusal naming every way to give one.
+ *
+ * **A default only where exactly one choice exists**, which is the project's
+ * own CLI invariant. Two stored origins and no selection is not a case with an
+ * obvious answer — picking the most recent would be picking production about as
+ * often as staging — so it is a question, asked once, rather than a guess made
+ * silently on every command.
+ */
+export declare function resolveOrigin(runtime: CliRuntime, store: CredentialStore, argumentValue: string | undefined): Promise<ResolvedOrigin>;
+export interface Session {
+    readonly client: DefaultGreatwaitClient;
+    readonly credentialKind: "api-key" | "environment-key" | "oauth";
+    readonly origin: string;
+    readonly originSource: ResolvedOrigin["source"];
+}
+export declare function storeFor(runtime: CliRuntime): CredentialStore;
+/** A client that presents no credential, for the reads that need none. */
+export declare function anonymousClient(runtime: CliRuntime, origin: string): DefaultGreatwaitClient;
+/**
+ * An authenticated session, refreshing an expired grant on the way.
+ *
+ * **The rotated pair is written back before the token is used.** A refresh
+ * exchange invalidates the refresh token it was given, so a process that
+ * refreshed, made its call, and crashed would leave a stored refresh token the
+ * service no longer honours — and the person would have to sign in again for a
+ * reason nothing on their machine explains. Persisting first costs one write
+ * and removes the whole failure.
+ */
+export declare function openSession(runtime: CliRuntime, options: {
+    readonly apiUrl?: string | undefined;
+}): Promise<Session>;
+/**
+ * How long before expiry a grant is refreshed rather than presented.
+ *
+ * **Published, so a case can name it.** A margin pinned only by "refreshes at
+ * ten seconds, does not at an hour" is satisfied by anything between, and a
+ * thirty-minute margin would refresh on nearly every command — burning a
+ * rotation each time and making the stored pair a race between two terminals.
+ *
+ * A minute, because that is comfortably longer than any single call this
+ * command makes and far shorter than the hour a grant lasts.
+ */
+export declare const REFRESH_MARGIN_MS = 60000;

package/dist/session.js

@@ -0,0 +1,157 @@
+import { createGreatwaitClient, } from "@greatwait/api-client";
+import { createCredentialStore, originKey, } from "./config.js";
+import { discover, refresh } from "./oauth.js";
+import { CliError } from "./runtime.js";
+/**
+ * Which service this command is talking to, and what it presents to it.
+ *
+ * **Two questions, resolved separately and both refusable.** Merging them is
+ * how a command ends up presenting a staging credential to production: a single
+ * "current context" that carried both would be one value to get wrong, and the
+ * value that must never be wrong is which origin a secret is sent to. So the
+ * origin is chosen first, and the credential is whatever that origin has.
+ */
+/** Environment names, stated once so nothing else spells one. */
+export const ENVIRONMENT_NAMES = {
+    apiKey: "GREATWAIT_API_KEY",
+    apiUrl: "GREATWAIT_API_URL",
+};
+/**
+ * The origin, or a refusal naming every way to give one.
+ *
+ * **A default only where exactly one choice exists**, which is the project's
+ * own CLI invariant. Two stored origins and no selection is not a case with an
+ * obvious answer — picking the most recent would be picking production about as
+ * often as staging — so it is a question, asked once, rather than a guess made
+ * silently on every command.
+ */
+export async function resolveOrigin(runtime, store, argumentValue) {
+    if (argumentValue !== undefined) {
+        return { origin: normalize(argumentValue), source: "argument" };
+    }
+    const fromEnvironment = runtime.env[ENVIRONMENT_NAMES.apiUrl];
+    if (fromEnvironment !== undefined && fromEnvironment !== "") {
+        return { origin: normalize(fromEnvironment), source: "environment" };
+    }
+    const selected = await store.readSelection();
+    if (selected !== undefined) {
+        return { origin: selected, source: "selection" };
+    }
+    const known = await store.origins();
+    if (known.length === 1) {
+        return { origin: known[0], source: "sole" };
+    }
+    if (known.length === 0) {
+        throw new CliError("no Greatwait service has been chosen", "usage", `Sign in first — greatwait login --api-url https://api.greatwait.dev — or set ${ENVIRONMENT_NAMES.apiUrl}.`);
+    }
+    throw new CliError(`${String(known.length)} services are signed in and none is selected`, "usage", `Choose one — greatwait context use ${known[0]} — or pass --api-url on this command.`);
+}
+function normalize(value) {
+    try {
+        return originKey(value);
+    }
+    catch {
+        throw new CliError(`${value} is not an https origin`, "usage", "Give the API's origin, such as https://api.greatwait.dev.");
+    }
+}
+export function storeFor(runtime) {
+    return createCredentialStore({
+        env: runtime.env,
+        home: runtime.home,
+        platform: runtime.platform,
+        uid: runtime.uid,
+    });
+}
+/** A client that presents no credential, for the reads that need none. */
+export function anonymousClient(runtime, origin) {
+    return createGreatwaitClient({
+        baseUrl: origin,
+        fetch: runtime.fetch,
+    });
+}
+/**
+ * An authenticated session, refreshing an expired grant on the way.
+ *
+ * **The rotated pair is written back before the token is used.** A refresh
+ * exchange invalidates the refresh token it was given, so a process that
+ * refreshed, made its call, and crashed would leave a stored refresh token the
+ * service no longer honours — and the person would have to sign in again for a
+ * reason nothing on their machine explains. Persisting first costs one write
+ * and removes the whole failure.
+ */
+export async function openSession(runtime, options) {
+    const store = storeFor(runtime);
+    const resolved = await resolveOrigin(runtime, store, options.apiUrl);
+    // **The environment wins, and only for an API key.** Non-interactive
+    // automation is the case this exists for, and the journey's own variable is
+    // the one it already exports. A stored OAuth grant is a person's, and a cron
+    // job that silently used one would be acting as them.
+    const fromEnvironment = runtime.env[ENVIRONMENT_NAMES.apiKey];
+    if (fromEnvironment !== undefined && fromEnvironment !== "") {
+        return {
+            client: createGreatwaitClient({
+                baseUrl: resolved.origin,
+                credential: fromEnvironment,
+                fetch: runtime.fetch,
+            }),
+            credentialKind: "environment-key",
+            origin: resolved.origin,
+            originSource: resolved.source,
+        };
+    }
+    const stored = await store.read(resolved.origin);
+    if (stored === undefined) {
+        throw new CliError(`no credential is stored for ${resolved.origin}`, "authentication", `Sign in — greatwait login --api-url ${resolved.origin} — or export ${ENVIRONMENT_NAMES.apiKey} for a non-interactive run.`);
+    }
+    const credential = await presentableSecret(runtime, store, resolved.origin, stored);
+    return {
+        client: createGreatwaitClient({
+            baseUrl: resolved.origin,
+            credential,
+            fetch: runtime.fetch,
+        }),
+        credentialKind: stored.kind,
+        origin: resolved.origin,
+        originSource: resolved.source,
+    };
+}
+/**
+ * How long before expiry a grant is refreshed rather than presented.
+ *
+ * **Published, so a case can name it.** A margin pinned only by "refreshes at
+ * ten seconds, does not at an hour" is satisfied by anything between, and a
+ * thirty-minute margin would refresh on nearly every command — burning a
+ * rotation each time and making the stored pair a race between two terminals.
+ *
+ * A minute, because that is comfortably longer than any single call this
+ * command makes and far shorter than the hour a grant lasts.
+ */
+export const REFRESH_MARGIN_MS = 60_000;
+async function presentableSecret(runtime, store, origin, stored) {
+    if (stored.kind === "api-key") {
+        if (stored.secret === undefined) {
+            throw new CliError(`the stored credential for ${origin} carries no secret`, "authentication", `Sign in again: greatwait login --api-url ${origin} --api-key`);
+        }
+        return stored.secret;
+    }
+    const { accessToken, clientId, expiresAtMs, refreshToken } = stored;
+    if (accessToken === undefined || clientId === undefined) {
+        throw new CliError(`the stored grant for ${origin} is incomplete`, "authentication", `Sign in again: greatwait login --api-url ${origin}`);
+    }
+    if (expiresAtMs === undefined ||
+        expiresAtMs - REFRESH_MARGIN_MS > runtime.now() ||
+        refreshToken === undefined) {
+        return accessToken;
+    }
+    const server = await discover(runtime, origin);
+    const rotated = await refresh(runtime, server, { clientId, refreshToken });
+    await store.write(origin, {
+        accessToken: rotated.accessToken,
+        clientId,
+        expiresAtMs: runtime.now() + rotated.expiresInSeconds * 1000,
+        kind: "oauth",
+        refreshToken: rotated.refreshToken,
+        scope: rotated.scope,
+    });
+    return rotated.accessToken;
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "bin": {
+    "greatwait": "./dist/main.js"
+  },
+  "bugs": {
+    "url": "https://github.com/flowxo/greatwait/issues"
+  },
+  "dependencies": {
+    "@greatwait/api-client": "0.1.0-alpha.3",
+    "@greatwait/contracts": "0.1.0-alpha.3"
+  },
+  "description": "The Greatwait command line: sign in, create a destination and a one-shot schedule, and wait for the callback, over the public API.",
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist"
+  ],
+  "homepage": "https://greatwait.dev",
+  "keywords": [
+    "greatwait",
+    "scheduling",
+    "webhooks",
+    "cli",
+    "command-line"
+  ],
+  "license": "MIT",
+  "name": "@greatwait/cli",
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flowxo/greatwait.git",
+    "directory": "packages/cli"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "version": "0.1.0-alpha.3"
+}