@indigoai-us/hq-cli 5.88.1 → 5.89.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [5.89.0]
+
+### Added
+
+- Native worker-registry generation and pack contribution scanning via `hq core
+  generate-workers-registry` and `hq core scan-packages`, replacing the staging
+  shell scripts; `hq reindex` now uses the native generator, with output
+  differential-proven against frozen staging references. Syntactically invalid
+  `worker.yaml` files are now quarantined rather than aborting the registry run.
+  (#315)
+
 ## [5.88.1]
 
 ### Fixed

package/assets/scaffold/core/scripts/generate-workers-registry.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# FORWARDER — native implementation: `hq core generate-workers-registry`.
+#
+# This preserves the legacy script ABI. It discovers the live HQ root exactly
+# as the original script did, forwards every argument untouched, and execs the
+# CLI so stdout, stderr, exit status, and signal disposition remain the child's.
+
+set -euo pipefail
+
+HQ_ROOT="${HQ_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+
+if ! command -v hq >/dev/null 2>&1; then
+  echo "generate-workers-registry.sh: requires the hq CLI — this script's implementation now ships with it." >&2
+  echo "Install it with: npm install -g @indigoai-us/hq-cli" >&2
+  exit 127
+fi
+
+exec hq core --hq-root "$HQ_ROOT" generate-workers-registry "$@"

package/assets/scaffold/core/scripts/scan-packages.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# FORWARDER — native implementation: `hq core scan-packages`.
+#
+# The original script treated $HQ_ROOT (or the caller's cwd) as authoritative.
+# Keep that root binding and exec the hidden command so the shell ABI survives.
+
+set -euo pipefail
+
+HQ_ROOT="${HQ_ROOT:-$PWD}"
+
+if ! command -v hq >/dev/null 2>&1; then
+  echo "scan-packages.sh: requires the hq CLI — this script's implementation now ships with it." >&2
+  echo "Install it with: npm install -g @indigoai-us/hq-cli" >&2
+  exit 127
+fi
+
+exec hq core --hq-root "$HQ_ROOT" scan-packages "$@"

package/dist/commands/core.d.ts

@@ -77,6 +77,15 @@ export type WorkerSubcommand = ScaffoldAsset & {
     /** Subcommand name under the `worker` group — `hq core worker <name>`. */
     name: string;
 };
+/**
+ * Native commands that still claim a scaffold forwarder asset. The forwarder
+ * is the backwards-compatible path for old callers; this command is the sole
+ * implementation and must never dispatch back through that asset.
+ */
+export type NativeScaffoldCommand = ScaffoldAsset & {
+    name: string;
+};
+export declare const NATIVE_SCAFFOLD_COMMANDS: NativeScaffoldCommand[];
 /**
  * The `hq core worker <name>` subgroup — worker-scoped skill maintenance.
  *

package/dist/commands/core.js

@@ -33,6 +33,22 @@ import { registerCoreCheckpointCommand } from "./core-checkpoint.js";
 import { resolveLiveRoot } from "../utils/hq-roots.js";
 import { runBundledScript } from "../utils/run-bundled-script.js";
 import { renderIndexTarget } from "../lib/index-render/index.js";
+import { generateWorkersRegistry } from "../lib/workers-registry/index.js";
+import { scanPackages } from "../lib/scan-packages/index.js";
+export const NATIVE_SCAFFOLD_COMMANDS = [
+    {
+        name: "generate-workers-registry",
+        asset: "core/scripts/generate-workers-registry.sh",
+        root: "live",
+        summary: "Regenerate the derived workers registry",
+    },
+    {
+        name: "scan-packages",
+        asset: "core/scripts/scan-packages.sh",
+        root: "live",
+        summary: "Wire installed content-pack contributions",
+    },
+];
 /**
  * The `hq core worker <name>` subgroup — worker-scoped skill maintenance.
  *
@@ -252,6 +268,7 @@ export const SCAFFOLD_ONLY_ASSETS = [
 /** Every claimed bundled asset, used by packaging and interpreter tests. */
 export const SCAFFOLD_ASSETS = [
     ...SCAFFOLD_COMMANDS,
+    ...NATIVE_SCAFFOLD_COMMANDS,
     ...SCAFFOLD_ONLY_ASSETS,
     ...WORKER_SUBCOMMANDS,
 ];
@@ -310,6 +327,27 @@ export function registerCoreCommands(program) {
     // This group primarily hosts manifest-driven bundled assets, but it also
     // hosts native TypeScript plumbing when a scaffold contract needs it.
     registerCoreCheckpointCommand(core);
+    // These command names intentionally own native implementations. Their
+    // similarly named scaffold assets are forwarders, so sending them through
+    // runEntry would recurse back into this command forever.
+    for (const entry of NATIVE_SCAFFOLD_COMMANDS) {
+        core
+            .command(entry.name)
+            .description(entry.summary)
+            .allowUnknownOption()
+            .allowExcessArguments()
+            .helpOption(false)
+            .argument("[args...]", "arguments accepted for shell ABI compatibility")
+            .action(() => {
+            const scope = core.opts();
+            const hqRoot = resolveLiveRoot({ hqRoot: scope.hqRoot });
+            const result = entry.name === "generate-workers-registry"
+                ? generateWorkersRegistry(hqRoot)
+                : scanPackages(hqRoot, { quiet: process.env.HQ_SCAN_QUIET === "1" });
+            if (result.status !== 0)
+                process.exit(result.status);
+        });
+    }
     // `hq core worker <name>` — a nested subgroup for worker-scoped skill
     // maintenance. Nested (rather than flat `hq core worker-<name>`) so the two
     // related operations read as one family.

package/dist/lib/scan-packages/index.d.ts

@@ -0,0 +1,13 @@
+type Logger = (message: string) => void;
+export interface ScanPackagesOptions {
+    quiet?: boolean;
+    log?: Logger;
+    warn?: Logger;
+}
+export interface ScanPackagesResult {
+    status: 0 | 1;
+}
+/** Wire installed pack contributions into their table-declared host locations. */
+export declare function scanPackages(hqRoot: string, options?: ScanPackagesOptions): ScanPackagesResult;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/scan-packages/index.js

@@ -0,0 +1,218 @@
+/** Native implementation of core/scripts/scan-packages.sh. */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as yaml from 'js-yaml';
+import { contributionLinks } from '../../utils/pack-contributions.js';
+function isDirectory(target) { try {
+    return fs.statSync(target).isDirectory();
+}
+catch {
+    return false;
+} }
+function existsOrSymlink(target) { try {
+    fs.lstatSync(target);
+    return true;
+}
+catch {
+    return false;
+} }
+function normalized(relative) { return relative.replaceAll(path.sep, '/'); }
+function readContributes(manifest) {
+    // This deliberately mirrors the staging script's shallow awk grammar rather
+    // than accepting YAML forms the legacy ABI never recognized (notably a
+    // non-empty inline list). Mapping remains single-sourced in
+    // contributionLinks/CONTRIBUTION_TABLE; this only preserves input syntax.
+    const contributes = {};
+    let inside = false;
+    let key;
+    for (const line of fs.readFileSync(manifest, 'utf8').split('\n')) {
+        if (/^\s*#/.test(line) || /^\s*$/.test(line))
+            continue;
+        if (/^contributes:\s*$/.test(line)) {
+            inside = true;
+            key = undefined;
+            continue;
+        }
+        if (inside && /^[^\s]/.test(line)) {
+            inside = false;
+            key = undefined;
+            continue;
+        }
+        const empty = inside && line.match(/^ {2}([a-zA-Z_][a-zA-Z0-9_-]*):\s*\[\s*\]\s*$/);
+        if (empty) {
+            key = undefined;
+            continue;
+        }
+        const header = inside && line.match(/^ {2}([a-zA-Z_][a-zA-Z0-9_-]*):\s*$/);
+        if (header) {
+            key = header[1];
+            continue;
+        }
+        const currentKey = key;
+        const item = inside && currentKey !== undefined && line.match(/^ {4}-\s+(.+)$/);
+        if (!item || currentKey === undefined)
+            continue;
+        let value = item[1].replace(/\s*#.*$/, '').trim();
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))
+            value = value.slice(1, -1);
+        if (!value)
+            continue;
+        (contributes[currentKey] ??= []).push(value);
+    }
+    return contributes;
+}
+function workerId(file) {
+    try {
+        const parsed = yaml.load(fs.readFileSync(file, 'utf8'));
+        const worker = parsed && typeof parsed === 'object' ? parsed.worker : undefined;
+        return worker && typeof worker === 'object' ? String(worker.id ?? '') : '';
+    }
+    catch {
+        return '';
+    }
+}
+function allWorkerYamlFiles(root, relative) {
+    const output = [];
+    const walk = (next, seen) => {
+        const absolute = path.join(root, next);
+        if (!isDirectory(absolute))
+            return;
+        let physical;
+        try {
+            physical = fs.realpathSync(absolute);
+        }
+        catch {
+            return;
+        }
+        if (seen.has(physical))
+            return;
+        const beneath = new Set(seen).add(physical);
+        let names;
+        try {
+            names = fs.readdirSync(absolute);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            const child = path.join(next, name);
+            const childAbsolute = path.join(root, child);
+            if (name === 'worker.yaml' && (() => { try {
+                return fs.statSync(childAbsolute).isFile();
+            }
+            catch {
+                return false;
+            } })())
+                output.push(child);
+            else if (isDirectory(childAbsolute))
+                walk(child, beneath);
+        }
+    };
+    walk(relative, new Set());
+    return output;
+}
+function workerIdClashes(hqRoot, source) {
+    const sourceYaml = path.join(source, 'worker.yaml');
+    if (!fs.existsSync(sourceYaml))
+        return undefined;
+    const id = workerId(sourceYaml);
+    if (!id)
+        return undefined;
+    let physical;
+    try {
+        physical = fs.realpathSync(sourceYaml);
+    }
+    catch {
+        return undefined;
+    }
+    for (const file of [...allWorkerYamlFiles(hqRoot, 'core/workers'), ...allWorkerYamlFiles(hqRoot, 'companies')]) {
+        const relative = normalized(file);
+        if (relative.includes('/_template/') || relative.includes('/_overrides/'))
+            continue;
+        if (workerId(path.join(hqRoot, file)) !== id)
+            continue;
+        try {
+            if (fs.realpathSync(path.join(hqRoot, file)) === physical)
+                continue;
+        }
+        catch { /* compare as a clash */ }
+        return relative;
+    }
+    return undefined;
+}
+function ensureSymlink(link, info, warn) {
+    if (!existsOrSymlink(link.src)) {
+        warn(`payload missing: ${link.src} (declared but not shipped)`);
+        return;
+    }
+    fs.mkdirSync(path.dirname(link.dst), { recursive: true });
+    try {
+        const stat = fs.lstatSync(link.dst);
+        if (stat.isSymbolicLink()) {
+            const existing = fs.readlinkSync(link.dst);
+            if (existing === link.src)
+                return;
+            warn(`collision: ${link.dst} already points at ${existing} (wanted ${link.src}) — skipping`);
+            return;
+        }
+        warn(`collision: ${link.dst} exists as regular file/dir — host content wins, skipping`);
+        return;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    fs.symlinkSync(link.src, link.dst);
+    info(`linked ${link.dst} -> ${link.src}`);
+}
+/** Wire installed pack contributions into their table-declared host locations. */
+export function scanPackages(hqRoot, options = {}) {
+    const log = options.log ?? ((message) => process.stdout.write(`${message}\n`));
+    const warnSink = options.warn ?? ((message) => process.stderr.write(`${message}\n`));
+    const info = (message) => { if (!options.quiet)
+        log(`  ${message}`); };
+    const warn = (message) => warnSink(`  [warn] ${message}`);
+    const packages = path.join(hqRoot, 'core/packages');
+    if (!isDirectory(packages)) {
+        info('[scan-packages] no core/packages/ dir; nothing to wire');
+        return { status: 0 };
+    }
+    let packageNames;
+    try {
+        packageNames = fs.readdirSync(packages).filter((name) => !name.startsWith('.')).sort();
+    }
+    catch (error) {
+        warnSink(`[scan-packages] error: ${error.message}`);
+        return { status: 1 };
+    }
+    let any = false;
+    try {
+        for (const name of packageNames) {
+            const packDir = path.join(packages, name);
+            const manifest = path.join(packDir, 'package.yaml');
+            if (!isDirectory(packDir) || !fs.existsSync(manifest))
+                continue;
+            any = true;
+            info(`[scan-packages] wiring ${name}`);
+            for (const link of contributionLinks(hqRoot, packDir, readContributes(manifest))) {
+                if (link.key === 'workers') {
+                    const clash = workerIdClashes(hqRoot, link.src);
+                    if (clash) {
+                        const id = workerId(path.join(link.src, 'worker.yaml'));
+                        warn(`worker-id collision: pack '${name}' worker id '${id}' is already registered at /${clash} — refusing to wire ${link.dst} (would hard-fail the worker registry on a duplicate id). Resolve the duplicate id (or namespace the pack worker), then re-run.`);
+                        continue;
+                    }
+                }
+                ensureSymlink(link, info, warn);
+            }
+        }
+    }
+    catch (error) {
+        warnSink(`[scan-packages] error: ${error.message}`);
+        return { status: 1 };
+    }
+    if (!any)
+        info('[scan-packages] no hq-pack manifests found in core/packages');
+    return { status: 0 };
+}
+//# sourceMappingURL=index.js.map

package/dist/lib/workers-registry/index.d.ts

@@ -0,0 +1,18 @@
+type Logger = (message: string) => void;
+export interface GenerateWorkersRegistryOptions {
+    now?: Date;
+    /** Receives the shell-compatible stderr lines, without their trailing newline. */
+    log?: Logger;
+}
+export interface GenerateWorkersRegistryResult {
+    status: 0 | 1;
+    written: boolean;
+    quarantined: number;
+}
+/**
+ * Generate core/workers/registry.yaml from worker.yaml files. Invalid workers
+ * are quarantined but do not prevent all valid workers from being registered.
+ */
+export declare function generateWorkersRegistry(hqRoot: string, options?: GenerateWorkersRegistryOptions): GenerateWorkersRegistryResult;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/workers-registry/index.js

@@ -0,0 +1,206 @@
+/** Native implementation of core/scripts/generate-workers-registry.sh. */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as yaml from 'js-yaml';
+function isDirectory(target) {
+    try {
+        return fs.statSync(target).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function isFile(target) {
+    try {
+        return fs.statSync(target).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** A sorted `find -L … -name worker.yaml -type f` equivalent, including symlinked pack workers. */
+function workerYamlFiles(root, relativeRoot) {
+    const output = [];
+    const walk = (relative, ancestors) => {
+        const absolute = path.join(root, relative);
+        if (!isDirectory(absolute))
+            return;
+        let physical;
+        try {
+            physical = fs.realpathSync(absolute);
+        }
+        catch {
+            return;
+        }
+        if (ancestors.has(physical))
+            return; // `find -L` reports loops; a bounded walk is safer here.
+        const nextAncestors = new Set(ancestors).add(physical);
+        let names;
+        try {
+            names = fs.readdirSync(absolute).sort();
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            const childRelative = path.join(relative, name);
+            const child = path.join(root, childRelative);
+            if (name === 'worker.yaml' && isFile(child))
+                output.push(childRelative);
+            else if (isDirectory(child))
+                walk(childRelative, nextAncestors);
+        }
+    };
+    walk(relativeRoot, new Set());
+    return output;
+}
+const UNIT_SEPARATOR = String.fromCharCode(31);
+function scalar(value) {
+    if (value === null || value === undefined)
+        return '';
+    return String(value).replace(/\n+$/, '').replace(/\n/g, ' ').replaceAll(UNIT_SEPARATOR, ' ');
+}
+/** yq's `.worker.<field> // ""` shape; malformed YAML degrades to empty required fields. */
+function readWorkerFields(file) {
+    try {
+        const document = yaml.load(fs.readFileSync(file, 'utf8'));
+        const worker = document && typeof document === 'object'
+            ? document.worker
+            : undefined;
+        const fields = worker && typeof worker === 'object'
+            ? worker
+            : {};
+        return {
+            id: scalar(fields.id), type: scalar(fields.type), description: scalar(fields.description),
+            status: scalar(fields.status), company: scalar(fields.company), team: scalar(fields.team),
+        };
+    }
+    catch {
+        return { id: '', type: '', description: '', status: '', company: '', team: '' };
+    }
+}
+function visibilityOf(relativePath) {
+    return relativePath.startsWith('companies/') ? 'private' : 'public';
+}
+function packAttribution(root, relativeDirectory) {
+    try {
+        const physical = fs.realpathSync(path.join(root, relativeDirectory));
+        const match = physical.match(/(?:^|[/\\])core[/\\]packages[/\\]([^/\\]+)/);
+        return match ? ` [source: pack ${match[1]}]` : '';
+    }
+    catch {
+        return '';
+    }
+}
+function quote(value) {
+    // Deliberately mirrors `${value//\"/\\\"}` in the source shell script.
+    return value.replace(/"/g, '\\"');
+}
+function isoSeconds(now) {
+    return now.toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+function registryText(now, entries) {
+    const lines = [
+        '# Workers Registry — AUTO-GENERATED by core/scripts/generate-workers-registry.sh',
+        '# DO NOT EDIT. Source of truth: worker.yaml in each worker\'s directory.',
+        '# Triggered by .claude/hooks/reindex.sh on Stop / PostToolUse-Write.',
+        '# To register a new worker: create its worker.yaml. Registry regenerates.',
+        '', 'version: "5.0"', `generated_at: "${isoSeconds(now)}"`, '', 'workers:',
+    ];
+    for (const entry of entries) {
+        lines.push(`  - id: "${quote(entry.id)}"`);
+        lines.push(`    path: "${quote(entry.path)}"`);
+        lines.push(`    type: "${quote(entry.type)}"`);
+        lines.push(`    visibility: "${entry.visibility}"`);
+        if (entry.team)
+            lines.push(`    team: "${quote(entry.team)}"`);
+        if (entry.company)
+            lines.push(`    company: "${quote(entry.company)}"`);
+        lines.push(`    status: "${quote(entry.status)}"`);
+        lines.push(`    description: "${quote(entry.description)}"`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+function withoutTimestamp(content) {
+    return content.split('\n').filter((line) => !line.startsWith('generated_at:')).join('\n');
+}
+/**
+ * Generate core/workers/registry.yaml from worker.yaml files. Invalid workers
+ * are quarantined but do not prevent all valid workers from being registered.
+ */
+export function generateWorkersRegistry(hqRoot, options = {}) {
+    const log = options.log ?? ((message) => process.stderr.write(`${message}\n`));
+    const entries = [];
+    let quarantined = 0;
+    const files = [
+        ...workerYamlFiles(hqRoot, 'core/workers'),
+        ...workerYamlFiles(hqRoot, 'companies'),
+        ...workerYamlFiles(hqRoot, 'personal/workers'),
+    ].sort();
+    for (const relativeFile of files) {
+        if (relativeFile.startsWith('companies/_template/') || /(?:^|[/\\])_overrides(?:[/\\]|$)/.test(relativeFile))
+            continue;
+        const fields = readWorkerFields(path.join(hqRoot, relativeFile));
+        const missing = ['id', 'type', 'description'].filter((key) => !fields[key]);
+        if (missing.length > 0) {
+            const relativeDir = path.dirname(relativeFile);
+            const attribution = packAttribution(hqRoot, relativeDir);
+            const remedy = attribution
+                ? `this worker ships from an installed pack — its on-disk copy is likely stale; run 'hq packs update ${attribution.slice(' [source: pack '.length, -1)}' to refresh it (you cannot edit the protected core/ copy directly). If it persists after refreshing, the pack's worker.yaml needs the field(s) added upstream`
+                : 'fix the worker.yaml and re-run';
+            log(`generate-workers-registry: QUARANTINED ${relativeFile.replaceAll(path.sep, '/')} — missing required field(s): ${missing.join(', ')}${attribution} (excluded from registry; ${remedy})`);
+            quarantined++;
+            continue;
+        }
+        entries.push({
+            ...fields,
+            status: fields.status === 'null' || !fields.status ? 'active' : fields.status,
+            company: fields.company === 'null' ? '' : fields.company,
+            team: fields.team === 'null' ? '' : fields.team,
+            path: `${path.dirname(relativeFile).replaceAll(path.sep, '/')}/`,
+            visibility: visibilityOf(relativeFile),
+        });
+    }
+    entries.sort((a, b) => a.id.localeCompare(b.id) || a.path.localeCompare(b.path));
+    const kept = [];
+    const hasDuplicates = entries.some((entry, index) => index > 0 && entries[index - 1].id === entry.id);
+    if (hasDuplicates) {
+        log('generate-workers-registry: WARNING duplicate worker id(s) detected — keeping the first copy of each and skipping the rest (registry still generated; resolve the clash to silence this):');
+    }
+    for (let index = 0; index < entries.length;) {
+        let end = index + 1;
+        while (end < entries.length && entries[end].id === entries[index].id)
+            end++;
+        const group = entries.slice(index, end);
+        const winner = group[0];
+        kept.push(winner);
+        if (group.length > 1) {
+            log(`  duplicate id '${winner.id}' — KEEPING ${winner.path}${packAttribution(hqRoot, winner.path)}`);
+            for (const skipped of group.slice(1)) {
+                log(`  duplicate id '${skipped.id}' — SKIPPING ${skipped.path}${packAttribution(hqRoot, skipped.path)}`);
+            }
+        }
+        index = end;
+    }
+    if (hasDuplicates)
+        log('  Fix: change worker.id in one of the colliding worker.yaml files (or namespace the pack\'s id) to make it unique.');
+    const output = registryText(options.now ?? new Date(), kept);
+    const registry = path.join(hqRoot, 'core/workers/registry.yaml');
+    let written = true;
+    if (fs.existsSync(registry) && withoutTimestamp(fs.readFileSync(registry, 'utf8')) === withoutTimestamp(output))
+        written = false;
+    if (written) {
+        fs.mkdirSync(path.dirname(registry), { recursive: true });
+        fs.writeFileSync(registry, output);
+        log('generate-workers-registry: wrote core/workers/registry.yaml');
+    }
+    else {
+        log('generate-workers-registry: core/workers/registry.yaml unchanged');
+    }
+    if (quarantined > 0) {
+        log(`generate-workers-registry: wrote registry for all VALID workers; quarantined ${quarantined} problem(s) above (loud + partial, never a silent total block). Fix the reported worker.yaml file(s) and re-run to register them.`);
+        return { status: 1, written, quarantined };
+    }
+    return { status: 0, written, quarantined };
+}
+//# sourceMappingURL=index.js.map

package/package.json

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