@indigoai-us/hq-cli 5.288.0 → 5.290.0

package/dist/lib/bot/setup-explain.js

@@ -0,0 +1,141 @@
+/**
+ * The setup bot's instant "Explain HQ first" answer.
+ *
+ * The setup bot's first question is whether to explain HQ or jump straight in,
+ * with "Explain HQ first" as a suggested reply. The explanation is fixed text,
+ * so a click on that button does not need a model turn: the runner sends the
+ * text from the setup worker's `skills/explain-hq.md` at once, and the bot's
+ * next turn starts with a note saying the explanation already went out.
+ *
+ * The text has one home, the worker file. The model reads the same file when
+ * someone asks for the explanation in their own words, so the two paths never
+ * drift. Anything unexpected (file missing or malformed, the question not
+ * pending, any other message) falls back to the normal model turn.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+/** The suggested reply that triggers the instant answer. Exact match only. */
+export const EXPLAIN_HQ_SUGGESTION = "Explain HQ first";
+/** Where the explanation lives, relative to the setup worker folder. */
+export const EXPLAIN_HQ_FILE = path.join("skills", "explain-hq.md");
+/** The setup bot's progress note in its memory folder (setup worker.yaml). */
+export const SETUP_PROGRESS_FILE = "setup-progress.md";
+/** Runner-owned state, in the bot's own folder (never the model's memory). */
+export const SETUP_INTRO_STATE_FILE = "setup-intro.json";
+const EXPLANATION_HEADING = /^##[ \t]+The explanation[ \t]*$/m;
+const CLOSING_HEADING = /^##[ \t]+After the explanation, when the app sends it[ \t]*$/m;
+/**
+ * Put in front of the next message from the person, so the model knows the
+ * explanation went out without it. It never reaches the person.
+ */
+export const SETUP_EXPLAINED_NOTE = `[Note from the HQ app: the person clicked "${EXPLAIN_HQ_SUGGESTION}", and the app already sent them the explanation ` +
+    `from skills/explain-hq.md word for word, ending by asking whether to start the setup. The explain-or-jump question is answered. ` +
+    "Write `Intro: explained` in your progress note, do not explain HQ again, and carry on with the first unfinished setup step. " +
+    "Their reply to that message follows.]";
+/** The text between a heading and the next `## ` heading (or the end). */
+function sectionAfter(body, heading) {
+    const match = heading.exec(body);
+    if (!match)
+        return null;
+    const rest = body.slice(match.index + match[0].length);
+    const next = /^##[ \t]/m.exec(rest);
+    return (next ? rest.slice(0, next.index) : rest).trim();
+}
+/** True when the closing carries exactly one well-formed suggestions block. */
+function hasSuggestionsBlock(closing) {
+    const fence = /^```hq-block\n(.+)\n```$/m.exec(closing);
+    if (!fence)
+        return false;
+    try {
+        const parsed = JSON.parse(fence[1]);
+        const block = parsed.blocks?.[0];
+        return (parsed.v === 1 &&
+            block?.kind === "suggestions" &&
+            Array.isArray(block.items) &&
+            block.items.length >= 2 &&
+            block.items.every((item) => typeof item === "string" && item.trim().length > 0));
+    }
+    catch {
+        return false;
+    }
+}
+/** Parse the worker file. Null when it is not the shape the app can send. */
+export function parseSetupExplainer(body) {
+    const text = body.replace(/\r\n/g, "\n");
+    const explanation = sectionAfter(text, EXPLANATION_HEADING);
+    const closing = sectionAfter(text, CLOSING_HEADING);
+    if (!explanation || !closing)
+        return null;
+    // The closing must end with the block (nothing after it) so the app shows the buttons.
+    if (!closing.endsWith("```") || !hasSuggestionsBlock(closing))
+        return null;
+    return { explanation, closing, reply: `${explanation}\n\n${closing}` };
+}
+/** Read the explanation from the setup worker folder the bot runs. */
+export function loadSetupExplainer(hqRoot, workerDir) {
+    try {
+        return parseSetupExplainer(fs.readFileSync(path.resolve(hqRoot, workerDir, EXPLAIN_HQ_FILE), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** What the model's progress note says about the opening question. */
+export function readSetupProgressIntro(memoryDir) {
+    let note;
+    try {
+        note = fs.readFileSync(path.join(memoryDir, SETUP_PROGRESS_FILE), "utf8");
+    }
+    catch {
+        return null;
+    }
+    if (/^Status:[ \t]*finished/im.test(note))
+        return "finished";
+    if (/^Intro:[ \t]*(explained|skipped)\b/im.test(note))
+        return "answered";
+    if (/^Intro:[ \t]*asked\b/im.test(note))
+        return "asked";
+    return null;
+}
+export function readSetupIntroState(dir) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(dir, SETUP_INTRO_STATE_FILE), "utf8"));
+        return parsed && parsed.v === 1 ? parsed : { v: 1 };
+    }
+    catch {
+        return { v: 1 };
+    }
+}
+export function patchSetupIntroState(dir, patch) {
+    const next = { ...readSetupIntroState(dir), ...patch, v: 1 };
+    for (const key of Object.keys(next)) {
+        if (next[key] === undefined)
+            delete next[key];
+    }
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const dest = path.join(dir, SETUP_INTRO_STATE_FILE);
+    const tmp = `${dest}.tmp.${process.pid}`;
+    fs.writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, dest);
+    return next;
+}
+/** A bot reply that asks the explain-or-jump question (the words or the button). */
+export function replyOffersExplain(reply) {
+    return reply.includes(`"${EXPLAIN_HQ_SUGGESTION}"`) || /explain HQ to you/i.test(reply);
+}
+/**
+ * The instant answer is due only when ALL of these hold: the message is exactly
+ * the button text with nothing attached, the question is pending (the bot's
+ * last reply offered it, or its note says it asked), and the explanation has
+ * not gone out yet (neither by the app nor, per the note, by the model).
+ */
+export function setupExplainDue(input) {
+    if (input.text !== EXPLAIN_HQ_SUGGESTION || input.attachments > 0)
+        return false;
+    if (input.state.explainedAt)
+        return false;
+    if (input.progress === "answered" || input.progress === "finished")
+        return false;
+    return Boolean(input.state.offeredAt) || input.progress === "asked";
+}
+//# sourceMappingURL=setup-explain.js.map

package/dist/lib/checkpoint-ontology/entity-file.d.ts

@@ -66,6 +66,27 @@ export type PatchResult = {
  * change, the file is returned unchanged so a rerun writes nothing.
  */
 export declare function patchEntityFile(content: string, patch: EntityPatch): PatchResult;
+/** A namespaced record in a source system, as the cloud schema's `external_refs` holds it. */
+export interface ExternalRef {
+    system: string;
+    namespace: string;
+    objectType?: string;
+    recordId: string;
+}
+export interface IdentityPatch {
+    externalIds: Record<string, string>;
+    webDomains: string[];
+    /** When set, the whole `external_refs` list; when absent, the key is left alone. */
+    externalRefs?: ExternalRef[];
+    lastUpdated: string;
+}
+/**
+ * Set `external_ids` and `web_domains` on an existing, valid entity file.
+ * A key whose value is already equal is left as it is; an absent key is
+ * appended at the end of the front matter. Nothing else changes except
+ * `last_updated`. When neither key changes the file is returned unchanged.
+ */
+export declare function setIdentityKeys(content: string, patch: IdentityPatch): PatchResult;
 export interface SignalBackRef {
     signalType: string;
     preview: string;

package/dist/lib/checkpoint-ontology/entity-file.js

@@ -206,6 +206,106 @@ function checkPatched(original, next, aliases, signalCount, lastUpdated) {
         return "patch_last_updated";
     return null;
 }
+function renderExternalIds(ids) {
+    const entries = Object.entries(ids);
+    if (entries.length === 0)
+        return "external_ids: {}";
+    return ["external_ids:", ...entries.map(([key, value]) => `  ${key}: ${quote(value)}`)].join("\n");
+}
+function renderExternalRefs(refs) {
+    if (refs.length === 0)
+        return "external_refs: []";
+    const lines = ["external_refs:"];
+    for (const ref of refs) {
+        lines.push(`  - system: ${quote(ref.system)}`, `    namespace: ${quote(ref.namespace)}`);
+        if (ref.objectType !== undefined)
+            lines.push(`    objectType: ${quote(ref.objectType)}`);
+        lines.push(`    recordId: ${quote(ref.recordId)}`);
+    }
+    return lines.join("\n");
+}
+function renderWebDomains(domains) {
+    if (domains.length === 0)
+        return "web_domains: []";
+    return ["web_domains:", ...domains.map((domain) => `  - ${quote(domain)}`)].join("\n");
+}
+/**
+ * Set `external_ids` and `web_domains` on an existing, valid entity file.
+ * A key whose value is already equal is left as it is; an absent key is
+ * appended at the end of the front matter. Nothing else changes except
+ * `last_updated`. When neither key changes the file is returned unchanged.
+ */
+export function setIdentityKeys(content, patch) {
+    const match = FRONTMATTER_RE.exec(content);
+    const parsed = parseEntityFile(content);
+    if (!match || !parsed)
+        return { ok: false, reason: "unparseable" };
+    const before = validateEntityFrontmatter(parsed.frontmatter);
+    if (typeof before === "string")
+        return { ok: false, reason: `invalid_existing:${before}` };
+    for (const key of Object.keys(patch.externalIds)) {
+        if (!/^[A-Za-z0-9_-]+$/.test(key))
+            return { ok: false, reason: "external_ids_key" };
+    }
+    const currentIds = (parsed.frontmatter.external_ids ?? {});
+    const currentDomains = (parsed.frontmatter.web_domains ?? []);
+    const currentRefs = parsed.frontmatter.external_refs ?? [];
+    const idsChanged = !isDeepStrictEqual(currentIds, patch.externalIds);
+    const domainsChanged = !isDeepStrictEqual(currentDomains, patch.webDomains);
+    const refsChanged = patch.externalRefs !== undefined && !isDeepStrictEqual(currentRefs, patch.externalRefs);
+    if (!idsChanged && !domainsChanged && !refsChanged)
+        return { ok: true, content, changed: false };
+    const newline = content.includes("\r\n") ? "\r\n" : "\n";
+    let lines = match[1].split(/\r?\n/);
+    if (idsChanged) {
+        const rendered = renderExternalIds(patch.externalIds);
+        lines = replaceTopLevelKey(lines, "external_ids", rendered) ?? [...lines, ...rendered.split("\n")];
+    }
+    if (domainsChanged) {
+        const rendered = renderWebDomains(patch.webDomains);
+        lines = replaceTopLevelKey(lines, "web_domains", rendered) ?? [...lines, ...rendered.split("\n")];
+    }
+    if (refsChanged) {
+        const rendered = renderExternalRefs(patch.externalRefs);
+        lines = replaceTopLevelKey(lines, "external_refs", rendered) ?? [...lines, ...rendered.split("\n")];
+    }
+    const stamped = replaceTopLevelKey(lines, "last_updated", `last_updated: ${patch.lastUpdated}`);
+    if (!stamped)
+        return { ok: false, reason: "missing_owned_key" };
+    lines = stamped;
+    const head = content.slice(0, content.indexOf(match[1]));
+    const tail = content.slice(content.indexOf(match[1]) + match[1].length);
+    const next = `${head}${lines.join(newline)}${tail}`;
+    const reparsed = parseEntityFile(next);
+    if (!reparsed)
+        return { ok: false, reason: "patch_unparseable" };
+    if (typeof validateEntityFrontmatter(reparsed.frontmatter) === "string")
+        return { ok: false, reason: "patch_invalid" };
+    const keys = new Set([...Object.keys(parsed.frontmatter), ...Object.keys(reparsed.frontmatter)]);
+    for (const key of keys) {
+        if (key === "external_ids" || key === "web_domains" || key === "last_updated")
+            continue;
+        if (key === "external_refs" && patch.externalRefs !== undefined)
+            continue;
+        if (!isDeepStrictEqual(parsed.frontmatter[key], reparsed.frontmatter[key])) {
+            return { ok: false, reason: `patch_changed_key:${key}` };
+        }
+    }
+    if (!isDeepStrictEqual(reparsed.frontmatter.external_ids ?? {}, patch.externalIds)) {
+        return { ok: false, reason: "patch_external_ids" };
+    }
+    if (!isDeepStrictEqual(reparsed.frontmatter.web_domains ?? [], patch.webDomains)) {
+        return { ok: false, reason: "patch_web_domains" };
+    }
+    if (refsChanged && !isDeepStrictEqual(reparsed.frontmatter.external_refs ?? [], patch.externalRefs)) {
+        return { ok: false, reason: "patch_external_refs" };
+    }
+    if (reparsed.frontmatter.last_updated !== patch.lastUpdated)
+        return { ok: false, reason: "patch_last_updated" };
+    if (reparsed.body !== parsed.body)
+        return { ok: false, reason: "patch_body" };
+    return { ok: true, content: next, changed: true };
+}
 /** hq-pro `previewSignalContent`: first 80 characters, one line. */
 export function previewSignalContent(canonicalContent) {
     const collapsed = canonicalContent.replace(/\s+/g, " ").trim();

package/dist/lib/checkpoint-ontology/merge-copies.d.ts

@@ -26,7 +26,11 @@
  * merge cannot rewrite (a copy, a knowledge file, a signal) is held.
  *
  * A signal whose `entity_refs` names a copy holds that copy: signals are
- * server-owned, so the ref cannot be re-pointed from here.
+ * 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.
  *
  * With `pairKind: "variants"` (flag `checkpoint.ontology.merge-variants`) the
  * pairs are two-file duplicate groups whose canonical names differ only in
@@ -42,6 +46,12 @@ export declare const MERGE_COPIES_FLAG = "checkpoint.ontology.merge-copies";
  * names differ only in spacing, case or punctuation (CO-65).
  */
 export declare const MERGE_VARIANTS_FLAG = "checkpoint.ontology.merge-variants";
+/**
+ * `merge-copies --rewrite-refs`: re-point signal `entity_refs`, invoice and
+ * bill links, source and knowledge links from a copy to its survivor, and
+ * carry the copy's `external_ids` and `web_domains` to the survivor.
+ */
+export declare const MERGE_REWRITE_REFS_FLAG = "checkpoint.ontology.merge-rewrite-refs";
 export type CopySkipReason = "no_original" | "original_invalid" | "identity_differs" | "not_in_duplicate_group" | "group_size" | "type_differs" | "names_differ" | "numbered_copy" | "not_listed";
 export type PairKind = "numbered" | "variants";
 export interface CopySkip {
@@ -55,10 +65,22 @@ export interface CopyPair {
     /** Company-relative path of the original it merges into. */
     original: string;
 }
+/**
+ * How to settle one provider's `external_ids` conflict: `primary` stays in
+ * `external_ids`, and the pair's other id moves to `external_refs` under
+ * `namespace` (the provider account or workspace) and `object_type`.
+ */
+export interface ExternalIdResolution {
+    primary: string;
+    namespace: string;
+    object_type?: string;
+}
 /** One entry of a `--only` list: an exact copy -> original pair. */
 export interface ListedPair {
     copy: string;
     original: string;
+    /** Provider -> resolution, applied only when `rewriteRefs` is on and the ids conflict. */
+    resolve_external_ids?: Record<string, ExternalIdResolution>;
 }
 export interface CopyPlan extends CopyPair {
     add_aliases: string[];
@@ -75,8 +97,14 @@ export interface CopyPlan extends CopyPair {
     /** Signal files whose `entity_refs` name the copy. */
     signal_refs: string[];
     /** Why the copy cannot be merged or deleted from here. */
-    held?: "signal_refs" | "linked_from_unwritable" | "merge_invalid";
+    held?: "signal_refs" | "linked_from_unwritable" | "merge_invalid" | "external_id_conflict";
     detail?: string;
+    /** Keys added to the survivor. Set only when `rewriteRefs` is on. */
+    add_external_ids?: string[];
+    /** Domains added to the survivor. Set only when `rewriteRefs` is on. */
+    add_web_domains?: string[];
+    /** `system:namespace:recordId` refs added to the survivor's `external_refs`. Set only when `rewriteRefs` is on. */
+    add_external_refs?: string[];
     /** Body lines of the copy the merged original lacks; a copy with any is never deleted. */
     unmerged_body_lines: number;
 }
@@ -105,6 +133,8 @@ export interface MergeCopiesReport {
     }[];
     /** Listed entries the finder did not produce. Absent unless `--only` was set. */
     only_unmatched?: ListedPair[];
+    /** Signal, source and knowledge files re-pointed at a survivor. Absent unless `rewriteRefs` was set. */
+    rewritten?: string[];
     /** Entity-file links whose target file does not exist. */
     broken_links_before: number;
     broken_links_after: number;
@@ -123,6 +153,8 @@ export interface MergeCopiesOptions {
     limit?: number;
     /** Handle only these exact pairs; every other found pair is skipped as `not_listed`. */
     only?: ListedPair[];
+    /** Re-point refs and links held today, and carry ids and domains (flag merge-rewrite-refs). */
+    rewriteRefs?: boolean;
     now: Date;
     deleteVaultKey?: DeleteVaultKey;
 }