@notedge/panduck 0.0.0

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

@@ -0,0 +1,84 @@
+import { access, mkdtemp, rm } from "node:fs/promises";
+import { constants } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { Cli, ParsedOptions } from "@vmz/commander";
+
+import { loadBindings } from "../context.js";
+import { emitHuman, emitJson } from "../diagnostics.js";
+import { readSharedOptions } from "../options.js";
+
+type DoctorCheck = {
+    id: string;
+    ok: boolean;
+    message: string;
+};
+
+export function registerDoctorCommand(cli: Cli): void {
+    cli.command("doctor", "cli.cmd.doctor")
+        .option("--json", "cli.opt.json")
+        .action((options: ParsedOptions) => runDoctor(options));
+}
+
+async function runDoctor(options: ParsedOptions): Promise<number> {
+    const shared = readSharedOptions(options);
+    const checks: DoctorCheck[] = [];
+
+    checks.push({
+        id: "node",
+        ok: Number(process.versions.node.split(".")[0]) >= 20,
+        message: `node ${process.version}`,
+    });
+
+    const bindings = loadBindings();
+    if (bindings) {
+        checks.push({
+            id: "native",
+            ok: true,
+            message: `panduck-napi ${bindings.panduckVersion()}; formats=${bindings.supportedFormats().join(",")}`,
+        });
+    } else {
+        checks.push({
+            id: "native",
+            ok: false,
+            message: "native bindings are not installed for this platform",
+        });
+    }
+
+    try {
+        const dir = await mkdtemp(join(tmpdir(), "panduck-doctor-"));
+        await access(dir, constants.W_OK);
+        await rm(dir, { recursive: true, force: true });
+        checks.push({ id: "tempdir", ok: true, message: tmpdir() });
+    } catch (error) {
+        checks.push({
+            id: "tempdir",
+            ok: false,
+            message: error instanceof Error ? error.message : String(error),
+        });
+    }
+
+    const ok = checks.every((check) => check.ok);
+    const payload = {
+        schema_version: "panduck.doctor/v1",
+        status: ok ? "ok" : "issues",
+        checks,
+    };
+
+    if (shared.json || options.json === true) {
+        emitJson(payload);
+    } else if (ok) {
+        emitHuman("Panduck environment looks healthy");
+        for (const check of checks) {
+            emitHuman(`  ok  ${check.id}: ${check.message}`);
+        }
+    } else {
+        emitHuman("Panduck environment has issues");
+        for (const check of checks) {
+            emitHuman(`  ${check.ok ? "ok" : "fail"}  ${check.id}: ${check.message}`);
+        }
+    }
+
+    return ok ? 0 : 2;
+}

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

@@ -0,0 +1,50 @@
+import type { Cli, ParsedOptions } from "@vmz/commander";
+
+import { createContext } from "../context.js";
+import { emitJson } from "../diagnostics.js";
+import { findFormat, type OperationKind } from "../format-registry.js";
+import { readSharedOptions, readString } from "../options.js";
+
+export function registerFormatsCommand(cli: Cli): void {
+    cli.command("formats", "cli.cmd.formats")
+        .option("--operation <kind>", "cli.opt.operation")
+        .option("--json", "cli.opt.json")
+        .action((options: ParsedOptions) => runFormats(options));
+}
+
+function runFormats(options: ParsedOptions): number {
+    const shared = readSharedOptions(options);
+    const ctx = createContext();
+    const formatId = options._[0] ?? readString(options, "format");
+    const operation = readString(options, "operation") as OperationKind | undefined;
+    const selected = formatId ? findFormat(ctx.registry, formatId) : undefined;
+    if (formatId && !selected) {
+        console.error(`unknown format: ${formatId}`);
+        return 2;
+    }
+
+    const records = selected ? [selected] : ctx.registry;
+    const payload = records.map((record) => {
+        if (operation === "read") {
+            return { format: record.format, reader: record.reader, container: record.container, coverage: record.coverage };
+        }
+        if (operation === "write") {
+            return { format: record.format, writer: record.writer, container: record.container, coverage: record.coverage };
+        }
+        return record;
+    });
+
+    if (shared.json || options.json === true) {
+        emitJson({
+            schema_version: "panduck.formats/v1",
+            formats: payload,
+            conversions: ctx.bindings?.supportedConversions?.() ?? [],
+        });
+        return 0;
+    }
+
+    for (const record of records) {
+        console.log(`${record.format}\tread=${record.reader.state}\twrite=${record.writer.state}`);
+    }
+    return 0;
+}

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

@@ -0,0 +1,231 @@
+import { stat } from "node:fs/promises";
+
+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 { CliOptionError, parseInspectStage, readSharedOptions, readString } from "../options.js";
+import { configureConsoleBackend } from "../console-backend.js";
+import { createReport } from "../report.js";
+import { isStdinPath } from "../paths.js";
+
+export function registerInspectCommand(cli: Cli): void {
+    cli.command("inspect", "cli.cmd.inspect")
+        .option("--from <format>", "cli.opt.from")
+        .option("--stage <stage>", "cli.opt.stage")
+        .option("--path <layout-path>", "cli.opt.path")
+        .option("--budget <limit>", "cli.opt.budget")
+        .option("--json", "cli.opt.json")
+        .action((options: ParsedOptions) => runInspect(options));
+}
+
+async function runInspect(options: ParsedOptions): Promise<number> {
+    try {
+        const shared = readSharedOptions(options);
+        const inputPath = options._[0] ?? readString(options, "input");
+        if (!inputPath) {
+            return ExitCode.InvalidArgs;
+        }
+        const stage = parseInspectStage(readString(options, "stage"));
+        const layoutPath = readString(options, "path");
+        const ctx = createContext();
+        configureConsoleBackend(ctx.bindings, shared.logFile);
+        const resolved = resolveFormats(inputPath, undefined, shared);
+
+        if (resolved.ambiguous) {
+            const report = buildBlockedReport(
+                ctx,
+                "inspect",
+                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,
+                "inspect",
+                inputPath,
+                resolved,
+                "input is not readable",
+                ExitCode.InputUnsupported,
+                shared,
+            );
+            emitReport(report, shared.diagnostics, shared.json);
+            return ExitCode.InputUnsupported;
+        }
+
+        const size = isStdinPath(inputPath) ? null : (await stat(inputPath)).size;
+
+        if (stage === "decode" && resolved.from === "docx" && ctx.bindings?.inspectDecode) {
+            try {
+                const decode = ctx.bindings.inspectDecode(inputPath, layoutPath);
+                const report = createReport({
+                    operation: "inspect",
+                    toolVersion: ctx.toolVersion,
+                    status: "success",
+                    inputs: [{ path: inputPath, format: decode.format }],
+                    detection: {
+                        format: decode.format,
+                        outer: decode.outer,
+                        inner: decode.inner,
+                        confidence: "verified",
+                        hints: resolved.hints,
+                    },
+                    pipeline: { stages: ["decode"] },
+                    decodedParts: decode.parts.map((part) => ({
+                        path: part.path,
+                        compression_method: part.compressionMethod,
+                        compressed_size: part.compressedSize,
+                        uncompressed_size: part.uncompressedSize,
+                        decoded_size: part.decodedSize,
+                    })),
+                    budgets: shared.budgets,
+                    determinism: { profile: shared.profile ?? "default", config: shared.config ?? null },
+                    statusPolicy: {
+                        loss: shared.loss,
+                        strict: shared.strict,
+                        exit_code: ExitCode.Success,
+                    },
+                });
+                if (size !== null) {
+                    report.budgets = { ...report.budgets, input_bytes: size };
+                }
+                emitReport(report, shared.diagnostics, shared.json);
+                return ExitCode.Success;
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const report = buildBlockedReport(
+                    ctx,
+                    "inspect",
+                    inputPath,
+                    resolved,
+                    message,
+                    ExitCode.IrOrWriterFailure,
+                    shared,
+                );
+                emitReport(report, shared.diagnostics, shared.json);
+                return ExitCode.IrOrWriterFailure;
+            }
+        }
+
+        if (stage === "index" && resolved.from === "docx" && ctx.bindings?.inspectIndex) {
+            try {
+                const index = ctx.bindings.inspectIndex(inputPath);
+                const report = createReport({
+                    operation: "inspect",
+                    toolVersion: ctx.toolVersion,
+                    status: "success",
+                    inputs: [{ path: inputPath, format: index.format }],
+                    detection: {
+                        format: index.format,
+                        outer: index.outer,
+                        inner: index.inner,
+                        confidence: "verified",
+                        hints: resolved.hints,
+                    },
+                    pipeline: { stages: ["index"] },
+                    parts: index.parts,
+                    budgets: shared.budgets,
+                    determinism: { profile: shared.profile ?? "default", config: shared.config ?? null },
+                    statusPolicy: {
+                        loss: shared.loss,
+                        strict: shared.strict,
+                        exit_code: ExitCode.Success,
+                    },
+                });
+                if (size !== null) {
+                    report.budgets = { ...report.budgets, input_bytes: size };
+                }
+                emitReport(report, shared.diagnostics, shared.json);
+                return ExitCode.Success;
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const report = buildBlockedReport(
+                    ctx,
+                    "inspect",
+                    inputPath,
+                    resolved,
+                    message,
+                    ExitCode.IrOrWriterFailure,
+                    shared,
+                );
+                emitReport(report, shared.diagnostics, shared.json);
+                return ExitCode.IrOrWriterFailure;
+            }
+        }
+
+        const report = createReport({
+            operation: "inspect",
+            toolVersion: ctx.toolVersion,
+            status: stage === "probe" ? "success" : "partial",
+            inputs: [{ path: inputPath, format: resolved.from }],
+            detection: {
+                format: resolved.from,
+                confidence: resolved.from ? "hint" : undefined,
+                hints: resolved.hints,
+            },
+            pipeline: {
+                stages: [stage],
+                blocked_reason:
+                    stage === "probe"
+                        ? undefined
+                        : "deeper inspect stages require Acorn/Oak integration",
+            },
+            diagnostics:
+                stage === "probe"
+                    ? []
+                    : [
+                          {
+                              owner: "panduck",
+                              severity: "warning",
+                              message: `inspect stage ${stage} is not implemented yet`,
+                              code: "panduck.inspect.not_implemented",
+                          },
+                      ],
+            budgets: shared.budgets,
+            determinism: { profile: shared.profile ?? "default", config: shared.config ?? null },
+            statusPolicy: {
+                loss: shared.loss,
+                strict: shared.strict,
+                exit_code: stage === "probe" ? ExitCode.Success : ExitCode.IrOrWriterFailure,
+            },
+        });
+
+        if (layoutPath) {
+            report.diagnostics?.push({
+                owner: "acorn",
+                severity: "warning",
+                message: `layout path ${layoutPath} indexing is not implemented yet`,
+                code: "acorn.layout.not_implemented",
+            });
+        }
+
+        if (size !== null) {
+            report.budgets = { ...report.budgets, input_bytes: size };
+        }
+
+        emitReport(report, shared.diagnostics, shared.json);
+        return stage === "probe" ? ExitCode.Success : 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;
+    }
+}

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

@@ -0,0 +1,188 @@
+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, readSharedOptions, readString } from "../options.js";
+import { hasPipeline } from "../pipeline.js";
+import { configureConsoleBackend } from "../console-backend.js";
+import { createReport } from "../report.js";
+
+export function registerPlanCommand(cli: Cli): void {
+    cli.command("plan", "cli.cmd.plan")
+        .option("--to <format>", "cli.opt.to")
+        .option("--from <format>", "cli.opt.from")
+        .option("--profile <name>", "cli.opt.profile")
+        .option("--config <file>", "cli.opt.config")
+        .option("--budget <limit>", "cli.opt.budget")
+        .option("--json", "cli.opt.json")
+        .action((options: ParsedOptions) => runPlan(options));
+}
+
+async function runPlan(options: ParsedOptions): Promise<number> {
+    try {
+        const shared = readSharedOptions(options);
+        const inputPath = options._[0] ?? readString(options, "input");
+        if (!inputPath) {
+            return ExitCode.InvalidArgs;
+        }
+        const ctx = createContext();
+        configureConsoleBackend(ctx.bindings, shared.logFile);
+        const resolved = resolveFormats(inputPath, undefined, shared);
+
+        if (resolved.ambiguous) {
+            const report = buildBlockedReport(
+                ctx,
+                "plan",
+                inputPath,
+                resolved,
+                "ambiguous input format",
+                ExitCode.InputUnsupported,
+                shared,
+            );
+            emitReport(report, shared.diagnostics, shared.json);
+            return ExitCode.InputUnsupported;
+        }
+
+        if (!resolved.to) {
+            const report = buildBlockedReport(
+                ctx,
+                "plan",
+                inputPath,
+                resolved,
+                "target format is required for plan",
+                ExitCode.InvalidArgs,
+                shared,
+            );
+            emitReport(report, shared.diagnostics, shared.json);
+            return ExitCode.InvalidArgs;
+        }
+
+        try {
+            await assertReadableInput(inputPath);
+        } catch {
+            const report = buildBlockedReport(
+                ctx,
+                "plan",
+                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;
+        const target = findFormat(ctx.registry, resolved.to);
+        if (!target) {
+            const report = buildBlockedReport(
+                ctx,
+                "plan",
+                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 (!routeReady) {
+            if (source && !isOperationReady(source, "read")) {
+                const report = createReport({
+                    operation: "plan",
+                    toolVersion: ctx.toolVersion,
+                    status: "blocked",
+                    inputs: [{ path: inputPath, format: source.format }],
+                    detection: { format: source.format, confidence: "hint", hints: resolved.hints },
+                    pipeline: {
+                        reader: source.format,
+                        writer: target.format,
+                        stages: ["detect", "read", "ir", "write", "publish"],
+                        blocked_reason: `reader state is ${source.reader.state}`,
+                    },
+                    coverage: target.coverage,
+                    diagnostics: [
+                        {
+                            owner: "panduck",
+                            severity: "error",
+                            message: `source format ${source.format} is not ready for read`,
+                            code: "panduck.reader.not_ready",
+                        },
+                    ],
+                    determinism: { profile: shared.profile ?? "default", config: shared.config ?? null },
+                    statusPolicy: { loss: shared.loss, strict: shared.strict, exit_code: ExitCode.InputUnsupported },
+                });
+                emitReport(report, shared.diagnostics, shared.json);
+                return ExitCode.InputUnsupported;
+            }
+
+            if (!isOperationReady(target, "write")) {
+                const report = createReport({
+                    operation: "plan",
+                    toolVersion: ctx.toolVersion,
+                    status: "blocked",
+                    inputs: [{ path: inputPath, format: resolved.from }],
+                    detection: { format: resolved.from, confidence: "hint", hints: resolved.hints },
+                    pipeline: {
+                        reader: source?.format,
+                        writer: target.format,
+                        stages: ["detect", "read", "ir", "write", "publish"],
+                        blocked_reason: `writer state is ${target.writer.state}`,
+                    },
+                    coverage: target.coverage,
+                    diagnostics: [
+                        {
+                            owner: "panduck",
+                            severity: "error",
+                            message: `target format ${target.format} is not ready for write`,
+                            code: "panduck.writer.not_ready",
+                        },
+                    ],
+                    determinism: { profile: shared.profile ?? "default", config: shared.config ?? null },
+                    statusPolicy: { loss: shared.loss, strict: shared.strict, exit_code: ExitCode.InputUnsupported },
+                });
+                emitReport(report, shared.diagnostics, shared.json);
+                return ExitCode.InputUnsupported;
+            }
+        }
+
+        const report = createReport({
+            operation: "plan",
+            toolVersion: ctx.toolVersion,
+            status: routeReady ? "success" : "success_with_loss",
+            inputs: [{ path: inputPath, format: resolved.from }],
+            detection: { format: resolved.from, confidence: resolved.from ? "hint" : undefined, hints: resolved.hints },
+            pipeline: {
+                reader: source?.format ?? resolved.from,
+                writer: target.format,
+                stages: ["detect", "read", "ir", "write", "publish"],
+            },
+            coverage: source?.coverage ?? target.coverage,
+            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;
+    } 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/console-backend.ts

@@ -0,0 +1,16 @@
+import type { PanduckBindings } from "../types.js";
+
+/** Install a native JSON lines log sink when bindings expose the hook. */
+export function configureConsoleBackend(
+    bindings: PanduckBindings | null,
+    logFile?: string,
+): void {
+    if (!logFile) {
+        return;
+    }
+    const install = bindings?.installLoggerLogFile ?? bindings?.installConsoleLogFile;
+    if (!install) {
+        return;
+    }
+    install(logFile);
+}

package/src/cli/context.ts

@@ -0,0 +1,98 @@
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+
+import type { PanduckBindings } from "../types.js";
+import { loadPanduckNode } from "../node/load.js";
+import { getFormatRegistry, findFormat, type FormatRecord } from "./format-registry.js";
+import { extensionHints, inferTargetFromPath, isStdinPath, normalizeFormatId, pathsOverlap } from "./paths.js";
+import { ExitCode } from "./exit-codes.js";
+import type { SharedCliOptions } from "./options.js";
+import { createReport, type PanduckReport } from "./report.js";
+
+export type CliContext = {
+    bindings: PanduckBindings | null;
+    toolVersion: string;
+    registry: FormatRecord[];
+};
+
+export function loadBindings(): PanduckBindings | null {
+    try {
+        return loadPanduckNode();
+    } catch {
+        return null;
+    }
+}
+
+export function createContext(): CliContext {
+    const bindings = loadBindings();
+    return {
+        bindings,
+        toolVersion: bindings?.panduckVersion() ?? "0.0.0",
+        registry: getFormatRegistry(bindings),
+    };
+}
+
+/** Resolved source/target format ids for a CLI invocation. */
+export type ResolvedFormats = {
+    from?: string;
+    to?: string;
+    ambiguous: boolean;
+    hints: string[];
+};
+
+export function resolveFormats(
+    inputPath: string,
+    outputPath: string | undefined,
+    shared: SharedCliOptions,
+): ResolvedFormats {
+    const hints = extensionHints(inputPath);
+    const from = shared.from ? normalizeFormatId(shared.from) : hints.length === 1 ? hints[0] : undefined;
+    const to =
+        shared.to
+            ? normalizeFormatId(shared.to)
+            : outputPath && outputPath !== "-"
+              ? inferTargetFromPath(outputPath)
+              : undefined;
+    const ambiguous = !shared.from && hints.length > 1;
+    return { from, to, ambiguous, hints };
+}
+
+export async function assertReadableInput(path: string): Promise<void> {
+    if (isStdinPath(path)) {
+        return;
+    }
+    await access(path, constants.R_OK);
+}
+
+export function buildBlockedReport(
+    ctx: CliContext,
+    operation: string,
+    inputPath: string,
+    resolved: ResolvedFormats,
+    reason: string,
+    exitCode: number,
+    shared: SharedCliOptions,
+): PanduckReport {
+    return createReport({
+        operation,
+        toolVersion: ctx.toolVersion,
+        status: "blocked",
+        inputs: [{ path: inputPath, format: resolved.from }],
+        detection: {
+            format: resolved.from,
+            confidence: resolved.ambiguous ? "ambiguous" : resolved.from ? "hint" : undefined,
+            hints: resolved.hints,
+        },
+        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 },
+    });
+}
+
+export function validateIoPaths(inputPath: string, outputPath: string | undefined): number | null {
+    if (outputPath && pathsOverlap(inputPath, outputPath)) {
+        return ExitCode.InvalidArgs;
+    }
+    return null;
+}

package/src/cli/diagnostics.ts

@@ -0,0 +1,24 @@
+import type { DiagnosticsMode } from "./options.js";
+import type { PanduckReport } from "./report.js";
+
+export function emitHuman(message: string): void {
+    console.error(message);
+}
+
+export function emitJson(value: unknown): void {
+    console.log(JSON.stringify(value, null, 2));
+}
+
+export function emitReport(report: PanduckReport, mode: DiagnosticsMode, jsonRequested: boolean): void {
+    if (jsonRequested || mode === "json") {
+        emitJson(report);
+        return;
+    }
+    if (mode === "silent") {
+        return;
+    }
+    emitHuman(`${report.operation}: ${report.status}`);
+    for (const item of report.diagnostics ?? []) {
+        emitHuman(`[${item.owner}] ${item.severity}: ${item.message}`);
+    }
+}