fix: resolve pre-publish blockers, including a broken write command

[sjsyrek]

Summary

Pre-publish hardening for the first public release of @deepl/cli. The headline item is that deepl write did not work at all from a published install — the rest are correctness, security and packaging fixes found while verifying the release surface end to end.

The blocker

diff is a static runtime import in src/cli/commands/write.ts but was declared only under devDependencies, which consumers never install. Reproduced against the packed tarball installed into a clean prefix:

$ deepl write "hello world"
Error: Cannot find package 'diff' imported from .../dist/cli/commands/write.js

The entire DeepL Write feature — one of the two headline capabilities — failed before producing output on every real install. A --help sweep cannot surface this class, because write.js is loaded lazily through service-factory's dynamic import, so the module graph is never resolved until the command actually runs. scripts/check-dependencies.mjs now fails the build on it.

Changes Made

Dependencies and packaging

• diff and @inquirer/prompts declared as runtime dependencies. @inquirer/prompts is imported by init, write --interactive and sync init while only the unused inquirer was declared, so it resolved purely through npm's hoisting: under a strict layout (pnpm, --install-strategy=nested) those commands fail with ERR_MODULE_NOT_FOUND, and under npm the prompt that reads the user's API key binds to whatever major another dependent happens to hoist. Dependency ranges are immutable per published version, so neither is repairable after 2.0.0 ships.
• Source maps no longer emitted. They were already excluded from the tarball, so emitting them only left dangling sourceMappingURL comments in 334 shipped files, giving library consumers unresolvable stack frames.
• SECURITY.md now ships, so offline installs carry the reporting channel. .npmignore removed as dead weight — the files array governs. VERSION removed: nothing read it, and a second hand-edited source of truth could only drift.

Correctness

• deepl init at a non-TTY exits 6 with the documented message instead of starting to prompt and dying with exit 1 plus a Node unsettled top-level await warning. Hit by docker run without -it, CI, and piped invocations. The guard existed in write --interactive but not here, and the only test covered --no-input init — the variant that already worked.
• sync --auto-commit retried after a refusal no longer reports success without committing. A refused run writes its translations to disk first, so the retry finds nothing to translate; the preflight was gated on that and was skipped, leaving exit 0 with no commit, the translation uncommitted and the tree still dirty.
• write --lang/--to accept any casing and normalize to the API's form. They previously required an exact match against a mixed-case list, rejecting the lowercase codes deepl languages prints and translate --to accepts — so the CLI's own output was unusable with the command documented as consistent with translate.
• The shipped bug-report URL pointed at github.com/user/deepl-cli, a live third-party account that could create that repository and receive reports from a DeepL-branded binary.
• Hidden internal commands no longer appear in shell completions or did-you-mean output, and the suggester is alias-aware — deepl tr resolves to translate rather than tm.
• The missing-key remediation survives --quiet. It was emitted as a warning, which quiet mode suppresses entirely; docs/API.md claimed otherwise and is corrected.
• NO_PROXY/no_proxy honoured, with standard semantics. A corporate HTTPS_PROXY was previously applied even to a localhost endpoint.
• auth set-key --no-verify added. Validation ran before persisting, so on a network without proxy configuration both documented setup paths failed and discarded the key; an unreachable API now also names DEEPL_API_KEY as the zero-network alternative.

Security

• The test suite no longer inherits real credentials. Suites that spawn the bare deepl command cannot be intercepted by nock, so they reached the live DeepL API with whatever key was exported and read and wrote the developer's cache database — cached responses matching this suite's fixtures were recovered from a real cache, confirming it had happened. globalSetup now clears DEEPL_API_KEY, TMS_API_KEY and TMS_TOKEN and points DEEPL_CONFIG_DIR at a temp directory. Suite runtime dropped from ~48s to ~28s once the calls stopped.
• ConfigService.save() writes through an unpredictably named temp file created with an exclusive flag. A symlink planted at the fixed config.json.tmp redirected the plaintext API key to a path of the planter's choosing, and the rename left config.json as that symlink for every later write.
• The prototype-pollution guard in the JSON parser is now pinned by tests. Replacing Object.defineProperty with plain assignment previously left the whole suite green: on a fresh object obj['__proto__'] = value retargets that object's prototype rather than Object.prototype, so the translation was silently dropped while the negative assertion still passed.

Release workflow

• npm publishing removed from GitHub. It cannot be triggered from this repository; releases are published from GitLab, which is the source of truth and mirrors to GitHub — the arrangement the other DeepL client libraries use. The publish job is gone along with the environment reference, id-token permission and token wiring, and the homebrew job with it (it declared needs: publish, so leaving it would have made the workflow invalid).
• The tag↔package.json guard was preserved by moving it into the surviving release job rather than deleting it with its former host. A tag can be pushed at any commit, and without the check a mislabelled tag would mint a Release whose title disagrees with the version it contains.
• gh release create is now idempotent, so re-running the workflow does not fail on work that already succeeded.

Test Coverage

269 suites / 6096 tests, all green. Lint, type-check and check-deps clean; production npm audit reports 0.

Three new gates, each verified to actually fail rather than merely pass:

• scripts/check-dependencies.mjs — flags a runtime import missing from dependencies. Compares against dependencies alone, which is what catches a runtime import misfiled under devDependencies. Correctly does not flag php-parser, which is reached indirectly via requireModule.
• tests/unit/docs/documented-surface.test.ts — checks every documented deepl … invocation in the README and docs against the CLI's real surface, read from the hidden _describe command. Verified it fails on both an unknown command and an unknown flag.
• tests/require-build.ts — now rejects a stale dist/ by mtime, not just a missing one. It caught a genuinely stale build during this work, reducing thousands of misleading failures to one clear message.

Also added: 50 expect.assertions guards on tests that assert only inside a catch and so passed with zero assertions whenever the command unexpectedly succeeded. Efficacy proven by making a guarded command stop failing and confirming the test turns red. Those guards are what surfaced the sync --auto-commit bug above, along with an assertion that could never have matched (/detached HEAD/i against a message reading "HEAD is detached").

Verified from a tarball installed into a clean prefix with no credentials: deepl --version reports the tree's version; write and translate exit 2 on a missing key; init < /dev/null exits 6; an invalid language exits 6; a lowercase language code is accepted; --no-verify stores a key offline with config.json at mode 0600; a module-resolution sweep across 18 command action paths is clean; and npm pack yields 340 files / 213 kB with README, LICENSE and SECURITY.md present and no maps or test files.

Backward Compatibility

✅ No breaking changes. Additive only — auth set-key --no-verify, NO_PROXY support. write --lang now accepts more casings than before rather than fewer.

✅ Removals have no runtime effect — VERSION and .npmignore were unread and inert respectively; CLAUDE.md's release procedure is updated to use npm version.

⚠️ One intentional behaviour change: sync --auto-commit now reports the refusal on every attempt rather than silently succeeding on a retry. Publishing also no longer happens on a tag push, by design.

Size: Large ✓

62 files, ~1000 insertions. The risk concentrates in two one-line manifest changes and a handful of guards, each verified against a real tarball install rather than only in-tree.

🤖 Generated with Claude Code

[sjsyrek]

Update: a second real bug, found by the assertion guards

b8502be adds a fix that was not in the original scope, because the expect.assertions guards surfaced it.

Retrying deepl sync --auto-commit after a refusal reported success without committing. Reproduced directly:

CALL1 threw: ValidationError  "Refusing to auto-commit: ... README.md (M), src.ts"
de.json on disk after call 1: true
CALL2 threw: NOTHING    fileResults.length: 0    success: true
HEAD after both calls: initial        still dirty: 4 entries

A refused run writes its translations to disk before the preflight, so the retry finds nothing to translate. The preflight was gated on result.fileResults.length > 0, so it was skipped entirely and run() resolved — exit 0, no commit, translation left uncommitted, tree still dirty, no error. Same false-green class as a --locale defect fixed earlier in this release.

Fix: the repo-state checks now run whenever --auto-commit is requested; staging and committing are still skipped when there is nothing to commit. After the fix CALL2 throws.

Two tests covered this path and could not see it — their assertions sat inside a catch the retry never entered. Declaring the counts made them fail, which in turn exposed a third defect: the detached-HEAD test asserted /detached HEAD/i against a message reading "HEAD is detached". Reversed word order, so it could never have matched, dead since it was written. Both fixed, plus a new test for the retry itself.

One existing unit test (should not call git when fileResults is empty) encoded the old contract and now asserts the intended one: preflight runs, staging and commit do not.

Deliberately not changed here: the watch path (sync-command.ts:387) keeps the same gate. It is materially less severe — runOnce() catches the throw and logs it via Logger.error, the watcher continues, and no exit code implies success — and naively removing it would log a refusal on nearly every trigger, since a dirty tree is the normal state while editing. Filed as a follow-up issue with three candidate fixes, including the deeper one (make expectedStaged aware of configured target paths) that would also remove the manual-intervention dead end in the one-shot path.

269 suites / 6096 tests green; lint, type-check, check-deps clean; CI green on this commit.

[sjsyrek]

Update: npm publishing removed from GitHub (d180349)

Publishing to npm cannot be triggered from GitHub for this repository. Releases will be published from GitLab, which becomes the source of truth and mirrors to GitHub — the arrangement the rest of the DeepL client-library fleet already uses. deepl-node publishes from a .gitlab-ci.yml job and has its GitHub publish step commented out with the note "Test and npm publish stage are disabled for now."

Removed from .github/workflows/release.yml:

• the publish job in full — npm-publish environment, id-token: write, NPM_TOKEN wiring and --provenance
• the homebrew job — not optional cleanup, since it declared needs: publish and would have made the workflow invalid. Its formula-bump logic is preserved as a comment on the tap issue.

Preserved rather than deleted: the tag↔package.json guard, moved into the surviving release job. It lived inside publish, so deleting that job would have silently taken the guard with it — and it still catches a mislabelled tag minting a Release whose title disagrees with its contents.

What a tag push does now: creates the GitHub Release, and nothing else. Verified no NPM_TOKEN exists at either repo or environment scope, and ci.yml/security.yml both filter on branches: [main], so neither fires on a tag.

Provenance is dropped, and this is worth stating plainly: npm --provenance needs a CI with OIDC and cannot be produced from a laptop. That puts @deepl/cli at parity with the fleet rather than behind it — npm view deepl-node dist.attestations returns nothing for 1.27.0. It can return once GitLab publishes, since npm supports GitLab CI for trusted publishing.

Three [Unreleased] changelog entries describing GitHub-side publishing, provenance and the required-reviewer gate are reworded; they would otherwise have shipped as false claims in the 2.0.0 notes.

Suite green (the one suite failure in my local run was the known Node 24 V8 SIGSEGV worker flake — 0 tests failed, and it passes in isolation).