@notedge/panduck 0.0.0

package/src/cli/exit-codes.ts

@@ -0,0 +1,14 @@
+/** Stable Panduck CLI exit codes (see Living CLI contract). */
+export const ExitCode = {
+    Success: 0,
+    LossPolicyViolation: 1,
+    InvalidArgs: 2,
+    InputUnsupported: 3,
+    ParseFailure: 4,
+    IrOrWriterFailure: 5,
+    OutputFailure: 6,
+    BudgetExceeded: 7,
+    BatchFailure: 8,
+} as const;
+
+export type ExitCodeValue = (typeof ExitCode)[keyof typeof ExitCode];

package/src/cli/format-registry.ts

@@ -0,0 +1,170 @@
+import type { PanduckBindings } from "../types.js";
+
+export type CapabilityState =
+    | "registered"
+    | "planned"
+    | "partial"
+    | "ready"
+    | "unavailable"
+    | "blocked";
+
+export type OperationKind = "read" | "write";
+
+export type OperationCapability = {
+    state: CapabilityState;
+    stages: string[];
+};
+
+export type FormatRecord = {
+    format: string;
+    container: string[];
+    aliases?: string[];
+    reader: OperationCapability;
+    writer: OperationCapability;
+    embeddedText?: string[];
+    coverage: {
+        state: CapabilityState;
+        known: string[];
+        unknown: string[];
+    };
+};
+
+const TEXT_READ_STAGES = ["probe", "decode", "validate"];
+const TEXT_WRITE_STAGES = ["ir", "validate"];
+const CONTAINER_READ_STAGES = ["probe", "index", "decode", "validate"];
+const CONTAINER_WRITE_STAGES = ["ir", "package", "validate"];
+
+function textFormat(
+    format: string,
+    reader: CapabilityState,
+    writer: CapabilityState,
+    known: string[],
+    unknown: string[],
+    aliases?: string[],
+): FormatRecord {
+    return {
+        format,
+        container: ["text"],
+        aliases,
+        reader: { state: reader, stages: TEXT_READ_STAGES },
+        writer: { state: writer, stages: TEXT_WRITE_STAGES },
+        coverage: { state: reader === "ready" && writer === "ready" ? "ready" : "partial", known, unknown },
+    };
+}
+
+function containerFormat(
+    format: string,
+    container: string[],
+    reader: CapabilityState,
+    writer: CapabilityState,
+    embeddedText: string[],
+    known: string[],
+    unknown: string[],
+): FormatRecord {
+    return {
+        format,
+        container,
+        reader: { state: reader, stages: CONTAINER_READ_STAGES },
+        writer: { state: writer, stages: CONTAINER_WRITE_STAGES },
+        embeddedText,
+        coverage: {
+            state:
+                reader === "ready" && writer === "ready"
+                    ? "ready"
+                    : reader === "planned" && writer === "planned"
+                      ? "planned"
+                      : "partial",
+            known,
+            unknown,
+        },
+    };
+}
+
+/** Static capability registry aligned with the Panduck Living CLI matrix. */
+export function baseFormatRegistry(): FormatRecord[] {
+    return [
+        textFormat("markdown", "partial", "ready", ["paragraph", "heading", "code_block", "link"], ["table", "footnote"]),
+        textFormat("notedown", "partial", "planned", ["paragraph", "heading", "list", "link"], ["macro", "table"]),
+        textFormat("org", "partial", "partial", ["headline", "paragraph"], ["drawer", "babel"]),
+        textFormat("rst", "partial", "partial", ["paragraph", "directive"], ["table"]),
+        textFormat("tex", "partial", "partial", ["paragraph", "command"], ["environment"]),
+        textFormat("html", "planned", "planned", ["paragraph", "heading"], ["script", "style"]),
+        containerFormat(
+            "docx",
+            ["zip", "opc"],
+            "partial",
+            "partial",
+            ["oak-xml"],
+            ["paragraph", "heading", "list", "table", "style", "hyperlink", "image", "bold", "italic", "footnote_reference", "footnote_body"],
+            ["tracked_changes", "comment"],
+        ),
+        containerFormat(
+            "epub",
+            ["zip", "ocf"],
+            "planned",
+            "planned",
+            ["oak-xml", "oak-xhtml"],
+            ["spine", "nav", "image"],
+            ["fixed_layout"],
+        ),
+        containerFormat(
+            "pdf",
+            ["pdf"],
+            "planned",
+            "planned",
+            [],
+            ["page", "text_run", "image"],
+            ["annotation", "form", "encryption"],
+        ),
+        containerFormat(
+            "doc",
+            ["ole"],
+            "planned",
+            "unavailable",
+            ["oak-xml"],
+            ["paragraph"],
+            ["field", "revision"],
+        ),
+    ];
+}
+
+/** Merges N-API `supportedFormats()` names into the static registry as `registered` floors. */
+export function getFormatRegistry(bindings?: PanduckBindings | null): FormatRecord[] {
+    const registered = new Set((bindings?.supportedFormats() ?? []).map((name) => name.toLowerCase()));
+    return baseFormatRegistry().map((record) => {
+        if (!registered.has(record.format)) {
+            return record;
+        }
+        const readerState = bumpRegistered(record.reader.state);
+        const writerState = bumpRegistered(record.writer.state);
+        return {
+            ...record,
+            reader: { ...record.reader, state: readerState },
+            writer: { ...record.writer, state: writerState },
+        };
+    });
+}
+
+function bumpRegistered(state: CapabilityState): CapabilityState {
+    if (state === "planned" || state === "registered") {
+        return "registered";
+    }
+    return state;
+}
+
+export function findFormat(registry: FormatRecord[], id: string): FormatRecord | undefined {
+    const needle = id.toLowerCase();
+    return registry.find(
+        (record) =>
+            record.format === needle || record.aliases?.some((alias) => alias.toLowerCase() === needle),
+    );
+}
+
+export function isOperationReady(record: FormatRecord, operation: OperationKind): boolean {
+    const capability = operation === "read" ? record.reader : record.writer;
+    return capability.state === "ready";
+}
+
+export function ebookAliasTarget(): string {
+    return "epub";
+}

package/src/cli/index.ts

@@ -0,0 +1,7 @@
+export { buildPanduckCli } from "./cli.js";
+export { runCli } from "./main.js";
+export { ExitCode } from "./exit-codes.js";
+export { getFormatRegistry, baseFormatRegistry } from "./format-registry.js";
+export type { FormatRecord, CapabilityState, OperationKind } from "./format-registry.js";
+export { REPORT_SCHEMA_VERSION } from "./report.js";
+export type { PanduckReport } from "./report.js";

package/src/cli/main.ts

@@ -0,0 +1,10 @@
+import { buildPanduckCli } from "./cli.js";
+
+export async function runCli(argv: string[]): Promise<number> {
+    try {
+        return await buildPanduckCli().parse(argv);
+    } catch (error) {
+        console.error(`error: ${error instanceof Error ? error.message : String(error)}`);
+        return 2;
+    }
+}

package/src/cli/options.ts

@@ -0,0 +1,127 @@
+import type { ParsedOptions } from "@vmz/commander";
+
+import { ExitCode } from "./exit-codes.js";
+import type { LossPolicy } from "./report.js";
+
+export type AssetPolicy = "preserve" | "copy" | "embed" | "drop";
+export type LinkPolicy = "preserve" | "rewrite" | "drop";
+export type DiagnosticsMode = "silent" | "human" | "json";
+export type InspectStage = "probe" | "index" | "decode" | "validate";
+
+export type SharedCliOptions = {
+    from?: string;
+    to?: string;
+    profile?: string;
+    config?: string;
+    json: boolean;
+    budgets: Record<string, number>;
+    loss: LossPolicy;
+    strict: boolean;
+    allowPartial: boolean;
+    diagnostics: DiagnosticsMode;
+    overwrite: boolean;
+    logFile?: string;
+};
+
+const LOSS_VALUES = new Set<LossPolicy>(["allow", "warn", "deny"]);
+const ASSET_VALUES = new Set<AssetPolicy>(["preserve", "copy", "embed", "drop"]);
+const LINK_VALUES = new Set<LinkPolicy>(["preserve", "rewrite", "drop"]);
+const DIAG_VALUES = new Set<DiagnosticsMode>(["silent", "human", "json"]);
+const STAGE_VALUES = new Set<InspectStage>(["probe", "index", "decode", "validate"]);
+
+export function readFlag(options: ParsedOptions, key: string): boolean {
+    return options[key] === true;
+}
+
+export function readString(options: ParsedOptions, key: string): string | undefined {
+    const value = options[key];
+    if (typeof value === "string" && value.length > 0) {
+        return value;
+    }
+    return undefined;
+}
+
+export function readSharedOptions(options: ParsedOptions): SharedCliOptions {
+    const loss = parseEnum(readString(options, "loss") ?? "warn", LOSS_VALUES, "loss");
+    const diagnostics = parseEnum(
+        readString(options, "diagnostics") ?? "human",
+        DIAG_VALUES,
+        "diagnostics",
+    );
+    return {
+        from: readString(options, "from"),
+        to: readString(options, "to"),
+        profile: readString(options, "profile"),
+        config: readString(options, "config"),
+        json: readFlag(options, "json"),
+        budgets: parseBudgets(options.budget),
+        loss,
+        strict: readFlag(options, "strict"),
+        allowPartial: readFlag(options, "allow-partial"),
+        diagnostics,
+        overwrite: readFlag(options, "overwrite"),
+        logFile: readString(options, "log-file"),
+    };
+}
+
+export function parseAssetPolicy(value: string | undefined): AssetPolicy {
+    return parseEnum(value ?? "preserve", ASSET_VALUES, "asset-policy");
+}
+
+export function parseLinkPolicy(value: string | undefined): LinkPolicy {
+    return parseEnum(value ?? "preserve", LINK_VALUES, "link-policy");
+}
+
+export function parseInspectStage(value: string | undefined): InspectStage {
+    return parseEnum(value ?? "probe", STAGE_VALUES, "stage");
+}
+
+function parseEnum<T extends string>(value: string, allowed: Set<T>, name: string): T {
+    if (!allowed.has(value as T)) {
+        throw new CliOptionError(name, value);
+    }
+    return value as T;
+}
+
+export function parseBudgets(raw: string | boolean | string[] | undefined): Record<string, number> {
+    const entries = normalizeRepeatable(raw);
+    const budgets: Record<string, number> = {};
+    for (const item of entries) {
+        const eq = item.indexOf("=");
+        if (eq <= 0) {
+            throw new CliOptionError("budget", item);
+        }
+        const key = item.slice(0, eq).trim();
+        const value = Number(item.slice(eq + 1).trim());
+        if (!Number.isFinite(value) || value < 0) {
+            throw new CliOptionError("budget", item);
+        }
+        budgets[key] = value;
+    }
+    return budgets;
+}
+
+function normalizeRepeatable(raw: string | boolean | string[] | undefined): string[] {
+    if (raw === undefined || raw === false) {
+        return [];
+    }
+    if (Array.isArray(raw)) {
+        return raw;
+    }
+    if (typeof raw === "string") {
+        return [raw];
+    }
+    return [];
+}
+
+export class CliOptionError extends Error {
+    readonly field: string;
+    readonly value: string;
+    readonly exitCode = ExitCode.InvalidArgs;
+
+    constructor(field: string, value: string) {
+        super(`invalid ${field}: ${value}`);
+        this.field = field;
+        this.value = value;
+    }
+}

package/src/cli/paths.ts

@@ -0,0 +1,56 @@
+import { extname, resolve } from "node:path";
+
+const EXTENSION_HINTS: Record<string, string[]> = {
+    ".md": ["markdown"],
+    ".markdown": ["markdown"],
+    ".nd": ["notedown"],
+    ".org": ["org"],
+    ".rst": ["rst"],
+    ".tex": ["tex"],
+    ".html": ["html"],
+    ".htm": ["html"],
+    ".docx": ["docx"],
+    ".epub": ["epub"],
+    ".pdf": ["pdf"],
+    ".doc": ["doc"],
+};
+
+export function isStdinPath(path: string | undefined): boolean {
+    return path === "-";
+}
+
+export function isStdoutPath(path: string | undefined): boolean {
+    return path === "-";
+}
+
+export function normalizeFormatId(value: string): string {
+    const lowered = value.trim().toLowerCase();
+    if (lowered === "ebook") {
+        return "epub";
+    }
+    return lowered;
+}
+
+export function extensionHints(path: string): string[] {
+    const ext = extname(path).toLowerCase();
+    return EXTENSION_HINTS[ext] ? [...EXTENSION_HINTS[ext]] : [];
+}
+
+export function inferTargetFromPath(path: string): string | undefined {
+    const hints = extensionHints(path);
+    return hints.length === 1 ? hints[0] : undefined;
+}
+
+export function resolveFilesystemPath(path: string, cwd = process.cwd()): string {
+    if (isStdinPath(path) || isStdoutPath(path)) {
+        return path;
+    }
+    return resolve(cwd, path);
+}
+
+export function pathsOverlap(inputPath: string, outputPath: string, cwd = process.cwd()): boolean {
+    if (isStdinPath(inputPath) || isStdoutPath(outputPath)) {
+        return false;
+    }
+    return resolveFilesystemPath(inputPath, cwd) === resolveFilesystemPath(outputPath, cwd);
+}

package/src/cli/pipeline.ts

@@ -0,0 +1,225 @@
+import { mkdir, mkdtemp, rename, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+
+import type { PanduckBindings } from "../types.js";
+import { ExitCode } from "./exit-codes.js";
+import type { SharedCliOptions } from "./options.js";
+import { createReport, type PanduckReport } from "./report.js";
+import { emitReport } from "./diagnostics.js";
+import type { CliContext } from "./context.js";
+import type { ResolvedFormats } from "./context.js";
+import { isStdoutPath } from "./paths.js";
+
+export type PipelineResult = {
+    exitCode: number;
+    report: PanduckReport;
+};
+
+export function hasPipeline(
+    bindings: PanduckBindings | null,
+    from: string | undefined,
+    to: string,
+): boolean {
+    if (!bindings?.supportsConversion || !from) {
+        return false;
+    }
+    return bindings.supportsConversion(from, to);
+}
+
+export function inferCheckTarget(bindings: PanduckBindings, from: string): string | undefined {
+    const routes = bindings.supportedConversions?.() ?? [];
+    const targets = routes
+        .filter((route) => route.startsWith(`${from}:`))
+        .map((route) => route.slice(from.length + 1));
+    if (targets.length === 1) {
+        return targets[0];
+    }
+    if (targets.includes("markdown")) {
+        return "markdown";
+    }
+    return undefined;
+}
+
+export async function runCheckPipeline(input: {
+    ctx: CliContext;
+    bindings: PanduckBindings;
+    inputPath: string;
+    resolved: ResolvedFormats;
+    shared: SharedCliOptions;
+}): Promise<PipelineResult> {
+    const { bindings, inputPath, resolved, shared, ctx } = input;
+    const from = resolved.from;
+    const to = resolved.to;
+    if (!from || !to) {
+        throw new Error("check requires resolved from/to formats");
+    }
+
+    const workdir = await mkdtemp(join(tmpdir(), "panduck-check-"));
+    const extension = to === "markdown" ? ".md" : `.${to}`;
+    const outputPath = join(workdir, `check${extension}`);
+
+    const result = await runConversionPipeline({
+        ctx,
+        bindings,
+        inputPath,
+        outputPath,
+        resolved: { ...resolved, to },
+        shared,
+        toolVersion: ctx.toolVersion,
+        operation: "check",
+        suppressStdout: true,
+        publishOutput: false,
+    });
+
+    return {
+        exitCode: result.exitCode,
+        report: {
+            ...result.report,
+            operation: "check",
+            outputs: [{ path: outputPath, published: false }],
+            pipeline: {
+                ...result.report.pipeline,
+                stages: ["read", "ir", "write", "validate"],
+            },
+        },
+    };
+}
+
+export async function runConversionPipeline(input: {
+    ctx: CliContext;
+    bindings: PanduckBindings;
+    inputPath: string;
+    outputPath: string | undefined;
+    resolved: ResolvedFormats;
+    shared: SharedCliOptions;
+    toolVersion: string;
+    operation?: "convert" | "check";
+    suppressStdout?: boolean;
+    publishOutput?: boolean;
+}): Promise<PipelineResult> {
+    const {
+        bindings,
+        inputPath,
+        outputPath,
+        resolved,
+        shared,
+        ctx,
+        operation = "convert",
+        suppressStdout = false,
+        publishOutput = true,
+    } = input;
+    const from = resolved.from;
+    const to = resolved.to;
+    if (!from || !to) {
+        throw new Error("conversion requires resolved from/to formats");
+    }
+
+    if (!bindings.convertDocument) {
+        return blocked(ctx, operation, inputPath, resolved, shared, "native convertDocument binding is missing");
+    }
+
+    const response = bindings.convertDocument(from, to, inputPath);
+    const markdown = response.markdown ?? "";
+    const binary = response.binary;
+    const parsedReport = safeParseReport(response.reportJson);
+
+    if (publishOutput && outputPath && !isStdoutPath(outputPath)) {
+        if (binary && binary.length > 0) {
+            await publishBinary(outputPath, binary);
+        } else {
+            await publishText(outputPath, markdown);
+        }
+    } else if (!suppressStdout && (isStdoutPath(outputPath) || !outputPath)) {
+        if (binary && binary.length > 0) {
+            process.stdout.write(binary);
+        } else {
+            process.stdout.write(markdown);
+        }
+    }
+
+    const lossCount = Array.isArray(parsedReport?.losses) ? parsedReport.losses.length : 0;
+    const status = lossCount > 0 ? "success_with_loss" : "success";
+    let exitCode: number = ExitCode.Success;
+    if (shared.strict || shared.loss === "deny") {
+        if (lossCount > 0 || status === "success_with_loss") {
+            exitCode = ExitCode.LossPolicyViolation;
+        }
+    }
+
+    const report = createReport({
+        operation,
+        toolVersion: ctx.toolVersion,
+        status,
+        inputs: [{ path: inputPath, format: from }],
+        detection: { format: from, outer: "zip", inner: "opc", confidence: "verified", hints: resolved.hints },
+        pipeline: {
+            reader: from,
+            writer: to,
+            stages: operation === "check" ? ["read", "ir", "write", "validate"] : ["read", "ir", "write", "publish"],
+        },
+        losses: parsedReport?.losses as PanduckReport["losses"],
+        outputs: outputPath
+            ? [{ path: outputPath, published: publishOutput && !isStdoutPath(outputPath) }]
+            : [{ path: "-", published: !suppressStdout }],
+        budgets: shared.budgets,
+        determinism: { profile: shared.profile ?? "default", config: shared.config ?? null },
+        statusPolicy: { loss: shared.loss, strict: shared.strict, exit_code: exitCode },
+    });
+
+    return { exitCode, report };
+}
+
+async function publishBinary(path: string, content: Uint8Array): Promise<void> {
+    const dir = dirname(path);
+    await mkdir(dir, { recursive: true });
+    const temp = join(dir, `.${basename(path)}.${randomBytes(4).toString("hex")}.tmp`);
+    await writeFile(temp, content);
+    await rename(temp, path);
+}
+
+async function publishText(path: string, content: string): Promise<void> {
+    const dir = dirname(path);
+    await mkdir(dir, { recursive: true });
+    const temp = join(dir, `.${basename(path)}.${randomBytes(4).toString("hex")}.tmp`);
+    await writeFile(temp, content, "utf8");
+    await rename(temp, path);
+}
+
+function safeParseReport(raw: string): Record<string, unknown> | null {
+    try {
+        return JSON.parse(raw) as Record<string, unknown>;
+    } catch {
+        return null;
+    }
+}
+
+function blocked(
+    ctx: CliContext,
+    operation: "convert" | "check",
+    inputPath: string,
+    resolved: ResolvedFormats,
+    shared: SharedCliOptions,
+    reason: string,
+): PipelineResult {
+    const report = createReport({
+        operation,
+        toolVersion: ctx.toolVersion,
+        status: "blocked",
+        inputs: [{ path: inputPath, format: resolved.from }],
+        pipeline: { blocked_reason: reason },
+        diagnostics: [{ owner: "panduck", severity: "error", message: reason }],
+        determinism: { profile: shared.profile ?? "default", config: shared.config ?? null },
+        statusPolicy: { loss: shared.loss, strict: shared.strict, exit_code: ExitCode.IrOrWriterFailure },
+    });
+    return { exitCode: ExitCode.IrOrWriterFailure, report };
+}
+
+export async function emitPipelineResult(
+    result: PipelineResult,
+    shared: SharedCliOptions,
+): Promise<number> {
+    emitReport(result.report, shared.diagnostics, shared.json);
+    return result.exitCode;
+}