@indigoai-us/hq-cli 5.30.0 → 5.32.0

package/dist/commands/files-browse.js

@@ -34,7 +34,7 @@
  * methods and `grantPathToPrefix` from hq-cloud.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="73529786-7369-5356-a6a8-4d55bd553147")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="cad165f9-6445-5434-969b-e0705274aa56")}catch(e){}}();
 import chalk from "chalk";
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -559,9 +559,12 @@ export function registerFilesBrowseCommands(filesCmd) {
         "bucket-relative (omit it to list the vault root). Mutually exclusive " +
         "with --company.")
         .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
-        .action(async (pathArg, options) => {
+        .action(async (pathArg, options, command) => {
         try {
-            if (options.personal && options.company) {
+            // `--company` is declared on the parent `files` group, so commander
+            // binds it there — read merged opts to see it from the subcommand.
+            const company = command.optsWithGlobals().company;
+            if (options.personal && company) {
                 throw new Error("--personal and --company are mutually exclusive. Pick one.");
             }
             const accessToken = await ensureCognitoToken();
@@ -594,12 +597,12 @@ export function registerFilesBrowseCommands(filesCmd) {
                     "browse your personal vault.");
             }
             // Resolve slug — CLI flag wins, otherwise parse from path arg.
-            const slug = options.company ?? parseCompanySlugFromPath(pathArg);
+            const slug = company ?? parseCompanySlugFromPath(pathArg);
             // If the user passed `--company` AND the path doesn't begin with
             // companies/<that-slug>/, refuse — we'd otherwise vend creds for
             // one company and list keys from another tree, which never makes
             // sense (defense in depth against operator typos).
-            if (options.company !== undefined) {
+            if (company !== undefined) {
                 const fromPath = (() => {
                     try {
                         return parseCompanySlugFromPath(pathArg);
@@ -608,8 +611,8 @@ export function registerFilesBrowseCommands(filesCmd) {
                         return undefined;
                     }
                 })();
-                if (fromPath && fromPath !== options.company) {
-                    throw new Error(`--company '${options.company}' disagrees with path slug '${fromPath}'.`);
+                if (fromPath && fromPath !== company) {
+                    throw new Error(`--company '${company}' disagrees with path slug '${fromPath}'.`);
                 }
             }
             // Confirm the slug resolves to a known membership — same pattern
@@ -644,9 +647,11 @@ export function registerFilesBrowseCommands(filesCmd) {
         .option("--personal", "Read from the caller's canonical personal vault. <path> is treated as " +
         "bucket-relative. Mutually exclusive with --company.")
         .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
-        .action(async (keyArg, options) => {
+        .action(async (keyArg, options, command) => {
         try {
-            if (options.personal && options.company) {
+            // `--company` is bound on the parent `files` group — read merged opts.
+            const company = command.optsWithGlobals().company;
+            if (options.personal && company) {
                 throw new Error("--personal and --company are mutually exclusive. Pick one.");
             }
             const accessToken = await ensureCognitoToken();
@@ -673,8 +678,8 @@ export function registerFilesBrowseCommands(filesCmd) {
                 }
                 return;
             }
-            const slug = options.company ?? parseCompanySlugFromPath(keyArg);
-            if (options.company !== undefined) {
+            const slug = company ?? parseCompanySlugFromPath(keyArg);
+            if (company !== undefined) {
                 const fromPath = (() => {
                     try {
                         return parseCompanySlugFromPath(keyArg);
@@ -683,8 +688,8 @@ export function registerFilesBrowseCommands(filesCmd) {
                         return undefined;
                     }
                 })();
-                if (fromPath && fromPath !== options.company) {
-                    throw new Error(`--company '${options.company}' disagrees with path slug '${fromPath}'.`);
+                if (fromPath && fromPath !== company) {
+                    throw new Error(`--company '${company}' disagrees with path slug '${fromPath}'.`);
                 }
             }
             await getCompanyUid(accessToken, slug);
@@ -710,21 +715,23 @@ export function registerFilesBrowseCommands(filesCmd) {
         .command("shared-with-me")
         .description("List the files/prefixes explicitly shared with you. Omit --company to roll up across every company you're a member of. Pure read — no download, no credentials vended. Owner/admin role-bypass access is NOT listed (only explicit grants).")
         .option("--company <slug>", "Scope to a single company (defaults to a cross-company roll-up).")
-        .action(async (options) => {
+        .action(async (options, command) => {
         try {
+            // `--company` is bound on the parent `files` group — read merged opts.
+            const company = command.optsWithGlobals().company;
             const accessToken = await ensureCognitoToken();
             const vaultConfig = buildVaultConfig(accessToken);
             const client = new VaultClient(vaultConfig);
             let companyUid;
-            if (options.company) {
+            if (company) {
                 // Confirm membership + resolve UID, same early-failure pattern as
                 // browse/cat. Roll-up mode skips this and fans out internally.
-                companyUid = await getCompanyUid(accessToken, options.company);
+                companyUid = await getCompanyUid(accessToken, company);
             }
             const rows = await runSharedWithMe({
                 vaultClient: client,
                 companyUid,
-                companySlug: options.company,
+                companySlug: company,
             });
             console.log(formatSharedWithMeTable(rows));
         }
@@ -738,9 +745,12 @@ export function registerFilesBrowseCommands(filesCmd) {
         .description("Search vault object keys (case-insensitive path/name match) under a company without downloading. Requires --company (or --personal). Content search is not supported in v1.")
         .option("--company <slug>", "Company slug to search.")
         .option("--personal", "Search the caller's canonical personal vault. Mutually exclusive with --company.")
-        .action(async (query, options) => {
+        .action(async (query, options, command) => {
         try {
-            if (options.personal && options.company) {
+            // `--company` is declared on the parent `files` group too, so commander
+            // binds it there; read the merged (global+local) opts to see it.
+            const company = command.optsWithGlobals().company;
+            if (options.personal && company) {
                 throw new Error("--personal and --company are mutually exclusive. Pick one.");
             }
             const accessToken = await ensureCognitoToken();
@@ -763,13 +773,13 @@ export function registerFilesBrowseCommands(filesCmd) {
                 console.log(formatBrowseTable(rows));
                 return;
             }
-            if (!options.company) {
+            if (!company) {
                 throw new Error("search: --company <slug> is required (or --personal to search your personal vault).");
             }
-            await getCompanyUid(accessToken, options.company);
+            await getCompanyUid(accessToken, company);
             const rows = await runSearch({
                 query,
-                companySlug: options.company,
+                companySlug: company,
                 vaultClient: client,
                 s3Factory: defaultS3Factory,
                 region: DEFAULT_COGNITO.region,
@@ -787,12 +797,14 @@ export function registerFilesBrowseCommands(filesCmd) {
         .option("--into <dir>", "Write into this directory instead of the in-place companies/<slug>/ location. No pin is registered.")
         .option("--company <slug>", "Company slug (defaults to the slug parsed from <path>).")
         .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
-        .action(async (pathArg, options) => {
+        .action(async (pathArg, options, command) => {
         try {
             const accessToken = await ensureCognitoToken();
             const client = new VaultClient(buildVaultConfig(accessToken));
-            const slug = options.company ?? parseCompanySlugFromPath(pathArg);
-            if (options.company !== undefined) {
+            // `--company` is bound on the parent `files` group — read merged opts.
+            const companyOpt = command.optsWithGlobals().company;
+            const slug = companyOpt ?? parseCompanySlugFromPath(pathArg);
+            if (companyOpt !== undefined) {
                 const fromPath = (() => {
                     try {
                         return parseCompanySlugFromPath(pathArg);
@@ -801,8 +813,8 @@ export function registerFilesBrowseCommands(filesCmd) {
                         return undefined;
                     }
                 })();
-                if (fromPath && fromPath !== options.company) {
-                    throw new Error(`--company '${options.company}' disagrees with path slug '${fromPath}'.`);
+                if (fromPath && fromPath !== companyOpt) {
+                    throw new Error(`--company '${companyOpt}' disagrees with path slug '${fromPath}'.`);
                 }
             }
             await getCompanyUid(accessToken, slug);
@@ -827,4 +839,4 @@ export function registerFilesBrowseCommands(filesCmd) {
     });
 }
 //# sourceMappingURL=files-browse.js.map
-//# debugId=73529786-7369-5356-a6a8-4d55bd553147
+//# debugId=cad165f9-6445-5434-969b-e0705274aa56

package/dist/commands/group-grants.d.ts

@@ -0,0 +1,76 @@
+import { Command } from "commander";
+/**
+ * `hq group-grants` — manage cross-company group access grants.
+ *
+ * A *group grant* lets a group defined in a SOURCE company be granted a role
+ * on a TARGET company. The hq-pro API authorizes the operation against the
+ * TARGET company (the caller must be able to invite into it). The CLI is a
+ * thin client — it passes the right params and surfaces the server's 403 as an
+ * actionable cross-tenant permission error. NO authorization is reimplemented
+ * here.
+ *
+ * Backend contract (hq-pro feature/agency-cross-company-group-grants):
+ *   - POST /group-grants            { groupId, sourceCompanyUid, targetCompanyUid, role }
+ *   - POST /group-grants/revoke     { groupId, sourceCompanyUid, targetCompanyUid }
+ *   - GET  /group-grants/outbound?sourceCompanyUid&groupId
+ *   - GET  /group-grants/inbound?companyUid
+ *
+ * All require a Cognito idToken bearer; 403 (code FORBIDDEN) on authz failure.
+ */
+export declare const VALID_GRANT_ROLES: Set<string>;
+export type GrantRole = "owner" | "admin" | "member" | "guest";
+export interface GroupGrant {
+    groupId: string;
+    sourceCompanyUid: string;
+    targetCompanyUid: string;
+    role: string;
+    grantedBy?: string;
+    grantedAt?: string;
+}
+export interface GrantGroupOptions {
+    groupId: string;
+    sourceCompanyUid: string;
+    targetCompanyUid: string;
+    role: string;
+    token: string;
+}
+export interface RevokeGroupGrantOptions {
+    groupId: string;
+    sourceCompanyUid: string;
+    targetCompanyUid: string;
+    token: string;
+}
+/**
+ * Typed HTTP error mirroring members.ts's `InviteHttpError`. Carries the
+ * server status + optional error `code` (e.g. `FORBIDDEN`) so the command
+ * layer can render an actionable message and exit non-zero.
+ */
+export declare class GrantHttpError extends Error {
+    status: number;
+    code?: string | undefined;
+    constructor(status: number, message: string, code?: string | undefined);
+}
+/**
+ * Map a `GrantHttpError` onto an actionable, human-readable message. The 403
+ * branch is the story's key cross-tenant case: authorization is enforced
+ * against the TARGET company, so the message names the target the caller
+ * lacks rights on.
+ */
+export declare function formatGrantHttpError(status: number, fallback: string, ctx?: {
+    targetCompany?: string;
+    code?: string;
+}): string;
+/**
+ * POST /group-grants — grant a group's access to a target company at a role.
+ * Pure-ish: validates inputs, then calls the API client. Throws
+ * `GrantHttpError` on non-2xx so the command layer surfaces it.
+ */
+export declare function grantGroup(options: GrantGroupOptions): Promise<GroupGrant>;
+/** POST /group-grants/revoke — remove a group's grant on a target company. */
+export declare function revokeGroupGrant(options: RevokeGroupGrantOptions): Promise<void>;
+/** GET /group-grants/outbound — grants a source company's group(s) hold. */
+export declare function listOutboundGrants(token: string, sourceCompanyUid: string, groupId?: string): Promise<GroupGrant[]>;
+/** GET /group-grants/inbound — grants other companies' groups hold on us. */
+export declare function listInboundGrants(token: string, companyUid: string): Promise<GroupGrant[]>;
+export declare function registerGroupGrantsCommand(program: Command): void;
+//# sourceMappingURL=group-grants.d.ts.map

package/dist/commands/group-grants.js

@@ -0,0 +1,296 @@
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="eff1a01a-1996-5c23-aaf4-084319d454fc")}catch(e){}}();
+import chalk from "chalk";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
+import { GROUP_ID_PATTERN } from "./_patterns.js";
+/**
+ * `hq group-grants` — manage cross-company group access grants.
+ *
+ * A *group grant* lets a group defined in a SOURCE company be granted a role
+ * on a TARGET company. The hq-pro API authorizes the operation against the
+ * TARGET company (the caller must be able to invite into it). The CLI is a
+ * thin client — it passes the right params and surfaces the server's 403 as an
+ * actionable cross-tenant permission error. NO authorization is reimplemented
+ * here.
+ *
+ * Backend contract (hq-pro feature/agency-cross-company-group-grants):
+ *   - POST /group-grants            { groupId, sourceCompanyUid, targetCompanyUid, role }
+ *   - POST /group-grants/revoke     { groupId, sourceCompanyUid, targetCompanyUid }
+ *   - GET  /group-grants/outbound?sourceCompanyUid&groupId
+ *   - GET  /group-grants/inbound?companyUid
+ *
+ * All require a Cognito idToken bearer; 403 (code FORBIDDEN) on authz failure.
+ */
+export const VALID_GRANT_ROLES = new Set(["owner", "admin", "member", "guest"]);
+/**
+ * Typed HTTP error mirroring members.ts's `InviteHttpError`. Carries the
+ * server status + optional error `code` (e.g. `FORBIDDEN`) so the command
+ * layer can render an actionable message and exit non-zero.
+ */
+export class GrantHttpError extends Error {
+    status;
+    code;
+    constructor(status, message, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "GrantHttpError";
+    }
+}
+/**
+ * Map a `GrantHttpError` onto an actionable, human-readable message. The 403
+ * branch is the story's key cross-tenant case: authorization is enforced
+ * against the TARGET company, so the message names the target the caller
+ * lacks rights on.
+ */
+export function formatGrantHttpError(status, fallback, ctx = {}) {
+    if (status === 401)
+        return "Not authenticated — please run `hq login`";
+    if (status === 403) {
+        const target = ctx.targetCompany ? ` '${ctx.targetCompany}'` : "";
+        return (`Permission denied: you must be an owner or admin of the target company${target} to grant a group into it. ` +
+            "The grant is authorized against the target company — ask an owner/admin there, or have them enable adminCanInvite.");
+    }
+    if (status === 404) {
+        return `Not found: ${fallback}. Check the group id and that both companies exist.`;
+    }
+    if (status === 409) {
+        return `That grant already exists: ${fallback}`;
+    }
+    if (status >= 500)
+        return `Server error: ${fallback}`;
+    return fallback;
+}
+function shortDate(iso) {
+    return iso.slice(0, 10);
+}
+/**
+ * POST /group-grants — grant a group's access to a target company at a role.
+ * Pure-ish: validates inputs, then calls the API client. Throws
+ * `GrantHttpError` on non-2xx so the command layer surfaces it.
+ */
+export async function grantGroup(options) {
+    if (!GROUP_ID_PATTERN.test(options.groupId)) {
+        throw new Error(`Invalid group id '${options.groupId}': must match grp_<alphanumeric, underscore, hyphen>`);
+    }
+    if (!VALID_GRANT_ROLES.has(options.role)) {
+        throw new Error(`Invalid role '${options.role}': must be one of owner, admin, member, guest`);
+    }
+    if (options.sourceCompanyUid === options.targetCompanyUid) {
+        throw new Error("Source and target companies are the same — a group grant must cross company boundaries.");
+    }
+    const res = await vaultApiFetch({
+        token: options.token,
+        path: "/group-grants",
+        method: "POST",
+        body: {
+            groupId: options.groupId,
+            sourceCompanyUid: options.sourceCompanyUid,
+            targetCompanyUid: options.targetCompanyUid,
+            role: options.role,
+        },
+    });
+    if (!res.ok) {
+        const err = (await res.json().catch(() => ({})));
+        throw new GrantHttpError(res.status, err.message ?? err.error ?? res.statusText, err.code);
+    }
+    const data = (await res.json());
+    return (data.grant ?? {
+        groupId: options.groupId,
+        sourceCompanyUid: options.sourceCompanyUid,
+        targetCompanyUid: options.targetCompanyUid,
+        role: options.role,
+    });
+}
+/** POST /group-grants/revoke — remove a group's grant on a target company. */
+export async function revokeGroupGrant(options) {
+    if (!GROUP_ID_PATTERN.test(options.groupId)) {
+        throw new Error(`Invalid group id '${options.groupId}': must match grp_<alphanumeric, underscore, hyphen>`);
+    }
+    const res = await vaultApiFetch({
+        token: options.token,
+        path: "/group-grants/revoke",
+        method: "POST",
+        body: {
+            groupId: options.groupId,
+            sourceCompanyUid: options.sourceCompanyUid,
+            targetCompanyUid: options.targetCompanyUid,
+        },
+    });
+    if (!res.ok) {
+        const err = (await res.json().catch(() => ({})));
+        throw new GrantHttpError(res.status, err.message ?? err.error ?? res.statusText, err.code);
+    }
+}
+/** GET /group-grants/outbound — grants a source company's group(s) hold. */
+export async function listOutboundGrants(token, sourceCompanyUid, groupId) {
+    const query = { sourceCompanyUid };
+    if (groupId)
+        query.groupId = groupId;
+    const res = await vaultApiFetch({
+        token,
+        path: "/group-grants/outbound",
+        query,
+    });
+    if (!res.ok) {
+        const err = (await res.json().catch(() => ({})));
+        throw new GrantHttpError(res.status, err.message ?? err.error ?? res.statusText, err.code);
+    }
+    const data = (await res.json());
+    return data.grants ?? [];
+}
+/** GET /group-grants/inbound — grants other companies' groups hold on us. */
+export async function listInboundGrants(token, companyUid) {
+    const res = await vaultApiFetch({
+        token,
+        path: "/group-grants/inbound",
+        query: { companyUid },
+    });
+    if (!res.ok) {
+        const err = (await res.json().catch(() => ({})));
+        throw new GrantHttpError(res.status, err.message ?? err.error ?? res.statusText, err.code);
+    }
+    const data = (await res.json());
+    return data.grants ?? [];
+}
+function printGrantsTable(grants) {
+    const idW = Math.max(8, ...grants.map((g) => g.groupId.length));
+    const srcW = Math.max(6, ...grants.map((g) => g.sourceCompanyUid.length));
+    const tgtW = Math.max(6, ...grants.map((g) => g.targetCompanyUid.length));
+    const roleW = Math.max(4, ...grants.map((g) => g.role.length));
+    console.log(chalk.bold([
+        "GROUP_ID".padEnd(idW),
+        "SOURCE".padEnd(srcW),
+        "TARGET".padEnd(tgtW),
+        "ROLE".padEnd(roleW),
+        "GRANTED_AT",
+    ].join("  ")));
+    for (const g of grants) {
+        console.log([
+            g.groupId.padEnd(idW),
+            g.sourceCompanyUid.padEnd(srcW),
+            g.targetCompanyUid.padEnd(tgtW),
+            g.role.padEnd(roleW),
+            g.grantedAt ? shortDate(g.grantedAt) : "",
+        ].join("  "));
+    }
+}
+export function registerGroupGrantsCommand(program) {
+    const grants = program
+        .command("group-grants")
+        .description("Grant a group's access to another company (cross-company), and revoke or inspect those grants")
+        .option("--company <slug>", "Source company slug (the company that owns the group; resolves to sourceCompanyUid)");
+    grants
+        .command("grant <groupId> <targetCompany>")
+        .description("Grant a group (from the source company) access to <targetCompany> at a role")
+        .option("--role <role>", "Role the group receives on the target company: owner, admin, member, or guest", "member")
+        .action(async (groupId, targetCompany, opts) => {
+        try {
+            const token = await ensureCognitoToken();
+            const sourceSlug = grants.opts().company;
+            const sourceCompanyUid = await getCompanyUid(token, sourceSlug);
+            const targetCompanyUid = await getCompanyUid(token, targetCompany);
+            const grant = await grantGroup({
+                groupId,
+                sourceCompanyUid,
+                targetCompanyUid,
+                role: opts.role,
+                token,
+            });
+            console.log(chalk.green(`Granted group '${grant.groupId}' access to '${targetCompany}' as ${grant.role}`));
+            console.log(chalk.dim(`  source: ${grant.sourceCompanyUid}  →  target: ${grant.targetCompanyUid}`));
+        }
+        catch (err) {
+            if (err instanceof GrantHttpError) {
+                console.error(chalk.red(formatGrantHttpError(err.status, err.message, {
+                    targetCompany,
+                    code: err.code,
+                })));
+                process.exit(1);
+            }
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    grants
+        .command("revoke <groupId> <targetCompany>")
+        .description("Revoke a group's grant on <targetCompany>")
+        .action(async (groupId, targetCompany) => {
+        try {
+            const token = await ensureCognitoToken();
+            const sourceSlug = grants.opts().company;
+            const sourceCompanyUid = await getCompanyUid(token, sourceSlug);
+            const targetCompanyUid = await getCompanyUid(token, targetCompany);
+            await revokeGroupGrant({
+                groupId,
+                sourceCompanyUid,
+                targetCompanyUid,
+                token,
+            });
+            console.log(chalk.green(`Revoked group '${groupId}' grant on '${targetCompany}'`));
+        }
+        catch (err) {
+            if (err instanceof GrantHttpError) {
+                console.error(chalk.red(formatGrantHttpError(err.status, err.message, {
+                    targetCompany,
+                    code: err.code,
+                })));
+                process.exit(1);
+            }
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    grants
+        .command("outbound")
+        .description("List grants the source company's groups hold on other companies")
+        .option("--group <groupId>", "Filter to a single group id")
+        .action(async (opts) => {
+        try {
+            const token = await ensureCognitoToken();
+            const sourceSlug = grants.opts().company;
+            const sourceCompanyUid = await getCompanyUid(token, sourceSlug);
+            const list = await listOutboundGrants(token, sourceCompanyUid, opts.group);
+            if (list.length === 0) {
+                console.log(chalk.gray("No outbound group grants."));
+                return;
+            }
+            printGrantsTable(list);
+        }
+        catch (err) {
+            if (err instanceof GrantHttpError) {
+                console.error(chalk.red(formatGrantHttpError(err.status, err.message)));
+                process.exit(1);
+            }
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    grants
+        .command("inbound")
+        .description("List grants other companies' groups hold on this company")
+        .action(async () => {
+        try {
+            const token = await ensureCognitoToken();
+            const companySlug = grants.opts().company;
+            const companyUid = await getCompanyUid(token, companySlug);
+            const list = await listInboundGrants(token, companyUid);
+            if (list.length === 0) {
+                console.log(chalk.gray("No inbound group grants."));
+                return;
+            }
+            printGrantsTable(list);
+        }
+        catch (err) {
+            if (err instanceof GrantHttpError) {
+                console.error(chalk.red(formatGrantHttpError(err.status, err.message)));
+                process.exit(1);
+            }
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=group-grants.js.map
+//# debugId=eff1a01a-1996-5c23-aaf4-084319d454fc

package/dist/commands/pack-install.d.ts

@@ -34,12 +34,44 @@
  * from each pack's package.yaml; rationale lives in the layout-fix PR.)
  */
 import type { PackManifest } from '../types.js';
+export type Transport = 'npm' | 'git' | 'local';
+export declare function classify(source: string): Transport;
+/**
+ * Parse a git source's '#<...>' fragment into { url, subpath, ref }.
+ * Disambiguation: fragment containing '/' is a subpath (optionally with
+ * '@<ref>' suffix); fragment without '/' is a ref.
+ */
+export declare function parseGitFragment(source: string): {
+    url: string;
+    subpath?: string;
+    ref?: string;
+};
 /**
  * sourceMatchesPackPattern — exported for the dispatcher in pkg-install.ts
  * so it can decide whether to route to the new content-pack handler or fall
  * back to the legacy registry flow.
  */
 export declare function sourceMatchesPackPattern(source: string): boolean;
+export interface LatestResult {
+    transport: Transport;
+    /** Identifier of the currently-installed pack (sha for git, version for npm). */
+    current?: string;
+    /** Latest available identifier from the remote. */
+    latest?: string;
+    /** true/false when a comparison was possible; null when undeterminable (local). */
+    updateAvailable: boolean | null;
+    error?: string;
+}
+/**
+ * Probe whether a newer version of an already-installed pack is available,
+ * WITHOUT fetching or installing. Reuses the same git/npm primitives as the
+ * install path. Never throws — network/parse failures return
+ * `{ updateAvailable: null, error }` so callers (the menubar) stay resilient.
+ *
+ * @param source         the stamped `source:` from the installed package.yaml
+ * @param installedVersion the installed pack's manifest `version` (npm compare)
+ */
+export declare function resolveLatest(source: string, installedVersion?: string): LatestResult;
 /**
  * Install the fetched payload to `<hqRoot>/core/packages/<pkg.name>/` (HQ
  * v12+ layout). The HQ template (`hq-core` / `hq-core-staging`) ships
@@ -86,11 +118,24 @@ export declare function stampInstallSource(destDir: string, source: string): voi
  * own scan.
  *
  * Exported for tests.
+ *
+ * `quiet` keeps the script's stdout off our stdout (it routes only stderr
+ * through, and sets HQ_SCAN_QUIET=1) so callers emitting machine-readable
+ * JSON — e.g. `hq packs uninstall --json` — produce clean output.
  */
-export declare function runScanPackages(hqRoot: string): void;
+export declare function runScanPackages(hqRoot: string, opts?: {
+    quiet?: boolean;
+}): void;
 export interface InstallPackOptions {
     allowHooks?: boolean;
     followBranch?: boolean;
+    /**
+     * Route this function's human output to stderr (and silence scan-packages
+     * stdout) so a caller emitting machine-readable JSON keeps stdout clean.
+     * The fetch tools are already quiet/stderr-only (`npm pack --silent`,
+     * `rsync -a`, `git clone` progress -> stderr), so this is sufficient.
+     */
+    quiet?: boolean;
 }
 export declare function installPack(source: string, opts?: InstallPackOptions): Promise<void>;
 //# sourceMappingURL=pack-install.d.ts.map