@biaoo/tiangong-wiki 0.2.0

package/dist/core/workflow-context.js

@@ -0,0 +1,188 @@
+import { chmodSync } from "node:fs";
+import path from "node:path";
+import { ensureDirSync, writeTextFileSync } from "../utils/fs.js";
+import { sha256Text } from "../utils/fs.js";
+function shellSingleQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function resolveNodeExecutable() {
+    const currentExec = path.basename(process.execPath).toLowerCase();
+    if (currentExec === "node" || currentExec.startsWith("node")) {
+        return process.execPath;
+    }
+    const npmNodeExecPath = process.env.npm_node_execpath?.trim();
+    if (npmNodeExecPath) {
+        return npmNodeExecPath;
+    }
+    return "node";
+}
+function readableArtifactPrefix(queueItemId) {
+    const normalized = queueItemId
+        .replace(/[\\/]+/g, "__")
+        .replace(/[^A-Za-z0-9._-]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    if (!normalized) {
+        return "queue-item";
+    }
+    return normalized.slice(0, 80);
+}
+export function toWorkflowArtifactId(queueItemId) {
+    return `${readableArtifactPrefix(queueItemId)}--${sha256Text(queueItemId).slice(0, 12)}`;
+}
+export function getWorkflowArtifactSet(paths, queueItemId) {
+    const artifactId = toWorkflowArtifactId(queueItemId);
+    const rootDir = path.join(paths.queueArtifactsPath, artifactId);
+    return {
+        queueItemId,
+        artifactId,
+        rootDir,
+        queueItemPath: path.join(rootDir, "queue-item.json"),
+        promptPath: path.join(rootDir, "prompt.md"),
+        resultPath: path.join(rootDir, "result.json"),
+        skillArtifactsPath: path.join(rootDir, "skill-artifacts"),
+    };
+}
+export function buildVaultWorkflowPrompt(input) {
+    return [
+        "Process one vault queue item.",
+        "",
+        `WORKSPACE_ROOT=${input.workspaceRoot}`,
+        `VAULT_FILE_PATH=${input.vaultFilePath}`,
+        `RESULT_JSON_PATH=${input.resultJsonPath}`,
+        `ALLOW_TEMPLATE_EVOLUTION=${input.allowTemplateEvolution ? "true" : "false"}`,
+        "",
+        "## Environment",
+        "",
+        "Workspace-local skills are available from WORKSPACE_ROOT through normal Codex skill discovery.",
+        "A local tiangong-wiki CLI launcher is already available on PATH for this run.",
+        "",
+        "The tiangong-wiki CLI provides these discovery and search capabilities:",
+        "- `tiangong-wiki type list` / `tiangong-wiki type show <type>` — discover registered page types and their purpose",
+        "- `tiangong-wiki template show <type>` — see the exact frontmatter fields and body structure for a type",
+        "- `tiangong-wiki find [options]` — find pages by structured metadata filters",
+        "- `tiangong-wiki search <query>` — semantic search over page summary embeddings",
+        "- `tiangong-wiki fts <query>` — full-text search over title, tags, and summary",
+        "- `tiangong-wiki list [options]` — list existing wiki pages",
+        "- `tiangong-wiki page-info <pageId>` — show full metadata and edges for one page",
+        "- `tiangong-wiki graph <root>` — traverse the wiki knowledge graph",
+        "- `tiangong-wiki stat` — show aggregate wiki index statistics",
+        "",
+        "Use whichever combination you judge necessary. These are tools at your disposal, not a mandatory checklist.",
+        "",
+        "## Step 1 — Read and Discover",
+        "",
+        "1. Read queue-item.json next to RESULT_JSON_PATH.",
+        "2. Read the target vault file at VAULT_FILE_PATH.",
+        "3. Discover the current page type ontology through the tiangong-wiki CLI. Do not assume any type, template, or default target type.",
+        "4. Understand the existing wiki knowledge landscape before deciding what to create or update:",
+        "   - What pages already exist? Are any of them covering the same or overlapping topics?",
+        "   - What is the current knowledge graph structure? Are there clusters of related pages that this new source naturally connects to?",
+        "   - Does this source introduce genuinely new knowledge, or does it reinforce, extend, or contradict something already captured?",
+        "",
+        "These questions must be answered before proceeding to Step 2.",
+        "",
+        "Keep the run narrowly focused on the target vault file, the current ontology, and the best candidate pages.",
+        "Do not inspect the whole workspace, list broad file trees, or read large reference files unless a concrete command failure blocks you.",
+        "Do not call tiangong-wiki --help or perform broad discovery unless a specific command failure forces it.",
+        "",
+        "## Step 2 — Decide",
+        "",
+        "### Type Selection",
+        "",
+        "Choose the page type that best matches the nature of the knowledge in the source. Query the registered types and understand their intended use before deciding. Do not default to any single type.",
+        "",
+        "### Update vs Create",
+        "",
+        "If an existing page already covers the same topic, prefer updating it over creating a duplicate. Only create a new page when the source introduces a genuinely new topic not yet represented in the wiki.",
+        "",
+        "### Splitting",
+        "",
+        "A single vault source MAY produce multiple pages of different types when the source contains independently reusable knowledge points.",
+        "- At most 5 pages per vault source to avoid over-fragmentation.",
+        "- Link all pages created from the same source via relatedPages.",
+        "",
+        "### Building Relations",
+        "",
+        "Every page you create or update should be connected to the existing knowledge graph where meaningful relations exist. Orphan pages with no relations are acceptable only when the source introduces a topic with no overlap to existing wiki content.",
+        "",
+        "## Step 3 — Create or Update Pages",
+        "",
+        "### Field Conventions",
+        "",
+        "- **vaultPath**: MUST be relative to the vault root. Never use absolute paths. Derive it by stripping the vault root prefix from VAULT_FILE_PATH.",
+        "- **sourceRefs**: Prefer existing wiki page IDs when the new page directly builds on already-indexed wiki pages. Do not put absolute vault paths into sourceRefs. If no existing wiki page is directly referenced, it is acceptable to leave sourceRefs empty.",
+        "- **relatedPages**: Populate with page IDs of related pages discovered in Step 1. Every page should have relations when related content exists in the wiki.",
+        "- **createdAt / updatedAt**: Leave placeholders unchanged or omit them. The system will normalize them to YYYY-MM-DD during indexing and refresh updatedAt on modified pages.",
+        "- **nodeId**: Use a lowercase kebab-case slug derived from the title.",
+        "",
+        "Consult the template for your chosen type before writing a page.",
+        "If ALLOW_TEMPLATE_EVOLUTION=false, do not create templates or new page types.",
+        "",
+        "### Quality Gate",
+        "",
+        "For every changed page, run:",
+        "1. `tiangong-wiki sync --path <page>`",
+        "2. `tiangong-wiki lint --path <page> --format json`",
+        "",
+        "Fix any errors before proceeding. Warnings are acceptable.",
+        "",
+        "## Step 4 — Write Result Manifest",
+        "",
+        "The authoritative threadId is queue-item.json.threadId. Read it from there and copy it unchanged into result.json.threadId. If it is empty on first read, read queue-item.json again immediately before writing the manifest.",
+        "",
+        "Write RESULT_JSON_PATH as one JSON object with: status, decision, reason, threadId, skillsUsed, createdPageIds, updatedPageIds, appliedTypeNames, proposedTypes, actions, lint.",
+        "",
+        "### Allowed Values",
+        "",
+        "- **status**: done | skipped | error. Use done for successful apply or propose_only runs, skipped for skip, and error only when the workflow itself failed. Never use success, completed, failed, or other aliases.",
+        "- **decision**: apply | skip | propose_only. Never use update_existing, create_new, update, create, or other aliases.",
+        "- **actions**: Array of objects, never strings. Allowed action kinds: create_page, update_page, create_template. Every action object must include kind and summary. create_page requires pageType and title. update_page requires pageId. create_template requires pageType and title.",
+        "- **proposedTypes**: Objects with name, reason, suggestedTemplateSections.",
+        "- **lint**: Objects with pageId, errors, warnings.",
+        "",
+        "### Example",
+        "",
+        '{"status":"done","decision":"apply","reason":"Updated the existing method.","threadId":"<copy queue-item.json.threadId>","skillsUsed":["tiangong-wiki-skill"],"createdPageIds":[],"updatedPageIds":["methods/example.md"],"appliedTypeNames":["method"],"proposedTypes":[],"actions":[{"kind":"update_page","pageId":"methods/example.md","pageType":"method","summary":"Updated the page with durable knowledge."}],"lint":[{"pageId":"methods/example.md","errors":0,"warnings":0}]}',
+        "",
+        "If no page change is justified, still write RESULT_JSON_PATH with decision=skip or decision=propose_only and then stop.",
+        "Use RESULT_JSON_PATH only for the final structured manifest. Write raw JSON only, with no Markdown fences and no prose before or after the JSON object.",
+        "The queue item metadata is stored next to RESULT_JSON_PATH as queue-item.json.",
+        "Stop immediately after RESULT_JSON_PATH is fully written.",
+    ].join("\n");
+}
+export function ensureWorkflowArtifactSet(paths, input) {
+    const artifacts = getWorkflowArtifactSet(paths, input.queueItemId);
+    ensureDirSync(paths.queueArtifactsPath);
+    ensureDirSync(artifacts.rootDir);
+    ensureDirSync(artifacts.skillArtifactsPath);
+    const wikiCliWrapperPath = path.join(artifacts.skillArtifactsPath, "tiangong-wiki");
+    const nodeExecutable = resolveNodeExecutable();
+    const cliEntrypoint = path.join(paths.packageRoot, "dist", "index.js");
+    writeTextFileSync(artifacts.queueItemPath, `${JSON.stringify(input.queueItem, null, 2)}\n`);
+    writeTextFileSync(wikiCliWrapperPath, [
+        "#!/bin/sh",
+        'node_bin=${WIKI_CLI_NODE:-}',
+        'if [ -z "$node_bin" ]; then',
+        `  node_bin=${shellSingleQuote(nodeExecutable)}`,
+        "fi",
+        'cli_entry=${WIKI_CLI_ENTRYPOINT:-}',
+        'if [ -z "$cli_entry" ]; then',
+        `  cli_entry=${shellSingleQuote(cliEntrypoint)}`,
+        "fi",
+        'if [ ! -f "$cli_entry" ]; then',
+        '  echo "tiangong-wiki CLI entrypoint not found: ${cli_entry}" >&2',
+        "  exit 127",
+        "fi",
+        'exec "$node_bin" "$cli_entry" "$@"',
+        "",
+    ].join("\n"));
+    chmodSync(wikiCliWrapperPath, 0o755);
+    writeTextFileSync(artifacts.promptPath, input.promptMarkdown ??
+        [
+            "# Vault To Wiki Workflow",
+            "",
+            "This prompt is intentionally minimal and will be populated by the workflow runner.",
+        ].join("\n"));
+    writeTextFileSync(artifacts.resultPath, "");
+    return artifacts;
+}

package/dist/core/workflow-result.js

@@ -0,0 +1,162 @@
+import { AppError } from "../utils/errors.js";
+import { pathExistsSync, readTextFileSync } from "../utils/fs.js";
+function fail(message, details) {
+    throw new AppError(message, "runtime", details);
+}
+function ensureRecord(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        fail(`${label} must be an object`);
+    }
+    return value;
+}
+function ensureString(value, label) {
+    if (typeof value !== "string" || !value.trim()) {
+        fail(`${label} must be a non-empty string`);
+    }
+    return value.trim();
+}
+function ensureStringArray(value, label) {
+    if (!Array.isArray(value)) {
+        fail(`${label} must be an array`);
+    }
+    return value.map((entry, index) => ensureString(entry, `${label}[${index}]`));
+}
+function ensureNumber(value, label) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        fail(`${label} must be a finite number`);
+    }
+    return value;
+}
+function ensureStatus(value) {
+    const status = ensureString(value, "result.status");
+    if (status === "done" || status === "skipped" || status === "error") {
+        return status;
+    }
+    fail(`result.status must be one of done, skipped, error`);
+}
+function ensureDecision(value) {
+    const decision = ensureString(value, "result.decision");
+    if (decision === "skip" || decision === "apply" || decision === "propose_only") {
+        return decision;
+    }
+    fail(`result.decision must be one of skip, apply, propose_only`);
+}
+function parseSourceFile(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const sourceFile = ensureRecord(value, "result.sourceFile");
+    const path = ensureString(sourceFile.path, "result.sourceFile.path");
+    const sha256 = sourceFile.sha256 === undefined ? undefined : ensureString(sourceFile.sha256, "result.sourceFile.sha256");
+    return { path, ...(sha256 ? { sha256 } : {}) };
+}
+function parseProposedTypes(value) {
+    if (!Array.isArray(value)) {
+        fail("result.proposedTypes must be an array");
+    }
+    return value.map((entry, index) => {
+        const proposed = ensureRecord(entry, `result.proposedTypes[${index}]`);
+        return {
+            name: ensureString(proposed.name, `result.proposedTypes[${index}].name`),
+            reason: ensureString(proposed.reason, `result.proposedTypes[${index}].reason`),
+            suggestedTemplateSections: ensureStringArray(proposed.suggestedTemplateSections, `result.proposedTypes[${index}].suggestedTemplateSections`),
+        };
+    });
+}
+function parseActions(value) {
+    if (!Array.isArray(value)) {
+        fail("result.actions must be an array");
+    }
+    return value.map((entry, index) => {
+        const action = ensureRecord(entry, `result.actions[${index}]`);
+        const kind = ensureString(action.kind, `result.actions[${index}].kind`);
+        if (kind !== "create_page" && kind !== "update_page" && kind !== "create_template") {
+            fail(`result.actions[${index}].kind must be create_page, update_page, or create_template`);
+        }
+        const parsed = {
+            kind,
+            summary: ensureString(action.summary, `result.actions[${index}].summary`),
+        };
+        if (action.pageType !== undefined) {
+            parsed.pageType = ensureString(action.pageType, `result.actions[${index}].pageType`);
+        }
+        if (action.pageId !== undefined) {
+            parsed.pageId = ensureString(action.pageId, `result.actions[${index}].pageId`);
+        }
+        if (action.title !== undefined) {
+            parsed.title = ensureString(action.title, `result.actions[${index}].title`);
+        }
+        if ((kind === "create_page" || kind === "create_template") && !parsed.pageType) {
+            fail(`result.actions[${index}].pageType must be provided for ${kind}`);
+        }
+        if (kind === "create_page" && !parsed.title) {
+            fail(`result.actions[${index}].title must be provided for create_page`);
+        }
+        if (kind === "update_page" && !parsed.pageId) {
+            fail(`result.actions[${index}].pageId must be provided for update_page`);
+        }
+        if (kind === "create_template" && !parsed.title) {
+            fail(`result.actions[${index}].title must be provided for create_template`);
+        }
+        return parsed;
+    });
+}
+function parseLint(value) {
+    if (!Array.isArray(value)) {
+        fail("result.lint must be an array");
+    }
+    return value.map((entry, index) => {
+        const lint = ensureRecord(entry, `result.lint[${index}]`);
+        return {
+            pageId: ensureString(lint.pageId, `result.lint[${index}].pageId`),
+            errors: ensureNumber(lint.errors, `result.lint[${index}].errors`),
+            warnings: ensureNumber(lint.warnings, `result.lint[${index}].warnings`),
+        };
+    });
+}
+export function parseWorkflowResult(raw) {
+    try {
+        const result = ensureRecord(raw, "result");
+        const manifest = {
+            status: ensureStatus(result.status),
+            decision: ensureDecision(result.decision),
+            reason: ensureString(result.reason, "result.reason"),
+            threadId: ensureString(result.threadId, "result.threadId"),
+            skillsUsed: ensureStringArray(result.skillsUsed, "result.skillsUsed"),
+            createdPageIds: ensureStringArray(result.createdPageIds, "result.createdPageIds"),
+            updatedPageIds: ensureStringArray(result.updatedPageIds, "result.updatedPageIds"),
+            appliedTypeNames: ensureStringArray(result.appliedTypeNames, "result.appliedTypeNames"),
+            proposedTypes: parseProposedTypes(result.proposedTypes),
+            actions: parseActions(result.actions),
+            lint: parseLint(result.lint),
+            sourceFile: parseSourceFile(result.sourceFile),
+        };
+        if (manifest.decision === "apply" && manifest.actions.length === 0) {
+            fail("result.actions must contain at least one action when decision=apply");
+        }
+        return manifest;
+    }
+    catch (error) {
+        if (error instanceof AppError) {
+            throw error;
+        }
+        fail("Failed to parse workflow result", { cause: error instanceof Error ? error.message : String(error) });
+    }
+}
+export function readWorkflowResult(resultPath) {
+    if (!pathExistsSync(resultPath)) {
+        fail(`Workflow result not found: ${resultPath}`);
+    }
+    const rawText = readTextFileSync(resultPath);
+    let parsed;
+    try {
+        parsed = JSON.parse(rawText);
+    }
+    catch (error) {
+        fail("Workflow result is not valid JSON", {
+            resultPath,
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+    return parseWorkflowResult(parsed);
+}

package/dist/core/workspace-bootstrap.js

@@ -0,0 +1,30 @@
+import path from "node:path";
+import { copyDirectoryContentsSync, copyFileIfMissingSync, ensureDirSync, isDirectoryEmptySync, pathExistsSync, } from "../utils/fs.js";
+function ensureDirectory(dirPath, createdDirectories) {
+    if (!pathExistsSync(dirPath)) {
+        createdDirectories.push(dirPath);
+    }
+    ensureDirSync(dirPath);
+}
+export function scaffoldWorkspaceAssets(paths) {
+    const createdDirectories = [];
+    ensureDirectory(paths.wikiRoot, createdDirectories);
+    ensureDirectory(paths.wikiPath, createdDirectories);
+    ensureDirectory(paths.templatesPath, createdDirectories);
+    if (paths.vaultPath) {
+        ensureDirectory(paths.vaultPath, createdDirectories);
+    }
+    const defaultConfigPath = path.join(paths.packageRoot, "assets", "wiki.config.default.json");
+    const defaultTemplatesPath = path.join(paths.packageRoot, "assets", "templates");
+    const copiedConfig = copyFileIfMissingSync(defaultConfigPath, paths.configPath);
+    let copiedTemplates = 0;
+    if (isDirectoryEmptySync(paths.templatesPath) && pathExistsSync(defaultTemplatesPath)) {
+        copyDirectoryContentsSync(defaultTemplatesPath, paths.templatesPath);
+        copiedTemplates = 1;
+    }
+    return {
+        copiedConfig,
+        copiedTemplates,
+        createdDirectories,
+    };
+}

package/dist/core/workspace-skills.js

@@ -0,0 +1,220 @@
+import { spawnSync } from "node:child_process";
+import { accessSync, constants, lstatSync, realpathSync, rmSync, symlinkSync, unlinkSync } from "node:fs";
+import path from "node:path";
+import { AppError } from "../utils/errors.js";
+import { ensureDirSync, pathExistsSync } from "../utils/fs.js";
+export const PARSER_SKILL_SOURCE = "https://github.com/anthropics/skills";
+export const OPTIONAL_PARSER_SKILLS = [
+    { name: "pdf", summary: "Process PDF files" },
+    { name: "docx", summary: "Process DOCX files" },
+    { name: "pptx", summary: "Process PPTX files" },
+    { name: "xlsx", summary: "Process XLSX/CSV files" },
+];
+const OPTIONAL_PARSER_SKILL_NAMES = new Set(OPTIONAL_PARSER_SKILLS.map((skill) => skill.name));
+function canRead(filePath) {
+    accessSync(filePath, constants.R_OK);
+    return true;
+}
+function getNpxCommand() {
+    return process.platform === "win32" ? "npx.cmd" : "npx";
+}
+export function resolveWorkspaceRootFromWikiPath(wikiPath) {
+    return path.resolve(wikiPath, "..", "..");
+}
+export function resolveWorkspaceSkillPaths(wikiPath) {
+    const workspaceRoot = resolveWorkspaceRootFromWikiPath(wikiPath);
+    const skillsRoot = path.join(workspaceRoot, ".agents", "skills");
+    return {
+        workspaceRoot,
+        skillsRoot,
+        wikiSkillPath: path.join(skillsRoot, "tiangong-wiki-skill"),
+    };
+}
+export function resolveWorkspaceSkillPath(workspaceRoot, skillName) {
+    return path.join(workspaceRoot, ".agents", "skills", skillName);
+}
+export function parseParserSkillSelection(rawValue) {
+    const value = rawValue?.trim();
+    if (!value) {
+        return {
+            skills: [],
+            invalid: [],
+        };
+    }
+    const skills = [];
+    const seen = new Set();
+    const invalid = [];
+    for (const entry of value.split(",")) {
+        const candidate = entry.trim().toLowerCase();
+        if (!candidate) {
+            continue;
+        }
+        if (!OPTIONAL_PARSER_SKILL_NAMES.has(candidate)) {
+            invalid.push(candidate);
+            continue;
+        }
+        const skill = candidate;
+        if (!seen.has(skill)) {
+            seen.add(skill);
+            skills.push(skill);
+        }
+    }
+    return {
+        skills,
+        invalid,
+    };
+}
+export function parseParserSkills(rawValue, options = {}) {
+    const { skills, invalid } = parseParserSkillSelection(rawValue);
+    if (invalid.length > 0 && options.strict !== false) {
+        throw new AppError(`WIKI_PARSER_SKILLS contains unsupported skills: ${invalid.join(", ")}`, "config");
+    }
+    return skills;
+}
+export function formatParserSkills(skills) {
+    return skills.join(",");
+}
+export function inspectSkillInstall(skillPath, name = path.basename(skillPath)) {
+    const skillMdPath = path.join(skillPath, "SKILL.md");
+    if (!pathExistsSync(skillPath)) {
+        return {
+            name,
+            skillPath,
+            skillMdPath,
+            exists: false,
+            readable: false,
+        };
+    }
+    try {
+        canRead(skillMdPath);
+        return {
+            name,
+            skillPath,
+            skillMdPath,
+            exists: true,
+            readable: true,
+        };
+    }
+    catch {
+        return {
+            name,
+            skillPath,
+            skillMdPath,
+            exists: true,
+            readable: false,
+        };
+    }
+}
+export function ensureWikiSkillInstall(wikiPath, packageRoot) {
+    const paths = resolveWorkspaceSkillPaths(wikiPath);
+    const packageRealPath = realpathSync(packageRoot);
+    const existing = inspectSkillInstall(paths.wikiSkillPath, "tiangong-wiki-skill");
+    ensureDirSync(paths.skillsRoot);
+    if (existing.exists) {
+        const stats = lstatSync(paths.wikiSkillPath);
+        if (stats.isSymbolicLink()) {
+            const currentRealPath = realpathSync(paths.wikiSkillPath);
+            if (currentRealPath === packageRealPath) {
+                return {
+                    sourcePath: packageRoot,
+                    skillPath: paths.wikiSkillPath,
+                    status: "linked",
+                };
+            }
+            unlinkSync(paths.wikiSkillPath);
+            symlinkSync(packageRoot, paths.wikiSkillPath, "dir");
+            return {
+                sourcePath: packageRoot,
+                skillPath: paths.wikiSkillPath,
+                status: "updated",
+            };
+        }
+        if (existing.readable) {
+            rmSync(paths.wikiSkillPath, { recursive: true, force: true });
+            symlinkSync(packageRoot, paths.wikiSkillPath, "dir");
+            return {
+                sourcePath: packageRoot,
+                skillPath: paths.wikiSkillPath,
+                status: "updated",
+            };
+        }
+        throw new AppError(`workspace skill path is occupied and cannot be reused: ${paths.wikiSkillPath}`, "config", {
+            skillName: "tiangong-wiki-skill",
+            skillPath: paths.wikiSkillPath,
+        });
+    }
+    symlinkSync(packageRoot, paths.wikiSkillPath, "dir");
+    return {
+        sourcePath: packageRoot,
+        skillPath: paths.wikiSkillPath,
+        status: "linked",
+    };
+}
+function renderCommand(command, args) {
+    return [command, ...args]
+        .map((part) => (/[A-Za-z0-9_./:@+-]+/.test(part) ? part : JSON.stringify(part)))
+        .join(" ");
+}
+export function buildParserSkillInstallInvocation(skillName) {
+    const command = getNpxCommand();
+    const args = ["-y", "skills", "add", PARSER_SKILL_SOURCE, "--skill", skillName, "-a", "codex", "-y"];
+    return {
+        command,
+        args,
+        rendered: renderCommand(command, args),
+    };
+}
+export function installParserSkill(skillName, workspaceRoot, options = {}) {
+    const skillPath = resolveWorkspaceSkillPath(workspaceRoot, skillName);
+    const current = inspectSkillInstall(skillPath, skillName);
+    const invocation = buildParserSkillInstallInvocation(skillName);
+    if (current.readable) {
+        return {
+            name: skillName,
+            skillPath,
+            skillMdPath: current.skillMdPath,
+            status: "existing",
+            command: invocation.rendered,
+        };
+    }
+    options.output?.write(`Installing parser skill ${skillName}...\n`);
+    const result = spawnSync(invocation.command, invocation.args, {
+        cwd: workspaceRoot,
+        env: options.env ?? process.env,
+        encoding: "utf8",
+    });
+    if (result.error) {
+        throw new AppError(`failed to install parser skill ${skillName}: ${result.error.message}`, "runtime", {
+            skillName,
+            command: invocation.rendered,
+            cwd: workspaceRoot,
+        });
+    }
+    if (result.status !== 0) {
+        throw new AppError(`failed to install parser skill ${skillName}`, "runtime", {
+            skillName,
+            command: invocation.rendered,
+            cwd: workspaceRoot,
+            exitCode: result.status,
+            stdout: result.stdout.trim(),
+            stderr: result.stderr.trim(),
+        });
+    }
+    const installed = inspectSkillInstall(skillPath, skillName);
+    if (!installed.readable) {
+        throw new AppError(`parser skill ${skillName} was installed but SKILL.md is missing or unreadable`, "runtime", {
+            skillName,
+            command: invocation.rendered,
+            cwd: workspaceRoot,
+            skillPath,
+            skillMdPath: installed.skillMdPath,
+        });
+    }
+    return {
+        name: skillName,
+        skillPath,
+        skillMdPath: installed.skillMdPath,
+        status: "installed",
+        command: invocation.rendered,
+    };
+}