@automaton-labs/aib 0.0.6 → 0.0.8

package/dist/commands/help-command.js

@@ -1,7 +1,460 @@
-"use strict";var w=exports&&exports.__createBinding||(Object.create?(function(e,t,n,i){i===void 0&&(i=n);var s=Object.getOwnPropertyDescriptor(t,n);(!s||("get"in s?!t.__esModule:s.writable||s.configurable))&&(s={enumerable:!0,get:function(){return t[n]}}),Object.defineProperty(e,i,s)}):(function(e,t,n,i){i===void 0&&(i=n),e[i]=t[n]})),_=exports&&exports.__setModuleDefault||(Object.create?(function(e,t){Object.defineProperty(e,"default",{enumerable:!0,value:t})}):function(e,t){e.default=t}),m=exports&&exports.__importStar||(function(){var e=function(t){return e=Object.getOwnPropertyNames||function(n){var i=[];for(var s in n)Object.prototype.hasOwnProperty.call(n,s)&&(i[i.length]=s);return i},e(t)};return function(t){if(t&&t.__esModule)return t;var n={};if(t!=null)for(var i=e(t),s=0;s<i.length;s++)i[s]!=="default"&&w(n,t,i[s]);return _(n,t),n}})();Object.defineProperty(exports,"__esModule",{value:!0}),exports.runHelpCommand=x,exports.resolveHelpRoot=d;const c=m(require("node:fs")),o=m(require("node:path")),p=require("../content/content-bundle"),u=require("../shared/agent-text"),v=require("../shared/errors"),j=require("../shared/stdin-examples"),h=new Map([["inspect file","inspect.file"],["inspect imports","inspect.imports"],["inspect exports","inspect.exports"],["inspect members","inspect.members"],["inspect code","inspect.code"],["inspect deps","inspect.deps"],["inspect dependencies","inspect.deps"],["inspect usages","inspect.usages"],["inspect usage","inspect.usages"],["inspect graph","inspect.graph"],["inspect tree","inspect.tree"],["inspect duplicates","inspect.duplicates"],["inspect duplicate","inspect.duplicates"],["inspect cycles","inspect.cycles"],["inspect cycle","inspect.cycles"],["refactor batch","refactor.batch"],["module plan","modulePlan"],["moduleplan","modulePlan"]]),g=["help-protocol","quick-map","help-format","basics","dsl","patterns","config-setup.aliases","config-setup.excludes","config-setup.import-normalize","config-setup.import-rules","config-setup.tsconfigs","session","prefs","selectors","inspect","inspect.file","inspect.imports","inspect.exports","inspect.members","inspect.code","inspect.deps","inspect.usages","inspect.graph","inspect.tree","inspect.duplicates","inspect.cycles","mutation","imports.normalize","rename","move","modulePlan","refactor.batch","view","qr","reveal"];function x(e){if(H(e))return T();const t=S(e);if(t.length===0)return f();const n=d(),i=$(t,n);if(i.targets.length===0&&i.unknown.length===0)return f();const s=i.targets.map(r=>{const a=o.join(n.dir,r.file);return c.existsSync(a)?{target:r,text:O(c.readFileSync(a,"utf8").trim())}:null}).filter(r=>r!==null);if(s.length===1&&i.unknown.length===0){const r=s[0];return r?(0,u.attachAgentText)({operation:"help",topic:r.target.id,source:n.source},r.text):f()}const l=[...s.map(r=>`// ${r.target.id}
-${r.text}`),...i.unknown.length>0?[["Unknown help topics:",...i.unknown].join(`
-`)]:[]].join(`
-
-`);if(i.unknown.length>0)throw new v.CliError("HELP_TOPIC_NOT_FOUND",l,{topics:s.map(r=>r.target.id),unknown:i.unknown,helpRoot:n.dir,available:g});return(0,u.attachAgentText)({operation:"help",topics:s.map(r=>r.target.id),source:n.source},l)}function H(e){const t=e.filter(n=>n!=="help");return t.length===1&&t[0]==="status"}function f(){const e=["Run as: aib help <topic...>","","Start here if this is your first AIB pass:","  bootstrap","","Always after context compaction:","  aib help help-protocol quick-map","  aib config aliases","","Help conventions:","  help-format","","Refresh workflow model:","  basics patterns","","Core focused topics:","  session","  prefs","  selectors","  dsl","  inspect","  mutation","","Feature topics:","  inspect.file","  inspect.imports","  inspect.exports","  inspect.members","  inspect.code","  inspect.deps","  inspect.usages","  inspect.graph","  inspect.tree","  inspect.duplicates","  inspect.cycles","  rename","  move","  modulePlan","  refactor.batch","  imports.normalize","  view","  qr","  reveal"].join(`
-`);return(0,u.attachAgentText)({operation:"help",topic:"index",available:g},e)}function O(e){return e.replace(/\{\{stdin\.examples\}\}/g,(0,j.formatStdinExamples)({includeQr:!1}))}function S(e){return e.filter(t=>t!=="help")}function $(e,t){if(e.length===0)return{targets:[],unknown:[]};if(e.includes("--full"))return{targets:[{id:"full",input:"--full",file:"full.md"}],unknown:[]};const n=C(e,t);if(n)return{targets:[n],unknown:[]};const i=[],s=[];for(const l of e.filter(r=>!r.startsWith("--"))){const r=l.trim(),a=k(r,t);if(a){i.push(a);continue}s.push(r)}return{targets:i,unknown:s}}function C(e,t){const n=e.join(" ").trim();if(!n)return null;if(n==="bootstrap")return{id:"bootstrap",input:n,file:"bootstrap.md"};const i=h.get(n.toLowerCase());if(i)return{id:i,input:n,file:o.join("topics",`${i}.md`)};const s=n.replace(/\s+/g,".");return b(t,s)?{id:s,input:n,file:o.join("topics",`${s}.md`)}:null}function k(e,t){if(!e)return null;if(e==="bootstrap")return{id:"bootstrap",input:e,file:"bootstrap.md"};if(e==="full")return{id:"full",input:e,file:"full.md"};const n=h.get(e.toLowerCase());if(n)return{id:n,input:e,file:o.join("topics",`${n}.md`)};if(b(t,e))return{id:e,input:e,file:o.join("topics",`${e}.md`)};const i=q(t,e);return i?{id:i,input:e,file:o.join("topics",`${i}.md`)}:null}function T(){const e=d(),t=P(e.dir),n=(0,p.collectContentCandidates)(),i=t&&y(t.topics)?Object.keys(t.topics).length:A(e.dir),s=typeof t?.contentHash=="string"?t.contentHash:void 0,l=["aib help status","",`source: ${e.source}`,`path: ${e.dir}`,`assets: ${(0,p.directoryHasHelp)(e.dir)?"ok":"missing"}`,`metadata: ${t?"ok":"missing help-meta.json"}`,...typeof t?.helpVersion=="string"?[`version: ${t.helpVersion}`]:[],...typeof t?.generatedAt=="string"?[`generatedAt: ${t.generatedAt}`]:[],...typeof t?.sourceCommit=="string"?[`sourceCommit: ${t.sourceCommit}`]:[],...s?[`contentHash: ${I(s)}`]:[],`topics: ${i}`,"","checked:",...n.map(r=>{const a=r.valid?"ok":`skip (${r.reason??"invalid"})`;return`${r.source}: ${a} ${r.dir}`})].join(`
-`);return(0,u.attachAgentText)({operation:"help.status",source:e.source,path:e.dir,assetsOk:(0,p.directoryHasHelp)(e.dir),metadataOk:t!==null,topicCount:i,meta:t??null,candidates:n},l)}function d(){return(0,p.resolveContentRoot)()}function P(e){const t=o.join(e,"help-meta.json");if(!c.existsSync(t))return null;try{const n=JSON.parse(c.readFileSync(t,"utf8"));return y(n)?n:null}catch{return null}}function A(e){const t=o.join(e,"topics");return c.existsSync(t)?c.readdirSync(t).filter(n=>n.endsWith(".md")).length:0}function b(e,t){return c.existsSync(o.join(e.dir,"topics",`${t}.md`))}function q(e,t){const n=M(e.dir),i=t.toLowerCase(),s=n.filter(l=>{const r=l.toLowerCase();return r.endsWith(`.${i}`)||r===i});return s.length===1?s[0]??null:null}function M(e){const t=o.join(e,"topics");return c.existsSync(t)?c.readdirSync(t).filter(n=>n.endsWith(".md")).map(n=>n.replace(/\.md$/,"")).sort():[]}function I(e){return e.replace(/^sha256:/,"sha256:").slice(0,19)}function y(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runHelpCommand = runHelpCommand;
+exports.resolveHelpRoot = resolveHelpRoot;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const content_bundle_1 = require("../content/content-bundle");
+const agent_text_1 = require("../shared/agent-text");
+const errors_1 = require("../shared/errors");
+const stdin_examples_1 = require("../shared/stdin-examples");
+const TOPIC_ALIASES = new Map([
+    ["inspect", "inspect.shared"],
+    ["inspect file", "inspect.file"],
+    ["inspect imports", "inspect.imports"],
+    ["inspect exports", "inspect.exports"],
+    ["inspect members", "inspect.members"],
+    ["inspect code", "inspect.code"],
+    ["inspect deps", "inspect.deps"],
+    ["inspect dependencies", "inspect.deps"],
+    ["inspect usages", "inspect.usages"],
+    ["inspect usage", "inspect.usages"],
+    ["inspect graph", "inspect.graph"],
+    ["inspect tree", "inspect.tree"],
+    ["inspect aliasCandidates", "inspect.aliasCandidates"],
+    ["inspect alias candidates", "inspect.aliasCandidates"],
+    ["inspect alias-candidates", "inspect.aliasCandidates"],
+    ["inspect duplicates", "inspect.duplicates"],
+    ["inspect duplicate", "inspect.duplicates"],
+    ["inspect cycles", "inspect.cycles"],
+    ["inspect cycle", "inspect.cycles"],
+    ["mutation", "mutation.shared"],
+    ["mixed mutation", "mutate.mixed"],
+    ["mutate mixed", "mutate.mixed"],
+    ["move to dir", "moveToDir"],
+    ["move todir", "moveToDir"],
+    ["rename file", "renameFile"],
+    ["module plan", "modulePlan"],
+    ["moduleplan", "modulePlan"]
+]);
+const COMMON_TOPICS = [
+    "help-protocol",
+    "quick-map",
+    "rules",
+    "help-format",
+    "basics",
+    "dsl",
+    "patterns",
+    "config-setup.aliases",
+    "config-setup.excludes",
+    "config-setup.import-normalize",
+    "config-setup.import-rules",
+    "config-setup.tsconfigs",
+    "session",
+    "selectors",
+    "inspect.shared",
+    "inspect.file",
+    "inspect.imports",
+    "inspect.exports",
+    "inspect.members",
+    "inspect.code",
+    "inspect.deps",
+    "inspect.usages",
+    "inspect.graph",
+    "inspect.tree",
+    "inspect.aliasCandidates",
+    "inspect.duplicates",
+    "inspect.cycles",
+    "mutation.shared",
+    "imports.normalize",
+    "rename",
+    "move",
+    "moveToDir",
+    "renameFile",
+    "mutate.mixed",
+    "modulePlan",
+    "recipes",
+    "recipe.file-layout",
+    "recipe.import-boundary",
+    "recipe.unfamiliar-area",
+    "recipe.safe-artifact-probing",
+    "view",
+    "qr",
+    "rg",
+    "reveal"
+];
+const BOOTSTRAP_COVERED_TOPICS = new Set([
+    "basics",
+    "patterns",
+    "session",
+    "selectors",
+    "dsl",
+    "inspect.shared",
+    "inspect.file",
+    "inspect.imports",
+    "inspect.exports",
+    "inspect.members",
+    "inspect.code",
+    "inspect.deps",
+    "inspect.usages",
+    "inspect.graph",
+    "inspect.tree",
+    "inspect.duplicates",
+    "inspect.cycles",
+    "mutation.shared",
+    "rename",
+    "move",
+    "mutate.mixed",
+    "modulePlan",
+    "import.rebase",
+    "imports.normalize",
+    "view",
+    "qr",
+    "rg",
+    "reveal"
+]);
+function runHelpCommand(restArgs) {
+    if (isHelpStatus(restArgs)) {
+        return buildHelpStatus();
+    }
+    const args = normalizeHelpArgs(restArgs);
+    if (args.length === 0) {
+        return buildHelpIndex();
+    }
+    const root = resolveHelpRoot();
+    let activeRoot = root;
+    let resolution = resolveHelpTargets(args, activeRoot);
+    if (activeRoot.source === "cache" && resolution.targets.length === 0 && resolution.unknown.length > 0) {
+        const bundled = resolveBundledHelpRoot();
+        if (bundled) {
+            const bundledResolution = resolveHelpTargets(args, bundled);
+            if (bundledResolution.targets.length > 0 || bundledResolution.unknown.length < resolution.unknown.length) {
+                activeRoot = bundled;
+                resolution = bundledResolution;
+            }
+        }
+    }
+    if (resolution.targets.length === 0 && resolution.unknown.length === 0) {
+        return buildHelpIndex();
+    }
+    const suppression = suppressBootstrapCoveredTopics(resolution.targets);
+    const blocks = suppression.targets.map((target) => {
+        const file = path.join(activeRoot.dir, target.file);
+        if (!fs.existsSync(file)) {
+            return null;
+        }
+        return {
+            target,
+            text: renderHelpTokens(fs.readFileSync(file, "utf8").trim(), activeRoot.dir)
+        };
+    }).filter((block) => block !== null);
+    if (blocks.length === 1 && resolution.unknown.length === 0 && suppression.suppressed.length === 0) {
+        const block = blocks[0];
+        if (!block) {
+            return buildHelpIndex();
+        }
+        return (0, agent_text_1.attachAgentText)({
+            operation: "help",
+            topic: block.target.id,
+            source: activeRoot.source
+        }, block.text);
+    }
+    const text = [
+        ...blocks.map((block) => `// ${block.target.id}\n${block.text}`),
+        ...(suppression.suppressed.length > 0
+            ? [formatBootstrapSuppressedTopics(suppression.suppressed)]
+            : []),
+        ...(resolution.unknown.length > 0
+            ? [
+                [
+                    "Unknown help topics:",
+                    ...resolution.unknown
+                ].join("\n")
+            ]
+            : [])
+    ].join("\n\n");
+    if (resolution.unknown.length > 0) {
+        throw new errors_1.CliError("HELP_TOPIC_NOT_FOUND", text, {
+            topics: blocks.map((block) => block.target.id),
+            suppressed: suppression.suppressed,
+            unknown: resolution.unknown,
+            helpRoot: activeRoot.dir,
+            available: COMMON_TOPICS
+        });
+    }
+    return (0, agent_text_1.attachAgentText)({
+        operation: "help",
+        topics: blocks.map((block) => block.target.id),
+        suppressed: suppression.suppressed,
+        source: activeRoot.source
+    }, text);
+}
+function suppressBootstrapCoveredTopics(targets) {
+    const hasBootstrap = targets.some((target) => target.id === "bootstrap");
+    if (!hasBootstrap) {
+        return { targets, suppressed: [] };
+    }
+    const suppressed = [];
+    const seenSuppressed = new Set();
+    const filtered = targets.filter((target) => {
+        if (target.id === "bootstrap" || !BOOTSTRAP_COVERED_TOPICS.has(target.id)) {
+            return true;
+        }
+        if (!seenSuppressed.has(target.id)) {
+            suppressed.push(target.id);
+            seenSuppressed.add(target.id);
+        }
+        return false;
+    });
+    return { targets: filtered, suppressed };
+}
+function formatBootstrapSuppressedTopics(topics) {
+    return [
+        "redundant topics suppressed; bootstrap already includes:",
+        topics.join(", ")
+    ].join("\n");
+}
+function isHelpStatus(restArgs) {
+    const args = restArgs.filter((arg) => arg !== "help");
+    return args.length === 1 && args[0] === "status";
+}
+function buildHelpIndex() {
+    const root = resolveHelpIndexRoot();
+    const text = root
+        ? renderHelpTokens(fs.readFileSync(path.join(root.dir, "help-index.md"), "utf8").trim(), root.dir)
+        : [
+            "Run as: aib help <topic...>",
+            "",
+            "Start here if this is your first AIB pass:",
+            "  bootstrap",
+            "",
+            "After context compaction:",
+            "  aib help help-protocol quick-map recipes rules",
+            "  aib config aliases"
+        ].join("\n");
+    return (0, agent_text_1.attachAgentText)({
+        operation: "help",
+        topic: "index",
+        available: COMMON_TOPICS
+    }, text);
+}
+function resolveHelpIndexRoot() {
+    try {
+        const root = resolveHelpRoot();
+        if (fs.existsSync(path.join(root.dir, "help-index.md"))) {
+            return root;
+        }
+    }
+    catch {
+        // Fall through to bundled/fallback index.
+    }
+    const bundled = resolveBundledHelpRoot();
+    return bundled && fs.existsSync(path.join(bundled.dir, "help-index.md")) ? bundled : null;
+}
+function renderHelpTokens(text, helpRootDir) {
+    return text.replace(/\{\{([a-z0-9_.-]+)\}\}/gi, (_match, tokenName) => {
+        try {
+            return (0, stdin_examples_1.formatHelpToken)(tokenName, helpRootDir);
+        }
+        catch (error) {
+            throw new errors_1.CliError("HELP_TOKEN_NOT_FOUND", error instanceof Error ? error.message : String(error), {
+                token: tokenName,
+                helpRoot: helpRootDir
+            });
+        }
+    });
+}
+function normalizeHelpArgs(restArgs) {
+    return restArgs.filter((arg) => arg !== "help");
+}
+function resolveHelpTargets(args, root) {
+    if (args.length === 0) {
+        return { targets: [], unknown: [] };
+    }
+    if (args.includes("--full")) {
+        return { targets: [{ id: "full", input: "--full", file: "full.md" }], unknown: [] };
+    }
+    const legacySingle = resolveLegacySingleTopic(args, root);
+    if (legacySingle) {
+        return { targets: [legacySingle], unknown: [] };
+    }
+    const targets = [];
+    const unknown = [];
+    for (const rawInput of args.filter((arg) => !arg.startsWith("--"))) {
+        const input = rawInput.trim();
+        const target = tryResolveSingleTopic(input, root);
+        if (target) {
+            targets.push(target);
+            continue;
+        }
+        unknown.push(input);
+    }
+    return { targets, unknown };
+}
+function resolveLegacySingleTopic(args, root) {
+    const normalized = args.join(" ").trim();
+    if (!normalized) {
+        return null;
+    }
+    if (normalized === "bootstrap") {
+        return { id: "bootstrap", input: normalized, file: "bootstrap.md" };
+    }
+    const alias = TOPIC_ALIASES.get(normalized.toLowerCase());
+    if (alias) {
+        return { id: alias, input: normalized, file: path.join("topics", `${alias}.md`) };
+    }
+    const dotted = normalized.replace(/\s+/g, ".");
+    if (topicExists(root, dotted)) {
+        return { id: dotted, input: normalized, file: path.join("topics", `${dotted}.md`) };
+    }
+    return null;
+}
+function tryResolveSingleTopic(input, root) {
+    if (!input) {
+        return null;
+    }
+    if (input === "bootstrap") {
+        return { id: "bootstrap", input, file: "bootstrap.md" };
+    }
+    if (input === "full") {
+        return { id: "full", input, file: "full.md" };
+    }
+    const alias = TOPIC_ALIASES.get(input.toLowerCase());
+    if (alias) {
+        return { id: alias, input, file: path.join("topics", `${alias}.md`) };
+    }
+    if (topicExists(root, input)) {
+        return { id: input, input, file: path.join("topics", `${input}.md`) };
+    }
+    const resolved = resolveUniqueTopicSuffix(root, input);
+    if (resolved) {
+        return { id: resolved, input, file: path.join("topics", `${resolved}.md`) };
+    }
+    return null;
+}
+function buildHelpStatus() {
+    const root = resolveHelpRoot();
+    const meta = readHelpMeta(root.dir);
+    const candidates = (0, content_bundle_1.collectContentCandidates)();
+    const topicCount = meta && isJsonObject(meta.topics)
+        ? Object.keys(meta.topics).length
+        : countTopicFiles(root.dir);
+    const contentHash = typeof meta?.contentHash === "string" ? meta.contentHash : undefined;
+    const text = [
+        "aib help status",
+        "",
+        `source: ${root.source}`,
+        `path: ${root.dir}`,
+        `assets: ${(0, content_bundle_1.directoryHasHelp)(root.dir) ? "ok" : "missing"}`,
+        `metadata: ${meta ? "ok" : "missing help-meta.json"}`,
+        ...(typeof meta?.helpVersion === "string" ? [`version: ${meta.helpVersion}`] : []),
+        ...(typeof meta?.generatedAt === "string" ? [`generatedAt: ${meta.generatedAt}`] : []),
+        ...(typeof meta?.sourceCommit === "string" ? [`sourceCommit: ${meta.sourceCommit}`] : []),
+        ...(contentHash ? [`contentHash: ${compactHash(contentHash)}`] : []),
+        `topics: ${topicCount}`,
+        "",
+        "checked:",
+        ...candidates.map((candidate) => {
+            const status = candidate.valid ? "ok" : `skip (${candidate.reason ?? "invalid"})`;
+            return `${candidate.source}: ${status} ${candidate.dir}`;
+        })
+    ].join("\n");
+    return (0, agent_text_1.attachAgentText)({
+        operation: "help.status",
+        source: root.source,
+        path: root.dir,
+        assetsOk: (0, content_bundle_1.directoryHasHelp)(root.dir),
+        metadataOk: meta !== null,
+        topicCount,
+        meta: meta ?? null,
+        candidates
+    }, text);
+}
+function resolveHelpRoot() {
+    return (0, content_bundle_1.resolveContentRoot)();
+}
+function resolveBundledHelpRoot() {
+    const bundled = (0, content_bundle_1.collectContentCandidates)().find((candidate) => candidate.source === "bundled" && candidate.valid);
+    return bundled ? { dir: bundled.dir, source: bundled.source } : null;
+}
+function readHelpMeta(helpRoot) {
+    const file = path.join(helpRoot, "help-meta.json");
+    if (!fs.existsSync(file)) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        return isJsonObject(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function countTopicFiles(helpRoot) {
+    const topicsDir = path.join(helpRoot, "topics");
+    if (!fs.existsSync(topicsDir)) {
+        return 0;
+    }
+    return fs.readdirSync(topicsDir).filter((file) => file.endsWith(".md")).length;
+}
+function topicExists(root, topic) {
+    return fs.existsSync(path.join(root.dir, "topics", `${topic}.md`));
+}
+function resolveUniqueTopicSuffix(root, input) {
+    const topics = listHelpTopics(root.dir);
+    const normalized = input.toLowerCase();
+    const matches = topics.filter((topic) => {
+        const lower = topic.toLowerCase();
+        return lower.endsWith(`.${normalized}`) || lower === normalized;
+    });
+    return matches.length === 1 ? matches[0] ?? null : null;
+}
+function listHelpTopics(helpRoot) {
+    const topicsDir = path.join(helpRoot, "topics");
+    if (!fs.existsSync(topicsDir)) {
+        return [];
+    }
+    return fs.readdirSync(topicsDir)
+        .filter((file) => file.endsWith(".md"))
+        .map((file) => file.replace(/\.md$/, ""))
+        .sort();
+}
+function compactHash(value) {
+    return value.replace(/^sha256:/, "sha256:").slice(0, 19);
+}
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}