document-comparison Shared Rust Project

This is the generated shared Rust project for document-comparison.

Layout

• src/lib.rs: shared domain logic and CLI implementation
• src/main.rs: executable entrypoint

Included Commands

• find-duplicates [OPTIONS] <DOC> <DOC>...
• auth login --json
• auth status --json
• auth logout --json
• auth complete-demo --json

Public CLI Contract

• The public Rust CLI contract for document-comparison is limited to the commands listed in Included Commands.
• The npm wrapper forwards user-provided arguments to the Rust binary by default.
• When the bundled helper is present, the npm wrapper also exposes a wrapper-level convert-doc command and merges that command into top-level --help.
• In other words, document-comparison ... exposes the Rust CLI commands above directly, plus the wrapper-level convert-doc shortcut when the helper is bundled.

Duplicate Detection Command

• Inspect the real business command surface:

document-comparison find-duplicates --help

• Compare multiple DOCX files and generate an HTML report by default:

document-comparison find-duplicates file-a.docx file-b.docx file-c.docx

• Write JSON instead:

document-comparison find-duplicates --json-out result.json file-a.docx file-b.docx

• Compare text only with the precise mode:

document-comparison find-duplicates --text-only --text-compare-mode precise file-a.docx file-b.docx

• Compare files and also write an HTML pair report:

document-comparison find-duplicates --html-out report.html file-a.docx file-b.docx

• The command writes exactly one output artifact per run: HTML or JSON.

• When neither --html-out nor --json-out is provided, it defaults to HTML and auto-generates a report path.

• Output artifacts do not embed image base64 payloads; HTML reports prefer relative media image paths and fall back to file:///... when needed, while JSON keeps metadata such as img_path and img_phash.

• After writing the artifact, the CLI prints:

  • OUTPUT_FORMAT: <html|json>
  • OUTPUT_PATH: <absolute-path>

• Compare images only:

document-comparison find-duplicates --images-only file-a.docx file-b.docx

Bundled Helper Binary

• legacy-doc-converter is still not part of the public Rust CLI contract for document-comparison.
• The npm wrapper bundles it as a helper binary for the TypeScript-side document normalization flow and also re-exports it through the wrapper-level convert-doc command.
• The converter-specific build profiles and feature combinations are documented under ../../Converter/README.md.
• The wrapper locates that helper through LEGACY_DOC_CONVERTER_BIN, and internal code paths such as doc-auto-converter.ts call it directly.
• document-comparison --help includes the wrapper-level convert-doc entry, and document-comparison convert-doc --help shows the helper usage.

Wrapper Command Examples

• Inspect the merged public help surface:

document-comparison --help

• Inspect the bundled document conversion helper usage:

document-comparison convert-doc --help

• Convert a legacy .doc file into .docx:

document-comparison convert-doc input.doc output.docx --force

• Convert a .docx file into PDF through the same helper entry when the helper was built with the full or docx-render profile:

document-comparison convert-doc input.docx output.pdf --force

• If the wrapper receives a .doc during internal normalization, it can call the same bundled helper automatically without requiring the user to invoke convert-doc manually.

Development Notes

• auth login --json prints a plain browser URL first so WorkBuddy can extract it.
• auth complete-demo --json is a local development helper that simulates the browser callback.
• This directory is now the shared Rust project plus local Node-based test dependencies. npm publish assets are generated transiently by skillforge, not stored here long-term.
• npm install still runs patch-package so the local docx4js compatibility patch under patches/ is applied for TypeScript-side comparison runs.

npm Packaging

• npm run build:native: delegate to skillforge build-native --path ..
• npm run setup:wsl:darwin: delegate to skillforge setup-wsl-darwin --path ..
• npm run collect:native: delegate to skillforge collect-native --path ..
• npm run prepare:npm: rebuild the selected Rust binaries, then stage a publishable npm package into ../.skillforge/npm-package/
• npm run pack:npm: rebuild the selected Rust binaries, stage the package, and generate a .tgz tarball via skillforge pack-npm
• npm run publish:npm: rebuild the selected Rust binaries, stage the package, and publish it via skillforge publish-npm

skillforge prepare-npm now stages a lightweight main package under .skillforge/npm-package/main/ and one runtime package per target under .skillforge/npm-package/runtimes/<os>-<arch>/. The staged package launcher resolves the native executable from npm-cli/runtime/<os>-<arch>/native/, and the main package downloads only the current runtime package during postinstall. The TypeScript-side legacy Word normalization flow resolves the bundled legacy-doc-converter helper from ../../Converter/artifacts/<rid>/ by default, and also supports overriding the path with LEGACY_DOC_CONVERTER_BIN. shared-lib does not build the helper itself; prepare the Converter artifacts ahead of packaging. When skillforge prepare-npm sees matching Converter/artifacts/<rid>/legacy-doc-converter* outputs, it vendors them into the matching runtime package under vendor/legacy-doc-converter/, injects LEGACY_DOC_CONVERTER_BIN, and enables the wrapper-level convert-doc command automatically. By default, the packaging flow assumes the helper was built with the default Converter configuration unless you intentionally replace the artifacts with another build. By default, prepare:npm expects these targets before packaging:

• win32-x64 -> target/x86_64-pc-windows-msvc/release/document-comparison.exe
• linux-x64 -> target/x86_64-unknown-linux-gnu/release/document-comparison
• darwin-x64 -> target/x86_64-apple-darwin/release/document-comparison
• darwin-arm64 -> target/aarch64-apple-darwin/release/document-comparison

Use NPM_PACKAGE_TARGETS=win32-x64,linux-x64,... to package a subset while iterating locally. Use --skip-native-build only when you intentionally want to reuse binaries already present under target/<rust-target>/release/.

Local Multi-Platform Workflow

Option A: Build locally where possible

On Windows, npm run build:native defaults to:

• win32-x64 via normal cargo build
• linux-x64 via cargo zigbuild

Before using Linux cross compilation on Windows, install:

cargo install cargo-zigbuild

and make sure zig is available in PATH.

On Linux, npm run build:native defaults to linux-x64. To also build win32-x64 from Linux, skillforge build-native uses cargo xwin build automatically. Install the Windows cross tool first:

cargo install cargo-xwin
rustup target add x86_64-pc-windows-msvc

Then build the Linux and Windows artifacts together:

export BUILD_NATIVE_TARGETS="win32-x64,linux-x64"
npm run build:native

For macOS targets (darwin-x64, darwin-arm64), Linux can now build directly through local osxcross. The same bootstrap script used by Windows+WSL is reused on Linux, but it runs locally instead of forwarding through wsl.exe. When you target Darwin from Linux, skillforge build-native prepares the local toolchain automatically if needed.

Linux needs these pieces before Darwin builds can work:

• Rust toolchain (cargo, rustup)
• o64-clang for darwin-x64
• oa64-clang for darwin-arm64
• Apple SDK wired into osxcross

You can bootstrap only the Darwin toolchain first from Linux:

cargo run --manifest-path ../../Cargo.toml -p skillforge -- setup-wsl-darwin --path ..

Then build all Linux, Windows, and Darwin artifacts together:

export BUILD_NATIVE_TARGETS="win32-x64,linux-x64,darwin-x64,darwin-arm64"
npm run build:native

If you want to override the defaults and publish only a subset, restrict the package targets explicitly:

export NPM_PACKAGE_TARGETS="win32-x64,linux-x64"
cargo run -- release-npm -n document-comparison

For macOS targets (darwin-x64, darwin-arm64), you can build from Windows through WSL. The build is forwarded to the selected WSL distro. In practice, the Darwin toolchain is prepared inside WSL, while Windows only provides the wrapper command. WSL is where cargo, rustup, osxcross, and the Apple SDK must exist. When you run npm run build:native for a Darwin target, the script now bootstraps the WSL-side dependencies automatically before building.

By default, the script uses the Ubuntu distro. You can override it:

$env:BUILD_NATIVE_WSL_DISTRO="Ubuntu"
$env:BUILD_NATIVE_TARGETS="darwin-x64,darwin-arm64"
npm run build:native

WSL needs these pieces before Darwin builds can work:

• Rust toolchain inside WSL (cargo, rustup)
• o64-clang for darwin-x64
• oa64-clang for darwin-arm64
• Apple SDK wired into osxcross

You can still bootstrap only the WSL Darwin toolchain from Windows:

npm run setup:wsl:darwin

If no Apple SDK tarball is found, the setup script stops after preparing Rust, apt packages, and the osxcross source tree. Then place an SDK tarball such as MacOSX13.3.sdk.tar.xz under C:\Users\admin\Downloads\ and rerun the same command.

The setup script can also consume Apple-source archives directly from C:\Users\admin\Downloads\:

• Xcode*.xip
• Command_Line_Tools*.dmg
• MacOSX*.sdk.tar.xz

When one of these files is present, the WSL bootstrap will try to generate the SDK package automatically before building osxcross.

If you prefer to work directly from the shared CLI entry, run:

cargo run --manifest-path ../../Cargo.toml -p skillforge -- setup-wsl-darwin --path ..

You can restrict the build set:

$env:BUILD_NATIVE_TARGETS="win32-x64,linux-x64"
npm run build:native

Option B: Collect binaries built elsewhere

1. Build the current host binary with cargo build --release
2. Put binaries built on other machines into npm-artifacts/ using either layout:
   • npm-artifacts/win32-x64/document-comparison.exe
   • npm-artifacts/linux-x64/document-comparison
   • npm-artifacts/darwin-x64/document-comparison
   • npm-artifacts/darwin-arm64/document-comparison
3. Run npm run collect:native
4. Run npm run prepare:npm or npm run publish:npm

You can also pass a custom source directory:

$env:NATIVE_ARTIFACTS_DIR="D:\artifacts\document-comparison"
npm run collect:native