euni-commands-guide

name: euni-commands-guide description: English runbook for euni command usage in local development and CI, including exit-code and UG-code troubleshooting.

euni Commands (English)

Operational playbook for excel-unidiff-cli (euni). Goal: decide quickly which command to run, in what order, and how to interpret results.

Command Map

• euni init-policy
  • Create .euni.yml template in --repo.
• euni check
  • Non-destructive check for policy drift + Unicode findings on tracked files.
• euni apply
  • Apply policy drift fixes via git config --local only.
  • Use --dry-run before writing.
  • Use --repair-unicode-deletes to restore staged/worktree deleted tracked paths in core.precomposeunicode=false mode.
  • The repair keeps staged non-delete changes (worktree-only delete is restored with git restore --worktree).
  • Caution: this restores deleted tracked paths in scope; do not use when deletions are intentional.
• euni doctor
  • Combined diagnosis (check + scan-like Unicode analysis).
• euni scan
  • Unicode path analysis on tracked + untracked files (no policy input).
• euni version
  • Print euni <version> (<commit>).

Core Rules

• Subcommand required; no standalone help command.
• --recursive default is false (root repo only).
• Write operations are only apply and init-policy.
• scan does not accept --policy.
• version accepts no options.
• --format is text or json only.

Recommended Flows

1) First-time setup

euni init-policy --repo .
euni check --repo . --recursive --policy ./.euni.yml

2) Drift remediation loop

euni apply --repo . --recursive --policy ./.euni.yml --dry-run
euni apply --repo . --recursive --policy ./.euni.yml
euni check --repo . --recursive --policy ./.euni.yml

3) Unicode phantom delete repair (one command)

euni apply --repo . --recursive --policy ./.euni.yml --repair-unicode-deletes

4) Hard-case diagnosis

euni doctor --repo . --recursive --policy ./.euni.yml
euni scan --repo . --recursive --format json

CI Recipe (Deterministic Gate)

euni check \
  --repo . \
  --recursive \
  --policy ./.euni.yml \
  --non-interactive \
  --format json > euni-report.json

Gate expectations:

• Validate against schema/euni-report.schema.json.
• Ensure process exit code matches report.exitCode.
• Treat exit 1 as findings (operational failure), exit 2 as execution/runtime failure.
• Upload euni-report.json as artifact.

JSON contract:

• stdout: exactly one JSON object.
• stderr: logs/progress/error details.

Exit Codes

• 0: no findings, no errors.
• 1: findings present.
• 2: execution error.

Precedence: if any execution error exists, exit is 2.

UG Code Triage (Quick)

Common findings (exit 1):

• UG004: config drift detected.
• UG005: NFC collision detected.
• UG011: combining mark in path.
• UG012: non-standard FS entry (symlink/reparse/mount).
• UG013: ambiguous policy path key (case-only collision).
• UG014: unicode delete repair signal (dry-run plan or runtime safety skip).

Common execution errors (exit 2):

• UG001: invalid/inaccessible --repo.
• UG002: git command/runtime failure.
• UG003: policy load failure.
• UG006: submodule uninitialized/inaccessible.
• UG007: invalid policy structure/unsupported keys.
• UG008: .euni.yml exists without --force.
• UG009: unsupported command/option usage.
• UG010: gitdir/top-level outside --repo boundary.

Local Source Run Note

When running via go run, non-zero app exits may appear as process exit 1 (Go tool wrapper behavior). For strict 0/1/2 contract checks, build and run the binary directly:

go build -o ./bin/euni ./cmd/euni
./bin/euni check --repo . --policy ./.euni.yml
echo $?