@springbrand/hr-cli 0.1.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.
- package/.agents/skills/saas-hr-cli/SKILL.md +18 -56
- package/README.md +2 -0
- package/dist/hr.js +52 -19
- package/package.json +1 -1
|
@@ -1,73 +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:
|
|
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`
|
|
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
|
-
|
|
10
|
+
The rules below are what the help cannot tell you.
|
|
11
11
|
|
|
12
|
-
|
|
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
|
|
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
|
-
##
|
|
17
|
+
## People and jobs
|
|
21
18
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
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
|
-
|
|
23
|
+
## Changing a candidate's process
|
|
36
24
|
|
|
37
|
-
|
|
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
|
-
|
|
40
|
-
| --- | --- | --- |
|
|
41
|
-
| `{ "ok": true, "data": … }` | 0 | Done. Check `data.pendingApproval` first (below). |
|
|
42
|
-
| `{ "ok": false, "error": { "code", "message", "candidates"? } }` | 1 | Tell the user the message. |
|
|
43
|
-
| `error.code` is `USAGE` | 2 | Fix the command; see `hr --help`. |
|
|
29
|
+
## Approvals
|
|
44
30
|
|
|
45
|
-
|
|
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`.
|
|
46
32
|
|
|
47
|
-
|
|
48
|
-
- `NOT_FOUND`: nothing matches, or the caller cannot see it.
|
|
49
|
-
- `NOT_SIGNED_IN`: ask the user to run `hr login` or set `HR_AGENT_KEY`.
|
|
50
|
-
- `APP_FORBIDDEN`: the caller lacks the permission and this action cannot be approved. It is granted in IAM.
|
|
51
|
-
- `APP_CONFLICT`: the state changed, for example the candidate was already screened. List again.
|
|
33
|
+
## Privacy
|
|
52
34
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
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:
|
|
56
|
-
|
|
57
|
-
```json
|
|
58
|
-
{ "ok": true, "data": { "pendingApproval": { "approvalId": "…", "actionId": "…" } } }
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
**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:
|
|
62
|
-
|
|
63
|
-
```bash
|
|
64
|
-
hr approvals status <approvalId> --wait --timeout 300
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
`data.status` is `pending`, `executed` (approved and done), `rejected` (denied or expired) or `failed` (see `data.error`).
|
|
68
|
-
|
|
69
|
-
## Rules
|
|
70
|
-
|
|
71
|
-
- Passing or rejecting changes a real candidate's process. Do it only when the user clearly asked, about a specific person.
|
|
72
|
-
- Candidate data is personal. Only share what the user needs, and never send it elsewhere.
|
|
73
|
-
- 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/README.md
CHANGED
|
@@ -19,4 +19,6 @@ hr screening list
|
|
|
19
19
|
| `HR_CONFIG_DIR` | No | Where `hr login` stores its token. Default `~/.config/saas-hr`. |
|
|
20
20
|
| `XDG_CONFIG_HOME` | No | Moves the default to `$XDG_CONFIG_HOME/saas-hr`. |
|
|
21
21
|
|
|
22
|
+
Talents and applications in the output carry `url`, their page in the HR console, on the address HR reports.
|
|
23
|
+
|
|
22
24
|
`hr --help` lists the commands. Agents: see `.agents/skills/saas-hr-cli/SKILL.md`.
|
package/dist/hr.js
CHANGED
|
@@ -76,6 +76,10 @@ var Hr = class {
|
|
|
76
76
|
this.bearer = stored.token;
|
|
77
77
|
return this.bearer;
|
|
78
78
|
}
|
|
79
|
+
/** The console's address, as HR reports it, so page links never guess a domain. */
|
|
80
|
+
async appOrigin() {
|
|
81
|
+
return (await this.config()).appOrigin.replace(/\/+$/, "");
|
|
82
|
+
}
|
|
79
83
|
get(pathname, query = {}) {
|
|
80
84
|
const url = new URL(`${this.apiUrl}/api/v1${pathname}`);
|
|
81
85
|
for (const [name, value] of Object.entries(query)) if (value !== void 0 && value !== "") url.searchParams.set(name, String(value));
|
|
@@ -162,26 +166,43 @@ function pickOne(items, query, names, describe, what) {
|
|
|
162
166
|
}
|
|
163
167
|
|
|
164
168
|
// src/run.ts
|
|
165
|
-
var
|
|
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.
|
|
166
188
|
|
|
167
189
|
Setup
|
|
168
190
|
HR_API_URL this deployment's HR address (or --api-url)
|
|
169
191
|
HR_AGENT_KEY an Agent key from IAM; without it, run \`hr login\`
|
|
170
192
|
IAM_URL optional; by default HR says where IAM is
|
|
171
193
|
|
|
172
|
-
Commands
|
|
173
|
-
|
|
174
|
-
hr jobs list [--status open]
|
|
175
|
-
hr talents search [text] [--job <job>] [--page n] [--page-size n]
|
|
176
|
-
hr talents show <name|id>
|
|
177
|
-
hr screening list [--job <job>]
|
|
178
|
-
hr screening pass <name|id> [--job <job>]
|
|
179
|
-
hr screening reject <name|id> --reason <reason> [--job <job>]
|
|
180
|
-
hr interviews to-schedule [--job <job>]
|
|
181
|
-
hr reasons list
|
|
182
|
-
hr approvals status <id> [--wait] [--timeout seconds]
|
|
194
|
+
Commands (\`hr <command> --help\` shows what one returns)
|
|
195
|
+
${Commands.map((command) => ` ${command.usage}`).join("\n")}
|
|
183
196
|
|
|
184
|
-
|
|
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
|
+
}
|
|
185
206
|
var options = {
|
|
186
207
|
"api-url": { type: "string" },
|
|
187
208
|
job: { type: "string" },
|
|
@@ -194,6 +215,18 @@ var options = {
|
|
|
194
215
|
timeout: { type: "string" },
|
|
195
216
|
help: { type: "boolean", short: "h" }
|
|
196
217
|
};
|
|
218
|
+
async function linked(hr, records, page2) {
|
|
219
|
+
const origin = await hr.appOrigin();
|
|
220
|
+
return records.map((record) => ({ ...record, url: `${origin}/${page2}/${record.id}` }));
|
|
221
|
+
}
|
|
222
|
+
async function linkedPage(hr, result, page2) {
|
|
223
|
+
return { ...result, items: await linked(hr, result.items, page2) };
|
|
224
|
+
}
|
|
225
|
+
async function linkedTalent(hr, id) {
|
|
226
|
+
const talent = await hr.get(`/talents/${id}`);
|
|
227
|
+
const [withUrl] = await linked(hr, [talent], "talents");
|
|
228
|
+
return { ...withUrl, ...talent.applications ? { applications: await linked(hr, talent.applications, "applications") } : {} };
|
|
229
|
+
}
|
|
197
230
|
async function jobId(hr, job) {
|
|
198
231
|
if (!job || isId(job)) return job;
|
|
199
232
|
const jobs = await hr.get("/jobs");
|
|
@@ -238,15 +271,15 @@ async function dispatch(args, deps) {
|
|
|
238
271
|
case "jobs list":
|
|
239
272
|
return hr.get("/jobs", { status: values.status });
|
|
240
273
|
case "talents search":
|
|
241
|
-
return hr.get("/talents", { q: rest.join(" ") || void 0, jobId: await jobId(hr, values.job), ...page2 });
|
|
274
|
+
return linkedPage(hr, await hr.get("/talents", { q: rest.join(" ") || void 0, jobId: await jobId(hr, values.job), ...page2 }), "talents");
|
|
242
275
|
case "talents show": {
|
|
243
276
|
const who = needed("a name or id", rest.join(" "));
|
|
244
|
-
if (isId(who)) return hr
|
|
277
|
+
if (isId(who)) return linkedTalent(hr, who);
|
|
245
278
|
const found = await hr.get("/talents", { q: who, pageSize: 50 });
|
|
246
|
-
return hr
|
|
279
|
+
return linkedTalent(hr, pickOne(found.items, who, (item) => [item.displayName], (item) => ({ id: item.id, name: item.displayName, headline: item.headline }), "talent").id);
|
|
247
280
|
}
|
|
248
281
|
case "screening list":
|
|
249
|
-
return screeningQueue(hr, values.job);
|
|
282
|
+
return linkedPage(hr, await screeningQueue(hr, values.job), "applications");
|
|
250
283
|
case "screening pass":
|
|
251
284
|
return hr.post(`/applications/${await screeningApplication(hr, needed("a candidate", rest.join(" ")), values.job)}/screening`, { decision: "pass" });
|
|
252
285
|
case "screening reject": {
|
|
@@ -254,7 +287,7 @@ async function dispatch(args, deps) {
|
|
|
254
287
|
return hr.post(`/applications/${id}/screening`, { decision: "reject", reasonId: await rejectReason(hr, values.reason) });
|
|
255
288
|
}
|
|
256
289
|
case "interviews to-schedule":
|
|
257
|
-
return hr.get("/applications", { queue: "to_schedule", jobId: await jobId(hr, values.job), ...page2 });
|
|
290
|
+
return linkedPage(hr, await hr.get("/applications", { queue: "to_schedule", jobId: await jobId(hr, values.job), ...page2 }), "applications");
|
|
258
291
|
case "reasons list":
|
|
259
292
|
return hr.get("/reject-reasons");
|
|
260
293
|
case "approvals status":
|
|
@@ -265,7 +298,7 @@ async function dispatch(args, deps) {
|
|
|
265
298
|
}
|
|
266
299
|
async function run(args, deps) {
|
|
267
300
|
if (!args.length || args.includes("--help") || args.includes("-h")) {
|
|
268
|
-
deps.stdout(
|
|
301
|
+
deps.stdout(helpFor(args));
|
|
269
302
|
return 0;
|
|
270
303
|
}
|
|
271
304
|
try {
|