@indigoai-us/hq-cli 5.33.0 → 5.34.0

package/dist/commands/publish.d.ts

@@ -0,0 +1,186 @@
+/**
+ * hq publish <skill-or-worker-path> — marketplace packer + authenticated upload
+ * (US-004, hq-creator-marketplace).
+ *
+ * Flow:
+ *   1. Refuse if not logged in (cached Cognito session absent/expired) — uploads
+ *      nothing. The author uid is read from the cached idToken's `sub`.
+ *   2. Validate package.yaml with the canonical 10-rule validator
+ *      (`validateManifest` from pack-install.ts) — never duplicate that logic.
+ *      On failure, print the validation error and upload nothing.
+ *   3. Stamp `author` (uid from the idToken `sub`, plus handle/displayName) into
+ *      the pack's package.yaml (AC1). The server re-derives author from the
+ *      Cognito sub too, but the CLI stamps it so the on-disk + published pack
+ *      carry attribution.
+ *   4. Tar (gzip) the payload, base64-encode the bytes, and POST a JSON body to
+ *      `/v1/listings` via vaultApiFetch with the access token. The deployed
+ *      server JSON.parses the body and expects
+ *      { type, name, slug, version, summary?, contributes(string)?,
+ *        creatorHandle?, tarball(base64) }, returning the created listing id +
+ *      `pending_review` status. A 409 (re-publishing the same version) is
+ *      surfaced as a clear duplicate error.
+ *   5. Register/update `modules.yaml` provenance for the published source.
+ *
+ * Reuses the existing CLI plumbing:
+ *   - cognito-session.ts (token cache / access token)
+ *   - vault-api.ts (vaultApiFetch — authed JSON POST to /v1/listings)
+ *   - pack-install.ts:validateManifest (the 10 validation rules)
+ *   - manifest.ts (modules.yaml read/write for provenance)
+ */
+import { Command } from 'commander';
+import type { PackManifest, PackModuleDefinition, ModulesManifest } from '../types.js';
+export interface IdTokenClaims {
+    sub?: string;
+    email?: string;
+    /** Cognito custom attributes / standard claims used for attribution. */
+    'cognito:username'?: string;
+    preferred_username?: string;
+    name?: string;
+}
+/**
+ * Decode a Cognito idToken's payload (no signature verification — this is a
+ * local read of an already-trusted cached token, mirroring whoami.ts/login.ts).
+ * Pure → unit-testable.
+ */
+export declare function peekIdToken(idToken: string): IdTokenClaims;
+export interface ResolvedAuthor {
+    uid: string;
+    handle: string;
+    displayName: string;
+}
+/**
+ * Build the pack `author` block from idToken claims. `uid` is the Cognito
+ * `sub` (AC1). `handle`/`displayName` fall back gracefully so a thin token
+ * still produces a well-shaped author that passes `validateManifest`. Throws
+ * if there is no `sub` (caller is treated as logged-out). Pure.
+ */
+export declare function resolveAuthor(claims: IdTokenClaims): ResolvedAuthor;
+/**
+ * Stamp `author` into a parsed manifest object, returning the YAML text to
+ * write. Existing `author` is overwritten with the resolved attribution so the
+ * publisher's own identity always wins (the server enforces this too). Pure.
+ */
+export declare function stampAuthorYaml(manifest: Record<string, unknown>, author: ResolvedAuthor): string;
+/** Read package.yaml, stamp author, write it back. Returns the stamped author. */
+export declare function stampAuthorIntoPackage(payloadDir: string, author: ResolvedAuthor): void;
+/**
+ * Create a gzipped tarball of `payloadDir` and return its bytes. Uses the same
+ * `tar` argv approach as pack-install.ts (no shell, no new dep). The archive is
+ * written to a tmp file, read back, then removed.
+ */
+export declare function tarballPayload(payloadDir: string): Uint8Array;
+/** The marketplace listing type the server enforces (VALID_TYPES). */
+export type ListingType = 'skill' | 'worker';
+/**
+ * Infer the listing `type` the server requires (exactly "skill" | "worker").
+ *
+ * Rules:
+ *   - An explicit `type` hint in package.yaml wins if it is already a valid
+ *     listing type (lets a pack author override the inference deterministically).
+ *   - Otherwise: a pack that contributes workers → "worker"; one that
+ *     contributes skills → "skill".
+ *   - Ambiguous/both/neither → "skill" (the documented default).
+ * Pure → unit-testable.
+ */
+export declare function inferListingType(pkg: PackManifest): ListingType;
+/**
+ * Derive the marketplace slug from the pack name. By convention pack names are
+ * `^hq-pack-[a-z0-9][a-z0-9-]*$`, so we strip the leading `hq-pack-` to get a
+ * short, valid, non-empty slug (e.g. `hq-pack-demo` → `demo`). If the name does
+ * not carry that prefix we fall back to the full name. Pure.
+ */
+export declare function deriveSlug(packName: string): string;
+/**
+ * Build the SHORT STRING `contributes` summary the server expects (it stores a
+ * string, NOT the structured object). Lists each non-empty contribute category
+ * with its entries, e.g. "workers: alpha, beta; skills: demo". Pure.
+ */
+export declare function summarizeContributes(contributes: PackManifest['contributes']): string;
+/**
+ * Register or update a `package`-strategy module entry in modules.yaml so the
+ * published source has on-disk provenance (AC4). Returns the updated manifest.
+ * Pure (operates on an in-memory manifest); the disk read/write is done by the
+ * caller via `recordProvenance`.
+ */
+export declare function upsertPackProvenance(manifest: ModulesManifest | null, entry: PackModuleDefinition): ModulesManifest;
+/** Read modules.yaml, upsert the provenance entry, write it back. */
+export declare function recordProvenance(hqRoot: string, pkg: PackManifest, source: string): void;
+export interface ListingResponse {
+    id?: string;
+    listingId?: string;
+    status?: string;
+    /** Server-resolved creator handle (prefers the caller's claimed handle). */
+    creatorHandle?: string;
+}
+/**
+ * Unwrap the `POST /v1/listings` SUCCESS envelope. The deployed server returns
+ * the created listing WRAPPED: `{ listing: { listingId, creatorHandle, status,
+ * … } }`. Older/mocked responses return the listing fields at the TOP level.
+ * This reads `body.listing` when present and falls back to the top-level `body`
+ * for backwards-compat. Pure.
+ */
+export declare function unwrapListing(body: Record<string, unknown>): ListingResponse;
+/**
+ * Map a `POST /v1/listings` response into a user-facing success notice. Pure.
+ * Throws a clear error on a duplicate (409) or any non-2xx status so the caller
+ * prints it and exits non-zero.
+ *
+ * The notice uses the REAL listing id and the SERVER-resolved `creatorHandle`
+ * from the (possibly `{ listing }`-wrapped) response body — not the
+ * 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;
+/**
+ * The exact JSON body the deployed `POST /v1/listings` handler expects. Field
+ * shapes mirror the server contract: `type` ∈ {skill,worker}, `contributes` is
+ * a STRING summary (not the structured object), `tarball` is base64 gzip bytes.
+ */
+export interface ListingRequest {
+    type: ListingType;
+    name: string;
+    slug: string;
+    version: string;
+    summary?: string;
+    contributes?: string;
+    creatorHandle?: string;
+    /** Base64-encoded gzip pack tarball (pack.tar.gz bytes). */
+    tarball: string;
+}
+export interface PublishDeps {
+    /** Returns the cached idToken, or null/expired if not logged in. */
+    loadIdToken: () => string | null;
+    /** Returns a non-interactive access token. */
+    getAccessToken: () => Promise<string>;
+    /**
+     * POSTs the listing as a JSON body to `/v1/listings` and returns the parsed
+     * { status, body }. `tarball` is the BASE64-encoded gzip pack bytes — the
+     * server JSON.parses the body and base64-decodes the tarball.
+     */
+    upload: (args: {
+        token: string;
+        listing: ListingRequest;
+    }) => Promise<{
+        status: number;
+        body: Record<string, unknown>;
+    }>;
+    hqRoot: string;
+    /** Reads core.yaml hqVersion for the validator (null when absent). */
+    hqVersion: string | null;
+}
+export interface PublishResult {
+    notice: string;
+    author: ResolvedAuthor;
+    pkg: PackManifest;
+    /** True when the success notice already carries the server's attribution. */
+    serverAttributed: boolean;
+}
+/**
+ * Core publish logic, dependency-injected so it can be unit-tested with mocked
+ * network + a tmp filesystem (no real API, no browser login). Returns the
+ * success notice; throws (uploading nothing) on logged-out or validation
+ * failure.
+ */
+export declare function runPublish(targetPath: string, deps: PublishDeps): Promise<PublishResult>;
+export declare function registerPublishCommand(program: Command): void;
+//# sourceMappingURL=publish.d.ts.map

package/dist/commands/publish.js

@@ -0,0 +1,375 @@
+/**
+ * hq publish <skill-or-worker-path> — marketplace packer + authenticated upload
+ * (US-004, hq-creator-marketplace).
+ *
+ * Flow:
+ *   1. Refuse if not logged in (cached Cognito session absent/expired) — uploads
+ *      nothing. The author uid is read from the cached idToken's `sub`.
+ *   2. Validate package.yaml with the canonical 10-rule validator
+ *      (`validateManifest` from pack-install.ts) — never duplicate that logic.
+ *      On failure, print the validation error and upload nothing.
+ *   3. Stamp `author` (uid from the idToken `sub`, plus handle/displayName) into
+ *      the pack's package.yaml (AC1). The server re-derives author from the
+ *      Cognito sub too, but the CLI stamps it so the on-disk + published pack
+ *      carry attribution.
+ *   4. Tar (gzip) the payload, base64-encode the bytes, and POST a JSON body to
+ *      `/v1/listings` via vaultApiFetch with the access token. The deployed
+ *      server JSON.parses the body and expects
+ *      { type, name, slug, version, summary?, contributes(string)?,
+ *        creatorHandle?, tarball(base64) }, returning the created listing id +
+ *      `pending_review` status. A 409 (re-publishing the same version) is
+ *      surfaced as a clear duplicate error.
+ *   5. Register/update `modules.yaml` provenance for the published source.
+ *
+ * Reuses the existing CLI plumbing:
+ *   - cognito-session.ts (token cache / access token)
+ *   - vault-api.ts (vaultApiFetch — authed JSON POST to /v1/listings)
+ *   - pack-install.ts:validateManifest (the 10 validation rules)
+ *   - manifest.ts (modules.yaml read/write for provenance)
+ */
+
+!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]="73704bc7-d7b1-5c4c-a34e-54edadcc2753")}catch(e){}}();
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import { execFileSync } from 'child_process';
+import chalk from 'chalk';
+import { loadCachedTokens, isExpiring } from '@indigoai-us/hq-cloud';
+import { ensureCognitoToken } from '../utils/cognito-session.js';
+import { vaultApiFetch } from '../utils/vault-api.js';
+import { validateManifest } from './pack-install.js';
+import { findHqRoot, readManifest, writeManifest } from '../utils/manifest.js';
+/**
+ * Decode a Cognito idToken's payload (no signature verification — this is a
+ * local read of an already-trusted cached token, mirroring whoami.ts/login.ts).
+ * Pure → unit-testable.
+ */
+export function peekIdToken(idToken) {
+    try {
+        const payload = idToken.split('.')[1];
+        if (!payload)
+            return {};
+        const pad = payload.length % 4 === 0 ? '' : '='.repeat(4 - (payload.length % 4));
+        const normalized = payload.replace(/-/g, '+').replace(/_/g, '/') + pad;
+        const decoded = JSON.parse(Buffer.from(normalized, 'base64').toString('utf-8'));
+        return decoded;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Build the pack `author` block from idToken claims. `uid` is the Cognito
+ * `sub` (AC1). `handle`/`displayName` fall back gracefully so a thin token
+ * still produces a well-shaped author that passes `validateManifest`. Throws
+ * if there is no `sub` (caller is treated as logged-out). Pure.
+ */
+export function resolveAuthor(claims) {
+    const uid = claims.sub?.trim();
+    if (!uid) {
+        throw new Error('Cached session has no subject (sub) claim — run `hq login` again.');
+    }
+    const handle = claims.preferred_username?.trim() ||
+        claims['cognito:username']?.trim() ||
+        claims.email?.split('@')[0]?.trim() ||
+        uid;
+    const displayName = claims.name?.trim() || claims.email?.trim() || handle;
+    return { uid, handle, displayName };
+}
+// ---------------------------------------------------------------------------
+// package.yaml author stamping
+// ---------------------------------------------------------------------------
+/**
+ * Stamp `author` into a parsed manifest object, returning the YAML text to
+ * write. Existing `author` is overwritten with the resolved attribution so the
+ * publisher's own identity always wins (the server enforces this too). Pure.
+ */
+export function stampAuthorYaml(manifest, author) {
+    const stamped = { ...manifest, author };
+    return yaml.dump(stamped, { lineWidth: -1 });
+}
+/** Read package.yaml, stamp author, write it back. Returns the stamped author. */
+export function stampAuthorIntoPackage(payloadDir, author) {
+    const manifestPath = path.join(payloadDir, 'package.yaml');
+    const parsed = yaml.load(fs.readFileSync(manifestPath, 'utf-8'));
+    fs.writeFileSync(manifestPath, stampAuthorYaml(parsed, author));
+}
+// ---------------------------------------------------------------------------
+// Tarball
+// ---------------------------------------------------------------------------
+/**
+ * Create a gzipped tarball of `payloadDir` and return its bytes. Uses the same
+ * `tar` argv approach as pack-install.ts (no shell, no new dep). The archive is
+ * written to a tmp file, read back, then removed.
+ */
+export function tarballPayload(payloadDir) {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hq-publish-tar-'));
+    const tarPath = path.join(tmpDir, 'pack.tar.gz');
+    try {
+        // `-C payloadDir .` packs the directory contents at the archive root
+        // (package.yaml + skills/ etc. at top level), excluding VCS/junk.
+        execFileSync('tar', [
+            '-czf',
+            tarPath,
+            '-C',
+            payloadDir,
+            '--exclude=.git',
+            '--exclude=node_modules',
+            '--exclude=.DS_Store',
+            '.',
+        ], { stdio: ['ignore', 'ignore', 'inherit'] });
+        return fs.readFileSync(tarPath);
+    }
+    finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+/**
+ * Infer the listing `type` the server requires (exactly "skill" | "worker").
+ *
+ * Rules:
+ *   - An explicit `type` hint in package.yaml wins if it is already a valid
+ *     listing type (lets a pack author override the inference deterministically).
+ *   - Otherwise: a pack that contributes workers → "worker"; one that
+ *     contributes skills → "skill".
+ *   - Ambiguous/both/neither → "skill" (the documented default).
+ * Pure → unit-testable.
+ */
+export function inferListingType(pkg) {
+    const hint = pkg.type;
+    if (hint === 'skill' || hint === 'worker')
+        return hint;
+    const contributes = pkg.contributes ?? {};
+    const hasWorkers = (contributes.workers?.length ?? 0) > 0;
+    const hasSkills = (contributes.skills?.length ?? 0) > 0;
+    // Prefer skill when ambiguous (both) or when neither is present.
+    if (hasWorkers && !hasSkills)
+        return 'worker';
+    return 'skill';
+}
+/**
+ * Derive the marketplace slug from the pack name. By convention pack names are
+ * `^hq-pack-[a-z0-9][a-z0-9-]*$`, so we strip the leading `hq-pack-` to get a
+ * short, valid, non-empty slug (e.g. `hq-pack-demo` → `demo`). If the name does
+ * not carry that prefix we fall back to the full name. Pure.
+ */
+export function deriveSlug(packName) {
+    const stripped = packName.replace(/^hq-pack-/, '');
+    return stripped.length > 0 ? stripped : packName;
+}
+/**
+ * Build the SHORT STRING `contributes` summary the server expects (it stores a
+ * string, NOT the structured object). Lists each non-empty contribute category
+ * with its entries, e.g. "workers: alpha, beta; skills: demo". Pure.
+ */
+export function summarizeContributes(contributes) {
+    const parts = [];
+    for (const [key, entries] of Object.entries(contributes ?? {})) {
+        if (Array.isArray(entries) && entries.length > 0) {
+            parts.push(`${key}: ${entries.join(', ')}`);
+        }
+    }
+    return parts.join('; ');
+}
+// ---------------------------------------------------------------------------
+// Provenance — modules.yaml upsert
+// ---------------------------------------------------------------------------
+/**
+ * Register or update a `package`-strategy module entry in modules.yaml so the
+ * published source has on-disk provenance (AC4). Returns the updated manifest.
+ * Pure (operates on an in-memory manifest); the disk read/write is done by the
+ * caller via `recordProvenance`.
+ */
+export function upsertPackProvenance(manifest, entry) {
+    const next = manifest ?? { version: '1', modules: [] };
+    const idx = next.modules.findIndex((m) => m.name === entry.name);
+    if (idx >= 0) {
+        next.modules[idx] = entry;
+    }
+    else {
+        next.modules.push(entry);
+    }
+    return next;
+}
+/** Read modules.yaml, upsert the provenance entry, write it back. */
+export function recordProvenance(hqRoot, pkg, source) {
+    const entry = {
+        name: pkg.name,
+        strategy: 'package',
+        source,
+        version: pkg.version,
+        installed_at_iso: new Date().toISOString(),
+        // PackManifest.access is 'public'|'private'; module AccessLevel uses
+        // 'public'|'team'|'role:*'. A private pack maps to team scope.
+        access: pkg.access === 'private' ? 'team' : 'public',
+    };
+    const updated = upsertPackProvenance(readManifest(hqRoot), entry);
+    writeManifest(hqRoot, updated);
+}
+/**
+ * Unwrap the `POST /v1/listings` SUCCESS envelope. The deployed server returns
+ * the created listing WRAPPED: `{ listing: { listingId, creatorHandle, status,
+ * … } }`. Older/mocked responses return the listing fields at the TOP level.
+ * This reads `body.listing` when present and falls back to the top-level `body`
+ * for backwards-compat. Pure.
+ */
+export function unwrapListing(body) {
+    const inner = body?.listing;
+    if (inner && typeof inner === 'object') {
+        return inner;
+    }
+    return body;
+}
+/**
+ * Map a `POST /v1/listings` response into a user-facing success notice. Pure.
+ * Throws a clear error on a duplicate (409) or any non-2xx status so the caller
+ * prints it and exits non-zero.
+ *
+ * The notice uses the REAL listing id and the SERVER-resolved `creatorHandle`
+ * from the (possibly `{ listing }`-wrapped) response body — not the
+ * locally-resolved author handle — falling back gracefully when the server
+ * omits either field.
+ */
+export function buildListingNotice(status, body, packName, packVersion) {
+    if (status === 409) {
+        throw new Error(`${packName}@${packVersion} is already published (duplicate version). ` +
+            `Bump the version in package.yaml and re-run \`hq publish\`.`);
+    }
+    if (status === 401 || status === 403) {
+        throw new Error('Not authorized to publish — run `hq login` and ensure your creator account is verified.');
+    }
+    if (status < 200 || status >= 300) {
+        const msg = body.error ?? body.message ?? `HTTP ${status}`;
+        throw new Error(`Publish failed: ${msg}`);
+    }
+    const listing = unwrapListing(body);
+    const id = listing.listingId ?? listing.id ?? '(unknown id)';
+    const listingStatus = listing.status ?? 'pending_review';
+    const serverHandle = listing.creatorHandle?.trim();
+    const attribution = serverHandle ? ` Attributed to @${serverHandle}.` : '';
+    return `Published ${packName}@${packVersion} — listing ${id} (${listingStatus}).${attribution}`;
+}
+/**
+ * Core publish logic, dependency-injected so it can be unit-tested with mocked
+ * network + a tmp filesystem (no real API, no browser login). Returns the
+ * success notice; throws (uploading nothing) on logged-out or validation
+ * failure.
+ */
+export async function runPublish(targetPath, deps) {
+    // 1. Logged-in gate — refuse BEFORE any packing/upload.
+    const idToken = deps.loadIdToken();
+    if (!idToken) {
+        throw new Error('Not logged in — run `hq login` before publishing. Nothing was uploaded.');
+    }
+    const author = resolveAuthor(peekIdToken(idToken));
+    // 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);
+    if (!fs.existsSync(absTarget) || !fs.statSync(absTarget).isDirectory()) {
+        throw new Error(`Not a directory: ${absTarget}`);
+    }
+    const workDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hq-publish-'));
+    const payloadDir = path.join(workDir, 'payload');
+    try {
+        fs.cpSync(absTarget, payloadDir, { recursive: true });
+        // 2. Stamp author (AC1) BEFORE validation so the stamped author is what
+        //    gets validated, packed, and recorded.
+        if (!fs.existsSync(path.join(payloadDir, 'package.yaml'))) {
+            throw new Error(`package.yaml missing from ${absTarget} — nothing was uploaded.`);
+        }
+        stampAuthorIntoPackage(payloadDir, author);
+        // 3. Validate with the canonical 10-rule validator. Throws on any failure;
+        //    we have uploaded nothing at this point.
+        const pkg = validateManifest(payloadDir, deps.hqVersion);
+        // 4. Tar + base64 + authenticated JSON upload. The deployed server
+        //    JSON.parses the body, so we send the gzip tarball base64-encoded
+        //    inside a JSON listing request (NOT a raw octet-stream body).
+        const tarballBytes = tarballPayload(payloadDir);
+        const token = await deps.getAccessToken();
+        const listing = {
+            type: inferListingType(pkg),
+            name: pkg.name,
+            slug: deriveSlug(pkg.name),
+            version: pkg.version,
+            summary: pkg.description,
+            contributes: summarizeContributes(pkg.contributes) || undefined,
+            // Server prefers the caller's claimed creator handle, but we stamp our
+            // resolved handle as a backwards-compat fallback.
+            creatorHandle: author.handle,
+            tarball: Buffer.from(tarballBytes).toString('base64'),
+        };
+        const { status, body } = await deps.upload({ token, listing });
+        const notice = buildListingNotice(status, body, pkg.name, pkg.version);
+        // 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();
+        // 5. Provenance (only after a successful upload).
+        recordProvenance(deps.hqRoot, pkg, absTarget);
+        return { notice, author, pkg, serverAttributed: Boolean(serverHandle) };
+    }
+    finally {
+        fs.rmSync(workDir, { recursive: true, force: true });
+    }
+}
+// ---------------------------------------------------------------------------
+// Command wiring
+// ---------------------------------------------------------------------------
+function readHqVersion(hqRoot) {
+    const p = path.join(hqRoot, 'core.yaml');
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        const c = yaml.load(fs.readFileSync(p, 'utf-8'));
+        return c?.hqVersion ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export function registerPublishCommand(program) {
+    program
+        .command('publish <path>')
+        .description('Package a skill/worker pack and submit it to the HQ marketplace (POST /v1/listings).')
+        .action(async (targetPath) => {
+        try {
+            const hqRoot = findHqRoot();
+            const result = await runPublish(targetPath, {
+                loadIdToken: () => {
+                    const cached = loadCachedTokens();
+                    if (!cached || isExpiring(cached, 0))
+                        return null;
+                    return cached.idToken;
+                },
+                getAccessToken: () => ensureCognitoToken({ interactive: false }),
+                upload: async ({ token, listing }) => {
+                    // JSON body (application/json) — the deployed handler JSON.parses
+                    // the body and base64-decodes `listing.tarball`. vaultApiFetch
+                    // sends application/json + the bearer token.
+                    const res = await vaultApiFetch({
+                        token,
+                        path: '/v1/listings',
+                        method: 'POST',
+                        body: listing,
+                    });
+                    const json = (await res.json().catch(() => ({})));
+                    return { status: res.status, body: json };
+                },
+                hqRoot,
+                hqVersion: readHqVersion(hqRoot),
+            });
+            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).
+            if (!result.serverAttributed) {
+                console.log(chalk.dim(`  Attributed to ${result.author.displayName} (@${result.author.handle}).`));
+            }
+        }
+        catch (err) {
+            console.error(chalk.red('Error:'), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=publish.js.map
+//# debugId=73704bc7-d7b1-5c4c-a34e-54edadcc2753

package/dist/commands/rescue.d.ts

@@ -0,0 +1,33 @@
+/**
+ * hq rescue — re-sync the local HQ core to an upstream hq-core release (or the
+ * staging branch) WITHOUT destroying local edits ("drift").
+ *
+ * Thin driver over @indigoai-us/hq-cloud's `rescue()`, which execs the bundled
+ * scripts/replace-rescue.sh against the HQ root. This is the CLI sibling of the
+ * HQ Sync menubar app's "Update / Restore" pill — both drive the exact same
+ * rescue script, just resolved from the shared hq-cloud package.
+ *
+ * Prod (default): resolves the latest `indigoai-us/hq-core` release tag and
+ * pins the three-way history floor to the commit of the user's currently
+ * installed version (read from core/core.yaml). Staging (`--staging`): targets
+ * `indigoai-us/hq-core-staging@main` and lets the script read its on-disk
+ * sync stamp for the floor.
+ */
+import { Command } from 'commander';
+export interface RescueTarget {
+    source: string;
+    /** undefined → let the script apply its own default ref (`main`). */
+    ref?: string;
+}
+/**
+ * Resolve the source repo + ref from the user's flags. Pure + exported for
+ * tests. `latestTag` is the resolved latest release tag (prod only); ignored
+ * for staging and when an explicit `--ref` is given.
+ */
+export declare function resolveRescueTarget(opts: {
+    staging?: boolean;
+    source?: string;
+    ref?: string;
+}, latestTag?: string): RescueTarget;
+export declare function registerRescueCommand(program: Command): void;
+//# sourceMappingURL=rescue.d.ts.map