Imported from iancarlos335/line-endings-converter (AGENTS.md). Install upstream with npx skills add iancarlos335/line-endings-converter. Copyright stays with the author.

Agent Guidelines — line-endings-converter

What this project is

A TypeScript CLI tool (lecvt) that converts line endings (LF/CRLF) on files changed from the default git branch. Distributed as an npm global package.

Build & test

npm run build   # tsc → dist/
npm test        # vitest run (all tests)

Always run both before marking work complete. The dist/ output is what the lecvt binary actually executes — source changes alone won't take effect.

Source layout

src/
  index.ts        # entry point: orchestrates everything, formats output
  cli.ts          # argument parsing via commander
  git.ts          # branch auto-detection, getChangedFiles
  lineEndings.ts  # isBinary, detectLineEnding, convertLineEnding
tests/
  lineEndings.test.ts   # unit tests for lineEndings.ts
  git.test.ts           # unit tests for git.ts (uses tmp git repos)
  integration.test.ts   # end-to-end flow in a real tmp git repo
skill/
  SKILL.md        # agentskills.io skill — when/how to use lecvt
scripts/
  install.sh      # POSIX installer (Claude Code, Codex, agentskills, Antigravity)
  install.ps1     # PowerShell installer (same targets, Windows paths)

Key design decisions

• Dry-run is the default. --write must be explicitly passed to mutate files. Do not change this default.
• Binary skip heuristic: null byte anywhere in the first 8 KB of a file → skip. Lives in isBinary() in lineEndings.ts. Don't over-engineer this.
• Base branch auto-detection order: main → master → origin/HEAD remote show. If none resolves, hard error with a message telling the user to use --base.
• mixed line endings convert to the target — they are not treated as "already correct" for either LF or CRLF.
• No partial writes. If a file read or write fails, it's recorded as an error in the results and the exit code is 1, but other files still process.

Code style

• TypeScript strict mode. Avoid any; use typed errors via (err as Error).message.
• No comments unless the reason is non-obvious. Names should be self-explanatory.
• No new abstractions unless a feature genuinely requires them.
• Prefer fs.readFileSync / fs.writeFileSync for file I/O (the tool is inherently synchronous in its per-file loop).

Testing guidelines

• Unit tests for pure functions in lineEndings.ts and git.ts belong in their respective test files.
• Integration tests in integration.test.ts spin up real tmp git repos with execSync — keep this pattern, do not mock git.
• Tests must be idempotent and clean up after themselves (afterAll removes tmp dirs).

Skill directory

skill/ contains the lecvt AI agent skill (agentskills.io convention). It is distribution-only — not part of the build or test pipeline.

• skill/ contains only the distributable artifact (SKILL.md). Do not add scripts or tooling there.
• scripts/ contains the installers. They resolve ../skill/SKILL.md relative to their own location — keep this path correct if either directory is renamed.
• Do not import or reference anything from skill/ or scripts/ in src/.
• Do not run the install scripts as part of npm test or npm run build.
• If you edit skill/SKILL.md, keep the frontmatter valid: name must be lecvt, description must start with Use when, no workflow summary in the description field.

What NOT to do

• Do not add a config file, .lecvtrc, or any project-level configuration — the CLI flags are sufficient.
• Do not add streaming or watch mode; this tool is a one-shot converter.
• Do not modify line endings in files that were not changed relative to the base branch.