@temir.ra/create-ts-lib 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Version 0
 
+## 0.2.4
+
+1. Documented template caching in the Quick Start section with commands to pin the version or clear the cache.
+2. Minor README updates: Revised Asset Resolution sections in root and template; Added introductory paragraph to Documentation section;
+3. Moved git-upstream to `https://git.chimps.quest/trs/create-ts-lib.git`.
+
+## 0.2.3
+
+1. Updated change management workflow in `README.md` and `template/README.md`: build step now happens after merge (not before PR), so `buildinfo.txt` captures the correct git hash and artifacts are up to date before publish.
+2. Added Change Management section to root and template `CLAUDE.md`.
+
 ## 0.2.2
 
 1. Fixed `CHANGELOG.md` and `buildinfo.txt` copy paths in `cli.ts`: they were resolved relative to `template/` instead of the package root, causing the copy to fail. Refactored URL/path construction to derive all paths from a single `packageUrl`, eliminating redundant `fileURLToPath` calls at each copy site.

package/README.md

@@ -11,9 +11,17 @@ A template for TypeScript libraries distributed via npm-compatible registries. P
     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. [Asset Resolution](#asset-resolution)
-    7. [`src/dev.ts`](#srcdevts)
-    8. [`CLAUDE.md` / `AGENTS.md`](#claudemd--agentsmd)
+    6. [`"bin"` field in `package.json`](#bin-field-in-packagejson)
+    7. [Asset Resolution](#asset-resolution)
+        1. [Externalized - loaded from CDN or `node_modules/`](#externalized---loaded-from-cdn-or-node_modules)
+        2. [Bundled - absorbed into the consumer's output](#bundled---absorbed-into-the-consumers-output)
+        3. [Contract](#contract)
+            1. [Scoped assets directory convention](#scoped-assets-directory-convention)
+            2. [Accessing assets](#accessing-assets)
+            3. [README statement for library consumers](#readme-statement-for-library-consumers)
+            4. [When the library is bundled by the consumer](#when-the-library-is-bundled-by-the-consumer)
+    8. [`src/dev.ts`](#srcdevts)
+    9. [`CLAUDE.md` / `AGENTS.md`](#claudemd--agentsmd)
 3. [DevOps](#devops)
     1. [Build](#build)
     2. [Change Management](#change-management)
@@ -23,17 +31,34 @@ A template for TypeScript libraries distributed via npm-compatible registries. P
 
 # Quick Start
 
+*`bun create` caches the template package - a newer published version will not be picked up automatically. Pin the version or clear the cache to use the latest.*
+
 ```bash
 # placeholder:
-    # <PACKAGE: <PACKAGE>
+    # <NEW_PACKAGE: <NEW_PACKAGE>
+    # <@_VERSION: <@_VERSION>
+
+# identify the latest version of the template package as <@_VERSION.
+bun info "@temir.ra/create-ts-lib" version
+# create a new library from the template version
+bun create --no-install --no-git "@temir.ra/ts-lib<@_VERSION>" <NEW_PACKAGE>
+
+# or
+
+# clear package manager cache to ensure the latest template version is used
+bun pm cache rm
+# create a new library from the latest template version
+bun create --no-install --no-git "@temir.ra/ts-lib" <NEW_PACKAGE>
 
-bun create --no-install --no-git "@temir.ra/ts-lib" <PACKAGE>
-cd <PACKAGE>
+# dependencies must be installed manually
+cd <NEW_PACKAGE>
 bun install
 ```
 
 # Documentation
 
+The following sections explain the configurations and conventions baked into the generated package. Useful when adapting the template to fit a specific library's needs.
+
 ## `tsconfig.json` and `tsconfig.build.json`
 
 ```json
@@ -286,25 +311,42 @@ For CLI packages, add the following to `package.json`:
 
 ## Asset Resolution
 
-The key question to ask is: **does my library retain its own URL at runtime?** Module identity is the invariant. Everything else follows from it.
+The key question to ask is: **does my library retain its own URL at runtime?** Everything else follows from it.
 
-### Externalized - loaded from CDN or node_modules
+### Externalized - loaded from CDN or `node_modules/`
 
 The consumer does not bundle the library. It is loaded as a discrete module at runtime. Module identity is preserved regardless of the URL form:
 
 ```
-https://cdn.jsdelivr.net/npm/@scope/lib@1.0.0/dist/index.js
-file:///project/node_modules/@scope/lib/dist/index.js
-https://your-own-cdn.com/lib/index.js
+https://cdn.jsdelivr.net/npm/@scope/lib-name@1.0.0/dist/index.js
+file:///project/node_modules/@scope/lib-name/dist/index.js
+https://your-own-cdn.com/lib-name/index.js
 ```
 
-`import.meta.url` is reliable in all these cases. Asset paths resolve automatically - the consumer does nothing. `fetch()` is the correct I/O mechanism because it accepts both `https://` and `file://` URLs, making it universally correct for isomorphic (browser + Node) libraries.
+`import.meta.url` is reliable in all these cases. `fetch()` is the correct I/O mechanism because it accepts both `https://` and `file://` URLs, making it universally correct for isomorphic (`--target node` or `--target browser`) libraries.
+
+### Bundled - absorbed into the consumer's output
+
+The consumer's bundler absorbs the library into their own output. Module identity is destroyed - `import.meta.url` now points to the consumer's bundle, not the library's. However, **the path relationship can be preserved by convention**: if the consumer copies the library's assets into their build output at the same relative path the library expects, `import.meta.url` resolution continues to work correctly.
+
+### Contract
+
+If the library has runtime assets, the following contract applies:
 
-### Bundled into the consumer's app
+**The library must:**
+1. **Place assets in a scoped assets directory** - see [Scoped assets directory convention](#scoped-assets-directory-convention) below.
+2. **Access assets via `import.meta.url`** - see [Accessing assets](#accessing-assets) below.
+3. **Document the bundled case** - see [README statement for library consumers](#readme-statement-for-library-consumers) below.
 
-The consumer's bundler absorbs the library into their own output file. Module identity is destroyed - `import.meta.url` now points to the consumer's bundle, not the library's file. However, **the path relationship can be preserved by convention**: if the consumer copies the library's assets into their build output at the same relative path the library expects, `import.meta.url` resolution continues to work correctly.
+**The consumer must,**
+- **when loading the library externalized:** do nothing - the library's `import.meta.url` works as-is, and assets load from their original location (CDN or `node_modules/`).
+- **when bundling the library:**
+    1. **Copy the assets** - see [When the library is bundled by the consumer](#when-the-library-is-bundled-by-the-consumer) below.
+    2. **Ensure the assets are served**
+        - if the consumer is a web server, ensure the copied assets are served as static files
+        - if the consumer is a bundler, ensure the copied assets are included in the bundle output
 
-### Scoped asset folder convention
+#### Scoped assets directory convention
 
 Place all runtime assets under a scoped directory that mirrors the package name:
 
@@ -312,13 +354,12 @@ Place all runtime assets under a scoped directory that mirrors the package name:
 assets/
 └── @scope/
     └── lib-name/
-        ├── schema.json
-        └── data.json
+        └── <ASSETS>
 ```
 
 This prevents naming collisions when multiple libraries are bundled into the same consumer app. Each library's assets live under their own namespace; no library can shadow another's files.
 
-Add `assets/` to the `files` field in `package.json` so npm publishes it:
+Add `assets/` to the `files` field in `package.json` so that the assets are included in the published package:
 
 ```json
   "files": [
@@ -329,93 +370,50 @@ Add `assets/` to the `files` field in `package.json` so npm publishes it:
   ],
 ```
 
-### Accessing assets
+#### Accessing assets
 
-Construct asset URLs directly from `import.meta.url`. Replace `@scope/lib-name` with your actual package name:
+Construct asset URLs directly from `import.meta.url`.
 
 ```typescript
 const packageUrl = new URL('../', import.meta.url);
 const assetsUrl  = new URL('assets/@scope/lib-name/', packageUrl);
 
-// isomorphic (browser or Node) - fetch accepts both https:// and file:// URLs
-const schema = await fetch(new URL('schema.json', assetsUrl)).then(r => r.json());
+// for --target browser
+const asset = await fetch(new URL('<ASSET>', assetsUrl)).then(r => r.json());
 
-// server-only (Node/Bun)
+// for --target node
 import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'url';
-const data = JSON.parse(await readFile(fileURLToPath(new URL('data.json', assetsUrl)), 'utf-8'));
+const asset = JSON.parse(await readFile(fileURLToPath(new URL('<ASSET>', assetsUrl)), 'utf-8'));
 ```
 
-`fetch()` is the correct I/O primitive for isomorphic libraries: it accepts both `https://` URLs (CDN/production) and `file://` URLs (node_modules/development) without any special handling.
+### README statement for library consumers
+
+```markdown
+<!-- placeholder:
+    <SCOPE: <SCOPE>
+    <LIB_NAME: <LIB_NAME>
+ -->
 
-> **Server-only libraries** (no browser target, bundled-into-consumer scenario unlikely): use `readFile` directly - `fetch()` is not required. The scoped asset convention still applies unchanged.
+## Asset resolution
 
-### When the library is bundled by the consumer
+This library resolves assets at runtime using `import.meta.url`. If you bundle this library into your application, copy `node_modules/<SCOPE>/<LIB_NAME>/assets/<SCOPE>/<LIB_NAME>/` into your build output directory alongside your bundle.
+```
+
+#### When the library is bundled by the consumer
 
 The consumer must copy the assets into their build output at the same relative path the library expects:
 
 ```
 consumer output/
-├── bundle.js                       ← import.meta.url points here
+├── bundle.js               ← import.meta.url points here
 └── assets/
     └── @scope/
         └── lib-name/
-            ├── schema.json         ← copied; relative path preserved
-            └── data.json
+            └── <ASSETS>    ← copied; relative path preserved
 ```
 
-From the bundle's perspective `assets/@scope/lib-name/` is at the same directory level as `bundle.js`, so `new URL('assets/@scope/lib-name/schema.json', import.meta.url)` resolves correctly. No code configuration is needed - only the file copy.
-
-### Setup
-
-If your library has runtime assets, the steps to wire everything up:
-
-1. **Create the scoped directory** `assets/@scope/lib-name/` and place asset files inside (replace `@scope/lib-name` with your actual package name).
-
-2. **Access assets via `import.meta.url`** - see [Accessing assets](#accessing-assets) above.
-
-3. **Publish the assets** - add `assets/` to the `files` field in `package.json`:
-   ```json
-    "files": [
-      "dist",
-      "CHANGELOG.md",
-      "buildinfo.txt",
-      "assets"
-    ],
-   ```
-
-4. **Document the bundled case** - copy the [README statement](#readme-statement-for-your-consumers) into your library's README.
-
-### Contract
-
-**The library must:**
-- Place assets under `assets/@scope/lib-name/` (mirroring the package name)
-- Resolve asset paths via `import.meta.url` - no shared helper file required
-- Include `assets/` in `package.json` `files`
-- Document the bundled-case copy requirement in its README
-
-**The consumer must, when bundling the library:**
-- Copy `node_modules/@scope/lib-name/assets/` into their build output alongside the bundle
-- Ensure assets are served
-
-**The consumer must do nothing when loading the library externalized.** Asset resolution is automatic.
-
-### Checklist
-
-- [ ] Assets live under `assets/@scope/lib-name/` (matching the package name)
-- [ ] `assets/` is listed in `package.json` `files`
-- [ ] All asset access resolves paths via `import.meta.url` - no hardcoded paths
-- [ ] Library README documents the bundled-case copy requirement (see statement below)
-
-### README statement for your consumers
-
-Copy this into your library's README:
-
-> **Asset resolution**
->
-> This library resolves assets at runtime using `import.meta.url`. It works automatically when the library is loaded as an external module (from CDN or node_modules).
->
-> If you bundle this library into your application, copy `node_modules/@scope/lib-name/assets/@scope/lib-name/` into your build output directory alongside your bundle. No code configuration is required.
+From the bundle's perspective `assets/@scope/lib-name/` is at the same directory level as `bundle.js`, so `new URL('assets/@scope/lib-name/<ASSETS>', import.meta.url)` resolves correctly. No code configuration is needed - only the file copy.
 
 ## `src/dev.ts`
 
@@ -453,8 +451,9 @@ bun run dist/cli.bundle.js -- example
 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.
+5. Pull request the branch.
+6. After merge, run `bun run build`.
+7. Publish
 
 ## Publish
 

package/buildinfo.txt

@@ -1 +1 @@
-0.2.2+77ce44b
+0.2.3+0a2de3a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temir.ra/create-ts-lib",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Typescript library template",
   "author": "temir.ra",
   "license": "MIT",
@@ -12,7 +12,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://git.temirs.cloud/trs/create-ts-lib.git"
+    "url": "https://git.chimps.quest/trs/create-ts-lib.git"
   },
   "type": "module",
   "sideEffects": false,

package/template/CLAUDE.md

@@ -77,30 +77,78 @@ import { Foo } from "./foo.js"            // ✗ — if Foo is only used as a ty
 
 ### Asset Resolution (if the library has runtime assets)
 
-Place runtime assets (JSON data, WASM, binary files, etc.) under a scoped directory that mirrors the package name — this prevents naming collisions when multiple libraries are bundled into the same consumer app:
+The key question: **does your library retain its own URL at runtime?** Everything else follows from it.
+
+- **Externalized** (loaded from CDN or `node_modules/`): `import.meta.url` is reliable as-is — no consumer action needed.
+- **Bundled** (absorbed into the consumer's output): `import.meta.url` points to the consumer's bundle, not the library's file. The path relationship can be preserved by convention — if the consumer copies the library's assets into their build output at the same relative path, resolution continues to work correctly.
+
+#### Contract
+
+**The library must:**
+1. Place assets in a scoped directory — `assets/@scope/lib-name/` (mirrors the package name, prevents collisions when multiple libraries share a consumer bundle).
+2. Access assets via `import.meta.url` — see code below.
+3. Document the bundled case in the library's README — see [README statement](#readme-statement-for-consumers) below.
+
+**The consumer must,**
+- **when loading the library externalized:** do nothing.
+- **when bundling the library:** copy `node_modules/@scope/lib-name/assets/` into their build output alongside the bundle, and ensure the assets are served.
+
+#### Scoped assets directory
 
 ```
-assets/@scope/lib-name/
-├── data.json
-└── model.wasm
+assets/
+└── @scope/
+    └── lib-name/
+        └── <ASSETS>
 ```
 
+Add `assets/` to `files` in `package.json` so it is included in the published package:
+
+```json
+"files": ["dist", "CHANGELOG.md", "buildinfo.txt", "assets"]
+```
+
+#### Accessing assets
+
 Resolve asset URLs inline from `import.meta.url` — no shared helper file:
 
 ```typescript
 const packageUrl = new URL('../', import.meta.url);
 const assetsUrl  = new URL('assets/@scope/lib-name/', packageUrl);
 
-// isomorphic (browser + Node) — fetch() handles both https:// and file:// URLs
+// for --target browser
 const data = await fetch(new URL('data.json', assetsUrl)).then(r => r.json());
 
-// server-only (Node/Bun)
+// for --target node
 import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'url';
 const raw = await readFile(fileURLToPath(new URL('data.json', assetsUrl)), 'utf-8');
 ```
 
-Add `assets/` to `files` in `package.json` so it is included in the published package. See the [create-ts-lib README](../README.md) Asset Resolution section for the full setup guide, checklist, and the README statement to copy for your consumers.
+#### When the library is bundled by the consumer
+
+The consumer must copy assets into their build output at the same relative path:
+
+```
+consumer output/
+├── bundle.js               ← import.meta.url points here
+└── assets/
+    └── @scope/
+        └── lib-name/
+            └── <ASSETS>    ← copied; relative path preserved
+```
+
+No code configuration needed — only the file copy.
+
+#### README statement for consumers
+
+Copy the following into the library's README (replace `<SCOPE>` and `<LIB_NAME>`):
+
+```markdown
+## Asset resolution
+
+This library resolves assets at runtime using `import.meta.url`. If you bundle this library into your application, copy `node_modules/<SCOPE>/<LIB_NAME>/assets/<SCOPE>/<LIB_NAME>/` into your build output directory alongside your bundle.
+```
 
 ### Tests
 
@@ -153,6 +201,16 @@ 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.
 
+## Change Management
+
+1. Branch off main.
+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. Pull request the branch.
+6. After merge, run `bun run build`. ← must happen after merge so `buildinfo.txt` captures the correct git hash, and before publish so the artifacts are up to date.
+7. Publish.
+
 ## Publishing
 
 See [README.md](README.md) for registry setup and publish commands.

package/template/README.md

@@ -36,10 +36,20 @@ bun run dev
 
 # Documentation
 
-> If this library has runtime assets, see the **Asset Resolution** section in the create-ts-lib README for the setup guide, code examples, checklist, and consumer README statement.
-
 *<DOCUMENTATION>*
 
+## Asset Resolution
+
+*<!-- Remove this section if the library has no runtime assets. Replace `@scope/lib-name` throughout with the actual package name. -->*
+
+Assets are placed under `assets/@scope/lib-name/` (scoped to the package name to prevent collisions). They are resolved at runtime via `import.meta.url` and loaded with `fetch()` (browser) or `readFile` (Node). `assets/` must be listed in `files` in `package.json`.
+
+`import.meta.url` is reliable when the library is loaded as a discrete module (from CDN or `node_modules/`). When the consumer bundles the library, they must copy the assets — see below.
+
+### For consumers bundling this library
+
+Copy `node_modules/@scope/lib-name/assets/` into your build output alongside the bundle, preserving the relative path. No code configuration is required — only the file copy.
+
 # DevOps
 
 ## Change Management
@@ -48,8 +58,9 @@ bun run dev
 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.
+5. Pull request the branch.
+6. After merge, run `bun run build`.
+7. Publish
 
 ## Publish