@springbrand/hr-cli 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,82 +1,35 @@
1
1
  ---
2
2
  name: saas-hr-cli
3
- description: Use the `hr` command to work with SpringBrand HR (recruiting) on the user's behalf: list jobs, search talents, see who is waiting for screening or an interview, pass or reject candidates, and track approvals. Use when the user asks about candidates, resumes, open roles, screening or interview scheduling.
3
+ description: Use the `hr` command to work with SpringBrand HR (recruiting) on the user's behalf: jobs, the talent pool, screening, interview scheduling and approvals. Use when the user asks about candidates, resumes, open roles, screening or interviews.
4
4
  ---
5
5
 
6
6
  # hr CLI
7
7
 
8
- `hr` calls the HR system. Every command prints JSON on stdout.
8
+ `hr --help` lists the commands. `hr <command> --help` says what one command takes and returns, including totals, so read it instead of probing the output. Every command prints JSON: `{ ok: true, data }` or `{ ok: false, error }`.
9
9
 
10
- ## Setup
10
+ The rules below are what the help cannot tell you.
11
11
 
12
- | Variable | Meaning |
13
- | --- | --- |
14
- | `HR_API_URL` | HR's address. Required. Never assume a domain; if it is missing, ask the user. |
15
- | `HR_AGENT_KEY` | An Agent key from IAM. Without it, the user runs `hr login` once. |
16
- | `IAM_URL` | Optional. HR tells the CLI where IAM is. |
12
+ ## Answering
17
13
 
18
- Never print, log or repeat `HR_AGENT_KEY` or a token.
14
+ - Speak in the user's terms. Never put command names, flags or JSON field names in the reply.
15
+ - Report only what the output says. Do not infer a result the command did not return.
19
16
 
20
- ## Commands
17
+ ## People and jobs
21
18
 
22
- ```bash
23
- hr whoami
24
- hr jobs list [--status open]
25
- hr talents search [text] [--job <job>] [--page n] [--page-size n]
26
- hr talents show <name|id>
27
- hr screening list [--job <job>]
28
- hr screening pass <name|id> [--job <job>]
29
- hr screening reject <name|id> --reason <reason> [--job <job>]
30
- hr interviews to-schedule [--job <job>]
31
- hr reasons list
32
- hr approvals status <approvalId> [--wait] [--timeout seconds]
33
- ```
19
+ - `AMBIGUOUS` means several people or jobs match. Show `error.candidates` and ask which one. Never pick for the user.
20
+ - `NOT_FOUND` means nothing matches, or the caller cannot see it.
21
+ - For a link to a candidate, give the `url` from the output. Never build a link yourself.
34
22
 
35
- `<job>` is a title, slug or id. `<reason>` is a name from `hr reasons list`, or an id.
23
+ ## Changing a candidate's process
36
24
 
37
- ## Links
25
+ - Pass or reject only when the user clearly asked, about a specific person.
26
+ - `APP_CONFLICT` means the state changed, for example the candidate was already screened. List again.
27
+ - `APP_FORBIDDEN` means the caller lacks the permission and it cannot be approved. It is granted in IAM.
38
28
 
39
- When the user asks for a link to a candidate, give the `url` from the output. Never build a link yourself.
29
+ ## Approvals
40
30
 
41
- - `talents search` and `talents show`: each talent's `url` opens their talent page; in `talents show`, each entry in `applications` has the `url` of that application.
42
- - `screening list` and `interviews to-schedule`: each item's `url` opens that application (one candidate in one job).
31
+ Without the permission, a change waits for a person in IAM, and the command answers with `data.pendingApproval: { approvalId }`. **The action has not happened yet.** Do not say the candidate was rejected. Tell the user it is waiting for approval, then check when asked, or wait with `hr approvals status <approvalId> --wait`.
43
32
 
44
- If the person you need is not in a result, run the command that lists them first, for example `hr talents show <name>`.
33
+ ## Privacy
45
34
 
46
- ## Reading the result
47
-
48
- | Output | Exit | What to do |
49
- | --- | --- | --- |
50
- | `{ "ok": true, "data": … }` | 0 | Done. Check `data.pendingApproval` first (below). |
51
- | `{ "ok": false, "error": { "code", "message", "candidates"? } }` | 1 | Tell the user the message. |
52
- | `error.code` is `USAGE` | 2 | Fix the command; see `hr --help`. |
53
-
54
- Codes you will meet:
55
-
56
- - `AMBIGUOUS`: several people or jobs match. Show `error.candidates` and ask which one. Never pick for the user.
57
- - `NOT_FOUND`: nothing matches, or the caller cannot see it.
58
- - `NOT_SIGNED_IN`: ask the user to run `hr login` or set `HR_AGENT_KEY`.
59
- - `APP_FORBIDDEN`: the caller lacks the permission and this action cannot be approved. It is granted in IAM.
60
- - `APP_CONFLICT`: the state changed, for example the candidate was already screened. List again.
61
-
62
- ## When an action needs approval
63
-
64
- Permissions decide everything, for a person and an Agent alike. With the permission an action runs at once. Without it, a person decides in IAM, and the command answers:
65
-
66
- ```json
67
- { "ok": true, "data": { "pendingApproval": { "approvalId": "…", "actionId": "…" } } }
68
- ```
69
-
70
- **The action has not happened yet.** Do not say the candidate was rejected. Tell the user it is waiting for approval in IAM, then check when asked, or wait:
71
-
72
- ```bash
73
- hr approvals status <approvalId> --wait --timeout 300
74
- ```
75
-
76
- `data.status` is `pending`, `executed` (approved and done), `rejected` (denied or expired) or `failed` (see `data.error`).
77
-
78
- ## Rules
79
-
80
- - Passing or rejecting changes a real candidate's process. Do it only when the user clearly asked, about a specific person.
81
- - Candidate data is personal. Only share what the user needs, and never send it elsewhere.
82
- - Report what the output says. Do not infer a result the command did not return.
35
+ Candidate data is personal. Share only what the user needs, never send it elsewhere, and never print, log or repeat `HR_AGENT_KEY` or a token.
package/dist/hr.js CHANGED
@@ -166,27 +166,43 @@ function pickOne(items, query, names, describe, what) {
166
166
  }
167
167
 
168
168
  // src/run.ts
169
- var Help = `hr: SpringBrand HR from the command line. Output is JSON on stdout.
169
+ var Commands = [
170
+ { usage: "hr login [--no-browser] | logout", does: "Sign a person in or out. Agents use HR_AGENT_KEY instead.", returns: "login: data: { name, expiresAt }. logout: data: { signedOut }." },
171
+ { usage: "hr whoami", does: "Who the caller is.", returns: "data: { principalId, name, kind, permissions[] }. permissions are HR action codes such as recruit:talent:view." },
172
+ { usage: "hr jobs list [--status open|paused|draft|closed]", does: "Jobs, open ones first.", returns: "data: [{ id, title, slug, status, counts: { active, hired, rejected, withdrawn } }]. counts are applications per job." },
173
+ {
174
+ usage: "hr talents search [text] [--job <job>] [--page n] [--page-size n]",
175
+ does: "Talents in the pool, optionally matching text (name, headline, contact) or applying to a job. Page size defaults to 50, at most 200.",
176
+ returns: "data: { total, items: [{ id, displayName, headline, status, tags, skills, applicationCount, jobTitles, bestScore, url }] }. total counts every match, not just this page.",
177
+ example: "hr talents search --page-size 1 # data.total is the size of the pool"
178
+ },
179
+ { usage: "hr talents show <name|id>", does: "One talent with contacts (when the caller may see them), documents, skills and applications.", returns: "data: { id, displayName, \u2026, url, applications: [{ id, jobTitle, stageName, status, url }] }" },
180
+ { usage: "hr screening list [--job <job>]", does: "Applications waiting for screening.", returns: "data: { total, items: [{ id, talentName, jobTitle, stageName, url }] }. total is how many are waiting." },
181
+ { usage: "hr screening pass <name|id> [--job <job>]", does: "Pass a candidate waiting for screening to the next stage.", returns: "data: the updated application, or data.pendingApproval (see below)." },
182
+ { usage: "hr screening reject <name|id> --reason <reason> [--job <job>]", does: "Reject a candidate waiting for screening. <reason> comes from `hr reasons list`.", returns: "data: the updated application, or data.pendingApproval (see below)." },
183
+ { usage: "hr interviews to-schedule [--job <job>] [--page n] [--page-size n]", does: "Candidates in an interview stage with no interview booked.", returns: "data: { total, items: [{ id, talentName, jobTitle, stageName, url }] }" },
184
+ { usage: "hr reasons list", does: "Reject reasons.", returns: "data: [{ id, name, category }]. Rejecting uses those with category we_rejected." },
185
+ { usage: "hr approvals status <id> [--wait] [--timeout seconds]", does: "Where an approval stands; --wait polls until it is decided or the timeout (default 300) passes.", returns: "data: { status: pending | executed | rejected | failed, error? }" }
186
+ ];
187
+ var Overall = `hr: SpringBrand HR from the command line. Output is JSON on stdout.
170
188
 
171
189
  Setup
172
190
  HR_API_URL this deployment's HR address (or --api-url)
173
191
  HR_AGENT_KEY an Agent key from IAM; without it, run \`hr login\`
174
192
  IAM_URL optional; by default HR says where IAM is
175
193
 
176
- Commands
177
- hr login [--no-browser] | logout | whoami
178
- hr jobs list [--status open]
179
- hr talents search [text] [--job <job>] [--page n] [--page-size n]
180
- hr talents show <name|id>
181
- hr screening list [--job <job>]
182
- hr screening pass <name|id> [--job <job>]
183
- hr screening reject <name|id> --reason <reason> [--job <job>]
184
- hr interviews to-schedule [--job <job>]
185
- hr reasons list
186
- hr approvals status <id> [--wait] [--timeout seconds]
194
+ Commands (\`hr <command> --help\` shows what one returns)
195
+ ${Commands.map((command) => ` ${command.usage}`).join("\n")}
187
196
 
188
- Talents and applications carry url, their page in the HR console.
189
- A command without the permission answers with data.pendingApproval: a person decides in IAM.`;
197
+ Every command prints { ok: true, data } or { ok: false, error: { code, message } }.
198
+ <job> is a title, slug or id. Talents and applications carry url, their page in the HR console.
199
+ A command without the permission answers with data.pendingApproval: the action waits for a person to decide in IAM.`;
200
+ function helpFor(args) {
201
+ const words = args.filter((arg) => !arg.startsWith("-")).slice(0, 2).join(" ");
202
+ const command = words && Commands.find((entry) => entry.usage.startsWith(`hr ${words}`));
203
+ if (!command) return Overall;
204
+ return [`${command.usage}`, "", command.does, "", `Returns ${command.returns}`, ...command.example ? ["", `Example: ${command.example}`] : []].join("\n");
205
+ }
190
206
  var options = {
191
207
  "api-url": { type: "string" },
192
208
  job: { type: "string" },
@@ -282,7 +298,7 @@ async function dispatch(args, deps) {
282
298
  }
283
299
  async function run(args, deps) {
284
300
  if (!args.length || args.includes("--help") || args.includes("-h")) {
285
- deps.stdout(Help);
301
+ deps.stdout(helpFor(args));
286
302
  return 0;
287
303
  }
288
304
  try {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@springbrand/hr-cli",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "SpringBrand HR from the command line, for people and Agents.",
5
5
  "license": "UNLICENSED",
6
6
  "type": "module",
@@ -24,15 +24,16 @@
24
24
  "url": "git+ssh://git@github.com/springbrand-lab/saas-hr.git",
25
25
  "directory": "packages/cli"
26
26
  },
27
+ "scripts": {
28
+ "build": "esbuild src/bin.ts --bundle --platform=node --format=esm --target=node24 --outfile=dist/hr.js --banner:js=\"#!/usr/bin/env node\"",
29
+ "check": "tsc --noEmit",
30
+ "test": "vitest run",
31
+ "prepublishOnly": "pnpm run build && pnpm run test"
32
+ },
27
33
  "devDependencies": {
28
34
  "@types/node": "^24.13.3",
29
35
  "esbuild": "^0.27.4",
30
36
  "typescript": "^7.0.2",
31
37
  "vitest": "^4.1.10"
32
- },
33
- "scripts": {
34
- "build": "esbuild src/bin.ts --bundle --platform=node --format=esm --target=node24 --outfile=dist/hr.js --banner:js=\"#!/usr/bin/env node\"",
35
- "check": "tsc --noEmit",
36
- "test": "vitest run"
37
38
  }
38
- }
39
+ }