@indigoai-us/hq-cli 5.31.0 → 5.32.0

package/dist/commands/packs.js

@@ -0,0 +1,406 @@
+/**
+ * `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.
+ */
+
+!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]="cb73c4fb-255e-5df7-accd-9b7d12362a06")}catch(e){}}();
+import * as fs from 'fs';
+import * as path from 'path';
+import * as readline from 'readline';
+import { spawnSync } from 'child_process';
+import chalk from 'chalk';
+import semverSatisfies from 'semver/functions/satisfies.js';
+import { findHqRoot } from '../utils/manifest.js';
+import { classify, resolveLatest, runScanPackages, installPack, } from './pack-install.js';
+import { contributionLinks, linkStatus, listInstalledPacks, readPackManifest, unwirePack, readHqVersion, readRecommendedPackages, packagesDir, } from '../utils/pack-contributions.js';
+function resolveRoot(opts) {
+    return opts.hqRoot ? path.resolve(opts.hqRoot) : findHqRoot();
+}
+/** JSON when --json or when piped (non-TTY); human-readable on a terminal. */
+function wantsJson(opts) {
+    return opts.json === true || !process.stdout.isTTY;
+}
+function emitJson(value) {
+    process.stdout.write(JSON.stringify(value, null, 2) + '\n');
+}
+function safeClassify(source) {
+    if (!source)
+        return null;
+    try {
+        return classify(source);
+    }
+    catch {
+        return null;
+    }
+}
+function evalConditional(expr) {
+    return spawnSync('bash', ['-c', expr], { stdio: 'ignore' }).status === 0;
+}
+async function confirm(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) => {
+        rl.question(`${question} [y/N] `, (a) => {
+            rl.close();
+            resolve(a);
+        });
+    });
+    return /^(y|yes)$/i.test(answer.trim());
+}
+function buildInstalledView(hqRoot, hqVersion, pack, installedSources, checkUpdates) {
+    if (!pack.manifest) {
+        return {
+            name: pack.name,
+            transport: null,
+            hqCoreSatisfied: null,
+            contributes: {},
+            links: { live: 0, broken: 0, missing: 0, foreign: 0 },
+            brokenLinks: [],
+            inCatalog: false,
+            updateAvailable: null,
+            error: pack.error ?? 'unreadable manifest',
+        };
+    }
+    const m = pack.manifest;
+    const contributes = m.contributes ?? {};
+    const links = contributionLinks(hqRoot, pack.dir, contributes);
+    const counts = { live: 0, broken: 0, missing: 0, foreign: 0 };
+    const brokenLinks = [];
+    for (const link of links) {
+        const st = linkStatus(link);
+        counts[st]++;
+        if (st === 'broken')
+            brokenLinks.push({ key: link.key, item: link.item, dst: link.dst });
+    }
+    const contributeCounts = {};
+    for (const [key, items] of Object.entries(contributes)) {
+        if (Array.isArray(items) && items.length > 0)
+            contributeCounts[key] = items.length;
+    }
+    const requiresHqCore = m.requires?.hqCore;
+    const hqCoreSatisfied = hqVersion && requiresHqCore ? semverSatisfies(hqVersion, requiresHqCore) : null;
+    let updateAvailable = null;
+    if (checkUpdates && m.source) {
+        updateAvailable = resolveLatest(m.source, m.version).updateAvailable;
+    }
+    return {
+        name: m.name ?? pack.name,
+        version: m.version,
+        publisher: m.publisher,
+        source: m.source,
+        transport: safeClassify(m.source),
+        requiresHqCore,
+        hqCoreSatisfied,
+        contributes: contributeCounts,
+        links: counts,
+        brokenLinks,
+        inCatalog: m.source ? installedSources.has(m.source) : false,
+        updateAvailable,
+    };
+}
+function buildListView(hqRoot, checkUpdates, evalConditionals) {
+    const hqVersion = readHqVersion(hqRoot);
+    const packs = listInstalledPacks(hqRoot);
+    const catalog = readRecommendedPackages(hqRoot);
+    const catalogSources = new Set(catalog.map((c) => c.source));
+    const warnings = [];
+    const installed = packs.map((p) => buildInstalledView(hqRoot, hqVersion, p, catalogSources, checkUpdates));
+    for (const p of installed) {
+        if (p.error)
+            warnings.push(`${p.name}: ${p.error}`);
+    }
+    const installedSources = new Set(packs.map((p) => p.manifest?.source).filter((s) => !!s));
+    const available = catalog
+        .filter((c) => !installedSources.has(c.source))
+        .map((c) => {
+        let conditionalStatus = c.conditional
+            ? 'unevaluated'
+            : 'none';
+        if (c.conditional && evalConditionals) {
+            conditionalStatus = evalConditional(c.conditional) ? 'pass' : 'fail';
+        }
+        return {
+            source: c.source,
+            description: c.description,
+            installed: false,
+            conditional: c.conditional,
+            conditionalStatus,
+        };
+    });
+    return { hqRoot, hqVersion, installed, available, warnings };
+}
+function printListHuman(view) {
+    console.log(chalk.bold(`\nHQ packs  (${view.hqRoot}, hqCore ${view.hqVersion ?? '?'})\n`));
+    if (view.installed.length === 0) {
+        console.log(chalk.dim('  No content packs installed.\n'));
+    }
+    else {
+        console.log(chalk.bold('Installed:'));
+        for (const p of view.installed) {
+            if (p.error) {
+                console.log(`  ${chalk.red(p.name)}  ${chalk.dim('(' + p.error + ')')}`);
+                continue;
+            }
+            const broken = p.links.broken > 0 ? chalk.red(`  ! ${p.links.broken} broken link(s)`) : '';
+            const upd = p.updateAvailable ? chalk.yellow('  ^ update available') : '';
+            const hq = p.hqCoreSatisfied === false ? chalk.red('  x hqCore mismatch') : '';
+            console.log(`  ${chalk.green(p.name)}@${p.version ?? '?'}  ${chalk.dim(p.transport ?? '')}${upd}${hq}${broken}`);
+        }
+        console.log();
+    }
+    if (view.available.length > 0) {
+        console.log(chalk.bold('Available (curated):'));
+        for (const a of view.available) {
+            const gate = a.conditionalStatus === 'fail'
+                ? chalk.dim('  (gated off)')
+                : a.conditionalStatus === 'unevaluated' && a.conditional
+                    ? chalk.dim('  (conditional)')
+                    : '';
+            console.log(`  ${chalk.cyan(a.source)}${gate}`);
+            if (a.description)
+                console.log(chalk.dim(`    ${a.description}`));
+        }
+        console.log(chalk.dim('\n  Install with: hq install <source>\n'));
+    }
+}
+async function runUpdate(name, opts) {
+    const hqRoot = resolveRoot(opts);
+    let packs = listInstalledPacks(hqRoot).filter((p) => p.manifest);
+    if (name) {
+        packs = packs.filter((p) => (p.manifest?.name ?? p.name) === name);
+        if (packs.length === 0) {
+            return [{ name, transport: 'unknown', updateAvailable: null, applied: false, error: 'not installed' }];
+        }
+    }
+    const results = [];
+    for (const pack of packs) {
+        const m = pack.manifest;
+        const source = m.source;
+        const pname = m.name ?? pack.name;
+        if (!source) {
+            results.push({ name: pname, transport: 'unknown', updateAvailable: null, applied: false, error: 'no stamped source -- cannot update' });
+            continue;
+        }
+        const probe = resolveLatest(source, m.version);
+        const base = {
+            name: pname,
+            transport: probe.transport,
+            current: probe.current,
+            latest: probe.latest,
+            updateAvailable: probe.updateAvailable,
+            applied: false,
+            error: probe.error,
+        };
+        if (opts.checkOnly) {
+            results.push(base);
+            continue;
+        }
+        // Apply only when there's a known update, or when explicitly named (force re-sync).
+        if (probe.updateAvailable === false && !name) {
+            results.push({ ...base, reason: 'already current' });
+            continue;
+        }
+        try {
+            // Un-wire old contributions first so a contribution dropped by the new
+            // version doesn't leave a dangling host symlink. installPack re-wires.
+            unwirePack(hqRoot, pack.dir, m.contributes ?? {});
+            const prevCwd = process.cwd();
+            if (opts.hqRoot)
+                process.chdir(hqRoot); // installPack resolves via findHqRoot()
+            try {
+                await installPack(source, {
+                    allowHooks: opts.yes || opts.allowHooks,
+                    followBranch: opts.branch,
+                    quiet: wantsJson(opts),
+                });
+            }
+            finally {
+                if (opts.hqRoot)
+                    process.chdir(prevCwd);
+            }
+            results.push({ ...base, applied: true });
+        }
+        catch (e) {
+            results.push({ ...base, applied: false, error: e.message });
+        }
+    }
+    return results;
+}
+function archiveTimestamp() {
+    return new Date().toISOString().replace(/[:.]/g, '-').replace('T', '_').slice(0, 19);
+}
+async function runUninstall(name, opts) {
+    const hqRoot = resolveRoot(opts);
+    const packDir = path.join(packagesDir(hqRoot), name);
+    if (!fs.existsSync(packDir)) {
+        throw new Error(`Pack "${name}" is not installed (no core/packages/${name}/).`);
+    }
+    const warnings = [];
+    const { manifest } = readPackManifest(packDir);
+    const contributes = manifest?.contributes ?? {};
+    if (!manifest) {
+        warnings.push('package.yaml unreadable -- host symlinks could not be computed precisely; ran a re-scan to reconcile.');
+    }
+    // 1. Un-wire only our symlinks.
+    const { unlinked, skipped } = unwirePack(hqRoot, packDir, contributes);
+    // 2. Archive (or delete) the pack dir -- BEFORE re-scan so it isn't re-wired.
+    let archived = null;
+    if (opts.archive === false) {
+        fs.rmSync(packDir, { recursive: true, force: true });
+    }
+    else {
+        const dest = path.join(packagesDir(hqRoot), '.archive', `${name}-${archiveTimestamp()}`);
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.renameSync(packDir, dest);
+        archived = path.relative(hqRoot, dest);
+    }
+    // 3. Re-assert remaining packs' links (handles two packs sharing a contribution).
+    let rescan = 'skipped';
+    try {
+        // Quiet: uninstall emits its own summary / JSON; keep scan stdout off ours.
+        runScanPackages(hqRoot, { quiet: true });
+        rescan = 'ok';
+    }
+    catch {
+        rescan = 'skipped';
+    }
+    // 4. Regenerate the workers registry if this pack contributed workers.
+    let workersRegistryRegenerated = false;
+    const contributedWorkers = Array.isArray(contributes.workers) && contributes.workers.length > 0;
+    if (contributedWorkers) {
+        const gen = path.join(hqRoot, 'core', 'scripts', 'generate-workers-registry.sh');
+        if (fs.existsSync(gen)) {
+            const r = spawnSync('bash', [gen], { cwd: hqRoot, env: { ...process.env, HQ_ROOT: hqRoot }, stdio: 'ignore' });
+            workersRegistryRegenerated = r.status === 0;
+            if (!workersRegistryRegenerated)
+                warnings.push('generate-workers-registry.sh exited non-zero');
+        }
+    }
+    const sideEffectsSuggested = ['master-sync', 'qmd-reindex'];
+    if (contributedWorkers && !workersRegistryRegenerated)
+        sideEffectsSuggested.push('workers-registry');
+    return {
+        name,
+        archived,
+        unlinked,
+        skipped,
+        rescan,
+        workersRegistryRegenerated,
+        sideEffectsSuggested,
+        warnings,
+    };
+}
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+export function registerPacksCommand(parent) {
+    const packs = parent.command('packs').description('Content-pack lifecycle (install via `hq install`)');
+    packs
+        .command('list')
+        .alias('ls')
+        .description('List installed content packs and the curated catalog')
+        .option('--json', 'Machine-readable JSON output')
+        .option('--hq-root <path>', 'HQ root (default: auto-detect)')
+        .option('--check-updates', 'Probe each pack for available updates (network I/O)')
+        .option('--eval-conditionals', 'Evaluate catalog conditional predicates (runs bash)')
+        .action(async (opts) => {
+        try {
+            const view = buildListView(resolveRoot(opts), !!opts.checkUpdates, !!opts.evalConditionals);
+            if (wantsJson(opts))
+                emitJson(view);
+            else
+                printListHuman(view);
+        }
+        catch (e) {
+            console.error(chalk.red('packs list failed:'), e.message);
+            process.exit(1);
+        }
+    });
+    packs
+        .command('update [name]')
+        .description('Update an installed content pack (re-install latest)')
+        .option('--json', 'Machine-readable JSON output')
+        .option('--hq-root <path>', 'HQ root (default: auto-detect)')
+        .option('--check-only', 'Report availability without installing')
+        .option('-y, --yes', 'Non-interactive (implies --allow-hooks)')
+        .option('--allow-hooks', 'Install pack hooks without prompting')
+        .option('--branch', 'Follow the source branch instead of SHA-pinning')
+        .action(async (name, opts) => {
+        try {
+            const results = await runUpdate(name, opts);
+            if (wantsJson(opts)) {
+                emitJson({ checked: results, updatedCount: results.filter((r) => r.applied).length });
+            }
+            else {
+                for (const r of results) {
+                    if (r.error)
+                        console.log(`  ${chalk.red(r.name)}: ${r.error}`);
+                    else if (r.applied)
+                        console.log(`  ${chalk.green(r.name)}: updated`);
+                    else if (r.updateAvailable)
+                        console.log(`  ${chalk.yellow(r.name)}: ${r.current ?? '?'} -> ${r.latest ?? '?'} available`);
+                    else
+                        console.log(`  ${chalk.dim(r.name)}: ${r.reason ?? 'current'}`);
+                }
+            }
+        }
+        catch (e) {
+            console.error(chalk.red('packs update failed:'), e.message);
+            process.exit(1);
+        }
+    });
+    packs
+        .command('uninstall <name>')
+        .alias('remove')
+        .description('Un-wire and archive an installed content pack')
+        .option('--json', 'Machine-readable JSON output')
+        .option('--hq-root <path>', 'HQ root (default: auto-detect)')
+        .option('-y, --yes', 'Skip confirmation')
+        .option('--no-archive', 'Delete instead of archiving')
+        .action(async (name, opts) => {
+        try {
+            if (!opts.yes) {
+                if (!process.stdout.isTTY) {
+                    throw new Error('Refusing to uninstall without --yes in non-interactive mode.');
+                }
+                const ok = await confirm(`Uninstall pack "${name}"? This removes its host symlinks.`);
+                if (!ok) {
+                    console.log(chalk.dim('Aborted.'));
+                    return;
+                }
+            }
+            const result = await runUninstall(name, opts);
+            if (wantsJson(opts)) {
+                emitJson(result);
+            }
+            else {
+                console.log(chalk.green(`\nOK Uninstalled ${name}`));
+                console.log(chalk.dim(`  Unlinked ${result.unlinked.length} symlink(s); archived to ${result.archived ?? '(deleted)'}.`));
+                if (result.skipped.length > 0)
+                    console.log(chalk.dim(`  Left ${result.skipped.length} non-owned path(s) in place.`));
+                for (const w of result.warnings)
+                    console.log(chalk.yellow(`  ! ${w}`));
+            }
+        }
+        catch (e) {
+            console.error(chalk.red('packs uninstall failed:'), e.message);
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=packs.js.map
+//# debugId=cb73c4fb-255e-5df7-accd-9b7d12362a06

package/dist/commands/pkg-list.js

@@ -4,7 +4,7 @@
  * Graceful offline: if registry is unreachable, show cached data with a note.
  */
 
-!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]="2ca922cd-1115-5059-850d-3927226eb9ee")}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]="a2386adb-d4c5-5725-b406-4246ac40425a")}catch(e){}}();
 import chalk from 'chalk';
 import { resolveDefaultHqRoot } from '../utils/cognito-session.js';
 import { readRegistry } from '../utils/registry.js';
@@ -15,9 +15,10 @@ export function registerPackageListCommand(parent) {
         .command('list')
         .alias('ls')
         .description('List installed and available packages')
-        .action(async () => {
+        .option('--json', 'Machine-readable JSON output')
+        .action(async (opts) => {
         try {
-            await listPackages();
+            await listPackages(opts.json === true || !process.stdout.isTTY);
         }
         catch (error) {
             console.error(chalk.red('List failed:'), error instanceof Error ? error.message : 'Unknown error');
@@ -25,7 +26,32 @@ export function registerPackageListCommand(parent) {
         }
     });
 }
-async function listPackages() {
+async function gatherRegistryPackages() {
+    const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
+    const installed = readRegistry(hqRoot);
+    let entitlements = [];
+    let offline = false;
+    try {
+        const cached = loadCachedTokens();
+        if (cached && !isExpiring(cached, 120)) {
+            const client = new RegistryClient(getRegistryUrl(), cached.accessToken);
+            const result = await client.getMyEntitlements();
+            entitlements = result.entitlements;
+        }
+    }
+    catch {
+        offline = true;
+    }
+    const installedSlugs = new Set(installed.map((p) => p.slug));
+    const available = entitlements.filter((e) => !installedSlugs.has(e.slug));
+    return { installed, available, offline };
+}
+async function listPackages(json) {
+    if (json) {
+        const { installed, available, offline } = await gatherRegistryPackages();
+        process.stdout.write(JSON.stringify({ installed, available, offline }, null, 2) + '\n');
+        return;
+    }
     const hqRoot = resolveDefaultHqRoot({ onMissing: 'throw' });
     const installed = readRegistry(hqRoot);
     // Print installed packages
@@ -70,4 +96,4 @@ async function listPackages() {
     }
 }
 //# sourceMappingURL=pkg-list.js.map
-//# debugId=2ca922cd-1115-5059-850d-3927226eb9ee
+//# debugId=a2386adb-d4c5-5725-b406-4246ac40425a

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]="d7693093-4011-58fa-b5be-805b5f9f5421")}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]="89e1a66a-6a45-56a3-847c-2f0beba1429b")}catch(e){}}();
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
 import { registerAddCommand } from "./commands/add.js";
@@ -23,11 +23,13 @@ import { registerPackageInstallCommand } from "./commands/pkg-install.js";
 import { registerPackageRemoveCommand } from "./commands/pkg-remove.js";
 import { registerPackageUpdateCommand } from "./commands/pkg-update.js";
 import { registerPackageListCommand } from "./commands/pkg-list.js";
+import { registerPacksCommand } from "./commands/packs.js";
 import { registerTeamSyncCommand } from "./commands/team-sync.js";
 import { registerAuthCommands } from "./commands/auth.js";
 import { registerSecretsCommand } from "./commands/secrets.js";
 import { registerRunCommand } from "./commands/run.js";
 import { registerGroupsCommand } from "./commands/groups.js";
+import { registerGroupGrantsCommand } from "./commands/group-grants.js";
 import { registerFilesCommand } from "./commands/files.js";
 import { registerFilesBrowseCommands } from "./commands/files-browse.js";
 import { registerMembersCommand } from "./commands/members.js";
@@ -72,6 +74,11 @@ registerPackageInstallCommand(packagesCmd);
 registerPackageRemoveCommand(packagesCmd);
 registerPackageUpdateCommand(packagesCmd);
 registerPackageListCommand(packagesCmd);
+// Content-pack lifecycle (core/packages/hq-pack-*). Distinct from the registry
+// `packages` system above. Available as both `hq packages packs …` (grouped)
+// and `hq packs …` (top-level convenience).
+registerPacksCommand(packagesCmd);
+registerPacksCommand(program);
 // Top-level shortcuts for package commands
 // "hq install <slug>" = "hq packages install <slug>"
 // "hq remove <slug>"  = "hq packages remove <slug>"
@@ -104,6 +111,9 @@ registerSecretsCommand(program);
 registerRunCommand(program);
 // Groups management (subcommand group — hq groups create|delete|add|remove|list|members)
 registerGroupsCommand(program);
+// Cross-company group grants (subcommand group —
+// hq group-grants grant|revoke|outbound|inbound)
+registerGroupGrantsCommand(program);
 // Files ACL management (subcommand group — hq files share|unshare|acl)
 // `registerFilesCommand` returns the `files` group so we can attach the
 // browse-vs-sync subcommands (`hq files browse`/`cat`) onto the same group.
@@ -148,4 +158,4 @@ registerSignalsCommand(program);
     }
 })();
 //# sourceMappingURL=index.js.map
-//# debugId=d7693093-4011-58fa-b5be-805b5f9f5421
+//# debugId=89e1a66a-6a45-56a3-847c-2f0beba1429b

package/dist/utils/pack-contributions.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Content-pack contribution helpers -- the single source of truth (in TS) for
+ * the `contributes.* -> host-path` symlink mapping that `hq install` wires via
+ * `core/scripts/scan-packages.sh`.
+ *
+ * `pack-install.ts` only INSTALLS content packs (into `core/packages/<name>/`,
+ * tracked by filesystem presence -- there is no registry file). The list /
+ * update / uninstall lifecycle in `commands/packs.ts` needs to reason about the
+ * SAME mapping so it can report link health and cleanly un-wire a pack without
+ * leaving dangling symlinks. That mapping is duplicated today in two places:
+ *
+ *   - core/scripts/scan-packages.sh  (bash `case`, the wiring authority)
+ *   - pack-install.ts validateManifest's `subpaths` record (payload validation)
+ *
+ * This module re-encodes it once for TS callers. A parity test
+ * (`pack-contributions.test.ts`) asserts it matches scan-packages.sh's `case`
+ * arms so the three copies cannot drift.
+ */
+import type { PackManifest, PackContributeKey } from '../types.js';
+/** A single symlink a pack contributes: dst (host path) -> src (inside pack). */
+export interface WiredLink {
+    key: PackContributeKey;
+    item: string;
+    src: string;
+    dst: string;
+}
+export type LinkStatus = 'live' | 'broken' | 'missing' | 'foreign';
+/**
+ * Every symlink a pack's `contributes` block declares. Empty subfields and
+ * non-array values are ignored, mirroring scan-packages.sh.
+ */
+export declare function contributionLinks(hqRoot: string, packDir: string, contributes: Partial<Record<PackContributeKey, string[]>>): WiredLink[];
+/** Classify a host path against the link that should own it. */
+export declare function linkStatus(link: WiredLink): LinkStatus;
+/** A content pack's manifest plus the install-time stamped source. */
+export interface InstalledPackManifest extends PackManifest {
+    source?: string;
+}
+export interface InstalledPack {
+    name: string;
+    dir: string;
+    manifest: InstalledPackManifest | null;
+    error?: string;
+}
+/** Absolute path to `<hqRoot>/core/packages`. */
+export declare function packagesDir(hqRoot: string): string;
+/** Read and shallowly validate a pack's package.yaml. */
+export declare function readPackManifest(packDir: string): {
+    manifest: InstalledPackManifest | null;
+    error?: string;
+};
+/**
+ * Walk `core/packages/<name>/package.yaml`. Skips the `.archive` dir, the bundled
+ * `README.md`, and any non-directory entry. Filesystem presence is the source
+ * of truth for installed content packs.
+ */
+export declare function listInstalledPacks(hqRoot: string): InstalledPack[];
+export interface UnwireResult {
+    unlinked: Array<{
+        key: PackContributeKey;
+        item: string;
+        dst: string;
+    }>;
+    skipped: Array<{
+        key: PackContributeKey;
+        item: string;
+        dst: string;
+        reason: 'foreign' | 'missing';
+    }>;
+}
+/**
+ * Remove only the host symlinks that resolve into THIS pack's directory
+ * (status `live` or `broken`). Foreign links and real files are left in place
+ * -- same collision philosophy as scan-packages.sh. This is what prevents an
+ * uninstall from leaving dangling symlinks behind.
+ */
+export declare function unwirePack(hqRoot: string, packDir: string, contributes: Partial<Record<PackContributeKey, string[]>>): UnwireResult;
+export declare function readHqVersion(hqRoot: string): string | null;
+export interface CatalogEntry {
+    source: string;
+    description?: string;
+    conditional?: string;
+    auto_install?: boolean;
+}
+/** Read `recommended_packages` from core.yaml (the curated content-pack catalog). */
+export declare function readRecommendedPackages(hqRoot: string): CatalogEntry[];
+//# sourceMappingURL=pack-contributions.d.ts.map