@indigoai-us/hq-cli 5.47.13 → 5.47.15

package/dist/commands/api-keys.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function registerApiKeysCommand(program: Command): Command;
+//# sourceMappingURL=api-keys.d.ts.map

package/dist/commands/api-keys.js

@@ -0,0 +1,198 @@
+
+!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]="c9f6fe34-9e38-5001-97b7-14b35c956330")}catch(e){}}();
+import chalk from "chalk";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { getCompanyUid, vaultApiFetch } from "./secrets.js";
+function collectRepeatedOption(value, previous) {
+    return [...previous, value];
+}
+function formatMaybe(value) {
+    return value ?? "-";
+}
+function formatPrefixes(prefixes) {
+    return prefixes.length > 0 ? prefixes.join(", ") : "-";
+}
+function parsePermission(value) {
+    if (value === "read" || value === "write" || value === "admin") {
+        return value;
+    }
+    throw new Error(`Invalid permission '${value}'. Use one of: read, write, admin.`);
+}
+function parseExpires(expires) {
+    if (expires === undefined)
+        return undefined;
+    if (Number.isNaN(Date.parse(expires))) {
+        throw new Error(`Invalid --expires value '${expires}'. Use an ISO-8601 timestamp.`);
+    }
+    return expires;
+}
+async function readApiError(res, action) {
+    const body = (await res.json().catch(() => ({})));
+    const message = typeof body.message === "string"
+        ? body.message
+        : typeof body.error === "string"
+            ? body.error
+            : res.statusText;
+    if (res.status === 401) {
+        return "Not authenticated - please run `hq login`";
+    }
+    if (res.status === 403) {
+        return `Not authorized to ${action}`;
+    }
+    if (res.status === 404) {
+        return message || "API key not found";
+    }
+    if (res.status >= 500) {
+        return `Server error: ${message}`;
+    }
+    return message || `Request failed (${res.status})`;
+}
+function renderApiKeysTable(apiKeys) {
+    const rows = apiKeys.map((apiKey) => ({
+        keyId: apiKey.keyId,
+        name: apiKey.name,
+        permission: apiKey.scope.permission,
+        prefixes: formatPrefixes(apiKey.scope.allowedPrefixes),
+        status: apiKey.status,
+        lastUsedAt: formatMaybe(apiKey.lastUsedAt),
+        expiresAt: formatMaybe(apiKey.expiresAt),
+    }));
+    const keyIdWidth = Math.max(6, ...rows.map((row) => row.keyId.length));
+    const nameWidth = Math.max(4, ...rows.map((row) => row.name.length));
+    const permissionWidth = Math.max(10, ...rows.map((row) => row.permission.length));
+    const prefixesWidth = Math.max(8, ...rows.map((row) => row.prefixes.length));
+    const statusWidth = Math.max(6, ...rows.map((row) => row.status.length));
+    const lastUsedWidth = Math.max(11, ...rows.map((row) => row.lastUsedAt.length));
+    const expiresWidth = Math.max(10, ...rows.map((row) => row.expiresAt.length));
+    const header = [
+        "KEY ID".padEnd(keyIdWidth),
+        "NAME".padEnd(nameWidth),
+        "PERMISSION".padEnd(permissionWidth),
+        "PREFIXES".padEnd(prefixesWidth),
+        "STATUS".padEnd(statusWidth),
+        "LAST USED".padEnd(lastUsedWidth),
+        "EXPIRES".padEnd(expiresWidth),
+    ].join("  ");
+    console.log(chalk.bold(header));
+    for (const row of rows) {
+        console.log([
+            row.keyId.padEnd(keyIdWidth),
+            row.name.padEnd(nameWidth),
+            row.permission.padEnd(permissionWidth),
+            row.prefixes.padEnd(prefixesWidth),
+            row.status.padEnd(statusWidth),
+            row.lastUsedAt.padEnd(lastUsedWidth),
+            row.expiresAt.padEnd(expiresWidth),
+        ].join("  "));
+    }
+}
+export function registerApiKeysCommand(program) {
+    const apiKeys = program
+        .command("api-keys")
+        .description("Manage vault API keys for CI and automation")
+        .option("--company <slug>", "Company slug (resolves to companyUid)");
+    apiKeys
+        .command("create")
+        .description("Create a new API key")
+        .requiredOption("--name <label>", "Human-readable label for the API key")
+        .option("--scope <prefix>", "Allowed prefix (repeatable)", collectRepeatedOption, [])
+        .option("--permission <level>", "Permission level: read | write | admin", "read")
+        .option("--expires <ISO8601>", "Optional ISO-8601 expiry timestamp")
+        .action(async (opts) => {
+        try {
+            if (opts.scope.length === 0) {
+                console.error(chalk.red("Error: at least one --scope <prefix> is required."));
+                process.exit(1);
+            }
+            const permission = parsePermission(opts.permission);
+            const expiresAt = parseExpires(opts.expires);
+            const token = await ensureCognitoToken();
+            const companyUid = await getCompanyUid(token, apiKeys.opts().company);
+            const res = await vaultApiFetch({
+                token,
+                path: "/v1/api-keys",
+                method: "POST",
+                body: {
+                    companyUid,
+                    name: opts.name,
+                    allowedPrefixes: opts.scope,
+                    permission,
+                    ...(expiresAt ? { expiresAt } : {}),
+                },
+            });
+            if (!res.ok) {
+                throw new Error(await readApiError(res, "create API keys"));
+            }
+            const data = (await res.json());
+            console.log(chalk.green("API key created."));
+            console.log(chalk.yellow("Store this key now - it won't be shown again:"));
+            console.log(`\n  ${data.key.value}\n`);
+            console.log(chalk.bold("Metadata"));
+            console.log(`  Key ID: ${data.apiKey.keyId}`);
+            console.log(`  Name: ${data.apiKey.name}`);
+            console.log(`  Company: ${data.apiKey.companyUid}`);
+            console.log(`  Permission: ${data.apiKey.scope.permission}`);
+            console.log(`  Prefixes: ${formatPrefixes(data.apiKey.scope.allowedPrefixes)}`);
+            console.log(`  Status: ${data.apiKey.status}`);
+            console.log(`  Created: ${data.apiKey.createdAt}`);
+            console.log(`  Last used: ${formatMaybe(data.apiKey.lastUsedAt)}`);
+            console.log(`  Expires: ${formatMaybe(data.apiKey.expiresAt)}`);
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    apiKeys
+        .command("list")
+        .description("List API keys for a company")
+        .action(async () => {
+        try {
+            const token = await ensureCognitoToken();
+            const companyUid = await getCompanyUid(token, apiKeys.opts().company);
+            const res = await vaultApiFetch({
+                token,
+                path: "/v1/api-keys",
+                query: { companyUid },
+            });
+            if (!res.ok) {
+                throw new Error(await readApiError(res, "list API keys"));
+            }
+            const data = (await res.json());
+            if (data.apiKeys.length === 0) {
+                console.log(chalk.dim("No API keys found."));
+                return;
+            }
+            renderApiKeysTable(data.apiKeys);
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    apiKeys
+        .command("revoke <keyId>")
+        .description("Revoke an API key")
+        .action(async (keyId) => {
+        try {
+            const token = await ensureCognitoToken();
+            const res = await vaultApiFetch({
+                token,
+                path: `/v1/api-keys/${encodeURIComponent(keyId)}/revoke`,
+                method: "POST",
+            });
+            if (!res.ok) {
+                throw new Error(await readApiError(res, "revoke this API key"));
+            }
+            const data = (await res.json());
+            console.log(chalk.green(`Revoked API key '${data.apiKey.keyId}'`));
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    return apiKeys;
+}
+//# sourceMappingURL=api-keys.js.map
+//# debugId=c9f6fe34-9e38-5001-97b7-14b35c956330

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

@@ -238,6 +238,20 @@ export declare function computeArtifactHash(tarballBytes: Uint8Array): string;
  */
 export declare function verifyArtifact(input: VerifyArtifactInput): void;
 export declare function validateManifest(payloadDir: string, hqVersion: string | null): PackManifest;
+/**
+ * Derive the safe, auto-generated "get started" line for a freshly installed
+ * pack from its `initialization.entrypoint` ONLY. PHASE 1 deliberately ignores
+ * the free-text `initialization.prompt` prose (rendering/moderation is a later
+ * story) so untrusted prose can't reach the operator's terminal.
+ *
+ * The command is slash-normalized to exactly one leading slash regardless of
+ * whether `entrypoint` was stored with or without one, matching the HQ Sync
+ * desktop render: ``Run `/email-assistant` to get started``.
+ *
+ * Returns `null` when there is no initialization block (backwards-compatible —
+ * the caller prints nothing extra).
+ */
+export declare function getStartedLine(initialization?: PackManifest['initialization']): string | null;
 /**
  * Install the fetched payload to `<hqRoot>/core/packages/<pkg.name>/` (HQ
  * v12+ layout). The HQ template (`hq-core` / `hq-core-staging`) ships

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]="cbb11285-034d-50c4-917d-797ab226db66")}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]="cb8b5583-b60f-52a5-802d-befc33f2a07b")}catch(e){}}();
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -807,9 +807,75 @@ export function validateManifest(payloadDir, hqVersion) {
             throw new Error('capabilities must be a list of strings');
         }
     }
+    // initialization (US-004) — OPTIONAL and backwards-compatible. Absent → fine
+    // (legacy packs). Present → the `entrypoint` is REQUIRED and MUST resolve to a
+    // declared `contributes.skills` or `contributes.commands` entry (this is the
+    // content-pack system, so entries are named under `contributes.*` — NOT the
+    // registry `exposes.*` system). The post-install initialization prompt is
+    // rendered/moderated in a later story; here we only validate shape so a
+    // malformed block can't slip through to install.
+    if (m.initialization !== undefined) {
+        const init = m.initialization;
+        if (!init || typeof init !== 'object' || Array.isArray(init)) {
+            throw new Error('initialization must be a mapping with an entrypoint');
+        }
+        const initObj = init;
+        const entrypoint = initObj.entrypoint;
+        if (typeof entrypoint !== 'string' || entrypoint.trim() === '') {
+            throw new Error('initialization.entrypoint is required and must be a non-empty string');
+        }
+        // Resolve the entrypoint against declared skills/commands. Normalize a
+        // leading slash on BOTH sides so `/email-assistant` matches a contributes
+        // entry named `email-assistant` and vice-versa.
+        const stripSlash = (s) => (s.startsWith('/') ? s.slice(1) : s);
+        const target = stripSlash(entrypoint.trim());
+        const declared = [
+            ...(contributes.skills ?? []),
+            ...(contributes.commands ?? []),
+        ];
+        const resolves = declared.some((d) => stripSlash(d) === target);
+        if (!resolves) {
+            throw new Error(`initialization.entrypoint "${entrypoint}" does not resolve to a declared ` +
+                `contributes.skills or contributes.commands entry. ` +
+                `Valid entries: ${declared.length ? declared.join(', ') : '(none declared)'}`);
+        }
+        // initialization.prompt — OPTIONAL. When present it must be a string ≤ 2000
+        // chars. (Rendering/moderation is a later story; we only validate type/length.)
+        if (initObj.prompt !== undefined) {
+            if (typeof initObj.prompt !== 'string') {
+                throw new Error('initialization.prompt must be a string');
+            }
+            if (initObj.prompt.length > 2000) {
+                throw new Error(`initialization.prompt must be ≤ 2000 characters (got ${initObj.prompt.length})`);
+            }
+        }
+    }
     return m;
 }
 // ---------------------------------------------------------------------------
+// Post-install get-started line (US-005)
+// ---------------------------------------------------------------------------
+/**
+ * Derive the safe, auto-generated "get started" line for a freshly installed
+ * pack from its `initialization.entrypoint` ONLY. PHASE 1 deliberately ignores
+ * the free-text `initialization.prompt` prose (rendering/moderation is a later
+ * story) so untrusted prose can't reach the operator's terminal.
+ *
+ * The command is slash-normalized to exactly one leading slash regardless of
+ * whether `entrypoint` was stored with or without one, matching the HQ Sync
+ * desktop render: ``Run `/email-assistant` to get started``.
+ *
+ * Returns `null` when there is no initialization block (backwards-compatible —
+ * the caller prints nothing extra).
+ */
+export function getStartedLine(initialization) {
+    const entrypoint = initialization?.entrypoint;
+    if (typeof entrypoint !== 'string' || entrypoint.trim() === '')
+        return null;
+    const command = '/' + entrypoint.trim().replace(/^\/+/, '');
+    return `Run \`${command}\` to get started`;
+}
+// ---------------------------------------------------------------------------
 // Hooks confirmation
 // ---------------------------------------------------------------------------
 async function confirmHooks(pkg, allowHooks) {
@@ -1070,10 +1136,18 @@ export async function installPack(source, opts = {}) {
         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.`));
+        // US-005 — when the pack declares an `initialization` block, print a safe,
+        // auto-generated "get started" line right after the success output. PHASE 1
+        // derives the line from `initialization.entrypoint` ONLY (never the
+        // free-text `initialization.prompt` prose), and matches the HQ Sync desktop
+        // wording for consistency. Absent block → nothing extra (backwards-compat).
+        const getStarted = getStartedLine(pkg.initialization);
+        if (getStarted)
+            say(chalk.cyan(getStarted));
     }
     finally {
         fs.rmSync(tmpDir, { recursive: true, force: true });
     }
 }
 //# sourceMappingURL=pack-install.js.map
-//# debugId=cbb11285-034d-50c4-917d-797ab226db66
+//# debugId=cb8b5583-b60f-52a5-802d-befc33f2a07b

package/dist/commands/packs.d.ts

@@ -18,5 +18,37 @@
  * Spec: knowledge/public/hq-core/package-yaml-spec.md.
  */
 import { Command } from 'commander';
+import { type InstalledPack, type LinkStatus } from '../utils/pack-contributions.js';
+import type { PackContributeKey } from '../types.js';
+interface InstalledPackView {
+    name: string;
+    version?: string;
+    publisher?: string;
+    source?: string;
+    transport: string | null;
+    requiresHqCore?: string;
+    hqCoreSatisfied: boolean | null;
+    contributes: Partial<Record<PackContributeKey, number>>;
+    links: Record<LinkStatus, number>;
+    brokenLinks: Array<{
+        key: PackContributeKey;
+        item: string;
+        dst: string;
+    }>;
+    inCatalog: boolean;
+    updateAvailable: boolean | null;
+    /**
+     * Post-install initialization (US-005). Present only when the pack's
+     * package.yaml declares an `initialization` block — drives the HQ Sync
+     * "Installed" panel get-started affordance. Absent → omitted (no null noise).
+     */
+    initialization?: {
+        entrypoint: string;
+        prompt?: string;
+    };
+    error?: string;
+}
+export declare function buildInstalledView(hqRoot: string, hqVersion: string | null, pack: InstalledPack, installedSources: Set<string>, checkUpdates: boolean): InstalledPackView;
 export declare function registerPacksCommand(parent: Command): void;
+export {};
 //# sourceMappingURL=packs.d.ts.map

package/dist/commands/packs.js

@@ -18,7 +18,7 @@
  * Spec: knowledge/public/hq-core/package-yaml-spec.md.
  */
 
-!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]="fa6cf3bf-90fa-5261-a15f-c8810e4b5615")}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]="527d0e7d-2101-5438-8251-2579a40453e6")}catch(e){}}();
 import * as fs from 'fs';
 import * as path from 'path';
 import * as readline from 'readline';
@@ -61,7 +61,7 @@ async function confirm(question) {
     });
     return /^(y|yes)$/i.test(answer.trim());
 }
-function buildInstalledView(hqRoot, hqVersion, pack, installedSources, checkUpdates) {
+export function buildInstalledView(hqRoot, hqVersion, pack, installedSources, checkUpdates) {
     if (!pack.manifest) {
         return {
             name: pack.name,
@@ -97,6 +97,22 @@ function buildInstalledView(hqRoot, hqVersion, pack, installedSources, checkUpda
     if (checkUpdates && m.source) {
         updateAvailable = resolveLatest(m.source, m.version).updateAvailable;
     }
+    // US-005 — surface the pack's `initialization` block so the HQ Sync
+    // "Installed" panel can render its get-started affordance. `readPackManifest`
+    // already parses the full package.yaml, so `m.initialization` is available;
+    // we still shape it defensively (tolerate a malformed/absent block) and omit
+    // the field entirely when absent so the JSON carries no null noise.
+    let initialization;
+    const rawInit = m.initialization;
+    if (rawInit && typeof rawInit === 'object' && !Array.isArray(rawInit)) {
+        const initObj = rawInit;
+        const entrypoint = initObj.entrypoint;
+        if (typeof entrypoint === 'string' && entrypoint.trim() !== '') {
+            initialization = { entrypoint };
+            if (typeof initObj.prompt === 'string')
+                initialization.prompt = initObj.prompt;
+        }
+    }
     return {
         name: m.name ?? pack.name,
         version: m.version,
@@ -110,6 +126,7 @@ function buildInstalledView(hqRoot, hqVersion, pack, installedSources, checkUpda
         brokenLinks,
         inCatalog: m.source ? installedSources.has(m.source) : false,
         updateAvailable,
+        ...(initialization ? { initialization } : {}),
     };
 }
 function buildListView(hqRoot, checkUpdates, evalConditionals) {
@@ -408,4 +425,4 @@ export function registerPacksCommand(parent) {
     });
 }
 //# sourceMappingURL=packs.js.map
-//# debugId=fa6cf3bf-90fa-5261-a15f-c8810e4b5615
+//# debugId=527d0e7d-2101-5438-8251-2579a40453e6

package/dist/index.js

@@ -3,7 +3,7 @@
  * HQ CLI - Module management, package management, and cloud sync for HQ
  */
 
-!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]="6fa5c878-2930-5b94-bc7c-5deea8795218")}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]="964b8c71-056c-51fb-893a-d51f8f6ad5d9")}catch(e){}}();
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
 import { registerAddCommand } from "./commands/add.js";
@@ -28,6 +28,7 @@ import { registerPublishCommand } from "./commands/publish.js";
 import { registerCreatorsCommand } from "./commands/creators.js";
 import { registerTeamSyncCommand } from "./commands/team-sync.js";
 import { registerAuthCommands } from "./commands/auth.js";
+import { registerApiKeysCommand } from "./commands/api-keys.js";
 import { registerSecretsCommand } from "./commands/secrets.js";
 import { registerRunCommand } from "./commands/run.js";
 import { registerGroupsCommand } from "./commands/groups.js";
@@ -117,6 +118,8 @@ registerWhoamiCommand(program);
 registerAuthCommands(program);
 // Secrets management (subcommand group — hq secrets set|get|list|delete|exec|generate-link|cache)
 registerSecretsCommand(program);
+// API key management (subcommand group — hq api-keys create|list|revoke)
+registerApiKeysCommand(program);
 // Schema-driven dev runner — hq run [options] -- <cmd>
 registerRunCommand(program);
 // Groups management (subcommand group — hq groups create|delete|add|remove|list|members)
@@ -177,4 +180,4 @@ registerRescueCommand(program);
     }
 })();
 //# sourceMappingURL=index.js.map
-//# debugId=6fa5c878-2930-5b94-bc7c-5deea8795218
+//# debugId=964b8c71-056c-51fb-893a-d51f8f6ad5d9

package/dist/types.d.ts

@@ -93,5 +93,15 @@ export interface PackManifest {
      * yet enforced.
      */
     capabilities?: string[];
+    /**
+     * Post-install initialization (US-004/US-005). Optional — absent on legacy
+     * packs. `entrypoint` names a declared `contributes.skills`/`commands` entry
+     * (slash-normalized); `prompt` is optional free-text prose (PHASE 1 does NOT
+     * render the prose — only an auto-generated get-started line from entrypoint).
+     */
+    initialization?: {
+        entrypoint: string;
+        prompt?: string;
+    };
 }
 //# sourceMappingURL=types.d.ts.map

package/package.json

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