@indigoai-us/hq-cli 5.345.169 → 5.345.170

package/dist/commands/feedback-triage.js

@@ -11,6 +11,29 @@ import { assertFeedbackId, normalizeFeedbackAssignee, readFeedbackError, resolve
  * send them.
  */
 export const TRIAGE_KINDS = ["bug", "feature", "question"];
+/**
+ * Internal feedback row statuses `hq feedback list --status` accepts.
+ * `stalled` is open work that started and then stopped: a row is in_progress
+ * only while it has a linked open PR or a live lane, and moves to stalled after
+ * 48h with no activity. It is listed apart from `new` (not started).
+ */
+/**
+ * Statuses shown in `list --status` help. Help text only: the CLI does not
+ * validate against this list, because hq-pro owns the set and returns a 400
+ * for an unknown value.
+ */
+export const FEEDBACK_LIST_STATUSES = [
+    "new",
+    "triaging",
+    "accepted",
+    "wont_fix",
+    "in_progress",
+    "resolved",
+    "waiting_on_customer",
+    "reopened",
+    "stalled",
+    "needs_info",
+];
 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. */
@@ -64,49 +87,114 @@ export function cursorFrom(data) {
     }
     return null;
 }
+function isTruncated(data) {
+    return (!!data &&
+        typeof data === "object" &&
+        !Array.isArray(data) &&
+        data.truncated === true);
+}
 /** Server page cap (FEEDBACK_LIST_PAGE_MAX). The plain list path rejects a cursor without a limit. */
 const LIST_PAGE_SIZE = 200;
+/**
+ * Lifecycle states hq-pro treats as closed (`TERMINAL_STATUSES` in
+ * feedback-status.ts). `--open` lists every row outside this set; a row with
+ * no status counts as open.
+ */
+export const TERMINAL_FEEDBACK_STATUSES = ["resolved", "wont_fix", "accepted"];
+function isOpenRow(row) {
+    const status = row.status;
+    return typeof status !== "string" || !TERMINAL_FEEDBACK_STATUSES.includes(status);
+}
 /** 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 };
+        : opts.selector.kind === "assignee"
+            ? { assignee: opts.selector.assignee }
+            : {};
     if (opts.status)
         base.status = opts.status;
+    const keep = opts.selector.kind === "open" ? isOpenRow : () => true;
     const rows = [];
     let cursor = null;
+    let serverTruncated = false;
     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);
+        // The untriaged queue applies `limit` after filtering, so ask for exactly
+        // what is still needed. The plain list path applies `limit` to the
+        // DynamoDB read BEFORE its filters, so a small page returns few or no
+        // matches per request and burns the page budget: always ask for a full
+        // page there and trim to the limit here.
+        const pageSize = opts.limit === null || opts.selector.kind !== "untriaged"
+            ? 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)}`);
+            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);
+        rows.push(...rowsFrom(data).filter(keep));
+        if (isTruncated(data))
+            serverTruncated = true;
         cursor = cursorFrom(data);
-        if (!cursor)
-            return rows;
+        if (opts.limit !== null && rows.length >= opts.limit) {
+            // More rows exist when this page overflowed the limit or the server
+            // has another page.
+            const more = rows.length > opts.limit || cursor !== null || serverTruncated;
+            return {
+                items: rows.slice(0, opts.limit),
+                ...(more ? { truncated: serverTruncated ? "server" : "limit" } : {}),
+            };
+        }
+        if (!cursor) {
+            return { items: rows, ...(serverTruncated ? { truncated: "server" } : {}) };
+        }
     }
-    return rows;
+    return { items: rows, truncated: "page-cap" };
+}
+/** One-line stderr notice for a list that stopped before the end. */
+export function feedbackTruncationNotice(reason, shown) {
+    if (reason === "limit") {
+        return "Showing the first " + String(shown) + " items; more may match. Use --all or a larger --limit.";
+    }
+    if (reason === "page-cap") {
+        return ("Stopped after " + String(MAX_LIST_PAGES) + " pages (" + String(shown) +
+            " items); more may match. Narrow the query, for example with --status or --assignee instead of --open.");
+    }
+    return "The server cut this read short; some matching items may be missing.";
 }
 export function formatFeedbackTable(rows, now = Date.now()) {
-    const header = ["ID", "AGE", "PLAN", "TITLE"];
+    const header = ["ID", "AGE", "STATUS", "PLAN", "TITLE"];
     const body = rows.map((row) => [
         row.id,
         formatFeedbackAge(row.submittedAt ?? row.createdAt, now),
+        formatFeedbackStatus(row.status),
         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)));
+    const widths = [0, 1, 2, 3].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())
+        .map((cells) => cells.map((cell, col) => (col < 4 ? cell.padEnd(widths[col]) : cell)).join("  ").trimEnd())
         .join("\n");
 }
+/** Status cell for the list table. A stalled row is flagged so it does not read as not started. */
+export function formatFeedbackStatus(status) {
+    if (typeof status !== "string" || status.length === 0)
+        return "-";
+    return status === "stalled" ? "stalled!" : status;
+}
+/**
+ * Normalize `list --status`; accepts `in-progress` as an alias of `in_progress`.
+ * Any non-empty value goes to the server, which validates it.
+ */
+export function parseListStatus(raw) {
+    const value = raw.trim().toLowerCase().replace(/-/g, "_");
+    if (!value)
+        throw new Error("--status must not be empty.");
+    return value;
+}
 export function parseListLimit(raw) {
     const n = Number(raw);
     if (!Number.isInteger(n) || n < 1) {
@@ -167,31 +255,40 @@ function registerListSubcommand(feedbackCmd) {
         .command("list")
         .description("List feedback: untriaged (default), yours, or one person's")
         .option("--untriaged", "Items nobody has triaged yet (the default)")
+        .option("--open", "Every item not resolved, won't-fix or accepted, triaged or not")
         .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("--status <status>", `Only items with this status (${FEEDBACK_LIST_STATUSES.join(", ")}). Without --untriaged, --mine or --assignee it lists every item in that 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")
+        .option("--json", "Print { items, count } as JSON, plus truncated: true when more items match")
         .action(async (opts) => {
         try {
-            const picked = [opts.untriaged, opts.mine, opts.assignee !== undefined].filter(Boolean);
+            const picked = [opts.untriaged, opts.open, opts.mine, opts.assignee !== undefined].filter(Boolean);
             if (picked.length > 1) {
-                throw new Error("Use only one of --untriaged, --mine and --assignee.");
+                throw new Error("Use only one of --untriaged, --open, --mine and --assignee.");
+            }
+            if (opts.open && opts.status !== undefined) {
+                throw new Error("--open already selects every open status; use --status on its own instead.");
             }
             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 status = opts.status === undefined ? undefined : parseListStatus(opts.status);
             const limit = opts.all
                 ? null
                 : opts.limit === undefined
                     ? DEFAULT_LIST_LIMIT
                     : parseListLimit(opts.limit);
             const token = await resolveStaffToken();
-            let selector = { kind: "untriaged" };
+            // No selector means the untriaged queue, except with --status: a
+            // status filter alone lists every row in that status. The queue only
+            // holds untriaged rows, so `--status accepted` there was nearly empty.
+            let selector = opts.open
+                ? { kind: "open" }
+                : opts.status !== undefined && !opts.untriaged
+                    ? { kind: "any" }
+                    : { kind: "untriaged" };
             if (opts.mine) {
                 const email = emailFromToken(token);
                 if (!email) {
@@ -206,14 +303,17 @@ function registerListSubcommand(feedbackCmd) {
                 };
             }
             assertVaultApiRequestSupported({ token, path: "/v1/feedback" });
-            const items = await listFeedback({
+            const { items, truncated } = await listFeedback({
                 token,
                 selector,
-                status: opts.status?.trim(),
+                status,
                 limit,
             });
+            if (truncated) {
+                console.error(chalk.yellow("Note:"), feedbackTruncationNotice(truncated, items.length));
+            }
             if (opts.json) {
-                console.log(JSON.stringify({ items, count: items.length }));
+                console.log(JSON.stringify({ items, count: items.length, ...(truncated ? { truncated: true } : {}) }));
             }
             else if (items.length === 0) {
                 console.log("No feedback items match.");

package/dist/commands/feedback.d.ts

@@ -73,7 +73,7 @@ export declare function attachDebugLogs(requestBody: Record<string, unknown>, di
 }): void;
 export declare function submitFeedback(opts: FeedbackSubmitOptions): Promise<FeedbackResult>;
 /** Customer-visible states accepted by `hq feedback update --state`. */
-export declare const PUBLIC_TICKET_STATES: readonly ["triaged", "in-progress", "shipped", "verified", "resolved"];
+export declare const PUBLIC_TICKET_STATES: readonly ["triaged", "in-progress", "stalled", "shipped", "verified", "resolved"];
 export type PublicTicketState = (typeof PUBLIC_TICKET_STATES)[number];
 export declare function assertFeedbackId(id: string): void;
 /**
@@ -88,6 +88,45 @@ export declare function fetchFeedbackLink(opts: {
     id: string;
     token: string;
 }): Promise<string>;
+/**
+ * Work links for an in-progress update. A feedback row is in_progress only
+ * while it has a linked open PR or a live lane, so `--state in-progress`
+ * requires one of them. Field names match the hq-pro PATCH body.
+ */
+export interface FeedbackWorkLink {
+    prUrl?: string;
+    laneId?: string;
+}
+/** Accept `in_progress` as an alias of the public `in-progress` state. */
+export declare function normalizePublicState(raw: string): string;
+/** Validate --pr/--lane for a state; in-progress needs at least one, other states take none. */
+export declare function buildWorkLink(state: string, opts: {
+    pr?: string;
+    lane?: string;
+}): FeedbackWorkLink | null;
+/** Read a feedback row with the staff GET. Returns null when it cannot be read. */
+export declare function fetchFeedbackRow(opts: {
+    id: string;
+    token: string;
+}): Promise<Record<string, unknown> | null>;
+/** Delays between read-back attempts: 3 reads over about 1s. */
+export declare const LINK_READBACK_DELAYS_MS: readonly number[];
+/** Overridable in tests so retries do not wait on real timers. */
+export declare const linkReadbackTimer: {
+    sleep: (ms: number) => Promise<void>;
+};
+/**
+ * Store the PR or lane link before any state change, then confirm it was
+ * saved by reading the row back. The PATCH response does not echo prUrl or
+ * laneId, and an older server ignores unknown fields, so only the GET shows
+ * the link is stored. A link-only PATCH can itself change the row (hq-pro
+ * resumes a stalled row), so errors report the row's actual state.
+ */
+export declare function storeFeedbackWorkLink(opts: {
+    id: string;
+    token: string;
+    link: FeedbackWorkLink;
+}): Promise<void>;
 /** Post a customer-visible update; the server also mirrors it into #hq-feedback. */
 export declare function postFeedbackUpdate(opts: {
     id: string;

package/dist/commands/feedback.js

@@ -9,6 +9,7 @@ import { FEEDBACK_LOGS_MAX_TOTAL_BYTES, FEEDBACK_LOGS_MIN_USEFUL_BYTES, collectF
 import { uploadLogBundle } from "../utils/feedback-log-bundle.js";
 import { resolveProcessFlagGate } from "../lib/flag-registry.js";
 import { cachedLatestVersion } from "../utils/version-check.js";
+import { decodeJwtPayload } from "../utils/person-token-cache.js";
 import { registerFeedbackShowCommand } from "./feedback-show.js";
 import { registerFeedbackTriageCommands } from "./feedback-triage.js";
 export const FEEDBACK_LATEST_VERSION_FLAG = "feedback.latest-version";
@@ -223,6 +224,7 @@ export async function submitFeedback(opts) {
 export const PUBLIC_TICKET_STATES = [
     "triaged",
     "in-progress",
+    "stalled",
     "shipped",
     "verified",
     "resolved",
@@ -277,6 +279,129 @@ export async function fetchFeedbackLink(opts) {
     }
     return url;
 }
+const PR_URL_RE = /^https:\/\/[^\s/]+\/[^\s]+$/;
+/** Max `--lane` length; matches hq-pro LANE_ID_MAX_CHARS. */
+const LANE_ID_MAX_CHARS = 200;
+/** Same rule as hq-pro normalizeLaneId: non-empty, at most 200 chars, no control characters. */
+function isValidLaneId(lane) {
+    if (lane.length === 0 || lane.length > LANE_ID_MAX_CHARS)
+        return false;
+    for (let i = 0; i < lane.length; i += 1) {
+        const code = lane.charCodeAt(i);
+        if (code < 0x20 || code === 0x7f)
+            return false;
+    }
+    return true;
+}
+/** Accept `in_progress` as an alias of the public `in-progress` state. */
+export function normalizePublicState(raw) {
+    const value = raw.trim().toLowerCase();
+    return value === "in_progress" ? "in-progress" : value;
+}
+/** Validate --pr/--lane for a state; in-progress needs at least one, other states take none. */
+export function buildWorkLink(state, opts) {
+    const pr = opts.pr?.trim();
+    const lane = opts.lane?.trim();
+    if (state !== "in-progress") {
+        if (pr !== undefined || lane !== undefined) {
+            throw new Error("--pr and --lane only apply to --state in-progress.");
+        }
+        return null;
+    }
+    if (!pr && !lane) {
+        throw new Error("--state in-progress needs --pr <url> or --lane <id>: a ticket is in progress only while it has an open PR or a live lane. Claiming a ticket does not need a state; use hq feedback claim.");
+    }
+    const link = {};
+    if (pr) {
+        if (!PR_URL_RE.test(pr))
+            throw new Error(`Invalid --pr '${opts.pr}': expected an https:// pull request URL.`);
+        link.prUrl = pr;
+    }
+    if (lane) {
+        if (!isValidLaneId(lane)) {
+            throw new Error(`Invalid --lane '${opts.lane}': expected a lane id of at most ${LANE_ID_MAX_CHARS} characters with no control characters.`);
+        }
+        link.laneId = lane;
+    }
+    return link;
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function storedLinkMatches(row, link) {
+    if (!row)
+        return false;
+    return ((link.prUrl === undefined || row.prUrl === link.prUrl) &&
+        (link.laneId === undefined || row.laneId === link.laneId));
+}
+/** Read a feedback row with the staff GET. Returns null when it cannot be read. */
+export async function fetchFeedbackRow(opts) {
+    try {
+        const res = await vaultApiFetch({ token: opts.token, path: `/v1/feedback/${opts.id}`, method: "GET" });
+        if (!res.ok)
+            return null;
+        const data = asRecord(await res.json().catch(() => null));
+        return asRecord(data?.item);
+    }
+    catch {
+        return null;
+    }
+}
+function describeRowState(row) {
+    return typeof row?.status === "string"
+        ? `The ticket's current state is '${row.status}'.`
+        : "The ticket's current state could not be read; check it with hq feedback list.";
+}
+/** Re-read the row and describe its actual state, for error messages. */
+async function currentStateNote(id, token) {
+    return describeRowState(await fetchFeedbackRow({ id, token }));
+}
+const OLD_SERVER_HINT = "The server may not support work links yet.";
+/** Delays between read-back attempts: 3 reads over about 1s. */
+export const LINK_READBACK_DELAYS_MS = [300, 700];
+/** Overridable in tests so retries do not wait on real timers. */
+export const linkReadbackTimer = {
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+function sleep(ms) {
+    return linkReadbackTimer.sleep(ms);
+}
+/**
+ * Store the PR or lane link before any state change, then confirm it was
+ * saved by reading the row back. The PATCH response does not echo prUrl or
+ * laneId, and an older server ignores unknown fields, so only the GET shows
+ * the link is stored. A link-only PATCH can itself change the row (hq-pro
+ * resumes a stalled row), so errors report the row's actual state.
+ */
+export async function storeFeedbackWorkLink(opts) {
+    const res = await vaultApiFetch({
+        token: opts.token,
+        path: `/v1/feedback/${opts.id}`,
+        method: "PATCH",
+        body: { ...opts.link },
+    });
+    if (!res.ok) {
+        const message = await readFeedbackError(res);
+        throw new Error(`The server rejected the work link for ${opts.id}: ${message}. ${OLD_SERVER_HINT} ${await currentStateNote(opts.id, opts.token)}`);
+    }
+    // The GET resolves through an eventually consistent index, so a read right
+    // after the PATCH can return the old row. Retry briefly before deciding.
+    let row = null;
+    let readOk = false;
+    for (let attempt = 0; attempt < LINK_READBACK_DELAYS_MS.length + 1; attempt += 1) {
+        if (attempt > 0)
+            await sleep(LINK_READBACK_DELAYS_MS[attempt - 1]);
+        row = await fetchFeedbackRow({ id: opts.id, token: opts.token });
+        if (row)
+            readOk = true;
+        if (storedLinkMatches(row, opts.link))
+            return;
+    }
+    if (!readOk) {
+        throw new Error(`Could not read ${opts.id} back to confirm the work link; the link may have been saved. The state was not posted; rerun the same command to retry.`);
+    }
+    throw new Error(`The server did not store the work link for ${opts.id}. ${OLD_SERVER_HINT} ${describeRowState(row)}`);
+}
 /** Post a customer-visible update; the server also mirrors it into #hq-feedback. */
 export async function postFeedbackUpdate(opts) {
     const res = await vaultApiFetch({
@@ -286,7 +411,11 @@ export async function postFeedbackUpdate(opts) {
         body: { publicUpdate: { state: opts.state, note: opts.note } },
     });
     if (!res.ok) {
-        throw new Error(`Failed to update ${opts.id}: ${await readFeedbackError(res)}`);
+        const message = await readFeedbackError(res);
+        const hint = opts.state === "stalled" && (res.status === 400 || res.status === 422)
+            ? ` The server may not support the stalled state yet. ${await currentStateNote(opts.id, opts.token)}`
+            : "";
+        throw new Error(`Failed to update ${opts.id}: ${message}${hint}`);
     }
     const data = (await res.json());
     return {
@@ -367,6 +496,41 @@ function registerAssignSubcommand(feedbackCmd) {
         }
     });
 }
+function registerClaimSubcommand(feedbackCmd) {
+    feedbackCmd
+        .command("claim")
+        .description("Assign a ticket to yourself (sets the assignee only, never the status)")
+        .argument("<id>", "Feedback id (feedback_<uuid>)")
+        .option("--json", "Print { id, assignee } as JSON")
+        .action(async (id, opts) => {
+        try {
+            assertFeedbackId(id);
+            const token = await resolveStaffToken();
+            const email = emailFromStaffToken(token);
+            if (!email) {
+                throw new Error("hq feedback claim needs a person login with an email (hq login). Use hq feedback assign <id> <person> instead.");
+            }
+            assertVaultApiRequestSupported({ token, path: `/v1/feedback/${id}` });
+            await assignFeedback({ id, token, assignee: email });
+            if (opts.json) {
+                console.log(JSON.stringify({ id, assignee: email }));
+            }
+            else {
+                console.log(`Claimed: ${id} -> ${email}`);
+                console.log("Set --state in-progress with --pr <url> or --lane <id> once work is linked.");
+            }
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+}
+function emailFromStaffToken(token) {
+    const claims = decodeJwtPayload(token);
+    const email = claims?.email;
+    return typeof email === "string" && email.includes("@") ? email.toLowerCase() : null;
+}
 function registerLinkSubcommand(feedbackCmd) {
     feedbackCmd
         .command("link")
@@ -393,12 +557,16 @@ function registerUpdateSubcommand(feedbackCmd) {
         .argument("<id>", "Feedback id (feedback_<uuid>)")
         .requiredOption("--state <state>", `One of: ${PUBLIC_TICKET_STATES.join(", ")}`)
         .requiredOption("--note <text>", "What the customer should read (plain text, up to 2000 characters)")
+        .option("--pr <url>", "Open pull request for this ticket (required with --state in-progress unless --lane is given)")
+        .option("--lane <id>", "Live lane working this ticket (required with --state in-progress unless --pr is given)")
         .action(async (id, opts) => {
         try {
             assertFeedbackId(id);
-            if (!PUBLIC_TICKET_STATES.includes(opts.state)) {
+            const state = normalizePublicState(opts.state);
+            if (!PUBLIC_TICKET_STATES.includes(state)) {
                 throw new Error(`Invalid --state '${opts.state}': expected one of ${PUBLIC_TICKET_STATES.join(", ")}.`);
             }
+            const link = buildWorkLink(state, opts);
             const note = opts.note.trim();
             if (note.length === 0)
                 throw new Error("--note must not be empty.");
@@ -406,13 +574,24 @@ function registerUpdateSubcommand(feedbackCmd) {
                 throw new Error("--note must be at most 2000 characters.");
             const token = await resolveStaffToken();
             assertVaultApiRequestSupported({ token, path: `/v1/feedback/${id}` });
+            if (link)
+                await storeFeedbackWorkLink({ id, token, link });
             const result = await postFeedbackUpdate({
                 id,
                 token,
-                state: opts.state,
+                state: state,
                 note,
+            }).catch((err) => {
+                if (!link)
+                    throw err;
+                const message = err instanceof Error ? err.message : String(err);
+                throw new Error(`${message} The work link was saved; rerun the same command to set the state.`);
             });
-            console.log(`Updated: ${id} -> ${opts.state}`);
+            console.log(`Updated: ${id} -> ${state}`);
+            if (link?.prUrl)
+                console.log(`PR: ${link.prUrl}`);
+            if (link?.laneId)
+                console.log(`Lane: ${link.laneId}`);
             if (result.publicUrl)
                 console.log(`Track: ${result.publicUrl}`);
             if (result.slack === "failed") {
@@ -530,6 +709,7 @@ export function registerFeedbackCommand(program) {
     registerUpdateSubcommand(feedbackCmd);
     registerFeedbackShowCommand(feedbackCmd);
     registerAssignSubcommand(feedbackCmd);
+    registerClaimSubcommand(feedbackCmd);
     registerFeedbackTriageCommands(feedbackCmd);
 }
 //# sourceMappingURL=feedback.js.map

package/dist/commands/files.d.ts

@@ -66,6 +66,48 @@ export declare class ShareSessionHttpError extends Error {
  */
 export declare function formatShareSessionError(err: ShareSessionHttpError): string;
 export declare function registerFilesCommand(program: Command): Command;
+/**
+ * True for a prefix that might name a folder without saying so: no trailing
+ * `/` (private folder), no `/*` (shared folder glob), and not the `*`
+ * wildcard, and a last segment with no extension (a name with an extension is
+ * taken as the file it names). The vault ACL treats such a path as an exact
+ * object key, so
+ * `hq files share knowledge --with x` used to grant an object named
+ * "knowledge" and nothing under `knowledge/` (DEV-5173: members were blocked
+ * under a folder their admin had "shared"). The name alone does not decide
+ * whether it is a folder (`Makefile`, `bin/hq`); resolveBareSharePrefix asks
+ * the vault.
+ */
+export declare function looksLikeBareFolderPrefix(prefix: string): boolean;
+/**
+ * Refuse a bare prefix that would become a malformed grant if it were
+ * rewritten to a folder glob: a `*` inside a segment (`**`, `know*`) or an
+ * empty segment (`/knowledge`, `a//b`). Returns the error text, or null.
+ */
+export declare function malformedBareSharePrefix(prefix: string): string | null;
+export type BareSharePrefixResolution = {
+    kind: "unchanged";
+    prefix: string;
+} | {
+    kind: "folder";
+    prefix: string;
+    folderGlob: string;
+} | {
+    kind: "refused";
+    prefix: string;
+    message: string;
+};
+/**
+ * Decide what a bare prefix means by looking it up in the vault. Rewrite `X`
+ * to `X/*` only when `X/` has children and no object `X` exists. Keep `X` when
+ * only the object exists. Refuse when both exist, when neither does, or when
+ * the lookup fails; the caller exits non-zero and points to --exact or `X/*`.
+ */
+export declare function resolveBareSharePrefix(params: {
+    token: string;
+    companyUid: string;
+    prefix: string;
+}): Promise<BareSharePrefixResolution>;
 /** Server response shape for POST /v1/files/delete. */
 export interface FilesDeleteResponse {
     prefix: string;