Skip to content

Commit 8ed20ee

Browse files
feat(npm): make @deepgram/cli the real Deepgram CLI (#146)
## Why `@deepgram/cli` on npm is the obvious name for "the Deepgram CLI", and it's broken: - `npm i @deepgram/cli` fails with `notarget`. The only versions are two old betas (`0.3.0-beta.0`, `0.4.0-beta.0`) from `lukeocodes/deepgram-cli`. - `npm i @deepgram/cli@0.4.0-beta.0` installs, then crashes on start: `MODULE_NOT_FOUND …/src/hooks/init/log`. Coding agents try npm first. In our build-journey evals, agents asked to "use the Deepgram CLI" went to `@deepgram/cli`, hit both failures, and gave up on the CLI. This PR makes `@deepgram/cli` the real CLI. ## What it does **New `npm/` package.** `@deepgram/cli` has no dependencies and no install scripts. It provides `dg` and `deepgram`, and runs the Python `deepctl` at the **same version as the npm package**: 1. A cached private venv (`~/.cache/deepgram-cli/venvs/<V>`) if one is already built. This is fast and works offline. 2. Otherwise, with uv present, a venv built with `uv pip install --require-hashes --no-deps --only-binary :all:` against the hash-pinned `requirements-<V>.txt` the package ships. No local Python is needed. 3. Otherwise, a Python 3.10+ with `venv` builds the same hash-checked venv the same way, in place under a lock. All bootstrap output goes to stderr, so `dg -o json` and `dg mcp` stdout stay clean on the first run. 4. Otherwise, a clear error with the three fixes: install uv, install `python3-venv`, or use `install.sh`/brew. `DEEPCTL_NPM_RUNNER=uvx|venv|path` forces a strategy. `path` uses a `deepctl` already on PATH, and only when asked. **Python side.** `InstallMethod.NPM` is detected through `DEEPCTL_LAUNCHER`, which `deepctl_core._launcher` reads once and removes from the environment so it doesn't leak to child processes. With it: - `dg update` and the update banner tell npm and npx users the npm command. - Plugins go into the isolated plugin venv, so they survive npm version bumps. - The skills prompt says `dg`. **Release.** - release-please bumps `npm/package.json` along with the root package (`extra-files`). - A new `publish-npm` job runs after `verify-published`, so npm never points at a version PyPI can't install. - It uses npm trusted publishing (OIDC, environment `npm-publish`, npm pinned to 11.21.0) and sets provenance. - It's safe to re-run: it skips a version that's already published, and it fails closed if the dist-tag lookup errors. - If the version is lower than the current `latest`, it publishes under `v<maj>.<min>-maint` instead of moving `latest`. - Recovery is "Re-run failed jobs". **CI.** Three new jobs, added to `all-checks`: - `launcher` (Linux, macOS, Windows): Node unit tests, `cmp LICENSE npm/LICENSE`, and a check that stdin stays blocking for deepctl. - `launcher-node` (Linux): Node unit tests on every version `package.json`'s `engines` admits (20.0.0, 20, 22, 24). - `launcher-hashed` (Windows, macOS): the release path end to end against a local package index — builds this commit's packages, writes the hash-locked `requirements-<V>.txt`, and runs the launcher through both uv and the pip fallback. - A `release-bump-gate` status (`scripts/check_release_bumps.py`) fails the build if a package's shipped code changed since its last release tag without a version bump — the drift that would otherwise let a sibling package ship against a `deepctl-core` PyPI hasn't released yet. It runs again before publish with the same check. **Docs.** npm/npx install lines in `README.md` and `web/src/data/llms-full.txt`. The latter also fixes the `deepgram/tap/deepctl` → `deepgram/tap/deepgram` typo. The first npm version will be **0.4.1**, from the next release PR. `0.4.1` is newer than `0.4.0-beta.0`, so `latest` moves and plain `npm i @deepgram/cli` works. ## Hardening This went through five rounds of independent review, each followed by a fix round. Every finding was reproduced in Docker before it was fixed, and each fix was checked against its repro. Highlights: **Cache security.** - Every cache ancestor must be owned by you or root. - Group/other-writable ancestors must be sticky. - Group-write is never trusted, even for a user-private group (`gid == uid`); a shared-group cache falls back to a private temp dir. - The `/tmp` fallback is `0700` and owner-checked. These checks block another user from planting or swapping a cached venv. Tested by pre-creating the cache, with a symlink, and with a 150-iteration swap loop. **Locking.** - `mkdir` lock with owner, pid and host. - A lock is stale when its pid is dead, it's older than 60 min, or it was taken by our own pid after a pid reuse. - Stale locks are renamed aside and their owner verified before deletion. - Release is ownership-checked. **Signals and stdio.** - SIGTERM and SIGHUP are forwarded. - With a terminal attached, SIGINT and SIGQUIT come from the process group, so each Ctrl-C reaches deepctl exactly once and cancel still exits 2. - With no terminal (IDEs, agent hosts), a SIGINT sent only to the launcher is forwarded after 1s. - The launcher never constructs a Node std stream. That stream would put the inherited stdin into non-blocking mode and break `dg mcp` over stdio, `ffmpeg | dg listen`, and similar pipes. - Launcher messages to stderr are best effort, so a full or closed stderr can't break a run. **Self-repair and pruning.** - A venv whose base Python was removed gets rebuilt. - Old version venvs are pruned only after 30 days unused, and never while locked or in use. ## Testing **Docker** (linux/arm64; the uvx, venv, signal and stdin cases also on amd64): 43/43 cases pass. They cover: - no Python; - uv only; - Python 3.12 venv: cold, warm, and offline warm and cold; - Debian with and without `python3-venv` (PEP 668); - Python 3.9 rejected; - Alpine/musl; - two concurrent first runs; - SIGTERM, SIGINT and SIGHUP, with and without a TTY; - unwritable HOME and an arbitrary uid; - OpenShift-style uid with gid 0; - shared primary group; - the npx and npm labels; - `npx ./tgz`; - clean JSON stdout on a cold cache; - an MCP `initialize` sent 1s late. **Unit and lint:** - Node: 111/111 on Node 20, 22 and 24 (the `engines` floor). - Python: 2280 passed, 12 skipped in Docker as root; 2283 passed, 9 skipped as a non-root user (three permission tests skip under root). - ruff, mypy, `check_dependency_floors.py` and actionlint are clean. - The `test_release_bumps.py` tests that read this repository's git history now skip when git or a git checkout isn't available, instead of failing with `FileNotFoundError`. CI has both, so they still run there. - The `pip install` steps in `release.yml` and the `release-bump-gate` job are pinned to the versions in `uv.lock` (`build==1.5.0`, `twine==7.0.0`, `packaging==26.3`). **Not yet run:** real macOS and Windows runs, which the new `launcher` job does on this PR, and the `publish-npm` job, which runs on the first release now that the owner setup below is in place. ## Before the first release, owner steps (done 2026-10-23) - [x] Trusted publisher on `@deepgram/cli` (set as `deepgramai`): GitHub Actions, repo `deepgram/cli`, workflow `release.yml`, environment `npm-publish`, permission **publish**. Note for anyone redoing this: npm now separates `publish` from `stage publish`; the first attempt from the web UI granted only `stage publish`, which a plain `npm publish` is rejected under, so it was revoked and re-added with `npm trust github @deepgram/cli --repo deepgram/cli --file release.yml --env npm-publish --allow-publish`. Verify with `npm trust list @deepgram/cli`. - [x] GitHub environment **`npm-publish`** created on this repo, deployment branches limited to `main`, no required reviewer. - [x] Both 2023 betas carry a deprecation message pointing at the new install: `Unsupported 2023 beta. Install the Deepgram CLI with: npm i -g @deepgram/cli@latest (0.4.1 or newer)`. (npm Support had deprecated them on 2026-09-11 with its generic "no longer supported" text; the flag is per version and does not block publishing.) - [ ] After 0.4.1 publishes: confirm `npm view @deepgram/cli dist-tags.latest` is `0.4.1`, then turn on "Require 2FA and disallow tokens" for the package. Until the first publish, `npx @deepgram/cli` still runs the old 2023 beta (now with the pointer message), so the README line goes live slightly ahead of the package. ## Floors `deepctl-cmd-update` and `deepctl-cmd-skills` already declare `deepctl-core>=0.3.0` on this branch, and `deepctl-cmd-plugin` already declares `deepctl-cmd-update>=0.2.7` for the `InstallMethod.NPM` import it's always made without declaring. No hand edits are needed on the release PR: the release sync job (`check_dependency_floors.py --fix`) keeps these floors current automatically, and `release-bump-gate` (above) catches it if a future change needs a bump this job doesn't cover. A normal `pip install -U deepctl` is already safe, because the root floors pin everything. ## Known limits and follow-ups (not in this PR) **Accepted limits:** - A `pip install deepctl` into the same prefix overwrites npm's `dg`, and brew and npm both want `dg`. The npm README says to use one install method. - Group-writable caches on shared-group systems (macOS `staff`, SUSE `users`) fall back to a private temp dir. Any user-private-group member could interfere, which is a limit of that convention. - `nohup dg …` doesn't survive SIGHUP the way `nohup deepctl …` does, because of how Node handles it. Use `setsid` or deepctl directly for detached runs. - With a TTY attached, a SIGINT sent only to the launcher's pid (not the process group) isn't forwarded. - npm and npx don't work on Intel Macs or Windows on ARM64. The launcher installs with `--only-binary :all:`, and `cryptography` 50.0.0 has no wheel for either platform. `README.md`, `npm/README.md` and `llms-full.txt` say so. On an Intel Mac they point to Homebrew, because the tap formula brings the Rust toolchain that a source build of `cryptography` needs. - The launcher sets `DEEPCTL_LAUNCHER=npm` for both a global install and a project dependency, because it has no reliable, portable way to tell them apart. `dg update` shows both the global and the project-local command (`npm install @deepgram/cli@latest`); the update notice shows only the global one. `npm/README.md` covers both and has a new Uninstall section. **Notes for reviewers:** - `deepctl_core._launcher.capture_launcher()` still checks `deepctl.main.LAUNCHER_CAPTURED` first. It can look like dead code on this branch, but it's kept on purpose. In 0.5.0 (#165), `deepctl.main` becomes stdlib-only and removes `DEEPCTL_LAUNCHER` before `deepctl_core` is imported, so that flag is the only way npm installs are still detected. The docstrings now explain this. - `publish-on-release.yml` (line 46) also runs an unpinned `pip install build twine`. That file isn't changed by this PR, so it's left for a follow-up. **Existing bugs found along the way:** - `dg update` tells Homebrew users to run `brew upgrade deepctl`, but the formula is `deepgram`. - deepctl 0.4.0 crashes when HOME is unreadable (`PermissionError` on `~/.deepctl/plugins/venv`). - The `actions/checkout` pins are commented `# v4` but resolve to v7.0.1. **Phase 2:** PyInstaller per-platform binaries through `optionalDependencies`, so npm installs need no Python or uv at all. The history includes a manual re-publish path that was added and later removed, so **squash on merge**.
2 parents 6537b4f + 6691803 commit 8ed20ee

49 files changed

Lines changed: 6113 additions & 69 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitattributes‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
11
# output.py is CRLF on main and ruff format keeps it that way; let git diff --check accept it.
22
packages/deepctl-core/src/deepctl_core/output.py whitespace=cr-at-eol
3+
# .gitignore is CRLF on main too; same treatment so new entries match the file.
4+
.gitignore whitespace=cr-at-eol
35
packages/deepctl-core/tests/unit/fixtures/legacy_v03/** -text

‎.github/release-please-config.json‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,12 @@
1111
"include-component-in-tag": false,
1212
"make-latest": true,
1313
"extra-files": [
14-
"src/deepctl/__init__.py"
14+
"src/deepctl/__init__.py",
15+
{
16+
"type": "json",
17+
"path": "npm/package.json",
18+
"jsonpath": "$.version"
19+
}
1520
]
1621
},
1722
"packages/deepctl-core": {

‎.github/workflows/release.yml‎

Lines changed: 286 additions & 10 deletions
Large diffs are not rendered by default.

‎.github/workflows/test.yml‎

Lines changed: 225 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,227 @@ jobs:
112112
- name: Verify packages
113113
run: make verify-packages
114114

115+
# The launcher's unit tests on every Node version package.json's engines
116+
# field admits. Linux only: the cross-OS job below covers platforms.
117+
launcher-node:
118+
name: npm launcher unit tests / Node ${{ matrix.node }}
119+
runs-on: ubuntu-latest
120+
strategy:
121+
fail-fast: false
122+
matrix:
123+
# 20.0.0 is the engines floor itself.
124+
node: ["20.0.0", "20", "22", "24"]
125+
steps:
126+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
127+
128+
- name: Set up Node
129+
uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
130+
with:
131+
node-version: ${{ matrix.node }}
132+
133+
# Unquoted: Node 20 does not expand --test globs itself, bash does.
134+
- name: Unit tests
135+
run: node --test npm/test/*.test.js
136+
137+
launcher:
138+
name: npm launcher / ${{ matrix.os }}
139+
runs-on: ${{ matrix.os }}
140+
strategy:
141+
fail-fast: false
142+
matrix:
143+
os: [ubuntu-latest, windows-latest, macos-latest]
144+
defaults:
145+
run:
146+
shell: bash
147+
steps:
148+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
149+
150+
- name: Set up Node
151+
uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
152+
with:
153+
node-version: "22"
154+
155+
# A glob, not the directory: Node 22+ treats --test arguments as file
156+
# patterns, and Node expands it itself where the shell does not.
157+
- name: Unit tests
158+
run: node --test "npm/test/*.test.js"
159+
160+
# npm/LICENSE is what npmjs.com and the tarball show; it must not drift
161+
# from the repository's.
162+
- name: npm/LICENSE matches LICENSE
163+
run: cmp LICENSE npm/LICENSE
164+
165+
# Regression: the launcher once made the stdin it hands to deepctl
166+
# non-blocking, so a reader that had to wait (an MCP host, `ffmpeg |
167+
# dg listen`) failed. A stand-in deepctl checks fds 0-2 and reads input
168+
# that arrives a second late.
169+
- name: stdin stays blocking for deepctl
170+
if: runner.os != 'Windows'
171+
run: |
172+
set -euo pipefail
173+
FAKE="$(mktemp -d)"
174+
cat > "${FAKE}/deepctl" <<'PY'
175+
#!/usr/bin/env python3
176+
import fcntl, os, sys
177+
flags = [bool(fcntl.fcntl(fd, fcntl.F_GETFL) & os.O_NONBLOCK) for fd in (0, 1, 2)]
178+
print("nonblock=%s read=%r" % (flags, sys.stdin.read()))
179+
PY
180+
chmod +x "${FAKE}/deepctl"
181+
OUT="$( (sleep 1; echo hello) | PATH="${FAKE}:${PATH}" DEEPCTL_NPM_RUNNER=path node npm/bin/dg.js)"
182+
echo "${OUT}"
183+
[ "${OUT}" = "nonblock=[False, False, False] read='hello\n'" ]
184+
185+
- name: Install uv
186+
uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
187+
with:
188+
version: "0.13.6"
189+
190+
# npm/package.json is already bumped on a release PR, before PyPI has
191+
# that version, so run the launcher against the newest deepctl that
192+
# PyPI actually serves. This checks the launcher, not the release.
193+
- name: Smoke test against the latest deepctl on PyPI
194+
run: |
195+
set -euo pipefail
196+
LATEST="$(node -e 'fetch("https://pypi.org/pypi/deepctl/json").then(r => r.json()).then(d => console.log(d.info.version))')"
197+
echo "deepctl on PyPI: ${LATEST}"
198+
echo "latest=${LATEST}" >> "$GITHUB_ENV"
199+
OUT="$(DEEPCTL_NPM_PYPI_SPEC="deepctl==${LATEST}" node npm/bin/dg.js --version)"
200+
echo "${OUT}"
201+
printf '%s' "${OUT}" | grep -qF "${LATEST}"
202+
203+
# The fallback for machines without uv: find Python, build a private
204+
# venv, run from it. Windows exercises Scripts\deepctl.exe and the py
205+
# launcher here.
206+
- name: Set up Python
207+
uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
208+
with:
209+
python-version: "3.12"
210+
211+
- name: Smoke test the venv strategy
212+
run: |
213+
set -euo pipefail
214+
# tr: Python on Windows ends lines with CRLF.
215+
OUT="$(DEEPCTL_NPM_RUNNER=venv DEEPCTL_NPM_PYPI_SPEC="deepctl==${latest}" node npm/bin/dg.js --version | tr -d '\r')"
216+
printf 'stdout: %s\n' "${OUT}"
217+
# Exactly the version line: setup chatter must stay on stderr.
218+
[ "${OUT}" = "deepctl, version ${latest}" ]
219+
# Windows never reuses a venv: the one-run venv must be gone.
220+
if [ "${RUNNER_OS}" = "Windows" ]; then
221+
LEFT="$(ls -A "$(cygpath "${LOCALAPPDATA}")/deepgram-cli/venvs")"
222+
[ -z "${LEFT}" ] || { echo "::error::one-run venv left behind: ${LEFT}"; exit 1; }
223+
fi
224+
225+
# The release path, end to end, without PyPI: build this commit's
226+
# packages, serve them and their locked dependencies from a local index
227+
# (simple pages plus the JSON API write_requirements.py reads), write the
228+
# hash-locked requirements file against it, and run the launcher through
229+
# uv and through the pip fallback. The `launcher` job's smoke tests use
230+
# the unhashed DEEPCTL_NPM_PYPI_SPEC override; this one does not.
231+
launcher-hashed:
232+
name: npm launcher hash-locked install / ${{ matrix.os }}
233+
runs-on: ${{ matrix.os }}
234+
permissions:
235+
contents: read
236+
strategy:
237+
fail-fast: false
238+
matrix:
239+
os: [windows-latest, macos-latest]
240+
defaults:
241+
run:
242+
shell: bash
243+
env:
244+
DEEPCTL_TELEMETRY_DISABLED: "1"
245+
DEEPCTL_TELEMETRY_DSN: "http://k@127.0.0.1:9/1"
246+
UV_PYTHON_DOWNLOADS: never
247+
steps:
248+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
249+
250+
- name: Set up Node
251+
uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
252+
with:
253+
node-version: "22"
254+
255+
- name: Set up Python
256+
uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
257+
with:
258+
python-version: "3.12"
259+
260+
- name: Install uv
261+
uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
262+
with:
263+
version: "0.13.6"
264+
265+
# One step: the index server only lives as long as the step's shell.
266+
- name: Install through the launcher from a local index
267+
run: |
268+
set -euo pipefail
269+
uv build --all-packages -q -o dist
270+
uv export --frozen --no-dev --no-emit-workspace --no-header --no-annotate > third.txt
271+
# Wheels for every Python the launcher may pick (it prefers the
272+
# newest supported one, and runners have several installed).
273+
for v in 3.12 3.13 3.14; do
274+
python -m pip download -q --disable-pip-version-check --only-binary :all: --no-deps --require-hashes --python-version "${v}" -r third.txt -d wheels
275+
done
276+
python npm/scripts/local_index.py --out idx dist wheels
277+
python -m http.server -b 127.0.0.1 -d idx 8765 > /dev/null 2>&1 &
278+
SERVER=$!
279+
trap 'kill "${SERVER}"' EXIT
280+
for _ in $(seq 1 30); do curl -sf http://127.0.0.1:8765/simple/ > /dev/null && break; sleep 1; done
281+
python npm/scripts/write_requirements.py --index-url http://127.0.0.1:8765 --dist dist
282+
VERSION="$(node -p 'require("./npm/package.json").version')"
283+
export UV_INDEX_URL=http://127.0.0.1:8765/simple PIP_INDEX_URL=http://127.0.0.1:8765/simple
284+
# Windows never reuses a uv cache: plant one where earlier versions
285+
# kept it, and check below that uv neither read nor wrote it.
286+
if [ "${RUNNER_OS}" = "Windows" ]; then
287+
PLANTED="$(cygpath "${LOCALAPPDATA}")/deepgram-cli/uv-cache"
288+
mkdir -p "${PLANTED}"
289+
echo planted > "${PLANTED}/marker"
290+
fi
291+
for runner in uvx venv; do
292+
# A fresh HOME per runner, so the venv run cannot reuse the venv
293+
# the uv run cached (macOS keeps it under ~/Library/Caches).
294+
# tr: Python on Windows ends lines with CRLF.
295+
mkdir -p "${RUNNER_TEMP}/home-${runner}"
296+
OUT="$(HOME="${RUNNER_TEMP}/home-${runner}" DEEPCTL_NPM_RUNNER="${runner}" node npm/bin/dg.js --version | tr -d '\r')"
297+
printf '%s: %s\n' "${runner}" "${OUT}"
298+
[ "${OUT}" = "deepctl, version ${VERSION}" ]
299+
done
300+
# Windows never reuses a venv: the one-run venvs must be gone.
301+
if [ "${RUNNER_OS}" = "Windows" ]; then
302+
LEFT="$(ls -A "$(cygpath "${LOCALAPPDATA}")/deepgram-cli/venvs")"
303+
[ -z "${LEFT}" ] || { echo "::error::one-run venv left behind: ${LEFT}"; exit 1; }
304+
CACHED="$(ls -A "${PLANTED}")"
305+
[ "${CACHED}" = "marker" ] || { echo "::error::the uv cache in ${PLANTED} was used: ${CACHED}"; exit 1; }
306+
fi
307+
308+
# The release PR's bump gate (scripts/check_release_bumps.py), for commits
309+
# people push to the release PR, such as a CHANGELOG edit. Commits from
310+
# release-please and the release workflow's sync job use GITHUB_TOKEN and
311+
# trigger no workflows; release.yml's sync-release-pr posts the same
312+
# `release-bump-gate` context as a commit status on those. Skipped on
313+
# every other PR, which a required check treats as passing. Deliberately
314+
# not in all-checks: on non-release PRs it never runs.
315+
release-bump-gate:
316+
name: release-bump-gate
317+
if: github.event_name == 'pull_request' && startsWith(github.head_ref, 'release-please--')
318+
runs-on: ubuntu-latest
319+
steps:
320+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
321+
with:
322+
# The PR head, not the merge commit, and every release tag.
323+
ref: ${{ github.event.pull_request.head.sha }}
324+
fetch-depth: 0
325+
326+
- name: Set up Python
327+
uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
328+
with:
329+
python-version: "3.12"
330+
331+
- name: Check every changed package is being released
332+
run: |
333+
pip install packaging==26.3
334+
python scripts/check_release_bumps.py
335+
115336
# Single rollup so branch protection needs exactly one required check.
116337
# Requiring the matrix contexts directly means editing repo settings every
117338
# time a Python version or OS is added or dropped, and a required context
@@ -123,7 +344,7 @@ jobs:
123344
# cancelled and skipped prerequisites are failures here too.
124345
all-checks:
125346
name: All checks
126-
needs: [test, lint, floors, build-test]
347+
needs: [test, lint, floors, build-test, launcher-node, launcher, launcher-hashed]
127348
if: always()
128349
runs-on: ubuntu-latest
129350
steps:
@@ -133,6 +354,9 @@ jobs:
133354
echo "lint: ${{ needs.lint.result }}"
134355
echo "floors: ${{ needs.floors.result }}"
135356
echo "build-test: ${{ needs.build-test.result }}"
357+
echo "launcher-node: ${{ needs.launcher-node.result }}"
358+
echo "launcher: ${{ needs.launcher.result }}"
359+
echo "launcher-hashed: ${{ needs.launcher-hashed.result }}"
136360
137361
- name: Fail unless every prerequisite succeeded
138362
if: ${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') || contains(needs.*.result, 'skipped') }}

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,10 @@ downloads/
1515
eggs/
1616
.eggs/
1717
lib/
18+
# The npm launcher's sources, not a build output.
19+
!/npm/lib/
20+
# Written by the release (npm/scripts/write_requirements.py).
21+
/npm/requirements-*.txt
1822
lib64/
1923
parts/
2024
sdist/

‎CONTRIBUTING.md‎

Lines changed: 27 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -70,13 +70,29 @@ only installs what root depends on, so a published package missing from that
7070
list never reaches anyone. `make floors-check` fails on both that omission and
7171
a floor left below the workspace version; run `make floors-fix` to pin floors.
7272

73+
When a package starts importing a sibling API that only the sibling's newest
74+
release has, add the pair to `SIBLING_FLOORS` in
75+
`scripts/check_dependency_floors.py`. That floor then tracks the sibling's
76+
workspace version the same way root floors do, and the release workflow checks
77+
it again before building for PyPI.
78+
79+
Floors only hold if every package whose code changed is released.
80+
`scripts/check_release_bumps.py` fails when a package's `src/` or dependencies
81+
changed since its last release tag but its version did not move (a `chore:` or
82+
`refactor:` commit does not bump it). On the release PR it reports as the
83+
`release-bump-gate` check: `sync-release-pr` posts it as a commit status on the
84+
bot's commits, and `test.yml` runs it for commits people push. It blocks the
85+
merge only while `release-bump-gate` is a required check on `main`. The build
86+
job runs it again before anything reaches PyPI. Land a `fix:` commit
87+
touching that package, or a `Release-As:` footer, and release again.
88+
7389
### Releasing
7490

7591
Releases are driven by release-please. Two things are worth knowing before you
7692
run one:
7793

7894
**Land your release-notes edits as a commit, not a PR description edit.**
79-
`sync-release-pr` regenerates `uv.lock` and the root dependency floors on the
95+
`sync-release-pr` regenerates `uv.lock` and the root and sibling dependency floors on the
8096
release branch automatically, but it pushes with `GITHUB_TOKEN`, which by
8197
design retriggers nothing — so the PR's checks still reflect the bot's first
8298
commit and stay red on content that is now correct. Editing `CHANGELOG.md` on
@@ -87,11 +103,16 @@ dedicated PAT or GitHub App token.
87103

88104
**Nothing advertises a release until it is installable.** `verify-published`
89105
polls PyPI until `pip install deepctl==X` resolves its full closure, then
90-
installs it for real and runs the CLI. `mark-latest`, `deploy-web`, and the
91-
Homebrew bump all wait on it. If it times out, PyPI has not propagated or a
92-
sub-package failed to publish — re-run all jobs on that workflow run once
93-
PyPI has caught up; re-running only the failed job leaves the three
94-
downstream jobs skipped. Re-running all jobs is safe: the publish step uses
106+
installs it for real and runs the CLI. `mark-latest`, `deploy-web`, the
107+
Homebrew bump, and `publish-npm` all wait on it. `deploy-web` also waits on
108+
`publish-npm`, which publishes `@deepgram/cli` and smoke-tests it with `npx`,
109+
so the site never shows npm install instructions before the package works.
110+
If `verify-published` times out, PyPI has not propagated or a sub-package
111+
failed to publish — re-run all jobs on that workflow run once PyPI has caught
112+
up; re-running only the failed job leaves the downstream jobs skipped. If
113+
only `publish-npm` fails, fix the cause and re-run failed jobs: `deploy-web`
114+
stays skipped until it passes, and the npm publish step skips an
115+
already-published version. Re-running all jobs is safe: the publish step uses
95116
`skip-existing`.
96117

97118
### Testing

‎Makefile‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -148,10 +148,10 @@ readmes: ## Generate sub-package READMEs from pyproject.toml metadata
148148
readmes-check: ## Check sub-package READMEs are up to date
149149
python3 scripts/generate_readmes.py --check
150150

151-
floors-check: ## Check intra-workspace dependency floors (root must pin workspace versions)
151+
floors-check: ## Check intra-workspace dependency floors (root and SIBLING_FLOORS must pin workspace versions)
152152
uv run python scripts/check_dependency_floors.py
153153

154-
floors-fix: ## Pin root dependency floors to the current workspace versions
154+
floors-fix: ## Pin root and SIBLING_FLOORS dependency floors to the current workspace versions
155155
uv run python scripts/check_dependency_floors.py --fix
156156

157157
# ===================================================================

‎README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,13 +57,22 @@ iwr https://deepgram.com/install.ps1 -useb | iex
5757
pip install deepctl # pip
5858
uv tool install deepctl # uv
5959
pipx install deepctl # pipx
60+
npm install -g @deepgram/cli # npm (installs dg and deepgram)
6061
```
6162

63+
The npm package is a launcher for the same Python CLI. It needs
64+
Node.js 20+ and either [uv](https://docs.astral.sh/uv/) or Python 3.10-3.14
65+
with `venv`, and sets the CLI up on first run. It installs prebuilt wheels
66+
only, so it (and `npx`) fails on Intel Macs and Windows on ARM64, where
67+
`cryptography` has none; on an Intel Mac, use Homebrew. See
68+
[npm/README.md](npm/README.md).
69+
6270
### Try Without Installing
6371

6472
```bash
6573
uvx deepctl --help
6674
pipx run deepctl --help
75+
npx @deepgram/cli --help
6776
```
6877

6978
## Getting Started

‎conftest.py‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,13 @@ def _clean_deepgram_env(monkeypatch):
1616
for key in list(os.environ):
1717
if key.startswith("DEEPGRAM_"):
1818
monkeypatch.delenv(key, raising=False)
19+
20+
21+
@pytest.fixture(autouse=True)
22+
def _fresh_launcher_capture():
23+
"""Re-read DEEPCTL_LAUNCHER in each test, so env patches take effect."""
24+
from deepctl_core._launcher import reset_launcher_for_tests
25+
26+
reset_launcher_for_tests()
27+
yield
28+
reset_launcher_for_tests()

0 commit comments

Comments
 (0)