fconvert 0.1.0

package/src/cli/parse.ts

@@ -0,0 +1,127 @@
+import { CliError, ExitCode } from "../core/errors.ts";
+import { DEFAULT_MAX_CANDIDATES, DEFAULT_MAX_STEPS } from "../core/config.ts";
+import type { CliOptions } from "../core/types.ts";
+
+export interface ParsedArgs {
+  command: "convert" | "route" | "formats" | "handlers" | "doctor";
+  positionals: string[];
+  options: CliOptions;
+}
+
+function parseNumber(value: string | undefined, fallback: number, flagName: string): number {
+  if (!value) {
+    return fallback;
+  }
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new CliError(`Invalid ${flagName} value: ${value}`, ExitCode.InvalidArgs);
+  }
+  return parsed;
+}
+
+export function parseArgs(argv: string[]): ParsedArgs {
+  const raw = [...argv];
+  const knownCommands = new Set(["convert", "route", "formats", "handlers", "doctor"]);
+
+  let command: ParsedArgs["command"] = "convert";
+  if (raw[0] && knownCommands.has(raw[0])) {
+    command = raw.shift() as ParsedArgs["command"];
+  }
+
+  const options: CliOptions = {
+    force: false,
+    strict: false,
+    json: false,
+    verbose: false,
+    quiet: false,
+    showRoute: false,
+    keepTemp: false,
+    maxSteps: DEFAULT_MAX_STEPS,
+    maxCandidates: DEFAULT_MAX_CANDIDATES,
+  };
+
+  const positionals: string[] = [];
+  for (let index = 0; index < raw.length; index += 1) {
+    const token = raw[index];
+    if (!token) {
+      continue;
+    }
+
+    const next = raw[index + 1];
+
+    if (token === "--from") {
+      if (!next) throw new CliError("Missing value for --from", ExitCode.InvalidArgs);
+      options.from = next;
+      index += 1;
+      continue;
+    }
+    if (token === "--to") {
+      if (!next) throw new CliError("Missing value for --to", ExitCode.InvalidArgs);
+      options.to = next;
+      index += 1;
+      continue;
+    }
+    if (token === "--output") {
+      if (!next) throw new CliError("Missing value for --output", ExitCode.InvalidArgs);
+      options.output = next;
+      index += 1;
+      continue;
+    }
+    if (token === "--timeout") {
+      options.timeoutMs = parseNumber(next, 0, "--timeout");
+      index += 1;
+      continue;
+    }
+    if (token === "--max-steps") {
+      options.maxSteps = parseNumber(next, DEFAULT_MAX_STEPS, "--max-steps");
+      index += 1;
+      continue;
+    }
+    if (token === "--max-candidates") {
+      options.maxCandidates = parseNumber(next, DEFAULT_MAX_CANDIDATES, "--max-candidates");
+      index += 1;
+      continue;
+    }
+
+    if (token === "--force") {
+      options.force = true;
+      continue;
+    }
+    if (token === "--strict") {
+      options.strict = true;
+      continue;
+    }
+    if (token === "--json") {
+      options.json = true;
+      continue;
+    }
+    if (token === "--verbose") {
+      options.verbose = true;
+      continue;
+    }
+    if (token === "--quiet") {
+      options.quiet = true;
+      continue;
+    }
+    if (token === "--show-route") {
+      options.showRoute = true;
+      continue;
+    }
+    if (token === "--keep-temp") {
+      options.keepTemp = true;
+      continue;
+    }
+
+    if (token.startsWith("--")) {
+      throw new CliError(`Unknown option: ${token}`, ExitCode.InvalidArgs);
+    }
+
+    positionals.push(token);
+  }
+
+  return {
+    command,
+    positionals,
+    options,
+  };
+}

package/src/core/config.ts

@@ -0,0 +1,16 @@
+import type { PlanOptions } from "./types.ts";
+
+export const DEFAULT_MAX_STEPS = 6;
+export const DEFAULT_MAX_CANDIDATES = 12;
+
+export function buildPlanOptions(options: {
+  strict: boolean;
+  maxSteps: number;
+  maxCandidates: number;
+}): PlanOptions {
+  return {
+    strict: options.strict,
+    maxSteps: options.maxSteps,
+    maxCandidates: options.maxCandidates,
+  };
+}

package/src/core/errors.ts

@@ -0,0 +1,18 @@
+export enum ExitCode {
+  Ok = 0,
+  ConversionFailed = 1,
+  InvalidArgs = 2,
+  UnsupportedRoute = 3,
+  EnvironmentError = 4,
+  InternalError = 5,
+}
+
+export class CliError extends Error {
+  readonly exitCode: ExitCode;
+
+  constructor(message: string, exitCode: ExitCode) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+  }
+}

package/src/core/logger.ts

@@ -0,0 +1,38 @@
+export interface Logger {
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+  debug(message: string): void;
+}
+
+export class ConsoleLogger implements Logger {
+  private readonly verbose: boolean;
+  private readonly quiet: boolean;
+
+  constructor(verbose: boolean, quiet: boolean) {
+    this.verbose = verbose;
+    this.quiet = quiet;
+  }
+
+  info(message: string): void {
+    if (!this.quiet) {
+      console.log(message);
+    }
+  }
+
+  warn(message: string): void {
+    if (!this.quiet) {
+      console.warn(message);
+    }
+  }
+
+  error(message: string): void {
+    console.error(message);
+  }
+
+  debug(message: string): void {
+    if (this.verbose && !this.quiet) {
+      console.log(message);
+    }
+  }
+}

package/src/core/types.ts

@@ -0,0 +1,77 @@
+export type Category =
+  | "data"
+  | "image"
+  | "video"
+  | "vector"
+  | "document"
+  | "text"
+  | "audio"
+  | "archive"
+  | "spreadsheet"
+  | "presentation"
+  | "font"
+  | "code"
+  | "binary";
+
+export interface FormatDefinition {
+  id: string;
+  name: string;
+  extension: string;
+  extensions: string[];
+  mime: string[];
+  category: Category[];
+  aliases?: string[];
+}
+
+export interface FileFormat {
+  id: string;
+  name: string;
+  extension: string;
+  mime: string;
+  category: Category[];
+  aliases: string[];
+}
+
+export interface PlanOptions {
+  maxCandidates: number;
+  maxSteps: number;
+  strict: boolean;
+}
+
+export interface CliOptions {
+  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;
+}
+
+export interface DoctorCheck {
+  name: string;
+  ok: boolean;
+  detail: string;
+}
+
+export interface CommandResult {
+  ok: boolean;
+  message?: string;
+  data?: unknown;
+  warnings?: string[];
+}
+
+export interface ConvertSummary {
+  ok: boolean;
+  input: string;
+  output: string;
+  route: string[];
+  durationMs: number;
+  warnings: string[];
+}

package/src/diagnostics/doctor.ts

@@ -0,0 +1,43 @@
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import type { BundleResolver } from "../bundle/resolve.ts";
+import type { DoctorCheck } from "../core/types.ts";
+
+async function checkBinary(bundle: BundleResolver, name: string): Promise<DoctorCheck> {
+  const resolved = await bundle.resolveBinary(name);
+  if (!resolved) {
+    return {
+      name,
+      ok: false,
+      detail: "missing",
+    };
+  }
+  return {
+    name,
+    ok: true,
+    detail: resolved,
+  };
+}
+
+export async function runDoctor(bundle: BundleResolver): Promise<DoctorCheck[]> {
+  const checks: DoctorCheck[] = [];
+
+  const manifestPath = join(bundle.assetsDir, "manifest.json");
+  try {
+    await access(manifestPath);
+    checks.push({ name: "bundle-manifest", ok: true, detail: manifestPath });
+  } catch {
+    checks.push({ name: "bundle-manifest", ok: false, detail: `not found at ${manifestPath}` });
+  }
+
+  checks.push(await checkBinary(bundle, "ffmpeg"));
+  checks.push(await checkBinary(bundle, "pandoc"));
+  checks.push(await checkBinary(bundle, "magick"));
+
+  const sevenZip = (await checkBinary(bundle, "7zz")).ok
+    ? await checkBinary(bundle, "7zz")
+    : await checkBinary(bundle, "7z");
+  checks.push({ name: "7zip", ok: sevenZip.ok, detail: sevenZip.detail });
+
+  return checks;
+}

package/src/executor/executor.ts

@@ -0,0 +1,177 @@
+import { copyFile, mkdir, stat } from "node:fs/promises";
+import { dirname, extname, join } from "node:path";
+import type { ArtifactRef } from "../artifacts/artifact.ts";
+import type { BundleResolver } from "../bundle/resolve.ts";
+import { CliError, ExitCode } from "../core/errors.ts";
+import type { Logger } from "../core/logger.ts";
+import type { FileFormat, PlanOptions } from "../core/types.ts";
+import { FormatRegistry } from "../formats/registry.ts";
+import type { HandlerContext, PlannedRoute } from "../handlers/base.ts";
+import { HandlerRegistry } from "../handlers/registry.ts";
+import { DeadEndTracker } from "../planner/deadends.ts";
+import { ConversionGraph } from "../planner/graph.ts";
+import { findRoutes } from "../planner/search.ts";
+import { Workspace } from "./workspace.ts";
+
+export interface EngineInput {
+  inputPath: string;
+  outputPath: string;
+  inputFormat: FileFormat;
+  outputFormat: FileFormat;
+  strict: boolean;
+  keepTemp: boolean;
+  timeoutMs?: number;
+  plan: PlanOptions;
+}
+
+export interface EngineResult {
+  route: PlannedRoute;
+  outputPath: string;
+  durationMs: number;
+  warnings: string[];
+}
+
+export class ConversionEngine {
+  constructor(
+    private readonly formats: FormatRegistry,
+    private readonly handlers: HandlerRegistry,
+    private readonly bundle: BundleResolver,
+    private readonly logger: Logger,
+  ) {}
+
+  private async validateInput(path: string): Promise<void> {
+    try {
+      const fileStat = await stat(path);
+      if (!fileStat.isFile()) {
+        throw new CliError(`Input is not a file: ${path}`, ExitCode.InvalidArgs);
+      }
+    } catch (error) {
+      if (error instanceof CliError) {
+        throw error;
+      }
+      throw new CliError(`Input file not found: ${path}`, ExitCode.InvalidArgs);
+    }
+  }
+
+  async planRoutes(
+    inputFormat: FileFormat,
+    outputFormat: FileFormat,
+    strict: boolean,
+    plan: PlanOptions,
+    timeoutMs?: number,
+  ): Promise<{ workspace: Workspace; routes: PlannedRoute[] }> {
+    const workspace = await Workspace.create();
+    await this.handlers.init({
+      workspace,
+      bundle: this.bundle,
+      logger: this.logger,
+      timeoutMs,
+    });
+
+    const graph = new ConversionGraph(this.formats, this.handlers.availableHandlers(), strict);
+    const routes = findRoutes(graph, inputFormat.id, outputFormat.id, plan);
+    return { workspace, routes };
+  }
+
+  async execute(input: EngineInput): Promise<EngineResult> {
+    const startedAt = Date.now();
+    await this.validateInput(input.inputPath);
+
+    const { workspace, routes } = await this.planRoutes(
+      input.inputFormat,
+      input.outputFormat,
+      input.strict,
+      input.plan,
+      input.timeoutMs,
+    );
+
+    const deadEnds = new DeadEndTracker();
+    const warnings: string[] = [];
+
+    try {
+      if (routes.length === 0) {
+        throw new CliError(
+          `No route found from ${input.inputFormat.id} to ${input.outputFormat.id}`,
+          ExitCode.UnsupportedRoute,
+        );
+      }
+
+      for (const route of routes) {
+        if (deadEnds.routeBlocked(route)) {
+          continue;
+        }
+
+        const routeAttempt = await this.tryRoute(route, input, workspace, warnings);
+        if (routeAttempt.failedPrefix) {
+          deadEnds.markDeadPrefix(routeAttempt.failedPrefix);
+          continue;
+        }
+
+        if (routeAttempt.artifact) {
+          await workspace.cleanup(input.keepTemp);
+          return {
+            route,
+            outputPath: routeAttempt.artifact.path,
+            durationMs: Date.now() - startedAt,
+            warnings,
+          };
+        }
+      }
+
+      throw new CliError("All candidate routes failed", ExitCode.ConversionFailed);
+    } catch (error) {
+      await workspace.cleanup(input.keepTemp);
+      throw error;
+    }
+
+  }
+
+  private async tryRoute(
+    route: PlannedRoute,
+    input: EngineInput,
+    workspace: Workspace,
+    warnings: string[],
+  ): Promise<{ artifact?: ArtifactRef; failedPrefix?: PlannedRoute["edges"] }> {
+    const inputCopy = join(workspace.inputDir, `source${extname(input.inputPath)}`);
+    await copyFile(input.inputPath, inputCopy);
+    let currentArtifact: ArtifactRef = { kind: "file", path: inputCopy };
+
+    const context: HandlerContext = {
+      workspace,
+      bundle: this.bundle,
+      logger: this.logger,
+      timeoutMs: input.timeoutMs,
+    };
+
+    for (let index = 0; index < route.edges.length; index += 1) {
+      const edge = route.edges[index];
+      if (!edge) {
+        return { failedPrefix: route.edges.slice(0, index) };
+      }
+
+      const stepDir = await workspace.ensureStepDir(index);
+      const outputPath = join(stepDir, `output.${edge.to.extension}`);
+      const prefix = route.edges.slice(0, index + 1);
+
+      try {
+        const result = await edge.handler.convert(context, {
+          input: currentArtifact,
+          outputPath,
+          inputFormat: edge.from,
+          outputFormat: edge.to,
+        });
+        currentArtifact = result.output;
+        if (result.warnings && result.warnings.length > 0) {
+          warnings.push(...result.warnings);
+        }
+      } catch (error) {
+        this.logger.debug(`Route failed at step ${index + 1}: ${(error as Error).message}`);
+        return { failedPrefix: prefix };
+      }
+    }
+
+    await mkdir(dirname(input.outputPath), { recursive: true });
+    await copyFile(currentArtifact.path, input.outputPath);
+    return { artifact: { kind: "file", path: input.outputPath } };
+  }
+}

package/src/executor/workspace.ts

@@ -0,0 +1,47 @@
+import { mkdtemp, mkdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export class Workspace {
+  readonly root: string;
+  readonly inputDir: string;
+  readonly stepsDir: string;
+  readonly outputDir: string;
+  readonly logsDir: string;
+
+  private constructor(root: string) {
+    this.root = root;
+    this.inputDir = join(root, "input");
+    this.stepsDir = join(root, "steps");
+    this.outputDir = join(root, "output");
+    this.logsDir = join(root, "logs");
+  }
+
+  static async create(prefix = "convert-"): Promise<Workspace> {
+    const root = await mkdtemp(join(tmpdir(), prefix));
+    const workspace = new Workspace(root);
+    await mkdir(workspace.inputDir, { recursive: true });
+    await mkdir(workspace.stepsDir, { recursive: true });
+    await mkdir(workspace.outputDir, { recursive: true });
+    await mkdir(workspace.logsDir, { recursive: true });
+    return workspace;
+  }
+
+  stepDir(index: number): string {
+    const normalized = String(index + 1).padStart(2, "0");
+    return join(this.stepsDir, normalized);
+  }
+
+  async ensureStepDir(index: number): Promise<string> {
+    const path = this.stepDir(index);
+    await mkdir(path, { recursive: true });
+    return path;
+  }
+
+  async cleanup(keepTemp: boolean): Promise<void> {
+    if (keepTemp) {
+      return;
+    }
+    await rm(this.root, { recursive: true, force: true });
+  }
+}

package/src/formats/aliases.ts

@@ -0,0 +1,8 @@
+export const FORMAT_ALIASES: Record<string, string> = {
+  jpg: "jpeg",
+  jpeg: "jpeg",
+  markdown: "md",
+  yml: "yaml",
+  text: "txt",
+  binary: "bin",
+};

package/src/formats/common.ts

@@ -0,0 +1,69 @@
+import type { Category, FormatDefinition } from "../core/types.ts";
+
+function defineFormat(
+  id: string,
+  name: string,
+  extension: string,
+  mime: string[],
+  category: Category[],
+  aliases: string[] = [],
+): FormatDefinition {
+  return {
+    id,
+    name,
+    extension,
+    extensions: [extension],
+    mime,
+    category,
+    aliases,
+  };
+}
+
+export const COMMON_FORMATS: FormatDefinition[] = [
+  defineFormat("png", "Portable Network Graphics", "png", ["image/png"], ["image"]),
+  defineFormat("jpeg", "JPEG Image", "jpg", ["image/jpeg"], ["image"], ["jpg"]),
+  defineFormat("webp", "WebP Image", "webp", ["image/webp"], ["image"]),
+  defineFormat("gif", "Graphics Interchange Format", "gif", ["image/gif"], ["image", "video"]),
+  defineFormat("bmp", "Bitmap Image", "bmp", ["image/bmp"], ["image"]),
+  defineFormat("tiff", "Tagged Image File Format", "tiff", ["image/tiff"], ["image"], ["tif"]),
+  defineFormat("svg", "Scalable Vector Graphics", "svg", ["image/svg+xml"], ["image", "vector", "document"]),
+
+  defineFormat("wav", "Waveform Audio", "wav", ["audio/wav"], ["audio"]),
+  defineFormat("mp3", "MP3 Audio", "mp3", ["audio/mpeg"], ["audio"]),
+  defineFormat("flac", "FLAC Audio", "flac", ["audio/flac"], ["audio"]),
+  defineFormat("ogg", "Ogg Audio", "ogg", ["audio/ogg"], ["audio"]),
+
+  defineFormat("mp4", "MPEG-4 Video", "mp4", ["video/mp4"], ["video"]),
+  defineFormat("mov", "QuickTime MOV", "mov", ["video/quicktime"], ["video"]),
+  defineFormat("webm", "WebM Video", "webm", ["video/webm"], ["video"]),
+  defineFormat("wmv", "Windows Media Video", "wmv", ["video/x-ms-wmv"], ["video"]),
+
+  defineFormat("txt", "Plain Text", "txt", ["text/plain"], ["text"]),
+  defineFormat("md", "Markdown", "md", ["text/markdown"], ["text", "document"], ["markdown"]),
+  defineFormat("html", "HyperText Markup Language", "html", ["text/html"], ["text", "document"]),
+  defineFormat("json", "JSON", "json", ["application/json"], ["data", "text"]),
+  defineFormat("xml", "XML", "xml", ["application/xml", "text/xml"], ["data", "text"]),
+  defineFormat("yaml", "YAML", "yml", ["application/yaml", "text/yaml"], ["data", "text"], ["yml"]),
+  defineFormat("csv", "Comma Separated Values", "csv", ["text/csv"], ["data", "text"]),
+  defineFormat("css", "Cascading Style Sheets", "css", ["text/css"], ["code", "text"]),
+  defineFormat("sh", "Shell Script", "sh", ["application/x-sh"], ["code", "text"]),
+  defineFormat("py", "Python Script", "py", ["text/x-python"], ["code", "text"]),
+
+  defineFormat("pdf", "Portable Document Format", "pdf", ["application/pdf"], ["document"]),
+  defineFormat("docx", "Word Document", "docx", ["application/vnd.openxmlformats-officedocument.wordprocessingml.document"], ["document"]),
+  defineFormat("xlsx", "Excel Workbook", "xlsx", ["application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"], ["spreadsheet", "document"]),
+  defineFormat("pptx", "PowerPoint Presentation", "pptx", ["application/vnd.openxmlformats-officedocument.presentationml.presentation"], ["presentation", "document"]),
+
+  defineFormat("zip", "ZIP Archive", "zip", ["application/zip"], ["archive"]),
+  defineFormat("tar", "TAR Archive", "tar", ["application/x-tar"], ["archive"]),
+  defineFormat("7z", "7-Zip Archive", "7z", ["application/x-7z-compressed"], ["archive"]),
+
+  defineFormat("ttf", "TrueType Font", "ttf", ["font/ttf"], ["font"]),
+  defineFormat("otf", "OpenType Font", "otf", ["font/otf"], ["font"]),
+  defineFormat("woff", "Web Open Font Format", "woff", ["font/woff"], ["font"]),
+  defineFormat("woff2", "Web Open Font Format 2", "woff2", ["font/woff2"], ["font"]),
+
+  defineFormat("base64", "Base64 Text", "b64", ["text/plain"], ["data", "text"]),
+  defineFormat("hex", "Hex Text", "hex", ["text/plain"], ["data", "text"]),
+  defineFormat("bin", "Binary Blob", "bin", ["application/octet-stream"], ["binary"]),
+];

package/src/formats/detect.ts

@@ -0,0 +1,62 @@
+import { extname } from "node:path";
+import { CliError, ExitCode } from "../core/errors.ts";
+import type { FileFormat } from "../core/types.ts";
+import { FormatRegistry } from "./registry.ts";
+
+export function detectInputFormat(
+  inputPath: string,
+  override: string | undefined,
+  registry: FormatRegistry,
+): FileFormat {
+  if (override) {
+    const format = registry.getById(override);
+    if (!format) {
+      throw new CliError(`Unknown input format: ${override}`, ExitCode.InvalidArgs);
+    }
+    return format;
+  }
+
+  const extension = extname(inputPath).replace(/^\./, "").toLowerCase();
+  if (extension) {
+    const byExtension = registry.getByExtension(extension);
+    if (byExtension) {
+      return byExtension;
+    }
+  }
+
+  const bin = registry.getById("bin");
+  if (!bin) {
+    throw new CliError("Binary fallback format is missing", ExitCode.InternalError);
+  }
+  return bin;
+}
+
+export function resolveOutputFormat(
+  outputPath: string | undefined,
+  override: string | undefined,
+  registry: FormatRegistry,
+): FileFormat {
+  if (override) {
+    const format = registry.getById(override);
+    if (!format) {
+      throw new CliError(`Unknown output format: ${override}`, ExitCode.InvalidArgs);
+    }
+    return format;
+  }
+
+  if (!outputPath) {
+    throw new CliError("Missing output path or --to format", ExitCode.InvalidArgs);
+  }
+
+  const extension = extname(outputPath).replace(/^\./, "").toLowerCase();
+  if (!extension) {
+    throw new CliError("Could not infer output format from path; use --to", ExitCode.InvalidArgs);
+  }
+
+  const byExtension = registry.getByExtension(extension);
+  if (!byExtension) {
+    throw new CliError(`Unsupported output extension: .${extension}`, ExitCode.UnsupportedRoute);
+  }
+
+  return byExtension;
+}