@bli-cockpit/cli 0.2.124 → 0.2.126

package/dist/commands/careers-resume.js

@@ -0,0 +1,111 @@
+import { stat, writeFile } from 'node:fs/promises';
+import { writeLine } from './cli-io.js';
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from './agent-door.js';
+/**
+ * `cockpit careers resume <id>` — the drawer's "Open resume" button, typed
+ * (BLI-4462).
+ *
+ * It lives beside `careers.ts` rather than inside it because it is the only
+ * careers verb that does not end at `emitAgentDoor`: the Tower door answers
+ * with a SIGNED URL that lives 60 seconds, and `--out <path>` spends it here,
+ * fetching the private object straight from storage and writing the bytes to
+ * disk. Two requests, one act.
+ *
+ * The URL is a bearer credential for that object, so it goes to stdout only
+ * when a person asked for it and NEVER into a log line: every `[careers
+ * resume]` line carries the application id, a byte count, the seconds left and
+ * a reason label. The overwrite refusal is checked twice, once before the
+ * link is fetched so the sentence is the useful one, and again by opening the
+ * file with `wx`, which is what actually closes the race.
+ */
+const TAG = '[careers resume]';
+const RESUME_TIMEOUT_MS = 60_000;
+/** What the door promises the link is good for. Read from the answer when it says. */
+const DEFAULT_EXPIRES_IN_SECONDS = 60;
+export async function runCareersResume(command, door) {
+    const id = command.id ?? '';
+    const outPath = command.outPath;
+    if (outPath !== undefined && command.force !== true && await fileExists(outPath)) {
+        return failAgentDoor(door, TAG, 'file_exists', `${outPath} is already there, so nothing was downloaded. Pass --force to overwrite it, or name another path.`);
+    }
+    const answer = await askAgentDoor(door, {
+        path: `/api/careers/applications/${encodeURIComponent(id)}/resume-url`,
+        method: 'GET',
+        label: 'careers resume',
+        timeoutMs: RESUME_TIMEOUT_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const url = readUrl(answer.body);
+    if (!url) {
+        return failAgentDoor(door, TAG, 'no_signed_url', 'Tower answered that door without a link, so there is nothing to open or download. That application may have no resume on file.');
+    }
+    const expiresInSeconds = readExpiry(answer.body);
+    if (outPath === undefined)
+        return emitLink(door, id, url, expiresInSeconds);
+    return downloadResume(door, { id, url, outPath, force: command.force === true, expiresInSeconds });
+}
+/** No `--out`: the link itself, on stdout, and never in the receipt line. */
+function emitLink(door, id, url, expiresInSeconds) {
+    writeLine(door.io.stderr, `${TAG} link ${JSON.stringify({ application_id: id, expires_in_seconds: expiresInSeconds, reason: 'signed_url_issued' })}`);
+    if (door.json)
+        return emitAgentDoor(door, { url, expires_in_seconds: expiresInSeconds });
+    writeLine(door.io.stdout, url);
+    return 0;
+}
+async function downloadResume(door, file) {
+    // Straight to storage, not through Tower: this URL IS the authorisation, and
+    // the device token has no business on a request to another host.
+    let response;
+    try {
+        response = await door.io.fetch(file.url, { method: 'GET' });
+    }
+    catch (error) {
+        return failAgentDoor(door, TAG, 'download_failed', `Could not reach the storage that holds that resume: ${error instanceof Error ? error.message : String(error)}. Nothing was written to ${file.outPath}.`);
+    }
+    if (!response.ok) {
+        return failAgentDoor(door, TAG, `http_${response.status}`, `Storage answered ${response.status} for that resume; the link is only good for ${file.expiresInSeconds} seconds. Nothing was written to ${file.outPath}.`);
+    }
+    const bytes = Buffer.from(await response.arrayBuffer());
+    try {
+        // `wx` fails rather than clobbering: the check above is the good sentence,
+        // this is the one that holds when the file appears in between.
+        await writeFile(file.outPath, bytes, file.force ? {} : { flag: 'wx' });
+    }
+    catch (error) {
+        const reason = error?.code === 'EEXIST' ? 'file_exists' : 'write_failed';
+        writeLine(door.io.stderr, `${TAG} download ${JSON.stringify({ application_id: file.id, bytes: bytes.length, reason })}`);
+        return failAgentDoor(door, TAG, reason, `Downloaded ${bytes.length} bytes and could not write them to ${file.outPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    writeLine(door.io.stderr, `${TAG} download ${JSON.stringify({ application_id: file.id, bytes: bytes.length, reason: 'written' })}`);
+    if (door.json)
+        return emitAgentDoor(door, { path: file.outPath, bytes: bytes.length });
+    writeLine(door.io.stdout, `Wrote ${bytes.length} bytes to ${file.outPath}.`);
+    return 0;
+}
+function readUrl(body) {
+    if (!body || typeof body !== 'object')
+        return null;
+    const value = body['url'];
+    return typeof value === 'string' && value.trim() !== '' ? value : null;
+}
+/**
+ * The door answers `expires_in`; every surface a person reads says
+ * `expires_in_seconds`, because "60" with no unit is the kind of number that
+ * gets read as minutes.
+ */
+function readExpiry(body) {
+    if (!body || typeof body !== 'object')
+        return DEFAULT_EXPIRES_IN_SECONDS;
+    const value = body['expires_in'];
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : DEFAULT_EXPIRES_IN_SECONDS;
+}
+async function fileExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/commands/careers.js

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor } from './agent-door.js';
+import { runCareersResume } from './careers-resume.js';
 /**
  * `cockpit careers` — application review (BLI-3706) and, since BLI-4460, the
  * pipeline: invite, decide, the role's take-home and the settings. BLI-4461
@@ -9,9 +10,15 @@ import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor } from './age
  * decides policy. The take-home body arrives from a FILE rather than a flag,
  * because an email body does not belong in an argument vector, a shell history
  * or a process list.
+ *
+ * `resume` (BLI-4462) is the one verb that does not end at `emitAgentDoor`,
+ * because its answer is a 60-second signed URL and `--out` spends it on a
+ * download. That work lives in `careers-resume.ts`.
  */
 export async function runCareers(command, io) {
     const door = await openAgentDoor('careers', command, io);
+    if (command.action === 'resume')
+        return runCareersResume(command, door);
     let plan;
     try {
         plan = await planCareersRequest(command);
@@ -47,6 +54,10 @@ async function planCareersRequest(command) {
         // names where the run actually happens rather than implying it ran here.
         case 'grade': return { path: `${application}/grade`, method: 'POST', body: { now: command.now === true } };
         case 'decide': return { path: `${application}/decide`, method: 'POST', body: { decision: command.decision } };
+        // `resume` never arrives here: `runCareers` hands it to `careers-resume.ts`
+        // above, which owns both of its requests. The case keeps the switch
+        // exhaustive, so a verb added later cannot fall through this table unseen.
+        case 'resume': throw new Error('careers resume is answered by runCareersResume, not by this table.');
         case 'takehome-show': return { path: takehomePath(command), method: 'GET' };
         case 'takehome-set': return { path: takehomePath(command), method: 'PUT', body: await takehomeBody(command) };
         case 'settings-show': return { path: '/api/careers/settings', method: 'GET' };

package/dist/commands/local-args-tower-careers.js

@@ -1,12 +1,14 @@
 import { optionalNonEmpty, optionalUrl, parseNamedArgs } from './local-arg-values.js';
-const ACTIONS = ['list', 'show', 'rescreen', 'invite', 'decide', 'grade', 'takehome-show', 'takehome-set', 'settings-show', 'settings-set'];
+const ACTIONS = ['list', 'show', 'rescreen', 'invite', 'decide', 'grade', 'resume', 'takehome-show', 'takehome-set', 'settings-show', 'settings-set'];
+/** Typed word → the one action it means. The left side is what a person reads on the button. */
+const ALSO_SPELLED = { 'send-takehome': 'invite' };
 const DECISIONS = ['passed_on', 'archived', 'reopen'];
 /** Verbs that name an application id, a role slug, or nothing at all. */
-const NEEDS_ID = ['show', 'rescreen', 'invite', 'decide', 'grade'];
+const NEEDS_ID = ['show', 'rescreen', 'invite', 'decide', 'grade', 'resume'];
 const NEEDS_ROLE = ['takehome-show', 'takehome-set'];
 export function parseCareersArgs(args) {
-    const valueFlags = ['--role', '--min-score', '--since', '--home', '--dashboard-url', '--decision', '--stage', '--subject', '--body-file', '--link', '--pass-score', '--account', '--auto-invite-min-score', '--attention-min-score', '--enabled', '--booking-link', '--grader-model'];
-    const values = parseNamedArgs(args, { allowedFlags: [...valueFlags, '--json', '--now'], valueFlags });
+    const valueFlags = ['--role', '--min-score', '--since', '--home', '--dashboard-url', '--decision', '--stage', '--subject', '--body-file', '--link', '--pass-score', '--account', '--auto-invite-min-score', '--attention-min-score', '--enabled', '--booking-link', '--grader-model', '--out'];
+    const values = parseNamedArgs(args, { allowedFlags: [...valueFlags, '--json', '--now', '--force'], valueFlags });
     const positionals = [...values.positionals];
     // `takehome show` and `settings set` are two words a person types and one
     // action everything downstream reads.
@@ -14,15 +16,18 @@ export function parseCareersArgs(args) {
     // `team device` reads as `team device list`: the noun alone is a question.
     const first = positionals[0] ?? 'list';
     const paired = first === 'takehome' || first === 'settings';
-    const action = paired
+    const typed = paired
         ? `${first}-${positionals.splice(0, positionals[1] === undefined ? 1 : 2)[1] ?? 'show'}`
         : (positionals.shift() ?? 'list');
+    // `send-takehome` is the button's own words; `invite` is the older spelling
+    // of the same act. One action from here on, the typed word only for errors.
+    const action = ALSO_SPELLED[typed] ?? typed;
     if (!ACTIONS.includes(action))
-        throw new Error(`careers takes ${ACTIONS.join(', ')}.`);
+        throw new Error(`careers takes ${[...ACTIONS, ...Object.keys(ALSO_SPELLED)].join(', ')}.`);
     const verb = action;
     const target = positionals.shift();
     if (NEEDS_ID.includes(verb) && !target)
-        throw new Error(`careers ${verb} needs an application id.`);
+        throw new Error(`careers ${typed} needs an application id.`);
     if (NEEDS_ROLE.includes(verb) && !target)
         throw new Error(`careers ${verb.replace('-', ' ')} needs a role slug.`);
     if (positionals.length > 0)
@@ -43,6 +48,16 @@ export function parseCareersArgs(args) {
     const enabledRaw = optionalNonEmpty(values.flags.get('--enabled'));
     if (enabledRaw !== undefined && enabledRaw !== 'true' && enabledRaw !== 'false')
         throw new Error('--enabled must be true or false.');
+    // The resume is the only thing this noun writes to disk, so both file flags
+    // belong to it alone and say so rather than being accepted and ignored.
+    const outPath = optionalNonEmpty(values.flags.get('--out'));
+    const force = values.booleans.has('--force');
+    if (outPath !== undefined && verb !== 'resume')
+        throw new Error('--out belongs to `cockpit careers resume <id>`.');
+    if (force && verb !== 'resume')
+        throw new Error('--force belongs to `cockpit careers resume <id> --out <path>`.');
+    if (force && outPath === undefined)
+        throw new Error('--force only means something beside --out <path>: with no file to write there is nothing to overwrite.');
     return {
         kind: 'careers', action: verb,
         id: NEEDS_ID.includes(verb) ? target : undefined,
@@ -55,6 +70,7 @@ export function parseCareersArgs(args) {
         bookingLink: httpsFlag(values.flags.get('--booking-link')),
         graderModel: optionalNonEmpty(values.flags.get('--grader-model')),
         now: values.booleans.has('--now'),
+        outPath, force,
         autoInviteMinScore, attentionMinScore,
         autoInviteEnabled: enabledRaw === undefined ? undefined : enabledRaw === 'true',
         homeDir: optionalNonEmpty(values.flags.get('--home')), dashboardUrl: optionalUrl(values.flags.get('--dashboard-url')), json: values.booleans.has('--json'),

package/dist/commands/local-help-commands-tower.js

@@ -25,13 +25,14 @@ export const TOWER_COMMAND_HELP = [
     [
         "careers",
         [
-            "Usage: cockpit careers [list|show <id>|rescreen <id>|invite <id>|decide <id> --decision <d>|grade <id>|takehome show <role>|takehome set <role>|settings show|settings set] [flags]",
+            "Usage: cockpit careers [list|show <id>|rescreen <id>|send-takehome <id>|decide <id> --decision <d>|grade <id>|resume <id>|takehome show <role>|takehome set <role>|settings show|settings set] [flags]",
             "",
             "Super-admin application review and pipeline. Lists at most 100 matches with total and has_more; use filters to narrow.",
             "list [--role <slug>] [--min-score <n>] [--since <date>] [--stage <screened|invited|submitted|graded|booking_sent|passed_on|archived>] — the board, newest first, with the two thresholds in force.",
-            "invite <id> — sends that role's take-home from the configured mailbox, whatever the screening scored. Only a row still at `screened`.",
+            "send-takehome <id> (also `invite <id>`): sends that role's take-home from the configured mailbox, whatever the screening scored. The same act as Tower's Send take-home button, and only a row still at `screened`.",
             "decide <id> --decision <passed_on|archived|reopen> — your own call on a row; `reopen` puts it back to `screened`.",
             "grade <id> [--now]: puts one submission back in the take-home grader's queue. The grader runs on Railway every 15 minutes; --now says so rather than pretending the run happened here.",
+            "resume <id> [--out <path>] [--force]: the candidate's resume, the same file the drawer's Open resume button shows. Bare, it prints a signed link that dies in 60 seconds; --out downloads the file to that path and refuses to overwrite one already there unless you pass --force.",
             "takehome show <role> — the subject, body, link and the reviewer's rubric for that role.",
             "takehome set <role> [--subject <s>] [--body-file <path>] [--link <url>] [--pass-score <0-10>] — the body comes from a FILE and must keep {first_name} and {link}.",
             "settings show — the bar, the attention threshold, whether automatic sending is on, and which mailbox it goes out from.",

package/dist/commands/local-help.js

@@ -104,7 +104,7 @@ export function localCommandHelp(command) {
         "  cockpit project [list] [--archived] [--dashboard-url <url>] [--json]",
         `  cockpit search "<words>" [--kind ${SEARCH_KINDS.join(",")}] [--limit <n>] [--dashboard-url <url>] [--json]`,
         "  cockpit release [--dry-run] [--skip-checks] [--no-floor] [--tag <tag>] [--access <public|restricted>] [--otp <code>]",
-        "  cockpit careers [list|show <id>|rescreen <id>|invite <id>|decide <id> --decision <passed_on|archived|reopen>|grade <id> [--now]|takehome show <role>|takehome set <role> --body-file <path>|settings show|settings set --enabled <true|false>] [--role <slug>] [--min-score <n>] [--since <date>] [--stage <s>] [--json]",
+        "  cockpit careers [list|show <id>|rescreen <id>|send-takehome <id>|decide <id> --decision <passed_on|archived|reopen>|grade <id> [--now]|resume <id> [--out <path>]|takehome show <role>|takehome set <role> --body-file <path>|settings show|settings set --enabled <true|false>] [--role <slug>] [--min-score <n>] [--since <date>] [--stage <s>] [--force] [--json]",
         "  cockpit usage sessions [--task <BLI-NNNN> | --subject <name>] [--repo <label>] [--since <window>] [--json]",
         "  cockpit usage sessions --session <id> [--from-window <n>] [--json]",
         "  --by-topic groups work types; --by-subject groups open subjects from session summaries.",

package/dist/commands/public-root.js

@@ -15,7 +15,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.124");
+    writeLine(io?.stdout ?? process.stdout, "0.2.126");
     return 0;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.124",
+  "version": "0.2.126",
   "private": false,
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@bli-cockpit/memory-mcp": "0.1.32",
-    "@bli-cockpit/mcp": "0.1.51",
+    "@bli-cockpit/mcp": "0.1.53",
     "@bli-cockpit/telemetry-core": "0.1.48"
   }
 }