@indigoai-us/hq-cli 5.291.0 → 5.292.0

package/dist/lib/checkpoint-ontology/merge-copies.js

@@ -27,16 +27,25 @@
  *
  * A signal whose `entity_refs` names a copy holds that copy: signals are
  * server-owned, so the ref cannot be re-pointed from here. With `rewriteRefs`
- * (flag `checkpoint.ontology.merge-rewrite-refs`) signal refs, invoice and
- * bill links, source and knowledge links are re-pointed at the survivor, the
- * survivor receives the copy's `external_ids` and `web_domains`, and only a
- * link from another copy or an external id conflict holds a pair.
+ * (flag `checkpoint.ontology.merge-rewrite-refs`) invoice and bill links and
+ * knowledge links are re-pointed at the survivor and the survivor receives
+ * the copy's `external_ids` and `web_domains`. A signal ref or a link from a
+ * source still holds the pair (`server_owned_refs`): the sync client cannot
+ * push those files. A link from another copy or an external id conflict also
+ * holds a pair.
  *
  * With `pairKind: "variants"` (flag `checkpoint.ontology.merge-variants`) the
  * pairs are two-file duplicate groups whose canonical names differ only in
  * case, spacing or punctuation; the survivor is the spaced name, then the
  * higher `signal_count`, then path order. The copy's canonical name becomes
  * an alias of the survivor. Merge and delete work as for numbered copies.
+ *
+ * With `pairKind: "listed"` (flag `checkpoint.ontology.merge-listed-pairs`)
+ * the pairs are exactly the `only` entries, reviewed by a person: no finder
+ * runs, so the names may differ. Each entry must name two entities of one
+ * type; a copy listed twice, or listed both as a copy and as an original, is
+ * skipped as `listed_conflict`. Holds, merge and delete work as for numbered
+ * copies.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -53,6 +62,8 @@ export const MERGE_COPIES_FLAG = "checkpoint.ontology.merge-copies";
  * names differ only in spacing, case or punctuation (CO-65).
  */
 export const MERGE_VARIANTS_FLAG = "checkpoint.ontology.merge-variants";
+/** `merge-copies --listed`: merge exactly the reviewed `--only` pairs (CO-74). */
+export const MERGE_LISTED_PAIRS_FLAG = "checkpoint.ontology.merge-listed-pairs";
 /**
  * `merge-copies --rewrite-refs`: re-point signal `entity_refs`, invoice and
  * bill links, source and knowledge links from a copy to its survivor, and
@@ -219,6 +230,36 @@ export function findVariantPairs(index) {
     pairs.sort((a, b) => a.copy.localeCompare(b.copy));
     return { pairs, skipped };
 }
+/**
+ * The reviewed pairs themselves, for `pairKind: "listed"`. An entry is kept
+ * when both files are indexed entities of one writable type. Read-only.
+ */
+export function findListedPairs(index, only) {
+    const pairs = [];
+    const skipped = [];
+    const copyCount = new Map();
+    for (const entry of only)
+        copyCount.set(entry.copy, (copyCount.get(entry.copy) ?? 0) + 1);
+    const originals = new Set(only.map((entry) => entry.original));
+    for (const entry of only) {
+        const copy = index.byRel.get(entry.copy);
+        const original = index.byRel.get(entry.original);
+        if (copyCount.get(entry.copy) > 1 || originals.has(entry.copy) || entry.copy === entry.original) {
+            skipped.push({ copy: entry.copy, reason: "listed_conflict" });
+        }
+        else if (!copy || !original) {
+            skipped.push({ copy: entry.copy, reason: index.invalid.has(entry.original) ? "original_invalid" : "no_original" });
+        }
+        else if (copy.type !== original.type || !isWritableEntityType(copy.type)) {
+            skipped.push({ copy: entry.copy, reason: "type_differs" });
+        }
+        else {
+            pairs.push({ type: copy.type, copy: entry.copy, original: entry.original });
+        }
+    }
+    pairs.sort((a, b) => a.copy.localeCompare(b.copy));
+    return { pairs, skipped };
+}
 /** Resolve a relative link in `fromRel` to a company-relative path, or null. */
 function resolveLink(fromRel, href) {
     if (/^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith("#") || href.startsWith("/"))
@@ -525,76 +566,13 @@ function referencesCopy(fromRel, content, copy) {
     }
     return false;
 }
-function entityRefOf(rel) {
-    const [, , type, file] = rel.split("/");
-    return `${type}/${file.slice(0, -3)}`;
-}
-/** Re-point block-style `entity_refs` items from a copy to its survivor. */
-function rewriteSignalRefs(content, copyRef, originalRef) {
-    const front = frontLines(content);
-    if (!front)
-        return content;
-    const index = front.lines.findIndex((line) => /^entity_refs:\s*$/.test(line));
-    if (index === -1) {
-        const inline = front.lines.some((line) => /^entity_refs:\s*\S/.test(line));
-        if (inline && content.includes(copyRef))
-            return "signal_ref_format";
-        return content;
-    }
-    let end = index + 1;
-    // A block sequence may sit at the key's own indent: `entity_refs:\n- company/x`.
-    while (end < front.lines.length && (/^\s/.test(front.lines[end]) || /^- /.test(front.lines[end])))
-        end += 1;
-    const itemRe = /^(\s*)- (["']?)([^"'\n]+?)\2\s*$/;
-    const refs = [];
-    for (let i = index + 1; i < end; i += 1) {
-        const match = itemRe.exec(front.lines[i]);
-        if (!match)
-            continue;
-        const hadMd = match[3].endsWith(".md");
-        refs.push({
-            index: i,
-            value: hadMd ? match[3].slice(0, -3) : match[3],
-            hadMd,
-            indent: match[1],
-            quote: match[2],
-        });
-    }
-    const copyItems = refs.filter((item) => item.value === copyRef);
-    if (copyItems.length === 0)
-        return content;
-    const lines = [...front.lines];
-    const remove = new Set();
-    let seenOriginal = refs.some((item) => item.value === originalRef);
-    for (const item of copyItems) {
-        if (seenOriginal) {
-            remove.add(item.index);
-        }
-        else {
-            const value = item.hadMd ? `${originalRef}.md` : originalRef;
-            lines[item.index] = `${item.indent}- ${item.quote}${value}${item.quote}`;
-            seenOriginal = true;
-        }
-    }
-    const next = withFrontLines(content, front, lines.filter((_, i) => !remove.has(i)), fileNewline(content));
-    const oldParsed = parseEntityFile(content);
-    const newParsed = parseEntityFile(next);
-    if (!oldParsed || !newParsed || oldParsed.body !== newParsed.body)
-        return "signal_ref_format";
-    const keys = new Set([...Object.keys(oldParsed.frontmatter), ...Object.keys(newParsed.frontmatter)]);
-    for (const key of keys) {
-        if (key === "entity_refs")
-            continue;
-        if (!isDeepStrictEqual(oldParsed.frontmatter[key], newParsed.frontmatter[key]))
-            return "signal_ref_format";
-    }
-    const newRefs = newParsed.frontmatter.entity_refs;
-    if (!Array.isArray(newRefs) || !newRefs.every((ref) => typeof ref === "string"))
-        return "signal_ref_format";
-    const normalized = newRefs.map((ref) => (ref.endsWith(".md") ? ref.slice(0, -3) : ref));
-    if (!normalized.includes(originalRef) || normalized.includes(copyRef))
-        return "signal_ref_format";
-    return next;
+/**
+ * Signals and sources are written by the server pipeline and the sync
+ * client never pushes them, so a rewrite made here would not reach the
+ * vault (hq-cloud cloud-authoritative.ts).
+ */
+function isServerOwnedRel(rel) {
+    return rel.startsWith("signals/") || rel.startsWith("sources/");
 }
 const REF_KEYS = new Set(["system", "namespace", "objectType", "recordId"]);
 function refKey(ref) {
@@ -871,6 +849,7 @@ function plan(company, index, pairs, allPairs, now, rewriteRefs, resolutions = n
         const unwritable = rewriteRefs
             ? inbound.filter((rel) => copies.has(rel))
             : inbound.filter((rel) => !rel.startsWith("ontology/entities/") || !isWritableEntityType(rel.split("/")[2]) || copies.has(rel));
+        const serverOwned = rewriteRefs ? [...refs, ...inbound.filter(isServerOwnedRel)] : [];
         if (typeof merged === "string") {
             entry.held = "merge_invalid";
             entry.detail = merged;
@@ -879,6 +858,10 @@ function plan(company, index, pairs, allPairs, now, rewriteRefs, resolutions = n
             entry.held = "external_id_conflict";
             entry.detail = identity.conflicts.join(", ");
         }
+        else if (serverOwned.length > 0) {
+            entry.held = "server_owned_refs";
+            entry.detail = [...new Set(serverOwned)].sort().join(", ");
+        }
         else if (!rewriteRefs && refs.length > 0) {
             entry.held = "signal_refs";
         }
@@ -960,7 +943,13 @@ export async function mergeCopies(options) {
     const { hqRoot, company, mode, now } = options;
     const index = buildEntityIndex(company.dir);
     const pairKind = options.pairKind ?? "numbered";
-    const found = pairKind === "variants" ? findVariantPairs(index) : findCopyPairs(index);
+    if (pairKind === "listed" && !options.only)
+        throw new Error("merge-copies: listed pairs need an only list");
+    const found = pairKind === "listed"
+        ? findListedPairs(index, options.only)
+        : pairKind === "variants"
+            ? findVariantPairs(index)
+            : findCopyPairs(index);
     const listed = options.only
         ? found.pairs.filter((pair) => options.only.some((entry) => entry.copy === pair.copy && entry.original === pair.original))
         : found.pairs;
@@ -1060,28 +1049,6 @@ export async function mergeCopies(options) {
                     report.errors.push({ path: rel, error: error.name });
                 }
             }
-            if (!rewriteRefs)
-                continue;
-            const copyRef = entityRefOf(entry.copy);
-            const originalRef = entityRefOf(entry.original);
-            for (const rel of entry.signal_refs) {
-                try {
-                    const content = read(company, rel);
-                    const next = rewriteSignalRefs(content, copyRef, originalRef);
-                    if (next === "signal_ref_format") {
-                        report.errors.push({ path: rel, error: "signal_ref_format" });
-                        continue;
-                    }
-                    if (next === content)
-                        continue;
-                    safeWriteFile(hqRoot, [company.dir], path.join(company.dir, rel), next);
-                    if (!report.rewritten.includes(rel))
-                        report.rewritten.push(rel);
-                }
-                catch (error) {
-                    report.errors.push({ path: rel, error: error.name });
-                }
-            }
         }
     }
     if (mode === "delete") {

package/dist/lib/daemon/flag.d.ts

@@ -6,6 +6,8 @@
 import { type FlagClientOptions, type FlagResolution } from "@indigoai-us/hq-flags-client";
 /** Outposts hand running services to the next daemon on a CLI update instead of restarting them all. */
 export declare const SUPERVISOR_HANDOFF_FLAG = "daemon.supervisor-handoff";
+/** Self-updates build the new CLI beside the running one and swap it in, so `hq` never disappears mid-update. */
+export declare const STAGED_SELF_UPDATE_FLAG = "cli.staged-self-update";
 export interface DaemonFlagClient {
     ready(): Promise<void>;
     explain(flagKey: string, options?: {

package/dist/lib/daemon/flag.js

@@ -9,6 +9,8 @@ import { resolveFlagRegistryEndpoint } from "../flag-registry-endpoint.js";
 import { resolveProcessFlagCompanyContext } from "../flag-registry.js";
 /** Outposts hand running services to the next daemon on a CLI update instead of restarting them all. */
 export const SUPERVISOR_HANDOFF_FLAG = "daemon.supervisor-handoff";
+/** Self-updates build the new CLI beside the running one and swap it in, so `hq` never disappears mid-update. */
+export const STAGED_SELF_UPDATE_FLAG = "cli.staged-self-update";
 const READ_TIMEOUT_MS = 5_000;
 export async function readDaemonFlag(flagKey, options = {}) {
     const env = options.env ?? process.env;

package/dist/utils/scaffold-sibling-references.js

@@ -42,7 +42,7 @@ function shellLocationAliases(contents) {
         const scriptRoot = SCRIPT_ROOT_TOKENS.exec(value);
         if (scriptRoot) {
             const suffix = value.slice(scriptRoot.index + scriptRoot[0].length)
-                .match(/^\/([^"'`\s;|&)]+)/)?.[1] ?? ".";
+                .match(/^\/([^"'`\s;|&)}]+)/)?.[1] ?? ".";
             aliases.set(name, { kind: "asset", baseDirectory: path.posix.normalize(suffix) });
             continue;
         }
@@ -116,15 +116,15 @@ export function scanScaffoldSiblingReferences(scaffoldRoot) {
             (/\b(?:source|exec|bash|sh|node)\b/.test(line) || /^\s*\.\s+/.test(line)));
         for (const line of commandLines) {
             SCRIPT_ROOT_TOKENS.lastIndex = 0;
-            for (const match of line.matchAll(/(?:\$\{SCRIPT_DIR\}|\$SCRIPT_DIR)\/([^"'`\s;|&)]+)/g)) {
+            for (const match of line.matchAll(/(?:\$\{SCRIPT_DIR\}|\$SCRIPT_DIR)\/([^"'`\s;|&)}]+)/g)) {
                 recordRelative(sourceFile, match[1]);
             }
-            const dirnamePath = new RegExp(String.raw `\$\(\s*dirname\s+["']?${BASH_SOURCE_TOKEN}["']?\s*\)(\/[^"'\x60\s;|&)]+)`, "g");
+            const dirnamePath = new RegExp(String.raw `\$\(\s*dirname\s+["']?${BASH_SOURCE_TOKEN}["']?\s*\)(\/[^"'\x60\s;|&)}]+)`, "g");
             for (const match of line.matchAll(dirnamePath))
                 recordRelative(sourceFile, match[1]);
             for (const [alias, location] of aliases) {
                 const escapedAlias = alias.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-                const aliasPath = new RegExp(String.raw `(?:\$\{${escapedAlias}\}|\$${escapedAlias})\/([^"'\x60\s;|&)]+)`, "g");
+                const aliasPath = new RegExp(String.raw `(?:\$\{${escapedAlias}\}|\$${escapedAlias})\/([^"'\x60\s;|&)}]+)`, "g");
                 for (const match of line.matchAll(aliasPath)) {
                     if (location.kind === "hq-root") {
                         const reference = match[0];

package/dist/utils/self-update.d.ts

@@ -161,6 +161,12 @@ export interface SelfUpdateDeps {
     interactive?: boolean;
     /** Best-effort daemon kick after the CLI install converges (tests). */
     restartDaemon?: () => RestartDaemonResult | void;
+    /**
+     * Whether `cli.staged-self-update` is on: build the new version beside the
+     * running package and swap it in, instead of moving the running package
+     * aside for the whole install. Read only when an npm global install is due.
+     */
+    stagedSelfUpdate?: () => Promise<boolean>;
 }
 /**
  * Startup path: the running CLI is behind npm `latest`, so update in place and

package/dist/utils/self-update.js

@@ -64,6 +64,7 @@ import semver from "semver";
 import chalk from "chalk";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
 import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, checkUpdateConvergence, derivePnpmHome, isBunManagedPackageDir, isLocalDependencyInstall, isPnpmManagedPackageDir, isPrefixWritable, nonWritablePrefixNote, openInstallOutput, pnpmUpdateEnv, resolveRunningInstall, runUpdateCommand, runSupervisedUpdateCommand, } from "./version-gate.js";
+import { canStageInstall, stagedNpmInstall } from "./staged-install.js";
 import { acquireUpdateLock as acquireSharedUpdateLock } from "./update-lock.js";
 import { markLatestIneffective } from "./version-check.js";
 import { restartDaemonServiceIfInstalled } from "../lib/mesh/live/daemon/install.js";
@@ -414,12 +415,15 @@ async function updateAndReexec(argv, flavor, known, deps) {
         console.error(chalk.dim(`hq-cli ${latest} is available, but this copy is a local dependency (${install.packageRoot}) — update the project that owns it.`));
         return { action: "skipped", latest };
     }
+    const staged = canStageInstall(install) && (await readStagedSelfUpdateFlag(deps, env));
     const releaseLock = flavor.lock ? (deps.acquireLock ?? acquireUpdateLock)() : () => { };
     if (!releaseLock)
         return { action: "skipped", latest };
     const renamePath = deps.renamePath ?? fs.renameSync;
-    const installSnapshot = snapshotInstall(install, renamePath);
-    if (!installSnapshot) {
+    // The staged install keeps the running package in place until the swap and
+    // restores it itself, so it takes no snapshot.
+    const installSnapshot = staged ? null : snapshotInstall(install, renamePath);
+    if (!staged && !installSnapshot) {
         console.error(chalk.dim("  No backup could be made for this hq-cli install; proceeding without rollback protection."));
     }
     let result;
@@ -440,10 +444,15 @@ async function updateAndReexec(argv, flavor, known, deps) {
         // Forward env only when PNPM_HOME had to be injected, so the common path
         // spawns with the inherited environment and keeps the two-argument runner
         // call it has always made.
-        result =
-            updateEnv === undefined
-                ? runner(plan.cmd, plan.args)
-                : runner(plan.cmd, plan.args, updateEnv);
+        if (staged) {
+            result = stagedNpmInstall(install, latestValid, { run: runner, env, rename: renamePath });
+        }
+        else if (updateEnv === undefined) {
+            result = runner(plan.cmd, plan.args);
+        }
+        else {
+            result = runner(plan.cmd, plan.args, updateEnv);
+        }
         if (!result.ok && installSnapshot) {
             restoredAfterFailure = restoreInstall(installSnapshot, renamePath);
             if (restoredAfterFailure)
@@ -537,6 +546,19 @@ async function updateAndReexec(argv, flavor, known, deps) {
     console.error(chalk.dim(`✓ hq-cli updated to ${latest}.`));
     return { action: "reexec", reexecStatus: status, latest };
 }
+async function readStagedSelfUpdateFlag(deps, env) {
+    try {
+        if (deps.stagedSelfUpdate)
+            return await deps.stagedSelfUpdate();
+        // Loaded here so the startup path pays for the flag client only when an
+        // update is actually due.
+        const { readDaemonFlag, STAGED_SELF_UPDATE_FLAG } = await import("../lib/daemon/flag.js");
+        return await readDaemonFlag(STAGED_SELF_UPDATE_FLAG, { env });
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Startup path: the running CLI is behind npm `latest`, so update in place and
  * re-run the user's command on the new version. `latest` is normally the cached

package/dist/utils/staged-install.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Staged npm self-update: install the new hq-cli beside the running package,
+ * check that it starts, then swap it in with two renames.
+ *
+ * The in-place update moves the live package aside for the whole
+ * `npm install -g`, so anything that starts `hq` during the install finds no
+ * CLI on disk ("hq: command not found", MODULE_NOT_FOUND; outposts primary and
+ * 2, 5.290.0 -> 5.291.0). Here the live package stays in place until the new
+ * one is complete and has answered `--version`.
+ *
+ * Only a plain npm global layout is staged: `<prefix>/lib/node_modules/<pkg>`
+ * as a real directory, with bin links in `<prefix>/bin`. pnpm, Bun, Windows
+ * and linked checkouts keep the in-place update.
+ */
+import * as fs from "node:fs";
+import { type RunningInstall, type UpdateResult } from "./version-gate.js";
+/** Set for the staging install; hq-cli's own postinstall skips itself on it. */
+export declare const STAGED_INSTALL_ENV = "HQ_STAGED_INSTALL";
+export interface StagedInstallDeps {
+    /** Runs the package manager. Defaults to {@link runUpdateCommand}. */
+    run?: (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => UpdateResult;
+    env?: NodeJS.ProcessEnv;
+    /** The version the staged package's `hq --version` reports, or null. */
+    probeVersion?: (packageRoot: string) => string | null;
+    /** The package's postinstall, run from the live path after the swap. */
+    runPostinstall?: (packageRoot: string) => void;
+    rename?: typeof fs.renameSync;
+    /** Removes the staging and backup directories. */
+    remove?: (target: string) => void;
+    platform?: NodeJS.Platform;
+}
+export declare function canStageInstall(install: RunningInstall, platform?: NodeJS.Platform): boolean;
+export declare function stagedNpmInstall(install: RunningInstall, version: string, deps?: StagedInstallDeps): UpdateResult;
+//# sourceMappingURL=staged-install.d.ts.map