@automaton-labs/aib 0.0.7 → 0.0.8

package/dist/commands/help-command.js

@@ -1,7 +1,460 @@
-"use strict";var H=exports&&exports.__createBinding||(Object.create?(function(e,t,n,r){r===void 0&&(r=n);var i=Object.getOwnPropertyDescriptor(t,n);(!i||("get"in i?!t.__esModule:i.writable||i.configurable))&&(i={enumerable:!0,get:function(){return t[n]}}),Object.defineProperty(e,r,i)}):(function(e,t,n,r){r===void 0&&(r=n),e[r]=t[n]})),O=exports&&exports.__setModuleDefault||(Object.create?(function(e,t){Object.defineProperty(e,"default",{enumerable:!0,value:t})}):function(e,t){e.default=t}),g=exports&&exports.__importStar||(function(){var e=function(t){return e=Object.getOwnPropertyNames||function(n){var r=[];for(var i in n)Object.prototype.hasOwnProperty.call(n,i)&&(r[r.length]=i);return r},e(t)};return function(t){if(t&&t.__esModule)return t;var n={};if(t!=null)for(var r=e(t),i=0;i<r.length;i++)r[i]!=="default"&&H(n,t,r[i]);return O(n,t),n}})();Object.defineProperty(exports,"__esModule",{value:!0}),exports.runHelpCommand=$,exports.resolveHelpRoot=d;const l=g(require("node:fs")),c=g(require("node:path")),p=require("../content/content-bundle"),f=require("../shared/agent-text"),m=require("../shared/errors"),S=require("../shared/stdin-examples"),b=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"]]),y=["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","rg","reveal"];function $(e){if(C(e))return q();const t=T(e);if(t.length===0)return h();let r=d(),i=w(t,r);if(r.source==="cache"&&i.targets.length===0&&i.unknown.length>0){const o=j();if(o){const a=w(t,o);(a.targets.length>0||a.unknown.length<i.unknown.length)&&(r=o,i=a)}}if(i.targets.length===0&&i.unknown.length===0)return h();const u=i.targets.map(o=>{const a=c.join(r.dir,o.file);return l.existsSync(a)?{target:o,text:_(l.readFileSync(a,"utf8").trim(),r.dir)}:null}).filter(o=>o!==null);if(u.length===1&&i.unknown.length===0){const o=u[0];return o?(0,f.attachAgentText)({operation:"help",topic:o.target.id,source:r.source},o.text):h()}const s=[...u.map(o=>`// ${o.target.id}
-${o.text}`),...i.unknown.length>0?[["Unknown help topics:",...i.unknown].join(`
-`)]:[]].join(`
-
-`);if(i.unknown.length>0)throw new m.CliError("HELP_TOPIC_NOT_FOUND",s,{topics:u.map(o=>o.target.id),unknown:i.unknown,helpRoot:r.dir,available:y});return(0,f.attachAgentText)({operation:"help",topics:u.map(o=>o.target.id),source:r.source},s)}function C(e){const t=e.filter(n=>n!=="help");return t.length===1&&t[0]==="status"}function h(){const e=k(),t=e?_(l.readFileSync(c.join(e.dir,"help-index.md"),"utf8").trim(),e.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","  aib config aliases"].join(`
-`);return(0,f.attachAgentText)({operation:"help",topic:"index",available:y},t)}function k(){try{const t=d();if(l.existsSync(c.join(t.dir,"help-index.md")))return t}catch{}const e=j();return e&&l.existsSync(c.join(e.dir,"help-index.md"))?e:null}function _(e,t){return e.replace(/\{\{([a-z0-9_.-]+)\}\}/gi,(n,r)=>{try{return(0,S.formatHelpToken)(r,t)}catch(i){throw new m.CliError("HELP_TOKEN_NOT_FOUND",i instanceof Error?i.message:String(i),{token:r,helpRoot:t})}})}function T(e){return e.filter(t=>t!=="help")}function w(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=P(e,t);if(n)return{targets:[n],unknown:[]};const r=[],i=[];for(const u of e.filter(s=>!s.startsWith("--"))){const s=u.trim(),o=A(s,t);if(o){r.push(o);continue}i.push(s)}return{targets:r,unknown:i}}function P(e,t){const n=e.join(" ").trim();if(!n)return null;if(n==="bootstrap")return{id:"bootstrap",input:n,file:"bootstrap.md"};const r=b.get(n.toLowerCase());if(r)return{id:r,input:n,file:c.join("topics",`${r}.md`)};const i=n.replace(/\s+/g,".");return v(t,i)?{id:i,input:n,file:c.join("topics",`${i}.md`)}:null}function A(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=b.get(e.toLowerCase());if(n)return{id:n,input:e,file:c.join("topics",`${n}.md`)};if(v(t,e))return{id:e,input:e,file:c.join("topics",`${e}.md`)};const r=E(t,e);return r?{id:r,input:e,file:c.join("topics",`${r}.md`)}:null}function q(){const e=d(),t=R(e.dir),n=(0,p.collectContentCandidates)(),r=t&&x(t.topics)?Object.keys(t.topics).length:M(e.dir),i=typeof t?.contentHash=="string"?t.contentHash:void 0,u=["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}`]:[],...i?[`contentHash: ${L(i)}`]:[],`topics: ${r}`,"","checked:",...n.map(s=>{const o=s.valid?"ok":`skip (${s.reason??"invalid"})`;return`${s.source}: ${o} ${s.dir}`})].join(`
-`);return(0,f.attachAgentText)({operation:"help.status",source:e.source,path:e.dir,assetsOk:(0,p.directoryHasHelp)(e.dir),metadataOk:t!==null,topicCount:r,meta:t??null,candidates:n},u)}function d(){return(0,p.resolveContentRoot)()}function j(){const e=(0,p.collectContentCandidates)().find(t=>t.source==="bundled"&&t.valid);return e?{dir:e.dir,source:e.source}:null}function R(e){const t=c.join(e,"help-meta.json");if(!l.existsSync(t))return null;try{const n=JSON.parse(l.readFileSync(t,"utf8"));return x(n)?n:null}catch{return null}}function M(e){const t=c.join(e,"topics");return l.existsSync(t)?l.readdirSync(t).filter(n=>n.endsWith(".md")).length:0}function v(e,t){return l.existsSync(c.join(e.dir,"topics",`${t}.md`))}function E(e,t){const n=I(e.dir),r=t.toLowerCase(),i=n.filter(u=>{const s=u.toLowerCase();return s.endsWith(`.${r}`)||s===r});return i.length===1?i[0]??null:null}function I(e){const t=c.join(e,"topics");return l.existsSync(t)?l.readdirSync(t).filter(n=>n.endsWith(".md")).map(n=>n.replace(/\.md$/,"")).sort():[]}function L(e){return e.replace(/^sha256:/,"sha256:").slice(0,19)}function x(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);
+}