@indigoai-us/hq-cli 5.125.0 → 5.126.0

package/dist/lib/lanes/registry.js

@@ -0,0 +1,247 @@
+/**
+ * HQ worker resolution for lanes (spec §5.3).
+ *
+ * Tenancy derives from the registry entry's `path:` prefix, never from the
+ * optional `company:` field. A company path with a missing or contradictory
+ * `company:` is `worker_tenancy_unresolved`, never a global worker.
+ *
+ * The registry does not index personal/workers/ for this command. Naming a
+ * personal worker fails with a clear error and does not fall through to a
+ * same-named entry in another tree.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parseUserYaml } from "../../utils/user-yaml-error.js";
+import { WorkerResolutionError } from "./errors.js";
+export const WORKER_REGISTRY_REL = path.join("core", "workers", "registry.yaml");
+function defaultRegistryDeps() {
+    return {
+        existsSync: (p) => fs.existsSync(p),
+        readFileSync: (p, encoding) => fs.readFileSync(p, encoding),
+        statSync: (p) => fs.statSync(p),
+    };
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function registryPath(hqRoot) {
+    return path.join(hqRoot, WORKER_REGISTRY_REL);
+}
+export function personalWorkerDir(hqRoot, workerId) {
+    return path.join(hqRoot, "personal", "workers", workerId);
+}
+function isExistingPath(p, deps) {
+    try {
+        const st = deps.statSync(p);
+        return st.isFile() || st.isDirectory();
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+export function personalWorkerExists(hqRoot, workerId, deps = defaultRegistryDeps()) {
+    const yamlPath = path.join(personalWorkerDir(hqRoot, workerId), "worker.yaml");
+    try {
+        return deps.statSync(yamlPath).isFile();
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+export function readWorkerRegistryFile(hqRoot, deps = defaultRegistryDeps()) {
+    const filePath = registryPath(hqRoot);
+    if (!deps.existsSync(filePath)) {
+        throw new WorkerResolutionError("worker_registry_unreadable", `Worker registry missing at ${filePath}`, { path: filePath });
+    }
+    let text;
+    try {
+        text = deps.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        throw new WorkerResolutionError("worker_registry_unreadable", `Failed to read ${filePath}: ${err instanceof Error ? err.message : String(err)}`, { path: filePath });
+    }
+    const doc = parseUserYaml(text, filePath);
+    const workers = doc?.workers;
+    if (!Array.isArray(workers)) {
+        throw new WorkerResolutionError("worker_registry_unreadable", `Worker registry workers key is missing or not an array at ${filePath}`, { path: filePath });
+    }
+    const entries = [];
+    for (let i = 0; i < workers.length; i += 1) {
+        const item = workers[i];
+        if (!isPlainObject(item)) {
+            process.stderr.write(`lanes registry: skipping malformed worker entry in ${filePath} at index ${i}: not an object (type=${typeof item})\n`);
+            continue;
+        }
+        if (typeof item.id !== "string" ||
+            item.id.length === 0 ||
+            typeof item.path !== "string" ||
+            item.path.length === 0) {
+            process.stderr.write(`lanes registry: skipping malformed worker entry in ${filePath} at index ${i}: missing id or path (id=${JSON.stringify(item.id)} path=${JSON.stringify(item.path)})\n`);
+            continue;
+        }
+        entries.push({
+            id: item.id,
+            path: item.path,
+            type: typeof item.type === "string" ? item.type : "",
+            visibility: typeof item.visibility === "string" ? item.visibility : undefined,
+            company: typeof item.company === "string" ? item.company : undefined,
+            team: typeof item.team === "string" ? item.team : undefined,
+            status: typeof item.status === "string" ? item.status : undefined,
+            description: typeof item.description === "string" ? item.description : undefined,
+        });
+    }
+    return entries;
+}
+const COMPANY_PATH = /^companies\/([^/]+)\//;
+const PERSONAL_PATH = /^(?:personal\/workers\/)/;
+const CORE_PATH = /^(?:core\/workers\/)/;
+/**
+ * Tenancy from path, not from `company:`. A company path whose field is
+ * missing or disagrees is unresolved — never global.
+ */
+export function tenancyFromRegistryPath(entry) {
+    const normalized = entry.path.replaceAll("\\", "/");
+    if (PERSONAL_PATH.test(normalized)) {
+        return { kind: "personal" };
+    }
+    const companyMatch = COMPANY_PATH.exec(normalized);
+    if (companyMatch) {
+        const pathSlug = companyMatch[1] ?? "";
+        if (!pathSlug) {
+            return { kind: "unresolved", pathSlug, field: entry.company };
+        }
+        const field = entry.company?.trim() ?? "";
+        if (!field || field !== pathSlug) {
+            return { kind: "unresolved", pathSlug, field: field || undefined };
+        }
+        return { kind: "company", slug: pathSlug };
+    }
+    if (CORE_PATH.test(normalized) || normalized.startsWith("core/")) {
+        return { kind: "global" };
+    }
+    // Unknown tree: do not treat as global.
+    return { kind: "unresolved", pathSlug: "", field: entry.company };
+}
+function loadWorkerYaml(hqRoot, relativeDir, deps) {
+    const dir = path.join(hqRoot, relativeDir);
+    const filePath = path.join(dir, "worker.yaml");
+    if (!deps.existsSync(filePath)) {
+        throw new WorkerResolutionError("worker_not_found", `worker.yaml missing at ${filePath}`, { path: filePath });
+    }
+    const text = deps.readFileSync(filePath, "utf8");
+    const doc = parseUserYaml(text, filePath);
+    if (doc === null || typeof doc !== "object" || Array.isArray(doc)) {
+        return {};
+    }
+    return doc;
+}
+/**
+ * Resolve context.base against HQ root, then core/, then the worker directory.
+ * Entries that resolve nowhere are dropped, not passed on.
+ */
+export function resolveContextBasePaths(hqRoot, workerDir, bases, deps = defaultRegistryDeps()) {
+    if (!bases || bases.length === 0)
+        return [];
+    const resolved = [];
+    for (const entry of bases) {
+        if (typeof entry !== "string" || entry.length === 0)
+            continue;
+        const candidates = [
+            path.isAbsolute(entry) ? entry : path.join(hqRoot, entry),
+            path.join(hqRoot, "core", entry),
+            path.join(workerDir, entry),
+        ];
+        const hit = candidates.find((candidate) => isExistingPath(candidate, deps));
+        if (hit)
+            resolved.push(hit);
+    }
+    return resolved;
+}
+export function resolveSkillFiles(workerDir, skills, deps = defaultRegistryDeps()) {
+    if (!skills)
+        return [];
+    const files = [];
+    for (const skill of skills) {
+        if (!skill || typeof skill.file !== "string" || skill.file.length === 0) {
+            continue;
+        }
+        const candidate = path.isAbsolute(skill.file)
+            ? skill.file
+            : path.join(workerDir, skill.file);
+        if (isExistingPath(candidate, deps))
+            files.push(candidate);
+    }
+    return files;
+}
+function humanCheckpointsOf(yaml) {
+    const raw = yaml.verification?.human_checkpoints;
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((item) => typeof item === "string");
+}
+export function resolveLaneWorker(hqRoot, workerId, laneCompany, deps = defaultRegistryDeps()) {
+    if (personalWorkerExists(hqRoot, workerId, deps)) {
+        throw new WorkerResolutionError("personal_worker_unindexed", `Worker ${JSON.stringify(workerId)} lives under personal/workers/ which the registry does not index; --worker cannot resolve personal workers`, {
+            worker: workerId,
+            path: path.join("personal", "workers", workerId).replaceAll("\\", "/"),
+        });
+    }
+    const entries = readWorkerRegistryFile(hqRoot, deps);
+    const entry = entries.find((item) => item.id === workerId);
+    if (!entry) {
+        throw new WorkerResolutionError("worker_not_found", `Worker ${JSON.stringify(workerId)} is not in core/workers/registry.yaml`, { worker: workerId });
+    }
+    const tenancy = tenancyFromRegistryPath(entry);
+    if (tenancy.kind === "personal") {
+        throw new WorkerResolutionError("personal_worker_unindexed", `Worker ${JSON.stringify(workerId)} is registered under personal/workers/ which lanes do not admit`, { worker: workerId, path: entry.path });
+    }
+    if (tenancy.kind === "unresolved") {
+        throw new WorkerResolutionError("worker_tenancy_unresolved", `Worker ${JSON.stringify(workerId)} has a company path whose company field is missing or contradicts the path`, {
+            worker: workerId,
+            path: entry.path,
+            path_slug: tenancy.pathSlug,
+            company_field: tenancy.field ?? null,
+        });
+    }
+    if (tenancy.kind === "company") {
+        if (!laneCompany || laneCompany !== tenancy.slug) {
+            throw new WorkerResolutionError("worker_not_available", `Worker ${JSON.stringify(workerId)} belongs to company ${tenancy.slug} and is not available to ${laneCompany ?? "(none)"}`, {
+                worker: workerId,
+                worker_company: tenancy.slug,
+                lane_company: laneCompany ?? null,
+            });
+        }
+    }
+    const status = entry.status && entry.status.length > 0 ? entry.status : "active";
+    if (status !== "active") {
+        throw new WorkerResolutionError("worker_not_active", `Worker ${JSON.stringify(workerId)} has status ${JSON.stringify(status)} (need active)`, { worker: workerId, status });
+    }
+    const relativeDir = entry.path.replace(/\/+$/, "");
+    const workerDir = path.join(hqRoot, relativeDir);
+    const workerYaml = loadWorkerYaml(hqRoot, relativeDir, deps);
+    const resolvedContextBase = resolveContextBasePaths(hqRoot, workerDir, workerYaml.context?.base, deps);
+    const skillFiles = resolveSkillFiles(workerDir, workerYaml.skills, deps);
+    return {
+        id: entry.id,
+        path: entry.path,
+        type: entry.type,
+        status,
+        visibility: entry.visibility,
+        description: entry.description,
+        tenancy,
+        workerYaml,
+        workerDir,
+        resolvedContextBase,
+        skillFiles,
+        defaultTimeout: workerYaml.execution?.max_runtime,
+        approvalRequired: workerYaml.verification?.approval_required === true,
+        humanCheckpoints: humanCheckpointsOf(workerYaml),
+    };
+}
+//# sourceMappingURL=registry.js.map

package/dist/lib/lanes/store.d.ts

@@ -0,0 +1,64 @@
+/**
+ * File-backed lane / question record store (spec §10, §10.1).
+ *
+ * Root: workspace/lanes/ under the HQ root. One stable path per record;
+ * `status` is the pending/answered discriminator — files are never moved
+ * between directories. Every mutation is temp-file-plus-rename and a
+ * compare-and-set on `version`. Histories are capped at 50 at the append site.
+ */
+import * as fs from "node:fs";
+import { type AttributionHistoryEntry, type LaneRecord, type QuestionRecord, type RoutingHistoryEntry, type SeniorHistoryEntry } from "./types.js";
+export declare const LANES_STORE_REL: string;
+export declare const LANE_RECORDS_DIR = "lanes";
+export declare const QUESTION_RECORDS_DIR = "questions";
+export declare const PENDING_INDEX_DIR: string;
+export interface StoreDeps {
+    now: () => Date;
+    hostname: () => string;
+    mkdirSync: typeof fs.mkdirSync;
+    readFileSync: typeof fs.readFileSync;
+    writeFileSync: typeof fs.writeFileSync;
+    renameSync: typeof fs.renameSync;
+    unlinkSync: typeof fs.unlinkSync;
+    existsSync: typeof fs.existsSync;
+    readdirSync: typeof fs.readdirSync;
+    openSync: typeof fs.openSync;
+    closeSync: typeof fs.closeSync;
+    fsyncSync: typeof fs.fsyncSync;
+    chmodSync: typeof fs.chmodSync;
+}
+export declare function resolveStoreHqRoot(hqRoot?: string): string;
+export declare function lanesStoreRoot(hqRoot?: string): string;
+export declare function laneRecordPath(hqRoot: string, laneId: string): string;
+export declare function questionRecordPath(hqRoot: string, questionId: string): string;
+export declare function pendingMarkerPath(hqRoot: string, questionId: string): string;
+export declare function sanitizeHostComponent(hostname: string): string;
+/** Collision-safe across machines: ULID plus a host component. */
+export declare function mintLaneId(deps?: Pick<StoreDeps, "now" | "hostname">): string;
+export declare function mintQuestionId(deps?: Pick<StoreDeps, "now" | "hostname">): string;
+export declare function appendCappedHistory<T>(history: readonly T[], entry: T, cap?: number): T[];
+export declare function parseLaneRecord(raw: unknown, filePath?: string): LaneRecord;
+export declare function parseQuestionRecord(raw: unknown, filePath?: string): QuestionRecord;
+/**
+ * HQ Sync sibling-twin grammar from `@indigoai-us/hq-cloud` `buildConflictPath`:
+ * `<file>.json.conflict-<ISO-with-dashes>-<machine>.json`
+ * (legacy twins; current engines park losers under `.hq/conflict-backups/`,
+ * but merge-on-read still has to recover the ones already on disk).
+ */
+export declare function isConflictSidecarName(recordBasename: string, name: string): boolean;
+export declare function mergeLaneRecords(live: LaneRecord, sidecars: readonly LaneRecord[]): LaneRecord;
+export declare function mergeQuestionRecords(live: QuestionRecord, sidecars: readonly QuestionRecord[]): QuestionRecord;
+export declare function tryReadLane(hqRoot: string, laneId: string, deps?: StoreDeps): LaneRecord | null;
+export declare function readLane(hqRoot: string, laneId: string, deps?: StoreDeps): LaneRecord;
+export declare function tryReadQuestion(hqRoot: string, questionId: string, deps?: StoreDeps): QuestionRecord | null;
+export declare function readQuestion(hqRoot: string, questionId: string, deps?: StoreDeps): QuestionRecord;
+export declare function createLane(hqRoot: string, init: Omit<LaneRecord, "schema_version" | "lane_id" | "version" | "created_at" | "updated_at"> & Partial<Pick<LaneRecord, "schema_version" | "lane_id" | "version" | "created_at" | "updated_at">>, deps?: StoreDeps): LaneRecord;
+export declare function updateLane(hqRoot: string, laneId: string, expectedVersion: number, updater: (current: LaneRecord) => LaneRecord, deps?: StoreDeps): LaneRecord;
+export declare function appendLaneSeniorHistory(hqRoot: string, laneId: string, expectedVersion: number, entry: SeniorHistoryEntry, deps?: StoreDeps): LaneRecord;
+export declare function appendLaneAttribution(hqRoot: string, laneId: string, expectedVersion: number, entry: AttributionHistoryEntry, deps?: StoreDeps): LaneRecord;
+export declare function createQuestion(hqRoot: string, init: Omit<QuestionRecord, "schema_version" | "question_id" | "version"> & Partial<Pick<QuestionRecord, "schema_version" | "question_id" | "version">>, deps?: StoreDeps): QuestionRecord;
+export declare function updateQuestion(hqRoot: string, questionId: string, expectedVersion: number, updater: (current: QuestionRecord) => QuestionRecord, deps?: StoreDeps): QuestionRecord;
+export declare function appendQuestionRouting(hqRoot: string, questionId: string, expectedVersion: number, entry: RoutingHistoryEntry, deps?: StoreDeps): QuestionRecord;
+export declare function listLaneIds(hqRoot: string, deps?: StoreDeps): string[];
+export declare function listQuestionIds(hqRoot: string, deps?: StoreDeps): string[];
+//# sourceMappingURL=store.d.ts.map