hirify-cli 0.4.7 → 0.5.0

package/bin/lib/api.js

@@ -0,0 +1,130 @@
+import { randomUUID } from 'node:crypto'
+import { CliError } from './errors.js'
+import { trustedURL } from './config.js'
+import { requireJSON, retryDelay } from './http.js'
+import { accessRestrictedMessage, actionRequiredMessage } from './messages.js'
+const READS = new Set(['account.status', 'vacancies.search', 'feeds.list', 'feeds.vacancies', 'profiles.list', 'webhooks.list', 'filters.guide'])
+const LISTS = new Set(['vacancies.search', 'feeds.list', 'feeds.vacancies', 'profiles.list', 'webhooks.list'])
+const OBJECTS = new Set(['account.status', 'vacancies.read', 'vacancies.reveal', 'applications.apply', 'feeds.create', 'feeds.set_delivery', 'webhooks.create', 'feedback.send', 'filters.guide'])
+const isObject = value => value && typeof value === 'object' && !Array.isArray(value)
+const immutable = value => { if (value && typeof value === 'object') { for (const child of Object.values(value)) immutable(child); Object.freeze(value) }; return value }
+export function validateManifest(doc, origin) {
+  if (!isObject(doc) || !Number.isInteger(doc.schema_version) || doc.schema_version < 1) throw new CliError('manifest_invalid', 'Hirify sent a manifest without a supported version.')
+  if (doc.schema_version > 1) throw new CliError('manifest_unsupported', 'this Hirify speaks a newer manifest than this CLI can read. Please update the CLI.', { exitCode: 2 })
+  if (!Array.isArray(doc.capabilities)) throw new CliError('manifest_invalid', 'Hirify sent a manifest with no list of what it can do.')
+  const ids = new Set()
+  for (const cap of doc.capabilities) {
+    if (!isObject(cap) || typeof cap.id !== 'string' || !/^[a-zA-Z0-9_.-]+$/.test(cap.id) || ids.has(cap.id) || !['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD'].includes(cap.method) || typeof cap.path !== 'string' || /[?#]/.test(cap.path)) throw new CliError('manifest_invalid', 'Hirify returned an invalid capability description.')
+    ids.add(cap.id); trustedURL(cap.path, origin, { path: true })
+    if (cap.inputs !== undefined && !isObject(cap.inputs)) throw new CliError('manifest_invalid', 'Hirify returned invalid input metadata.')
+    // Schema v1 servers serialize an empty PHP map as []; nonempty lists are still invalid.
+    const locations = cap.inputs?.locations
+    const emptyLocations = Array.isArray(locations) && locations.length === 0
+    if (locations !== undefined && !emptyLocations && (!isObject(locations) || Object.values(locations).some(where => !['path', 'query', 'body'].includes(where)))) throw new CliError('manifest_invalid', 'Hirify returned invalid input locations.')
+    if (cap.inputs?.schema !== undefined && !isObject(cap.inputs.schema)) throw new CliError('manifest_invalid', 'Hirify returned an invalid input schema.')
+  }
+  return immutable(doc)
+}
+export function responseError(response, { key = false } = {}) {
+  const { status, body, headers } = response
+  const options = { status, requestId: headers.get('x-request-id') || headers.get('request-id') || undefined }
+  if (status === 401) return new CliError('auth_required', key ? 'the key was not accepted (401). It may have been revoked, or copied incompletely.' : 'your sign-in is no longer valid. Please run hirify login --force.', options)
+  if (status === 403 && body?.error?.code === 'access_restricted') return new CliError('access_restricted', accessRestrictedMessage(body), options)
+  if (status === 409 && body?.error?.code === 'action_required') return new CliError('action_required', actionRequiredMessage(body), options)
+  if (status === 403) return new CliError('access_denied', 'no access (403). This needs an active paid plan, or the sign-in is missing a permission.', options)
+  if (status === 404) return new CliError('not_found', 'not found (404).', options)
+  if (status === 429) {
+    const action = body?.quota?.action
+    const messages = {
+      vacancy_opens: 'you have opened as many vacancies today as the daily allowance covers.\n        Feeds and search still work, and so does anything already read today.',
+      contact_reveals: 'you have no reveals left right now. Reading still works.',
+      apply: 'you have sent as many applications today as the daily allowance covers.\n        Reading and revealing still work. What is left: hirify account show',
+    }
+    const wait = Math.ceil(retryDelay(headers.get('retry-after')) / 1000)
+    const message = messages[action] || (body?.quota ? `today's allowance for ${String(action ?? 'that action').replace(/_/g, ' ')} is used up.\n        What is left: hirify account show` : `too many requests in a short time.${wait ? ` Please try again in ${wait} seconds.` : ' Please try again in a minute.'}`)
+    return new CliError(body?.quota ? 'quota_exhausted' : 'rate_limited', message, { ...options, retryable: !body?.quota })
+  }
+  return new CliError(status >= 500 ? 'server_error' : 'request_rejected', status >= 500 ? 'something went wrong on our side. Please try again in a minute.' : 'that command could not be completed. Please check it and try again.', options)
+}
+export function createApi({ config, http, auth, output }) {
+  let discovery, manifest, lastError
+  async function agentDiscovery() {
+    if (!discovery) discovery = (async () => {
+      const res = await http.request(`${config.api}/.well-known/hirify-agent`, { safe: true, timeout: 5000 })
+      if (!res.ok) throw new CliError('discovery_unavailable', 'could not reach Hirify to load what it can do. Please check your connection and try again.', { status: res.status })
+      const doc = requireJSON(res)
+      if (!isObject(doc)) throw new CliError('discovery_invalid', 'Hirify returned invalid discovery metadata.')
+      if (doc.manifest_url) trustedURL(doc.manifest_url, config.api)
+      return doc
+    })()
+    return discovery
+  }
+  async function authenticated(url, options = {}) {
+    // Validate even on retries; changing the configured server never retargets saved tokens.
+    const target = trustedURL(url, config.api)
+    const token = await auth.access()
+    const send = value => http.request(target, { ...options, headers: { ...options.headers, Authorization: `Bearer ${value}` } })
+    let res = await send(token)
+    if (res.status === 401 && options.safe) {
+      const replacement = await auth.retryToken(token)
+      if (replacement) res = await send(replacement)
+    }
+    return res
+  }
+  async function loadManifest() {
+    if (!manifest) manifest = (async () => {
+      const doc = await agentDiscovery()
+      if (!doc.manifest_url) throw new CliError('manifest_unavailable', 'could not reach Hirify to load what it can do. Please check your connection and try again.')
+      const res = await authenticated(doc.manifest_url, { safe: true })
+      if (!res.ok) { if (res.status === 401) throw responseError(res, { key: Boolean(config.envKey) }); throw new CliError('manifest_unavailable', 'could not load what Hirify can do right now. Please try again in a minute.', { status: res.status }) }
+      return validateManifest(requireJSON(res), config.api)
+    })()
+    return manifest
+  }
+  async function resolveCapability(id) {
+    const cap = (await loadManifest()).capabilities.find(c => c.id === id)
+    if (!cap) throw new CliError('capability_unavailable', `this Hirify does not offer "${id}". It may be an older server, or the operation has moved.`)
+    return cap
+  }
+  async function callCapability(id, { params = {}, query, payload = null, allow = [], raw = false } = {}) {
+    const cap = await resolveCapability(id)
+    const path = cap.path.replace(/\{([a-zA-Z0-9_]+)\}/g, (_, name) => {
+      const value = params[name]
+      if (value === undefined || value === null || typeof value === 'object') throw new CliError('invalid_arguments', `this call needs "${name}", and it was not given.`)
+      return encodeURIComponent(String(value))
+    })
+    if (/[{}]/.test(path)) throw new CliError('manifest_invalid', 'Hirify returned an invalid path template.')
+    let target = trustedURL(path, config.api, { path: true })
+    if (query?.toString()) target += `?${query}`
+    const safe = cap.method === 'GET' && READS.has(id) && (!cap.meter || cap.meter === 'none')
+    const mutation = !['GET', 'HEAD'].includes(cap.method)
+    let replayKey
+    if (mutation && cap.retry_policy === 'caller_keyed' && cap.inputs?.locations?.idempotency_key === 'body') {
+      replayKey = payload?.idempotency_key || randomUUID()
+      payload = { ...(payload || {}), idempotency_key: replayKey }
+      if (typeof replayKey !== 'string' || !/^[A-Za-z0-9._:-]{1,128}$/.test(replayKey)) throw new CliError('invalid_arguments', 'Use an idempotency key of 1 to 128 letters, digits, dots, underscores, colons or hyphens.')
+      output?.progress(`Request reference: ${replayKey}. Keep this value if the same request needs to be repeated.`)
+    }
+    let res
+    try { res = await authenticated(target, { method: cap.method, safe, body: payload === null ? undefined : JSON.stringify(payload), headers: payload === null ? {} : { 'Content-Type': 'application/json' } }) }
+    catch (error) {
+      if (mutation && ['network_error', 'network_timeout', 'response_incomplete', 'response_too_large', 'command_timeout'].includes(error.code)) throw new CliError('outcome_unknown', 'No confirmation was received. The action may have completed. Check its result before trying again.')
+      if (mutation && error.code === 'cancelled') error.message += ' The action may have completed; check its result before retrying.'
+      throw error
+    }
+    if (res.ok) {
+      requireJSON(res, { mutation })
+      const expected = allow.filter(code => code >= 200 && code < 300)
+      if (!expected.length && (LISTS.has(id) || (OBJECTS.has(id) && cap.method === 'GET'))) expected.push(200)
+      const invalid = res.body.ok === false || (expected.length && !expected.includes(res.status)) || (LISTS.has(id) && !Array.isArray(res.body.data)) || (OBJECTS.has(id) && !isObject(res.body.data)) || (id === 'applications.apply' && !res.body.data?.application_id) || (['feeds.create', 'feeds.set_delivery'].includes(id) && !(res.body.data?.id ?? res.body.data?.feed_id)) || (id === 'webhooks.create' && !(res.body.data?.id ?? res.body.data?.endpoint_id)) || (id === 'feedback.send' && !(res.body.data?.reference || res.body.data?.ticket))
+      if (invalid) throw new CliError(mutation ? 'outcome_unknown' : 'protocol_error', mutation ? 'The server did not return a valid confirmation. Check the result before trying again.' : 'The server response did not match this operation.', { status: res.status })
+    }
+    lastError = res.ok ? null : mutation && res.status >= 500 ? new CliError('outcome_unknown', 'The server did not confirm the result. The action may have completed; check before retrying.', { status: res.status }) : responseError(res, { key: Boolean(config.envKey) })
+    if (raw) return { ...res, error: lastError }
+    if ([403, 409].includes(res.status) && ['access_restricted', 'action_required'].includes(res.body?.error?.code)) throw responseError(res)
+    if (allow.includes(res.status)) return { status: res.status, body: res.body, retryAfter: res.headers.get('retry-after'), error: res.ok ? null : responseError(res) }
+    if (!res.ok) throw lastError
+    return res.body
+  }
+  return { agentDiscovery, loadManifest, resolveCapability, callCapability, get lastError() { return lastError } }
+}

package/bin/lib/auth.js

@@ -0,0 +1,113 @@
+import { randomBytes, createHash, randomUUID } from 'node:crypto'
+import { CliError, aborted } from './errors.js'
+import { trustedURL } from './config.js'
+import { requireJSON } from './http.js'
+import { startCallbackServer } from './loopback.js'
+import { environment, openBrowser } from './browser.js'
+export const SCOPES = ['agent:read', 'agent:reveal', 'agent:apply', 'agent:manage', 'agent:feedback', 'offline_access']
+export function tokenResponse(body, previous = {}) {
+  if (!body || typeof body.access_token !== 'string' || !body.access_token.trim() || typeof body.token_type !== 'string' || body.token_type.toLowerCase() !== 'bearer' || (body.refresh_token != null && (typeof body.refresh_token !== 'string' || !body.refresh_token)) || (body.scope !== undefined && typeof body.scope !== 'string')) throw new CliError('oauth_protocol', 'The sign-in server returned an invalid token response. No new credentials were saved.')
+  if (body.expires_in !== undefined && !['number', 'string'].includes(typeof body.expires_in)) throw new CliError('oauth_protocol', 'The sign-in server returned an invalid token lifetime.')
+  const expiry = body.expires_in === undefined ? null : Number(body.expires_in)
+  if (expiry !== null && (!Number.isSafeInteger(expiry) || expiry <= 0 || expiry > 315360000)) throw new CliError('oauth_protocol', 'The sign-in server returned an invalid token lifetime.')
+  return { ...previous, access_token: body.access_token, refresh_token: body.refresh_token ?? previous.refresh_token ?? null, scope: body.scope ?? previous.scope ?? '', expires_at: expiry === null ? null : Math.floor(Date.now() / 1000) + expiry }
+}
+export function createAuth({ config, store, http, signal, output, event, secrets }) {
+  const remember = s => { if (s) { secrets.add(s.access_token); secrets.add(s.refresh_token) }; return s }
+  async function form(url, data) {
+    const res = await http.request(trustedURL(url, config.api), { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams(data).toString() })
+    return { ...res, body: requireJSON(res) }
+  }
+  async function refresh(observed, { force = false } = {}) {
+    return store.locked(async () => {
+      const current = store.read()
+      if (!current || current.kind !== 'oauth') throw new CliError('session_changed', 'The sign-in changed. Run the command again.')
+      if (current.generation !== observed.generation || current.access_token !== observed.access_token) return remember(current)
+      if (!force && (!current.expires_at || current.expires_at > Date.now() / 1000 + 60)) return remember(current)
+      if (!current.refresh_token) throw new CliError('auth_required', 'Your sign-in has expired. Run hirify login --force.')
+      const endpoint = trustedURL(current.token_endpoint || `${config.api}/oauth/token`, config.api)
+      // A lost refresh response cannot safely be retried with a rotating token.
+      await store.write({ ...current, refresh_pending: true })
+      let response
+      try { response = await form(endpoint, { grant_type: 'refresh_token', client_id: current.client_id, refresh_token: current.refresh_token }) }
+      catch (error) { if (signal.aborted) throw signal.reason; event('refresh', { code: error.code }); throw new CliError('refresh_uncertain', 'Token renewal did not finish safely. Run hirify login --force; the old refresh token will not be retried.') }
+      if (!response.ok) {
+        // Explicit OAuth errors are a known failure, but never silently replay the grant.
+        throw new CliError(response.body?.error === 'invalid_grant' ? 'auth_required' : 'refresh_failed', 'The saved sign-in could not be renewed. Run hirify login --force.', { status: response.status })
+      }
+      const next = remember(tokenResponse(response.body, current))
+      next.generation = randomUUID(); next.refresh_pending = false
+      await store.write(next); return next
+    })
+  }
+  async function access() {
+    if (config.envKey) { secrets.add(config.envKey); return config.envKey }
+    await store.secure()
+    let current = remember(store.read({ allowPending: true }))
+    if (!current) throw new CliError('auth_required', 'You are not signed in. Run hirify login. For CI or servers, set HIRIFY_KEY or use hirify auth --stdin.')
+    if (current.kind === 'oauth' && (current.refresh_pending || (current.expires_at && current.expires_at <= Date.now() / 1000 + 60))) current = await refresh(current)
+    return current.access_token
+  }
+  async function retryToken(rejected) {
+    if (config.envKey) return null
+    const current = remember(store.read({ allowPending: true }))
+    if (!current || current.kind !== 'oauth') return null
+    if (current.access_token !== rejected) return current.access_token
+    return (await refresh(current, { force: true })).access_token
+  }
+  async function discover() {
+    const res = await http.request(`${config.api}/.well-known/oauth-authorization-server`, { safe: true })
+    if (!res.ok) throw new CliError('oauth_discovery', 'Could not load the sign-in settings.', { status: res.status })
+    const body = requireJSON(res)
+    if (body.issuer !== config.api) throw new CliError('issuer_mismatch', 'The sign-in server returned a different issuer.')
+    const result = {}
+    for (const key of ['authorization_endpoint', 'token_endpoint', 'registration_endpoint']) result[key] = trustedURL(body[key], config.api)
+    if (body.code_challenge_methods_supported && (!Array.isArray(body.code_challenge_methods_supported) || !body.code_challenge_methods_supported.includes('S256'))) throw new CliError('oauth_protocol', 'The sign-in server does not support PKCE S256.')
+    const scopes = body.scopes_supported
+    if (scopes !== undefined && (!Array.isArray(scopes) || scopes.some(x => typeof x !== 'string'))) throw new CliError('oauth_protocol', 'The sign-in server returned invalid permissions.')
+    result.scopes = SCOPES.filter(scope => !scopes || scopes.includes(scope)).join(' ')
+    return result
+  }
+  async function login({ force = false, noBrowser = false, port = 0, consentMs = 300000 } = {}) {
+    if (!force) {
+      const current = store.read()
+      if (current?.kind === 'oauth') { await access(); return { signed_in: true, already_signed_in: true, source: config.envKey ? 'environment' : 'oauth' } }
+    }
+    const info = environment()
+    if (!noBrowser && (!info.interactive || info.remote)) throw new CliError('interaction_required', 'This terminal cannot complete browser sign-in automatically. Use HIRIFY_KEY or hirify auth --stdin. For manual sign-in, use hirify login --no-browser; over SSH, also choose --callback-port and forward that port.')
+    if (info.remote && noBrowser && !port) throw new CliError('remote_callback_required', 'Browser callbacks must reach this machine. Choose --callback-port and forward that port over SSH, or use HIRIFY_KEY.')
+    const generation = await store.beginLogin({ force })
+    const endpoints = await discover()
+    const verifier = randomBytes(32).toString('base64url'), state = randomBytes(16).toString('base64url')
+    secrets.add(verifier); secrets.add(state)
+    const listener = await startCallbackServer({ state, issuer: config.api, port, signal, timeoutMs: consentMs })
+    let reminder, launchTask
+    try {
+      const registration = await http.request(endpoints.registration_endpoint, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ client_name: 'Hirify CLI', redirect_uris: [listener.redirectUri] }) })
+      const client = requireJSON(registration)
+      if (!registration.ok || typeof client.client_id !== 'string' || !client.client_id) throw new CliError('oauth_registration', 'Could not start sign-in with this server.', { status: registration.status })
+      const url = new URL(endpoints.authorization_endpoint)
+      for (const [key, value] of Object.entries({ response_type: 'code', client_id: client.client_id, redirect_uri: listener.redirectUri, scope: endpoints.scopes, state, code_challenge: createHash('sha256').update(verifier).digest('base64url'), code_challenge_method: 'S256' })) url.searchParams.set(key, value)
+      // This intentional sign-in link belongs to the person, never to diagnostic events.
+      output.progress('Open this link to confirm access:')
+      output.progress(url.href, { secret: true })
+      output.progress('The browser must be able to reach the callback on this machine. Waiting for confirmation; press Ctrl+C to cancel.')
+      reminder = setInterval(() => output.progress('Still waiting for browser confirmation. Use the sign-in link above, or press Ctrl+C.'), 30000)
+      if (!noBrowser && info.canOpen) launchTask = openBrowser(url.href, { signal }).then(result => { event('browser', result); if (['launcher_missing', 'spawn_error', 'nonzero_exit'].includes(result.code)) output.progress('The browser launcher did not complete. Open the link above manually.') })
+      const answer = await listener.received
+      if (answer.error) throw new CliError(answer.error === 'access_denied' ? 'auth_denied' : 'oauth_error', 'Sign-in was not approved. Nothing was saved. Run hirify login again when ready.')
+      secrets.add(answer.code)
+      const res = await form(endpoints.token_endpoint, { grant_type: 'authorization_code', client_id: client.client_id, code: answer.code, redirect_uri: listener.redirectUri, code_verifier: verifier })
+      if (!res.ok) throw new CliError('oauth_exchange', 'The confirmation could not be exchanged. Run hirify login again.', { status: res.status })
+      const session = remember(tokenResponse(res.body, { kind: 'oauth', issuer: config.api, client_id: client.client_id, token_endpoint: endpoints.token_endpoint, scope: endpoints.scopes }))
+      aborted(signal)
+      await store.commit(session, generation)
+      return { signed_in: true, source: 'oauth', environment_override: Boolean(config.envKey) }
+    } finally { clearInterval(reminder); await listener.close(); await launchTask }
+  }
+  return { access, retryToken, login, refresh, discover, status: () => {
+    if (config.envKey) return { signed_in: true, source: 'environment', issuer: config.api }
+    const state = store.read({ allowPending: true })
+    return { signed_in: Boolean(state), source: state?.kind || 'none', issuer: state?.issuer || config.api, expires_at: state?.expires_at ?? null, renewal_uncertain: Boolean(state?.refresh_pending) }
+  } }
+}

package/bin/lib/browser.js

@@ -0,0 +1,34 @@
+import { spawn } from 'node:child_process'
+export function environment({ env = process.env, platform = process.platform, isTTY = Boolean(process.stdout.isTTY) } = {}) {
+  const remote = Boolean(env.SSH_CONNECTION || env.SSH_TTY)
+  const wsl = platform === 'linux' && Boolean(env.WSL_DISTRO_NAME || env.WSL_INTEROP)
+  const gui = platform !== 'linux' || Boolean(env.DISPLAY || env.WAYLAND_DISPLAY || wsl)
+  return { remote, wsl, interactive: isTTY, gui, canOpen: isTTY && !remote && gui }
+}
+export const canOpenBrowser = options => environment(options).canOpen
+/** A launcher acknowledgement is not proof that a browser window appeared. */
+export async function openBrowser(url, { waitMs = 1500, env = process.env, signal, launch } = {}) {
+  if (signal?.aborted) return { code: 'cancelled' }
+  let parsed
+  try { parsed = new URL(url) } catch { return { code: 'invalid_url' } }
+  if (parsed.username || parsed.password || (parsed.protocol !== 'https:' && !(parsed.protocol === 'http:' && ['127.0.0.1', '[::1]', 'localhost'].includes(parsed.hostname)))) return { code: 'invalid_url' }
+  let child
+  try {
+    if (launch) child = await launch(url)
+    else if (env.BROWSER) child = spawn(env.BROWSER, [url], { stdio: 'ignore', detached: true, windowsHide: true })
+    else { const { default: open } = await import('open'); child = await open(url) }
+  } catch { return { code: 'spawn_error' } }
+  return new Promise(resolve => {
+    let done = false
+    const finish = result => { if (done) return; done = true; clearTimeout(timer); signal?.removeEventListener('abort', cancel); child.off('error', error); child.on('error', () => {}); child.off('exit', exit); child.unref?.(); resolve(result) }
+    // Never terminate the user's browser on cancellation; only release our observation.
+    const cancel = () => finish({ code: 'cancelled' })
+    const error = e => finish({ code: e.code === 'ENOENT' ? 'launcher_missing' : 'spawn_error' })
+    const exit = code => finish({ code: code === 0 ? 'launcher_exited' : 'nonzero_exit' })
+    const timer = setTimeout(() => finish({ code: 'launcher_unconfirmed' }), waitMs)
+    child.once('error', error); child.once('exit', exit)
+    signal?.addEventListener('abort', cancel, { once: true })
+    if (child.exitCode !== null && child.exitCode !== undefined) exit(child.exitCode)
+    else if (signal?.aborted) cancel()
+  })
+}

package/bin/lib/cli.js

@@ -0,0 +1,126 @@
+import { CliError, redact, safeText } from './errors.js'
+const ARGUMENTS = { auth: '[<key>]', update: '[<version>]', 'vacancy search': '[<query>]', 'vacancy read': '<slug>', 'vacancy reveal': '<slug>', 'vacancy apply': '<slug>', 'feed show': '<id>', 'feed create': '<name>', 'feed deliver': '<id>', 'webhook create': '<name> <url>', 'feedback send': '<bug|feature> <title>', 'api call': '<capability>', 'capabilities show': '<capability>' }
+const GLOBAL = ['json', 'fields', 'error-format', 'debug', 'timeout', 'help']
+export const BOOLEAN_FLAGS = new Set(['json', 'debug', 'help', 'force', 'no-browser', 'stdin', 'telegram', 'no-telegram', 'no-webhook', 'check', 'rollback'])
+export const COMMANDS = {
+  intro: { args: [0, 0], description: 'what this can do, and in what order' },
+  version: { args: [0, 0], description: 'installed version' },
+  skill: { args: [0, 0], description: 'install the working rules for your agent' },
+  login: { args: [0, 0], flags: ['force', 'no-browser', 'callback-port'], description: 'sign in through your browser' },
+  logout: { args: [0, 0], description: 'sign out on this computer' },
+  auth: { args: [0, 1], flags: ['stdin'], description: 'save an API key; use --stdin to keep it out of shell history' },
+  'auth status': { args: [0, 0], description: 'show the local sign-in source without contacting the server' },
+  doctor: { args: [0, 0], description: 'show local diagnostic information without credentials' },
+  update: { args: [0, 1], flags: ['check', 'rollback'], description: 'check for an update or install an exact version' },
+  'account show': { args: [0, 0], description: 'your plan and allowances' },
+  'vacancy search': { args: [0, Infinity], flags: ['limit', 'page'], passthrough: true, description: 'search the board; server filter names are supported' },
+  'vacancy read': { args: [1, 1], description: 'read one vacancy in full; uses a vacancy open' },
+  'vacancy reveal': { args: [1, 1], description: 'get the contact or link to apply; uses a reveal' },
+  'vacancy apply': { args: [1, 1], flags: ['profile', 'cover', 'cover-file'], description: 'send a real application; ask the person first' },
+  'feed list': { args: [0, 0], description: 'your saved feeds' },
+  'feed show': { args: [1, 1], flags: ['limit', 'page'], description: 'vacancies in a feed' },
+  'feed create': { args: [1, 1], flags: ['filters', 'telegram', 'no-telegram', 'webhook'], description: 'save a search and its delivery settings' },
+  'feed deliver': { args: [1, 1], flags: ['telegram', 'no-telegram', 'webhook', 'no-webhook'], description: 'change delivery settings' },
+  'profile list': { args: [0, 0], description: 'profiles you can apply with' },
+  'webhook list': { args: [0, 0], description: 'your delivery endpoints' },
+  'webhook create': { args: [2, 2], description: 'create an endpoint: <name> <url>' },
+  'filter guide': { args: [0, 0], description: 'supported search filters, from the server' },
+  'feedback send': { args: [2, 2], flags: ['body', 'vacancy', 'idempotency-key'], description: 'send bug or feature feedback: <kind> <title> --body <text>' },
+  'api call': { args: [1, 1], flags: ['data', 'data-file'], description: 'invoke a capability with a JSON object of inputs' },
+  'capabilities list': { args: [0, 0], description: 'list the server capability catalogue' },
+  'capabilities show': { args: [1, 1], description: 'show the inputs, effects and metering of a capability' },
+}
+export const CLI_ONLY = new Set([...GLOBAL, 'data-file', 'cover-file'])
+export function tokenize(args) {
+  const words = [], options = new Map(); let literal = false
+  for (let i = 0; i < args.length; i++) {
+    let word = args[i]
+    if (literal) { words.push(word); continue }
+    if (word === '--') { literal = true; continue }
+    if (word === '-h') word = '--help'
+    if (word === '--version') { words.push('version'); continue }
+    if (!word.startsWith('--')) {
+      if (word.startsWith('-') && word !== '-') throw new CliError('invalid_arguments', `Unknown option: ${word}. Use -- before a value beginning with a hyphen.`)
+      words.push(word); continue
+    }
+    const at = word.indexOf('='); const name = word.slice(2, at < 0 ? undefined : at)
+    if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(name)) throw new CliError('invalid_arguments', 'Invalid option name.')
+    let value
+    if (BOOLEAN_FLAGS.has(name)) {
+      if (at >= 0) throw new CliError('invalid_arguments', `--${name} does not take a value.`)
+      value = true
+    } else {
+      value = at >= 0 ? word.slice(at + 1) : args[++i]
+      if (value === undefined || (at < 0 && value !== '-' && value.startsWith('-'))) throw new CliError('invalid_arguments', `--${name} requires a value. Use --${name}=<value> for a value beginning with a hyphen.`)
+    }
+    const values = options.get(name) || []; values.push(value); options.set(name, values)
+  }
+  return { words, options }
+}
+export const positional = args => tokenize(args).words
+export const flag = (args, name) => tokenize(args).options.get(name.replace(/^--/, ''))?.[0] ?? null
+export const options = args => new Map([...tokenize(args).options].map(([k, values]) => [k, values.join(',')]))
+export function parse(argv) {
+  // Help is resolved before parsing values, reading config or initializing effects.
+  const boundary = argv.indexOf('--'); const before = boundary < 0 ? argv : argv.slice(0, boundary)
+  if (!argv.length || before.some(x => ['--help', '-h'].includes(x)) || argv[0] === 'help') return { help: true, topic: argv.filter(x => !x.startsWith('-')).slice(0, 2).join(' ') }
+  const parsed = tokenize(argv)
+  let name = parsed.words[0]
+  if (Object.hasOwn(COMMANDS, `${name} ${parsed.words[1]}`)) name += ` ${parsed.words[1]}`
+  const spec = Object.hasOwn(COMMANDS, name) ? COMMANDS[name] : null
+  if (!spec) {
+    const verbs = Object.keys(COMMANDS).filter(x => x.startsWith(`${name} `)).map(x => x.split(' ')[1])
+    throw new CliError('invalid_arguments', verbs.length ? `${parsed.words[1] ? `hirify ${name} has no verb "${parsed.words[1]}".\n` : ''}hirify ${name} takes a verb: ${verbs.join(', ')}` : `unknown command: ${name}. Run hirify --help.`)
+  }
+  const words = parsed.words.slice(name.split(' ').length)
+  if (words.length < spec.args[0] || words.length > spec.args[1]) throw new CliError('invalid_arguments', `hirify ${name} needs ${spec.args[0] === spec.args[1] ? spec.args[0] : `${spec.args[0]} to ${spec.args[1]}`} argument(s). Run hirify ${name} --help.`)
+  const known = new Set([...GLOBAL, ...(spec.flags || [])])
+  for (const [key, values] of parsed.options) {
+    if (!known.has(key) && !spec.passthrough) throw new CliError('invalid_arguments', `Unknown option for ${name}: --${key}.`)
+    if (known.has(key) && values.length > 1) throw new CliError('invalid_arguments', `--${key} can be given only once.`)
+  }
+  const value = key => parsed.options.get(key)?.[0]
+  for (const [a, b] of [['telegram', 'no-telegram'], ['webhook', 'no-webhook'], ['cover', 'cover-file'], ['data', 'data-file']]) if (parsed.options.has(a) && parsed.options.has(b)) throw new CliError('invalid_arguments', `Choose either --${a} or --${b}.`)
+  for (const key of ['limit', 'page', 'profile', 'webhook', 'callback-port', 'timeout']) {
+    if (value(key) !== undefined && (!/^\d+$/.test(value(key)) || !Number.isSafeInteger(Number(value(key))) || Number(value(key)) < 1 || (key === 'callback-port' && Number(value(key)) > 65535) || (key === 'timeout' && Number(value(key)) > 3600))) throw new CliError('invalid_arguments', `--${key} requires a positive whole number${key === 'callback-port' ? ' up to 65535' : ''}.`)
+  }
+  for (const key of ['filters', 'data']) if (value(key) !== undefined) {
+    let obj; try { obj = JSON.parse(value(key)) } catch { throw new CliError('invalid_arguments', `--${key} expects JSON.`) }
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) throw new CliError('invalid_arguments', `--${key} expects a JSON object.`)
+  }
+  if (parsed.options.has('error-format') && !['json', 'text'].includes(value('error-format'))) throw new CliError('invalid_arguments', '--error-format must be json or text.')
+  if (name === 'update' && value('rollback') && (words.length || value('check'))) throw new CliError('invalid_arguments', 'Use --rollback by itself.')
+  if (name === 'auth' && Boolean(words.length) === Boolean(value('stdin'))) throw new CliError('invalid_arguments', 'Use hirify auth <key> or hirify auth --stdin.')
+  if (name === 'feed deliver' && !['telegram', 'no-telegram', 'webhook', 'no-webhook'].some(key => parsed.options.has(key))) throw new CliError('invalid_arguments', 'Choose at least one delivery setting: --telegram, --no-telegram, --webhook or --no-webhook.')
+  if (name === 'auth' && words.length && (!words[0].trim() || /[\r\n]/.test(words[0]))) throw new CliError('invalid_arguments', 'The key must be nonempty and contain no line breaks.')
+  if (name === 'feedback send' && (!['bug', 'feature'].includes(words[0]) || !value('body'))) throw new CliError('invalid_arguments', 'Use hirify feedback send bug|feature <title> --body <text>.')
+  const args = [...parsed.options].flatMap(([key, values]) => values.map(v => v === true ? `--${key}` : `--${key}=${v}`))
+  return { name, words, args, values: Object.fromEntries([...parsed.options].map(([k, v]) => [k, v[0]])), json: Boolean(value('json')), errorJSON: value('error-format') === 'json', timeout: Number(value('timeout') || (name === 'login' ? 360 : name === 'update' ? 300 : 30)) * 1000 }
+}
+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.\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.\nRules for your agent: npx skills add hirifyme/hirify-cli\n`
+}
+export function createOutput({ stdout = process.stdout, stderr = process.stderr, json = false, errorJSON = false, secrets = new Set() } = {}) {
+  let closed = false
+  const errors = []
+  const onError = error => { if (error.code === 'EPIPE') closed = true; else errors.push(error) }
+  stdout.on('error', onError); stderr.on('error', onError)
+  const write = (stream, value, secret = false) => { if (!closed) stream.write((secret ? safeText(value) : redact(value, [...secrets])) + '\n') }
+  const output = {
+    jsonMode: json, errorJSON,
+    console: { log: (...v) => write(stdout, v.map(String).join(' ')), error: (...v) => write(stderr, v.map(String).join(' ')) },
+    json: value => { if (!closed) stdout.write(JSON.stringify(value, (_key, item) => typeof item === 'string' ? redact(item, [...secrets], false) : item, 2) + '\n') },
+    dispose: () => { stdout.off('error', onError); stderr.off('error', onError) },
+    progress: (value, { secret = false } = {}) => write(stderr, value, secret),
+    error: error => {
+      const e = error instanceof CliError ? error : new CliError('internal_error', 'The command could not complete. Run hirify doctor and include its output when contacting support.')
+      const payload = { schema_version: 1, error: { code: e.code, message: redact(e.message, [...secrets]), retryable: e.retryable, ...(e.status ? { status: e.status } : {}), ...(e.requestId ? { request_id: safeText(e.requestId).slice(0, 128) } : {}) } }
+      if (errorJSON) { if (!closed) stderr.write(JSON.stringify(payload, (_key, item) => typeof item === 'string' ? redact(item, [...secrets], false) : item) + '\n') }
+      else write(stderr, `hirify: ${payload.error.message}`)
+      return e.exitCode
+    },
+    flush: async () => { if (!closed) await Promise.all([stdout, stderr].map(stream => new Promise(resolve => stream.write('', resolve)))); if (errors.length) throw errors[0] },
+  }
+  return output
+}