poddrill 0.0.0-stage → 0.1.0

package/.agents/skills/poddrill/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: poddrill
+description: >-
+  Transcribe a podcast episode into timed text, group the voices, and store
+  a summary whose paragraphs cite that text. The agent reads the text, names
+  the voices, and writes the summary words. PodDrill stores the episode.
+  Use when fetching episode audio, starting a transcript, labeling speakers,
+  or writing a summary. When a session has no PodDrill tools, register the
+  client before transcribing. Do not use it to change the poddrill TypeScript.
+---
+
+# PodDrill
+
+PodDrill is a toolset to make transcription and summary of podcast audio streamlined and structured. You may also use it for any other audio. It maps an episode (the audio) to cues, clusters those cues into speaker groups, and stores summaries. You decide how to use the toolset to answer user's request of audio summary.
+
+Set up a workspace once, when it is missing. After that, read the one guide for the part you are doing. Leave the other guides unread. If an episode already has the asset you need, read it. Do not reprocess the audio again.
+
+## Cues
+
+An asset maps each segment of the audio to text. That segment is a cue. A cue has the text and the times. You read the cues. You do not invent the text or the times.
+
+Read cues only after the embedding is ready. A ready transcript can still be not-ready for cues.
+
+## Speaker groups
+
+An asset clusters cues that sound like one voice. That cluster is a speaker group. You assign the group a name, `quote`, `ending`, or `undetermined`. The utility does not choose the name.
+
+A summary does not require those labels.
+
+## Summaries
+
+Summary is an asset of an episode. An episode can have multiple summary asset. You use the cues when you write a summary. PodDrill stores paragraphs that cite cues, then an episode summary written from the paragraph text. You choose which cues to include and you write the words. You do not write the file yourself.
+
+## The episode
+
+You keep the source list. The utility keeps the episode. The episode holds the transcript, the cues, the groups, the labels, and the summaries in your filesystem. Do not copy artifact state, progress, paths, or labels into the source list.
+
+## Register the client
+
+When this session has no PodDrill tools, register the client before setting up a workspace. `<version>` is the `version` field in this package's `package.json`. Do not use `@latest`.
+
+Run `npx -y poddrill@<version> client doctor --client cursor --json`. Use `grok_build` or `grok_bot` in place of `cursor` when that is the client.
+
+Then run `npx -y poddrill@<version> client plan --client cursor --json`.
+
+After that plan is approved, run `npx -y poddrill@<version> client apply --yes --client cursor`.
+
+A later refresh of clients that already have an entry is `npx -y poddrill@<version> client plan --linked --json`, then `npx -y poddrill@<version> client apply --yes --linked` after approval. Grok Bot prints a sentence and does not write a config file. Add that custom server in the Grok Bot chat. It runs on the bot's computer.
+
+## Set up once
+
+Set `PODDRILL_WORKSPACE` to a directory outside the git tree that contains this skill. Without that variable, `setup` uses the current directory and every other command uses `~/poddrill`.
+
+Run setup once in that workspace. The provider is the computer you are running on.
+
+```
+poddrill setup --provider <id> --queue-length 4
+```
+
+If you are the Grok Bot agent, `<id>` is `grok-bot`. If you are the Cursor cloud agent, `<id>` is `cursor-cloud`. That computer is the host. Otherwise `<id>` is `localhost`.
+
+For `ja`, `ko`, or `zh`, read the weights guide and pass `--model-weights` on that same setup command. `en`, `de`, `fr`, `es`, `it`, `nl`, and `pl` do not need weights.
+
+Stop the owner before you change setup. A running owner rejects a different provider, queue length, fleet limit, or embedding limit.
+
+## Start an episode
+
+Write the WAV at `<workspace>/audio/<file>.wav`. `poddrill start` resolves the path from the workspace root and rejects a file outside `audio/`.
+
+Pass `--language <code>` on `poddrill start` when the episode is not English. The code is `en`, `de`, `fr`, `es`, `it`, `nl`, `pl`, `ja`, `ko`, or `zh`.
+
+`poddrill start` returns before the transcript exists. Poll `poddrill episode <id>` until the transcript artifact `state` is `ready` or `failed`. The id is `ep_` plus the first 16 hex characters of the sha256 of the file bytes.
+
+The transcript is done when that `state` is `ready`. Exit 0 does not mean the transcript is done. If it is missing or `failed`, pass the same WAV to `poddrill start` again. The episode id does not change.
+
+## Read a result
+
+Parse the JSON line on stdout. `episode` exits 0 when the id is unknown. `not-ready` exits 0. `start` exits 1 when `kind` is `rejected` or `full`. MCP returns that same JSON. `isError` is true only when the text starts with `{"kind":"error"`.
+
+## Present the summary
+
+Present the summary in the format preferred or prescribed by users, but always grounded by the summary constructed via poddrill.
+
+## Guides
+
+Each file tells you how to do one part of the task.
+
+- For a feed or a YouTube page, and for telling a new episode from one already handed to poddrill, read [references/track-sources.md](references/track-sources.md).
+- For finding the audio, downloading it, and writing the 16 kHz WAV, read [references/fetch-audio.md](references/fetch-audio.md).
+- For Japanese, Korean, or Chinese weights, read [references/select-models.md](references/select-models.md).
+- For a voice name, a quote, an ending, or cues left undetermined, read [references/assign-speakers.md](references/assign-speakers.md).
+- For an episode summary, read [references/create-summary.md](references/create-summary.md).
+
+## Finish
+
+Name the episode id, the transcript `state`, and the paths you wrote.

package/.agents/skills/poddrill/references/assign-speakers.md

@@ -0,0 +1,22 @@
+# Speaker assignment
+
+Read cues with `cues`. Write labels with `labelGroups`. The CLI names are `poddrill cues` and `poddrill label-groups`.
+
+A group id looks like `gc0001`. It is one voice. The same name on two groups is one person. A page holds 8 cues unless you pass a limit. The limit cannot be above 20. Pass `groupId` to read one group. Pass `after` with a cue id to read the next page. Pass `hosts` to get host names. That list leaves out `quote` and `ending`.
+
+A label is a name, `undetermined`, `quote`, or `ending`. Send only the groups you are changing.
+
+## Heuristics You May Use
+
+These are suggestions, not rules. Use your best information and judgement.
+
+- A self-referencing introduction that then gives a name may belong to that voice group. In English that can be "I'm".
+- If a voice group says another person's name in two or more lines, that name may not be the group. One mention can be a stray line. If one name is left, it may be the one to use.
+- If the lines just before a voice group say a clip is about to play, the group may be a quote. Read the line before it and the line after it.
+- If the hosts have said goodbye and the next lines are a song or a short sign-off, those lines may be the ending. They may stay without a host name.
+
+## When to stop
+
+About 95 percent of spoken time with a host name is enough. Leave the remaining cues `undetermined`. That does not block later work.
+
+Do not copy a name from the nearest group. Do not match a repeated phrase. Do not guess from a handoff. Do not use show notes.

package/.agents/skills/poddrill/references/create-summary.md

@@ -0,0 +1,140 @@
+# Create an episode summary
+
+Build one summary of an episode from its cues. One episode can hold many summaries. Each one is a YAML file. You do not write that file yourself. Use the commands below.
+
+Read the cues first with `poddrill cues`. Page them as in [Speaker assignment](assign-speakers.md).
+
+The requirement is what the user asked you to summarize. Cite the cues that answer the requirement. You do not need to include a cue if it does not contribute to answering the requirement.
+
+Before you write, mark the parts that are actually there. An episode can hold several. A part the cues do not support is left out.
+
+### News commentary
+
+News commentary is what happened, and the opinions on what happened. An opinion is that person's statement about what happened.
+
+### Explanation
+
+An explanation is how something works or why it is that way.
+
+### Advice
+
+Advice is what the listener should do, how they should decide, or how to get better.
+
+### Claim
+
+A claim is what someone holds, how they elaborate it, and the backup they offer. The elaboration is how they explain the claim. A claim can include a correction of who is speaking, and a place they stop.
+
+### Discussion
+
+A discussion is one topic, the perspectives on that topic, and how the people respond to each other. A perspective is a claim.
+
+## Paragraphs and the summary
+
+A cue belongs in a paragraph when it supports a part you marked for the requirement.
+
+You decide how the parts sit in the paragraphs. A part may take more than one paragraph. Link the cues that belong to one part, and cover what holds that part together. The summary written from those paragraphs stays clear, concise, and structured.
+
+Write `summary` after those paragraphs exist. Write it from the paragraph `text`.
+
+## Writing
+
+Write the words in `summary` and in each paragraph `text` by [Orwell's rules](orwell.md).
+
+## Start the file
+
+`startSummary` creates a new id and an empty file for that episode. The file stays under the episode. Starting again creates another summary.
+
+```
+poddrill start-summary <episodeId>
+```
+
+The MCP tool is `startSummary`. Pass `episodeId`.
+
+Take `summaryId` from the reply. Do not invent an id.
+
+`startSummary` works before the transcript is ready.
+
+## Append a paragraph
+
+A paragraph cites the cue ids it is about, in `cues`. List only those cues. A cue you leave out is not part of the paragraph, even when it sits between two cues you list. The paragraph `text` answers the requirement, written as in [Orwell's rules](orwell.md).
+
+The cue words stay in the transcript.
+
+The transcript artifact must be `ready`. Until then, append and replace report `not-ready` on `transcript`.
+
+Do not send `index`. The first append is index 1. The next append is 2.
+
+The file stores `cues` in transcript order. Omit `startMs` and `endMs`. `startMs` is the start of the earliest listed cue. `endMs` is the end of the latest listed cue. A time you send must match those cues.
+
+```
+poddrill post-paragraph <episodeId> <summaryId> '<json>'
+```
+
+```json
+{ "text": "The guest says the city allows too few new homes near jobs.", "cues": ["c0002", "c0005"] }
+```
+
+The MCP tool is `postParagraph`. Pass `episodeId`, `summaryId`, `text`, and `cues`.
+
+Two paragraphs may list the same cue.
+
+## Replace a paragraph
+
+`index` must already exist. A missing index is left uncreated. The new `text` follows [Orwell's rules](orwell.md). The new `cues` follow the same rules as an append.
+
+```
+poddrill put-paragraph <episodeId> <summaryId> '<json>'
+```
+
+```json
+{ "index": 1, "text": "The guest says the city allows too few new homes near jobs.", "cues": ["c0002", "c0005"] }
+```
+
+The MCP tool is `putParagraph`. Pass `episodeId`, `summaryId`, `index`, `text`, and `cues`.
+
+## Set the episode summary
+
+Write this after the paragraphs. `setSummary` rejects a file that has no paragraphs.
+
+`summary` is the prose for the whole episode. Those words follow [Orwell's rules](orwell.md). An empty string is rejected.
+
+```
+poddrill set-summary <episodeId> <summaryId> '<json>'
+```
+
+```json
+{ "summary": "Cities allow too few new homes, and one renter's rent rose by a third." }
+```
+
+The MCP tool is `setSummary`. Pass `episodeId`, `summaryId`, and `summary`.
+
+## Read it back
+
+```
+poddrill summary <episodeId> <summaryId>
+```
+
+The MCP tool is `summary`. Pass `episodeId` and `summaryId`.
+
+`poddrill episode` lists each summary as `summaryId`. The paragraphs stay in the summary file.
+
+## The file
+
+The file is `summaries/<summaryId>.yaml` in the episode directory. It is YAML version 1. `summaryId` is the id `startSummary` returned.
+
+```yaml
+version: 1
+episodeId: ep_ab12cd34ef567890
+summaryId: sm_ab12cd34ef567890
+summary: The guest says the city allows too few new homes.
+paragraphs:
+  - index: 1
+    text: The guest says the city allows too few new homes near jobs.
+    cues:
+      - c0002
+      - c0005
+    startMs: 41000
+    endMs: 88000
+```
+
+`version` is the number 1. Each paragraph has `index`, `text`, `cues`, `startMs`, and `endMs`. `cues` is the ordered set of cue ids that paragraph is about. The episode id, the summary id, and the cue times above are a constructed example.

package/.agents/skills/poddrill/references/fetch-audio.md

@@ -0,0 +1,40 @@
+# Find and download episode audio
+
+Find the episode audio and download it. Then write the 16-bit PCM mono 16 kHz WAV that `poddrill start` copies. Write that WAV outside this git repository. Delete the download after the WAV exists.
+
+## Podcast feed
+
+Search for the podcast feed. Take the audio URL for the episode from that feed.
+
+Download that URL with the script in this skill. The file is `scripts/fetch-audio.mjs` next to `SKILL.md`. Pass that file to `node`.
+
+```
+node <skill-dir>/scripts/fetch-audio.mjs <url> <output-path> [expected-bytes]
+```
+
+The script refuses a destination inside the git tree that contains the script. Pass the byte length when the feed lists one. The script leaves an existing file of that size in place.
+
+## yt-dlp
+
+If the feed has no audio URL, or the script does not get the file, install the current yt-dlp and run that module. The printed line is the download path.
+
+```
+python3 -m pip install --upgrade yt-dlp
+python3 -m yt_dlp -x --no-playlist --print after_move:filepath -o "<directory>/download.%(ext)s" "<page-url>"
+```
+
+Write `<directory>` outside this git repository. If that command does not get the audio, read [Usage and options](https://github.com/yt-dlp/yt-dlp#usage-and-options).
+
+## Other audio
+
+If the episode is not in a podcast feed and yt-dlp does not apply, use the tools you already have or improvise a way to fetch or record the audio. Then write the WAV below.
+
+## Write the WAV
+
+If the download path and the WAV path are the same file, pick a new WAV path first.
+
+```
+ffmpeg -hide_banner -loglevel error -nostdin -y -i <download> -ac 1 -ar 16000 -c:a pcm_s16le -f wav <episode>.wav
+```
+
+`<episode>.wav` is the path you pass to `poddrill start`. Delete `<download>` only after that WAV exists. Keep the WAV.

package/.agents/skills/poddrill/references/orwell.md

@@ -0,0 +1,71 @@
+# Orwell's rules for writing
+
+Use this for the words in `summary` and for the words in each paragraph `text`. The rules are George Orwell's, from "Politics and the English Language", Horizon, April 1946. The wording below matches the [Orwell Foundation text](https://www.orwellfoundation.com/the-orwell-foundation/orwell/essays-and-other-works/politics-and-the-english-language/).
+
+Pick the word that matches the cue. Do not start from a ready phrase and bend the cue to fit it.
+
+Apply all six. The last rule wins when another rule would make the sentence false, cruel, or unclear.
+
+## Skip a worn figure
+
+Never use a metaphor, simile or other figure of speech which you are used to seeing in print.
+
+A figure you have seen in print carries no fact from this episode. Say what the cues say.
+
+**Weak.** The housing talk is the tip of the iceberg.
+
+**Use.** The guest says the city allows too few new homes, and one renter's rent rose by a third.
+
+## Prefer the short word
+
+Never use a long word where a short one will do.
+
+If a short word names the same fact, use it. Keep a long word only when the short one would name a different fact.
+
+**Weak.** The municipality implemented insufficient residential construction in proximity to employment.
+
+**Use.** The city built too few homes near jobs.
+
+## Cut a word that does no work
+
+If it is possible to cut a word out, always cut it out.
+
+Read the sentence without the word. If the fact is unchanged, the word goes. "It is important to note that", "basically", and "in order to" fail that test.
+
+**Weak.** It is important to note that the guest basically said that the city allows too few new homes.
+
+**Use.** The guest says the city allows too few new homes.
+
+## Name who did it
+
+Never use the passive where you can use the active.
+
+Name the person or the body that acted, when the cues name them. "It was argued" hides the guest. "The guest says" does not.
+
+**Weak.** It was argued that too few homes are being built near jobs.
+
+**Use.** The guest says the city builds too few homes near jobs.
+
+## Use an everyday word
+
+Never use a foreign phrase, a scientific word or a jargon word if you can think of an everyday English equivalent.
+
+Say the fact in words the reader already uses. Keep the speaker's term when the request is about that term, and put the everyday meaning beside it.
+
+**Weak.** Zoning externalities suppress housing supply elasticity.
+
+**Use.** Rules on what a lot may hold keep new homes scarce.
+
+## Break a rule sooner than write something barbarous
+
+Break any of these rules sooner than say anything outright barbarous.
+
+Barbarous means false, cruel, or so unclear that the reader cannot retell the cue. A short, active sentence that invents an actor has failed.
+
+The cues say the city downzoned three blocks, and the request asks what that did. Keep the word, and say what it means.
+
+**Use.** The city downzoned three blocks, so each lot may hold less floor space.
+
+The cues say the rent rose by a third and do not say who raised it. Do not invent a landlord.
+
+**Use.** Rent rose by a third.

package/.agents/skills/poddrill/references/select-models.md

@@ -0,0 +1,58 @@
+# Set up Moonshine weights
+
+PodDrill does not download the weights. Install the package, download the model with word timestamps, then pass the returned directory to setup.
+
+Install the package first.
+
+```
+pip install moonshine-voice
+```
+
+`python -m moonshine_voice.download` on moonshine-voice 0.1.5 exits unless you pass `--stt`. That command prints `Downloaded model path:`. The directory on that line does not include the attention decoder, so word timestamps stay empty. Call `get_model_for_language` with `include_word_timestamps=True` instead. The returned path is the directory setup stores.
+
+Setup still needs `--provider` and `--queue-length`. Use the provider the skill already named. Add `--model-weights` to that command.
+
+## Japanese
+
+Architecture 0 is tiny.
+
+```python
+from moonshine_voice import get_model_for_language
+
+path, _arch = get_model_for_language("ja", 0, include_word_timestamps=True)
+print(path)
+```
+
+```
+poddrill setup --provider <id> --queue-length 1 --model-weights moonshine-tiny-ja=<path>
+```
+
+## Korean
+
+Architecture 0 is tiny.
+
+```python
+from moonshine_voice import get_model_for_language
+
+path, _arch = get_model_for_language("ko", 0, include_word_timestamps=True)
+print(path)
+```
+
+```
+poddrill setup --provider <id> --queue-length 1 --model-weights moonshine-tiny-ko=<path>
+```
+
+## Chinese
+
+Architecture 1 is base.
+
+```python
+from moonshine_voice import get_model_for_language
+
+path, _arch = get_model_for_language("zh", 1, include_word_timestamps=True)
+print(path)
+```
+
+```
+poddrill setup --provider <id> --queue-length 1 --model-weights moonshine-base-zh=<path>
+```

package/.agents/skills/poddrill/references/track-sources.md

@@ -0,0 +1,59 @@
+# Track podcast sources
+
+Keep a SQLite file of sources and the episodes you have already seen. PodDrill keeps the transcript state. This file does not.
+
+## Create the tables
+
+```sql
+CREATE TABLE source (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  type TEXT NOT NULL CHECK (type IN ('rss', 'youtube')),
+  locator TEXT NOT NULL,
+  last_poll TEXT,
+  latest_episode TEXT
+);
+
+CREATE TABLE episode (
+  source_id TEXT NOT NULL REFERENCES source (id),
+  remote_key TEXT NOT NULL,
+  audio_sha256 TEXT CHECK (
+    audio_sha256 IS NULL
+    OR (
+      length(audio_sha256) = 64
+      AND audio_sha256 NOT GLOB '*[^0-9a-f]*'
+    )
+  ),
+  PRIMARY KEY (source_id, remote_key)
+);
+```
+
+`id` is a stable name you choose for that source.
+
+`type` is `rss` or `youtube`.
+
+`locator` is loose text. For `rss` it is the feed URL. For `youtube` it is the channel, playlist, or page URL.
+
+`last_poll` is the time of the last poll, or null before the first one. Store it as UTC `YYYY-MM-DDTHH:MM:SSZ`.
+
+`latest_episode` is the newest episode time from that poll, in the same form. Leave it null when the source has no episode time.
+
+`remote_key` is how you recognize the same item on the next poll. For `rss` use the item guid. If the item has no guid, use the enclosure URL. For `youtube` use the video id.
+
+`audio_sha256` is the sha256 of the file you pass to `poddrill start`, as 64 lowercase hex digits. Leave it null until that file exists. The episode id is `ep_` plus the first 16 characters of that hash.
+
+## Poll
+
+Read every row in `source`.
+
+For `rss`, fetch the feed at `locator`. For `youtube`, list the videos at `locator`. Then set `last_poll` to the current UTC time. Set `latest_episode` to the newest episode time in that response. Leave `latest_episode` null when the response has no episode time.
+
+For each item, look up `source_id` and `remote_key`.
+
+If the row is missing, insert it with `audio_sha256` null. Download the audio as in [Find and download episode audio](fetch-audio.md). Hash the file you will pass to `poddrill start`, store that digest, and start the episode.
+
+If the row exists and `audio_sha256` is null, the download did not finish. Download it, store the hash, and start the episode.
+
+If `audio_sha256` is set, run `poddrill episode` with `ep_` plus the first 16 characters of that hash. The episode is processed when the transcript artifact state is `ready`. Read that from `poddrill episode`, `poddrill cues`, or the episode directory. Do not copy the artifact state, the progress, the paths, or the labels into this database.
+
+A transcript that is missing or failed is not processed. Start it again with the CLI or MCP. Leave the hash in place.

package/.agents/skills/poddrill/scripts/fetch-audio.mjs

@@ -0,0 +1,154 @@
+import { createWriteStream } from "node:fs";
+import { mkdir, realpath, rename, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { fileURLToPath } from "node:url";
+
+export async function downloadTo(url, outputPath, expectedByteLength) {
+  if (typeof url !== "string" || url.length === 0) {
+    throw new Error("url must be a non-empty string");
+  }
+  if (typeof outputPath !== "string" || outputPath.length === 0) {
+    throw new Error("output path must be a non-empty string");
+  }
+  const expected = readExpectedByteLength(expectedByteLength);
+  const destination = await canonicalPath(outputPath);
+  const root = await gitRoot();
+  if (isInside(root, destination)) {
+    throw new Error(`refusing to write inside the git tree: ${destination}`);
+  }
+  await mkdir(path.dirname(destination), { recursive: true });
+  if (expected !== undefined && (await existingSize(destination)) === expected) {
+    return destination;
+  }
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`download failed with HTTP ${response.status}`);
+  }
+  if (response.body === null) {
+    throw new Error("download failed with an empty body");
+  }
+  const partial = `${destination}.partial`;
+  try {
+    await pipeline(Readable.fromWeb(response.body), createWriteStream(partial));
+    const written = await stat(partial);
+    if (expected !== undefined && written.size !== expected) {
+      throw new Error(`expected ${expected} bytes, got ${written.size}`);
+    }
+    await rename(partial, destination);
+  } catch (error) {
+    await rm(partial, { force: true });
+    throw error;
+  }
+  return destination;
+}
+
+function readExpectedByteLength(value) {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value === "number" && Number.isSafeInteger(value) && value > 0) {
+    return value;
+  }
+  throw new Error("expected byte length must be a positive integer");
+}
+
+async function existingSize(destination) {
+  try {
+    const existing = await stat(destination);
+    return existing.isFile() ? existing.size : undefined;
+  } catch (error) {
+    if (!isEnoent(error)) {
+      throw error;
+    }
+    return undefined;
+  }
+}
+
+function isEnoent(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+
+function isInside(root, target) {
+  const relative = path.relative(root, target);
+  if (relative === "") {
+    return true;
+  }
+  return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+
+async function gitRoot() {
+  let current = path.dirname(fileURLToPath(import.meta.url));
+  for (;;) {
+    try {
+      await stat(path.join(current, ".git"));
+      return await realpath(current);
+    } catch (error) {
+      if (!isEnoent(error)) {
+        throw error;
+      }
+      const parent = path.dirname(current);
+      if (parent === current) {
+        throw new Error("refusing to download because no git tree contains the script");
+      }
+      current = parent;
+    }
+  }
+}
+
+// A missing final component is still inside the tree when its real parent is.
+async function canonicalPath(input) {
+  let resolved = path.resolve(input);
+  const pending = [];
+  for (;;) {
+    try {
+      const real = await realpath(resolved);
+      return pending.length === 0 ? real : path.join(real, ...pending.toReversed());
+    } catch (error) {
+      if (!isEnoent(error)) {
+        throw error;
+      }
+      const parent = path.dirname(resolved);
+      if (parent === resolved) {
+        throw new Error(`cannot resolve ${input}`);
+      }
+      pending.push(path.basename(resolved));
+      resolved = parent;
+    }
+  }
+}
+
+function parseCliByteLength(raw) {
+  if (!/^[1-9][0-9]*$/.test(raw)) {
+    throw new Error("expected byte length must be a positive integer");
+  }
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value)) {
+    throw new Error("expected byte length must be a positive integer");
+  }
+  return value;
+}
+
+const entry = process.argv[1];
+if (entry !== undefined && path.resolve(entry) === fileURLToPath(import.meta.url)) {
+  const url = process.argv[2];
+  const outputPath = process.argv[3];
+  const rawLength = process.argv[4];
+  if (url === undefined || outputPath === undefined || process.argv.length > 5) {
+    console.error(
+      "usage: node <path-to-this-script> <url> <output-path> [expected-bytes]",
+    );
+    process.exitCode = 1;
+  } else {
+    try {
+      const expectedByteLength = rawLength === undefined ? undefined : parseCliByteLength(rawLength);
+      const written = await downloadTo(url, outputPath, expectedByteLength);
+      console.log(written);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "download failed";
+      console.error(message);
+      process.exitCode = 1;
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jianyu Zhao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.