@velaro/cli 1.4.92 → 1.4.93

package/lib/commands/agent.js

@@ -1,4 +1,4 @@
-import { get, post, messagingGet, messagingPost, getCredentials }  from '../api.js';
+import { get, post, messagingGet, messagingPost, messagingPut, getCredentials }  from '../api.js';
 import { runCommand }  from '../run.js';
 
 const VALID_STATUSES = ['Available', 'Away', 'Offline'];
@@ -97,6 +97,18 @@ export const agentCommand = {
         console.log(`  ${result.message ?? ''}`);
       }),
     })
+    .command({
+      command:  'set-roles',
+      describe: 'Set roles (Administrator/Manager/Agent) of an EXISTING user on a site (Velaro staff only) -- makes E2E/QA test logins admin-capable',
+      builder:  (y) => y
+        .option('site-id', { type: 'number', demandOption: true, describe: 'Target site ID' })
+        .option('email',   { type: 'string', demandOption: true, describe: 'Existing user email' })
+        .option('roles',   { type: 'array',  demandOption: true, describe: 'e.g. --roles Administrator' }),
+      handler: runCommand(async (argv) => {
+        const r = await messagingPut(`/SupportTools/sites/${argv['site-id']}/agents/roles`, { email: argv.email, roles: argv.roles.map(String) });
+        console.log(`OK: ${r.email} roles ${r.before || '(none)'} -> ${r.roles.join(', ')}`);
+      }),
+    })
     .command({
       command:  'set-status',
       describe: 'Set an agent\'s availability status (admin only)',

package/lib/commands/recruiting.js

@@ -1,7 +1,7 @@
-import { writeFileSync } from 'fs';
+import { readFileSync, writeFileSync } from 'fs';
 import { messagingGet, messagingPost, messagingPut, messagingDel, getCredentials } from '../api.js';
 import { runCommand } from '../run.js';
-import { applicationIdPath, buildApplySettingsBody, buildBotSettingsBody, buildHostedBody, buildJobPayBody, buildRenewBody, jobLifecyclePath, jobPayPath } from '../recruiting-apply.js';
+import { buildAssignBody, buildNoteBody, buildPipelineBody, buildRetentionBody, buildStageBody, applicationIdPath, buildApplySettingsBody, buildBotSettingsBody, buildHostedBody, buildJobPayBody, buildRenewBody, jobLifecyclePath, jobPayPath } from '../recruiting-apply.js';
 
 // -- velaro recruiting --------------------------------------------------------
 // CLI surface for the Recruiting Bot: job-feed sync (JSON/XML/RSS/Indeed/
@@ -22,6 +22,9 @@ import { applicationIdPath, buildApplySettingsBody, buildBotSettingsBody, buildH
 //   GET    Recruiting/Applications                     -> candidateApplication[]
 //   GET    Recruiting/Applications/AtsFailures; POST Recruiting/Applications/{id}/AtsRetry; PUT Recruiting/ApplySettings { publicApplyEnabled?, autoCreateCaseTypeId?, defaultListingDays? }; GET Recruiting/Applications/{id}/Resume (binary)
 //   GET    Recruiting/Applications/ExportEeoc           -> text/csv (Professional tier+, EnableRecruitingBotEeoc)
+//   GET/PUT Recruiting/Pipeline { stages:[{key,label,color?,applicantVisible?,applicantLabel?}] } ; PUT Recruiting/Applications/{id}/Stage { stage, note? }
+//   GET Recruiting/Applications/{id}/History ; POST .../Notes { note } ; PUT .../Assign { assignedTo }
+//   GET/PUT Recruiting/Retention ; POST Recruiting/Retention/Run?dryRun= -> recruiter pipeline and retention (package job-board-pipeline; 403 job_board_pipeline_not_entitled without it)
 
 const BOLD = '\x1b[1m';
 const DIM  = '\x1b[2m';
@@ -470,10 +473,100 @@ async function sourcesAddListingHandler(argv) {
 }
 
 async function pipelineMoveHandler(argv) {
-  const app = await messagingPut(`/Recruiting/Applications/${argv.applicationId}/Stage`, { stage: argv.stage });
+  const app = await messagingPut(applicationIdPath(argv.applicationId, 'Stage'), buildStageBody(argv.stage, argv.note));
   console.log(`\n${GRN}OK${RST} Application ${app.id} moved to stage "${app.pipelineStage}".\n`);
 }
 
+function printPipeline(r) {
+  console.log(`\n${BOLD}Job Board pipeline${RST}`);
+  console.log(`  Package:  ${r.entitled ? `${GRN}included${RST}` : 'not included (default stages; history, notes, assignment, stage editing and retention are off)'}`);
+  console.log(`  Source:   ${r.source === 'caseType' ? `case type ${r.caseTypeId}` : 'default list'}`);
+  for (const s of r.stages ?? []) {
+    const seen = s.applicantVisible ? `applicants see "${s.applicantLabel || s.label}"` : 'applicants see "In review"';
+    console.log(`  ${s.key.padEnd(16)} ${String(s.label).padEnd(20)} ${DIM}${seen}${s.color ? `, ${s.color}` : ''}${RST}`);
+  }
+  console.log('');
+}
+
+async function pipelineGetHandler() {
+  printPipeline(await messagingGet('/Recruiting/Pipeline'));
+}
+
+async function pipelineSetHandler(argv) {
+  let raw = argv.stagesJson;
+  if (!raw && argv.file) raw = readFileSync(argv.file, 'utf8');
+  if (!raw) throw new Error('Pass --stages-json \'[{"key":"Applied","label":"Applied"}]\' or --file stages.json.');
+  const r = await messagingPut('/Recruiting/Pipeline', buildPipelineBody(raw));
+  console.log(`\n${GRN}OK${RST} Pipeline saved.`);
+  printPipeline(r);
+}
+
+// The API returns UTC without a zone designator; show Pacific Time like every other user-facing timestamp.
+function pacific(raw) {
+  if (!raw) return '';
+  const d = new Date(/(Z|[+-]\d{2}:?\d{2})$/i.test(raw) ? raw : `${raw}Z`);
+  return Number.isNaN(d.getTime()) ? String(raw) : `${d.toLocaleString('en-US', { timeZone: 'America/Los_Angeles', dateStyle: 'medium', timeStyle: 'short' })} PT`;
+}
+
+async function applicationHistoryHandler(argv) {
+  const r = await messagingGet(applicationIdPath(argv.applicationId, 'History'));
+  const events = r.events ?? [];
+  if (!events.length) {
+    console.log('\n  No history yet.\n');
+    return;
+  }
+  console.log(`\n${BOLD}Application ${argv.applicationId} history${RST} (newest first, Pacific Time)\n`);
+  for (const e of events) {
+    // An Assign event carries the new recruiter in note (empty = unassigned); toStage is just the stage at the time.
+    const what = e.kind === 'Note' ? 'note' : e.kind === 'Assign' ? (e.note ? `assigned to ${e.note}` : 'unassigned') : `${e.fromStage ?? '-'} -> ${e.toStage ?? '?'}`;
+    console.log(`  ${pacific(e.at)}  ${String(e.actorType).padEnd(8)} ${e.actorId ?? ''}  ${what}${e.note && e.kind !== 'Assign' ? `  "${e.note}"` : ''}`);
+  }
+  console.log('');
+}
+
+async function applicationNoteHandler(argv) {
+  await messagingPost(applicationIdPath(argv.applicationId, 'Notes'), buildNoteBody(argv.text));
+  console.log(`\n${GRN}OK${RST} Note added to application ${argv.applicationId}.\n`);
+}
+
+async function applicationAssignHandler(argv) {
+  const app = await messagingPut(applicationIdPath(argv.applicationId, 'Assign'), buildAssignBody(argv.who));
+  console.log(`\n${GRN}OK${RST} Application ${app.id} ${app.assignedTo ? `assigned to ${app.assignedTo}` : 'unassigned'}.\n`);
+}
+
+function printRetention(r) {
+  console.log(`\n${BOLD}Applicant record retention${RST}`);
+  console.log(`  Automatic retention: ${r.enabled ? `${GRN}on${RST}` : 'off'}${r.enabled && r.dryRun ? ' (count only, nothing is deleted)' : ''}`);
+  console.log(`  Legal hold:          ${r.legalHold ? `${RED}ON, all deletion stopped${RST}` : 'off'}`);
+  console.log(`  Federal contractor:  ${r.isFederalContractor ? 'yes' : 'no'}`);
+  console.log(`  Retention days:      ${r.retentionDays} (legal minimum ${r.floorDays}, applied ${r.effectiveDays})`);
+  if (r.lastRunAt) console.log(`  Last run:            ${pacific(r.lastRunAt)}, ${r.lastRunDeleted} deleted, ${r.lastRunWouldDelete} would have been deleted`);
+  console.log(`  ${DIM}Records are never deleted before 1 year (2 years for federal contractors). Counts only.${RST}\n`);
+}
+
+async function retentionHandler(argv) {
+  const action = argv.action ?? 'get';
+  if (action === 'get') return printRetention(await messagingGet('/Recruiting/Retention'));
+  if (action === 'set') {
+    // Arming real deletion, or lifting a legal hold, is destructive: refuse unless --yes.
+    if ((argv.dryRun === false || argv.legalHold === false) && !argv.yes) {
+      throw new Error('This can start real deletion of applicant records or lift a legal hold. Preview first with `velaro recruiting retention run`, then repeat with --yes.');
+    }
+    const r = await messagingPut('/Recruiting/Retention', buildRetentionBody({ enabled: argv.enabled, dryRun: argv.dryRun, days: argv.days, federalContractor: argv.federalContractor, legalHold: argv.legalHold }));
+    console.log(`\n${GRN}OK${RST} Retention settings saved.`);
+    return printRetention(r);
+  }
+  // run: previews by default (nothing deleted); --execute --yes performs a real run.
+  if (argv.execute && !argv.yes) throw new Error('--execute permanently deletes applicant records past retention. Preview first (omit --execute), then repeat with --execute --yes.');
+  const r = await messagingPost(`/Recruiting/Retention/Run?dryRun=${argv.execute ? 'false' : 'true'}`, {});
+  console.log(`\n${BOLD}Retention run${RST} ${r.dryRun ? '(preview, nothing deleted)' : ''}`);
+  console.log(`  Due:                ${r.due}`);
+  console.log(`  Deleted:            ${r.deleted}`);
+  console.log(`  Resumes deleted:    ${r.resumesDeleted}`);
+  console.log(`  Held by legal hold: ${r.skippedLegalHold}`);
+  console.log(`  Legal minimum:      ${r.floorDays} days\n`);
+}
+
 const sourcesCommand = {
   command:  'sources <subcommand>',
   describe: 'Manage named job posting sources for a multi-employer job board (EnableJobBoardMultiEmployer)',
@@ -541,16 +634,74 @@ const pipelineCommand = {
   builder:  (y) => y
     .command({
       command:  'move <applicationId> <stage>',
-      describe: 'Move a candidate application to a new pipeline stage (Applied|Screened|Interview|Offer|Hired|Rejected)',
+      describe: 'Move a candidate application to a new pipeline stage (default stages: Applied|Screened|Interview|Offer|Hired|Rejected)',
       builder:  (y2) => y2
         .positional('applicationId', { type: 'number' })
-        .positional('stage', { type: 'string' }),
+        .positional('stage', { type: 'string' })
+        .option('note', { describe: 'Note recorded in the stage history', type: 'string' }),
       handler: runCommand(pipelineMoveHandler),
     })
-    .demandCommand(1, 'Specify a pipeline subcommand: move'),
+    .command({ command: 'get', describe: 'Show the pipeline stages (the default list when the Job board pipeline package is not included)', handler: runCommand(pipelineGetHandler) })
+    .command({
+      command:  'set',
+      describe: 'Replace the pipeline stages (needs the Job board pipeline package)',
+      builder:  (y2) => y2
+        .option('stages-json', { describe: 'JSON array: [{"key","label","color"?,"applicantVisible"?,"applicantLabel"?}]', type: 'string' })
+        .option('file', { describe: 'Read the stages JSON from a file', type: 'string' }),
+      handler: runCommand(pipelineSetHandler),
+    })
+    .demandCommand(1, 'Specify a pipeline subcommand: get | set | move'),
+  handler: () => {},
+};
+
+// `recruiting application ...` (singular): per-application stage, history, notes and assignment.
+const applicationCommand = {
+  command:  'application <subcommand>',
+  describe: 'One application: move stage, show history, add a note, assign a recruiter',
+  builder:  (y) => y
+    .command({
+      command:  'stage <applicationId> <stage>',
+      describe: 'Move an application to a stage, with an optional note',
+      builder:  (y2) => y2.positional('applicationId', { type: 'number' }).positional('stage', { type: 'string' }).option('note', { describe: 'Note recorded in the stage history', type: 'string' }),
+      handler:  runCommand(pipelineMoveHandler),
+    })
+    .command({
+      command:  'history <applicationId>',
+      describe: 'Show the stage, note and assignment history, newest first (needs the Job board pipeline package)',
+      builder:  (y2) => y2.positional('applicationId', { type: 'number' }),
+      handler:  runCommand(applicationHistoryHandler),
+    })
+    .command({
+      command:  'note <applicationId> <text>',
+      describe: 'Add an internal note (never shown to the applicant; needs the Job board pipeline package)',
+      builder:  (y2) => y2.positional('applicationId', { type: 'number' }).positional('text', { type: 'string' }),
+      handler:  runCommand(applicationNoteHandler),
+    })
+    .command({
+      command:  'assign <applicationId> <who>',
+      describe: 'Assign a recruiter (name or email; "none" clears; needs the Job board pipeline package)',
+      builder:  (y2) => y2.positional('applicationId', { type: 'number' }).positional('who', { type: 'string' }),
+      handler:  runCommand(applicationAssignHandler),
+    })
+    .demandCommand(1, 'Specify an application subcommand: stage | history | note | assign'),
   handler: () => {},
 };
 
+const retentionCommand = {
+  command:  'retention [action]',
+  describe: 'Applicant record retention: show (default), set, or run a preview (needs the Job board pipeline package; set and run need an Administrator)',
+  builder:  (y) => y
+    .positional('action', { describe: 'get | set | run', type: 'string', choices: ['get', 'set', 'run'], default: 'get' })
+    .option('enabled', { describe: 'set: turn automatic retention on or off', type: 'boolean' })
+    .option('dry-run', { describe: 'set: count only, never delete', type: 'boolean' })
+    .option('days', { describe: 'set: days to keep records (below the legal minimum the minimum applies)', type: 'number' })
+    .option('federal-contractor', { describe: 'set: federal contractor (2 year minimum)', type: 'boolean' })
+    .option('legal-hold', { describe: 'set: stop all deletion', type: 'boolean' })
+    .option('execute', { describe: 'run: really delete due records (default is a preview that deletes nothing)', type: 'boolean' })
+    .option('yes', { describe: 'Confirm a deleting run, or set --dry-run=false / --legal-hold=false', type: 'boolean' }),
+  handler:  runCommand(retentionHandler),
+};
+
 export const recruitingCommand = {
   command:  'recruiting <subcommand>',
   describe: 'Recruiting Bot: sync job feeds, manage listings, applications, config, and multi-employer job board sources',
@@ -562,7 +713,9 @@ export const recruitingCommand = {
     .command(applicationsCommand)
     .command(sourcesCommand)
     .command(pipelineCommand)
-    .demandCommand(1, 'Specify a recruiting subcommand: sync | config | jobs | hosted | applications | sources | pipeline')
+    .command(applicationCommand)
+    .command(retentionCommand)
+    .demandCommand(1, 'Specify a recruiting subcommand: sync | config | jobs | hosted | applications | application | sources | pipeline | retention')
     .strict(),
   handler: () => {},
 };

package/lib/recruiting-apply.js

@@ -111,3 +111,69 @@ export function buildBotSettingsBody(o = {}) {
   if (!Object.keys(body).length) throw new Error('Specify at least one bot setting.');
   return body;
 }
+
+// ── Job Board Stage 4: recruiter pipeline, history, notes, assignment, retention (package job-board-pipeline) ──
+
+// Body for PUT Recruiting/Applications/{id}/Stage. note is optional (recorded in the stage history).
+export function buildStageBody(stage, note) {
+  const s = String(stage ?? '').trim();
+  if (!s) throw new Error('stage is required.');
+  const body = { stage: s };
+  if (note !== undefined && String(note).trim()) {
+    if (String(note).length > 2000) throw new Error('note must be 2000 characters or fewer.');
+    body.note = String(note).trim();
+  }
+  return body;
+}
+
+// Body for POST Recruiting/Applications/{id}/Notes.
+export function buildNoteBody(note) {
+  const t = String(note ?? '').trim();
+  if (!t) throw new Error('note is required.');
+  if (t.length > 2000) throw new Error('note must be 2000 characters or fewer.');
+  return { note: t };
+}
+
+// Body for PUT Recruiting/Applications/{id}/Assign. "none" or "" clears the assignment.
+export function buildAssignBody(who) {
+  const t = String(who ?? '').trim();
+  if (t.length > 200) throw new Error('assignedTo must be 200 characters or fewer.');
+  return { assignedTo: !t || t.toLowerCase() === 'none' ? null : t };
+}
+
+// Body for PUT Recruiting/Pipeline from a JSON array of stages: [{ key, label, color?, applicantVisible?, applicantLabel? }].
+// The server also validates (1-12 stages, unique keys; removing a stage that holds applications is refused with a 400).
+export function buildPipelineBody(stagesJson) {
+  let stages;
+  try {
+    stages = typeof stagesJson === 'string' ? JSON.parse(stagesJson) : stagesJson;
+  } catch (e) {
+    throw new Error(`stages must be valid JSON: ${e.message}`);
+  }
+  if (!Array.isArray(stages) || stages.length < 1 || stages.length > 12) throw new Error('stages must be a JSON array of 1 to 12 stages.');
+  const keys = new Set();
+  for (const s of stages) {
+    if (!s || typeof s !== 'object' || typeof s.key !== 'string' || !s.key.trim() || s.key.length > 64) throw new Error('every stage needs a key (up to 64 characters).');
+    if (typeof s.label !== 'string' || !s.label.trim()) throw new Error(`stage ${s.key} needs a label.`);
+    if (keys.has(s.key)) throw new Error(`duplicate stage key: ${s.key}.`);
+    keys.add(s.key);
+  }
+  return { stages };
+}
+
+// Partial body for PUT Recruiting/Retention (apply-if-present). A day count below the legal floor is accepted by the server,
+// which then applies the floor (365 days, or 730 for federal contractors; 29 CFR 1602.14).
+export function buildRetentionBody({ enabled, dryRun, days, federalContractor, legalHold } = {}) {
+  const body = {};
+  if (enabled !== undefined) body.enabled = Boolean(enabled);
+  if (dryRun !== undefined) body.dryRun = Boolean(dryRun);
+  if (federalContractor !== undefined) body.isFederalContractor = Boolean(federalContractor);
+  if (legalHold !== undefined) body.legalHold = Boolean(legalHold);
+  if (days !== undefined) {
+    const n = Number(days);
+    if (!Number.isInteger(n) || n < 1 || n > 36500) throw new Error('days must be a whole number from 1 to 36500.');
+    body.retentionDays = n;
+  }
+  if (!Object.keys(body).length) throw new Error('Specify at least one retention setting.');
+  return body;
+}

package/lib/recruiting-apply.test.js

@@ -1,6 +1,6 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { applicationIdPath, buildApplySettingsBody, buildBotSettingsBody, buildHostedBody, buildJobPayBody, buildRenewBody, jobLifecyclePath, jobPayPath } from './recruiting-apply.js';
+import { buildAssignBody, buildNoteBody, buildPipelineBody, buildRetentionBody, buildStageBody, applicationIdPath, buildApplySettingsBody, buildBotSettingsBody, buildHostedBody, buildJobPayBody, buildRenewBody, jobLifecyclePath, jobPayPath } from './recruiting-apply.js';
 
 test('job lifecycle paths validate id and action', () => {
   assert.equal(jobLifecyclePath(7, 'close'), '/Recruiting/Jobs/7/close');
@@ -76,3 +76,40 @@ test('hosted body is apply-if-present; no flags means read-only', () => {
   assert.deepEqual(buildHostedBody({ enabled: false }), { enabled: false });
   assert.deepEqual(buildHostedBody({ regenerateLink: true }), { regenerateSlug: true });
 });
+
+// -- Job Board pipeline (Stage 4) ---------------------------------------------
+
+test('stage body carries an optional trimmed note', () => {
+  assert.deepEqual(buildStageBody('Interview'), { stage: 'Interview' });
+  assert.deepEqual(buildStageBody(' Offer ', ' good fit '), { stage: 'Offer', note: 'good fit' });
+  assert.deepEqual(buildStageBody('Offer', '  '), { stage: 'Offer' });
+  assert.throws(() => buildStageBody(''));
+  assert.throws(() => buildStageBody('Offer', 'x'.repeat(2001)));
+});
+
+test('note and assign bodies validate', () => {
+  assert.deepEqual(buildNoteBody(' hello '), { note: 'hello' });
+  assert.throws(() => buildNoteBody(' '));
+  assert.deepEqual(buildAssignBody('pat@acme.com'), { assignedTo: 'pat@acme.com' });
+  assert.deepEqual(buildAssignBody('none'), { assignedTo: null });
+  assert.deepEqual(buildAssignBody(''), { assignedTo: null });
+  assert.throws(() => buildAssignBody('x'.repeat(201)));
+});
+
+test('pipeline body validates the stage list client side', () => {
+  const ok = [{ key: 'Applied', label: 'Applied' }, { key: 'Hired', label: 'Hired', applicantVisible: true }];
+  assert.deepEqual(buildPipelineBody(JSON.stringify(ok)), { stages: ok });
+  assert.throws(() => buildPipelineBody('{'), /valid JSON/);
+  assert.throws(() => buildPipelineBody('[]'));
+  assert.throws(() => buildPipelineBody(JSON.stringify([{ key: 'A', label: 'A' }, { key: 'A', label: 'B' }])), /duplicate/);
+  assert.throws(() => buildPipelineBody(JSON.stringify([{ key: 'A' }])), /label/);
+  assert.throws(() => buildPipelineBody(JSON.stringify(Array.from({ length: 13 }, (_, i) => ({ key: `K${i}`, label: 'x' })))));
+});
+
+test('retention body is apply-if-present and range-checked', () => {
+  assert.deepEqual(buildRetentionBody({ legalHold: true }), { legalHold: true });
+  assert.deepEqual(buildRetentionBody({ enabled: false, dryRun: true, days: '400', federalContractor: true }), { enabled: false, dryRun: true, retentionDays: 400, isFederalContractor: true });
+  assert.throws(() => buildRetentionBody({}));
+  assert.throws(() => buildRetentionBody({ days: 0 }));
+  assert.throws(() => buildRetentionBody({ days: 1.5 }));
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velaro/cli",
-  "version": "1.4.92",
+  "version": "1.4.93",
   "description": "Velaro Workspace v20 — command-line interface for managing bots, knowledge base ingestion, MCP API keys, search indexes, and ops health.",
   "type": "module",
   "bin": {