Skip to content

refactor: unify CLI to macdoc convert --to pattern (textutil-compatible) #27

Description

@kiki830621

Summary

Migrate all conversion subcommands to a unified macdoc convert --to <format> entry point, following macOS textutil -convert <fmt> patterns.

Current State

macdoc word to-md file.docx
macdoc html to-md file.html
macdoc md to-html file.md
macdoc srt to-html file.srt
macdoc bib to-html file.bib
macdoc bib to-md file.bib
macdoc bib to-json file.bib

Each source format is a separate subcommand with its own to-* children.

Target State

macdoc convert --to md file.docx
macdoc convert --to md file.html
macdoc convert --to html file.md
macdoc convert --to html file.srt
macdoc convert --to html file.bib --style apa
macdoc convert --to md file.bib --style apa
macdoc convert --to json file.bib --style apa
macdoc convert --to tokens file.md

Design Principles (from .claude/rules/cli-textutil-compat.md)

  • Action first: convert --to <format>
  • File last: always the trailing argument
  • Auto-detect input format from file extension (.docx → Word, .html → HTML, .bib → BibLaTeX, etc.)
  • Long flags: --to, --output, --style (swift-argument-parser convention)
  • Non-conversion subcommands unchanged: pdf init/status/..., config ai detect/...

Routing Logic

Input extension --to Package
.docx md word-to-md-swift
.html md html-to-md-swift
.md html md-to-html-swift
.srt html srt-to-html-swift
.bib + --style apa html bib-apa-to-html-swift
.bib + --style apa md bib-apa-to-md-swift
.bib + --style apa json bib-apa-to-json-swift
any text tokens token-counter-swift (issue #20)

Backward Compatibility

Old subcommands (word to-md, html to-md, etc.) kept as aliases during migration, with deprecation warning. Remove in next major version.

Options

macdoc convert --to <format> [options] <file>

Options:
  --to <format>       Target format (md, html, json, latex, tokens)
  --output <path>     Output file path (default: stdout or same dir with new extension)
  --stdout            Force output to stdout
  --style <style>     Citation/formatting style (e.g. apa) — for bib conversions
  --model <model>     Model for token counting (gpt-4o, claude-sonnet)
  --hard-breaks       Treat soft breaks as hard breaks (md→html)
  --full              Output full HTML document instead of fragment

References

  • .claude/rules/cli-textutil-compat.md
  • macOS textutil -convert syntax
  • swift-argument-parser conventions

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions