fconvert 0.1.0

package/README.md

@@ -0,0 +1,54 @@
+# convert
+
+Fast local CLI conversion tool with graph-based anything-to-anything routing.
+
+## Quick start
+
+```bash
+bun install
+bun run convert formats
+```
+
+## Commands
+
+```bash
+bun run convert <input> <output>
+bun run convert route <input> --to <format>
+bun run convert formats
+bun run convert handlers
+bun run convert doctor
+```
+
+## Useful flags
+
+```bash
+--from <format>
+--to <format>
+--output <path>
+--force
+--strict
+--show-route
+--json
+--verbose
+--keep-temp
+--max-steps <n>
+--max-candidates <n>
+```
+
+## Build
+
+```bash
+bun run build
+```
+
+Compiled binary is written to `dist/convert`.
+
+## Project structure
+
+- `src/cli`: command parsing and command entrypoints
+- `src/formats`: format registry and detection
+- `src/handlers`: native and bridge handlers
+- `src/planner`: weighted route graph and search
+- `src/executor`: workspace and route execution
+- `src/bundle`: bundled binary resolution
+- `src/diagnostics`: doctor checks

package/assets/manifest.json

@@ -0,0 +1,15 @@
+{
+  "version": "0.1.0",
+  "platforms": {
+    "linux-x64": {
+      "bins": {
+        "ffmpeg": "bin/ffmpeg",
+        "pandoc": "bin/pandoc",
+        "magick": "bin/magick",
+        "7zz": "bin/7zz"
+      },
+      "wasm": [],
+      "libs": []
+    }
+  }
+}

package/bun.lock

@@ -0,0 +1,26 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "convert-cli",
+      "devDependencies": {
+        "@types/bun": "latest",
+      },
+      "peerDependencies": {
+        "typescript": "^5",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.11", "", { "dependencies": { "bun-types": "1.3.11" } }, "sha512-5vPne5QvtpjGpsGYXiFyycfpDF2ECyPcTSsFBMa0fraoxiQyMJ3SmuQIGhzPg2WJuWxVBoxWJ2kClYTcw/4fAg=="],
+
+    "@types/node": ["@types/node@25.5.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw=="],
+
+    "bun-types": ["bun-types@1.3.11", "", { "dependencies": { "@types/node": "*" } }, "sha512-1KGPpoxQWl9f6wcZh57LvrPIInQMn2TQ7jsgxqpRzg+l0QPOFvJVH7HmvHo/AiPgwXy+/Thf6Ov3EdVn1vOabg=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
+  }
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "fconvert",
+  "version": "0.1.0",
+  "description": "Fast local CLI conversion tool with graph-based anything-to-anything routing",
+  "type": "module",
+  "main": "src/cli/main.ts",
+  "scripts": {
+    "start": "bun run src/cli/main.ts",
+    "convert": "bun run src/cli/main.ts",
+    "test": "bun test",
+    "typecheck": "bunx tsc --noEmit",
+    "build": "bun build src/cli/main.ts --compile --outfile dist/convert"
+  },
+  "bin": {
+    "convert": "dist/convert"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "keywords": ["convert", "converter", "ffmpeg", "pandoc", "cli"],
+  "license": "MIT"
+}

package/src/artifacts/artifact.ts

@@ -0,0 +1,21 @@
+import type { FileFormat } from "../core/types.ts";
+
+export type ArtifactKind = "file" | "directory" | "sequence";
+
+export interface ArtifactRef {
+  kind: ArtifactKind;
+  path: string;
+  format?: FileFormat;
+  size?: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ConversionInput {
+  artifact: ArtifactRef;
+  format: FileFormat;
+}
+
+export interface ConversionOutput {
+  artifacts: ArtifactRef[];
+  format: FileFormat;
+}

package/src/artifacts/file.ts

@@ -0,0 +1,11 @@
+import { stat } from "node:fs/promises";
+import type { ArtifactRef } from "./artifact.ts";
+
+export async function toFileArtifact(path: string): Promise<ArtifactRef> {
+  const fileStat = await stat(path);
+  return {
+    kind: "file",
+    path,
+    size: fileStat.size,
+  };
+}

package/src/bundle/manifest.ts

@@ -0,0 +1,10 @@
+export interface PlatformManifest {
+  bins: Record<string, string>;
+  wasm?: string[];
+  libs?: string[];
+}
+
+export interface BundleManifest {
+  version: string;
+  platforms: Record<string, PlatformManifest>;
+}

package/src/bundle/platform.ts

@@ -0,0 +1,10 @@
+import { arch, platform } from "node:process";
+
+export function platformKey(): string {
+  const os = platform;
+  const cpu = arch;
+
+  const osPart = os === "win32" ? "windows" : os === "darwin" ? "macos" : os;
+  const cpuPart = cpu === "x64" ? "x64" : cpu === "arm64" ? "arm64" : cpu;
+  return `${osPart}-${cpuPart}`;
+}

package/src/bundle/resolve.ts

@@ -0,0 +1,88 @@
+import { constants as fsConstants } from "node:fs";
+import { access, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CliError, ExitCode } from "../core/errors.ts";
+import type { BundleManifest, PlatformManifest } from "./manifest.ts";
+import { platformKey } from "./platform.ts";
+
+function isExecutable(path: string): Promise<boolean> {
+  return access(path, fsConstants.X_OK)
+    .then(() => true)
+    .catch(() => false);
+}
+
+export class BundleResolver {
+  readonly assetsDir: string;
+  private manifestCache?: BundleManifest;
+
+  constructor(assetsDir?: string) {
+    if (assetsDir) {
+      this.assetsDir = assetsDir;
+      return;
+    }
+
+    const fromEnv = process.env.CONVERT_ASSETS_DIR;
+    if (fromEnv) {
+      this.assetsDir = fromEnv;
+      return;
+    }
+
+    const currentDir = dirname(fileURLToPath(import.meta.url));
+    this.assetsDir = join(currentDir, "../../assets");
+  }
+
+  private async manifest(): Promise<BundleManifest | undefined> {
+    if (this.manifestCache) {
+      return this.manifestCache;
+    }
+
+    const manifestPath = join(this.assetsDir, "manifest.json");
+    try {
+      const contents = await readFile(manifestPath, "utf8");
+      this.manifestCache = JSON.parse(contents) as BundleManifest;
+      return this.manifestCache;
+    } catch {
+      return undefined;
+    }
+  }
+
+  async resolveBinary(name: string, allowSystem = true): Promise<string | undefined> {
+    const envKey = `CONVERT_BIN_${name.toUpperCase()}`;
+    const fromEnv = process.env[envKey];
+    if (fromEnv && (await isExecutable(fromEnv))) {
+      return fromEnv;
+    }
+
+    const manifest = await this.manifest();
+    const platform = platformKey();
+    const platformManifest: PlatformManifest | undefined = manifest?.platforms[platform];
+    const relative = platformManifest?.bins[name];
+    if (relative) {
+      const candidate = join(this.assetsDir, platform, relative);
+      if (await isExecutable(candidate)) {
+        return candidate;
+      }
+    }
+
+    if (allowSystem) {
+      const fromSystem = Bun.which(name);
+      if (fromSystem) {
+        return fromSystem;
+      }
+    }
+
+    return undefined;
+  }
+
+  async mustResolveBinary(name: string): Promise<string> {
+    const path = await this.resolveBinary(name);
+    if (!path) {
+      throw new CliError(
+        `Required binary not found: ${name}. Run 'convert doctor' for details.`,
+        ExitCode.EnvironmentError,
+      );
+    }
+    return path;
+  }
+}

package/src/cli/commands/convert.ts

@@ -0,0 +1,105 @@
+import { access } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import { BundleResolver } from "../../bundle/resolve.ts";
+import { buildPlanOptions } from "../../core/config.ts";
+import { CliError, ExitCode } from "../../core/errors.ts";
+import { ConsoleLogger } from "../../core/logger.ts";
+import type { ConvertSummary } from "../../core/types.ts";
+import { ConversionEngine } from "../../executor/executor.ts";
+import { detectInputFormat, resolveOutputFormat } from "../../formats/detect.ts";
+import { FormatRegistry } from "../../formats/registry.ts";
+import { HandlerRegistry } from "../../handlers/registry.ts";
+import { explainRoute } from "../../planner/explain.ts";
+
+async function outputExists(path: string): Promise<boolean> {
+  try {
+    await access(path, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function runConvertCommand(input: {
+  positionals: string[];
+  options: {
+    from?: string;
+    to?: string;
+    output?: string;
+    force: boolean;
+    strict: boolean;
+    json: boolean;
+    verbose: boolean;
+    quiet: boolean;
+    showRoute: boolean;
+    keepTemp: boolean;
+    timeoutMs?: number;
+    maxSteps: number;
+    maxCandidates: number;
+  };
+}): Promise<void> {
+  const logger = new ConsoleLogger(input.options.verbose, input.options.quiet);
+
+  const inputPath = input.positionals[0];
+  const positionalOutput = input.positionals[1];
+  const outputPath = input.options.output ?? positionalOutput;
+
+  if (!inputPath) {
+    throw new CliError("Usage: convert <input> <output> [--from fmt] [--to fmt]", ExitCode.InvalidArgs);
+  }
+
+  if (!outputPath) {
+    throw new CliError("Missing output path. Provide <output> or --output", ExitCode.InvalidArgs);
+  }
+
+  if ((await outputExists(outputPath)) && !input.options.force) {
+    throw new CliError(`Output exists: ${outputPath}. Use --force to overwrite.`, ExitCode.InvalidArgs);
+  }
+
+  const formats = new FormatRegistry();
+  const inputFormat = detectInputFormat(inputPath, input.options.from, formats);
+  const outputFormat = resolveOutputFormat(outputPath, input.options.to, formats);
+
+  const bundle = new BundleResolver();
+  const handlers = new HandlerRegistry();
+  const engine = new ConversionEngine(formats, handlers, bundle, logger);
+
+  const result = await engine.execute({
+    inputPath,
+    outputPath,
+    inputFormat,
+    outputFormat,
+    strict: input.options.strict,
+    keepTemp: input.options.keepTemp,
+    timeoutMs: input.options.timeoutMs,
+    plan: buildPlanOptions({
+      strict: input.options.strict,
+      maxSteps: input.options.maxSteps,
+      maxCandidates: input.options.maxCandidates,
+    }),
+  });
+
+  const route = explainRoute(result.route);
+  const summary: ConvertSummary = {
+    ok: true,
+    input: inputPath,
+    output: result.outputPath,
+    route,
+    durationMs: result.durationMs,
+    warnings: result.warnings,
+  };
+
+  if (input.options.json) {
+    console.log(JSON.stringify(summary, null, 2));
+    return;
+  }
+
+  logger.info(`converted: ${inputPath} -> ${result.outputPath}`);
+  logger.info(`duration: ${result.durationMs}ms`);
+  if (input.options.showRoute || input.options.verbose) {
+    logger.info(`route: ${route.join(" | ")}`);
+  }
+  for (const warning of result.warnings) {
+    logger.warn(`warning: ${warning}`);
+  }
+}

package/src/cli/commands/doctor.ts

@@ -0,0 +1,16 @@
+import { BundleResolver } from "../../bundle/resolve.ts";
+import { runDoctor } from "../../diagnostics/doctor.ts";
+
+export async function runDoctorCommand(json: boolean): Promise<void> {
+  const bundle = new BundleResolver();
+  const checks = await runDoctor(bundle);
+
+  if (json) {
+    console.log(JSON.stringify({ ok: checks.every((item) => item.ok), checks }, null, 2));
+    return;
+  }
+
+  for (const check of checks) {
+    console.log(`${check.ok ? "ok " : "err"} ${check.name.padEnd(16)} ${check.detail}`);
+  }
+}

package/src/cli/commands/formats.ts

@@ -0,0 +1,20 @@
+import { FormatRegistry } from "../../formats/registry.ts";
+
+export async function runFormatsCommand(json: boolean): Promise<void> {
+  const registry = new FormatRegistry();
+  const formats = registry.all().map((format) => ({
+    id: format.id,
+    extension: format.extension,
+    category: format.category,
+    name: format.name,
+  }));
+
+  if (json) {
+    console.log(JSON.stringify({ ok: true, formats }, null, 2));
+    return;
+  }
+
+  for (const format of formats) {
+    console.log(`${format.id.padEnd(8)} .${format.extension.padEnd(6)} ${format.category.join(",")}`);
+  }
+}

package/src/cli/commands/handlers.ts

@@ -0,0 +1,37 @@
+import { BundleResolver } from "../../bundle/resolve.ts";
+import { ConsoleLogger } from "../../core/logger.ts";
+import { Workspace } from "../../executor/workspace.ts";
+import { HandlerRegistry } from "../../handlers/registry.ts";
+
+export async function runHandlersCommand(input: {
+  json: boolean;
+  verbose: boolean;
+  quiet: boolean;
+  timeoutMs?: number;
+}): Promise<void> {
+  const logger = new ConsoleLogger(input.verbose, input.quiet);
+  const workspace = await Workspace.create();
+  const bundle = new BundleResolver();
+  const handlers = new HandlerRegistry();
+
+  try {
+    await handlers.init({
+      workspace,
+      bundle,
+      logger,
+      timeoutMs: input.timeoutMs,
+    });
+
+    const status = handlers.status();
+    if (input.json) {
+      console.log(JSON.stringify({ ok: true, handlers: status }, null, 2));
+      return;
+    }
+
+    for (const item of status) {
+      console.log(`${item.name.padEnd(14)} ${item.available ? "available" : "missing"}`);
+    }
+  } finally {
+    await workspace.cleanup(false);
+  }
+}

package/src/cli/commands/route.ts

@@ -0,0 +1,91 @@
+import { BundleResolver } from "../../bundle/resolve.ts";
+import { buildPlanOptions } from "../../core/config.ts";
+import { CliError, ExitCode } from "../../core/errors.ts";
+import { ConsoleLogger } from "../../core/logger.ts";
+import { detectInputFormat, resolveOutputFormat } from "../../formats/detect.ts";
+import { FormatRegistry } from "../../formats/registry.ts";
+import { HandlerRegistry } from "../../handlers/registry.ts";
+import { describeRoutes } from "../../planner/explain.ts";
+import { ConversionEngine } from "../../executor/executor.ts";
+
+export async function runRouteCommand(input: {
+  positionals: string[];
+  options: {
+    from?: string;
+    to?: string;
+    output?: string;
+    strict: boolean;
+    json: boolean;
+    verbose: boolean;
+    quiet: boolean;
+    timeoutMs?: number;
+    maxSteps: number;
+    maxCandidates: number;
+  };
+}): Promise<void> {
+  const logger = new ConsoleLogger(input.options.verbose, input.options.quiet);
+
+  const inputPath = input.positionals[0];
+  const positionalOutput = input.positionals[1];
+  const outputPath = input.options.output ?? positionalOutput;
+
+  if (!inputPath) {
+    throw new CliError("Usage: convert route <input> --to <format>", ExitCode.InvalidArgs);
+  }
+  if (!input.options.to && !outputPath) {
+    throw new CliError("Missing target format: provide --to or output path", ExitCode.InvalidArgs);
+  }
+
+  const formats = new FormatRegistry();
+  const inputFormat = detectInputFormat(inputPath, input.options.from, formats);
+  const outputFormat = resolveOutputFormat(outputPath, input.options.to, formats);
+
+  const bundle = new BundleResolver();
+  const handlers = new HandlerRegistry();
+  const engine = new ConversionEngine(formats, handlers, bundle, logger);
+
+  const planned = await engine.planRoutes(
+    inputFormat,
+    outputFormat,
+    input.options.strict,
+    buildPlanOptions({
+      strict: input.options.strict,
+      maxSteps: input.options.maxSteps,
+      maxCandidates: input.options.maxCandidates,
+    }),
+    input.options.timeoutMs,
+  );
+
+  try {
+    if (input.options.json) {
+      console.log(
+        JSON.stringify(
+          {
+            ok: true,
+            from: inputFormat.id,
+            to: outputFormat.id,
+            routes: planned.routes.map((route) => ({
+              totalCost: route.totalCost,
+              steps: route.edges.map((edge) => `${edge.handler.name}:${edge.from.id}->${edge.to.id}`),
+            })),
+          },
+          null,
+          2,
+        ),
+      );
+      return;
+    }
+
+    if (planned.routes.length === 0) {
+      logger.info(`no route found for ${inputFormat.id} -> ${outputFormat.id}`);
+      return;
+    }
+
+    logger.info(`routes for ${inputFormat.id} -> ${outputFormat.id}`);
+    for (const line of describeRoutes(planned.routes, 10)) {
+      logger.info(line);
+    }
+  } finally {
+    await planned.workspace.cleanup(false);
+  }
+}

package/src/cli/main.ts

@@ -0,0 +1,69 @@
+#!/usr/bin/env bun
+
+import { runConvertCommand } from "./commands/convert.ts";
+import { runDoctorCommand } from "./commands/doctor.ts";
+import { runFormatsCommand } from "./commands/formats.ts";
+import { runHandlersCommand } from "./commands/handlers.ts";
+import { runRouteCommand } from "./commands/route.ts";
+import { CliError, ExitCode } from "../core/errors.ts";
+import { parseArgs } from "./parse.ts";
+
+function printUsage(): void {
+  console.log("convert <input> <output> [--from fmt] [--to fmt]");
+  console.log("convert route <input> --to <format>");
+  console.log("convert formats");
+  console.log("convert handlers");
+  console.log("convert doctor");
+}
+
+async function main(): Promise<void> {
+  const parsed = parseArgs(Bun.argv.slice(2));
+
+  switch (parsed.command) {
+    case "convert":
+      await runConvertCommand({
+        positionals: parsed.positionals,
+        options: parsed.options,
+      });
+      return;
+    case "route":
+      await runRouteCommand({
+        positionals: parsed.positionals,
+        options: parsed.options,
+      });
+      return;
+    case "formats":
+      await runFormatsCommand(parsed.options.json);
+      return;
+    case "handlers":
+      await runHandlersCommand({
+        json: parsed.options.json,
+        verbose: parsed.options.verbose,
+        quiet: parsed.options.quiet,
+        timeoutMs: parsed.options.timeoutMs,
+      });
+      return;
+    case "doctor":
+      await runDoctorCommand(parsed.options.json);
+      return;
+    default:
+      throw new CliError(`Unknown command: ${parsed.command}`, ExitCode.InvalidArgs);
+  }
+}
+
+main().catch((error: unknown) => {
+  if (error instanceof CliError) {
+    console.error(error.message);
+    if (error.exitCode === ExitCode.InvalidArgs) {
+      printUsage();
+    }
+    process.exit(error.exitCode);
+  }
+
+  if (error instanceof Error) {
+    console.error(error.message);
+  } else {
+    console.error(String(error));
+  }
+  process.exit(ExitCode.InternalError);
+});