@notedge/panduck 0.0.0

package/bin/panduck.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import { createJiti } from "jiti";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const jiti = createJiti(import.meta.url, { interopDefault: true });
+const { runCli } = await jiti.import(join(here, "../src/cli/main.ts"));
+
+process.exit(await runCli(process.argv.slice(2)));

package/locales/en-US/cli.json

@@ -0,0 +1,46 @@
+{
+  "cli.intro": "panduck — document conversion orchestrator for notedown-ir::DocumentGraph",
+  "cli.cmd.convert": "Convert one input document to a target format",
+  "cli.cmd.plan": "Probe input and plan a conversion pipeline without writing output",
+  "cli.cmd.inspect": "Inspect input format and container structure",
+  "cli.cmd.check": "Validate source or generated output against Panduck contracts",
+  "cli.cmd.formats": "List format capabilities from the shared registry",
+  "cli.cmd.doctor": "Check CLI install, native bindings, and environment",
+  "cli.opt.to": "Target format ID (e.g. epub, docx, markdown, notedown)",
+  "cli.opt.from": "Source format ID when detection should be skipped",
+  "cli.opt.output": "Output file path, or - for stdout",
+  "cli.opt.profile": "Named conversion profile from config",
+  "cli.opt.config": "Path to Panduck config file",
+  "cli.opt.assets-dir": "Output assets root directory",
+  "cli.opt.asset-policy": "Asset handling: preserve, copy, embed, or drop",
+  "cli.opt.link-policy": "Link handling: preserve, rewrite, or drop",
+  "cli.opt.loss": "Loss policy: allow, warn, or deny",
+  "cli.opt.strict": "Reject unknown coverage in addition to loss",
+  "cli.opt.allow-partial": "Allow publishing partial source reads when the writer accepts them",
+  "cli.opt.diagnostics": "Diagnostics channel: silent, human, or json",
+  "cli.opt.batch": "Process multiple inputs independently",
+  "cli.opt.output-dir": "Batch output directory",
+  "cli.opt.report": "Write JSON report to a file, or - for stdout",
+  "cli.opt.overwrite": "Replace an existing output file",
+  "cli.opt.budget": "Parse budget limit (repeatable KEY=VALUE)",
+  "cli.opt.dry-run": "Alias for plan-style validation on convert",
+  "cli.opt.stage": "Inspect depth: probe, index, decode, or validate",
+  "cli.opt.path": "Layout path inside a container (inspect)",
+  "cli.opt.operation": "Filter formats by read or write operation",
+  "cli.opt.json": "Emit machine-readable JSON on stdout",
+  "cli.opt.log-file": "Append structured console events to a JSON lines log file",
+  "cli.err.same_path": "Input and output paths must not be the same: {path}",
+  "cli.err.missing_to_stdout": "Writing to stdout requires an explicit --to format",
+  "cli.err.missing_input": "Input path is required",
+  "cli.err.stdin_batch": "Standard input cannot be used with --batch",
+  "cli.err.ambiguous_format": "Ambiguous input format; specify --from explicitly",
+  "cli.err.unsupported_target": "Target format {format} is not ready for {operation}",
+  "cli.err.unsupported_source": "Source format {format} is not ready for read",
+  "cli.err.output_exists": "Output already exists; pass --overwrite to replace it",
+  "cli.err.not_implemented": "Pipeline step not implemented yet: {step}",
+  "cli.err.invalid_policy": "Invalid {name}: {value}",
+  "cli.msg.plan_ready": "Plan complete",
+  "cli.msg.convert_blocked": "Conversion blocked by capability registry",
+  "cli.msg.doctor_ok": "Panduck environment looks healthy",
+  "cli.msg.doctor_issues": "Panduck environment has issues"
+}

package/locales/locales.json

@@ -0,0 +1,7 @@
+{
+  "defaultLocale": "en-US",
+  "locales": [
+    { "id": "en-US", "label": "English", "direction": "ltr" },
+    { "id": "zh-CN", "label": "简体中文", "direction": "ltr" }
+  ]
+}

package/locales/zh-CN/cli.json

@@ -0,0 +1,46 @@
+{
+  "cli.intro": "panduck — 面向 notedown-ir::DocumentGraph 的文档转换编排器",
+  "cli.cmd.convert": "将单个输入文档转换为目标格式",
+  "cli.cmd.plan": "探测输入并规划转换流水线，不写输出",
+  "cli.cmd.inspect": "查看输入格式与容器结构",
+  "cli.cmd.check": "按 Panduck 合同校验源文件或已生成输出",
+  "cli.cmd.formats": "列出共享注册表中的格式能力",
+  "cli.cmd.doctor": "检查 CLI 安装、原生绑定与环境",
+  "cli.opt.to": "目标格式 ID（如 epub、docx、markdown、notedown）",
+  "cli.opt.from": "在跳过自动探测时指定源格式 ID",
+  "cli.opt.output": "输出文件路径，或 - 表示标准输出",
+  "cli.opt.profile": "配置中的命名转换 profile",
+  "cli.opt.config": "Panduck 配置文件路径",
+  "cli.opt.assets-dir": "输出资产根目录",
+  "cli.opt.asset-policy": "资产策略：preserve、copy、embed 或 drop",
+  "cli.opt.link-policy": "链接策略：preserve、rewrite 或 drop",
+  "cli.opt.loss": "损失策略：allow、warn 或 deny",
+  "cli.opt.strict": "除损失外还拒绝 unknown coverage",
+  "cli.opt.allow-partial": "在 writer 接受时允许发布 partial 源读取",
+  "cli.opt.diagnostics": "诊断通道：silent、human 或 json",
+  "cli.opt.batch": "独立处理多个输入",
+  "cli.opt.output-dir": "批处理输出目录",
+  "cli.opt.report": "将 JSON 报告写入文件，或 - 表示标准输出",
+  "cli.opt.overwrite": "覆盖已存在的输出文件",
+  "cli.opt.budget": "解析预算上限（可重复 KEY=VALUE）",
+  "cli.opt.dry-run": "在 convert 上等价于 plan 式校验",
+  "cli.opt.stage": "inspect 深度：probe、index、decode 或 validate",
+  "cli.opt.path": "容器内布局路径（inspect）",
+  "cli.opt.operation": "按 read 或 write 过滤格式",
+  "cli.opt.json": "在标准输出打印机器可读 JSON",
+  "cli.opt.log-file": "将结构化 console 事件追加写入 JSON lines 日志文件",
+  "cli.err.same_path": "输入与输出路径不能相同：{path}",
+  "cli.err.missing_to_stdout": "写入标准输出时必须显式指定 --to 格式",
+  "cli.err.missing_input": "必须提供输入路径",
+  "cli.err.stdin_batch": "标准输入不能与 --batch 同时使用",
+  "cli.err.ambiguous_format": "输入格式存在歧义，请显式指定 --from",
+  "cli.err.unsupported_target": "目标格式 {format} 尚未就绪，无法 {operation}",
+  "cli.err.unsupported_source": "源格式 {format} 尚未就绪，无法读取",
+  "cli.err.output_exists": "输出已存在，请使用 --overwrite 覆盖",
+  "cli.err.not_implemented": "流水线步骤尚未实现：{step}",
+  "cli.err.invalid_policy": "无效的 {name}：{value}",
+  "cli.msg.plan_ready": "规划完成",
+  "cli.msg.convert_blocked": "能力注册表阻止了转换",
+  "cli.msg.doctor_ok": "Panduck 环境正常",
+  "cli.msg.doctor_issues": "Panduck 环境存在问题"
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "bin": {
+    "panduck": "./bin/panduck.mjs"
+  },
+  "dependencies": {
+    "@vmz/commander": "^0.2.0",
+    "jiti": "^2.4.2"
+  },
+  "description": "Panduck document conversion bindings (Node-API + TypeScript)",
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./cli": "./src/cli/index.ts",
+    "./node": "./src/node/index.ts",
+    "./wasm": "./src/wasm/index.ts"
+  },
+  "files": [
+    "bin",
+    "locales",
+    "src"
+  ],
+  "license": "MPL-2.0",
+  "name": "@notedge/panduck",
+  "optionalDependencies": {
+    "@notedge/panduck-darwin-arm64": "0.0.0",
+    "@notedge/panduck-darwin-x64": "0.0.0",
+    "@notedge/panduck-linux-arm64": "0.0.0",
+    "@notedge/panduck-linux-x64": "0.0.0",
+    "@notedge/panduck-unknown-wasm32": "0.0.0",
+    "@notedge/panduck-win32-x64": "0.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oovm/npm-tools.git"
+  },
+  "scripts": {
+    "test:e2e": "tsx --test tests/**/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "type": "module",
+  "version": "0.0.0"
+}

package/readme.md

@@ -0,0 +1,5 @@
+# @notedge/panduck
+
+TypeScript loader for Panduck Node-API bindings under the `@notedge` scope.
+
+Build native artifacts first: `pnpm run build:napi` at the repo root.

package/src/cli/cli.ts

@@ -0,0 +1,28 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { createCli } from "@vmz/commander";
+
+import { registerCheckCommand } from "./commands/check-cmd.js";
+import { registerConvertCommand } from "./commands/convert-cmd.js";
+import { registerDoctorCommand } from "./commands/doctor-cmd.js";
+import { registerFormatsCommand } from "./commands/formats-cmd.js";
+import { registerInspectCommand } from "./commands/inspect-cmd.js";
+import { registerPlanCommand } from "./commands/plan-cmd.js";
+
+export function buildPanduckCli() {
+    const localesRoot = join(dirname(fileURLToPath(import.meta.url)), "../../locales");
+    const cli = createCli("panduck")
+        .locales(localesRoot, { envKeys: ["PANDUCK_LOCALE", "LOCALE", "LANG", "LC_ALL"] })
+        .intro("cli.intro")
+        .option("--log-file <file>", "cli.opt.log-file");
+
+    registerConvertCommand(cli);
+    registerPlanCommand(cli);
+    registerInspectCommand(cli);
+    registerCheckCommand(cli);
+    registerFormatsCommand(cli);
+    registerDoctorCommand(cli);
+
+    return cli;
+}

package/src/cli/commands/check-cmd.ts

@@ -0,0 +1,174 @@
+import type { Cli, ParsedOptions } from "@vmz/commander";
+
+import {
+    assertReadableInput,
+    buildBlockedReport,
+    createContext,
+    resolveFormats,
+} from "../context.js";
+import { emitReport } from "../diagnostics.js";
+import { ExitCode } from "../exit-codes.js";
+import { findFormat } from "../format-registry.js";
+import { CliOptionError, readSharedOptions, readString } from "../options.js";
+import { createReport } from "../report.js";
+import { configureConsoleBackend } from "../console-backend.js";
+import {
+    emitPipelineResult,
+    hasPipeline,
+    inferCheckTarget,
+    runCheckPipeline,
+} from "../pipeline.js";
+
+export function registerCheckCommand(cli: Cli): void {
+    cli.command("check", "cli.cmd.check")
+        .option("--from <format>", "cli.opt.from")
+        .option("--format <format>", "cli.opt.to")
+        .option("--strict", "cli.opt.strict")
+        .option("--loss <policy>", "cli.opt.loss")
+        .option("--diagnostics <mode>", "cli.opt.diagnostics")
+        .option("--budget <limit>", "cli.opt.budget")
+        .option("--json", "cli.opt.json")
+        .action((options: ParsedOptions) => runCheck(options));
+}
+
+async function runCheck(options: ParsedOptions): Promise<number> {
+    try {
+        const shared = readSharedOptions(options);
+        const inputPath = options._[0] ?? readString(options, "input");
+        const outputFormat = readString(options, "format");
+        if (!inputPath) {
+            return ExitCode.InvalidArgs;
+        }
+
+        const ctx = createContext();
+        configureConsoleBackend(ctx.bindings, shared.logFile);
+        const resolved = resolveFormats(inputPath, undefined, {
+            ...shared,
+            to: outputFormat ?? shared.to,
+        });
+
+        if (resolved.ambiguous) {
+            const report = buildBlockedReport(
+                ctx,
+                "check",
+                inputPath,
+                resolved,
+                "ambiguous input format",
+                ExitCode.InputUnsupported,
+                shared,
+            );
+            emitReport(report, shared.diagnostics, shared.json);
+            return ExitCode.InputUnsupported;
+        }
+
+        try {
+            await assertReadableInput(inputPath);
+        } catch {
+            const report = buildBlockedReport(
+                ctx,
+                "check",
+                inputPath,
+                resolved,
+                "input is not readable",
+                ExitCode.InputUnsupported,
+                shared,
+            );
+            emitReport(report, shared.diagnostics, shared.json);
+            return ExitCode.InputUnsupported;
+        }
+
+        const source = resolved.from ? findFormat(ctx.registry, resolved.from) : undefined;
+        let targetFormat = resolved.to;
+        if (!targetFormat && resolved.from && ctx.bindings) {
+            targetFormat = inferCheckTarget(ctx.bindings, resolved.from);
+        }
+        const target = targetFormat ? findFormat(ctx.registry, targetFormat) : undefined;
+        const checkResolved = { ...resolved, to: targetFormat };
+
+        if (!targetFormat) {
+            const report = buildBlockedReport(
+                ctx,
+                "check",
+                inputPath,
+                checkResolved,
+                "target format is required for check",
+                ExitCode.InvalidArgs,
+                shared,
+            );
+            emitReport(report, shared.diagnostics, shared.json);
+            return ExitCode.InvalidArgs;
+        }
+
+        const routeReady = hasPipeline(ctx.bindings, resolved.from, targetFormat);
+
+        if (routeReady && ctx.bindings) {
+            try {
+                const result = await runCheckPipeline({
+                    ctx,
+                    bindings: ctx.bindings,
+                    inputPath,
+                    resolved: checkResolved,
+                    shared,
+                });
+                return emitPipelineResult(result, shared);
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const report = buildBlockedReport(
+                    ctx,
+                    "check",
+                    inputPath,
+                    checkResolved,
+                    message,
+                    ExitCode.IrOrWriterFailure,
+                    shared,
+                );
+                emitReport(report, shared.diagnostics, shared.json);
+                return ExitCode.IrOrWriterFailure;
+            }
+        }
+
+        const report = createReport({
+            operation: "check",
+            toolVersion: ctx.toolVersion,
+            status: "partial",
+            inputs: [{ path: inputPath, format: resolved.from }],
+            detection: { format: resolved.from, confidence: resolved.from ? "hint" : undefined, hints: resolved.hints },
+            pipeline: {
+                reader: source?.format,
+                writer: target?.format,
+                stages: ["validate"],
+                blocked_reason: routeReady
+                    ? "native bindings are unavailable"
+                    : "conversion route is not wired yet",
+            },
+            coverage: source?.coverage ?? target?.coverage,
+            diagnostics: [
+                {
+                    owner: "panduck",
+                    severity: "warning",
+                    message: routeReady
+                        ? "check requires native bindings for wired routes"
+                        : "check currently validates readability and registry presence only",
+                    code: "panduck.check.partial",
+                },
+            ],
+            budgets: shared.budgets,
+            determinism: { profile: shared.profile ?? "default", config: shared.config ?? null },
+            statusPolicy: {
+                loss: shared.loss,
+                strict: shared.strict,
+                exit_code: shared.strict ? ExitCode.LossPolicyViolation : ExitCode.Success,
+            },
+        });
+
+        emitReport(report, shared.diagnostics, shared.json);
+        return shared.strict ? ExitCode.LossPolicyViolation : ExitCode.Success;
+    } catch (error) {
+        if (error instanceof CliOptionError) {
+            console.error(error.message);
+            return error.exitCode;
+        }
+        console.error(error instanceof Error ? error.message : String(error));
+        return ExitCode.InvalidArgs;
+    }
+}

package/src/cli/commands/convert-cmd.ts

@@ -0,0 +1,300 @@
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+
+import type { Cli, ParsedOptions } from "@vmz/commander";
+
+import {
+    assertReadableInput,
+    buildBlockedReport,
+    createContext,
+    resolveFormats,
+    validateIoPaths,
+} from "../context.js";
+import { emitReport } from "../diagnostics.js";
+import { ExitCode } from "../exit-codes.js";
+import { findFormat, isOperationReady } from "../format-registry.js";
+import {
+    CliOptionError,
+    parseAssetPolicy,
+    parseLinkPolicy,
+    readSharedOptions,
+    readString,
+} from "../options.js";
+import { createReport } from "../report.js";
+import { isStdoutPath } from "../paths.js";
+import { configureConsoleBackend } from "../console-backend.js";
+import { emitPipelineResult, hasPipeline, runConversionPipeline } from "../pipeline.js";
+
+export function registerConvertCommand(cli: Cli): void {
+    cli.command("convert", "cli.cmd.convert")
+        .option("--to <format>", "cli.opt.to")
+        .option("-o, --output <file>", "cli.opt.output")
+        .option("--from <format>", "cli.opt.from")
+        .option("--profile <name>", "cli.opt.profile")
+        .option("--config <file>", "cli.opt.config")
+        .option("--assets-dir <dir>", "cli.opt.assets-dir")
+        .option("--asset-policy <policy>", "cli.opt.asset-policy")
+        .option("--link-policy <policy>", "cli.opt.link-policy")
+        .option("--loss <policy>", "cli.opt.loss")
+        .option("--strict", "cli.opt.strict")
+        .option("--allow-partial", "cli.opt.allow-partial")
+        .option("--diagnostics <mode>", "cli.opt.diagnostics")
+        .option("--batch", "cli.opt.batch")
+        .option("--output-dir <dir>", "cli.opt.output-dir")
+        .option("--report <file>", "cli.opt.report")
+        .option("--overwrite", "cli.opt.overwrite")
+        .option("--budget <limit>", "cli.opt.budget")
+        .option("--dry-run", "cli.opt.dry-run")
+        .action((options: ParsedOptions) => runConvert(options));
+}
+
+async function runConvert(options: ParsedOptions): Promise<number> {
+    try {
+        const shared = readSharedOptions(options);
+        const inputPath = options._[0] ?? readString(options, "input");
+        const outputPath = readString(options, "output");
+        const reportPath = readString(options, "report");
+        const batch = options.batch === true;
+        const dryRun = options["dry-run"] === true;
+
+        if (!inputPath) {
+            return ExitCode.InvalidArgs;
+        }
+        if (batch && inputPath === "-") {
+            console.error("standard input cannot be used with --batch");
+            return ExitCode.InvalidArgs;
+        }
+        if (batch && !readString(options, "output-dir")) {
+            console.error("--batch requires --output-dir");
+            return ExitCode.InvalidArgs;
+        }
+
+        const overlapCode = validateIoPaths(inputPath, outputPath);
+        if (overlapCode !== null) {
+            console.error(`input and output paths must not be the same: ${inputPath}`);
+            return overlapCode;
+        }
+
+        if (isStdoutPath(outputPath) && !shared.to) {
+            console.error("writing to stdout requires an explicit --to format");
+            return ExitCode.InvalidArgs;
+        }
+
+        const ctx = createContext();
+        configureConsoleBackend(ctx.bindings, shared.logFile);
+        const resolved = resolveFormats(inputPath, outputPath, shared);
+
+        if (resolved.ambiguous) {
+            const report = buildBlockedReport(
+                ctx,
+                "convert",
+                inputPath,
+                resolved,
+                "ambiguous input format",
+                ExitCode.InputUnsupported,
+                shared,
+            );
+            emitReport(report, shared.diagnostics, shared.json);
+            return ExitCode.InputUnsupported;
+        }
+
+        if (!resolved.to) {
+            const report = buildBlockedReport(
+                ctx,
+                "convert",
+                inputPath,
+                resolved,
+                "target format is required",
+                ExitCode.InvalidArgs,
+                shared,
+            );
+            emitReport(report, shared.diagnostics, shared.json);
+            return ExitCode.InvalidArgs;
+        }
+
+        try {
+            await assertReadableInput(inputPath);
+        } catch {
+            const report = buildBlockedReport(
+                ctx,
+                "convert",
+                inputPath,
+                resolved,
+                "input is not readable",
+                ExitCode.InputUnsupported,
+                shared,
+            );
+            emitReport(report, shared.diagnostics, shared.json);
+            return ExitCode.InputUnsupported;
+        }
+
+        if (outputPath && outputPath !== "-" && !shared.overwrite) {
+            try {
+                await access(outputPath, constants.F_OK);
+                const report = buildBlockedReport(
+                    ctx,
+                    "convert",
+                    inputPath,
+                    resolved,
+                    "output already exists",
+                    ExitCode.OutputFailure,
+                    shared,
+                );
+                emitReport(report, shared.diagnostics, shared.json);
+                return ExitCode.OutputFailure;
+            } catch {
+                // target does not exist yet
+            }
+        }
+
+        parseAssetPolicy(readString(options, "asset-policy"));
+        parseLinkPolicy(readString(options, "link-policy"));
+
+        const source = resolved.from ? findFormat(ctx.registry, resolved.from) : undefined;
+        const target = findFormat(ctx.registry, resolved.to);
+        if (!target) {
+            const report = buildBlockedReport(
+                ctx,
+                "convert",
+                inputPath,
+                resolved,
+                `unknown target format ${resolved.to}`,
+                ExitCode.InputUnsupported,
+                shared,
+            );
+            emitReport(report, shared.diagnostics, shared.json);
+            return ExitCode.InputUnsupported;
+        }
+
+        const routeReady = hasPipeline(ctx.bindings, resolved.from, resolved.to);
+
+        if (resolved.from === "doc") {
+            const report = buildBlockedReport(
+                ctx,
+                "convert",
+                inputPath,
+                resolved,
+                "legacy .doc import requires OLE reader support; convert to .docx first",
+                ExitCode.InputUnsupported,
+                shared,
+            );
+            emitReport(report, shared.diagnostics, shared.json);
+            return ExitCode.InputUnsupported;
+        }
+
+        if (!routeReady) {
+            if (source && !isOperationReady(source, "read")) {
+                const report = buildBlockedReport(
+                    ctx,
+                    "convert",
+                    inputPath,
+                    resolved,
+                    `source format ${source.format} is not ready for read`,
+                    ExitCode.InputUnsupported,
+                    shared,
+                );
+                emitReport(report, shared.diagnostics, shared.json);
+                return ExitCode.InputUnsupported;
+            }
+
+            if (!isOperationReady(target, "write")) {
+                const report = buildBlockedReport(
+                    ctx,
+                    "convert",
+                    inputPath,
+                    resolved,
+                    `target format ${target.format} is not ready for write`,
+                    ExitCode.InputUnsupported,
+                    shared,
+                );
+                emitReport(report, shared.diagnostics, shared.json);
+                return ExitCode.InputUnsupported;
+            }
+        }
+
+        if (dryRun) {
+            const report = createReport({
+                operation: "convert",
+                toolVersion: ctx.toolVersion,
+                status: "success",
+                inputs: [{ path: inputPath, format: resolved.from }],
+                detection: { format: resolved.from, confidence: "hint", hints: resolved.hints },
+                pipeline: {
+                    reader: source?.format ?? resolved.from,
+                    writer: target.format,
+                    stages: ["detect", "read", "ir", "write", "publish"],
+                },
+                outputs: outputPath ? [{ path: outputPath, published: false }] : [],
+                budgets: shared.budgets,
+                determinism: { profile: shared.profile ?? "default", config: shared.config ?? null },
+                statusPolicy: { loss: shared.loss, strict: shared.strict, exit_code: ExitCode.Success },
+            });
+            emitReport(report, shared.diagnostics, shared.json);
+            return ExitCode.Success;
+        }
+
+        if (routeReady && ctx.bindings) {
+            try {
+                const result = await runConversionPipeline({
+                    ctx,
+                    bindings: ctx.bindings,
+                    inputPath,
+                    outputPath,
+                    resolved,
+                    shared,
+                    toolVersion: ctx.toolVersion,
+                });
+                return emitPipelineResult(result, shared);
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const report = buildBlockedReport(
+                    ctx,
+                    "convert",
+                    inputPath,
+                    resolved,
+                    message,
+                    ExitCode.IrOrWriterFailure,
+                    shared,
+                );
+                emitReport(report, shared.diagnostics, shared.json);
+                return ExitCode.IrOrWriterFailure;
+            }
+        }
+
+        const report = createReport({
+            operation: "convert",
+            toolVersion: ctx.toolVersion,
+            status: "blocked",
+            inputs: [{ path: inputPath, format: resolved.from }],
+            detection: { format: resolved.from, confidence: "hint", hints: resolved.hints },
+            pipeline: {
+                reader: source?.format ?? resolved.from,
+                writer: target.format,
+                stages: ["detect", "read", "ir", "write", "publish"],
+                blocked_reason: "conversion pipeline is not wired yet",
+            },
+            diagnostics: [
+                {
+                    owner: "panduck",
+                    severity: "error",
+                    message: "conversion pipeline is not wired yet",
+                    code: "panduck.convert.not_implemented",
+                },
+            ],
+            outputs: outputPath ? [{ path: outputPath, published: false }] : [],
+            budgets: shared.budgets,
+            determinism: { profile: shared.profile ?? "default", config: shared.config ?? null },
+            statusPolicy: { loss: shared.loss, strict: shared.strict, exit_code: ExitCode.IrOrWriterFailure },
+        });
+
+        emitReport(report, shared.diagnostics, shared.json);
+        return ExitCode.IrOrWriterFailure;
+    } catch (error) {
+        if (error instanceof CliOptionError) {
+            console.error(error.message);
+            return error.exitCode;
+        }
+        console.error(error instanceof Error ? error.message : String(error));
+        return ExitCode.InvalidArgs;
+    }
+}