@greatwait/cli 0.1.0-alpha.8 → 0.2.1

package/README.md

@@ -6,7 +6,6 @@ against a receiver you control.
 ```sh
 npm install --global @greatwait/cli
 greatwait login --api-url https://api.greatwait.dev
-greatwait journey
 ```
 
 ## What it is
@@ -44,18 +43,59 @@ directory, readable by you and nobody else. A staging credential is never
 presented to production, because the two are separate entries rather than one
 current context.
 
-## First value
+## First callback
 
-`greatwait journey` prints the published first-value sequence — the same nine
-steps the website and the quickstarts walk — with the command for each one.
+Use a public HTTPS receiver you control. Once signed in, schedule directly to
+its URL and wait for the first delivery:
 
 ```sh
-greatwait destinations create --url https://your-receiver.example.com/greatwait
-greatwait schedules create --endpoint ep_… --in 30s --data '{"greeting":"first value"}'
-greatwait occurrences wait sch_… occ_…
-greatwait attempts list sch_… occ_…
+greatwait schedules create --url https://your-receiver.example.com/greatwait --in 30s --data '{"hello":"world"}' --wait
 ```
 
+GreatWait uses your project's destination at that URL or creates one. The
+answer includes the schedule and occurrence ids; copy them into the read:
+
+```sh
+greatwait attempts list <schedule> <occurrence>
+```
+
+Look for `state: succeeded` and the status your receiver returned. `--wait`
+stops after three minutes by default; a settled failure is also an outcome,
+so inspect the attempt. If it times out, use
+`greatwait occurrences wait <schedule> <occurrence>` and read the attempts
+again. The timeout does not cancel the scheduled call.
+
+For a signed receiver, first add your URL in
+[Settings → Endpoints](https://app.greatwait.dev/settings/endpoints), reveal its
+signing secret, and configure the receiver. The direct-URL schedule reuses that
+destination. If the schedule already created it, reveal the secret and configure
+the receiver before its due time; use a longer `--in` if needed. Direct-URL
+scheduling never prints the signing secret. Verify the signature over the exact request bytes
+before parsing, as described in the
+[CLI quickstart](https://docs.greatwait.dev/guides/cli).
+
+## Clean up
+
+Archive the finished schedule. Read it to find its destination id:
+
+```sh
+greatwait schedules read <schedule>
+greatwait schedules archive <schedule>
+```
+
+If this walkthrough created the destination and no other schedule uses it,
+disable it:
+
+```sh
+greatwait destinations disable <destination> --yes
+```
+
+If you stop before delivery, cancel the schedule with
+`greatwait schedules cancel <schedule> --yes` first. Revoke a walkthrough API
+key in the dashboard, or use `greatwait credentials revoke <credential> --yes`
+while signed in through OAuth. Finish with `greatwait logout` to revoke the CLI
+grant and remove local credentials.
+
 ## Output and exit codes
 
 `--json` is a versioned machine shape, not a serialization of the human text.

package/dist/commands.js

@@ -6,7 +6,7 @@ import { parseDuration } from "./args.js";
 import { COMMAND_CATALOG, REQUESTED_SCOPES } from "./catalog.js";
 import { confirmChange } from "./confirm.js";
 import { directoryConcerns, originKey } from "./config.js";
-import { buildAuthorization, codeFrom, discover, exchangeCode, registerClient, revoke, } from "./oauth.js";
+import { awaitRedirect, buildAuthorization, codeFrom, discover, exchangeCode, registerClient, revoke, } from "./oauth.js";
 import { redactSecret } from "./output.js";
 import { CliError, sleepOrAbort } from "./runtime.js";
 import { publishedWait, recoveryFor, renderJourney, STEP_COMMANDS, } from "./journey.js";
@@ -65,9 +65,10 @@ const login = async (runtime, args) => {
             human: described.known
                 ? `Signed in to ${origin} with an API credential, in project ${described.context.project} (${described.context.environmentKind}).`
                 : `Stored an API credential for ${origin} without checking it.`,
-            nextMove: described.known
-                ? `Next: ${runtime.programName} journey — the published first-value sequence, with the command for each step.`
-                : `${described.reason}\n\nNext: ${runtime.programName} journey — the published first-value sequence, with the command for each step.`,
+            // **No onward step.** Signing in is not enrolment in the first-value
+            // journey, and a person who asked only to sign in was being told where to
+            // go next (FXO-3054). `greatwait --help` still names the journey.
+            ...(described.known ? {} : { nextMove: described.reason }),
         };
     }
     const server = await discover(runtime, origin);
@@ -128,8 +129,13 @@ const login = async (runtime, args) => {
         // **Printed whether or not the browser opened.** A URL shown only when
         // launching failed is a URL nobody on a remote shell ever sees, because
         // `xdg-open` there exits zero having opened nothing.
-        runtime.stderr(`${opened ? "Opened your browser. If nothing appeared, open" : "Open"} this address to approve the request:\n\n  ${authorization.authorizationUrl}\n\nWaiting for the answer on ${listener.redirectUri} …\n`);
-        const returned = await listener.received;
+        //
+        // The loopback address is not printed. It is how the browser answers this
+        // process, not something a person acts on, and it read as a second address
+        // to visit (FXO-3054). It is still in the authorization address, as
+        // `redirect_uri`, for anyone diagnosing a sign-in.
+        runtime.stderr(`${opened ? "Opened your browser. If nothing appeared, open" : "Open"} this address to approve the request:\n\n  ${authorization.authorizationUrl}\n\nWaiting for you to approve it …\n`);
+        const returned = await awaitRedirect(runtime, listener);
         const code = codeFrom(returned, authorization.state, runtime.programName);
         const tokens = await exchangeCode(runtime, server, {
             clientId,
@@ -181,9 +187,7 @@ const login = async (runtime, args) => {
             human: described.known
                 ? `Signed in to ${origin}, in project ${described.context.project} (${described.context.environmentKind}).`
                 : `Signed in to ${origin}. The grant is real — the service issued it — but it cannot say what it reaches.`,
-            nextMove: described.known
-                ? `Next: ${runtime.programName} journey — the published first-value sequence, with the command for each step.`
-                : `${described.reason}\n\nNext: ${runtime.programName} journey — the published first-value sequence, with the command for each step.`,
+            ...(described.known ? {} : { nextMove: described.reason }),
         };
     }
     finally {

package/dist/node-runtime.d.ts

@@ -19,6 +19,16 @@ import { type CliRuntime, type LoopbackListener } from "./runtime.js";
  *
  * Port zero: the operating system picks, and the port is known before the
  * client is registered for it, which RFC 8252's exact-match rule requires.
+ *
+ * **Closing it ends every connection a browser opened, not just the listening
+ * socket.** `server.close()` stops accepting and then waits for open
+ * connections to finish, and a browser keeps them open: Chrome preconnects a
+ * socket it never sends a request on, and holds the redirect's own connection
+ * alive for reuse. Either one kept the process running after `login` had
+ * printed its success — and because Ctrl-C is caught to end waits cleanly, it
+ * could not be stopped short of closing the terminal (FXO-3054). Every socket
+ * is tracked from the moment it connects and destroyed on close, and every
+ * answer says `Connection: close` so a browser does not hold one for reuse.
  */
 export declare function openLoopback(): Promise<LoopbackListener>;
 /**

package/dist/node-runtime.js

@@ -23,6 +23,16 @@ import { InterruptedError, } from "./runtime.js";
  *
  * Port zero: the operating system picks, and the port is known before the
  * client is registered for it, which RFC 8252's exact-match rule requires.
+ *
+ * **Closing it ends every connection a browser opened, not just the listening
+ * socket.** `server.close()` stops accepting and then waits for open
+ * connections to finish, and a browser keeps them open: Chrome preconnects a
+ * socket it never sends a request on, and holds the redirect's own connection
+ * alive for reuse. Either one kept the process running after `login` had
+ * printed its success — and because Ctrl-C is caught to end waits cleanly, it
+ * could not be stopped short of closing the terminal (FXO-3054). Every socket
+ * is tracked from the moment it connects and destroyed on close, and every
+ * answer says `Connection: close` so a browser does not hold one for reuse.
  */
 export async function openLoopback() {
     let deliver;
@@ -39,19 +49,29 @@ export async function openLoopback() {
     // class the refusal earned. A handler attached here is never the *only* one:
     // a caller that does await it still sees the rejection.
     received.catch(() => undefined);
+    // `IncomingMessage["socket"]` rather than an import of `node:net`, which the
+    // architecture gate would count as one more runtime dependency.
+    const sockets = new Set();
     const server = createServer((request, response) => {
         const url = new URL(request.url ?? "/", "http://127.0.0.1");
         const isRedirect = url.pathname === "/callback" &&
             (url.searchParams.has("code") || url.searchParams.has("error"));
         if (!isRedirect) {
-            response.writeHead(204);
+            response.writeHead(204, { connection: "close" });
             response.end();
             return;
         }
-        response.writeHead(200, { "content-type": "text/plain; charset=utf-8" });
+        response.writeHead(200, {
+            connection: "close",
+            "content-type": "text/plain; charset=utf-8",
+        });
         response.end("GreatWait received the answer. You can close this tab.\n");
         deliver?.(url.searchParams);
     });
+    server.on("connection", (socket) => {
+        sockets.add(socket);
+        socket.once("close", () => sockets.delete(socket));
+    });
     await new Promise((resolve, reject) => {
         server.once("error", reject);
         // `127.0.0.1` rather than every interface: this socket receives an
@@ -70,6 +90,18 @@ export async function openLoopback() {
         close: () => {
             fail?.(new Error("the sign-in was abandoned"));
             server.close();
+            // After `close`, so nothing new is accepted while these are destroyed.
+            // A refusal can close within a tick of answering the redirect, so a
+            // socket still flushing that answer is ended first and destroyed once it
+            // has, and the browser still shows the page.
+            for (const socket of sockets) {
+                if (socket.writableLength > 0) {
+                    socket.end(() => socket.destroy());
+                }
+                else {
+                    socket.destroy();
+                }
+            }
         },
         received,
         redirectUri: `http://127.0.0.1:${String(address.port)}/callback`,

package/dist/oauth.d.ts

@@ -1,4 +1,4 @@
-import { type CliRuntime } from "./runtime.js";
+import { type CliRuntime, type LoopbackListener } from "./runtime.js";
 /**
  * The delegated-authorization half of `login`, spoken as a public client.
  *
@@ -59,6 +59,20 @@ export declare function buildAuthorization(runtime: CliRuntime, server: Authoriz
     readonly redirectUri: string;
     readonly scopes: readonly string[];
 }): Promise<AuthorizationRequest>;
+/**
+ * The redirect, or the reason there will not be one.
+ *
+ * **Bounded by Ctrl-C and by the authorization request's own lifetime.** It
+ * used to await the listener alone, so Ctrl-C aborted a signal nothing here was
+ * watching and a browser closed without answering held the terminal for ever.
+ * The deadline is the service's: past it the request a person would approve
+ * has expired, and waiting longer could only end in a refusal.
+ *
+ * The timer is cancelled however the wait ends. A ten-minute timer left armed
+ * after a successful sign-in is ten minutes of a process that has finished and
+ * will not exit.
+ */
+export declare function awaitRedirect(runtime: CliRuntime, listener: LoopbackListener): Promise<URLSearchParams>;
 /**
  * Turns the redirect into a code, refusing anything that is not this run's.
  *

package/dist/oauth.js

@@ -1,4 +1,5 @@
-import { CliError } from "./runtime.js";
+import { AUTHORIZATION_REQUEST_TTL_SECONDS } from "@greatwait/contracts";
+import { CliError, InterruptedError, } from "./runtime.js";
 function base64Url(bytes) {
     return Buffer.from(bytes).toString("base64url");
 }
@@ -109,6 +110,44 @@ export async function buildAuthorization(runtime, server, options) {
     url.searchParams.set("state", state);
     return { authorizationUrl: url.toString(), state, verifier };
 }
+/**
+ * The redirect, or the reason there will not be one.
+ *
+ * **Bounded by Ctrl-C and by the authorization request's own lifetime.** It
+ * used to await the listener alone, so Ctrl-C aborted a signal nothing here was
+ * watching and a browser closed without answering held the terminal for ever.
+ * The deadline is the service's: past it the request a person would approve
+ * has expired, and waiting longer could only end in a refusal.
+ *
+ * The timer is cancelled however the wait ends. A ten-minute timer left armed
+ * after a successful sign-in is ten minutes of a process that has finished and
+ * will not exit.
+ */
+export async function awaitRedirect(runtime, listener) {
+    if (runtime.signal.aborted)
+        throw new InterruptedError();
+    const stop = new AbortController();
+    const onAbort = () => {
+        stop.abort();
+    };
+    runtime.signal.addEventListener("abort", onAbort, { once: true });
+    const deadline = runtime
+        .sleep(AUTHORIZATION_REQUEST_TTL_SECONDS * 1_000, stop.signal)
+        .then(() => {
+        if (runtime.signal.aborted)
+            throw new InterruptedError();
+        throw new CliError(`nobody approved the request within ${String(AUTHORIZATION_REQUEST_TTL_SECONDS / 60)} minutes, so this command stopped waiting`, "timeout", `Run ${runtime.programName} login again, or use an API key: ${runtime.programName} login --api-key`);
+    });
+    try {
+        return await Promise.race([listener.received, deadline]);
+    }
+    finally {
+        runtime.signal.removeEventListener("abort", onAbort);
+        stop.abort();
+        // The losing side settles after the race and nobody awaits it.
+        deadline.catch(() => undefined);
+    }
+}
 /**
  * Turns the redirect into a code, refusing anything that is not this run's.
  *

package/dist/start.d.ts

@@ -1,15 +1 @@
-/**
- * The body both installed executables share.
- *
- * **Two entry files rather than one that works out what it was called.**
- * `process.argv[1]` is the *resolved* path of the main module, and npm links a
- * bin as a symlink into `node_modules/.bin`, so a program deriving its own name
- * from argv would read `main.js` — and the version that guesses correctly on
- * macOS is the version that guesses differently under a shell wrapper, on
- * Windows, or with `--preserve-symlinks-main`. The name is a property of the
- * entry point, so the entry point states it.
- *
- * `process.exitCode` rather than `process.exit`: the second truncates whatever
- * is still buffered on stdout, and this command's last act is to print.
- */
 export declare function start(programName: string): Promise<void>;

package/dist/start.js

@@ -1,4 +1,5 @@
 import { run } from "./cli.js";
+import { EXIT_CLASSES } from "./exit.js";
 import { nodeRuntime } from "./node-runtime.js";
 /**
  * The body both installed executables share.
@@ -13,14 +14,40 @@ import { nodeRuntime } from "./node-runtime.js";
  *
  * `process.exitCode` rather than `process.exit`: the second truncates whatever
  * is still buffered on stdout, and this command's last act is to print.
+ *
+ * **Catching a signal must never make the process unstoppable.** The first
+ * Ctrl-C aborts, so a wait can end with its own sentence and exit class. A
+ * second one a moment later exits at once with 130, and once the command has
+ * returned the handlers are removed, so a signal regains its default meaning.
+ * "A moment later" because one keypress under `npx` arrives twice — from the
+ * terminal to the process group, and again forwarded by npm — and treating the
+ * echo as a second Ctrl-C would skip the interruption's own sentence. Before
+ * FXO-3054 neither held: a socket left open after a successful `login` kept the
+ * process alive, every Ctrl-C was absorbed by an abort nothing was waiting on,
+ * and the only way out was closing the terminal.
  */
+/** How far apart two signals must be to count as a person asking twice. */
+const REPEATED_SIGNAL_MS = 500;
 export async function start(programName) {
     const controller = new AbortController();
-    process.on("SIGINT", () => {
-        controller.abort();
-    });
-    process.on("SIGTERM", () => {
-        controller.abort();
-    });
-    process.exitCode = await run(nodeRuntime(controller.signal, programName));
+    let firstSignalAt;
+    const onSignal = (signal) => {
+        if (firstSignalAt === undefined) {
+            firstSignalAt = Date.now();
+            controller.abort();
+            return;
+        }
+        if (Date.now() - firstSignalAt >= REPEATED_SIGNAL_MS) {
+            process.exit(signal === "SIGINT" ? EXIT_CLASSES.interrupted : 143);
+        }
+    };
+    process.on("SIGINT", onSignal);
+    process.on("SIGTERM", onSignal);
+    try {
+        process.exitCode = await run(nodeRuntime(controller.signal, programName));
+    }
+    finally {
+        process.off("SIGINT", onSignal);
+        process.off("SIGTERM", onSignal);
+    }
 }

package/package.json

@@ -7,10 +7,10 @@
     "url": "https://github.com/flowxo/greatwait/issues"
   },
   "dependencies": {
-    "@greatwait/api-client": "0.1.0-alpha.8",
-    "@greatwait/contracts": "0.1.0-alpha.8"
+    "@greatwait/api-client": "0.2.1",
+    "@greatwait/contracts": "0.2.1"
   },
-  "description": "The GreatWait command line: sign in, create a destination and a one-shot schedule, and wait for the callback, over the public API.",
+  "description": "The GreatWait command line: sign in, schedule a call to a URL, and read its delivery outcome over the public API.",
   "engines": {
     "node": ">=22.13.0"
   },
@@ -48,5 +48,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.1.0-alpha.8"
+  "version": "0.2.1"
 }