hirify-cli 0.4.7 → 0.5.0

package/bin/lib/config.js

@@ -0,0 +1,27 @@
+import { homedir } from 'node:os'
+import { isAbsolute, join } from 'node:path'
+import { CliError } from './errors.js'
+export const DEFAULT_API = 'https://api.hirify.me'
+export function serverURL(input) {
+  let url
+  try { url = new URL(input) } catch { throw new CliError('invalid_url', 'The server address is not a valid URL.') }
+  if (url.username || url.password || url.hash || url.search) throw new CliError('invalid_url', 'The server address must not contain credentials, a query, or a fragment.')
+  const loopback = ['127.0.0.1', '[::1]', 'localhost'].includes(url.hostname)
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) throw new CliError('insecure_url', 'Use an HTTPS server address. HTTP is supported only for local loopback servers.')
+  if (url.pathname !== '/') throw new CliError('invalid_url', 'HIRIFY_API must be an origin without a path.')
+  return url.origin
+}
+export function resolveConfig(env = process.env) {
+  const base = env.XDG_CONFIG_HOME || join(homedir(), '.config')
+  if (!isAbsolute(base)) throw new CliError('config_path', 'XDG_CONFIG_HOME must be an absolute path.')
+  const api = serverURL(env.HIRIFY_API || DEFAULT_API)
+  return { api, dir: join(base, 'hirify'), envKey: env.HIRIFY_KEY || '', env, version: null }
+}
+export function trustedURL(input, origin, { path = false } = {}) {
+  if (typeof input !== 'string' || !input || /[\s\\]/.test(input)) throw new CliError('untrusted_url', 'Hirify returned an invalid address.')
+  if (path && (!input.startsWith('/') || input.startsWith('//'))) throw new CliError('untrusted_url', 'Hirify returned an invalid operation path.')
+  let url
+  try { url = new URL(input, origin) } catch { throw new CliError('untrusted_url', 'Hirify returned an invalid address.') }
+  if (url.origin !== origin || url.username || url.password || url.hash) throw new CliError('untrusted_url', 'Hirify returned an address outside the selected server. No credentials were sent there.')
+  return url.href
+}

package/bin/lib/errors.js

@@ -0,0 +1,20 @@
+/** Errors carry a stable machine code; only the entrypoint decides how to exit. */
+export class CliError extends Error {
+  constructor(code, message, { exitCode = 1, status, retryable = false, requestId, action } = {}) {
+    super(message)
+    this.name = 'CliError'
+    Object.assign(this, { code, exitCode, status, retryable, requestId, action })
+  }
+}
+export function fail(message, exitCode = 1) { throw new CliError('command_failed', message, { exitCode }) }
+export function aborted(signal) {
+  if (signal?.aborted) throw signal.reason instanceof CliError ? signal.reason : new CliError('cancelled', 'The command was cancelled.', { exitCode: 130 })
+}
+export function safeText(value) {
+  return String(value).replace(/\x1b\][^\x07]*(?:\x07|\x1b\\)/g, '').replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '').replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, '')
+}
+export function redact(value, secrets = [], terminal = true) {
+  let text = terminal ? safeText(value) : String(value)
+  for (const secret of secrets) if (typeof secret === 'string' && secret.length) text = text.split(secret).join('[redacted]')
+  return text.replace(/\b(Bearer\s+)[^\s"']+/gi, '$1[redacted]').replace(/(https?:\/\/)[^\s/@]+:[^\s/@]+@/g, '$1[redacted]@')
+}

package/bin/lib/http.js

@@ -0,0 +1,113 @@
+import http from 'node:http'
+import https from 'node:https'
+import { HttpProxyAgent } from 'http-proxy-agent'
+import { HttpsProxyAgent } from 'https-proxy-agent'
+import proxyEnv from 'proxy-from-env'
+import { CliError, aborted } from './errors.js'
+
+export function retryDelay(value, now = Date.now()) {
+  if (!value) return 0
+  const seconds = Number(value)
+  return Number.isFinite(seconds) ? Math.max(0, seconds * 1000) : Math.max(0, Date.parse(value) - now) || 0
+}
+export function delay(ms, signal) {
+  aborted(signal)
+  return new Promise((resolve, reject) => {
+    const finish = () => { clearTimeout(timer); signal?.removeEventListener('abort', cancel); resolve() }
+    const cancel = () => { clearTimeout(timer); signal?.removeEventListener('abort', cancel); reject(signal.reason) }
+    const timer = setTimeout(finish, ms)
+    signal?.addEventListener('abort', cancel, { once: true })
+  })
+}
+export function createHttp({ signal, version, event = () => {}, timeoutMs = 30000, limit = 8 * 1024 * 1024 }) {
+  const active = new Set()
+  async function once(input, { method = 'GET', headers = {}, body, timeout = timeoutMs, maxBytes = limit } = {}) {
+    aborted(signal)
+    const url = new URL(input)
+    const started = Date.now()
+    if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password) throw new CliError('untrusted_url', 'Unsupported request address.')
+    let agent
+    const proxy = proxyEnv.getProxyForUrl(url.href)
+    if (proxy) {
+      let p
+      try { p = new URL(proxy) } catch { throw new CliError('proxy_config', 'The proxy address is invalid.') }
+      if (!['http:', 'https:'].includes(p.protocol)) throw new CliError('proxy_config', 'Use an HTTP or HTTPS proxy.')
+      agent = url.protocol === 'https:' ? new HttpsProxyAgent(p, { rejectUnauthorized: true }) : new HttpProxyAgent(p, { rejectUnauthorized: true })
+    }
+    return new Promise((resolve, reject) => {
+      let settled = false
+      let req
+      const finish = (error, result) => {
+        if (settled) return
+        settled = true
+        clearTimeout(timer)
+        signal?.removeEventListener('abort', cancel)
+        if (req) active.delete(req)
+        agent?.destroy()
+        event('http', { code: error?.code || 'response', status: result?.status, duration_ms: Date.now() - started })
+        if (error) reject(error); else resolve(result)
+      }
+      const cancel = () => { req?.destroy(); finish(signal.reason || new CliError('cancelled', 'The command was cancelled.', { exitCode: 130 })) }
+      const timer = setTimeout(() => { req?.destroy(); finish(new CliError('network_timeout', 'The server did not answer in time.', { retryable: method === 'GET' })) }, timeout)
+      signal?.addEventListener('abort', cancel, { once: true })
+      try {
+        req = (url.protocol === 'https:' ? https : http).request(url, {
+          method, agent, rejectUnauthorized: true,
+          headers: { Accept: 'application/json', 'User-Agent': `hirify-cli/${version}`, 'Accept-Encoding': 'identity', ...headers },
+        }, res => {
+          const chunks = []; let size = 0
+          res.on('data', chunk => {
+            size += chunk.length
+            if (size > maxBytes) { req.destroy(); finish(new CliError('response_too_large', 'The server response exceeded the supported size.')) }
+            else chunks.push(chunk)
+          })
+          res.on('error', () => finish(new CliError('response_incomplete', 'The connection ended before the response was complete.')))
+          res.on('end', () => {
+            const status = res.statusCode
+            const headers = new Headers()
+            for (const [key, value] of Object.entries(res.headers)) if (value !== undefined) headers.set(key, Array.isArray(value) ? value.join(', ') : value)
+            if (status >= 300 && status < 400) return finish(new CliError('redirect_refused', 'The server redirected this request. No credentials were forwarded.', { status }))
+            const text = Buffer.concat(chunks).toString('utf8')
+            let body = null
+            try { body = JSON.parse(text) } catch {}
+            finish(null, { status, ok: status >= 200 && status < 300, headers, text, body })
+          })
+        })
+        active.add(req)
+        req.on('error', error => {
+          const c = error.code || error.cause?.code
+          const code = /CERT|TLS|SSL|SELF_SIGNED|UNABLE_TO_VERIFY/.test(c || '') ? 'tls_error' : proxy ? 'proxy_error' : c === 'ENOTFOUND' || c === 'EAI_AGAIN' ? 'dns_error' : 'network_error'
+          finish(new CliError(code, code === 'tls_error' ? 'The TLS certificate could not be verified. Check your trusted CA configuration.' : 'Could not reach the server. Check your connection and proxy settings.', { retryable: method === 'GET' }))
+        })
+        if (signal?.aborted) return cancel()
+        req.end(body)
+      } catch { finish(new CliError('network_error', 'Could not start the request. Check your server and proxy settings.')) }
+    })
+  }
+  async function request(url, options = {}) {
+    const attempts = options.safe ? 3 : 1
+    for (let i = 0; i < attempts; i++) {
+      try {
+        const res = await once(url, options)
+        if (i + 1 < attempts && [429, 502, 503, 504].includes(res.status)) {
+          const wait = retryDelay(res.headers.get('retry-after')) || (100 * 2 ** i + Math.random() * 100)
+          if (wait <= 2000) { await delay(wait, signal); continue }
+        }
+        return res
+      } catch (error) {
+        if (i + 1 >= attempts || !['network_error', 'dns_error'].includes(error.code)) throw error
+        await delay(100 * 2 ** i + Math.random() * 100, signal)
+      }
+    }
+  }
+  return { request, close: () => { for (const req of active) req.destroy(); active.clear() } }
+}
+export function requireJSON(response, { mutation = false } = {}) {
+  const type = response.headers.get('content-type') || ''
+  if (!/\b(?:application\/json|application\/[\w.+-]+\+json)\b/i.test(type) || response.body === null || typeof response.body !== 'object') {
+    throw new CliError(mutation ? 'outcome_unknown' : 'protocol_error', mutation
+      ? 'The server did not return a readable confirmation. The action may have completed. Check its result before trying again.'
+      : 'The server returned an unreadable response.', { status: response.status })
+  }
+  return response.body
+}

package/bin/lib/input.js

@@ -0,0 +1,39 @@
+import { readFileSync, statSync } from 'node:fs'
+import { CliError, aborted } from './errors.js'
+const LIMIT = 1024 * 1024
+function decodeInput(bytes) {
+  try { return new TextDecoder('utf-8', { fatal: true }).decode(bytes) }
+  catch { throw new CliError('input_encoding', 'Input must be UTF-8 text. Save the file as UTF-8 before retrying.') }
+}
+async function readInput(path, signal) {
+  aborted(signal)
+  if (path !== '-') {
+    try { if (!statSync(path).isFile() || statSync(path).size > LIMIT) throw new Error(); return decodeInput(readFileSync(path)) }
+    catch (error) { if (error instanceof CliError) throw error; throw new CliError('input_file', 'Could not read the input file. Use a regular UTF-8 file no larger than 1 MiB.') }
+  }
+  if (process.stdin.isTTY) throw new CliError('interaction_required', 'Pipe the input to stdin, or use a file path.')
+  return new Promise((resolve, reject) => {
+    const chunks = []; let size = 0
+    const clean = () => { process.stdin.off('data', data); process.stdin.off('end', end); process.stdin.off('error', error); signal?.removeEventListener('abort', cancel); process.stdin.pause() }
+    const error = () => { clean(); reject(new CliError('input_file', 'Could not read standard input.')) }
+    const data = chunk => { size += chunk.length; if (size > LIMIT) { clean(); reject(new CliError('input_too_large', 'Standard input exceeds 1 MiB.')) } else chunks.push(chunk) }
+    const end = () => { clean(); try { resolve(decodeInput(Buffer.concat(chunks))) } catch (error) { reject(error) } }
+    const cancel = () => { clean(); reject(signal.reason) }
+    process.stdin.on('data', data); process.stdin.once('end', end); process.stdin.once('error', error); signal?.addEventListener('abort', cancel, { once: true })
+    if (signal?.aborted) cancel()
+  })
+}
+export async function prepareInput(command, signal) {
+  for (const [source, target] of [['data-file', 'data'], ['cover-file', 'cover']]) {
+    if (command.values[source] !== undefined) {
+      const text = await readInput(command.values[source], signal)
+      if (target === 'data') {
+        let data; try { data = JSON.parse(text) } catch { throw new CliError('invalid_arguments', 'The input file must contain a JSON object.') }
+        if (!data || typeof data !== 'object' || Array.isArray(data)) throw new CliError('invalid_arguments', 'The input file must contain a JSON object.')
+      }
+      command.args = command.args.filter(v => !v.startsWith(`--${source}=`)); command.args.push(`--${target}=${text}`)
+    }
+  }
+  if (command.name === 'auth' && command.values.stdin) command.words = [(await readInput('-', signal)).trim()]
+  if (command.name === 'auth' && (!command.words[0]?.trim() || /[\r\n]/.test(command.words[0]))) throw new CliError('invalid_arguments', 'Provide one nonempty API key.')
+}

package/bin/lib/loopback.js

@@ -0,0 +1,65 @@
+import { createServer } from 'node:http'
+import { timingSafeEqual } from 'node:crypto'
+import { CliError, aborted } from './errors.js'
+
+export async function startCallbackServer({ state, issuer, port = 0, signal, timeoutMs = 300000, serverFactory = createServer }) {
+  aborted(signal)
+  let settle, reject, settled = false, closePromise
+  const sockets = new Set()
+  const received = new Promise((resolve, fail) => { settle = resolve; reject = fail })
+  // The consumer may still be registering the public client when cancellation arrives.
+  received.catch(() => {})
+  let address
+  const server = serverFactory({ maxHeaderSize: 8192 }, (req, res) => {
+    const reply = (status, text, html = false) => {
+      res.writeHead(status, { 'Content-Type': html ? 'text/html; charset=utf-8' : 'text/plain; charset=utf-8', 'Cache-Control': 'no-store', 'Content-Security-Policy': "default-src 'none'", 'Referrer-Policy': 'no-referrer', Connection: 'close' })
+      res.end(text)
+    }
+    let url
+    try { url = new URL(req.url, address) } catch { return reply(400, 'Invalid request.') }
+    if (req.method !== 'GET') return reply(405, 'Use GET.')
+    if (!req.url.startsWith('/') || url.origin !== new URL(address).origin || req.headers.host !== new URL(address).host) return reply(400, 'Invalid callback address.')
+    if (url.pathname !== '/callback') return reply(404, 'Not found.')
+    const params = url.searchParams
+    const value = params.get('state') || ''
+    const validState = Buffer.byteLength(value) === Buffer.byteLength(state) && timingSafeEqual(Buffer.from(value), Buffer.from(state))
+    const code = params.get('code'), error = params.get('error')
+    if (settled || !validState || params.getAll('state').length !== 1 || params.getAll('code').length > 1 || params.getAll('error').length > 1 || Boolean(code) === Boolean(error) || (params.has('iss') && (params.getAll('iss').length !== 1 || params.get('iss') !== issuer))) return reply(400, 'This callback does not match the pending sign-in.')
+    settled = true
+    reply(200, '<!doctype html><html lang="en"><meta charset="utf-8"><title>Hirify</title><h1>Confirmation received</h1><p>Return to your terminal to see the sign-in result.</p></html>', true)
+    settle({ code, error })
+  })
+  server.requestTimeout = 5000
+  server.headersTimeout = 5000
+  server.keepAliveTimeout = 1000
+  server.on('connection', socket => { sockets.add(socket); socket.on('close', () => sockets.delete(socket)); socket.setTimeout(5000, () => socket.destroy()) })
+  server.on('clientError', (_, socket) => socket.destroy())
+  const listen = host => new Promise((resolve, fail) => {
+    const error = e => { server.off('listening', ready); fail(e) }
+    const ready = () => { server.off('error', error); resolve() }
+    server.once('error', error); server.once('listening', ready); server.listen(port, host)
+  })
+  let host = '127.0.0.1'
+  try { await listen(host) } catch (e) {
+    if (!['EADDRNOTAVAIL', 'EAFNOSUPPORT'].includes(e.code)) throw new CliError('callback_bind_failed', 'Could not listen for the browser callback. Choose another --callback-port or use an API key.')
+    host = '::1'
+    try { await listen(host) } catch { throw new CliError('callback_bind_failed', 'No loopback address is available. Use HIRIFY_KEY instead.') }
+  }
+  address = `http://${host === '::1' ? '[::1]' : host}:${server.address().port}`
+  const close = () => {
+    if (closePromise) return closePromise
+    clearTimeout(timer); signal?.removeEventListener('abort', cancel)
+    closePromise = new Promise(resolve => {
+      const force = setTimeout(() => { for (const socket of sockets) socket.destroy() }, 200)
+      server.close(() => { clearTimeout(force); resolve() })
+      server.closeIdleConnections?.()
+    })
+    return closePromise
+  }
+  const cancel = () => { if (!settled) { settled = true; reject(signal.reason || new CliError('cancelled', 'Sign-in was cancelled.', { exitCode: 130 })) }; void close() }
+  const timer = setTimeout(() => { if (!settled) { settled = true; reject(new CliError('login_timeout', 'No matching browser confirmation arrived in time. Run hirify login again.')) }; void close() }, timeoutMs)
+  server.on('error', () => { if (!settled) { settled = true; reject(new CliError('callback_error', 'The local callback server stopped. Run hirify login again.')) }; void close() })
+  signal?.addEventListener('abort', cancel, { once: true })
+  if (signal?.aborted) cancel()
+  return { redirectUri: `${address}/callback`, received, close }
+}

package/bin/lib/main.js

@@ -0,0 +1,103 @@
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { parse, help, createOutput } from './cli.js'
+import { CliError } from './errors.js'
+const ownRoot = dirname(dirname(dirname(fileURLToPath(import.meta.url))))
+
+export async function main(argv = process.argv.slice(2), { baseRoot = ownRoot, baseVersion, selected = false, skipUpdate = false } = {}) {
+  let command
+  let output = createOutput({ errorJSON: argv.includes('--error-format=json') || argv.some((x, i) => x === '--error-format' && argv[i + 1] === 'json') })
+  let cleanup = async () => {}
+  let next
+  let exitCode = 0
+  try {
+    command = parse(argv)
+    if (command.help) { output.console.log(help(command.topic)); await output.flush(); return 0 }
+    const pkg = JSON.parse(readFileSync(join(ownRoot, 'package.json'), 'utf8'))
+    baseVersion ||= pkg.version
+    const { resolveConfig } = await import('./config.js')
+    // A broken configuration must not make the offline version command unavailable.
+    let config
+    try { config = resolveConfig() } catch (error) { if (command.name !== 'version') throw error; config = { dir: '', env: process.env, api: '' } }
+    config.version = pkg.version
+    const { createUpdater, activeInstallation } = await import('./update.js')
+    if (!selected && config.dir) {
+      const active = activeInstallation(config.dir, baseRoot, baseVersion, config.env.HIRIFY_VERSION_PIN)
+      if (active && active.root !== ownRoot) {
+        const module = await import(pathToFileURL(join(active.root, 'bin', 'lib', 'main.js')).href)
+        return await module.main(argv, { baseRoot, baseVersion, selected: true, skipUpdate })
+      }
+    }
+    if (config.env.HIRIFY_VERSION_PIN && config.env.HIRIFY_VERSION_PIN !== pkg.version && command.name !== 'update') throw new CliError('version_pin_unavailable', 'The pinned CLI version is not active. Run hirify update <exact-version> or install that exact npm version.')
+    if (command.name === 'version') { if (command.json) output.json({ version: pkg.version }); else output.console.log(pkg.version); await output.flush(); return 0 }
+    const controller = new AbortController()
+    const signal = controller.signal
+    const interrupt = () => controller.abort(new CliError('cancelled', 'The command was cancelled.', { exitCode: 130 }))
+    const terminate = () => controller.abort(new CliError('cancelled', 'The command was terminated.', { exitCode: 143 }))
+    process.once('SIGINT', interrupt); process.once('SIGTERM', terminate)
+    const timer = setTimeout(() => controller.abort(new CliError('command_timeout', 'The command deadline was reached. Use --timeout <seconds> if more time is needed.')), command.timeout)
+    cleanup = async () => { clearTimeout(timer); process.off('SIGINT', interrupt); process.off('SIGTERM', terminate) }
+    const secrets = new Set([config.envKey].filter(Boolean))
+    output.dispose()
+    output = createOutput({ json: command.json, errorJSON: command.errorJSON, secrets })
+    const events = []
+    const event = (phase, data = {}) => {
+      const item = { phase, code: data.code || 'unknown', ...(Number.isInteger(data.status) ? { status: data.status } : {}), ...(Number.isFinite(data.duration_ms) ? { duration_ms: data.duration_ms } : {}) }
+      if (events.length < 100) events.push(item)
+      if (command.values.debug || config.env.HIRIFY_DEBUG) output.progress(JSON.stringify(item))
+    }
+    const [{ createHttp }, { createStore }, { createAuth }, { createApi }, { createCommands }, { prepareInput }] = await Promise.all([import('./http.js'), import('./store.js'), import('./auth.js'), import('./api.js'), import('./commands.js'), import('./input.js')])
+    const http = createHttp({ signal, version: pkg.version, event })
+    cleanup = async () => { clearTimeout(timer); process.off('SIGINT', interrupt); process.off('SIGTERM', terminate); http.close() }
+    await prepareInput(command, signal)
+    const store = createStore(config, { signal })
+    const auth = createAuth({ config, store, http, signal, output, event, secrets })
+    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', 'skill', 'update'].includes(command.name)
+    if (!skipUpdate && !local) next = await updater.automatic()
+    if (next) {
+      // Dispose every timer and signal handler before handing off, at most once per invocation.
+    } else if (command.name === 'login') {
+      const result = await auth.login({ force: Boolean(command.values.force), noBrowser: Boolean(command.values['no-browser']), port: Number(command.values['callback-port'] || 0), consentMs: Math.min(command.timeout, 300000) })
+      if (command.json) output.json(result)
+      else { output.console.log(result.already_signed_in ? 'Already signed in. Use hirify login --force to sign in again.' : 'Signed in. Access saved on this computer.'); if (result.environment_override || result.source === 'environment') output.progress('HIRIFY_KEY is set and takes precedence over the saved sign-in.'); output.console.log('Your plan and allowances: hirify account show') }
+    } else if (command.name === 'auth') {
+      secrets.add(command.words[0])
+      await store.commit({ kind: 'key', access_token: command.words[0] })
+      if (command.json) output.json({ signed_in: true, source: 'key', environment_override: Boolean(config.envKey) })
+      else output.console.log('Key saved on this computer.')
+      if (config.envKey) output.progress('HIRIFY_KEY is set and takes precedence over the saved key.')
+    } else if (command.name === 'logout') {
+      const had = await store.logout()
+      if (command.json) output.json({ signed_out: true, environment_override: Boolean(config.envKey) })
+      else output.console.log(had ? 'Signed out on this computer.' : 'Nobody is signed in here.')
+      if (config.envKey) output.progress('HIRIFY_KEY is still set. Remove it from the environment to stop using that key.')
+    } else if (command.name === 'auth status') {
+      const status = auth.status()
+      if (command.json) output.json(status); else output.console.log(`Sign-in source: ${status.source}\nServer: ${status.issuer}${status.renewal_uncertain ? '\nRenewal needs a new sign-in: hirify login --force' : ''}`)
+    } else if (command.name === 'doctor') {
+      const { environment } = await import('./browser.js')
+      let status
+      try { status = auth.status() } catch (error) { status = { error: error.code } }
+      const info = { schema_version: 1, cli_version: pkg.version, node: process.version, platform: process.platform, architecture: process.arch, server: config.api, config_source: config.env.XDG_CONFIG_HOME ? 'XDG_CONFIG_HOME' : 'home', auth: status, environment: environment(), proxy_configured: Boolean(config.env.HTTPS_PROXY || config.env.https_proxy || config.env.HTTP_PROXY || config.env.http_proxy), custom_ca: Boolean(config.env.NODE_EXTRA_CA_CERTS), auto_update_disabled: config.env.HIRIFY_NO_AUTO_UPDATE === '1', managed_version: ownRoot !== baseRoot, installation: await updater.installation() }
+      output.json(info)
+    } else if (command.name === 'update') {
+      if (command.values.rollback) { const result = await updater.rollback(); output.json(result); return 0 }
+      const target = await updater.check(command.words[0] || config.env.HIRIFY_VERSION_PIN || 'latest')
+      if (command.values.check) output.json({ current: pkg.version, ...target, integrity: undefined, registry: undefined, installation: await updater.installation() })
+      else { const result = await updater.install(target, { pin: Boolean(command.words[0] || config.env.HIRIFY_VERSION_PIN) }); if (command.json) output.json(result); else output.console.log(`Hirify CLI ${result.version} is ready for the next command.${result.pinned ? ' This version is pinned.' : ''}`) }
+    } else {
+      const commands = createCommands({ api, output, config, signal, event, fields: command.values.fields })
+      if (command.name === 'skill' && command.json) output.json({ install: 'npx skills add hirifyme/hirify-cli' })
+      else await commands[command.name](command.args, command.words)
+    }
+  } catch (error) { exitCode = output.error(error) }
+  finally { await cleanup(); await output.flush().catch(() => { exitCode = 1 }); output.dispose() }
+  if (next) {
+    const module = await import(pathToFileURL(join(next.root, 'bin', 'lib', 'main.js')).href)
+    return module.main(argv, { baseRoot, baseVersion, selected: true, skipUpdate: true })
+  }
+  return exitCode
+}

package/bin/lib/messages.js

@@ -0,0 +1,62 @@
+export function serverMessage(body) {
+  const firstLine = (value) => {
+    if (typeof value === 'string' && value.trim()) return value.trim()
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        const line = firstLine(item)
+        if (line) return line
+      }
+    }
+    if (value && typeof value === 'object') {
+      for (const item of Object.values(value)) {
+        const line = firstLine(item)
+        if (line) return line
+      }
+    }
+    return null
+  }
+
+  return firstLine(body?.error?.details) || firstLine(body?.error?.message) || firstLine(body?.message)
+}
+
+/**
+ * The one-line report for a policy restriction: a canonical 403 that names itself
+ * `access_restricted`. It is kept apart from the quota and rate-limit walls on purpose,
+ * because those clear on their own and this one does not. The CLI states what the server
+ * sent - the message it wrote, when the restriction lifts, where to ask for a review - and
+ * adds no rule of its own about why it was applied.
+ */
+export function accessRestrictedMessage(body) {
+  const err = (body && typeof body.error === 'object' && body.error) || {}
+  const line = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null)
+  const parts = [line(err.message) || line(body?.message) || 'access on this account is restricted (403).']
+  const until = line(err.restricted_until)
+  if (until) parts.push(`It stays in place until ${until}.`)
+  const appeal = line(err.appeal_url)
+  if (appeal) parts.push(`To ask us to look at it again: ${appeal}`)
+  return parts.join('\n        ')
+}
+
+/**
+ * The report for a blocking notice: a canonical 409 that names itself `action_required`.
+ * Unlike a `meta.notice` on a success, this one stands in place of the answer - the server is
+ * holding the result until the person confirms - so the CLI shows the text the server wrote and
+ * the one command that clears it, and reads nothing into the policy behind it. That command is
+ * the acknowledgement capability the server lists in its manifest, reached the same way as any
+ * other, so no route to it is written here. It carries the notice's own id and its first
+ * advertised action, both as the server sent them, so the printed line runs as it stands.
+ */
+export function actionRequiredMessage(body) {
+  const notice = (body && typeof body.error === 'object' && body.error && typeof body.error.notice === 'object' && body.error.notice) || {}
+  const line = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null)
+  const parts = [line(notice.message) || 'this needs your confirmation before it can go ahead (409).']
+
+  const id = line(notice.id)
+  const action = Array.isArray(notice.actions) ? notice.actions.map(line).find(Boolean) : null
+  const call = 'hirify api call security.notices.ack'
+  parts.push(id && action
+    ? `To continue, save this JSON to a file and run ${call} --data-file <file>:\n${JSON.stringify({ id, action })}`
+    : `To continue, acknowledge this notice: ${call}`)
+  return parts.join('\n        ')
+}
+

package/bin/lib/store.js

@@ -0,0 +1,118 @@
+import { mkdirSync, lstatSync, readFileSync, openSync, writeFileSync, fsyncSync, closeSync, renameSync, unlinkSync, chmodSync } from 'node:fs'
+import { join } from 'node:path'
+import { randomUUID, createHash } from 'node:crypto'
+import { execFile } from 'node:child_process'
+import lockfile from 'proper-lockfile'
+import { CliError, aborted } from './errors.js'
+import { DEFAULT_API, serverURL } from './config.js'
+import { delay } from './http.js'
+
+function stat(path) { try { return lstatSync(path) } catch (e) { if (e.code === 'ENOENT') return null; throw e } }
+function check(path, directory = false) {
+  const s = stat(path)
+  if (!s) return null
+  if (s.isSymbolicLink() || (directory ? !s.isDirectory() : !s.isFile())) throw new CliError('unsafe_storage', 'The credential location must be a regular file in a private directory, not a link.')
+  if (process.platform !== 'win32' && s.uid !== process.getuid()) throw new CliError('unsafe_storage', 'The credential location belongs to another user.')
+  return s
+}
+export async function makePrivate(path, directory = false, signal) {
+  aborted(signal)
+  check(path, directory)
+  if (process.platform !== 'win32') { chmodSync(path, directory ? 0o700 : 0o600); return }
+  // Set an exact DACL for the current SID; POSIX mode bits do not secure Windows files.
+  // Use .NET directly: PowerShell 7 can pass a module path incompatible with Windows PowerShell.
+  const script = `$ErrorActionPreference='Stop'; $sid=[System.Security.Principal.WindowsIdentity]::GetCurrent().User; $p=$env:HIRIFY_SECURE_PATH; $d=[System.IO.Directory]::Exists($p); if($d){$acl=[System.Security.AccessControl.DirectorySecurity]::new(); $rule=[System.Security.AccessControl.FileSystemAccessRule]::new($sid,[System.Security.AccessControl.FileSystemRights]::FullControl,[System.Security.AccessControl.InheritanceFlags]'ContainerInherit,ObjectInherit',[System.Security.AccessControl.PropagationFlags]::None,[System.Security.AccessControl.AccessControlType]::Allow)}else{$acl=[System.Security.AccessControl.FileSecurity]::new(); $rule=[System.Security.AccessControl.FileSystemAccessRule]::new($sid,[System.Security.AccessControl.FileSystemRights]::FullControl,[System.Security.AccessControl.AccessControlType]::Allow)}; $acl.SetOwner($sid); $acl.SetAccessRuleProtection($true,$false); $acl.AddAccessRule($rule); if($d){[System.IO.Directory]::SetAccessControl($p,$acl)}else{[System.IO.File]::SetAccessControl($p,$acl)}`
+  await new Promise((resolve, reject) => execFile('powershell.exe', ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64')], { env: { ...process.env, HIRIFY_SECURE_PATH: path }, signal, timeout: 10000, windowsHide: true }, error => error ? reject(signal?.aborted ? signal.reason : new CliError('storage_permissions', 'Could not set private Windows access permissions.')) : resolve()))
+}
+export function createStore(config, { signal } = {}) {
+  const file = join(config.dir, 'auth.json')
+  const legacy = join(config.dir, 'key')
+  let compromised = false
+  let secured = false
+  async function ensure() {
+    try { mkdirSync(config.dir, { recursive: true, mode: 0o700 }); await makePrivate(config.dir, true, signal) }
+    catch (e) { if (signal?.aborted) throw signal.reason; if (e instanceof CliError) throw e; throw new CliError('storage_unavailable', 'Could not create a private credential directory. Check its permissions.') }
+  }
+  function readRaw() {
+    try {
+      const stateStat = check(file)
+      if (stateStat) {
+        const raw = readFileSync(file, 'utf8')
+        let state
+        try { state = JSON.parse(raw) } catch { throw new CliError('state_corrupt', 'The saved sign-in is damaged. Run hirify login --force to replace it, or hirify logout to remove it.') }
+        if (!state || typeof state !== 'object' || Array.isArray(state) || (state.schema_version !== undefined && state.schema_version !== 1)) throw new CliError('state_unsupported', 'The saved sign-in format is not supported by this version.')
+        if (state.kind !== 'signed-out' && (!['key', 'oauth'].includes(state.kind) || typeof state.access_token !== 'string' || !state.access_token.trim())) throw new CliError('state_corrupt', 'The saved sign-in is incomplete. Run hirify login --force.')
+        if (state.kind === 'oauth' && ((state.expires_at !== null && state.expires_at !== undefined && (!Number.isFinite(state.expires_at) || state.expires_at < 0)) || (state.refresh_token != null && typeof state.refresh_token !== 'string') || typeof state.client_id !== 'string')) throw new CliError('state_corrupt', 'The saved sign-in is incomplete. Run hirify login --force.')
+        return { ...state, generation: state.generation || `legacy:${createHash('sha256').update(raw).digest('hex')}` }
+      }
+      if (check(legacy)) {
+        const key = readFileSync(legacy, 'utf8').trim()
+        if (key) return { kind: 'key', issuer: DEFAULT_API, access_token: key, generation: `legacy:${createHash('sha256').update(key).digest('hex')}` }
+      }
+      return { kind: 'signed-out', generation: 'absent' }
+    } catch (e) { if (e instanceof CliError) throw e; throw new CliError('storage_unreadable', 'Could not read the saved sign-in. Check the credential directory permissions.') }
+  }
+  function read({ allowPending = false } = {}) {
+    const state = readRaw()
+    if (state.kind === 'signed-out') return null
+    const issuer = state.issuer || DEFAULT_API
+    if (serverURL(issuer) !== config.api) throw new CliError('issuer_mismatch', 'This sign-in belongs to another server. Use an explicit HIRIFY_KEY or sign in to the selected server with hirify login --force.')
+    if (state.refresh_pending && !allowPending) throw new CliError('refresh_uncertain', 'The previous token renewal did not finish safely. Run hirify login --force before continuing.')
+    return { ...state, issuer }
+  }
+  async function write(state) {
+    if (compromised) throw new CliError('storage_lock_lost', 'The sign-in lock was lost. No credentials were committed.')
+    await ensure(); check(file)
+    const temp = join(config.dir, `.auth-${randomUUID()}.tmp`)
+    let fd
+    try {
+      fd = openSync(temp, 'wx', 0o600)
+      writeFileSync(fd, JSON.stringify({ ...state, schema_version: 1 }, null, 2) + '\n')
+      fsyncSync(fd); closeSync(fd); fd = undefined
+      if (process.platform === 'win32') await makePrivate(temp, false, signal)
+      for (let attempt = 0; ; attempt++) {
+        try { renameSync(temp, file); break }
+        catch (error) { if (process.platform !== 'win32' || !['EPERM', 'EACCES', 'EBUSY'].includes(error.code) || attempt >= 4) throw error; await delay(50 * (attempt + 1), signal) }
+      }
+      if (process.platform !== 'win32') { const dir = openSync(config.dir, 'r'); try { fsyncSync(dir) } finally { closeSync(dir) } }
+      if (check(legacy)) unlinkSync(legacy)
+    } catch (e) { if (e instanceof CliError) throw e; throw new CliError('storage_write_failed', 'Could not save the sign-in safely. Check disk space and directory permissions. You may need to sign in again.') }
+    finally { if (fd !== undefined) closeSync(fd); try { unlinkSync(temp) } catch {} }
+  }
+  async function locked(fn) {
+    await ensure(); aborted(signal)
+    const lockPath = join(config.dir, '.session.lock')
+    let release
+    compromised = false
+    while (!release) {
+      aborted(signal)
+      try { release = await lockfile.lock(file, { realpath: false, lockfilePath: lockPath, stale: 120000, update: 10000, onCompromised: () => { compromised = true } }) }
+      catch (e) { if (e.code !== 'ELOCKED') throw new CliError('storage_lock_failed', 'Could not lock the saved sign-in. Check directory permissions.'); await delay(40 + Math.random() * 80, signal) }
+    }
+    try { aborted(signal); return await fn() } finally { await release().catch(() => {}) }
+  }
+  async function commit(state, expected) {
+    return locked(async () => {
+      const current = readRaw()
+      if (expected !== undefined && current.generation !== expected) throw new CliError('session_changed', 'The saved sign-in changed while this command was running. No older credentials were restored.')
+      const next = { ...state, issuer: config.api, generation: randomUUID(), refresh_pending: false }
+      await write(next); return next
+    })
+  }
+  async function logout() {
+    return locked(async () => {
+      let had = true
+      try { had = readRaw().kind !== 'signed-out' } catch (e) { if (!['state_corrupt', 'state_unsupported'].includes(e.code)) throw e }
+      await write({ kind: 'signed-out', generation: randomUUID() }); return had
+    })
+  }
+  async function beginLogin({ force = false } = {}) {
+    return locked(async () => {
+      let state
+      try { state = readRaw() } catch (e) { if (!force || !['state_corrupt', 'state_unsupported'].includes(e.code)) throw e; await write({ kind: 'signed-out', generation: randomUUID() }); state = readRaw() }
+      return state.generation
+    })
+  }
+  async function secure() { if (secured) return; await ensure(); for (const path of [file, legacy]) if (check(path)) await makePrivate(path, false, signal); secured = true }
+  return { file, read, readRaw, write, locked, commit, logout, beginLogin, secure }
+}