@indigoai-us/hq-cli 5.251.0 → 5.253.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 
+## [5.253.0] — 2026-09-27
+
+### Added
+
+- `hq publish --handle <handle>` publishes a pack under one of the creator handles your
+  account owns, for accounts that own more than one. The server refuses a handle you do
+  not own with a plain message. `--as` is unchanged and cannot be combined with `--handle`.
+
+## [5.252.0] — 2026-09-27
+### Added
+
+- `hq report publish` takes a snapshot of the finished page and publishes it as the report's preview image, using a browser already installed on the computer. A page that names its own preview image keeps it. If no browser is found the report publishes without a preview.
+
 ## [5.251.0] — 2026-09-27
 
 ## [5.250.0] — 2026-09-27

package/dist/command-catalog.generated.d.ts

@@ -418,6 +418,9 @@ export declare const COMMAND_CATALOG: readonly [{
     }, {
         readonly flags: "--on-behalf <handle>";
         readonly description: "Alias for --as.";
+    }, {
+        readonly flags: "--handle <handle>";
+        readonly description: "Publish as one of your own claimed creator handles (for accounts that own more than one). Defaults to your first claimed handle.";
     }];
     readonly subcommands: readonly [];
 }, {

package/dist/command-catalog.generated.js

@@ -530,6 +530,10 @@ export const COMMAND_CATALOG = [
             {
                 "flags": "--on-behalf <handle>",
                 "description": "Alias for --as."
+            },
+            {
+                "flags": "--handle <handle>",
+                "description": "Publish as one of your own claimed creator handles (for accounts that own more than one). Defaults to your first claimed handle."
             }
         ],
         "subcommands": []

package/dist/commands/publish.d.ts

@@ -130,7 +130,7 @@ export declare function unwrapListing(body: Record<string, unknown>): ListingRes
  * locally-resolved author handle — falling back gracefully when the server
  * omits either field.
  */
-export declare function buildListingNotice(status: number, body: Record<string, unknown>, packName: string, packVersion: string): string;
+export declare function buildListingNotice(status: number, body: Record<string, unknown>, packName: string, packVersion: string, selectedHandle?: string): string;
 /**
  * The exact JSON body the deployed `POST /v1/listings` handler expects. Field
  * shapes mirror the server contract: `type` ∈ {skill,worker}, `contributes` is
@@ -151,6 +151,12 @@ export interface ListingRequest {
      * caller is staff (`@getindigo.ai`) and the server has the capability enabled.
      */
     publishAsHandle?: string;
+    /**
+     * OPTIONAL explicit choice among the caller's OWN claimed creator handles
+     * (`hq publish --handle <h>`). The server refuses a handle the caller does
+     * not own (403 CREATOR_HANDLE_NOT_OWNED) instead of falling back.
+     */
+    ownedCreatorHandle?: string;
     /** Base64-encoded gzip pack tarball (pack.tar.gz bytes). */
     tarball: string;
 }
@@ -196,6 +202,7 @@ export interface PublishResult {
  */
 export declare function runPublish(targetPath: string, deps: PublishDeps, opts?: {
     publishAsHandle?: string;
+    creatorHandle?: string;
 }): Promise<PublishResult>;
 export declare function registerPublishCommand(program: Command): void;
 //# sourceMappingURL=publish.d.ts.map

package/dist/commands/publish.js

@@ -231,7 +231,7 @@ export function unwrapListing(body) {
  * locally-resolved author handle — falling back gracefully when the server
  * omits either field.
  */
-export function buildListingNotice(status, body, packName, packVersion) {
+export function buildListingNotice(status, body, packName, packVersion, selectedHandle) {
     if (status === 409) {
         throw new Error(`${packName}@${packVersion} is already published (duplicate version). ` +
             `Bump the version in package.yaml and re-run \`hq publish\`.`);
@@ -246,6 +246,10 @@ export function buildListingNotice(status, body, packName, packVersion) {
     }
     if (status === 401 || status === 403) {
         const code = typeof body.code === 'string' ? body.code : '';
+        if (code === 'CREATOR_HANDLE_NOT_OWNED') {
+            const h = selectedHandle ?? '(unknown)';
+            throw new Error(`You do not own the creator handle ${h}. Claim it first with hq creators apply --handle ${h}.`);
+        }
         if (code === 'NOT_VERIFIED_CREATOR') {
             throw new Error('Only verified creators can publish to the marketplace. ' +
                 'Run `hq creators apply --reason "..."` to request verified-creator access; ' +
@@ -287,6 +291,12 @@ export async function runPublish(targetPath, deps, opts = {}) {
     const publishAsHandle = typeof opts.publishAsHandle === 'string' && opts.publishAsHandle.length > 0
         ? opts.publishAsHandle
         : undefined;
+    const selectedHandle = typeof opts.creatorHandle === 'string' && opts.creatorHandle.trim().length > 0
+        ? opts.creatorHandle.trim().replace(/^@/, '')
+        : undefined;
+    if (publishAsHandle && selectedHandle) {
+        throw new Error('Use either --as or --handle, not both. Nothing was uploaded.');
+    }
     // Resolve a payload dir. We stamp/validate against a temp copy so we never
     // mutate the user's working tree's package.yaml.
     const absTarget = path.resolve(process.cwd(), targetPath);
@@ -335,12 +345,13 @@ export async function runPublish(targetPath, deps, opts = {}) {
             // server is authoritative for attribution either way). Normal: our
             // resolved handle is a backwards-compat fallback under the server's
             // claimed-handle lookup.
-            creatorHandle: publishAsHandle ?? author.handle,
+            creatorHandle: publishAsHandle ?? selectedHandle ?? author.handle,
             ...(publishAsHandle ? { publishAsHandle } : {}),
+            ...(selectedHandle ? { ownedCreatorHandle: selectedHandle } : {}),
             tarball: Buffer.from(tarballBytes).toString('base64'),
         };
         const { status, body } = await deps.upload({ token, listing });
-        const notice = buildListingNotice(status, body, pkg.name, pkg.version);
+        const notice = buildListingNotice(status, body, pkg.name, pkg.version, selectedHandle);
         // Unwrap the `{ listing }` success envelope the server sends so attribution
         // reads the server's resolved handle (fall back to top-level for compat).
         const serverHandle = unwrapListing(body).creatorHandle?.trim();
@@ -362,6 +373,8 @@ export function registerPublishCommand(program) {
         .option('--as <handle>', 'Publish on behalf of a seeded, unclaimed creator by handle (HQ staff only). ' +
         'The listing is attributed to that creator instead of you.')
         .option('--on-behalf <handle>', 'Alias for --as.')
+        .option('--handle <handle>', 'Publish as one of your own claimed creator handles (for accounts that own more than one). ' +
+        'Defaults to your first claimed handle.')
         .action(async (targetPath, options) => {
         try {
             const publishAsHandle = options.as ?? options.onBehalf;
@@ -390,7 +403,7 @@ export function registerPublishCommand(program) {
                 },
                 hqRoot,
                 hqVersion: readHqVersion(hqRoot),
-            }, { publishAsHandle });
+            }, { publishAsHandle, creatorHandle: options.handle });
             console.log(chalk.green(result.notice));
             // Only print the locally-resolved author as a fallback when the server
             // did NOT return its own resolved handle (already in the notice).

package/dist/commands/report.js

@@ -1,4 +1,5 @@
 /** `hq report` — safe channel-report lifecycle commands for bot runbooks. */
+import { snapshotReport } from "../lib/report-snapshot.js";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -339,6 +340,7 @@ async function publishWithOrg(token, report, directory, draft) {
             return deployReportStatic(token, { ...input, org });
         },
         now: () => new Date().toISOString(),
+        snapshot: (source) => snapshotReport(source),
     });
     rememberReportChannelAfterSuccess(published);
     return published;

package/dist/lib/report-publish.d.ts

@@ -91,7 +91,17 @@ export interface ReportPublishDependencies {
         to: string;
         body: string;
     }): Promise<void>;
+    /**
+     * PNG of the finished page for the gallery card, or null when none can be
+     * made. It is given a staged copy of the files as they will be published. Only asked for when the page does not name its own preview image.
+     */
+    snapshot?(directory: string): Promise<Buffer | null>;
 }
+/**
+ * Add a snapshot of the page as its preview when it has none of its own.
+ * A snapshot that fails never fails the publish.
+ */
+export declare function withPreviewSnapshot(source: ReportSource, snapshot: ReportPublishDependencies["snapshot"]): Promise<ReportSource>;
 /**
  * Plain owner DM after a failed run. Suppressed for the publish lock
  * ("already running") so a second run does not page the owner.

package/dist/lib/report-publish.js

@@ -10,12 +10,55 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { gzipSync } from "node:zlib";
+import { REPORT_PREVIEW_FILE } from "./report-snapshot.js";
 import { loadUpdateReportRunbook } from "./report-templates.js";
 /** Mirrors the deploy skill's static-report guardrails. */
 export const REPORT_SOURCE_MAX_BYTES = 25 * 1024 * 1024;
 export const REPORT_BUNDLE_MAX_BYTES = 10 * 1024 * 1024;
 export const REPORT_SOURCE_MAX_FILES = 100;
 export const REPORT_CSP = "default-src 'none'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'; connect-src 'none'; frame-src 'none'; form-action 'none'";
+/**
+ * Write the files exactly as they will be published, protected index.html
+ * included, so the snapshot renders under the same rules as the live page
+ * and never opens the bot's raw page.
+ */
+function stageForSnapshot(files) {
+    const stage = fs.mkdtempSync(path.join(os.tmpdir(), "hq-report-stage-"));
+    for (const file of files) {
+        const target = path.resolve(stage, file.path);
+        if (target !== stage && !target.startsWith(stage + path.sep))
+            continue;
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, Buffer.from(file.content, file.encoding === "base64" ? "base64" : "utf8"));
+    }
+    return stage;
+}
+/**
+ * Add a snapshot of the page as its preview when it has none of its own.
+ * A snapshot that fails never fails the publish.
+ */
+export async function withPreviewSnapshot(source, snapshot) {
+    if (source.previewImage || !snapshot)
+        return source;
+    let image = null;
+    let stage = null;
+    try {
+        stage = stageForSnapshot(source.files);
+        image = await snapshot(stage);
+    }
+    catch {
+        image = null;
+    }
+    finally {
+        if (stage)
+            fs.rmSync(stage, { recursive: true, force: true });
+    }
+    if (!image || image.byteLength === 0)
+        return source;
+    const files = source.files.filter((file) => file.path !== REPORT_PREVIEW_FILE);
+    files.push({ path: REPORT_PREVIEW_FILE, content: image.toString("base64"), encoding: "base64" });
+    return { ...source, files, previewImage: REPORT_PREVIEW_FILE };
+}
 /**
  * Plain owner DM after a failed run. Suppressed for the publish lock
  * ("already running") so a second run does not page the owner.
@@ -277,7 +320,7 @@ export async function publishReport(report, directory, draft, deps) {
                 throw error;
             throw new ReportPublishError("Could not take the report run lock.");
         }
-        const source = loadReportSource(directory);
+        const source = await withPreviewSnapshot(loadReportSource(directory), deps.snapshot);
         const deployment = await deps.deploy({
             slug: reportDeploySlug(current, draft),
             files: source.files,

package/dist/lib/report-snapshot.d.ts

@@ -0,0 +1,14 @@
+/** File name of the snapshot inside the published report. */
+export declare const REPORT_PREVIEW_FILE = "hq-preview.png";
+export declare const REPORT_PREVIEW_WIDTH = 1280;
+export declare const REPORT_PREVIEW_HEIGHT = 720;
+/** First installed browser that can take a snapshot, or null. */
+export declare function findSnapshotBrowser(env?: NodeJS.ProcessEnv, platform?: string, exists?: (file: string) => boolean): string | null;
+export declare function snapshotArgs(indexFile: string, outFile: string, profileDir: string): string[];
+export type SnapshotRunner = (browser: string, args: string[], outFile: string, timeoutMs: number) => Promise<void>;
+/** PNG of the report's first screen, or null when one cannot be made. */
+export declare function snapshotReport(directory: string, options?: {
+    browser?: string | null;
+    run?: SnapshotRunner;
+}): Promise<Buffer | null>;
+//# sourceMappingURL=report-snapshot.d.ts.map

package/dist/lib/report-snapshot.js

@@ -0,0 +1,135 @@
+/**
+ * Report preview snapshot.
+ *
+ * Renders a report's index.html in a browser already installed on this
+ * computer and returns a PNG of the first screen. The snapshot is a nicety:
+ * every failure (no browser, timeout, empty file) returns null and the
+ * publish carries on without a preview.
+ */
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+/** File name of the snapshot inside the published report. */
+export const REPORT_PREVIEW_FILE = "hq-preview.png";
+export const REPORT_PREVIEW_WIDTH = 1280;
+export const REPORT_PREVIEW_HEIGHT = 720;
+const SNAPSHOT_TIMEOUT_MS = 30_000;
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
+const BROWSER_PATHS = {
+    darwin: [
+        "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+        "/Applications/Chromium.app/Contents/MacOS/Chromium",
+        "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+        "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+    ],
+    linux: [
+        "/usr/bin/google-chrome",
+        "/usr/bin/google-chrome-stable",
+        "/usr/bin/chromium",
+        "/usr/bin/chromium-browser",
+        "/snap/bin/chromium",
+    ],
+    win32: [
+        "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+        "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+        "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe",
+    ],
+};
+/** First installed browser that can take a snapshot, or null. */
+export function findSnapshotBrowser(env = process.env, platform = process.platform, exists = fs.existsSync) {
+    const override = (env.HQ_REPORT_BROWSER ?? "").trim();
+    if (override)
+        return exists(override) ? override : null;
+    return (BROWSER_PATHS[platform] ?? []).find((file) => exists(file)) ?? null;
+}
+export function snapshotArgs(indexFile, outFile, profileDir) {
+    return [
+        "--headless=new",
+        "--disable-gpu",
+        "--hide-scrollbars",
+        "--no-first-run",
+        "--no-default-browser-check",
+        "--disable-extensions",
+        `--user-data-dir=${profileDir}`,
+        `--window-size=${REPORT_PREVIEW_WIDTH},${REPORT_PREVIEW_HEIGHT}`,
+        "--virtual-time-budget=5000",
+        `--screenshot=${outFile}`,
+        pathToFileURL(indexFile).toString(),
+    ];
+}
+function stop(child) {
+    if (child.pid === undefined)
+        return;
+    try {
+        // The browser is its own process group, so its helpers stop with it.
+        if (process.platform === "win32")
+            child.kill("SIGKILL");
+        else
+            process.kill(-child.pid, "SIGKILL");
+    }
+    catch {
+        // Already gone.
+    }
+}
+/**
+ * Some browser versions write the snapshot and then never exit. The run is
+ * done when the file is complete, so the browser is stopped at that point
+ * instead of waited on.
+ */
+const runBrowser = (browser, args, outFile, timeoutMs) => new Promise((resolve, reject) => {
+    const child = spawn(browser, args, { stdio: "ignore", detached: process.platform !== "win32" });
+    let lastSize = -1;
+    let settled = false;
+    const finish = (error) => {
+        if (settled)
+            return;
+        settled = true;
+        clearInterval(poll);
+        clearTimeout(limit);
+        stop(child);
+        if (error)
+            reject(error);
+        else
+            resolve();
+    };
+    const poll = setInterval(() => {
+        let size = 0;
+        try {
+            size = fs.statSync(outFile).size;
+        }
+        catch {
+            return;
+        }
+        if (size > 0 && size === lastSize)
+            finish();
+        lastSize = size;
+    }, 250);
+    const limit = setTimeout(() => finish(new Error("The snapshot timed out.")), timeoutMs);
+    child.once("error", (error) => finish(error));
+    child.once("exit", () => finish(fs.existsSync(outFile) ? undefined : new Error("The browser wrote no snapshot.")));
+});
+/** PNG of the report's first screen, or null when one cannot be made. */
+export async function snapshotReport(directory, options = {}) {
+    const browser = options.browser === undefined ? findSnapshotBrowser() : options.browser;
+    if (!browser)
+        return null;
+    const indexFile = path.join(path.resolve(directory), "index.html");
+    if (!fs.existsSync(indexFile))
+        return null;
+    const work = fs.mkdtempSync(path.join(os.tmpdir(), "hq-report-preview-"));
+    try {
+        const outFile = path.join(work, REPORT_PREVIEW_FILE);
+        await (options.run ?? runBrowser)(browser, snapshotArgs(indexFile, outFile, path.join(work, "profile")), outFile, SNAPSHOT_TIMEOUT_MS);
+        const bytes = fs.readFileSync(outFile);
+        return bytes.subarray(0, 4).equals(PNG_MAGIC) ? bytes : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        fs.rmSync(work, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=report-snapshot.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.251.0",
+  "version": "5.253.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {