@indigoai-us/hq-cli 5.31.0 → 5.33.0

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

package/dist/commands/pack-install.js

@@ -34,7 +34,7 @@
  * from each pack's package.yaml; rationale lives in the layout-fix PR.)
  */
 
-!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]="845e5459-a7ba-53ca-a04c-dd055fabe52d")}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]="08d95744-5e4f-5938-8a49-4f57a9bf042f")}catch(e){}}();
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -45,8 +45,9 @@ import chalk from 'chalk';
 import semverSatisfies from 'semver/functions/satisfies.js';
 import semverValid from 'semver/functions/valid.js';
 import semverValidRange from 'semver/ranges/valid.js';
+import semverGt from 'semver/functions/gt.js';
 import { findHqRoot } from '../utils/manifest.js';
-function classify(source) {
+export function classify(source) {
     if (source.startsWith('@'))
         return 'npm';
     if (source.startsWith('http://') ||
@@ -93,7 +94,7 @@ function expandGithubShorthand(url) {
  * Disambiguation: fragment containing '/' is a subpath (optionally with
  * '@<ref>' suffix); fragment without '/' is a ref.
  */
-function parseGitFragment(source) {
+export function parseGitFragment(source) {
     const hashAt = source.indexOf('#');
     if (hashAt < 0)
         return { url: source };
@@ -273,6 +274,75 @@ function isNamedRef(url, ref) {
         return false;
     }
 }
+/** Extract the ref (sha or named ref) recorded in a stamped git source. */
+function gitRefFromSource(source) {
+    const { subpath, ref } = parseGitFragment(source);
+    // For 'url#subpath@ref' parseGitFragment returns ref; for 'url#ref' likewise.
+    // A bare 'url#subpath' (no @ref) has no ref.
+    void subpath;
+    return ref;
+}
+/**
+ * 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 function resolveLatest(source, installedVersion) {
+    let transport;
+    try {
+        transport = classify(source);
+    }
+    catch (e) {
+        return { transport: 'local', updateAvailable: null, error: e.message };
+    }
+    if (transport === 'local') {
+        return { transport, updateAvailable: null, error: 'local source — re-run to re-sync' };
+    }
+    if (transport === 'npm') {
+        const pkg = stripVersion(source);
+        const current = installedVersion ?? (source.lastIndexOf('@') > 0 ? source.slice(source.lastIndexOf('@') + 1) : undefined);
+        try {
+            const latest = execFileSync('npm', ['view', pkg, 'version'], {
+                encoding: 'utf-8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+            }).trim();
+            const updateAvailable = current && latest ? semverGt(latest, current) : null;
+            return { transport, current, latest, updateAvailable };
+        }
+        catch (e) {
+            return { transport, current, updateAvailable: null, error: `npm view failed: ${e.message}` };
+        }
+    }
+    // git
+    const parsed = parseGitFragment(source);
+    let url;
+    try {
+        url = expandGithubShorthand(parsed.url);
+    }
+    catch (e) {
+        return { transport, updateAvailable: null, error: e.message };
+    }
+    const current = gitRefFromSource(source);
+    // If install followed a named ref (branch/tag), compare that ref's tip;
+    // otherwise (default SHA-pin) compare the default branch HEAD.
+    const refArg = current && isNamedRef(url, current) ? current : 'HEAD';
+    try {
+        const out = execFileSync('git', ['ls-remote', url, refArg], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        const latest = out.split(/\s+/)[0] || undefined;
+        const updateAvailable = current && latest ? !latest.startsWith(current) && !current.startsWith(latest) : null;
+        return { transport, current, latest, updateAvailable };
+    }
+    catch (e) {
+        return { transport, current, updateAvailable: null, error: `git ls-remote failed: ${e.message}` };
+    }
+}
 // ---------------------------------------------------------------------------
 // Manifest validation (spec §Validation, 10 checks)
 // ---------------------------------------------------------------------------
@@ -509,20 +579,26 @@ export function stampInstallSource(destDir, source) {
  * 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 function runScanPackages(hqRoot) {
+export function runScanPackages(hqRoot, opts = {}) {
     const script = path.join(hqRoot, 'core', 'scripts', 'scan-packages.sh');
     if (!fs.existsSync(script)) {
-        console.log(chalk.dim(`  (core/scripts/scan-packages.sh not present — skipping auto-wire; ` +
-            `will run on next session start)`));
+        if (!opts.quiet) {
+            console.log(chalk.dim(`  (core/scripts/scan-packages.sh not present — skipping auto-wire; ` +
+                `will run on next session start)`));
+        }
         return;
     }
     const r = spawnSync('bash', [script], {
         cwd: hqRoot,
-        env: { ...process.env, HQ_ROOT: hqRoot },
-        stdio: 'inherit',
+        env: { ...process.env, HQ_ROOT: hqRoot, ...(opts.quiet ? { HQ_SCAN_QUIET: '1' } : {}) },
+        stdio: opts.quiet ? ['ignore', 'ignore', 'inherit'] : 'inherit',
     });
-    if (r.status !== 0) {
+    if (r.status !== 0 && !opts.quiet) {
         console.log(chalk.yellow('  scan-packages.sh exited non-zero; see output above.'));
     }
 }
@@ -530,7 +606,10 @@ export async function installPack(source, opts = {}) {
     const transport = classify(source);
     const hqRoot = findHqRoot();
     const hqVersion = readHqVersion(hqRoot);
-    console.log(chalk.dim(`→ transport: ${transport}; source: ${source}`));
+    const say = opts.quiet
+        ? (...a) => console.error(...a)
+        : (...a) => console.log(...a);
+    say(chalk.dim(`-> transport: ${transport}; source: ${source}`));
     const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hq-pack-'));
     try {
         let fetched;
@@ -549,18 +628,18 @@ export async function installPack(source, opts = {}) {
         if (pkg.conditional) {
             const allowed = await confirmConditional(pkg, opts.allowHooks ?? false);
             if (!allowed) {
-                console.log(chalk.red('Install aborted (conditional predicate not approved).'));
+                say(chalk.red('Install aborted (conditional predicate not approved).'));
                 return;
             }
             const ok = evalConditional(pkg.conditional);
             if (!ok) {
-                console.log(chalk.yellow(`Skipping ${pkg.name}: conditional "${pkg.conditional}" returned non-zero.`));
+                say(chalk.yellow(`Skipping ${pkg.name}: conditional "${pkg.conditional}" returned non-zero.`));
                 return;
             }
         }
         const confirmed = await confirmHooks(pkg, opts.allowHooks ?? false);
         if (!confirmed) {
-            console.log(chalk.red('Install aborted (hooks denied).'));
+            say(chalk.red('Install aborted (hooks denied).'));
             return;
         }
         const destDir = installToPackages(fetched.payloadDir, pkg, hqRoot);
@@ -573,9 +652,9 @@ export async function installPack(source, opts = {}) {
         // re-runs. Stamping the literal input (not the resolved SHA/version)
         // matches the verbatim equality check in setup.sh.
         stampInstallSource(destDir, source);
-        runScanPackages(hqRoot);
-        console.log(chalk.green(`\n✓ Installed ${pkg.name}@${pkg.version} → ${path.relative(hqRoot, destDir)}/`));
-        console.log(chalk.dim(`  Wired ${Object.values(pkg.contributes).flat().filter(Boolean).length} ` +
+        runScanPackages(hqRoot, { quiet: opts.quiet });
+        say(chalk.green(`\nOK Installed ${pkg.name}@${pkg.version} -> ${path.relative(hqRoot, destDir)}/`));
+        say(chalk.dim(`  Wired ${Object.values(pkg.contributes).flat().filter(Boolean).length} ` +
             `contribution(s) into host-side paths.`));
     }
     finally {
@@ -583,4 +662,4 @@ export async function installPack(source, opts = {}) {
     }
 }
 //# sourceMappingURL=pack-install.js.map
-//# debugId=845e5459-a7ba-53ca-a04c-dd055fabe52d
+//# debugId=08d95744-5e4f-5938-8a49-4f57a9bf042f

package/dist/commands/packs.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `hq packs` -- lifecycle for CONTENT packs (the ones installed via
+ * `hq install <source>` that live in `core/packages/hq-pack-<name>/`).
+ *
+ *   hq packs list        Installed packs + curated catalog, with link health.
+ *   hq packs update       Re-install the latest of an installed pack.
+ *   hq packs uninstall    Un-wire + archive a pack (clean, no dangling symlinks).
+ *
+ * Distinct from `hq packages ...` (the entitlement-gated REGISTRY system tracked
+ * in packages/registry.yaml). Content packs have no registry file -- the
+ * filesystem under core/packages/ is the source of truth. Today `hq install`
+ * is the only clean content-pack op; this adds the rest.
+ *
+ * Every subcommand supports `--json` for machine consumers (the HQ Sync
+ * menubar app). JSON is also the default when stdout is not a TTY, matching
+ * the `hq signals` / `hq sources` convention.
+ *
+ * Spec: knowledge/public/hq-core/package-yaml-spec.md.
+ */
+import { Command } from 'commander';
+export declare function registerPacksCommand(parent: Command): void;
+//# sourceMappingURL=packs.d.ts.map