@indigoai-us/hq-cli 5.345.162 → 5.345.163

package/dist/commands/feedback-triage.d.ts

@@ -0,0 +1,67 @@
+import { Command } from "commander";
+/**
+ * Staff triage commands on the feedback queue: `hq feedback list`,
+ * `hq feedback triage` and `hq feedback close`. `hq feedback assign` lives in
+ * feedback.ts next to the shared helpers.
+ *
+ * The server owns triagedAt, triagedBy and priority. These commands never
+ * send them.
+ */
+export declare const TRIAGE_KINDS: readonly ["bug", "feature", "question"];
+export type TriageKind = (typeof TRIAGE_KINDS)[number];
+export declare const MAX_TRIAGE_SUMMARY = 2000;
+export declare const DEFAULT_LIST_LIMIT = 50;
+export interface FeedbackListRow {
+    id: string;
+    title?: string;
+    plan?: string;
+    submittedAt?: string;
+    createdAt?: string;
+    [key: string]: unknown;
+}
+export type FeedbackListSelector = {
+    kind: "untriaged";
+} | {
+    kind: "assignee";
+    assignee: string;
+};
+/** Email claim of the caller's staff token, used by `list --mine`. */
+export declare function emailFromToken(token: string): string | null;
+/** Compact age such as `5m`, `3h` or `2d`. Unknown or unparsable times print `-`. */
+export declare function formatFeedbackAge(iso: string | undefined, now?: number): string;
+/**
+ * hq-pro's `GET /v1/feedback` returns the next page as `nextCursor` on every
+ * path (the untriaged queue also mirrors it as `cursor`) and reads it back from
+ * `?cursor=`. `nextToken` is accepted for older servers. The value always goes
+ * back as `?cursor=`.
+ */
+export declare function cursorFrom(data: unknown): string | null;
+/** Page through `GET /v1/feedback` until `limit` rows (or every row with `limit: null`). */
+export declare function listFeedback(opts: {
+    token: string;
+    selector: FeedbackListSelector;
+    status?: string;
+    limit: number | null;
+}): Promise<FeedbackListRow[]>;
+export declare function formatFeedbackTable(rows: FeedbackListRow[], now?: number): string;
+export declare function parseListLimit(raw: string): number;
+export declare function buildTriagePatch(opts: {
+    id: string;
+    kind: string;
+    area: string;
+    summary: string;
+    duplicateOf?: string;
+}): Record<string, string>;
+export declare function buildClosePatch(opts: {
+    reason: string;
+    wontFix?: boolean;
+}): Record<string, string>;
+/** PATCH one feedback row; returns the server's JSON, or the sent fields when the body is empty. */
+export declare function patchFeedback(opts: {
+    id: string;
+    token: string;
+    body: Record<string, string>;
+    action: string;
+}): Promise<unknown>;
+export declare function registerFeedbackTriageCommands(feedbackCmd: Command): void;
+//# sourceMappingURL=feedback-triage.d.ts.map

package/dist/commands/feedback-triage.js

@@ -0,0 +1,294 @@
+import chalk from "chalk";
+import { assertVaultApiRequestSupported, vaultApiFetch } from "../utils/vault-api.js";
+import { decodeJwtPayload } from "../utils/person-token-cache.js";
+import { assertFeedbackId, normalizeFeedbackAssignee, readFeedbackError, resolveStaffToken, } from "./feedback.js";
+/**
+ * Staff triage commands on the feedback queue: `hq feedback list`,
+ * `hq feedback triage` and `hq feedback close`. `hq feedback assign` lives in
+ * feedback.ts next to the shared helpers.
+ *
+ * The server owns triagedAt, triagedBy and priority. These commands never
+ * send them.
+ */
+export const TRIAGE_KINDS = ["bug", "feature", "question"];
+export const MAX_TRIAGE_SUMMARY = 2000;
+export const DEFAULT_LIST_LIMIT = 50;
+/** Safety stop for --all so a server that never ends its cursor can't loop forever. */
+const MAX_LIST_PAGES = 100;
+function fail(err) {
+    console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+    process.exit(1);
+}
+/** Email claim of the caller's staff token, used by `list --mine`. */
+export function emailFromToken(token) {
+    const claims = decodeJwtPayload(token);
+    const email = claims?.email;
+    return typeof email === "string" && email.includes("@") ? email.toLowerCase() : null;
+}
+/** Compact age such as `5m`, `3h` or `2d`. Unknown or unparsable times print `-`. */
+export function formatFeedbackAge(iso, now = Date.now()) {
+    if (!iso)
+        return "-";
+    const at = Date.parse(iso);
+    if (Number.isNaN(at))
+        return "-";
+    const minutes = Math.max(0, Math.floor((now - at) / 60_000));
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 48)
+        return `${hours}h`;
+    return `${Math.floor(hours / 24)}d`;
+}
+function rowsFrom(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return [];
+    const items = data.items;
+    if (!Array.isArray(items))
+        return [];
+    return items.filter((row) => !!row && typeof row === "object" && typeof row.id === "string");
+}
+/**
+ * hq-pro's `GET /v1/feedback` returns the next page as `nextCursor` on every
+ * path (the untriaged queue also mirrors it as `cursor`) and reads it back from
+ * `?cursor=`. `nextToken` is accepted for older servers. The value always goes
+ * back as `?cursor=`.
+ */
+export function cursorFrom(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return null;
+    for (const name of ["nextCursor", "cursor", "nextToken"]) {
+        const value = data[name];
+        if (typeof value === "string" && value.length > 0)
+            return value;
+    }
+    return null;
+}
+/** Server page cap (FEEDBACK_LIST_PAGE_MAX). The plain list path rejects a cursor without a limit. */
+const LIST_PAGE_SIZE = 200;
+/** Page through `GET /v1/feedback` until `limit` rows (or every row with `limit: null`). */
+export async function listFeedback(opts) {
+    const base = opts.selector.kind === "untriaged"
+        ? { triage: "untriaged" }
+        : { assignee: opts.selector.assignee };
+    if (opts.status)
+        base.status = opts.status;
+    const rows = [];
+    let cursor = null;
+    for (let page = 0; page < MAX_LIST_PAGES; page++) {
+        const pageSize = opts.limit === null ? LIST_PAGE_SIZE : Math.min(LIST_PAGE_SIZE, opts.limit - rows.length);
+        const query = { ...base, limit: String(pageSize) };
+        if (cursor)
+            query.cursor = cursor;
+        const res = await vaultApiFetch({ token: opts.token, path: "/v1/feedback", query });
+        if (!res.ok) {
+            throw new Error(`Failed to list feedback: ${await readFeedbackError(res)}`);
+        }
+        const data = (await res.json());
+        rows.push(...rowsFrom(data));
+        if (opts.limit !== null && rows.length >= opts.limit)
+            return rows.slice(0, opts.limit);
+        cursor = cursorFrom(data);
+        if (!cursor)
+            return rows;
+    }
+    return rows;
+}
+export function formatFeedbackTable(rows, now = Date.now()) {
+    const header = ["ID", "AGE", "PLAN", "TITLE"];
+    const body = rows.map((row) => [
+        row.id,
+        formatFeedbackAge(row.submittedAt ?? row.createdAt, now),
+        typeof row.plan === "string" && row.plan.length > 0 ? row.plan : "-",
+        typeof row.title === "string" ? row.title : "",
+    ]);
+    const widths = [0, 1, 2].map((col) => Math.max(header[col].length, ...body.map((cells) => cells[col].length)));
+    return [header, ...body]
+        .map((cells) => cells.map((cell, col) => (col < 3 ? cell.padEnd(widths[col]) : cell)).join("  ").trimEnd())
+        .join("\n");
+}
+export function parseListLimit(raw) {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1) {
+        throw new Error(`Invalid --limit '${raw}': expected a positive whole number.`);
+    }
+    return n;
+}
+export function buildTriagePatch(opts) {
+    if (!TRIAGE_KINDS.includes(opts.kind)) {
+        throw new Error(`Invalid --kind '${opts.kind}': expected one of ${TRIAGE_KINDS.join(", ")}.`);
+    }
+    const area = opts.area.trim();
+    if (!area)
+        throw new Error("--area must not be empty.");
+    const summary = opts.summary.trim();
+    if (!summary)
+        throw new Error("--summary must not be empty.");
+    if (summary.length > MAX_TRIAGE_SUMMARY) {
+        throw new Error(`--summary is ${summary.length} characters; the limit is ${MAX_TRIAGE_SUMMARY}.`);
+    }
+    const body = {
+        triageStatus: opts.duplicateOf === undefined ? "triaged" : "duplicate",
+        triageKind: opts.kind,
+        area,
+        summary,
+    };
+    if (opts.duplicateOf !== undefined) {
+        assertFeedbackId(opts.duplicateOf);
+        if (opts.duplicateOf === opts.id) {
+            throw new Error("--duplicate-of must name a different feedback item.");
+        }
+        body.duplicateOf = opts.duplicateOf;
+    }
+    return body;
+}
+export function buildClosePatch(opts) {
+    const reason = opts.reason.trim();
+    if (!reason)
+        throw new Error("--reason must not be empty.");
+    return { status: opts.wontFix ? "wont_fix" : "resolved", resolution: reason };
+}
+/** PATCH one feedback row; returns the server's JSON, or the sent fields when the body is empty. */
+export async function patchFeedback(opts) {
+    const res = await vaultApiFetch({
+        token: opts.token,
+        path: `/v1/feedback/${opts.id}`,
+        method: "PATCH",
+        body: opts.body,
+    });
+    if (!res.ok) {
+        throw new Error(`Failed to ${opts.action} ${opts.id}: ${await readFeedbackError(res)}`);
+    }
+    const data = (await res.json().catch(() => null));
+    return data ?? { id: opts.id, ...opts.body };
+}
+function registerListSubcommand(feedbackCmd) {
+    feedbackCmd
+        .command("list")
+        .description("List feedback: untriaged (default), yours, or one person's")
+        .option("--untriaged", "Items nobody has triaged yet (the default)")
+        .option("--mine", "Items assigned to you")
+        .option("--assignee <person>", "Items assigned to this email address or prs_ uid")
+        .option("--status <status>", "Only items with this status")
+        .option("--limit <n>", `Stop after this many items (default ${DEFAULT_LIST_LIMIT})`)
+        .option("--all", "Fetch every page")
+        .option("--json", "Print { items, count } as JSON")
+        .action(async (opts) => {
+        try {
+            const picked = [opts.untriaged, opts.mine, opts.assignee !== undefined].filter(Boolean);
+            if (picked.length > 1) {
+                throw new Error("Use only one of --untriaged, --mine and --assignee.");
+            }
+            if (opts.all && opts.limit !== undefined) {
+                throw new Error("Use --limit or --all, not both.");
+            }
+            if (opts.status !== undefined && !opts.status.trim()) {
+                throw new Error("--status must not be empty.");
+            }
+            const limit = opts.all
+                ? null
+                : opts.limit === undefined
+                    ? DEFAULT_LIST_LIMIT
+                    : parseListLimit(opts.limit);
+            const token = await resolveStaffToken();
+            let selector = { kind: "untriaged" };
+            if (opts.mine) {
+                const email = emailFromToken(token);
+                if (!email) {
+                    throw new Error("--mine needs a person login with an email (hq login). Use --assignee <person> instead.");
+                }
+                selector = { kind: "assignee", assignee: email };
+            }
+            else if (opts.assignee !== undefined) {
+                selector = {
+                    kind: "assignee",
+                    assignee: normalizeFeedbackAssignee(opts.assignee, "--assignee"),
+                };
+            }
+            assertVaultApiRequestSupported({ token, path: "/v1/feedback" });
+            const items = await listFeedback({
+                token,
+                selector,
+                status: opts.status?.trim(),
+                limit,
+            });
+            if (opts.json) {
+                console.log(JSON.stringify({ items, count: items.length }));
+            }
+            else if (items.length === 0) {
+                console.log("No feedback items match.");
+            }
+            else {
+                console.log(formatFeedbackTable(items));
+            }
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+}
+function registerTriageSubcommand(feedbackCmd) {
+    feedbackCmd
+        .command("triage")
+        .description("Label a feedback item with its kind, area and summary, or mark it a duplicate")
+        .argument("<id>", "Feedback id (feedback_<uuid>)")
+        .requiredOption("--kind <kind>", `One of ${TRIAGE_KINDS.join(", ")}`)
+        .requiredOption("--area <area>", "Product area, for example sync or desktop")
+        .requiredOption("--summary <text>", `One-line triage summary (at most ${MAX_TRIAGE_SUMMARY} characters)`)
+        .option("--duplicate-of <id>", "Mark this item a duplicate of another feedback id")
+        .option("--json", "Print the updated item as JSON")
+        .action(async (id, opts) => {
+        try {
+            assertFeedbackId(id);
+            const body = buildTriagePatch({ id, ...opts });
+            const token = await resolveStaffToken();
+            assertVaultApiRequestSupported({ token, path: `/v1/feedback/${id}` });
+            const result = await patchFeedback({ id, token, body, action: "triage" });
+            if (opts.json) {
+                console.log(JSON.stringify(result));
+            }
+            else if (body.duplicateOf) {
+                console.log(`Marked duplicate: ${id} -> ${body.duplicateOf}`);
+            }
+            else {
+                console.log(`Triaged: ${id} (${body.triageKind}, ${body.area})`);
+            }
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+}
+function registerCloseSubcommand(feedbackCmd) {
+    feedbackCmd
+        .command("close")
+        .description("Close a feedback item as resolved (or won't fix) with a reason")
+        .argument("<id>", "Feedback id (feedback_<uuid>)")
+        .requiredOption("--reason <text>", "Why it is closed: the fix, PR or version, or the decision")
+        .option("--wont-fix", "Close as won't fix instead of resolved")
+        .option("--json", "Print the updated item as JSON")
+        .action(async (id, opts) => {
+        try {
+            assertFeedbackId(id);
+            const body = buildClosePatch(opts);
+            const token = await resolveStaffToken();
+            assertVaultApiRequestSupported({ token, path: `/v1/feedback/${id}` });
+            const result = await patchFeedback({ id, token, body, action: "close" });
+            if (opts.json) {
+                console.log(JSON.stringify(result));
+            }
+            else {
+                console.log(`Closed: ${id} (${body.status})`);
+            }
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+}
+export function registerFeedbackTriageCommands(feedbackCmd) {
+    registerListSubcommand(feedbackCmd);
+    registerTriageSubcommand(feedbackCmd);
+    registerCloseSubcommand(feedbackCmd);
+}
+//# sourceMappingURL=feedback-triage.js.map

package/dist/commands/feedback.d.ts

@@ -76,6 +76,13 @@ export declare function submitFeedback(opts: FeedbackSubmitOptions): Promise<Fee
 export declare const PUBLIC_TICKET_STATES: readonly ["triaged", "in-progress", "shipped", "verified", "resolved"];
 export type PublicTicketState = (typeof PUBLIC_TICKET_STATES)[number];
 export declare function assertFeedbackId(id: string): void;
+/**
+ * The staff feedback routes gate on the id token's email claim, so send the
+ * cached id token when a person session has one. Machine identities already
+ * get their id token back from ensureCognitoToken.
+ */
+export declare function resolveStaffToken(): Promise<string>;
+export declare function readFeedbackError(res: Response): Promise<string>;
 /** Resolve (and lazily mint) the public tracking link for a ticket. */
 export declare function fetchFeedbackLink(opts: {
     id: string;
@@ -92,7 +99,7 @@ export declare function postFeedbackUpdate(opts: {
     slack: string | null;
 }>;
 /** Mirror of hq-pro normalizeAssignee: a prs_ uid as-is, an email lowercased. */
-export declare function normalizeFeedbackAssignee(value: string): string;
+export declare function normalizeFeedbackAssignee(value: string, label?: string): string;
 /**
  * Reassign a ticket. A person's own login may move a ticket that another
  * person claimed; agent and operator service tokens get 409
@@ -103,5 +110,10 @@ export declare function assignFeedback(opts: {
     token: string;
     assignee: string;
 }): Promise<void>;
+/**
+ * Pick the new assignee from the positional `[person]` or the `--to` flag.
+ * Either form works; naming two different people is an error.
+ */
+export declare function resolveAssignTarget(person: string | undefined, to: string | undefined): string;
 export declare function registerFeedbackCommand(program: Command): void;
 //# sourceMappingURL=feedback.d.ts.map

package/dist/commands/feedback.js

@@ -9,6 +9,7 @@ import { uploadLogBundle } from "../utils/feedback-log-bundle.js";
 import { resolveProcessFlagGate } from "../lib/flag-registry.js";
 import { cachedLatestVersion } from "../utils/version-check.js";
 import { registerFeedbackShowCommand } from "./feedback-show.js";
+import { registerFeedbackTriageCommands } from "./feedback-triage.js";
 export const FEEDBACK_LATEST_VERSION_FLAG = "feedback.latest-version";
 export const FEEDBACK_LATEST_VERSION_FLAG_FALLBACK = false;
 export const FEEDBACK_REPORTER_KIND_FLAG = "feedback.reporter-kind";
@@ -229,14 +230,14 @@ export function assertFeedbackId(id) {
  * cached id token when a person session has one. Machine identities already
  * get their id token back from ensureCognitoToken.
  */
-async function resolveStaffToken() {
+export async function resolveStaffToken() {
     const token = await ensureCognitoToken({ interactive: false });
     const cached = loadCachedTokens();
     return typeof cached?.idToken === "string" && cached.idToken.length > 0
         ? cached.idToken
         : token;
 }
-async function readFeedbackError(res) {
+export async function readFeedbackError(res) {
     const data = await res.json().catch(() => ({}));
     return data &&
         typeof data === "object" &&
@@ -287,10 +288,10 @@ export async function postFeedbackUpdate(opts) {
 }
 const ASSIGNEE_RE = /^(?:prs_[A-Za-z0-9]+|[^\s@]+@[^\s@]+\.[^\s@]+)$/;
 /** Mirror of hq-pro normalizeAssignee: a prs_ uid as-is, an email lowercased. */
-export function normalizeFeedbackAssignee(value) {
+export function normalizeFeedbackAssignee(value, label = "--to") {
     const trimmed = value.trim();
     if (!ASSIGNEE_RE.test(trimmed)) {
-        throw new Error(`Invalid --to '${value}': expected an email address or a prs_ uid.`);
+        throw new Error(`Invalid ${label} '${value}': expected an email address or a prs_ uid.`);
     }
     return trimmed.startsWith("prs_") ? trimmed : trimmed.toLowerCase();
 }
@@ -315,20 +316,42 @@ export async function assignFeedback(opts) {
     }
     throw new Error(`Failed to assign ${opts.id}: ${message}`);
 }
+/**
+ * Pick the new assignee from the positional `[person]` or the `--to` flag.
+ * Either form works; naming two different people is an error.
+ */
+export function resolveAssignTarget(person, to) {
+    if (person === undefined && to === undefined) {
+        throw new Error("Name the new assignee: hq feedback assign <id> <person> (or --to <person>).");
+    }
+    const fromPerson = person === undefined ? undefined : normalizeFeedbackAssignee(person, "person");
+    const fromTo = to === undefined ? undefined : normalizeFeedbackAssignee(to);
+    if (fromPerson !== undefined && fromTo !== undefined && fromPerson !== fromTo) {
+        throw new Error(`Conflicting assignees '${person}' and --to '${to}': give only one.`);
+    }
+    return (fromPerson ?? fromTo);
+}
 function registerAssignSubcommand(feedbackCmd) {
     feedbackCmd
         .command("assign")
         .description("Reassign a ticket to a person, including one another person has claimed")
         .argument("<id>", "Feedback id (feedback_<uuid>)")
-        .requiredOption("--to <assignee>", "New assignee: an email address or a prs_ uid")
-        .action(async (id, opts) => {
+        .argument("[person]", "New assignee: an email address or a prs_ uid")
+        .option("--to <assignee>", "New assignee: an email address or a prs_ uid")
+        .option("--json", "Print the result as JSON")
+        .action(async (id, person, opts) => {
         try {
             assertFeedbackId(id);
-            const assignee = normalizeFeedbackAssignee(opts.to);
+            const assignee = resolveAssignTarget(person, opts.to);
             const token = await resolveStaffToken();
             assertVaultApiRequestSupported({ token, path: `/v1/feedback/${id}` });
             await assignFeedback({ id, token, assignee });
-            console.log(`Assigned: ${id} -> ${assignee}`);
+            if (opts.json) {
+                console.log(JSON.stringify({ id, assignee }));
+            }
+            else {
+                console.log(`Assigned: ${id} -> ${assignee}`);
+            }
         }
         catch (err) {
             console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
@@ -499,5 +522,6 @@ export function registerFeedbackCommand(program) {
     registerUpdateSubcommand(feedbackCmd);
     registerFeedbackShowCommand(feedbackCmd);
     registerAssignSubcommand(feedbackCmd);
+    registerFeedbackTriageCommands(feedbackCmd);
 }
 //# sourceMappingURL=feedback.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.345.162",
+  "version": "5.345.163",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -114,11 +114,11 @@
     "*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}": "eslint --cache --no-error-on-unmatched-pattern"
   },
   "optionalDependencies": {
-    "@indigoai-us/hq-hook-win32-x64": "5.345.162",
-    "@indigoai-us/hq-hook-win32-arm64": "5.345.162",
-    "@indigoai-us/hq-hook-darwin-x64": "5.345.162",
-    "@indigoai-us/hq-hook-darwin-arm64": "5.345.162",
-    "@indigoai-us/hq-hook-linux-x64": "5.345.162",
-    "@indigoai-us/hq-hook-linux-arm64": "5.345.162"
+    "@indigoai-us/hq-hook-win32-x64": "5.345.163",
+    "@indigoai-us/hq-hook-win32-arm64": "5.345.163",
+    "@indigoai-us/hq-hook-darwin-x64": "5.345.163",
+    "@indigoai-us/hq-hook-darwin-arm64": "5.345.163",
+    "@indigoai-us/hq-hook-linux-x64": "5.345.163",
+    "@indigoai-us/hq-hook-linux-arm64": "5.345.163"
   }
 }