@throng/cli 0.1.0

package/README.md

@@ -0,0 +1,120 @@
+# throng
+
+Command-line client for [Throng](https://app.throng.dev).
+
+Requires Node 20 or later.
+
+## Commands
+
+```
+throng auth login      Sign in through your browser
+throng auth logout     Revoke the session on the server and forget the stored credentials
+throng auth status     Show host, user, access token expiry and organisation (exits 3 when not signed in)
+throng token           Print a valid access token on stdout
+throng org list        List your organisations
+throng org use <slug-or-id>
+                       Choose the organisation later commands act in
+throng api [-f file]   Run a GraphQL document and print the data as JSON
+```
+
+`api` reads the document from `-f <file>`, or from stdin when `-f` is absent
+(`echo '{ me { email } }' | throng api`). With no file and a terminal on stdin
+it exits with a usage error rather than wait for input. Organisation-scoped
+queries need an organisation: choose one with `org use`, or pass `--org <id>` for
+a single call.
+
+`auth logout` revokes the grant on the server (RFC 7009) as well as forgetting it
+on this machine, so a refresh token copied or backed up elsewhere stops working.
+Revocation is best-effort: if the server cannot be reached, logout warns on stderr
+and still forgets the credentials locally. `auth status` asks the server who you
+are; if it cannot, it reports what is stored locally and says the user is unknown.
+
+### Global options
+
+| Option | Meaning |
+| --- | --- |
+| `--host <url>` | The Throng host. Falls back to `THRONG_HOST`, then `https://app.throng.dev`. |
+| `--org <id>` | Organisation id for this call, overriding the one chosen with `org use`. |
+| `--json` | Print JSON instead of a table (`org list`). |
+
+### Output and exit codes
+
+Stdout carries only data: the token from `token`, the JSON from `api`, the table
+from `org list`. Every message meant for a person goes to stderr, so
+`throng token | pbcopy` copies the token and nothing else.
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 1 | API error, refused mutation, or any other failure (network, lock timeout) |
+| 2 | Usage error |
+| 3 | Authentication required: run `throng auth login` |
+
+If the server says you are no longer a member of the stored organisation, `api`
+forgets it and asks you to run `throng org use`.
+
+## Development
+
+```
+npm test              # unit tests
+npm run typecheck
+npm run dev -- --host http://localhost:4000 auth status
+```
+
+## Releasing
+
+Releases are published by `.github/workflows/cli-release.yml` when a `cli-v*` tag
+is pushed. **There is no npm token**: the workflow authenticates to npm over OIDC
+as a trusted publisher, so nothing long-lived has to be stored in the repository,
+and each release gets a provenance attestation for free.
+
+To cut a release, bump `version` in `package.json`, merge, then tag. The workflow
+refuses to publish if the tag and `package.json` disagree, so the two cannot drift:
+
+```
+git tag cli-v0.1.1 && git push origin cli-v0.1.1
+```
+
+### One-time setup
+
+Trusted publishing is configured per package, at
+`npmjs.com/package/@throng/cli/access` — which only exists once the package does.
+So the first version has to be published by hand, and only the first:
+
+1. Create the `throng` organisation on npm. A free org is enough; it allows
+   unlimited public packages, and this one is public.
+2. Publish once from a checkout: `npm login`, then `npm run build && npm publish
+   --access public`.
+3. At `npmjs.com/package/@throng/cli/access`, add a GitHub Actions trusted
+   publisher — organisation `col`, repository `throngx`, workflow filename
+   `cli-release.yml`. Leave the environment blank. **Every field is
+   case-sensitive, and npm does not validate them when you save**, so a typo
+   surfaces only as a failed publish.
+
+After that every release is tokenless. Two things to know if a publish ever fails
+with an authentication error: `package.json`'s `repository.url` must keep matching
+the trusted publisher exactly, and the publish job needs npm 11.5.1+ on Node
+22.14+, which is why it installs its own npm rather than using Node's bundled one.
+
+### Integration test
+
+`test/integration.test.ts` runs against a real server and is skipped unless
+`THRONG_INTEGRATION_HOST` is set:
+
+| Variable | Meaning |
+| --- | --- |
+| `THRONG_INTEGRATION_HOST` | Origin of the server, for example `http://localhost:4000`. |
+| `THRONG_INTEGRATION_REFRESH_TOKEN` | A refresh token for that host. Run `throng auth login --host <host>` by hand once and copy `refresh_token` from `~/.config/throng/credentials.json`. |
+
+```
+THRONG_INTEGRATION_HOST=http://localhost:4000 \
+THRONG_INTEGRATION_REFRESH_TOKEN=... \
+npx vitest run test/integration.test.ts
+```
+
+It exercises the library calls `token` and `api` are built on (refreshing against
+the live `/oauth/token`, a real `me { email }`, and the page shape of
+`myOrganisations`), not the commands themselves, which `commands.test.ts` covers
+against stubs. It does not cover `login`, because completing a browser sign-in
+and consent cannot be automated. Refresh tokens rotate, so a run spends the one
+you supplied; sign in again before the next.

package/dist/commands/api.js

@@ -0,0 +1,80 @@
+import { readFile } from "node:fs/promises";
+import { OrgAccessDeniedError, graphql } from "../graphql.js";
+import { clearOrgId, getOrgId } from "../oauth/session.js";
+import { printJson } from "../output.js";
+async function readStream(stream) {
+    const chunks = [];
+    for await (const chunk of stream)
+        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+/**
+ * `throng api [-f file]`: run a GraphQL document and print its `data` as JSON.
+ *
+ * With no `-f` the document is read from stdin. If stdin is a terminal there is
+ * nothing to read and waiting would just hang the command, so that is a usage
+ * error instead.
+ */
+export function registerApi(program, ctx) {
+    program
+        .command("api")
+        .description("Run a GraphQL document against the API and print the data as JSON")
+        .option("-f, --file <path>", "read the document from a file instead of stdin")
+        .action(async (opts, command) => {
+        const { host, org, stdin } = ctx();
+        let document;
+        if (opts.file !== undefined) {
+            try {
+                document = await readFile(opts.file, "utf8");
+            }
+            catch (cause) {
+                const code = cause.code ?? "unknown error";
+                return command.error(`error: cannot read ${opts.file} (${code})`, { exitCode: 2 });
+            }
+        }
+        else if (stdin.isTTY) {
+            return command.error("error: no GraphQL document: pass -f <file> or pipe one to stdin", { exitCode: 2 });
+        }
+        else {
+            document = await readStream(stdin);
+        }
+        if (document.trim() === "") {
+            return command.error("error: the GraphQL document is empty", { exitCode: 2 });
+        }
+        // --org wins; otherwise the organisation `throng org use` stored.
+        const storedOrg = org === undefined ? await getOrgId(host) : undefined;
+        const orgId = org ?? storedOrg;
+        try {
+            printJson(await graphql(host, document, { orgId }));
+        }
+        catch (error) {
+            if (!(error instanceof OrgAccessDeniedError))
+                throw error;
+            throw await orgDenied(error, host, org, storedOrg);
+        }
+    });
+}
+/**
+ * The documented recovery from a 403 `ORGANISATION_ACCESS_DENIED`: drop the
+ * stored organisation so the next command stops sending it, and point the user
+ * at `throng org use`. An organisation given with `--org` is the user's explicit
+ * choice for this one call; the stored one did not cause the refusal, so it stays.
+ */
+async function orgDenied(error, host, flagOrg, storedOrg) {
+    if (flagOrg !== undefined) {
+        return new OrgAccessDeniedError(`You are not a member of organisation ${flagOrg}. Run \`throng org list\` to see yours.`, error.code);
+    }
+    if (storedOrg === undefined)
+        return error;
+    let cleared = true;
+    try {
+        await clearOrgId(host);
+    }
+    catch {
+        cleared = false;
+    }
+    const action = cleared
+        ? "The stored organisation was cleared."
+        : "The stored organisation could not be cleared.";
+    return new OrgAccessDeniedError(`You are no longer a member of the selected organisation. ${action} Run \`throng org use <slug-or-id>\` to choose another.`, error.code);
+}

package/dist/commands/auth.js

@@ -0,0 +1,96 @@
+import open from "open";
+import { AuthRequiredError } from "../errors.js";
+import { graphql } from "../graphql.js";
+import { login } from "../oauth/login.js";
+import { getAccessToken, getExpiresAt, getOrgId, logout, saveLogin } from "../oauth/session.js";
+import { describeError, info } from "../output.js";
+export function registerAuth(program, ctx) {
+    const auth = program.command("auth").description("Sign in, sign out, and check your session");
+    auth
+        .command("login")
+        .description("Sign in through your browser")
+        .action(async () => {
+        const { host, openBrowser } = ctx();
+        const launch = openBrowser ??
+            (async (url) => {
+                await open(url);
+            });
+        const pair = await login(host, {
+            // `login` has no output channel of its own. The URL is printed before the
+            // launcher runs because a launcher can succeed without showing anything
+            // (headless box, SSH), and the user would otherwise wait out the timeout
+            // with nothing to act on.
+            openBrowser: async (url) => {
+                info(`Opening your browser to sign in to ${host}.`);
+                info("If it does not open, visit this URL:");
+                info(url);
+                await launch(url);
+            },
+        });
+        await saveLogin(host, pair);
+        info(`Signed in to ${host}.`);
+    });
+    auth
+        .command("logout")
+        .description("Revoke this host's session and forget the stored credentials")
+        .action(async () => {
+        const { host } = ctx();
+        const { revokeFailure } = await logout(host);
+        if (revokeFailure) {
+            info(`Could not revoke your session on ${host} (${revokeFailure}). It was forgotten on this machine only, and stays valid on the server until it expires.`);
+        }
+        info(`Signed out of ${host}.`);
+    });
+    auth
+        .command("status")
+        .description("Show your host, user, organisation and token expiry (exits 3 when you are not signed in)")
+        .action(async () => {
+        const context = ctx();
+        const { host } = context;
+        // The one problem that makes the rest of the report unverifiable, if there is one.
+        let problem;
+        try {
+            // Not just "is a record on disk": this refreshes a lapsed session, so a
+            // dead one is reported as signed out. The token itself is never shown.
+            await getAccessToken(host);
+        }
+        catch (error) {
+            if (!(error instanceof AuthRequiredError)) {
+                // Could not refresh (offline, lock timeout): fall through to the local facts.
+                problem = describeError(error);
+                context.exitCode = 1;
+            }
+            else {
+                // Reported, not thrown: a status check answering "no" is not a failure of the command.
+                info(error.message);
+                context.exitCode = 3;
+                return;
+            }
+        }
+        info(`Signed in to ${host}.`);
+        if (problem === undefined) {
+            try {
+                // No organisation header: `me` does not need one, and a stale stored one would be refused.
+                const data = await graphql(host, "{ me { email } }");
+                const email = data.me?.email;
+                info(typeof email === "string" ? `User: ${email}` : "User: unknown");
+            }
+            catch (error) {
+                // The local facts below are still true, so report them rather than fail the command.
+                info(`User: unknown (could not ask ${host}: ${describeError(error)})`);
+                // The server turning our access token away means the session is not usable.
+                if (error instanceof AuthRequiredError)
+                    context.exitCode = 3;
+            }
+        }
+        else {
+            info(`User: unknown (could not refresh your session: ${problem})`);
+        }
+        const expiresAt = await getExpiresAt(host);
+        if (expiresAt !== undefined) {
+            info(`Access token expires: ${new Date(expiresAt * 1000).toISOString()}`);
+        }
+        const orgId = await getOrgId(host);
+        info(orgId ? `Organisation: ${orgId}` : "No organisation selected. Run `throng org use <slug-or-id>`.");
+    });
+}

package/dist/commands/org.js

@@ -0,0 +1,52 @@
+import { graphql } from "../graphql.js";
+import { setOrgId } from "../oauth/session.js";
+import { info, printJson, printTable } from "../output.js";
+// The server's default page is 10; 250 is the most it serves per page. Asking for the
+// maximum is what lets `org use` reach any organisation without paginating.
+const MY_ORGANISATIONS = "{ myOrganisations(limit: 250) { hasNextPage results { id name slug } } }";
+/**
+ * Deliberately sent without `x-throng-organisation`. This query is how a user
+ * recovers from a stale stored organisation, and a header naming an
+ * organisation they have left would be refused for this query too.
+ */
+async function myOrganisations(host) {
+    const data = await graphql(host, MY_ORGANISATIONS);
+    return data.myOrganisations;
+}
+export function registerOrg(program, ctx) {
+    const org = program.command("org").description("List and select organisations");
+    org
+        .command("list")
+        .description("List the organisations you belong to")
+        .action(async () => {
+        const { host, json } = ctx();
+        const page = await myOrganisations(host);
+        if (json) {
+            printJson(page.results);
+        }
+        else if (page.results.length === 0) {
+            info("No organisations.");
+        }
+        else {
+            printTable(page.results, ["id", "name", "slug"]);
+        }
+        if (page.hasNextPage)
+            info("More organisations exist than are listed here.");
+    });
+    org
+        .command("use")
+        .argument("<slug-or-id>", "organisation slug or id")
+        .description("Select the organisation later commands act in")
+        .action(async (slugOrId) => {
+        const { host } = ctx();
+        const page = await myOrganisations(host);
+        // An id match wins over a slug match, whatever the list order.
+        const match = page.results.find((o) => o.id === slugOrId) ?? page.results.find((o) => o.slug === slugOrId);
+        if (!match) {
+            const more = page.hasNextPage ? " (only the first page of your organisations was searched)" : "";
+            throw new Error(`No organisation with slug or id "${slugOrId}" among yours${more}. Run \`throng org list\` to see them.`);
+        }
+        await setOrgId(host, match.id);
+        info(`Using organisation ${match.name} (${match.slug}).`);
+    });
+}

package/dist/commands/token.js

@@ -0,0 +1,14 @@
+import { getAccessToken } from "../oauth/session.js";
+/**
+ * `throng token`: print a valid access token. Stdout carries the token and a
+ * newline and nothing else, ever. It is meant for `$(throng token)` and pipes.
+ */
+export function registerToken(program, ctx) {
+    program
+        .command("token")
+        .description("Print a valid access token on stdout (refreshing it if needed)")
+        .action(async () => {
+        const token = await getAccessToken(ctx().host);
+        process.stdout.write(`${token}\n`);
+    });
+}

package/dist/config.js

@@ -0,0 +1,37 @@
+export const DEFAULT_HOST = "https://app.throng.dev";
+/**
+ * Resolve the Throng host: `--host` flag, then `THRONG_HOST`, then the default.
+ *
+ * Returns `origin + path` with no trailing slash, so callers can append paths
+ * (`/api/graphql`) and one host maps to exactly one credential record. A
+ * subpath is kept (reverse-proxy mounts); a query, fragment or userinfo is
+ * rejected rather than silently dropped.
+ */
+export function resolveHost(flag, env) {
+    // `??` for the flag: an explicitly empty `--host ""` is a mistake (an unset shell
+    // variable, say) and must fail validation, never quietly fall through to production.
+    // `||` for the environment: an empty variable conventionally means unset.
+    const raw = flag ?? (env.THRONG_HOST || DEFAULT_HOST);
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        // Never echo the host back: even a malformed one may contain a password.
+        throw new Error(`Invalid host: expected an absolute http(s) URL such as ${DEFAULT_HOST}`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error(`Invalid host: expected an absolute http(s) URL such as ${DEFAULT_HOST}, got protocol "${url.protocol}"`);
+    }
+    // As above, nothing from the host is echoed in any of these messages.
+    if (url.username || url.password) {
+        throw new Error("Invalid host: it must not contain embedded credentials (user:password@)");
+    }
+    if (url.search) {
+        throw new Error("Invalid host: it must not contain a query string (?...)");
+    }
+    if (url.hash) {
+        throw new Error("Invalid host: it must not contain a fragment (#...)");
+    }
+    return url.origin + url.pathname.replace(/\/+$/, "");
+}

package/dist/credentials.js

@@ -0,0 +1,211 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+const LOCK_RETRY_MS = 50;
+/**
+ * How long to wait for the lock. This must comfortably exceed the token
+ * request timeout plus a persist: a waiter that gives up while a refresh is
+ * still in flight invites the user to delete the lock, and the next process
+ * would then replay the not-yet-persisted refresh token.
+ */
+export const LOCK_TIMEOUT_MS = 30_000;
+/** Another process held the credentials lock for the whole wait. */
+export class LockTimeoutError extends Error {
+    name = "LockTimeoutError";
+}
+/**
+ * `${XDG_CONFIG_HOME:-~/.config}/throng/credentials.json`.
+ *
+ * Every function here resolves the path from `process.env` when it is called,
+ * never at module load, so a changed environment is always honoured.
+ */
+export function credentialsPath(env = process.env) {
+    const configHome = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), ".config");
+    return join(configHome, "throng", "credentials.json");
+}
+function lockPathFor(file) {
+    return `${file}.lock`;
+}
+function errorCode(err) {
+    return err.code;
+}
+/**
+ * Whole-file read. Only a missing file (ENOENT) or unparseable JSON counts as
+ * "nothing stored"; any other failure (EACCES, EISDIR, EIO, ...) is rethrown.
+ * Swallowing those would let a read-modify-write replace a file that still
+ * holds valid refresh tokens with one that holds only the new record.
+ */
+async function readAll(file) {
+    let text;
+    try {
+        text = await readFile(file, "utf8");
+    }
+    catch (err) {
+        if (errorCode(err) === "ENOENT")
+            return {};
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        if (err instanceof SyntaxError)
+            return {};
+        throw err;
+    }
+    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+        ? parsed
+        : {};
+}
+function isHostCredentials(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v.refresh_token === "string" &&
+        typeof v.access_token === "string" &&
+        typeof v.expires_at === "number" &&
+        (v.org_id === undefined || typeof v.org_id === "string"));
+}
+/**
+ * Write to a private temp file, then rename over the target. Rename is atomic
+ * within a filesystem, so a crash leaves either the old file or the new one,
+ * never a truncated one. The temp file is created 0600 so the secret is never
+ * briefly readable by others.
+ */
+async function writeAll(file, data) {
+    await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${process.pid}.tmp`;
+    try {
+        await writeFile(tmp, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
+        await rename(tmp, file);
+    }
+    catch (err) {
+        await unlink(tmp).catch(() => { });
+        throw err;
+    }
+}
+export async function readCredentials(host) {
+    const all = await readAll(credentialsPath(process.env));
+    if (!Object.hasOwn(all, host))
+        return null;
+    const record = all[host];
+    // A hand-edited or damaged record is the same as being signed out.
+    return isHostCredentials(record) ? record : null;
+}
+/**
+ * Merge one host's record into the file, leaving other hosts untouched. This
+ * is a read-modify-write: callers that can run concurrently must hold
+ * `withLock`.
+ */
+export async function writeCredentials(host, creds) {
+    const file = credentialsPath(process.env);
+    const all = await readAll(file);
+    all[host] = creds;
+    await writeAll(file, all);
+}
+/**
+ * Remove one host's record. A no-op when that host has nothing stored. Like
+ * `writeCredentials`, a read-modify-write: callers that can run concurrently
+ * must hold `withLock`.
+ */
+export async function deleteCredentials(host) {
+    const file = credentialsPath(process.env);
+    const all = await readAll(file);
+    if (!Object.hasOwn(all, host))
+        return;
+    delete all[host];
+    await writeAll(file, all);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Run `fn` while holding an exclusive lock on the credentials file.
+ *
+ * Refresh tokens rotate on every use and the server treats a replayed one as
+ * theft, so two concurrent invocations must never both refresh. One lock
+ * guards the whole file. Created with `open(..., "wx")`, which fails with
+ * EEXIST if another process holds it, and stamped with a per-call token.
+ */
+export async function withLock(fn) {
+    const lockPath = lockPathFor(credentialsPath(process.env));
+    await mkdir(dirname(lockPath), { recursive: true, mode: 0o700 });
+    // Identifies this holder, so release never removes a lock someone else
+    // took after ours was deleted (e.g. by a user following the timeout error).
+    const token = randomUUID();
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    for (;;) {
+        try {
+            const handle = await open(lockPath, "wx", 0o600);
+            try {
+                await handle.writeFile(token);
+            }
+            catch (err) {
+                await unlink(lockPath).catch(() => { });
+                throw err;
+            }
+            finally {
+                await handle.close();
+            }
+            break;
+        }
+        catch (err) {
+            if (errorCode(err) !== "EEXIST")
+                throw err;
+            // A holder that died without releasing (Ctrl-C does not run `finally`) leaves a
+            // lock nothing will ever remove. Past the point where we would tell the user to
+            // delete it by hand, delete it ourselves and try again straight away.
+            if (await removeIfAbandoned(lockPath))
+                continue;
+            if (Date.now() >= deadline) {
+                throw new LockTimeoutError(`Another throng command is probably refreshing your session. Wait a moment and try again. If no other throng command is running, delete ${lockPath} and retry.`);
+            }
+            await sleep(LOCK_RETRY_MS);
+        }
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        await releaseLock(lockPath, token);
+    }
+}
+/**
+ * Remove a lock file whose mtime is older than `LOCK_TIMEOUT_MS`, and report
+ * whether it did. Safe for a live holder: no refresh outlives that age, and
+ * `releaseLock` only unlinks a lock that still carries its own token, so a
+ * holder whose lock was stolen cannot remove the thief's.
+ */
+async function removeIfAbandoned(lockPath) {
+    try {
+        const { mtimeMs } = await stat(lockPath);
+        if (Date.now() - mtimeMs <= LOCK_TIMEOUT_MS)
+            return false;
+        await unlink(lockPath);
+        return true;
+    }
+    catch (err) {
+        // Released between our failed create and this look: nothing left to wait for.
+        if (errorCode(err) === "ENOENT")
+            return true;
+        throw err;
+    }
+}
+/**
+ * Remove the lock only if it is still ours. A lock that is already gone is
+ * fine; any other failure is surfaced, since swallowing it would leave a lock
+ * that nothing can release.
+ */
+async function releaseLock(lockPath, token) {
+    try {
+        if ((await readFile(lockPath, "utf8")) !== token)
+            return;
+        await unlink(lockPath);
+    }
+    catch (err) {
+        if (errorCode(err) !== "ENOENT")
+            throw err;
+    }
+}

package/dist/errors.js

@@ -0,0 +1,6 @@
+/** The command that starts a sign-in, quoted in every message that tells the user to sign in. */
+export const SIGN_IN_COMMAND = "throng auth login";
+/** The user has no usable session for the host and must sign in again. */
+export class AuthRequiredError extends Error {
+    name = "AuthRequiredError";
+}