@indigoai-us/hq-cli 5.94.1 → 5.94.2

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## [Unreleased]
 
+## [5.94.2]
+
+### Fixed
+
+- `hq search <query>` works. It has been broken since 5.86.0: the query was
+  registered as a subcommand literally named `<query>`, so every search
+  returned `error: unknown command '<the query>'` and only `hq search get`
+  functioned. Queries are now an argument on `search` itself, so
+  `hq search release gate` needs no quoting. (#337)
+- Commands no longer fail silently. The top-level handler printed a message
+  only for one error class, so a crashing qmd made `hq index status` exit 1
+  with zero bytes on stdout and stderr — indistinguishable from success. Every
+  failure now emits a diagnostic, routed through the existing redaction chain
+  so visibility widens without disclosure widening. (#337)
+- The CLI no longer prefers a bundled qmd it cannot run. 5.94.1 made
+  package-local resolution work and thereby started preferring a global
+  install's qmd whose native better-sqlite3 bindings were never compiled,
+  breaking search on hosts that had previously fallen through to a working qmd
+  on `PATH`. Resolution now verifies the candidate actually runs. The probe
+  costs a ~0.3s spawn, so it runs only when a fallback exists — with nothing
+  better available the answer is the bundled binary either way, and a failure
+  there is now loud rather than silent. (#337)
+
 ## [5.94.1]
 
 ### Fixed

package/dist/commands/company-transfer.d.ts

@@ -0,0 +1,185 @@
+import { Command } from "commander";
+import { type ActiveMember } from "./members.js";
+/**
+ * `hq company transfer` — company ownership handover (client-service-pack
+ * US-010). The server adds ZERO new API routes (vault-api-hq-prod sits at the
+ * 600-route quota), so the CLI half multiplexes onto two EXISTING routes:
+ *
+ *   - WRITES ride `POST /membership/role` with a body discriminator
+ *     `action: "transfer-initiate" | "transfer-accept" | "transfer-decline" |
+ *     "transfer-cancel"`. The ordinary role payload has never carried an
+ *     `action` field, so the shapes cannot collide.
+ *   - The READ rides `GET /membership/company/{companyUid}?view=transfers`;
+ *     without that exact `view` value the route returns the member roster as
+ *     before.
+ *
+ * TWO-PARTY BY CONSTRUCTION. `initiate` NOMINATES; it does not transfer
+ * anything. Ownership moves only when the nominee runs `accept`. The four write
+ * transitions (initiate / accept / decline / cancel) all multiplex through one
+ * POST with an explicit `action`, matching the server's route shape.
+ *
+ * ABSENT-FIELD DISCIPLINE (policy `hq-absent-field-never-means-constraining-value`).
+ * This flow spans two repos that deploy in EITHER order, so absence is load
+ * bearing in both directions and is handled in both directions here:
+ *
+ *   - REQUESTS: a flag the operator did not pass is OMITTED from the body — it
+ *     is never defaulted to a value on the wire. `--initiator-role` unset sends
+ *     no `initiatorRole` at all, so the server applies its own reversible
+ *     "keep them as admin" default; the CLI can therefore never turn silence
+ *     into `remove`. Same for `--transfer-id` (absent = "the pending one").
+ *   - RESPONSES: fields are read with presence and value SEPARATELY
+ *     ({@link readWireField}), because an OLDER server omits fields a newer CLI
+ *     knows about. An absent `effects.initiator` renders as "not reported",
+ *     never as "removed" — the CLI must not narrate a destructive outcome it
+ *     was never actually told about.
+ *
+ * Conventions mirror `company.ts` / `files.ts`: ensureCognitoToken() →
+ * getEntityUid() → vaultApiFetch() → error-check → chalk output, with the
+ * confirmation prompt behind an injectable seam so tests can drive it.
+ */
+/** The four write transitions the server accepts. */
+export declare const TRANSFER_ACTIONS: readonly ["initiate", "accept", "decline", "cancel"];
+export type TransferAction = (typeof TRANSFER_ACTIONS)[number];
+/**
+ * Legal `--initiator-role` values. `owner` is deliberately absent: a handover
+ * where the outgoing owner keeps `owner` is not a handover. `remove` is the
+ * ONLY value that takes them off the company, and it can only ever arrive from
+ * an explicit flag.
+ */
+export declare const INITIATOR_ROLE_VALUES: readonly ["admin", "member", "guest", "remove"];
+export type InitiatorRoleFlag = (typeof INITIATOR_ROLE_VALUES)[number];
+/**
+ * What the SERVER falls back to when `initiatorRole` is absent. Mirrored here
+ * only so the confirmation preview can tell the operator what will happen; the
+ * CLI never puts this value on the wire, because sending it would defeat the
+ * point of leaving the field absent.
+ */
+export declare const DEFAULT_INITIATOR_ROLE = "admin";
+/** A response field's presence, kept separate from its value. */
+export interface WireRead<T = unknown> {
+    present: boolean;
+    value: T | undefined;
+}
+/**
+ * Read a field off a server response reporting presence and value SEPARATELY.
+ *
+ * The CLI-side twin of hq-pro's `readField`. `body.x ?? fallback` is wrong here
+ * because it makes an OLDER server's omitted field indistinguishable from a
+ * newer server explicitly sending `null`/`false`/`""` — and every caller below
+ * needs to say "this server didn't tell me" rather than invent an answer.
+ */
+export declare function readWireField<T = unknown>(body: Record<string, unknown> | null | undefined, key: string): WireRead<T>;
+/**
+ * Parse `--initiator-role`.
+ *
+ * Returns `undefined` when the flag was NOT passed, and that `undefined` means
+ * "omit the field entirely" — never "remove", and never a substituted default.
+ * A present-but-invalid value throws instead of falling back, so a typo can
+ * never be silently reinterpreted as a different disposition.
+ */
+export declare function parseInitiatorRole(raw: string | undefined): InitiatorRoleFlag | undefined;
+export interface TransferBodyParams {
+    companyUid: string;
+    action: TransferAction;
+    targetPersonUid?: string;
+    initiatorRole?: InitiatorRoleFlag;
+    transferId?: string;
+    reason?: string;
+}
+/**
+ * The wire prefix that turns `POST /membership/role` into a transfer request.
+ * Mirrors the server's `TRANSFER_ACTION_PREFIX` in `_ownership-transfer.ts`:
+ * a body whose `action` starts with `transfer-` is a transfer; anything else
+ * (including no `action` at all) is an ordinary role change.
+ */
+export declare const TRANSFER_ACTION_PREFIX = "transfer-";
+/**
+ * The query discriminator on `GET /membership/company/{companyUid}` that
+ * selects the transfer surface instead of the member roster. Mirrors the
+ * server's `TRANSFER_HISTORY_VIEW` (exact match on the server side).
+ */
+export declare const TRANSFER_HISTORY_VIEW = "transfers";
+/**
+ * Build the `POST /membership/role` transfer body. The CLI-side `action`
+ * ("initiate" | …) is prefixed to the wire discriminator ("transfer-initiate"
+ * | …) HERE, so no call site can accidentally post an unprefixed action that
+ * the server would route to the ordinary role-change handler.
+ *
+ * Every optional field is included ONLY when the caller actually supplied it.
+ * This is the single choke point for the request half of the absent-field rule:
+ * if a value is not here, the server sees no key at all and applies its own
+ * safe default, which keeps the CLI correct against a server that predates any
+ * of these fields.
+ */
+export declare function buildTransferBody(params: TransferBodyParams): Record<string, unknown>;
+/**
+ * Describe what the confirmation prompt should say happens to the OUTGOING
+ * owner. Absence resolves to the reversible, non-destructive sentence.
+ */
+export declare function describeInitiatorOutcome(role: InitiatorRoleFlag | undefined): string;
+/**
+ * Render the `effects` block of an accepted transfer.
+ *
+ * Reads every field for PRESENCE first. An older server that does not send
+ * `effects`, or omits a field inside it, gets an honest "not reported" line —
+ * inventing "removed" or "unchanged" here would be the CLI asserting a
+ * destructive outcome it has no evidence for.
+ */
+export declare function describeEffects(rawEffects: unknown): string[];
+/** Injectable yes/no confirmation seam (stubbed in tests). */
+export type ConfirmFn = (message: string) => Promise<boolean>;
+/**
+ * The real prompt. Refuses (rather than assuming yes) when stdin is not a TTY,
+ * so a transfer can never be initiated or accepted by a pipeline that simply
+ * had nobody to ask. `--yes` is the only non-interactive path, and it is an
+ * explicit operator act.
+ *
+ * Exported ONLY so the non-TTY refusal — the one confirmation path the
+ * injectable seam hides from the command tests — can be covered directly.
+ */
+export declare function realConfirm(message: string): Promise<boolean>;
+/**
+ * Resolve `--to` to a `personUid`. A uid is used as-is; anything else is
+ * matched (case-insensitively) against the company's ACTIVE roster by email,
+ * slug, or name, because the server requires a uid and only accepts a target
+ * who is already an active member.
+ */
+export declare function matchMemberTarget(members: ActiveMember[], target: string): ActiveMember | undefined;
+export declare function resolveTargetPersonUid(token: string, companyUid: string, target: string): Promise<{
+    personUid: string;
+    label: string;
+}>;
+export interface TransferDeps {
+    confirm?: ConfirmFn;
+}
+export interface RunTransferParams {
+    companySlug: string;
+    action: TransferAction;
+    /** `--to` (initiate only): email, slug, name, or prs_… uid. */
+    to?: string;
+    /** Raw `--initiator-role`; `undefined` means the flag was NOT passed. */
+    initiatorRoleRaw?: string;
+    /** Raw `--transfer-id`; `undefined` means "the pending one". */
+    transferId?: string;
+    reason?: string;
+    yes?: boolean;
+}
+/**
+ * `hq company transfer initiate|accept|decline|cancel`.
+ *
+ * `initiate` and `accept` are the two transitions that move (or commit to
+ * moving) ownership, so both stop for an explicit confirmation that spells out
+ * who becomes owner and what happens to the outgoing owner. `decline` and
+ * `cancel` only ever ABORT a nomination, so they do not prompt.
+ */
+export declare function runCompanyTransfer(params: RunTransferParams, deps?: TransferDeps): Promise<void>;
+export interface RunTransferStatusParams {
+    companySlug: string;
+    limit?: string;
+    cursor?: string;
+    json?: boolean;
+}
+/** `hq company transfer status` — the pending nomination plus the audit trail. */
+export declare function runCompanyTransferStatus(params: RunTransferStatusParams): Promise<void>;
+export declare function registerCompanyTransferCommand(company: Command, deps?: TransferDeps): void;
+//# sourceMappingURL=company-transfer.d.ts.map