@teakit/napi

    CLI and documentation

    CLI

    The published npm package and executable are both named napikit. bunup bundles the CLI's JavaScript dependencies into dist/index.js, so the published manifest has no runtime dependency downloads. The CLI exposes:

    • new [name] to scaffold a project.
    • build and build --release to build addons.
    • bump [version] to version generated packages.
    • publish to publish packages to npm.
    • npm-init to initialize npm trusted publishing.

    The CLI workspace lives at packages/cli/. Keep bunup as its bundler. The published bundle requires Node.js >=20.19.0; repository development uses Bun 1.3.14, and generated Zig projects use Zig 0.16.0. Validate TypeScript with bun run typecheck, behavior with bun test, and the distributable plus its node dist/index.js --help smoke check with bun run build.

    packages/cli/bunup.config.ts embeds the checked-out repository's exact 40-character Git commit into the CLI bundle. The scaffolder uses only that immutable revision for zig fetch; runtime environment variables cannot redirect it. Generated projects record npm 11.18.0, pnpm 10.34.5, Yarn 4.17.1, or Bun 1.3.14 and use the corresponding frozen install in their pinned-action publication workflow.

    Keep command files focused on orchestration:

    • src/build/targets.ts owns target discovery and CLI target parsing.
    • src/build/dev-outputs.ts owns development output snapshots, compare-and-swap writes, and recovery.
    • src/build/reconcile.ts owns release package reconciliation.
    • src/scaffold/ owns templates, writes, project validation, and Zig fingerprints.
    • src/internal/validation.ts owns npm name/version, GitHub repository, workflow filename, and containment checks.
    • src/npm.ts owns publishable package discovery and the one-version invariant; src/utils.ts owns the canonical npmjs registry argument boundary.

    Documentation

    Rspress serves skills/ at https://napi.teakit.org, following the teakit/arith content model. The root contains only the overview, compact LLM contract, and teakit-napi package guidance. Detailed public pages live beside this file and are mapped back to stable routes by the canonical rspress.routes.ts inventory, which rspress.config.ts consumes, including /quick-start, /async/workers, and /reference/env.

    • Put detailed public tutorials, reference pages, and package guidance in skills/teakit-napi/references/.
    • Put durable implementation knowledge in docs/knowledge/.
    • Put decisions and invariants in docs/memory/.
    • Put design options in docs/proposals/.
    • Put accepted implementation contracts in docs/specs/.
    • Update skills/_meta.json, skills/teakit-napi/references/_meta.json, and rspress.routes.ts together when public pages move; tests/docs/verify-routes.ts enforces that they remain synchronized.
    • Keep Rspress itself at the repository root: root dependency, root scripts, root configuration, root skills/ content, and root doc_build/ output.
    • Run bun run docs:build to detect broken links and verify generated routes.

    Repository automation and hosting boundary

    • .github/workflows/quality.yml runs the canonical check, typecheck, test, build, and docs:build gate. Repository CI and the tag-driven CLI release reuse that gate.
    • .github/workflows/publish-to-npm.yml releases this repository's napikit package. The scaffolded addon workflow is a different file, .github/workflows/publish.yml, written into generated consumer projects.
    • Rspress writes the static site to doc_build/ and tests/docs/verify-routes.ts verifies the canonical origin and stable routes.
    • No hosting-provider deployment workflow or DNS configuration for napi.teakit.org is present in this repository. Maintainers must configure and verify external hosting, artifact deployment, TLS, and DNS separately; a successful docs:build proves the site artifact and route contract, not that production deployment occurred.

    Use the detailed CLI reference when changing commands or flags.