Package metadata for release: engines, exports, prepublishOnly #6

New Issue

clawbot · 2026-08-09T03:44:08+02:00

clawbot commented

2026-08-09 03:44:08 +02:00

Problem

package.json declares "files": ["dist/", "README.md", "LICENSE"], but dist/ is
gitignored and there is no prepublishOnly or prepare script. Packing from a clean checkout
would produce an empty package.

There is also no engines field, despite the code depending on global fetch and
ReadableStream (Node 18+) and script/bootstrap pinning a specific Node 22 release. And
there is no exports map, so every internal module path is part of the public API surface by
accident — bin/quak.ts already deep-imports src/backup.ts, src/thumbnails.ts and
src/metadata-backup.ts, none of which are re-exported from src/index.ts.

None of this can be fixed after a 1.0.0 tag without a breaking change.

Definition of done

package.json has a prepublishOnly (or prepack) script that runs the build, so a
packed tarball always contains dist/.
npm pack --dry-run (or yarn pack) from a clean checkout lists the built JavaScript,
declaration files, README.md, and LICENSE, and nothing else. Record the verified file
list in the PR body.
package.json has an engines.node range matching what the code actually requires, and
consistent with the Node version script/bootstrap pins.
package.json has an exports map that deliberately declares the public entrypoints,
including ./package.json, with types and import conditions ordered correctly.
A decision is made and documented in the PR body for each of runBackup,
runMetadataBackup, listMissingThumbnails, fixMissingThumbnails, BackupResult,
BackupError, MissingThumbnailInfo, ThumbnailFixResult and RawMagicMetadata: either
they become real public exports from src/index.ts, or they stay internal and the
exports map keeps them unreachable. The README API reference issue depends on this
answer, so it must be explicit.
The CLI still works after a build, whichever way item 5 goes.
make check green; make build green.
TODO.md updated in the same commit.

Depends on

The build fix issue.

Note

Whether this package is ever published to a public npm registry is a separate open question
tracked in its own issue; this work is correct regardless of the answer.

## Problem `package.json` declares `"files": ["dist/", "README.md", "LICENSE"]`, but `dist/` is gitignored and there is no `prepublishOnly` or `prepare` script. Packing from a clean checkout would produce an **empty package**. There is also no `engines` field, despite the code depending on global `fetch` and `ReadableStream` (Node 18+) and `script/bootstrap` pinning a specific Node 22 release. And there is no `exports` map, so every internal module path is part of the public API surface by accident — `bin/quak.ts` already deep-imports `src/backup.ts`, `src/thumbnails.ts` and `src/metadata-backup.ts`, none of which are re-exported from `src/index.ts`. None of this can be fixed after a 1.0.0 tag without a breaking change. ## Definition of done 1. `package.json` has a `prepublishOnly` (or `prepack`) script that runs the build, so a packed tarball always contains `dist/`. 2. `npm pack --dry-run` (or `yarn pack`) from a clean checkout lists the built JavaScript, declaration files, `README.md`, and `LICENSE`, and nothing else. Record the verified file list in the PR body. 3. `package.json` has an `engines.node` range matching what the code actually requires, and consistent with the Node version `script/bootstrap` pins. 4. `package.json` has an `exports` map that deliberately declares the public entrypoints, including `./package.json`, with `types` and `import` conditions ordered correctly. 5. A decision is made and documented in the PR body for each of `runBackup`, `runMetadataBackup`, `listMissingThumbnails`, `fixMissingThumbnails`, `BackupResult`, `BackupError`, `MissingThumbnailInfo`, `ThumbnailFixResult` and `RawMagicMetadata`: either they become real public exports from `src/index.ts`, or they stay internal and the `exports` map keeps them unreachable. The README API reference issue depends on this answer, so it must be explicit. 6. The CLI still works after a build, whichever way item 5 goes. 7. `make check` green; `make build` green. 8. `TODO.md` updated in the same commit. ## Depends on The build fix issue. ## Note Whether this package is ever published to a public npm registry is a separate open question tracked in its own issue; this work is correct regardless of the answer.

clawbot added this to the 1.0.0 milestone 2026-08-09 03:44:08 +02:00

clawbot self-assigned this 2026-08-09 03:44:08 +02:00

clawbot referenced this issue

2026-08-09 03:47:27 +02:00

Tag v1.0.0 #15

clawbot referenced this issue

2026-08-09 08:05:06 +02:00

Retry transient network failures with exponential backoff (closes #2) #23

clawbot referenced this issue

2026-08-09 11:56:00 +02:00

Fix the TypeScript build: `make build` fails with TS6059 on main #3

clawbot referenced this issue