@temir.ra/create-ts-lib 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Version 0
+
+## 0.1.0
+
+1. First version of the template.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Temir Ra
+
+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.

package/README.md

@@ -0,0 +1,358 @@
+# Introduction
+
+A template for TypeScript libraries distributed via npm-compatible registries. Provides TypeScript configuration, build tooling for ESM and bundled outputs, and build metadata generation.
+
+## Table of Contents
+
+1. [Quick Start](#quick-start)
+2. [Documentation](#documentation)
+    1. [`tsconfig.json` and `tsconfig.build.json`](#tsconfigjson-and-tsconfigbuildjson)
+    2. [`package.json`](#packagejson)
+    3. [Script `scripts/buildinfo.ts`](#script-scriptsbuildinfots)
+    4. [Script `scripts/build-lib-bundle.ts`](#script-scriptsbuild-lib-bundlets)
+    5. [CDN Map `scripts/cdn-rewrite-map.json`](#cdn-map-scriptscdn-rewrite-mapjson)
+    6. [`src/urls.ts`](#srcurlsts)
+    7. [`src/dev.ts`](#srcdevts)
+    8. [`CLAUDE.md` / `AGENTS.md`](#claudemd--agentsmd)
+3. [DevOps](#devops)
+    1. [Build](#build)
+    2. [Change Management](#change-management)
+    3. [Publish](#publish)
+        1. [npmjs.org](#npmjsorg)
+        2. [Custom registry](#custom-registry)
+
+# Quick Start
+
+```bash
+# placeholder:
+    # <PACKAGE: <PACKAGE>
+
+bun create --no-install --no-git "@temir.ra/ts-lib" <PACKAGE>
+cd <PACKAGE>
+bun install
+```
+
+# Documentation
+
+## `tsconfig.json` and `tsconfig.build.json`
+
+```json
+{
+
+  "compilerOptions": {
+
+    // ECMAScript version of emitted output
+    "target": "ES2022",
+
+    // output module format; ESNext passes ES module syntax through unchanged
+    "module": "ESNext",
+
+    // type definitions for built-in APIs
+    "lib": [
+      "ES2022", // standard JavaScript runtime APIs
+      "DOM"     // browser globals for bundled output
+    ],
+
+    // module resolution strategy; bundler mode allows omitting file extensions in imports
+    // tsconfig.build.json overrides this to nodenext for strict ESM compliance
+    "moduleResolution": "bundler",
+
+    // enables all strict type-checking options
+    "strict": true,
+
+    // enforces import type for type-only imports; emitted module syntax matches source exactly
+    "verbatimModuleSyntax": true,
+
+    // array indexing and index signature access returns T | undefined instead of T
+    "noUncheckedIndexedAccess": true,
+
+    // distinguishes absent optional properties from those explicitly set to undefined
+    "exactOptionalPropertyTypes": true,
+
+    // requires explicit override keyword when overriding base class methods
+    "noImplicitOverride": true,
+
+    // requires explicit types on all exported declarations; enables parallel .d.ts generation by external tools
+    "isolatedDeclarations": true,
+
+    // allows default imports from CommonJS modules
+    "esModuleInterop": true,
+
+    // enables project references and incremental builds via *.tsbuildinfo
+    "composite": true,
+
+    // do not type-check `.d.ts` files in `node_modules/`
+    "skipLibCheck": true,
+
+    // enforce consistent casing across import statements
+    "forceConsistentCasingInFileNames": true,
+
+    // allows importing JSON files as typed modules
+    "resolveJsonModule": true,
+
+    // emit .d.ts declaration files
+    "declaration": true,
+    // emit .d.ts.map files mapping declarations back to source
+    "declarationMap": true,
+
+    // emit only .d.ts files, no JavaScript; overridden in tsconfig.build.json
+    "emitDeclarationOnly": true,
+
+    // output directory for emitted files
+    "outDir": "./dist",
+
+    // root directory mirrored into outDir; set to project root during development, overridden to src/ in tsconfig.build.json
+    "rootDir": ".",
+
+  },
+
+  // includes src/, tests/, and scripts/ for type-checking and IDE support; overridden in tsconfig.build.json
+  "include": [
+    "src/**/*.ts",
+    "tests/**/*.ts",
+    "scripts/**/*.ts",
+    "scripts/**/*.json"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+
+}
+```
+
+`tsconfig.json` is the development configuration. `tsconfig.build.json` extends it, narrowing scope to `src/` and enabling JavaScript output for distribution.
+
+`declarationMap: true` enables go-to-definition for npm/bun consumers. For this to work, the original `.ts` source files must be accessible to the consumer. Consider adding `src/` to the `files` field in `package.json`.
+
+```json
+{
+
+  "extends": "./tsconfig.json",
+
+  "compilerOptions": {
+
+    // narrows root to src/ for distribution output
+    "rootDir": "./src",
+
+    // nodenext enforces strict ESM compliance; imports must use explicit .js file extensions
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+
+    // emit both JavaScript files and declaration files for distribution
+    "emitDeclarationOnly": false,
+
+  },
+
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "src/dev.ts",
+    "node_modules",
+    "dist",
+    "tests",
+    "scripts"
+  ]
+
+}
+```
+
+## `package.json`
+
+```json
+{
+  "name": "",
+  "version": "0.0.0",
+
+  "description": "",
+  "author": "",
+  "license": "",
+
+  "keywords": ["typescript"],
+
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+
+  // treats all .js files as ES modules; use .cjs extension for CommonJS files
+  "type": "module",
+
+  // no module has side effects; enables full tree-shaking by bundlers
+  // set to an array of file paths if some modules do have side effects, e.g. ["./src/polyfill.ts"]
+  "sideEffects": false,
+
+  // package entry points by consumer type
+  // "entrypoint" — custom condition; used by the bundle script to locate the source entry point
+  // "types"      — TypeScript consumers; resolves to the declaration files; must precede "import" so TypeScript matches it before the JS condition
+  // "browser"    — browser bundler consumers; resolves to the bundled output
+  // "import"     — ESM consumers; resolves to the compiled module output
+  "exports": {
+    ".": {
+      "entrypoint": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "browser": "./dist/index.bundle.js",
+      "import": "./dist/index.js"
+    }
+  },
+
+  // package-internal import alias resolved natively by Node.js and Bun at runtime; key must start with #
+  // for use in dev.ts, tests/, and scripts/ only — NOT in library source files compiled by tsconfig.build.json
+  // the .js extension is required in import statements (nodenext compliance);
+  // the runtime maps it to the actual .ts source file via this field
+  "imports": {
+    "#src/*.js": "./src/*.ts"
+  },
+
+  // CLI entry point; omit if the package is not a CLI tool
+  "bin": "./dist/cli.bundle.js",
+
+  // files to include in the published package
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "buildinfo.txt"
+  ],
+
+  "scripts": {
+
+    "clean:dist": "rm -rf dist/",
+    "clean:tsbuildinfo": "rm -f tsconfig.build.tsbuildinfo",
+    "clean": "bun run clean:dist && bun run clean:tsbuildinfo",
+
+    // lifecycle hook; runs automatically before "build"; generates buildinfo.txt
+    "prebuild": "bun run scripts/buildinfo.ts",
+
+    "tests": "bun test",
+
+    "build": "bun run build:lib && bun run build:lib-bundle",
+
+    "build:lib": "tsc --project tsconfig.build.json",
+    // bundles the library into ESM and IIFE formats for distribution
+    "build:lib-bundle": "bun run scripts/build-lib-bundle.ts",
+
+    "build:cli-bundle": "bun build src/cli.ts --entry-naming \"[dir]/[name].bundle.[ext]\" --outdir dist --target node --format esm --minify --sourcemap=external",
+
+    "typecheck": "tsc --noEmit",
+
+    // runs src/dev.ts in watch mode
+    "dev": "bun run --watch src/dev.ts"
+
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.9.3"
+  }
+}
+```
+
+## Script `scripts/buildinfo.ts`
+
+Generates `buildinfo.txt` containing the version from `package.json` and the git commit hash (if available). Included in the published package for build traceability.
+
+## Script `scripts/build-lib-bundle.ts`
+
+Bundles the library to ESM and IIFE formats. Entry points are resolved from the `entrypoint` condition in the `exports` field of `package.json`. Import specifiers can be rewritten to CDN URLs via `scripts/cdn-rewrite-map.json`.
+
+## CDN Map `scripts/cdn-rewrite-map.json`
+
+Maps import specifiers to CDN URLs. During bundling, matching specifiers in source files are rewritten to their CDN equivalents. `<VERSION>` in a URL is replaced with the version of the matching package from `package.json`.
+
+```json
+{
+  "import-specifier": "https://cdn.jsdelivr.net/npm/package-name@<VERSION>/dist/index.bundle.js"
+}
+```
+
+## `"bin"` field in `package.json`
+
+For CLI packages, add the following to `package.json`:
+
+```json
+{
+  "exports": ...,
+  "bin": "./dist/cli.bundle.js",
+  "files": ...,
+  "scripts": {
+    ...,
+    "build": "... && bun run build:cli-bundle",
+    ...,
+    "build:cli-bundle": "bun build src/cli.ts --entry-naming \"[dir]/[name].bundle.[ext]\" --outdir dist --target node --format esm --minify --sourcemap=external",
+    ...,
+  }
+}
+```
+
+## `src/urls.ts`
+
+Resolves `CHANGELOG.md` and `buildinfo.txt` relative to `dist/` at runtime using `import.meta.url`. Provides stable references to published package assets regardless of install location.
+
+## `src/dev.ts`
+
+Development scratchpad — not published, excluded from `tsconfig.build.json`. Run with `bun run dev` in watch mode. Use it to manually test and explore library code during development.
+
+## `CLAUDE.md` / `AGENTS.md`
+
+AI assistant context files. Provide project layout, commands, and architecture notes. `AGENTS.md` references `CLAUDE.md`. The template ships two pairs:
+
+- Root pair — describes the template package itself (scaffolding tool, CLI, how `template/` maps to generated projects)
+- `template/` pair — describes the generated library project; update to reflect the specific library being developed
+
+# DevOps
+
+## Build
+
+```bash
+# remove dist/ and tsconfig.build.tsbuildinfo
+bun run clean
+
+# remove dist/ only
+bun run clean:dist
+
+# remove tsconfig.build.tsbuildinfo only
+bun run clean:tsbuildinfo
+
+# compile + bundle
+bun run build
+```
+
+## Change Management
+
+1. Create a new branch for the change.
+2. Make the changes and commit.
+3. Bump the version in [`package.json`](package.json).
+4. Add an entry for the new version in [`CHANGELOG.md`](CHANGELOG.md).
+5. Run `bun run build`.
+6. Pull request the branch and publish.
+
+## Publish
+
+### `npmjs.org`
+
+⚠️ Authenticate first: run `npm login` or configure `~/.npmrc` or `bunfig.toml` with an auth token.
+
+```powershell
+bun publish --registry https://registry.npmjs.org/ --access public
+```
+
+### Custom registry
+
+```bash
+# placeholder:
+    # <SCOPE_WITHOUT_AT: <SCOPE_WITHOUT_AT>
+    # <REGISTRY_URL: <REGISTRY_URL>
+    # <BUN_PUBLISH_AUTH_TOKEN: <BUN_PUBLISH_AUTH_TOKEN>
+```
+
+`bunfig.toml`:
+
+```toml
+[install.scopes]
+<SCOPE_WITHOUT_AT> = { url = "<REGISTRY_URL>", token = "$BUN_PUBLISH_AUTH_TOKEN" }
+```
+
+```powershell
+$env:BUN_PUBLISH_AUTH_TOKEN = "<BUN_PUBLISH_AUTH_TOKEN>"
+bun publish
+```

package/buildinfo.txt

@@ -0,0 +1 @@
+0.1.0+d78d3df

package/dist/cli.bundle.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import{cpSync as o,readFileSync as U,renameSync as f,writeFileSync as d}from"fs";import{resolve as t,basename as u}from"path";import{fileURLToPath as a}from"url";var n=new URL(".",import.meta.url),l=new URL("../CHANGELOG.md",n),p=new URL("../buildinfo.txt",n),m=new URL("../template",n);try{let r=process.argv[2];if(!r)throw Error("Destination path is required. Usage: `bun/npm create <template> <destination>`");let e=t(process.cwd(),r),i=u(e),g=t(a(m));o(g,e,{recursive:!0}),o(t(a(l)),t(e,"CHANGELOG-template.md")),o(t(a(p)),t(e,"buildinfo-template.txt"));let s=t(e,"package.json"),c=JSON.parse(U(s,"utf-8"));c.name=i,d(s,JSON.stringify(c,null,2)),f(t(e,"gitignore"),t(e,".gitignore")),console.log(`Template has been successfully instantiated at '${e}' with package name '${i}'.`)}catch(r){let e=r instanceof Error?r:Error(String(r));console.error("Error:",e.message),process.exit(1)}
+
+//# debugId=683E20367A2ED95764756E2164756E21

package/dist/cli.bundle.js.map

@@ -0,0 +1,11 @@
+{
+  "version": 3,
+  "sources": ["..\\src\\cli.ts", "..\\src\\urls.ts"],
+  "sourcesContent": [
+    "#!/usr/bin/env node\r\n\r\nimport { cpSync, readFileSync, renameSync, writeFileSync } from 'fs';\r\nimport { resolve, basename } from 'path';\r\nimport { fileURLToPath } from 'url';\r\nimport { buildinfoUrl, changelogUrl, templateUrl } from '#src/urls.js';\r\n\r\n\r\ntry {\r\n\r\n    const dest = process.argv[2];\r\n    if (!dest) throw new Error('Destination path is required. Usage: `bun/npm create <template> <destination>`');\r\n\r\n    const destinationPath = resolve(process.cwd(), dest);\r\n    const packageName = basename(destinationPath);\r\n\r\n    const templatePath = resolve(fileURLToPath(templateUrl));\r\n\r\n    cpSync(templatePath, destinationPath, { recursive: true });\r\n    cpSync(resolve(fileURLToPath(changelogUrl)), resolve(destinationPath, 'CHANGELOG-template.md'));\r\n    cpSync(resolve(fileURLToPath(buildinfoUrl)), resolve(destinationPath, 'buildinfo-template.txt'));\r\n\r\n    const packageManifestPath = resolve(destinationPath, 'package.json');\r\n    const packageManifest = JSON.parse(readFileSync(packageManifestPath, 'utf-8'));\r\n    packageManifest.name = packageName;\r\n    writeFileSync(packageManifestPath, JSON.stringify(packageManifest, null, 2));\r\n\r\n    renameSync(resolve(destinationPath, 'gitignore'), resolve(destinationPath, '.gitignore'));\r\n\r\n    console.log(`Template has been successfully instantiated at '${destinationPath}' with package name '${packageName}'.`);\r\n\r\n}\r\ncatch (error) {\r\n    const err = error instanceof Error ? error : new Error(String(error));\r\n    console.error('Error:', err.message);\r\n    process.exit(1);\r\n}\r\n",
+    "export const distUrl: URL = new URL('.', import.meta.url);\r\nexport const changelogUrl: URL = new URL('../CHANGELOG.md', distUrl);\r\nexport const buildinfoUrl: URL = new URL('../buildinfo.txt', distUrl);\r\nexport const templateUrl: URL = new URL('../template', distUrl);\r\n"
+  ],
+  "mappings": ";AAEA,iBAAS,kBAAQ,gBAAc,mBAAY,WAC3C,kBAAS,cAAS,aAClB,wBAAS,YCJF,IAAM,EAAe,IAAI,IAAI,IAAK,YAAY,GAAG,EAC3C,EAAoB,IAAI,IAAI,kBAAmB,CAAO,EACtD,EAAoB,IAAI,IAAI,mBAAoB,CAAO,EACvD,EAAmB,IAAI,IAAI,cAAe,CAAO,EDK9D,GAAI,CAEA,IAAM,EAAO,QAAQ,KAAK,GAC1B,GAAI,CAAC,EAAM,MAAU,MAAM,gFAAgF,EAE3G,IAAM,EAAkB,EAAQ,QAAQ,IAAI,EAAG,CAAI,EAC7C,EAAc,EAAS,CAAe,EAEtC,EAAe,EAAQ,EAAc,CAAW,CAAC,EAEvD,EAAO,EAAc,EAAiB,CAAE,UAAW,EAAK,CAAC,EACzD,EAAO,EAAQ,EAAc,CAAY,CAAC,EAAG,EAAQ,EAAiB,uBAAuB,CAAC,EAC9F,EAAO,EAAQ,EAAc,CAAY,CAAC,EAAG,EAAQ,EAAiB,wBAAwB,CAAC,EAE/F,IAAM,EAAsB,EAAQ,EAAiB,cAAc,EAC7D,EAAkB,KAAK,MAAM,EAAa,EAAqB,OAAO,CAAC,EAC7E,EAAgB,KAAO,EACvB,EAAc,EAAqB,KAAK,UAAU,EAAiB,KAAM,CAAC,CAAC,EAE3E,EAAW,EAAQ,EAAiB,WAAW,EAAG,EAAQ,EAAiB,YAAY,CAAC,EAExF,QAAQ,IAAI,mDAAmD,yBAAuC,KAAe,EAGzH,MAAO,EAAO,CACV,IAAM,EAAM,aAAiB,MAAQ,EAAY,MAAM,OAAO,CAAK,CAAC,EACpE,QAAQ,MAAM,SAAU,EAAI,OAAO,EACnC,QAAQ,KAAK,CAAC",
+  "debugId": "683E20367A2ED95764756E2164756E21",
+  "names": []
+}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { cpSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { resolve, basename } from 'path';
+import { fileURLToPath } from 'url';
+import { buildinfoUrl, changelogUrl, templateUrl } from '#src/urls.js';
+try {
+    const dest = process.argv[2];
+    if (!dest)
+        throw new Error('Destination path is required. Usage: `bun/npm create <template> <destination>`');
+    const destinationPath = resolve(process.cwd(), dest);
+    const packageName = basename(destinationPath);
+    const templatePath = resolve(fileURLToPath(templateUrl));
+    cpSync(templatePath, destinationPath, { recursive: true });
+    cpSync(resolve(fileURLToPath(changelogUrl)), resolve(destinationPath, 'CHANGELOG-template.md'));
+    cpSync(resolve(fileURLToPath(buildinfoUrl)), resolve(destinationPath, 'buildinfo-template.txt'));
+    const packageManifestPath = resolve(destinationPath, 'package.json');
+    const packageManifest = JSON.parse(readFileSync(packageManifestPath, 'utf-8'));
+    packageManifest.name = packageName;
+    writeFileSync(packageManifestPath, JSON.stringify(packageManifest, null, 2));
+    renameSync(resolve(destinationPath, 'gitignore'), resolve(destinationPath, '.gitignore'));
+    console.log(`Template has been successfully instantiated at '${destinationPath}' with package name '${packageName}'.`);
+}
+catch (error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    console.error('Error:', err.message);
+    process.exit(1);
+}

package/dist/urls.d.ts

@@ -0,0 +1,5 @@
+export declare const distUrl: URL;
+export declare const changelogUrl: URL;
+export declare const buildinfoUrl: URL;
+export declare const templateUrl: URL;
+//# sourceMappingURL=urls.d.ts.map

package/dist/urls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"urls.d.ts","sourceRoot":"","sources":["../src/urls.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,EAAE,GAAmC,CAAC;AAC1D,eAAO,MAAM,YAAY,EAAE,GAAyC,CAAC;AACrE,eAAO,MAAM,YAAY,EAAE,GAA0C,CAAC;AACtE,eAAO,MAAM,WAAW,EAAE,GAAqC,CAAC"}

package/dist/urls.js

@@ -0,0 +1,4 @@
+export const distUrl = new URL('.', import.meta.url);
+export const changelogUrl = new URL('../CHANGELOG.md', distUrl);
+export const buildinfoUrl = new URL('../buildinfo.txt', distUrl);
+export const templateUrl = new URL('../template', distUrl);

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@temir.ra/create-ts-lib",
+  "version": "0.1.0",
+  "description": "Typescript library template",
+  "author": "temir.ra",
+  "license": "MIT",
+  "keywords": [
+    "typescript",
+    "template",
+    "library",
+    "bun"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://git.temirs.cloud/trs/create-ts-lib.git"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "imports": {
+    "#src/*.js": "./src/*.ts"
+  },
+  "bin": "./dist/cli.bundle.js",
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "buildinfo.txt",
+    "template"
+  ],
+  "scripts": {
+    "clean:dist": "rm -rf dist/",
+    "clean:tsbuildinfo": "rm -f tsconfig.build.tsbuildinfo",
+    "clean": "bun run clean:dist && bun run clean:tsbuildinfo",
+    "prebuild": "bun run scripts/buildinfo.ts",
+    "tests": "bun test",
+    "build": "bun run build:lib && bun run build:cli-bundle",
+    "build:lib": "tsc --project tsconfig.build.json",
+    "build:cli-bundle": "bun build src/cli.ts --entry-naming \"[dir]/[name].bundle.[ext]\" --outdir dist --target node --format esm --minify --sourcemap=external",
+    "typecheck": "tsc --noEmit",
+    "dev": "bun run --watch src/dev.ts"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.9.3"
+  }
+}

package/template/AGENTS.md

@@ -0,0 +1 @@
+See [CLAUDE.md](CLAUDE.md).

package/template/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Version 0
+
+## 0.0.0
+
+1. Versioning initialized.

package/template/CLAUDE.md

@@ -0,0 +1,132 @@
+# <package-name>
+
+A Bun TypeScript library.
+
+## Project Layout
+
+```
+<package-name>/
+├── src/
+│   ├── index.ts        # Library entry point (public API)
+│   ├── dev.ts          # Development scratchpad — run with `bun run dev`
+│   └── urls.ts         # URL helpers (changelog, buildinfo)
+├── scripts/
+│   ├── buildinfo.ts            # Writes version + git hash to buildinfo.txt
+│   ├── build-lib-bundle.ts     # Bundles the library for ESM + CDN distribution
+│   └── cdn-rewrite-map.json    # CDN import rewrite rules (empty by default)
+├── tests/              # Unit tests (Bun test runner)
+├── dist/               # Build output (gitignored)
+├── buildinfo.txt       # Written during build; included in published package
+├── CHANGELOG.md        # Version history
+├── CLAUDE.md           # This file — AI context for the library project
+└── AGENTS.md           # References CLAUDE.md
+```
+
+## Commands
+
+```bash
+bun install       # Install dependencies
+bun run build     # Compile + bundle the library
+bun run tests     # Run unit tests
+bun run typecheck # Type-check without emitting
+bun run dev       # Run src/dev.ts in watch mode
+bun run clean              # Remove dist/ and tsconfig.build.tsbuildinfo
+bun run clean:dist         # Remove dist/ only
+bun run clean:tsbuildinfo  # Remove tsconfig.build.tsbuildinfo only
+```
+
+## Writing Code
+
+### Where things go
+
+| Path | Purpose |
+|------|---------|
+| `src/index.ts` | Public API — the only entry point consumers see; export everything public from here |
+| `src/*.ts` | Library source modules — add new modules here, re-export from `index.ts` |
+| `src/dev.ts` | Development scratchpad — excluded from build, never published; use for manual testing |
+| `tests/*.test.ts` | Unit tests — Bun test runner |
+
+### Imports within `src/`
+
+`tsconfig.build.json` uses `moduleResolution: nodenext`, so imports between library source files must use explicit `.js` extensions:
+
+```ts
+import { helper } from "./helper.js"  // ✓
+import { helper } from "./helper"     // ✗ — fails under nodenext
+```
+
+The `#src/*.js` package alias is available in `dev.ts`, `tests/`, and `scripts/`, but **not** in library source files — tsc emits the specifier verbatim and it would break in published unbundled output.
+
+### Explicit return types (`isolatedDeclarations`)
+
+All exported declarations require explicit type annotations so tsc can emit `.d.ts` files without cross-file inference:
+
+```ts
+export function greet(name: string): string { ... }  // ✓
+export function greet(name: string) { ... }          // ✗ — implicit return type
+```
+
+### Type-only imports (`verbatimModuleSyntax`)
+
+Use `import type` for imports that are only used as types:
+
+```ts
+import type { Foo } from "./foo.js"       // ✓ — type-only import
+import { type Foo, bar } from "./foo.js"  // ✓ — mixed
+import { Foo } from "./foo.js"            // ✗ — if Foo is only used as a type
+```
+
+### Tests
+
+Tests live in `tests/` and use Bun's built-in runner:
+
+```ts
+import { describe, test, expect } from "bun:test"
+
+describe("greet", () => {
+  test("returns greeting", () => {
+    expect(greet("world")).toBe("hello, world")
+  })
+})
+```
+
+Run with `bun run tests`.
+
+## TypeScript Configuration
+
+Two tsconfig files serve different purposes:
+
+| File | Purpose |
+|------|---------|
+| `tsconfig.json` | Development — no emit, includes `src/`, `tests/`, `scripts/` |
+| `tsconfig.build.json` | Build — emits JS + `.d.ts`, `src/` only (excludes `dev.ts`, tests, scripts) |
+
+`bun run build:lib` uses `tsconfig.build.json`. During development the runtime handles TypeScript directly so no compilation step is needed.
+
+Both configs enable an extended strict type-safety profile beyond `strict`: `verbatimModuleSyntax`, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, `noImplicitOverride`, `isolatedDeclarations`.
+
+## Build Outputs
+
+`bun run build` runs two steps in sequence:
+
+1. **`build:lib`** — `tsc --project tsconfig.build.json` → `dist/*.js` + `dist/*.d.ts`
+2. **`build:lib-bundle`** — `scripts/build-lib-bundle.ts` → `dist/index.bundle.js` (ESM, minified) + `dist/index.iife.js` (IIFE, minified)
+
+The `exports` field in `package.json` maps consumers to the right file:
+
+| Condition | File |
+|-----------|------|
+| `types` | `dist/index.d.ts` |
+| `browser` | `dist/index.bundle.js` |
+| `import` | `dist/index.js` |
+
+## Package Configuration
+
+Key `package.json` fields:
+
+- `"sideEffects": false` — enables full tree-shaking by bundlers
+- `"imports": { "#src/*.js": "./src/*.ts" }` — package-internal alias for `src/`; use as `import { foo } from "#src/module.js"`. **Only for `dev.ts`, `tests/`, and `scripts/`** — not for library source files compiled by `tsconfig.build.json`, as tsc emits the specifier verbatim and it would break in published unbundled output.
+
+## Publishing
+
+See [README.md](README.md) for registry setup and publish commands.

package/template/README.md

@@ -0,0 +1,81 @@
+# Introduction
+
+*<INTRO TEXT>*
+
+## Table of Contents
+
+1. [Quick Start](#quick-start)
+2. [Documentation](#documentation)
+3. [DevOps](#devops)
+    1. [Change Management](#change-management)
+    2. [Publish](#publish)
+
+# Quick Start
+
+```bash
+# remove dist/ and tsconfig.build.tsbuildinfo
+bun run clean
+
+# remove dist/ only
+bun run clean:dist
+
+# remove tsconfig.build.tsbuildinfo only
+bun run clean:tsbuildinfo
+
+# compile + bundle
+bun run build
+
+# run tests
+bun run tests
+
+# run src/dev.ts in watch mode
+bun run dev
+```
+
+**Publish** — see [Publish](#publish).
+
+# Documentation
+
+*<DOCUMENTATION>*
+
+# DevOps
+
+## Change Management
+
+1. Create a new branch for the change.
+2. Make the changes and commit.
+3. Bump the version in [`package.json`](package.json).
+4. Add an entry for the new version in [`CHANGELOG.md`](CHANGELOG.md).
+5. Run `bun run build`.
+6. Pull request the branch and publish.
+
+## Publish
+
+### `npmjs.org`
+
+⚠️ Authenticate first: run `npm login` or configure `~/.npmrc` or `bunfig.toml` with an auth token.
+
+```powershell
+bun publish --registry https://registry.npmjs.org/ --access public
+```
+
+### Custom registry
+
+```bash
+# placeholder:
+    # <SCOPE_WITHOUT_AT: <SCOPE_WITHOUT_AT>
+    # <REGISTRY_URL: <REGISTRY_URL>
+    # <BUN_PUBLISH_AUTH_TOKEN: <BUN_PUBLISH_AUTH_TOKEN>
+```
+
+`bunfig.toml`:
+
+```toml
+[install.scopes]
+<SCOPE_WITHOUT_AT> = { url = "<REGISTRY_URL>", token = "$BUN_PUBLISH_AUTH_TOKEN" }
+```
+
+```powershell
+$env:BUN_PUBLISH_AUTH_TOKEN = "<BUN_PUBLISH_AUTH_TOKEN>"
+bun publish
+```

package/template/gitignore

@@ -0,0 +1,4 @@
+dist
+node_modules
+buildinfo.txt
+*.tsbuildinfo

package/template/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "",
+  "version": "0.0.0",
+  "description": "",
+  "author": "",
+  "license": "",
+  "keywords": [
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "entrypoint": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "browser": "./dist/index.bundle.js",
+      "import": "./dist/index.js"
+    }
+  },
+  "imports": {
+    "#src/*.js": "./src/*.ts"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "buildinfo.txt"
+  ],
+  "scripts": {
+    "clean:dist": "rm -rf dist/",
+    "clean:tsbuildinfo": "rm -f tsconfig.build.tsbuildinfo",
+    "clean": "bun run clean:dist && bun run clean:tsbuildinfo",
+    "prebuild": "bun run scripts/buildinfo.ts",
+    "tests": "bun test",
+    "build": "bun run build:lib && bun run build:lib-bundle",
+    "build:lib": "tsc --project tsconfig.build.json",
+    "build:lib-bundle": "bun run scripts/build-lib-bundle.ts",
+    "typecheck": "tsc --noEmit",
+    "dev": "bun run --watch src/dev.ts"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.9.3"
+  }
+}

package/template/scripts/build-lib-bundle.ts

@@ -0,0 +1,156 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import CDN_REWRITE_MAP from './cdn-rewrite-map.json';
+
+
+interface ExportConditions {
+    [key: string]: string | undefined;
+    import?: string;
+    types?: string;
+    browser?: string;
+    entrypoint?: string;
+}
+
+interface DependencyMap {
+    [packageName: string]: string;
+}
+
+interface PackageManifest {
+    version: string;
+    exports?: Record<string, ExportConditions>;
+    dependencies?: DependencyMap;
+    devDependencies?: DependencyMap;
+    peerDependencies?: DependencyMap;
+}
+
+function getManifest(packageIdentifier?: string): PackageManifest {
+
+    const manifestPath = packageIdentifier
+        ? join('node_modules', packageIdentifier, 'package.json')
+        : 'package.json';
+
+    let manifest: PackageManifest;
+    try {
+        manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    } catch {
+        if (packageIdentifier)
+            throw new Error("[scripts/build-lib-bundle.ts] Could not read manifest for '" + packageIdentifier + "' at '" + manifestPath + "'. Is it installed?");
+        else
+            throw new Error("[scripts/build-lib-bundle.ts] Could not read package manifest at '" + manifestPath + "'.");
+    }
+
+    return manifest;
+
+}
+
+function getManifestEntrypoints(packageManifest: PackageManifest): string[] {
+
+    const exports = packageManifest.exports;
+    if (!exports) throw new Error('[scripts/build-lib-bundle.ts] No exports field found in package.json.');
+
+    const entrypoints = Object.entries(exports)
+        .map(([key, conditions]) => {
+            if (!conditions.entrypoint) throw new Error(`[scripts/build-lib-bundle.ts] Export '${key}' does not have an 'entrypoint' condition.`);
+            return conditions.entrypoint;
+        });
+
+    return entrypoints;
+
+}
+
+function getPackageVersion(manifest: PackageManifest, packageIdentifier?: string): string {
+
+    let version: string | undefined;
+    if (packageIdentifier) {
+
+        const dependencies = {
+            ...manifest.dependencies,
+            ...manifest.devDependencies,
+            ...manifest.peerDependencies,
+        };
+
+        version = dependencies[packageIdentifier];
+        if (!version) throw new Error(`[scripts/build-lib-bundle.ts] Package '${packageIdentifier}' is not listed in dependencies.`);
+
+    }
+    else {
+        if (!manifest.version) throw new Error('[scripts/build-lib-bundle.ts] Package manifest does not contain a version field.');
+        version = manifest.version;
+    }
+
+    return version;
+
+}
+
+function resolveCdnUrl(importSpecifier: string, urlTemplate: string): string {
+    const manifest = getManifest();
+    const version = getPackageVersion(manifest, importSpecifier);
+    return urlTemplate.replace('<VERSION>', version);
+}
+
+const cdnRewritePlugin = {
+    name: 'cdn-rewrite',
+    setup(build: any) {
+
+        const resolved = new Map<string, string>();
+        for (const [importSpecifier, urlTemplate] of Object.entries(CDN_REWRITE_MAP) as [string, string][]) {
+            const url = resolveCdnUrl(importSpecifier, urlTemplate);
+            resolved.set(importSpecifier, url);
+            console.log(`[cdn-rewrite] '${importSpecifier}' → '${url}'`);
+        }
+
+        build.onResolve({ filter: /.*/ }, (args: any) => {
+            const url = resolved.get(args.path);
+            if (url) return { path: url, external: true };
+        });
+
+    },
+};
+
+
+const entrypoints = getManifestEntrypoints(getManifest());
+console.log('[scripts/build-lib-bundle.ts] Entrypoints:', entrypoints);
+
+let buildResult;
+
+console.log('[scripts/build-lib-bundle.ts] Starting ESM bundle build...');
+buildResult = await Bun.build({
+    entrypoints,
+    outdir: 'dist',
+    naming: '[dir]/[name].bundle.[ext]',
+    target: 'browser',
+    format: 'esm',
+    minify: true,
+    sourcemap: 'external',
+    plugins: [cdnRewritePlugin],
+});
+
+if (!buildResult.success) {
+    console.error('[scripts/build-lib-bundle.ts] Build failed:');
+    for (const message of buildResult.logs) {
+        console.error(message);
+    }
+    process.exit(1);
+}
+console.log('[scripts/build-lib-bundle.ts] ESM bundle build completed successfully.');
+
+console.log('[scripts/build-lib-bundle.ts] Starting IIFE bundle build...');
+buildResult = await Bun.build({
+    entrypoints,
+    outdir: 'dist',
+    naming: '[dir]/[name].iife.[ext]',
+    target: 'browser',
+    format: 'iife',
+    minify: true,
+    sourcemap: 'external',
+    plugins: [cdnRewritePlugin],
+});
+
+if (!buildResult.success) {
+    console.error('[scripts/build-lib-bundle.ts] Build failed:');
+    for (const message of buildResult.logs) {
+        console.error(message);
+    }
+    process.exit(1);
+}
+console.log('[scripts/build-lib-bundle.ts] IIFE bundle build completed successfully.');

package/template/scripts/buildinfo.ts

@@ -0,0 +1,21 @@
+import { execSync } from 'child_process';
+import { writeFileSync } from 'fs';
+
+
+const BUILD_INFO_FILE = 'buildinfo.txt';
+const GIT_COMMAND = 'git rev-parse --short HEAD';
+
+const version = process.env.npm_package_version ?? '0.0.0';
+
+let gitHash = '';
+try {
+    gitHash = execSync(GIT_COMMAND, { stdio: ['ignore', 'pipe', 'ignore'] })
+        .toString()
+        .trim();
+} catch { }
+
+const buildinfo = gitHash ? `${version}+${gitHash}` : version;
+
+writeFileSync(BUILD_INFO_FILE, buildinfo);
+
+console.log(`'${BUILD_INFO_FILE}' has been updated with build info: ${buildinfo}`);

package/template/scripts/cdn-rewrite-map.json

@@ -0,0 +1 @@
+{}

package/template/src/dev.ts

@@ -0,0 +1,15 @@
+import { buildinfoUrl, changelogUrl, distUrl } from '#src/urls.js';
+import { fileURLToPath } from 'url';
+
+
+const start: number = performance.now();
+
+console.log(`'distPath':`, fileURLToPath(distUrl));
+console.log(`'buildinfoPath':`, fileURLToPath(buildinfoUrl));
+console.log(`'changelogPath':`, fileURLToPath(changelogUrl));
+
+
+// dev code
+
+
+console.log(`${(performance.now() - start).toFixed(3)}ms`);

package/template/src/urls.ts

@@ -0,0 +1,3 @@
+export const distUrl: URL = new URL('.', import.meta.url);
+export const changelogUrl: URL = new URL('../CHANGELOG.md', distUrl);
+export const buildinfoUrl: URL = new URL('../buildinfo.txt', distUrl);

package/template/tests/buildinfo.test.ts

@@ -0,0 +1,28 @@
+import { describe, it, expect } from 'bun:test';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { buildinfoUrl } from '#src/urls.js';
+
+
+describe('buildInfo', () => {
+
+    it('should follow semantic versioning format with optional commit hash', () => {
+        const buildinfoPath = fileURLToPath(buildinfoUrl);
+        const buildinfo = readFileSync(buildinfoPath, 'utf-8').trim();
+        expect(buildinfo).toMatch(/^\d+\.\d+\.\d+(\+[0-9a-f]+)?$/);
+    });
+
+    it('should not contain whitespace', () => {
+        const buildinfoPath = fileURLToPath(buildinfoUrl);
+        const buildinfo = readFileSync(buildinfoPath, 'utf-8').trim();
+        expect(buildinfo).not.toMatch(/\s/);
+    });
+
+    it('should not be empty or dash', () => {
+        const buildinfoPath = fileURLToPath(buildinfoUrl);
+        const buildinfo = readFileSync(buildinfoPath, 'utf-8').trim();
+        expect(buildinfo.length).toBeGreaterThan(0);
+        expect(buildinfo).not.toBe('-');
+    });
+
+});

package/template/tsconfig.build.json

@@ -0,0 +1,19 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "emitDeclarationOnly": false,
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "src/dev.ts",
+    "node_modules",
+    "dist",
+    "tests",
+    "scripts"
+  ]
+}

package/template/tsconfig.json

@@ -0,0 +1,37 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": [
+      "ES2022",
+      "DOM"
+    ],
+    "moduleResolution": "bundler",
+    "strict": true,
+    "verbatimModuleSyntax": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "isolatedDeclarations": true,
+    "esModuleInterop": true,
+    "composite": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "outDir": "./dist",
+    "rootDir": ".",
+  },
+  "include": [
+    "src/**/*.ts",
+    "tests/**/*.ts",
+    "scripts/**/*.ts",
+    "scripts/**/*.json"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}