@springbrand/hr-cli 0.2.0 → 0.4.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 +24 -63
- package/dist/hr.js +113 -15
- package/package.json +1 -1
|
@@ -1,82 +1,43 @@
|
|
|
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, booking interviews (then putting them on a calendar with another tool) 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
|
-
|
|
29
|
+
## Interviews and calendars
|
|
40
30
|
|
|
41
|
-
-
|
|
42
|
-
-
|
|
31
|
+
- HR only records an interview's time, place and interviewers. It puts nothing on any calendar and invites nobody, the candidate included.
|
|
32
|
+
- When the user wants it on a calendar, first record it with `hr interviews schedule`, then create the event with the calendar tool you have for the user (for example Feishu). Put the candidate, job and `url` in the event. Keep the interview `id` with it.
|
|
33
|
+
- When an interview moves or is cancelled, change HR first (`reschedule`, `cancel`), then the calendar event.
|
|
34
|
+
- Pass times with the user's UTC offset. If you do not know their time zone, ask. Never let a bare "3 pm" be read in some other zone.
|
|
35
|
+
- Interviewers are people. An Agent must name them; when the user says "me", find the user with `hr people search`.
|
|
43
36
|
|
|
44
|
-
|
|
37
|
+
## Approvals
|
|
45
38
|
|
|
46
|
-
|
|
39
|
+
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`.
|
|
47
40
|
|
|
48
|
-
|
|
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`. |
|
|
41
|
+
## Privacy
|
|
53
42
|
|
|
54
|
-
|
|
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.
|
|
43
|
+
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
|
@@ -88,6 +88,9 @@ var Hr = class {
|
|
|
88
88
|
post(pathname, body) {
|
|
89
89
|
return this.request(`${this.apiUrl}/api/v1${pathname}`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) });
|
|
90
90
|
}
|
|
91
|
+
patch(pathname, body) {
|
|
92
|
+
return this.request(`${this.apiUrl}/api/v1${pathname}`, { method: "PATCH", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) });
|
|
93
|
+
}
|
|
91
94
|
async request(url, init) {
|
|
92
95
|
const token = await this.token();
|
|
93
96
|
return unwrap(await this.send(url, { ...init, headers: { ...init.headers, Authorization: `Bearer ${token}` } }, "HR"), "HR");
|
|
@@ -166,27 +169,53 @@ function pickOne(items, query, names, describe, what) {
|
|
|
166
169
|
}
|
|
167
170
|
|
|
168
171
|
// src/run.ts
|
|
169
|
-
var
|
|
172
|
+
var Commands = [
|
|
173
|
+
{ 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 }." },
|
|
174
|
+
{ usage: "hr whoami", does: "Who the caller is.", returns: "data: { principalId, name, kind, permissions[] }. permissions are HR action codes such as recruit:talent:view." },
|
|
175
|
+
{ 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." },
|
|
176
|
+
{
|
|
177
|
+
usage: "hr talents search [text] [--job <job>] [--page n] [--page-size n]",
|
|
178
|
+
does: "Talents in the pool, optionally matching text (name, headline, contact) or applying to a job. Page size defaults to 50, at most 200.",
|
|
179
|
+
returns: "data: { total, items: [{ id, displayName, headline, status, tags, skills, applicationCount, jobTitles, bestScore, url }] }. total counts every match, not just this page.",
|
|
180
|
+
example: "hr talents search --page-size 1 # data.total is the size of the pool"
|
|
181
|
+
},
|
|
182
|
+
{ 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 }] }" },
|
|
183
|
+
{ 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." },
|
|
184
|
+
{ 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)." },
|
|
185
|
+
{ 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)." },
|
|
186
|
+
{ 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 }] }" },
|
|
187
|
+
{
|
|
188
|
+
usage: "hr interviews schedule <name|id> --start <time> [--end <time> | --minutes n] [--location text] [--with <people>] [--job <job>]",
|
|
189
|
+
does: "Book an interview for a candidate waiting in `hr interviews to-schedule` (or an application id). <time> is ISO 8601 with its UTC offset, such as 2026-11-12T15:00+08:00. Length defaults to 60 minutes. <people> are interviewers, comma-separated names, emails or ids from `hr people search`; a person calling may leave it out to interview alone, an Agent must pass it. HR only records the interview: it puts nothing on any calendar.",
|
|
190
|
+
returns: "data: { id, applicationId, round, status, startsAt, endsAt, locationOrLink, participants: [{ principalId, submitted }], talentName, jobTitle, url }. Times are UTC.",
|
|
191
|
+
example: 'hr interviews schedule "Li Wei" --start 2026-11-12T15:00+08:00 --with "Rita Tan" --location "Room 3"'
|
|
192
|
+
},
|
|
193
|
+
{ usage: "hr interviews list <application id>", does: "Every interview of one application, latest first.", returns: "data: [{ id, applicationId, round, status, startsAt, endsAt, locationOrLink, participants: [{ principalId, submitted }], url }]. Times are UTC." },
|
|
194
|
+
{ usage: "hr interviews reschedule <interview id> [--start <time>] [--end <time> | --minutes n] [--location text]", does: "Move or relocate an interview. A new --start keeps the length unless --end or --minutes is given.", returns: "data: { id, applicationId, round, status, startsAt, endsAt, locationOrLink, participants: [{ principalId, submitted }], talentName, jobTitle, url }. Times are UTC." },
|
|
195
|
+
{ usage: "hr interviews cancel <interview id>", does: "Cancel an interview.", returns: "data: { id, applicationId, round, status, startsAt, endsAt, locationOrLink, participants: [{ principalId, submitted }], talentName, jobTitle, url }. Times are UTC." },
|
|
196
|
+
{ usage: "hr people search <name>", does: "People (not Agents) in the organization, to name interviewers.", returns: "data: [{ id, name, email, jobTitle }]" },
|
|
197
|
+
{ usage: "hr reasons list", does: "Reject reasons.", returns: "data: [{ id, name, category }]. Rejecting uses those with category we_rejected." },
|
|
198
|
+
{ 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? }" }
|
|
199
|
+
];
|
|
200
|
+
var Overall = `hr: SpringBrand HR from the command line. Output is JSON on stdout.
|
|
170
201
|
|
|
171
202
|
Setup
|
|
172
203
|
HR_API_URL this deployment's HR address (or --api-url)
|
|
173
204
|
HR_AGENT_KEY an Agent key from IAM; without it, run \`hr login\`
|
|
174
205
|
IAM_URL optional; by default HR says where IAM is
|
|
175
206
|
|
|
176
|
-
Commands
|
|
177
|
-
|
|
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]
|
|
207
|
+
Commands (\`hr <command> --help\` shows what one returns)
|
|
208
|
+
${Commands.map((command) => ` ${command.usage}`).join("\n")}
|
|
187
209
|
|
|
188
|
-
|
|
189
|
-
|
|
210
|
+
Every command prints { ok: true, data } or { ok: false, error: { code, message } }.
|
|
211
|
+
<job> is a title, slug or id. Talents and applications carry url, their page in the HR console.
|
|
212
|
+
A command without the permission answers with data.pendingApproval: the action waits for a person to decide in IAM.`;
|
|
213
|
+
function helpFor(args) {
|
|
214
|
+
const words = args.filter((arg) => !arg.startsWith("-")).slice(0, 2).join(" ");
|
|
215
|
+
const command = words && Commands.find((entry) => entry.usage.startsWith(`hr ${words}`));
|
|
216
|
+
if (!command) return Overall;
|
|
217
|
+
return [`${command.usage}`, "", command.does, "", `Returns ${command.returns}`, ...command.example ? ["", `Example: ${command.example}`] : []].join("\n");
|
|
218
|
+
}
|
|
190
219
|
var options = {
|
|
191
220
|
"api-url": { type: "string" },
|
|
192
221
|
job: { type: "string" },
|
|
@@ -197,6 +226,11 @@ var options = {
|
|
|
197
226
|
wait: { type: "boolean" },
|
|
198
227
|
"no-browser": { type: "boolean" },
|
|
199
228
|
timeout: { type: "string" },
|
|
229
|
+
start: { type: "string" },
|
|
230
|
+
end: { type: "string" },
|
|
231
|
+
minutes: { type: "string" },
|
|
232
|
+
location: { type: "string" },
|
|
233
|
+
with: { type: "string" },
|
|
200
234
|
help: { type: "boolean", short: "h" }
|
|
201
235
|
};
|
|
202
236
|
async function linked(hr, records, page2) {
|
|
@@ -228,6 +262,46 @@ async function rejectReason(hr, reason) {
|
|
|
228
262
|
const reasons = (await hr.get("/reject-reasons")).filter((entry) => entry.category === "we_rejected");
|
|
229
263
|
return pickOne(reasons, reason, (entry) => [entry.name], (entry) => ({ id: entry.id, name: entry.name }), "reject reason").id;
|
|
230
264
|
}
|
|
265
|
+
function time(value, flag) {
|
|
266
|
+
const date = new Date(value);
|
|
267
|
+
if (!/T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})$/i.test(value) || Number.isNaN(date.getTime())) {
|
|
268
|
+
throw new CliError("USAGE", `${flag} needs an ISO 8601 time with its UTC offset, such as 2026-11-12T15:00+08:00`);
|
|
269
|
+
}
|
|
270
|
+
return date;
|
|
271
|
+
}
|
|
272
|
+
function minutes(value) {
|
|
273
|
+
const length = Number(value);
|
|
274
|
+
if (!Number.isInteger(length) || length < 5 || length > 600) throw new CliError("USAGE", "--minutes is a whole number from 5 to 600");
|
|
275
|
+
return length;
|
|
276
|
+
}
|
|
277
|
+
function slot(values, current) {
|
|
278
|
+
if (values.end && values.minutes) throw new CliError("USAGE", "Pass --end or --minutes, not both");
|
|
279
|
+
const startsAt = values.start ? time(values.start, "--start") : current ? new Date(current.startsAt) : void 0;
|
|
280
|
+
if (!startsAt) throw new CliError("USAGE", "Pass --start");
|
|
281
|
+
const length = values.minutes ? minutes(values.minutes) : current ? (new Date(current.endsAt).getTime() - new Date(current.startsAt).getTime()) / 6e4 : 60;
|
|
282
|
+
const endsAt = values.end ? time(values.end, "--end") : new Date(startsAt.getTime() + length * 6e4);
|
|
283
|
+
return { startsAt: startsAt.toISOString(), endsAt: endsAt.toISOString() };
|
|
284
|
+
}
|
|
285
|
+
var people = async (hr) => (await hr.get("/people")).filter((person) => person.type === "human");
|
|
286
|
+
var describePerson = (person) => ({ id: person.id, name: person.displayName, email: person.email, jobTitle: person.jobTitle });
|
|
287
|
+
async function interviewers(hr, names) {
|
|
288
|
+
if (!names) {
|
|
289
|
+
const me = await hr.get("/me");
|
|
290
|
+
if (me.kind !== "human") throw new CliError("USAGE", "Say who interviews: pass --with with names from `hr people search`");
|
|
291
|
+
return [me.principalId];
|
|
292
|
+
}
|
|
293
|
+
const everyone = await people(hr);
|
|
294
|
+
return names.split(",").map((name) => name.trim()).filter(Boolean).map((name) => isId(name) ? name : pickOne(everyone, name, (person) => [person.displayName, person.email], describePerson, "person").id);
|
|
295
|
+
}
|
|
296
|
+
async function toScheduleApplication(hr, who, job) {
|
|
297
|
+
if (isId(who)) return who;
|
|
298
|
+
const queue = await hr.get("/applications", { queue: "to_schedule", jobId: await jobId(hr, job), pageSize: 200 });
|
|
299
|
+
return pickOne(queue.items, who, (item) => [item.talentName], (item) => ({ id: item.id, talent: item.talentName, job: item.jobTitle }), "candidate waiting for an interview").id;
|
|
300
|
+
}
|
|
301
|
+
async function described(hr, interview) {
|
|
302
|
+
const detail = await hr.get(`/applications/${interview.applicationId}`);
|
|
303
|
+
return { ...interview, talentName: detail.talent.displayName, jobTitle: detail.job.title, url: `${await hr.appOrigin()}/applications/${interview.applicationId}` };
|
|
304
|
+
}
|
|
231
305
|
async function approvalStatus(hr, deps, id, wait, timeoutSeconds) {
|
|
232
306
|
const deadline = Date.now() + timeoutSeconds * 1e3;
|
|
233
307
|
for (; ; ) {
|
|
@@ -272,6 +346,30 @@ async function dispatch(args, deps) {
|
|
|
272
346
|
}
|
|
273
347
|
case "interviews to-schedule":
|
|
274
348
|
return linkedPage(hr, await hr.get("/applications", { queue: "to_schedule", jobId: await jobId(hr, values.job), ...page2 }), "applications");
|
|
349
|
+
case "interviews schedule": {
|
|
350
|
+
const applicationId = await toScheduleApplication(hr, needed("a candidate", rest.join(" ")), values.job);
|
|
351
|
+
const body = { ...slot(values), participants: await interviewers(hr, values.with), ...values.location !== void 0 ? { locationOrLink: values.location } : {} };
|
|
352
|
+
return described(hr, await hr.post(`/applications/${applicationId}/interviews`, body));
|
|
353
|
+
}
|
|
354
|
+
case "interviews list": {
|
|
355
|
+
const applicationId = needed("an application id", rest[0]);
|
|
356
|
+
const url = `${await hr.appOrigin()}/applications/${applicationId}`;
|
|
357
|
+
return (await hr.get("/interviews", { applicationId })).map((interview) => ({ ...interview, url }));
|
|
358
|
+
}
|
|
359
|
+
case "interviews reschedule": {
|
|
360
|
+
const id = needed("an interview id", rest[0]);
|
|
361
|
+
if (!values.start && !values.end && !values.minutes && values.location === void 0) throw new CliError("USAGE", "Pass --start, --end, --minutes or --location");
|
|
362
|
+
const current = await hr.get(`/interviews/${id}`);
|
|
363
|
+
const times = values.start || values.end || values.minutes ? slot(values, current) : {};
|
|
364
|
+
return described(hr, await hr.patch(`/interviews/${id}`, { ...times, ...values.location !== void 0 ? { locationOrLink: values.location } : {} }));
|
|
365
|
+
}
|
|
366
|
+
case "interviews cancel":
|
|
367
|
+
return described(hr, await hr.patch(`/interviews/${needed("an interview id", rest[0])}`, { status: "cancelled" }));
|
|
368
|
+
case "people search": {
|
|
369
|
+
const everyone = await people(hr);
|
|
370
|
+
const wanted = rest.join(" ").trim().toLowerCase();
|
|
371
|
+
return everyone.filter((person) => !wanted || [person.displayName, person.email].some((value) => value?.toLowerCase().includes(wanted))).map(describePerson);
|
|
372
|
+
}
|
|
275
373
|
case "reasons list":
|
|
276
374
|
return hr.get("/reject-reasons");
|
|
277
375
|
case "approvals status":
|
|
@@ -282,7 +380,7 @@ async function dispatch(args, deps) {
|
|
|
282
380
|
}
|
|
283
381
|
async function run(args, deps) {
|
|
284
382
|
if (!args.length || args.includes("--help") || args.includes("-h")) {
|
|
285
|
-
deps.stdout(
|
|
383
|
+
deps.stdout(helpFor(args));
|
|
286
384
|
return 0;
|
|
287
385
|
}
|
|
288
386
|
try {
|