Skip to content

README.dev.md

Latest commit

 

History

History
124 lines (92 loc) · 6.95 KB

README.dev.md

File metadata and controls

124 lines (92 loc) · 6.95 KB
Raw

Development Guide

Scoped package: @carllee1983/dbcli. All npm / npx examples below use this name.

npm Publishing Process

Pre-Publication Checklist

Before running npm publish:

  1. Verify build is clean:

    bun run build
ls -lh dist/cli.mjs   # expect a few MB (bundled CLI + dependencies)

  2. Verify tests pass (pick one):

    # Fast path: unit + core only (matches CI-style smoke)
bun run test:unit

# Full suite (Bun test runner)
bun test

    For live database integration tests, set an explicit config if needed:

    LIVE_DB_CONFIG_PATH=/path/to/.dbcli bun test tests/integration/live-db.test.ts

    If no live config is available, tests/integration/live-db.test.ts skips instead of falling back to the default PostgreSQL configuration. Use SKIP_INTEGRATION_TESTS=true to skip integration tests when running a broad bun test.

  3. Update version in package.json:

    npm version minor   # bumps version + creates git tag (in this repo)
# OR edit the "version" field in package.json by hand

  4. Verify package contents (dry run):

    npm pack --dry-run

    Expect dist/ (including cli.mjs, core.mjs / core.d.ts, and agent-core.mjs / agent-core.d.ts), assets/ (e.g. SKILL.md, reference.md for dbcli skill), README.md, CHANGELOG.md, LICENSE, and package.json. There must be no src/, tests/, or node_modules/. The listing may also include other root README*.md files (npm can still pack them even when files is set); dev-only readmes are listed in .npmignore — re-check with dry-run if you add or remove docs.

  5. Check package size:

    npm pack
ls -lh carllee1983-dbcli-*.tgz   # compressed tarball (typically well under 5MB)
rm carllee1983-dbcli-*.tgz       # cleanup

Publication

Publication uses the prepublishOnly script in package.json:

npm publish

What runs (conceptually):

  1. prepublishOnly: bun run build — rebuilds dist/cli.mjs from src/cli.ts via scripts/build.ts.
  2. Tarball — paths from the files field in package.json, further filtered by .npmignore. (Some npm versions also merge in extra root README* files; use dry-run to see exactly what will ship.)
  3. Registry — with "publishConfig": { "access": "public" }, the scoped package is published as public.

A failed bun run build will fail the publish, so you should not ship a stale dist/ from a previous local build.

Verification (Post-Publication)

After publishing:

  1. Global install:

    bun install -g @carllee1983/dbcli
which dbcli
dbcli --version

    npm install -g also works, but the installed executable still runs under Bun via its #!/usr/bin/env bun shebang — verify on a machine that has Bun on PATH.

  2. Zero-install (bunx / npx):

    cd /tmp && mkdir -p test-dbcli && cd test-dbcli
bunx @carllee1983/dbcli --help
bunx @carllee1983/dbcli --version
# or: npx @carllee1983/dbcli --help

  3. Windows (if available): npm install -g @carllee1983/dbcli, then dbcli --help. npm creates the .cmd stub for the bin entry; no hand-written .cmd in the repo. Bun must be on PATH there too.

Rollback (if needed)

If a bad release must be mitigated:

npm unpublish @carllee1983/dbcli@<VERSION>
# and/or
npm deprecate @carllee1983/dbcli@<VERSION> "Reason; use <SAFE_VERSION> instead"

Then ship a patch version with the fix. Prefer deprecate over unpublish when consumers may already depend on the version.

Configuration Details

  • files (in package.json): Publishes dist/, assets/, README.md, CHANGELOG.md, LICENSE. The assets/ tree is required for dbcli skill to copy bundled SKILL.md / reference.md from the installed package.
  • prepublishOnly: bun run build so dist/cli.mjs matches current source.
  • engines: Declares bun >= 1.3.3 only. node was removed because the published bundles cannot run on Node: dist/cli.mjs dynamic-imports the extensionless ./cli-runtime (Bun's resolver appends .mjs, Node's does not) and dist/core.mjs calls Bun globals. tests/integration/runtime-contract.test.ts fails if engines.node comes back without the bundles being fixed to match, and if dist/agent-core.mjs — the one entry point that is Node-importable — regresses. See docs/adr/0008-dbcli-is-a-bun-program-and-engines-says-so.md.
  • Shebang: scripts/build.ts prepends #!/usr/bin/env bun to dist/cli.mjs; the bin field in package.json points at that file.
  • exports: ./core and ./agent-core only — there is deliberately no . entry. It used to point at dist/cli.mjs, and src/cli-runtime.ts calls outputHelp() and parseAsync(process.argv) at module top level, so importing the package ran the CLI against the host's argv and never returned. bin does not resolve through exports, so the executable is unaffected. tests/integration/runtime-contract.test.ts pins both the absence of . and the side effect that justifies it.
  • postinstall: scripts/postinstall-check-bun.mjs reports a missing Bun — npm ignores engines.bun, so this is the only signal an npm-only machine gets before dbcli refuses to start. The command is bun … || node … so it runs under whichever runtime is present: Bun-only machines have no node to invoke it with, and a hard node dependency there would break the primary install path. It must not end in || exit 0; v1.55.0 shipped with that mask and npm, which hides lifecycle output unless a script fails, therefore showed nothing at all. On a global install (npm_config_global === 'true') a missing Bun exits 1, so the reason is printed and npm rolls the bin back; a dependency install only warns, because that is the ./agent-core consumer. Both outcomes are pinned in tests/integration/runtime-contract.test.ts.
  • Live DB tests: tests/integration/live-db.test.ts uses project .dbcli by default or LIVE_DB_CONFIG_PATH when you point at another config directory. Set SKIP_INTEGRATION_TESTS=true to skip all integration tests.

For contributor workflow and release process, see CONTRIBUTING.md and the main README.md Development section.

Troubleshooting

Issue What to do
prepublishOnly / build fails Fix TypeScript or build errors, run bun run test:unit, then bun run build again.
Tarball unexpectedly large or bloated Inspect the bundle: e.g. bun build ./src/cli.ts --outfile=dist/cli.mjs --target=bun --metafile=meta.json and review the metafile; trim dependencies or dev-only code paths.
Windows: dbcli not found after global install Confirm PATH includes npm’s global bin; reinstall npm i -g @carllee1983/dbcli.
npx download slow or cache weird npm cache clean --force and retry npx @carllee1983/dbcli --version.