hirify-cli 0.6.3 → 0.6.5

package/bin/lib/cli.js

@@ -103,7 +103,7 @@ export function parse(argv) {
 }
 export function help(topic = '') {
   const entries = Object.entries(COMMANDS).filter(([name]) => !topic || name === topic || name.startsWith(topic + ' '))
-  return `hirify - job search for AI agents\n\n${(entries.length ? entries : Object.entries(COMMANDS)).map(([name, spec]) => `  hirify ${(name + (ARGUMENTS[name] ? ' ' + ARGUMENTS[name] : '')).padEnd(35)} ${spec.description}${spec.flags?.length ? `\n    ${spec.flags.map(f => '--' + f + (BOOLEAN_FLAGS.has(f) ? '' : ' <value>')).join('  ')}` : ''}`).join('\n')}\n\nGlobal options: --json, --fields a,b, --error-format json|text, --timeout <seconds>, --debug, --help.\nUse -- to end options; --name=value and --name value are supported.\nLists and search are free. Vacancy read, reveal and apply have separate allowances.\nCheck them with hirify account show. Apply sends a real application: ask the person first.\nLocal agents reuse saved sign-in when allowed. Token renewal needs write access.\nSandbox access denied: request permission for the command; do not copy tokens.\nHeadless/CI: HIRIFY_KEY or hirify auth --stdin. Manual login: --no-browser.\nSSH: forward the chosen --callback-port to the same loopback port on the CLI host.\nSet up the CLI, the skill and sign-in: hirify init. The skill alone: hirify skill\n`
+  return `hirify - job search for AI agents\n\n${(entries.length ? entries : Object.entries(COMMANDS)).map(([name, spec]) => `  hirify ${(name + (ARGUMENTS[name] ? ' ' + ARGUMENTS[name] : '')).padEnd(35)} ${spec.description}${spec.flags?.length ? `\n    ${spec.flags.map(f => '--' + f + (BOOLEAN_FLAGS.has(f) ? '' : ' <value>')).join('  ')}` : ''}`).join('\n')}\n\nGlobal options: --json, --fields a,b, --error-format json|text, --timeout <seconds>, --debug, --help.\nUse -- to end options; --name=value and --name value are supported.\nStart with hirify intro: the working method, kept current by Hirify.\nAllowances: hirify account show. Apply sends a real application: ask your user first.\nLocal agents reuse saved sign-in when allowed. Token renewal needs write access.\nSandbox access denied: request permission for the command; do not copy tokens.\nHeadless/CI: HIRIFY_KEY or hirify auth --stdin. Manual login: --no-browser.\nSSH: forward the chosen --callback-port to the same loopback port on the CLI host.\nSet up the CLI, the skill and sign-in: hirify init. The skill alone: hirify skill\n`
 }
 export function createOutput({ stdout = process.stdout, stderr = process.stderr, json = false, errorJSON = false, secrets = new Set() } = {}) {
   let closed = false

package/bin/lib/commands.js

@@ -110,6 +110,8 @@ function printVacancies(list, meta) {
     ? true
     : perPage !== null && list.length >= perPage
   if (more && page !== null) console.log(`More: add --page ${page + 1}`)
+  // Paging is fine; a list this long usually means the criteria do not yet describe the user.
+  if (lastPage !== null && lastPage > 3) console.log(`${total ?? 'Many'} vacancies over ${lastPage} pages: narrower criteria usually give a list worth reading in full.`)
 }
 
 /** The vacancies in one saved feed, using the criteria the feed already holds. */
@@ -619,94 +621,24 @@ async function cmdWebhookCreate(args, words) {
 
 const INTRO = `hirify - job search for AI agents
 
-Hirify is a job board. This CLI is how an agent works it for someone: the same vacancies, the
-same saved filters and the same account they have at hirify.me.
+This is the built-in text: Hirify did not return the playbook. The working method (interviewing your
+user, setting up the search, going through the results, judging a vacancy, applying) is the Hirify
+playbook, kept current on the server: https://hirify.me/agent-playbook.txt. Run hirify intro again
+when Hirify is reachable.
 
 Setting up
   npx -y hirify-cli@latest init installs this CLI and the agent's skill, then opens sign-in.
 
 Signing in
-  hirify login prints a link and tries the browser when available. A person confirms access.
+  hirify login prints a link and tries the browser when available. Your user confirms access.
   Manual sign-in: hirify login --no-browser. For automation, use HIRIFY_KEY or hirify auth --stdin; get a key at
   hirify.me/account/api-access.
 
-Start with what the account already has
-  Most people who use Hirify have saved a filter or two on the site. Those are feeds, and they
-  are the best place to start, because someone has already said in them what they want.
-
-    hirify account show          the plan and allowances
-    hirify feed list             what this account has saved
-    hirify feed show 31          the vacancies in one of them
-
-  When no feed fits, search the whole board. Search takes a phrase, and any criterion the
-  site's own filter form can express, written as an option:
-
-    hirify vacancy search "senior go"
-    hirify vacancy search "senior go" --page 2
-    hirify vacancy search "senior go" --<criterion> <value>
-
-  The criteria are the server's, not this CLI's, and nothing here names one on purpose: a
-  name written into this text would be a copy, and copies go stale quietly. Ask instead:
-
-    hirify filter guide
-
-  It prints what search can filter on and what the values are, written by the server from
-  the same source the site searches with. An option is sent on under the name you gave it;
-  give one twice and the values are joined, the way the site sends a filter with several
-  values.
-
-Read before you spend anything
-  A card is a headline: title, company, terms. Fit is decided in the text.
-
-    hirify vacancy read senior-go-engineer
-
-  This prints the whole vacancy, and it also says which of the two ways to apply this one
-  takes, so you do not have to work that out or find out from a refusal.
-
-What costs what
-  Lists and searches are free.
-  Reading one vacancy in full spends one of the Agent API's daily vacancy opens. There are
-  many of them, and reading a vacancy again the same day costs nothing. Read as much as you
-  need to.
-  Revealing where to apply spends 1 reveal, and reveals are the scarce one. Protect that
-  number: shortlist by reading, then reveal only the ones worth applying to.
-  Applying has a daily allowance of its own. It is not the free step it looks like.
-  hirify account show has all three, and it is the only place they are current.
-
-Where to apply
-    hirify vacancy reveal senior-go-engineer
-
-  Gives the company, its LinkedIn page when we know it, and the address to send the
-  application to. Revealing the same vacancy again returns the same thing and costs nothing.
-
-Applying
-  Most vacancies here came from somewhere else: company pages, Telegram channels, other
-  boards. For those, reveal brings back the address, and the application is made there rather
-  than through Hirify.
-  Vacancies hosted on Hirify can be applied to from here:
-
-    hirify profile list
-    hirify vacancy apply senior-go-engineer --profile 4 --cover "..."
-
-  An application reaches a real person and cannot be recalled. Ask first, every time, and
-  show what you are about to send. Nothing follows up afterwards: the recruiter replies
-  where they choose to.
-
-Two more things
-  A saved search can be created from here and delivered to Telegram or to a server of yours:
-  hirify feed create, hirify feed deliver, hirify webhook list.
-  Something broken or missing: hirify feedback send bug "<title>" --body "<what happened>". It
-  reaches the team and costs nothing.
-
-If a command you need is not here
-  hirify api call <capability> invokes any capability Hirify lists in its manifest and prints
-  the answer as it comes back, so a capability without its own command is a detour and not a
-  dead end. Inputs go in --data as a JSON object. Prefer the commands above where one fits:
-  they say what a thing costs and what a refusal means, and this one cannot.
-
-If you are an agent
-  Install the working rules once: hirify skill. They cover the order
-  above, what needs the person's permission before you do it, and what each refusal means.
+Commands
+  hirify account show, hirify feed list, hirify vacancy search, hirify vacancy read,
+  hirify vacancy reveal, hirify vacancy apply, hirify filter guide. Anything else:
+  hirify api call <capability>. An application reaches a real person and cannot be recalled:
+  ask your user first.
 
 Use --json for structured results and --error-format=json for structured errors.
 The full list of commands: hirify --help`

package/bin/lib/main.js

@@ -56,6 +56,7 @@ export async function main(argv = process.argv.slice(2), { baseRoot = ownRoot, b
     const api = createApi({ config, http, auth, output })
     const updater = createUpdater({ config, http, signal, output, event, packageRoot: ownRoot, baseRoot, baseVersion })
     const local = ['auth', 'auth status', 'logout', 'doctor', 'init', 'skill', 'update'].includes(command.name)
+    if (!['init', 'skill'].includes(command.name)) { const { refreshSkill } = await import('./setup.js'); refreshSkill({ packageRoot: ownRoot, env: config.env }) }
     if (!skipUpdate && !local) next = await updater.automatic()
     if (next) {
       // Dispose every timer and signal handler before handing off, at most once per invocation.

package/bin/lib/setup.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, cpSync, rmSync, symlinkSync, realpathSync, readFileSync } from 'node:fs'
+import { existsSync, mkdirSync, cpSync, rmSync, symlinkSync, realpathSync, readFileSync, writeFileSync, lstatSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join, relative } from 'node:path'
 import semver from 'semver'
@@ -52,6 +52,7 @@ export function installSkill({ packageRoot, env = process.env, home = homedir(),
     mkdirSync(shared, { recursive: true })
     remove(path)
     cpSync(source, path, { recursive: true })
+    markVersion(path, packageRoot)
   } catch (error) { throw new CliError('skill_install_failed', `Could not save the skill (${reason(error)}). This command needs write access to the home directory.`) }
   const agents = []
   for (const agent of agentDirectories({ env, home })) {
@@ -71,6 +72,39 @@ export function installSkill({ packageRoot, env = process.env, home = homedir(),
   return { skill: SKILL_NAME, path, agents }
 }
 
+// Which CLI release the installed skill came from, so a newer CLI knows to refresh it.
+const VERSION_MARK = '.hirify-cli-version'
+const packageVersion = root => { try { return JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version } catch { return null } }
+function markVersion(path, packageRoot) { const version = packageVersion(packageRoot); if (version) writeFileSync(join(path, VERSION_MARK), version + '\n') }
+
+/**
+ * Refresh a skill this CLI installed earlier, when the running CLI is newer than the release it
+ * came from: an auto-updated CLI brings its skill along, so the working rules on the computer
+ * never lag behind the CLI. Only an existing installation is touched - nothing is installed where
+ * there was none - and an older CLI never rolls a newer skill back. Agents that got a copy rather
+ * than a link get their copy refreshed too. Best effort: any failure leaves things as they were.
+ */
+export function refreshSkill({ packageRoot, env = process.env, home = homedir() } = {}) {
+  try {
+    const source = join(packageRoot, 'skills', SKILL_NAME)
+    const path = join(home, '.agents', 'skills', SKILL_NAME)
+    const own = packageVersion(packageRoot)
+    if (!own || !existsSync(join(path, 'SKILL.md')) || !existsSync(join(source, 'SKILL.md'))) return false
+    let installed = null
+    try { installed = readFileSync(join(path, VERSION_MARK), 'utf8').trim() } catch {}
+    if (semver.valid(installed) && !semver.gt(own, installed)) return false
+    remove(path); cpSync(source, path, { recursive: true }); markVersion(path, packageRoot)
+    for (const agent of agentDirectories({ env, home })) {
+      const target = join(agent.skills, SKILL_NAME)
+      try {
+        if (!existsSync(join(target, 'SKILL.md')) || lstatSync(target).isSymbolicLink() || realpathSync(target) === realpathSync(path)) continue
+        remove(target); cpSync(source, target, { recursive: true })
+      } catch {}
+    }
+    return true
+  } catch { return false }
+}
+
 /**
  * Put the newest release of the CLI on PATH, whichever package started the command, with the
  * person's own npm and its settings: the environment goes to npm as it is, because what npx adds

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "hirify-cli",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "hirify-cli",
-      "version": "0.6.3",
+      "version": "0.6.5",
       "license": "Apache-2.0",
       "dependencies": {
         "cross-spawn": "7.0.6",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hirify-cli",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "Hirify CLI for AI agents: browser sign-in, job feeds, search, reading a vacancy in full, contacts to apply to, and applying on Hirify.",
   "bin": {
     "hirify": "bin/hirify.js"

package/skills/hirify/SKILL.md

@@ -5,103 +5,50 @@ description: Job search through Hirify - vacancies from the user's saved feeds,
 
 # Hirify job search
 
-Use the Hirify job board through the `hirify` CLI. This file gives the working order; `reference.md`
-has every command in full, and `hirify intro` is the server's guide.
+## Start here
+
+Run `hirify intro` once per session, before anything else. It prints the Hirify playbook, the
+working method: interviewing your user, setting up the search, going through the results, judging
+a vacancy, applying. Hirify keeps it current on the server (it is also at
+https://hirify.me/agent-playbook.txt), so follow it rather than any older notes. This file only
+covers running the CLI; `reference.md` has every command.
+
+One rule stands regardless: `vacancy apply` sends a real application that cannot be taken back.
+Ask your user first, every time, and show what you are about to send.
 
 ## Setup and automation
 
 Package: `hirify-cli`; command: `hirify`; Node >=18.
 If `hirify` is missing, run `npx -y hirify-cli@latest init`: it installs the CLI and this skill,
-then signs in. Until then use `npx -y hirify-cli <command>`. Global installs update themselves;
-pin an exact version with `HIRIFY_NO_AUTO_UPDATE=1`.
+then signs in. Until then use `npx -y hirify-cli <command>`. Global installs update themselves,
+and this skill with them; pin an exact version with `HIRIFY_NO_AUTO_UPDATE=1`.
 
-To sign in, run `hirify login`; the person confirms access in the browser within five minutes.
+To sign in, run `hirify login`; your user confirms access in the browser within five minutes.
 It fails at once over SSH, and without a terminal in CI or with no display. `--no-browser` is
 manual callback login. SSH needs `--callback-port` with a matching SSH local port forward. Local
-agents reuse the person's saved sign-in when permitted to access the same configuration directory.
+agents reuse your user's saved sign-in when permitted to access the same configuration directory.
 CI and separate containers can use `HIRIFY_KEY` or `hirify auth --stdin`; never put a key in a
 command, log or chat.
 `hirify auth status --json` identifies the local source. Environment keys override saved access;
 logout is local and does not unset them. Use `hirify login --force` to replace expired access.
 
-Fetch mutable facts: `filter guide` for filter names/values, `account show --json` for current
-allowances and permissions, `--help` for commands, `capabilities show <id> --json` for inputs,
-effects and metering. This file supplies working rules, not a snapshot of server policy.
-
-## Two rules before anything else
-
-**Lists are free. Three commands are metered, and they spend different things.**
-
-- `vacancy read` spends one of the day's vacancy opens. Re-reading a vacancy the same day is free.
-- `vacancy reveal` spends 1 reveal, and reveals are scarce. When they run out, reading still works.
-- `vacancy apply` counts against a small daily allowance of its own and **cannot be taken back**. It
-  sends a real application, with the user's name and profile, to a person who will read it.
-
-**`hirify account show` is the only place these numbers are true.** Read it before spending; never
-state what is left from memory or plan a batch on a stale figure.
-
-**Ask the user before every apply, and before anything that changes their account.** Reading needs
-no permission. Sending, saving and configuring do.
-
-## Working order
-
-1. `hirify account show` before spending; use `feed list` and `feed show <id>` first.
-2. Search when no saved feed fits. Shortlist from cards; missing contacts are normal.
-3. `vacancy read <slug>` to assess fit from the full text rather than a headline.
-4. `vacancy reveal <slug>` only for vacancies that still fit after reading.
-5. Apply only after the person's approval and the rules below.
-6. `vacancy hide`/`company hide` what the user rejected; `hidden list` shows it.
+## Where current facts live
 
-## Searching
+Fetch mutable facts instead of remembering them: `filter guide` for filter names, values and how
+a request becomes a filter; `account show --json` for current allowances and permissions;
+`--help` for commands; `capabilities show <id> --json` for inputs, effects and metering.
 
 `vacancy search` takes a phrase and server-defined filter options; `--limit` and `--page` control
-pagination. Never guess criterion names or values. An empty result can mean a misspelt value.
-
-1. Read `hirify filter guide` and build criteria from the user's request or profile.
-2. Run `hirify api call filters.preview --data '{"filters":{...},"mode":"compact","per_page":20}'`.
-3. Inspect cards and `meta.total`; refine and preview again if empty, broad or irrelevant.
-4. Run `hirify vacancy search` with the validated criteria.
-
-If the guide is unavailable, ask the user about criteria rather than guessing.
-
-## Applying
-
-Two cases, two commands:
-
-- **Hosted on Hirify** -> `hirify vacancy apply <slug>` sends the application through Hirify.
-- **From somewhere else** -> `hirify vacancy reveal <slug>` gives the link or contact, and the
-  application goes there rather than through Hirify. `vacancy apply` refuses these and says so.
-  What you do with that destination is between you and your user.
-
-- **Ask first, every time, and show what you are about to send.** An application cannot be taken
-  back. Never apply to a list on a single "yes".
-- **Never invent the cover letter.** Draft it from what the user actually said about themselves and
-  show them the draft; if they gave you nothing, ask rather than fill the gap.
-- **Never choose the profile** when the user has several: `hirify profile list` lists them. With
-  exactly one profile it is chosen automatically.
-- After a successful apply, say it was sent and stop. Nobody follows up: the recruiter replies where
-  they choose to, and Hirify does not track it.
-
-## Saved searches and delivery
-
-These commands change the user's account, so get a yes. Creation leaves delivery off: report that,
-offer the exact `feed deliver` command, and run it only after a separate yes.
-
-```bash
-hirify feed create "<name>" --filters '<json>'   # criteria: hirify filter guide
-hirify feed deliver <id> --telegram | --no-telegram | --webhook <id> | --no-webhook
-hirify webhook list
-hirify webhook create "<name>" <url>
-```
+pagination. Check a draft with
+`hirify api call filters.preview --data '{"filters":{...},"mode":"compact","per_page":20}'`.
 
-`--filters` uses the site's filter criteria; read `hirify filter guide` first.
-Creating a delivery endpoint returns a **secret shown once**: give it to the user immediately to
-store, because it signs every delivery and cannot be shown again.
+Creating a delivery endpoint (`hirify webhook create`) returns a **secret shown once**: give it to
+your user immediately to store, because it signs every delivery and cannot be shown again.
 
 ## Feedback and failures
 
 `hirify feedback send <bug|feature> "<title>" --body "<text>" [--vacancy <slug>]` is free.
-Ask first and send the user's words. Report the actual received/queued status and retain the
+Ask first and send your user's words. Report the actual received/queued status and retain the
 reference; do not promise a reply or a fix. Keep an explicit `--idempotency-key` for deliberate
 retries when the server supports it.
 
@@ -109,7 +56,7 @@ Parse `--json` success output, never human text. Use `--error-format=json` for s
 errors; do not combine it with debug if expecting one object. Exit 0 means success, 1 failure,
 2 unsupported server manifest, 130/143 interruption. Read the stable error code and message.
 
-- `interaction_required`: ask the person to sign in or configure a key; do not wait on browser login.
+- `interaction_required`: ask your user to sign in or configure a key; do not wait on browser login.
 - Storage access failure: compare `doctor`, `version`, and `auth status` with the normal terminal.
   Request permission for the specific command through the agent's approval mechanism. Reading a
   current token needs read access; renewal needs write access. Do not treat storage errors as an
@@ -118,6 +65,7 @@ errors; do not combine it with debug if expecting one object. Exit 0 means succe
 - Authentication failure: inspect `auth status`; ask for `login --force` only when renewal requires
   a new sign-in. Never expose a token.
 - 403: permission or plan restriction. 429: pace or a named allowance; inspect `account show`.
+- `action_required`: stop and show your user the message; it concerns their account.
 - Network/TLS/proxy failure: fix connectivity or trust configuration; never disable TLS verification.
 - `outcome_unknown`: a metered action or mutation may have succeeded. Check before repeating;
   the CLI does not automatically retry it. Do not blindly repeat apply, reveal or feedback.