putitoutthere 0.1.8 → 0.1.10

package/dist/auth.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `auth login/logout/status` — OAuth Device Flow against the
+ * `putitoutthere-cli` GitHub App (client ID committed to
+ * docs/guide/auth.md).
+ *
+ * Scope: optional. The rest of the CLI authenticates to registries
+ * via env vars; this subcommand exists so `token list` (and later
+ * features) can read repo-secret metadata from GitHub on behalf of
+ * the user. If `auth login` has never been run, those features
+ * degrade gracefully — see #98.
+ *
+ * Token values are never logged or written to stdout. They flow
+ * through the `Keyring` abstraction (see `src/keyring.ts`); in logs
+ * a token is identified by the first 8 hex chars of its SHA-256.
+ */
+import { type Keyring } from './keyring.js';
+/** Public client ID of the `putitoutthere-cli` GitHub App (#104). */
+export declare const CLIENT_ID = "Iv23lio0NtN1koa0Rwle";
+export interface LoginOptions {
+    /** Override the App client ID. Tests inject a fake. */
+    clientId?: string;
+    fetchFn?: typeof fetch;
+    keyring?: Keyring;
+    /** Epoch-seconds clock. Defaults to `Date.now()/1000`. */
+    now?: () => number;
+    /** Awaitable delay between polls. Defaults to real `setTimeout`. */
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * Surface the verification prompt to the user. Callers that want
+     * human-readable output (the CLI) provide one that writes to stderr;
+     * tests pass a capture. Defaults to a no-op.
+     */
+    onPrompt?: (prompt: DevicePrompt) => void;
+}
+export interface DevicePrompt {
+    userCode: string;
+    verificationUri: string;
+    /** Raw seconds-from-now until the device_code expires. */
+    expiresInSeconds: number;
+}
+export interface LoginResult {
+    account: string;
+    /** Epoch seconds at which the *access* token expires. */
+    expiresAt: number;
+}
+export interface LogoutOptions {
+    keyring?: Keyring;
+}
+export interface StatusOptions {
+    fetchFn?: typeof fetch;
+    keyring?: Keyring;
+    now?: () => number;
+}
+export type StatusResult = {
+    authenticated: true;
+    account: string;
+    expiresAt: number;
+} | {
+    authenticated: false;
+    reason: 'not_logged_in' | 'refresh_failed' | 'revoked';
+    message: string;
+};
+export declare function login(opts?: LoginOptions): Promise<LoginResult>;
+export declare function logout(opts?: LogoutOptions): Promise<{
+    wiped: boolean;
+}>;
+export declare function status(opts?: StatusOptions): Promise<StatusResult>;
+/** SHA-256 prefix for identifying a token in logs without leaking it. */
+export declare function tokenDigest(token: string): string;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,EAAkB,KAAK,OAAO,EAAmB,MAAM,cAAc,CAAC;AAE7E,qEAAqE;AACrE,eAAO,MAAM,SAAS,yBAAyB,CAAC;AAehD,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0DAA0D;IAC1D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,oEAAoE;IACpE,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;CAC3C;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,aAAa,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC3D;IACE,aAAa,EAAE,KAAK,CAAC;IACrB,MAAM,EAAE,eAAe,GAAG,gBAAgB,GAAG,SAAS,CAAC;IACvD,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAIN,wBAAsB,KAAK,CAAC,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CA6BzE;AAID,wBAAsB,MAAM,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,CAMlF;AAID,wBAAsB,MAAM,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CAmE5E;AAsMD,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEjD"}

package/dist/auth.js

@@ -0,0 +1,290 @@
+/**
+ * `auth login/logout/status` — OAuth Device Flow against the
+ * `putitoutthere-cli` GitHub App (client ID committed to
+ * docs/guide/auth.md).
+ *
+ * Scope: optional. The rest of the CLI authenticates to registries
+ * via env vars; this subcommand exists so `token list` (and later
+ * features) can read repo-secret metadata from GitHub on behalf of
+ * the user. If `auth login` has never been run, those features
+ * degrade gracefully — see #98.
+ *
+ * Token values are never logged or written to stdout. They flow
+ * through the `Keyring` abstraction (see `src/keyring.ts`); in logs
+ * a token is identified by the first 8 hex chars of its SHA-256.
+ */
+import { createHash } from 'node:crypto';
+import { defaultKeyring } from './keyring.js';
+/** Public client ID of the `putitoutthere-cli` GitHub App (#104). */
+export const CLIENT_ID = 'Iv23lio0NtN1koa0Rwle';
+const GITHUB_DEVICE_URL = 'https://github.com/login/device/code';
+const GITHUB_TOKEN_URL = 'https://github.com/login/oauth/access_token';
+const GITHUB_API_USER = 'https://api.github.com/user';
+const GRANT_DEVICE = 'urn:ietf:params:oauth:grant-type:device_code';
+const GRANT_REFRESH = 'refresh_token';
+/** Seconds of slack to refresh a token before it actually expires. */
+const REFRESH_SKEW_SECONDS = 60;
+/** Bumped when GitHub returns `slow_down`. */
+const SLOW_DOWN_BUMP_SECONDS = 5;
+// ---- login -------------------------------------------------------------
+export async function login(opts = {}) {
+    const clientId = opts.clientId ?? CLIENT_ID;
+    const fetchFn = opts.fetchFn ?? fetch;
+    const keyring = opts.keyring ?? defaultKeyring();
+    const now = opts.now ?? epochSeconds;
+    const sleep = opts.sleep ?? realSleep;
+    const onPrompt = opts.onPrompt ?? (() => undefined);
+    const device = await requestDeviceCode(fetchFn, clientId);
+    onPrompt({
+        userCode: device.user_code,
+        verificationUri: device.verification_uri,
+        expiresInSeconds: device.expires_in,
+    });
+    const tokens = await pollForToken(fetchFn, sleep, clientId, device);
+    const account = await fetchLogin(fetchFn, tokens.access_token);
+    const issuedAt = now();
+    const stored = {
+        account,
+        access_token: tokens.access_token,
+        refresh_token: tokens.refresh_token,
+        access_token_expires_at: issuedAt + tokens.expires_in,
+        refresh_token_expires_at: issuedAt + tokens.refresh_token_expires_in,
+    };
+    await keyring.set(stored);
+    return { account, expiresAt: stored.access_token_expires_at };
+}
+// ---- logout ------------------------------------------------------------
+export async function logout(opts = {}) {
+    const keyring = opts.keyring ?? defaultKeyring();
+    const existing = await keyring.get();
+    if (!existing)
+        return { wiped: false };
+    await keyring.delete();
+    return { wiped: true };
+}
+// ---- status ------------------------------------------------------------
+export async function status(opts = {}) {
+    const fetchFn = opts.fetchFn ?? fetch;
+    const keyring = opts.keyring ?? defaultKeyring();
+    const now = opts.now ?? epochSeconds;
+    const stored = await keyring.get();
+    if (!stored) {
+        return {
+            authenticated: false,
+            reason: 'not_logged_in',
+            message: 'Not logged in. Run `putitoutthere auth login`.',
+        };
+    }
+    let working = stored;
+    const soonExpired = now() >= stored.access_token_expires_at - REFRESH_SKEW_SECONDS;
+    if (soonExpired) {
+        const refreshed = await tryRefresh(fetchFn, keyring, working, now);
+        if (!refreshed) {
+            return {
+                authenticated: false,
+                reason: 'refresh_failed',
+                message: 'Session expired. Run `putitoutthere auth login`.',
+            };
+        }
+        working = refreshed;
+    }
+    const probe = await probeUser(fetchFn, working.access_token);
+    if (probe.ok) {
+        return {
+            authenticated: true,
+            account: probe.login,
+            expiresAt: working.access_token_expires_at,
+        };
+    }
+    if (probe.status !== 401) {
+        // Network or 5xx — don't wipe credentials over a transient blip.
+        return {
+            authenticated: false,
+            reason: 'refresh_failed',
+            message: `GitHub /user probe failed (${probe.status}).`,
+        };
+    }
+    // 401 with a still-unexpired token => credential actually revoked.
+    // Try one refresh before giving up, in case the server clock drifted.
+    const refreshed = await tryRefresh(fetchFn, keyring, working, now);
+    if (!refreshed) {
+        return {
+            authenticated: false,
+            reason: 'revoked',
+            message: 'Token rejected by GitHub. Run `putitoutthere auth login`.',
+        };
+    }
+    const reprobe = await probeUser(fetchFn, refreshed.access_token);
+    if (!reprobe.ok) {
+        return {
+            authenticated: false,
+            reason: 'revoked',
+            message: 'Token rejected by GitHub. Run `putitoutthere auth login`.',
+        };
+    }
+    return {
+        authenticated: true,
+        account: reprobe.login,
+        expiresAt: refreshed.access_token_expires_at,
+    };
+}
+async function requestDeviceCode(fetchFn, clientId) {
+    const res = await fetchFn(GITHUB_DEVICE_URL, {
+        method: 'POST',
+        headers: {
+            accept: 'application/json',
+            'content-type': 'application/x-www-form-urlencoded',
+        },
+        body: new URLSearchParams({ client_id: clientId }).toString(),
+    });
+    if (!res.ok) {
+        throw new Error(`device code request failed: HTTP ${res.status}`);
+    }
+    const body = await res.json();
+    /* v8 ignore next 3 -- defensive; GitHub always returns the documented fields on 2xx. */
+    if (!isDeviceCodeResponse(body)) {
+        throw new Error('device code response missing expected fields');
+    }
+    return body;
+}
+async function pollForToken(fetchFn, sleep, clientId, device) {
+    let intervalSec = device.interval;
+    const deadline = Date.now() + device.expires_in * 1000;
+    while (Date.now() < deadline) {
+        await sleep(intervalSec * 1000);
+        const res = await fetchFn(GITHUB_TOKEN_URL, {
+            method: 'POST',
+            headers: {
+                accept: 'application/json',
+                'content-type': 'application/x-www-form-urlencoded',
+            },
+            body: new URLSearchParams({
+                client_id: clientId,
+                device_code: device.device_code,
+                grant_type: GRANT_DEVICE,
+            }).toString(),
+        });
+        const body = (await res.json());
+        if (isTokenResponse(body))
+            return body;
+        const error = typeof body.error === 'string' ? body.error : 'unknown_error';
+        if (error === 'authorization_pending')
+            continue;
+        if (error === 'slow_down') {
+            intervalSec += SLOW_DOWN_BUMP_SECONDS;
+            continue;
+        }
+        if (error === 'access_denied') {
+            throw new Error('authorization denied by user');
+        }
+        if (error === 'expired_token') {
+            throw new Error('device code expired before approval');
+        }
+        /* v8 ignore start -- unknown error codes + wall-clock deadline are both defensive; GitHub's error set is exhaustive and the server's expired_token fires first. */
+        throw new Error(`device flow error: ${error}`);
+    }
+    throw new Error('device code expired before approval');
+}
+/* v8 ignore stop */
+async function tryRefresh(fetchFn, keyring, current, now) {
+    const res = await fetchFn(GITHUB_TOKEN_URL, {
+        method: 'POST',
+        headers: {
+            accept: 'application/json',
+            'content-type': 'application/x-www-form-urlencoded',
+        },
+        body: new URLSearchParams({
+            client_id: CLIENT_ID,
+            refresh_token: current.refresh_token,
+            grant_type: GRANT_REFRESH,
+        }).toString(),
+    });
+    if (!res.ok)
+        return null;
+    const body = (await res.json());
+    if (!isTokenResponse(body))
+        return null;
+    const issuedAt = now();
+    const next = {
+        account: current.account,
+        access_token: body.access_token,
+        refresh_token: body.refresh_token,
+        access_token_expires_at: issuedAt + body.expires_in,
+        refresh_token_expires_at: issuedAt + body.refresh_token_expires_in,
+    };
+    await keyring.set(next);
+    return next;
+}
+async function fetchLogin(fetchFn, accessToken) {
+    const res = await fetchFn(GITHUB_API_USER, {
+        headers: {
+            authorization: `Bearer ${accessToken}`,
+            accept: 'application/vnd.github+json',
+            'user-agent': 'putitoutthere',
+        },
+    });
+    /* v8 ignore next 3 -- fetchLogin runs only after a successful token grant; the happy-path is covered. */
+    if (!res.ok) {
+        throw new Error(`GitHub /user failed: HTTP ${res.status}`);
+    }
+    const body = (await res.json());
+    /* v8 ignore next 3 -- defensive: GitHub has never shipped /user without a login field. */
+    if (typeof body.login !== 'string') {
+        throw new Error('GitHub /user response missing login');
+    }
+    return body.login;
+}
+async function probeUser(fetchFn, accessToken) {
+    try {
+        const res = await fetchFn(GITHUB_API_USER, {
+            headers: {
+                authorization: `Bearer ${accessToken}`,
+                accept: 'application/vnd.github+json',
+                'user-agent': 'putitoutthere',
+            },
+        });
+        if (!res.ok)
+            return { ok: false, status: res.status };
+        const body = (await res.json());
+        /* v8 ignore next -- defensive: GitHub has never shipped /user without a login field. */
+        if (typeof body.login !== 'string')
+            return { ok: false, status: res.status };
+        return { ok: true, login: body.login };
+        /* v8 ignore next 3 -- network-throw catch; msw can't model a pre-HTTP throw cleanly. */
+    }
+    catch {
+        return { ok: false, status: 0 };
+    }
+}
+// ---- helpers -----------------------------------------------------------
+function isDeviceCodeResponse(v) {
+    if (!v || typeof v !== 'object')
+        return false;
+    const o = v;
+    return (typeof o.device_code === 'string' &&
+        typeof o.user_code === 'string' &&
+        typeof o.verification_uri === 'string' &&
+        typeof o.expires_in === 'number' &&
+        typeof o.interval === 'number');
+}
+function isTokenResponse(v) {
+    if (!v || typeof v !== 'object')
+        return false;
+    const o = v;
+    return (typeof o.access_token === 'string' &&
+        typeof o.expires_in === 'number' &&
+        typeof o.refresh_token === 'string' &&
+        typeof o.refresh_token_expires_in === 'number');
+}
+function epochSeconds() {
+    return Math.floor(Date.now() / 1000);
+}
+/* v8 ignore next 3 -- real timer; every test injects `sleep`. */
+function realSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
+}
+/** SHA-256 prefix for identifying a token in logs without leaking it. */
+export function tokenDigest(token) {
+    return createHash('sha256').update(token).digest('hex').slice(0, 8);
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;GAaG;AAuGH,wBAAsB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA6LlE"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;GAaG;AAiHH,wBAAsB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAsPlE"}

package/dist/cli.js

@@ -14,14 +14,15 @@
  *   --json            for plan; emit JSON instead of a table
  */
 import pkg from '../package.json' with { type: 'json' };
+import { login, logout, status } from './auth.js';
 import { doctor } from './doctor.js';
 import { init } from './init.js';
 import { plan } from './plan.js';
 import { runPreflight } from './preflight-run.js';
 import { publish } from './publish.js';
-import { inspect } from './token.js';
+import { inspect, tokenList } from './token.js';
 const VERSION = pkg.version;
-const COMMANDS = ['init', 'plan', 'publish', 'doctor', 'preflight', 'token', 'version'];
+const COMMANDS = ['init', 'plan', 'publish', 'doctor', 'preflight', 'token', 'auth', 'version'];
 const REGISTRIES = ['crates', 'npm', 'pypi'];
 function isRegistry(v) {
     return REGISTRIES.includes(v);
@@ -39,7 +40,8 @@ function printUsage() {
         '  publish    Execute the plan',
         '  doctor     Validate config + handlers + auth (#23)',
         '  preflight  Run every pre-publish check without side effects (#93)',
-        '  token      Inspect registry tokens (pypi/npm/crates)',
+        '  token      Inspect or list registry tokens (pypi/npm/crates)',
+        '  auth       Optional: sign in to GitHub for `token list --secrets`',
         '  version    Print CLI version',
         '',
         'Options:',
@@ -49,6 +51,8 @@ function printUsage() {
         '  --json            emit machine-readable output (plan only)',
         '  --force           overwrite putitoutthere.toml on init',
         '  --artifacts       doctor: also check artifact completeness',
+        '  --deep            doctor: also inspect each token\'s publish scope',
+        '  --preflight-check publish: refuse on token scope mismatch (pypi/npm)',
         '  --all             preflight: include non-cascaded packages too',
         '  --cadence <mode>  init: immediate (default) or scheduled',
         '  --token <value>   token inspect: token value (else read from env)',
@@ -66,6 +70,8 @@ function parseFlags(argv) {
         force: false,
         artifacts: false,
         all: false,
+        deep: false,
+        preflightCheck: false,
     };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
@@ -84,6 +90,10 @@ function parseFlags(argv) {
             out.artifacts = true;
         else if (a === '--all')
             out.all = true;
+        else if (a === '--deep')
+            out.deep = true;
+        else if (a === '--preflight-check')
+            out.preflightCheck = true;
         else if (a === '--cadence') {
             const v = argv[++i];
             /* v8 ignore next -- invalid cadence is caught by the type system for legit callers */
@@ -153,6 +163,7 @@ export async function run(argv) {
                     /* v8 ignore next -- --config test covered in plan arm; publish shares the same plumbing */
                     ...(flags.config !== undefined ? { configPath: flags.config } : {}),
                     dryRun: flags.dryRun,
+                    preflightCheck: flags.preflightCheck,
                 });
                 if (flags.json) {
                     process.stdout.write(JSON.stringify(result) + '\n');
@@ -175,6 +186,7 @@ export async function run(argv) {
                     /* v8 ignore next -- --config test covered via plan arm */
                     ...(flags.config !== undefined ? { configPath: flags.config } : {}),
                     checkArtifacts: flags.artifacts,
+                    deep: flags.deep,
                 });
                 if (flags.json) {
                     process.stdout.write(JSON.stringify(report) + '\n');
@@ -182,7 +194,10 @@ export async function run(argv) {
                 else {
                     for (const p of report.packages) {
                         const badge = p.auth === 'missing' ? '✗' : '✓';
-                        process.stdout.write(`  ${badge} ${p.name} (${p.kind}) — auth: ${p.auth}\n`);
+                        const scopeSuffix = p.scope !== undefined
+                            ? `  scope: ${p.scope}${p.scope_match && p.scope_match !== 'ok' ? ` [${p.scope_match}]` : ''}`
+                            : '';
+                        process.stdout.write(`  ${badge} ${p.name} (${p.kind}) — auth: ${p.auth}${scopeSuffix}\n`);
                     }
                     if (report.artifacts && report.artifacts.length > 0) {
                         process.stdout.write('\nArtifacts:\n');
@@ -237,9 +252,23 @@ export async function run(argv) {
             }
             case 'token': {
                 const [sub, ...subRest] = rest;
+                if (sub === 'list') {
+                    const subFlags = parseFlags(subRest);
+                    const rows = tokenList({
+                        cwd: subFlags.cwd,
+                        ...(subFlags.config !== undefined ? { configPath: subFlags.config } : {}),
+                    });
+                    if (subFlags.json) {
+                        process.stdout.write(JSON.stringify({ tokens: rows }) + '\n');
+                    }
+                    else {
+                        printTokenList(rows);
+                    }
+                    return 0;
+                }
                 if (sub !== 'inspect') {
                     process.stderr.write(sub === undefined
-                        ? 'putitoutthere token: missing subcommand (expected "inspect")\n'
+                        ? 'putitoutthere token: missing subcommand (expected "inspect" or "list")\n'
                         : `putitoutthere token: unknown subcommand: ${sub}\n`);
                     return 1;
                 }
@@ -261,6 +290,46 @@ export async function run(argv) {
                 }
                 return 'error' in result ? 1 : 0;
             }
+            case 'auth': {
+                const [sub, ...subRest] = rest;
+                const subFlags = parseFlags(subRest);
+                /* v8 ignore start -- `auth login` requires live Device Flow against GitHub; the login() function itself is covered in auth.test.ts */
+                if (sub === 'login') {
+                    const result = await login({
+                        onPrompt: (p) => printDevicePrompt(p),
+                    });
+                    if (subFlags.json) {
+                        process.stdout.write(JSON.stringify(result) + '\n');
+                    }
+                    else {
+                        process.stdout.write(`Logged in as ${result.account} (access token expires ${new Date(result.expiresAt * 1000).toISOString()}).\n`);
+                    }
+                    return 0;
+                }
+                /* v8 ignore stop */
+                if (sub === 'logout') {
+                    const result = await logout();
+                    /* v8 ignore next -- --json branch is a trivial stringify; covered via auth.test.ts for `logout()` */
+                    if (subFlags.json)
+                        process.stdout.write(JSON.stringify(result) + '\n');
+                    else
+                        process.stdout.write(result.wiped ? 'Logged out.\n' : 'Not logged in.\n');
+                    return 0;
+                }
+                if (sub === 'status') {
+                    const result = await status();
+                    /* v8 ignore next -- --json branch is a trivial stringify; covered via auth.test.ts for `status()` */
+                    if (subFlags.json)
+                        process.stdout.write(JSON.stringify(result) + '\n');
+                    else
+                        printAuthStatus(result);
+                    return result.authenticated ? 0 : 1;
+                }
+                process.stderr.write(sub === undefined
+                    ? 'putitoutthere auth: missing subcommand (expected "login", "logout", or "status")\n'
+                    : `putitoutthere auth: unknown subcommand: ${sub}\n`);
+                return 1;
+            }
             case 'init': {
                 const r = init({
                     cwd: flags.cwd,
@@ -319,6 +388,26 @@ function envTokenFor(registry) {
     const filtered = matches.filter((m) => m.registry === registry);
     return filtered[0]?.value;
 }
+function printTokenList(rows) {
+    if (rows.length === 0) {
+        process.stdout.write('no registry tokens found in environment\n');
+        return;
+    }
+    const headers = ['REGISTRY', 'SOURCE', 'ENV/NAME', 'DETAILS'];
+    const widths = headers.map((h) => h.length);
+    for (const r of rows) {
+        widths[0] = Math.max(widths[0], r.registry.length);
+        widths[1] = Math.max(widths[1], r.source.length);
+        widths[2] = Math.max(widths[2], r.name.length);
+        widths[3] = Math.max(widths[3], r.details.length);
+    }
+    const pad = (s, w) => s + ' '.repeat(Math.max(0, w - s.length));
+    const line = (cells) => cells.map((c, i) => pad(c, widths[i])).join('  ').trimEnd() + '\n';
+    process.stdout.write(line(headers));
+    for (const r of rows) {
+        process.stdout.write(line([r.registry, r.source, r.name, r.details]));
+    }
+}
 function printInspectHuman(result) {
     if ('error' in result) {
         process.stderr.write(`inspect failed (${result.registry}, digest=${result.source_digest}): ${result.error}\n`);
@@ -372,6 +461,19 @@ function printInspectHuman(result) {
     }
     process.stdout.write(lines.join('\n') + '\n');
 }
+/* v8 ignore next 6 -- only called from the `auth login` arm above, which is itself v8-ignored */
+function printDevicePrompt(p) {
+    process.stderr.write(`Visit ${p.verificationUri} and enter code: ${p.userCode}\n` +
+        `(code expires in ${Math.round(p.expiresInSeconds / 60)} min)\n`);
+}
+function printAuthStatus(r) {
+    /* v8 ignore next 5 -- `authenticated: true` requires a live GitHub /user response; status() success path is covered in auth.test.ts */
+    if (r.authenticated) {
+        process.stdout.write(`Logged in as ${r.account} (access token expires ${new Date(r.expiresAt * 1000).toISOString()}).\n`);
+        return;
+    }
+    process.stderr.write(`${r.message}\n`);
+}
 // Entry point when invoked as `putitoutthere` or `node dist/cli.js`.
 /* v8 ignore start -- entry-point guard; only reachable when invoked as a binary */
 if (import.meta.url === `file://${process.argv[1]}`) {