driggsby 0.1.41 → 0.2.0

package/dist/args.js

@@ -0,0 +1,177 @@
+// Hand-rolled argv parsing for the small fixed command tree. The root and mcp
+// levels (and the whole mcp setup surface, in args-mcp-setup.ts) byte-match
+// the original clap 4.6 behavior: help routing, exit codes, error text, "did
+// you mean" tips (via the ported Jaro similarity in clap-suggestions.ts),
+// "--" end-of-options, and short-flag cluster dispatch. Newer commands
+// (login, logout) keep the same behavior and exit codes without chasing
+// clap's byte-level quirks.
+import { parseDeploy, parseRollback, parseVersions } from "./args-deploy.js";
+import { parseInit } from "./args-init.js";
+import { parseMcpSetup } from "./args-mcp-setup.js";
+import { removeDashesTip, similarArgumentTip, unexpectedArgument, unexpectedFlagValue, } from "./args-shared.js";
+import { didYouMean } from "./clap-suggestions.js";
+import { CliError } from "./cli-error.js";
+import { DEV_HELP, LOGIN_HELP, LOGOUT_HELP, MCP_HELP, ROOT_HELP } from "./help.js";
+import { sanitizeForTerminal } from "./terminal-text.js";
+export {} from "./args-shared.js";
+const ROOT_USAGE = "Usage: npx driggsby@latest <COMMAND>";
+const MCP_USAGE = "Usage: npx driggsby@latest mcp <COMMAND>";
+const ROOT_LEVEL = {
+    helpText: ROOT_HELP,
+    usage: ROOT_USAGE,
+    subcommands: ["mcp", "login", "logout", "init", "dev", "deploy", "rollback", "versions"],
+    longFlags: ["help", "version"],
+    subcommandFlags: [
+        { name: "mcp", longFlags: ["help"] },
+        { name: "login", longFlags: ["help"] },
+        { name: "logout", longFlags: ["help"] },
+        { name: "init", longFlags: ["help"] },
+        { name: "dev", longFlags: ["help"] },
+        { name: "deploy", longFlags: ["preview", "help"] },
+        { name: "rollback", longFlags: ["to", "help"] },
+        { name: "versions", longFlags: ["help"] },
+    ],
+    usagePrefix: "npx driggsby@latest",
+    hasVersion: true,
+};
+const MCP_LEVEL = {
+    helpText: MCP_HELP,
+    usage: MCP_USAGE,
+    subcommands: ["setup"],
+    longFlags: ["help"],
+    subcommandFlags: [{ name: "setup", longFlags: ["print", "help"] }],
+    usagePrefix: "npx driggsby@latest mcp",
+    hasVersion: false,
+};
+export function parseArgv(argv) {
+    return parseLevel(ROOT_LEVEL, argv);
+}
+function parseLevel(level, argv) {
+    const first = argv[0];
+    if (first === undefined) {
+        return { kind: "print-help", text: level.helpText, stream: "stderr", exitCode: 2 };
+    }
+    if (first === "-h" || first === "--help") {
+        return { kind: "print-help", text: level.helpText, stream: "stdout", exitCode: 0 };
+    }
+    if (level.hasVersion && (first === "-V" || first === "--version")) {
+        return { kind: "print-version" };
+    }
+    if (level.subcommands.includes(first)) {
+        return dispatchSubcommand(first, argv.slice(1));
+    }
+    if (first === "--") {
+        return parseLevelAfterEndOfOptions(level, argv[1]);
+    }
+    if (first.startsWith("--help=")) {
+        throw unexpectedFlagValue("--help", first.slice("--help=".length), levelFlagUsage(level, "help"));
+    }
+    if (level.hasVersion && first.startsWith("--version=")) {
+        throw unexpectedFlagValue("--version", first.slice("--version=".length), levelFlagUsage(level, "version"));
+    }
+    if (first.startsWith("--")) {
+        throw unknownLongFlagAtLevel(level, first, argv.slice(1));
+    }
+    if (first.startsWith("-") && first.length > 1) {
+        return dispatchShortCluster(level, first);
+    }
+    throw unrecognizedSubcommand(level, first);
+}
+function dispatchSubcommand(name, rest) {
+    switch (name) {
+        case "mcp":
+            return parseLevel(MCP_LEVEL, rest);
+        case "login":
+            return parseBareCommand({ kind: "login" }, LOGIN_HELP, "Usage: npx driggsby@latest login", rest);
+        case "logout":
+            return parseBareCommand({ kind: "logout" }, LOGOUT_HELP, "Usage: npx driggsby@latest logout", rest);
+        case "init":
+            return parseInit(rest);
+        case "dev":
+            return parseBareCommand({ kind: "dev" }, DEV_HELP, "Usage: npx driggsby@latest dev", rest);
+        case "deploy":
+            return parseDeploy(rest);
+        case "rollback":
+            return parseRollback(rest);
+        case "versions":
+            return parseVersions(rest);
+        case "setup":
+            return parseMcpSetup(rest);
+        default:
+            // Every name in a CommandLevel's subcommands list must have a case
+            // above; reaching here is a wiring bug, not a user error.
+            throw new Error(`unhandled subcommand dispatch: ${name}`);
+    }
+}
+// Parsing for commands that take no arguments beyond help: login and logout.
+// Same exit codes and error shape as the rest of the tree, no clap quirks.
+function parseBareCommand(command, helpText, usage, argv) {
+    let optionsEnded = false;
+    for (const token of argv) {
+        if (!optionsEnded && token === "--") {
+            optionsEnded = true;
+            continue;
+        }
+        if (!optionsEnded && (token === "-h" || token === "--help")) {
+            return { kind: "print-help", text: helpText, stream: "stdout", exitCode: 0 };
+        }
+        throw unexpectedArgument(token, usage);
+    }
+    return command;
+}
+function levelFlagUsage(level, flagName) {
+    return `Usage: ${level.usagePrefix} --${flagName} <COMMAND>`;
+}
+// After "--", everything is positional — and these levels take no
+// positionals, so clap reports the token as unexpected (with a targeted tip
+// when it names a real subcommand of this level).
+function parseLevelAfterEndOfOptions(level, next) {
+    if (next === undefined) {
+        return { kind: "print-help", text: level.helpText, stream: "stderr", exitCode: 2 };
+    }
+    if (level.subcommands.includes(next)) {
+        throw unexpectedArgument(next, level.usage, removeDashesTip(next));
+    }
+    throw unrecognizedSubcommand(level, next);
+}
+// clap dispatches a short-flag cluster on its first character: -hx prints
+// help, -Vx prints the version, and anything else errors naming just the
+// first short (-xy → '-x'). "Character" means one code point, like Rust's
+// char — never half of a surrogate pair.
+function dispatchShortCluster(level, token) {
+    const firstShort = Array.from(token.slice(1))[0] ?? "";
+    if (firstShort === "h") {
+        return { kind: "print-help", text: level.helpText, stream: "stdout", exitCode: 0 };
+    }
+    if (level.hasVersion && firstShort === "V") {
+        return { kind: "print-version" };
+    }
+    throw unexpectedArgument(`-${firstShort}`, level.usage);
+}
+function unknownLongFlagAtLevel(level, token, remainingArgs) {
+    const flagName = token.slice(2).split("=", 1)[0] ?? "";
+    const shown = `--${flagName}`;
+    const similar = didYouMean(flagName, level.longFlags);
+    if (similar !== undefined) {
+        const usage = `Usage: ${level.usagePrefix} --${similar} <COMMAND>`;
+        return unexpectedArgument(shown, usage, similarArgumentTip(similar));
+    }
+    // clap's cross-level fallback: when a LATER argv token names one of this
+    // level's subcommands and that subcommand has a similar flag, point the
+    // user at the flag's real home ("tip: 'setup --print' exists").
+    for (const subcommand of level.subcommandFlags) {
+        if (!remainingArgs.includes(subcommand.name)) {
+            continue;
+        }
+        const subcommandSimilar = didYouMean(flagName, subcommand.longFlags);
+        if (subcommandSimilar !== undefined) {
+            return unexpectedArgument(shown, level.usage, `  tip: '${subcommand.name} --${subcommandSimilar}' exists`);
+        }
+    }
+    return unexpectedArgument(shown, level.usage);
+}
+function unrecognizedSubcommand(level, subcommand) {
+    const similar = didYouMean(subcommand, level.subcommands);
+    const tip = similar === undefined ? "" : `  tip: a similar subcommand exists: '${similar}'\n\n`;
+    return new CliError(`error: unrecognized subcommand '${sanitizeForTerminal(subcommand)}'\n\n${tip}${level.usage}\n\nFor more information, try '--help'.`, 2);
+}

package/dist/clap-suggestions.js

@@ -0,0 +1,66 @@
+// A faithful port of clap 4.6.0's "did you mean" suggestion logic so typo
+// tips match the retired Rust CLI byte-for-byte: strsim 0.11.1's Jaro
+// similarity (clap deliberately avoids jaro_winkler — strsim GH #4660), a
+// strict > 0.7 threshold, and clap's tie behavior (a later candidate wins a
+// similarity tie).
+// strsim::jaro over Unicode code points.
+export function jaroSimilarity(left, right) {
+    // Array.from splits on Unicode code points, matching strsim's char iteration.
+    const a = Array.from(left);
+    const b = Array.from(right);
+    if (a.length === 0 && b.length === 0) {
+        return 1;
+    }
+    if (a.length === 0 || b.length === 0) {
+        return 0;
+    }
+    const searchRange = Math.max(0, Math.floor(Math.max(a.length, b.length) / 2) - 1);
+    const aFlags = new Array(a.length).fill(false);
+    const bFlags = new Array(b.length).fill(false);
+    let matches = 0;
+    for (let i = 0; i < a.length; i += 1) {
+        const minBound = i > searchRange ? i - searchRange : 0;
+        const maxBound = Math.min(b.length, i + searchRange + 1);
+        for (let j = minBound; j < maxBound; j += 1) {
+            if (a[i] === b[j] && !bFlags[j]) {
+                aFlags[i] = true;
+                bFlags[j] = true;
+                matches += 1;
+                break;
+            }
+        }
+    }
+    if (matches === 0) {
+        return 0;
+    }
+    let transpositions = 0;
+    let j = 0;
+    for (let i = 0; i < a.length; i += 1) {
+        if (!aFlags[i]) {
+            continue;
+        }
+        while (!bFlags[j]) {
+            j += 1;
+        }
+        if (a[i] !== b[j]) {
+            transpositions += 1;
+        }
+        j += 1;
+    }
+    transpositions = Math.floor(transpositions / 2);
+    return ((matches / a.length + matches / b.length + (matches - transpositions) / matches) / 3);
+}
+// clap's did_you_mean(...).pop(): the single most similar candidate above
+// the threshold, or undefined. Ties go to the later candidate.
+export function didYouMean(input, candidates) {
+    let best;
+    let bestConfidence = 0;
+    for (const candidate of candidates) {
+        const confidence = jaroSimilarity(input, candidate);
+        if (confidence > 0.7 && confidence >= bestConfidence) {
+            best = candidate;
+            bestConfidence = confidence;
+        }
+    }
+    return best;
+}

package/dist/cli-error.js

@@ -0,0 +1,12 @@
+// A user-facing CLI failure. `exitCode` mirrors the original Rust CLI:
+// 2 for argument/usage errors (clap's convention), 1 for command errors
+// such as an unsupported client name. The message is printed to stderr
+// verbatim; it must already be consumer-safe.
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode) {
+        super(message);
+        this.name = "CliError";
+        this.exitCode = exitCode;
+    }
+}

package/dist/credentials/clear-outcome.js

@@ -0,0 +1 @@
+export {};

package/dist/credentials/file-store.js

@@ -0,0 +1,77 @@
+// Fallback credential storage: ~/.driggsby/credentials.json, written
+// atomically with owner-only permissions. This is the only backend on
+// Windows (no readable credential CLI exists there; the profile directory's
+// default user-only ACL is the boundary) and the fallback everywhere else.
+import { randomUUID } from "node:crypto";
+import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import {} from "./clear-outcome.js";
+export function credentialsFilePath(homeDirectory) {
+    return join(homeDirectory, ".driggsby", "credentials.json");
+}
+export async function readFileToken(homeDirectory) {
+    let raw;
+    try {
+        raw = await readFile(credentialsFilePath(homeDirectory), "utf8");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null) {
+            return null;
+        }
+        const token = parsed.app_token;
+        return typeof token === "string" && token !== "" ? token : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeFileToken(homeDirectory, token) {
+    const directory = join(homeDirectory, ".driggsby");
+    // mode applies only when the directory is created; an existing ~/.driggsby
+    // keeps whatever permissions the user already gave it.
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const finalPath = credentialsFilePath(homeDirectory);
+    const temporaryPath = join(directory, `credentials.json.${randomUUID()}.tmp`);
+    const body = `${JSON.stringify({ app_token: token }, null, 2)}\n`;
+    try {
+        await writeFile(temporaryPath, body, { mode: 0o600 });
+        await rename(temporaryPath, finalPath);
+    }
+    catch (error) {
+        await rm(temporaryPath, { force: true });
+        throw error;
+    }
+}
+export async function clearFileToken(homeDirectory) {
+    let outcome;
+    try {
+        await rm(credentialsFilePath(homeDirectory));
+        outcome = "cleared";
+    }
+    catch (error) {
+        outcome = error.code === "ENOENT" ? "absent" : "failed";
+    }
+    // A crash between writeFileToken's temp write and its rename can strand a
+    // readable token in a `credentials.json.<uuid>.tmp` file; removal must not
+    // leave one behind while reporting the token gone.
+    try {
+        for (const entry of await readdir(join(homeDirectory, ".driggsby"))) {
+            if (entry.startsWith("credentials.json.") && entry.endsWith(".tmp")) {
+                try {
+                    await rm(join(homeDirectory, ".driggsby", entry), { force: true });
+                }
+                catch {
+                    outcome = "failed";
+                }
+            }
+        }
+    }
+    catch {
+        // No ~/.driggsby directory at all: nothing was ever stored here.
+    }
+    return outcome;
+}

package/dist/credentials/keychain.js

@@ -0,0 +1,54 @@
+// macOS keychain backend, via the system `security` CLI. The service name
+// `driggsby-cli` is distinct from the legacy Rust-era `driggsby.cli` items,
+// so old installs are never touched. `security` is invoked by its absolute
+// system path, never resolved through PATH, so a lookalike binary earlier on
+// PATH can never receive the token; tests override the path to a fake.
+import {} from "./clear-outcome.js";
+import { runCredentialTool } from "./tool-runner.js";
+const SECURITY_PROGRAM = "/usr/bin/security";
+const SERVICE = "driggsby-cli";
+const ACCOUNT = "app-token";
+// errSecItemNotFound, the exit code `security` uses for a missing item.
+const SECURITY_ITEM_NOT_FOUND = 44;
+// Every keychain call resolves `security` through this one function, and it
+// is exported so a test can pin the absolute-path invariant (no PATH lookup)
+// without ever invoking the real binary.
+export function resolveSecurityProgram(options) {
+    return options.securityProgram ?? SECURITY_PROGRAM;
+}
+export async function readKeychainToken(options = {}) {
+    const result = await runCredentialTool(resolveSecurityProgram(options), ["find-generic-password", "-s", SERVICE, "-a", ACCOUNT, "-w"], options);
+    if (result.kind !== "output") {
+        return { kind: "unavailable" };
+    }
+    if (result.exitCode === SECURITY_ITEM_NOT_FOUND) {
+        return { kind: "absent" };
+    }
+    if (result.exitCode !== 0) {
+        return { kind: "unavailable" };
+    }
+    const token = result.stdout.replace(/\r?\n$/, "");
+    return token === "" ? { kind: "absent" } : { kind: "token", token };
+}
+// -U updates the existing item in place, so re-login replaces the token.
+// The token rides on the argument list here: `security` offers no stdin path
+// for -w, and on macOS another user cannot read this process's arguments —
+// the same tradeoff every keychain-writing CLI accepts.
+export async function writeKeychainToken(token, options = {}) {
+    const result = await runCredentialTool(resolveSecurityProgram(options), ["add-generic-password", "-U", "-s", SERVICE, "-a", ACCOUNT, "-w", token], options);
+    return result.kind === "output" && result.exitCode === 0;
+}
+export async function clearKeychainToken(options = {}) {
+    const result = await runCredentialTool(resolveSecurityProgram(options), ["delete-generic-password", "-s", SERVICE, "-a", ACCOUNT], options);
+    if (result.kind === "not-found") {
+        // No `security` binary means no keychain this CLI could have written to.
+        return "absent";
+    }
+    if (result.kind !== "output") {
+        return "failed";
+    }
+    if (result.exitCode === 0) {
+        return "cleared";
+    }
+    return result.exitCode === SECURITY_ITEM_NOT_FOUND ? "absent" : "failed";
+}

package/dist/credentials/secret-tool.js

@@ -0,0 +1,48 @@
+// Linux keyring backend, via `secret-tool` (libsecret) when it is on PATH.
+// The token is written over stdin, never on the argument list, because Linux
+// exposes every process's arguments to every local user via /proc.
+import {} from "./clear-outcome.js";
+import { runCredentialTool } from "./tool-runner.js";
+const SERVICE_ATTRIBUTE = ["service", "driggsby-cli"];
+export async function readKeyringToken(options = {}) {
+    const result = await runCredentialTool("secret-tool", ["lookup", ...SERVICE_ATTRIBUTE], options);
+    if (result.kind !== "output") {
+        return { kind: "unavailable" };
+    }
+    if (result.exitCode !== 0) {
+        // secret-tool exits 1 both for "no such secret" and for real errors; the
+        // stderr text is not a stable contract, so treat every non-zero lookup as
+        // absent and let the caller fall back to the file store on read.
+        return { kind: "absent" };
+    }
+    const token = result.stdout.replace(/\r?\n$/, "");
+    return token === "" ? { kind: "absent" } : { kind: "token", token };
+}
+export async function writeKeyringToken(token, options = {}) {
+    const result = await runCredentialTool("secret-tool", ["store", "--label", "Driggsby CLI", ...SERVICE_ATTRIBUTE], { ...options, stdinText: token });
+    return result.kind === "output" && result.exitCode === 0;
+}
+// `secret-tool clear` exits 0 whether or not anything matched, so existence
+// is checked first: without that, "removed" and "there was never anything to
+// remove" would be indistinguishable. A lookup that cannot answer (no
+// session bus, locked keyring, timeout) must NOT collapse into "absent":
+// that would tell the user a token is gone while it keeps working. The
+// clear's own exit status is the tiebreaker — it exits 0 whenever the
+// keyring is reachable (match or no match) and non-zero when it is not.
+export async function clearKeyringToken(options = {}) {
+    const lookup = await runCredentialTool("secret-tool", ["lookup", ...SERVICE_ATTRIBUTE], options);
+    if (lookup.kind === "not-found") {
+        // No secret-tool binary means no keyring this CLI could have written to.
+        return "absent";
+    }
+    if (lookup.kind !== "output") {
+        // The tool crashed or hung; the keyring may still hold a live token.
+        return "failed";
+    }
+    const hadToken = lookup.exitCode === 0 && lookup.stdout.replace(/\r?\n$/, "") !== "";
+    const result = await runCredentialTool("secret-tool", ["clear", ...SERVICE_ATTRIBUTE], options);
+    if (result.kind !== "output" || result.exitCode !== 0) {
+        return "failed";
+    }
+    return hadToken ? "cleared" : "absent";
+}

package/dist/credentials/store.js

@@ -0,0 +1,164 @@
+// The credential store facade: one read/save/clear surface over the
+// platform backends. Precedence on read: the DRIGGSBY_TOKEN environment
+// variable (the CI/sandbox path), then the platform keyring (macOS keychain
+// or Linux secret-tool), then the ~/.driggsby/credentials.json file. Token
+// values never appear in output or errors; callers describe locations, not
+// contents.
+import { homedir } from "node:os";
+import { CliError } from "../cli-error.js";
+import { wrapProse } from "../terminal-text.js";
+import {} from "./clear-outcome.js";
+import { clearFileToken, readFileToken, writeFileToken } from "./file-store.js";
+import { clearKeychainToken, readKeychainToken, writeKeychainToken, } from "./keychain.js";
+import { clearKeyringToken, readKeyringToken, writeKeyringToken } from "./secret-tool.js";
+export function defaultCredentialEnvironment() {
+    return { platform: process.platform, env: process.env, homeDirectory: homedir() };
+}
+function keychainOptions(environment) {
+    return { spawnEnv: environment.spawnEnv, securityProgram: environment.securityProgram };
+}
+function keyringOptions(environment) {
+    return { spawnEnv: environment.spawnEnv };
+}
+// The DRIGGSBY_TOKEN override, or null when unset or blank. One definition,
+// so "a blank env token is ignored" holds everywhere it is consulted.
+export function environmentToken(environment) {
+    const token = environment.env.DRIGGSBY_TOKEN?.trim();
+    return token === undefined || token === "" ? null : token;
+}
+export async function readStoredToken(environment = defaultCredentialEnvironment()) {
+    const envToken = environmentToken(environment);
+    if (envToken !== null) {
+        return { token: envToken, source: "env" };
+    }
+    if (environment.platform === "darwin") {
+        const result = await readKeychainToken(keychainOptions(environment));
+        if (result.kind === "token") {
+            return { token: result.token, source: "keychain" };
+        }
+    }
+    else if (environment.platform === "linux") {
+        const result = await readKeyringToken(keyringOptions(environment));
+        if (result.kind === "token") {
+            return { token: result.token, source: "keyring" };
+        }
+    }
+    const fileToken = await readFileToken(environment.homeDirectory);
+    return fileToken === null ? null : { token: fileToken, source: "file" };
+}
+// Saves the token to the preferred backend for this platform and returns
+// where it landed. A failed platform keyring falls back to the file store —
+// but never silently: the keyring outranks the file on read, so an old
+// keyring token that cannot be removed would shadow the token being saved.
+// A readable shadowing token is a hard failure; an unverifiable keyring
+// (locked, unreachable) falls back with a loud warning through `warn`.
+export async function saveToken(token, environment, warn) {
+    if (environment.platform === "darwin") {
+        if (await writeKeychainToken(token, keychainOptions(environment))) {
+            // A stale file copy must not shadow or outlive the keychain token.
+            await clearFileToken(environment.homeDirectory);
+            return "keychain";
+        }
+        await guardAgainstShadowingToken({
+            clearOutcome: await clearKeychainToken(keychainOptions(environment)),
+            presence: async () => {
+                const read = await readKeychainToken(keychainOptions(environment));
+                if (read.kind === "token") {
+                    return "present";
+                }
+                // `security` answers a definitive "no such item" (exit 44) distinctly
+                // from errors, so an absent answer here is trustworthy.
+                return read.kind === "absent" ? "absent" : "unknown";
+            },
+            problem: "an older token is stored in your macOS keychain and couldn't be replaced or removed. If your keychain is locked, unlock it, then sign in again",
+            unverifiedWarning: "Note: we couldn't check your macOS keychain for an older Driggsby app token.\n" +
+                "If one is still there, driggsby commands will use it instead of the token\n" +
+                "saved just now. To fix that, unlock your keychain, then sign out and back in:\n" +
+                "  npx driggsby@latest logout\n" +
+                "  npx driggsby@latest login\n",
+            warn,
+        });
+    }
+    else if (environment.platform === "linux") {
+        if (await writeKeyringToken(token, keyringOptions(environment))) {
+            await clearFileToken(environment.homeDirectory);
+            return "keyring";
+        }
+        await guardAgainstShadowingToken({
+            clearOutcome: await clearKeyringToken(keyringOptions(environment)),
+            presence: async () => {
+                const read = await readKeyringToken(keyringOptions(environment));
+                // secret-tool's non-zero lookup exit is ambiguous (no match, or the
+                // keyring is unreachable), so a non-token answer never counts as a
+                // definitive absence here.
+                return read.kind === "token" ? "present" : "unknown";
+            },
+            problem: "an older token is stored in your system keyring and couldn't be replaced or removed. Check that your keyring is unlocked, then sign in again",
+            unverifiedWarning: "Note: we couldn't check your system keyring for an older Driggsby app token.\n" +
+                "If one is still there, driggsby commands will use it instead of the token\n" +
+                "saved just now. To fix that, make sure your keyring is unlocked, then sign\n" +
+                "out and back in:\n" +
+                "  npx driggsby@latest logout\n" +
+                "  npx driggsby@latest login\n",
+            warn,
+        });
+    }
+    await writeFileToken(environment.homeDirectory, token);
+    return "file";
+}
+// Called when a keyring write failed and the save is about to fall back to
+// the file store. If an older keyring token exists and cannot be cleared, it
+// would win over the file copy on every future read, so the save fails
+// loudly instead of storing a token that will never be used. When the
+// keyring cannot even be read — the same brokenness that failed the write —
+// the fallback proceeds, but with a warning: silence here would let a stale
+// token quietly win once the keyring becomes readable again. A definitive
+// "absent" answer needs neither: there is nothing to shadow.
+async function guardAgainstShadowingToken(check) {
+    if (check.clearOutcome !== "failed") {
+        return;
+    }
+    const presence = await check.presence();
+    if (presence === "present") {
+        throw new CliError(`${wrapProse(`We couldn't save your Driggsby app token: ${check.problem}:`)}\n  npx driggsby@latest login`, 1);
+    }
+    if (presence === "unknown") {
+        check.warn(check.unverifiedWarning);
+    }
+}
+export async function clearStoredToken(environment = defaultCredentialEnvironment()) {
+    const clearedSources = [];
+    const failedSources = [];
+    const record = (source, outcome) => {
+        if (outcome === "cleared") {
+            clearedSources.push(source);
+        }
+        else if (outcome === "failed") {
+            failedSources.push(source);
+        }
+    };
+    if (environment.platform === "darwin") {
+        record("keychain", await clearKeychainToken(keychainOptions(environment)));
+    }
+    else if (environment.platform === "linux") {
+        record("keyring", await clearKeyringToken(keyringOptions(environment)));
+    }
+    record("file", await clearFileToken(environment.homeDirectory));
+    return {
+        clearedSources,
+        failedSources,
+        envTokenStillSet: environmentToken(environment) !== null,
+    };
+}
+export function describeStorageLocation(source) {
+    switch (source) {
+        case "env":
+            return "the DRIGGSBY_TOKEN environment variable";
+        case "keychain":
+            return "your macOS keychain";
+        case "keyring":
+            return "your system keyring";
+        case "file":
+            return "the ~/.driggsby/credentials.json file";
+    }
+}

package/dist/credentials/tool-runner.js

@@ -0,0 +1,55 @@
+// Runs a platform credential tool (macOS `security`, Linux `secret-tool`)
+// with a hard timeout, optional stdin, and captured output. POSIX-only by
+// construction: Windows uses the file store and never reaches this module,
+// so there is no .cmd shim handling here. Programs are fixed constants named
+// by the calling backend; nothing user-controlled selects the program.
+import { spawn } from "node:child_process";
+const CREDENTIAL_TOOL_TIMEOUT_MS = 15_000;
+export function runCredentialTool(program, args, options = {}) {
+    return new Promise((resolve) => {
+        const child = spawn(program, [...args], {
+            stdio: [options.stdinText === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+            env: options.spawnEnv ?? process.env,
+        });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const settle = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            resolve(result);
+        };
+        const timer = setTimeout(() => {
+            child.kill();
+            // A tool that ignores SIGTERM must not linger with the token; the
+            // follow-up SIGKILL is unref'd so it never holds the process open.
+            setTimeout(() => child.kill("SIGKILL"), 2_000).unref();
+            settle({ kind: "timed-out" });
+        }, options.timeoutMs ?? CREDENTIAL_TOOL_TIMEOUT_MS);
+        child.stdout?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr?.setEncoding("utf8");
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", (error) => {
+            settle(error.code === "ENOENT" ? { kind: "not-found" } : { kind: "spawn-error" });
+        });
+        child.on("close", (code) => {
+            settle({ kind: "output", exitCode: code ?? 1, stdout, stderr });
+        });
+        if (options.stdinText !== undefined && child.stdin !== null) {
+            // A tool that exits without reading stdin can EPIPE the write; that is
+            // its own failure signal, never a crash of ours.
+            child.stdin.on("error", () => {
+                // Swallowed deliberately; the tool's exit code is the signal.
+            });
+            child.stdin.end(options.stdinText);
+        }
+    });
+}