Skip to content

docs: stop instructing readers to npm install the unpublished package#70

Open
maa-xx wants to merge 1 commit into
DeepLcom:mainfrom
maa-xx:docs/remove-speculative-npm-install
Open

docs: stop instructing readers to npm install the unpublished package#70
maa-xx wants to merge 1 commit into
DeepLcom:mainfrom
maa-xx:docs/remove-speculative-npm-install

Conversation

@maa-xx
Copy link
Copy Markdown

@maa-xx maa-xx commented May 15, 2026

Summary

The README, docs/SYNC.md, and several examples/*.sh CI snippets currently tell readers to run npm install -g deepl-cli, but no package exists under that name on the public npm registry. That has two practical problems:

  • Following the instructions doesn't work today. Anyone copy-pasting the CI snippets gets 404 Not Found from the registry.
  • It primes the project for a supply-chain footgun. As long as the docs name deepl-cli as the install target, a third party who registers something under or adjacent to that name on the public registry can serve code to anyone who follows the docs. (The README's > CI examples below ... assume a published npm package; source-installed users should substitute the source-install path caveat is easy to miss in the middle of a quickstart.)

This PR is docs-only. It replaces the speculative npm install -g deepl-cli invocations with the source-install path that already works (git clone … && npm ci && npm run build && npm link) so the examples run today, and rewrites the README's From npm section to be explicit about the current state plus a short security note about not running the speculative npm install against the public registry until an official (ideally scoped, e.g. @deepl/cli) package is published.

Files changed

  • README.md — rewrite the From npm (not yet published) section; add a security note.
  • docs/SYNC.md — replace npm install -g deepl-cli in all three CI YAML snippets (GitHub Actions check, GitHub Actions auto-sync, GitLab CI) with the source install.
  • examples/18-cicd-integration.sh, examples/31-sync-ci.sh — same replacement in the heredoc YAML they print.
  • examples/README.md — point readers at the From Source section instead of the speculative npm command.
  • examples/05-document-translation.sh, examples/12-cost-transparency.sh — these were translating fixture text that happened to read npm install -g deepl-cli; swapped to neutral wording so the repo contains no copy-pasteable speculative install line.

Follow-ups out of scope here

  • Publishing an official scoped package (e.g. @deepl/cli) and switching the docs back to npm install -g @deepl/cli.
  • Adding a prepare script to package.json so npm install -g github:DeepLcom/deepl-cli would Just Work and the CI snippets could collapse to a single line. Left out of this PR to keep it docs-only.

Test plan

  • grep -rn "npm install.*deepl-cli" --include='*.md' --include='*.sh' --include='*.yml' --include='*.yaml' returns only the two intentional mentions in README.md (the future-state sentence and the security warning).
  • The new install snippet runs end-to-end on a clean Ubuntu image: git clone --depth 1 https://github.com/DeepLcom/deepl-cli.git /tmp/deepl-cli && cd /tmp/deepl-cli && npm ci && npm run build && npm link && deepl --version.
  • Render the README and docs/SYNC.md on GitHub and confirm the rewritten sections are readable and the CI YAML still parses.

The README, SYNC docs, and example CI scripts told readers to run
`npm install -g deepl-cli`, but no package exists under that name on
the public npm registry. Following those instructions today would
either fail or — if a third party publishes under that name first —
install untrusted code. Replace the speculative install commands with
the actual working path (install from source via `git clone … && npm
ci && npm run build && npm link`) and add a security note in the
README explaining the situation until an official scoped package is
published.

No code changes; docs and example shell scripts only.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant