@temir.ra/create-ts-lib 0.6.0 → 0.6.3

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Version 0
 
+## 0.6.3
+
+1. Cleaned up dormant package scripts.
+2. Cleaned up minor `README.md` inconsistencies.
+
+## 0.6.2
+
+1. Updated `clean:tsbuildinfo` script to remove both `tsconfig.tsbuildinfo` and `tsconfig.build.tsbuildinfo`.
+
+## 0.6.1
+
+1. Cleaned up dormant imports.
+2. Cleaned up / updated minor `README.md` inconsistencies.
+3. Updated placeholders in `README.md` in the **Asset resolution** section.
+4. Removed **Asset resolution** section from the generated `README.md`, as the operational passage is given in the template `README.md`.
+5. Removed **AI Assistant Context** section from the `README.md` files.
+7. Cleaned up **Publish** section in the `README.md`.
+
 ## 0.6.0
 
 1. Updated documentation and configs to TypeScript 6.

package/README.md

@@ -5,8 +5,7 @@ A template for TypeScript libraries distributed via npm-compatible registries. P
 ## Table of Contents
 
 1. [Quick Start](#quick-start)
-2. [AI Assistant Context](#ai-assistant-context)
-3. [Documentation](#documentation)
+2. [Documentation](#documentation)
     1. [`tsconfig.json` and `tsconfig.build.json`](#tsconfigjson-and-tsconfigbuildjson)
     2. [`package.json`](#packagejson)
     3. [Script `scripts/buildinfo.ts`](#script-scriptsbuildinfots)
@@ -22,11 +21,9 @@ A template for TypeScript libraries distributed via npm-compatible registries. P
             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)
-4. [DevOps](#devops)
+3. [DevOps](#devops)
     1. [Change Management](#change-management)
     2. [Publish](#publish)
-        1. [npmjs.org](#npmjsorg)
-        2. [Custom registry](#custom-registry)
 
 # Quick Start
 
@@ -54,15 +51,9 @@ cd <NEW_PACKAGE>
 bun install
 ```
 
-# AI Assistant Context
-
-To generate an AI coding assistant context file for this project:
-
-> Generate an AI coding assistant context file. Analyze the project structure and source files, using this README as the primary reference for architecture and conventions. Give particular attention to: the dual tsconfig setup and the import constraints it imposes, the `#src/*.js` alias and where it may and may not be used, the custom `entrypoint` export condition, and the asset resolution contract.
-
 # Documentation
 
-The following sections explain the configurations and conventions baked into the generated package. Useful when adapting the generated package to fit a specific library's needs.
+The following sections explain the configurations and conventions baked into the generated package. Useful when adapting it to fit specific needs.
 
 ## `tsconfig.json` and `tsconfig.build.json`
 
@@ -78,6 +69,7 @@ See the typescriptlang documentation on [tsconfig.json](https://www.typescriptla
     "target": "ESNext",
 
     // output module format; ESNext passes ES module syntax through unchanged
+    // ES module syntax: import/export statements (as opposed to CommonJS require()/module.exports)
     "module": "ESNext",
 
     // type definitions for built-in APIs
@@ -252,7 +244,7 @@ See npmjs documentation on [package.json](https://docs.npmjs.com/cli/v11/configu
   "scripts": {
 
     "clean:dist": "rm -rf dist/",
-    "clean:tsbuildinfo": "rm -f tsconfig.build.tsbuildinfo",
+    "clean:tsbuildinfo": "rm -f tsconfig.tsbuildinfo tsconfig.build.tsbuildinfo",
     "clean": "bun run clean:dist && bun run clean:tsbuildinfo",
 
     // lifecycle hook; runs automatically before "build"; generates buildinfo.txt
@@ -266,8 +258,6 @@ See npmjs documentation on [package.json](https://docs.npmjs.com/cli/v11/configu
     // 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
@@ -322,14 +312,21 @@ For CLI packages, add the following to `package.json`:
 
 The key question to ask is: **does my library retain its own URL at runtime?** Everything else follows from it.
 
+```bash
+# placeholder:
+  # <@SCOPE: <@SCOPE>
+  # <LIB_NAME: <LIB_NAME>
+  # <VERSION: <VERSION>
+```
+
 ### 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-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
+https://cdn.jsdelivr.net/npm/<@SCOPE>/<LIB_NAME>@<VERSION>/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. `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.
@@ -361,12 +358,12 @@ Place all runtime assets under a scoped directory that mirrors the package name:
 
 ```
 assets/
-└── @scope/
-    └── lib-name/
-        └── <ASSETS>
+└── <@SCOPE>/
+    └── <LIB_NAME>/
+        └── ...
 ```
 
-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.
+This also 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 that the assets are included in the published package:
 
@@ -385,13 +382,13 @@ 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);
+const assetsUrl  = new URL('assets/<@SCOPE>/<LIB_NAME>/', packageUrl);
 
 // for --target browser
 const asset = await fetch(new URL('<ASSET>', assetsUrl)).then(r => r.json());
 
 // for --target node
-import { readFile } from 'node:fs/promises';
+import { readFile } from 'fs/promises';
 import { fileURLToPath } from 'url';
 const asset = JSON.parse(await readFile(fileURLToPath(new URL('<ASSET>', assetsUrl)), 'utf-8'));
 ```
@@ -399,14 +396,9 @@ const asset = JSON.parse(await readFile(fileURLToPath(new URL('<ASSET>', assetsU
 ### README statement for library consumers
 
 ```markdown
-<!-- placeholder:
-    <SCOPE: <SCOPE>
-    <LIB_NAME: <LIB_NAME>
- -->
-
 ## 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.
+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
@@ -417,12 +409,12 @@ The consumer must copy the assets into their build output at the same relative p
 consumer output/
 ├── bundle.js               ← import.meta.url points here
 └── assets/
-    └── @scope/
-        └── lib-name/
-            └── <ASSETS>    ← copied; relative path preserved
+    └── <@SCOPE>/
+        └── <LIB_NAME>/
+            └── ...         ← 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/<ASSETS>', import.meta.url)` resolves correctly. No code configuration is needed - only the file copy.
+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>/...', import.meta.url)` resolves correctly. No code configuration is needed - only the file copy.
 
 ## `src/dev.ts`
 
@@ -431,13 +423,13 @@ Development scratchpad - not published, excluded from `tsconfig.build.json`. Run
 # DevOps
 
 ```bash
-# remove dist/ and tsconfig.build.tsbuildinfo
+# remove dist/ and tsconfig.tsbuildinfo and tsconfig.build.tsbuildinfo
 bun run clean
 
 # remove dist/ only
 bun run clean:dist
 
-# remove tsconfig.build.tsbuildinfo only
+# remove tsconfig.tsbuildinfo and tsconfig.build.tsbuildinfo only
 bun run clean:tsbuildinfo
 
 # compile + bundle
@@ -459,15 +451,6 @@ bun run dist/cli.bundle.js -- example
 
 ## Publish
 
-See the following sources to configure the target registry and authentication.
-
-- [Configuring npm - `npmrc`](https://docs.npmjs.com/cli/v10/configuring-npm/npmrc)
-- [Bun package manager - `install.registry`](https://bun.com/docs/runtime/bunfig#install-scopes)
-
-⚠️ Package Scope and the authentication for the target registry must be aligned.
-
-### `npmjs.org`
-
 Publish to the public npm registry.
 
 ```powershell
@@ -476,26 +459,3 @@ npm login
 # publish
 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` or `bunfig.toml`:
-
-```toml
-[install.scopes]
-"<SCOPE_WITHOUT_AT>" = { url = "<REGISTRY_URL>", token = "$BUN_PUBLISH_AUTH_TOKEN" }
-```
-
-```powershell
-# authenticate
-$env:BUN_PUBLISH_AUTH_TOKEN = "<BUN_PUBLISH_AUTH_TOKEN>"
-# publish
-bun publish
-```

package/buildinfo.txt

@@ -1 +1 @@
-0.6.0+bf23035
+0.6.3+0b0d257

package/dist/cli.bundle.js.map

@@ -2,7 +2,7 @@
   "version": 3,
   "sources": ["..\\src\\cli.ts", "..\\src\\constants.ts"],
   "sourcesContent": [
-    "#!/usr/bin/env node\r\n\r\nimport { cpSync, readFileSync, renameSync, writeFileSync } from 'fs';\r\nimport { resolve, basename } from 'path';\r\nimport {\r\n    templatePath,\r\n    changelogPath,\r\n    buildinfoPath,\r\n    readmePath\r\n} from './constants.js';\r\n\r\n\r\ntry {\r\n\r\n    const packageNameArgument = process.argv[2];\r\n    if (!packageNameArgument) throw new Error('Package name argument is required. Usage: `create-ts-lib <package-name>`');\r\n    const packageName = packageNameArgument.replace(/\\\\/g, '/');\r\n\r\n    const destinationPath = resolve(process.cwd(), packageName);\r\n\r\n    cpSync(templatePath, destinationPath, { recursive: true });\r\n    cpSync(changelogPath, resolve(destinationPath, 'CHANGELOG-template.md'));\r\n    cpSync(buildinfoPath, resolve(destinationPath, 'buildinfo-template.txt'));\r\n    cpSync(readmePath, resolve(destinationPath, 'README-template.md'));\r\n\r\n    const packageJsonPath = resolve(destinationPath, 'package.json');\r\n    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));\r\n    packageJson.name = packageName;\r\n    writeFileSync(packageJsonPath, JSON.stringify(packageJson, 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",
+    "#!/usr/bin/env node\r\n\r\nimport { cpSync, readFileSync, renameSync, writeFileSync } from 'fs';\r\nimport { resolve } from 'path';\r\nimport {\r\n    templatePath,\r\n    changelogPath,\r\n    buildinfoPath,\r\n    readmePath\r\n} from './constants.js';\r\n\r\n\r\ntry {\r\n\r\n    const packageNameArgument = process.argv[2];\r\n    if (!packageNameArgument) throw new Error('Package name argument is required. Usage: `create-ts-lib <package-name>`');\r\n    const packageName = packageNameArgument.replace(/\\\\/g, '/');\r\n\r\n    const destinationPath = resolve(process.cwd(), packageName);\r\n\r\n    cpSync(templatePath, destinationPath, { recursive: true });\r\n    cpSync(changelogPath, resolve(destinationPath, 'CHANGELOG-template.md'));\r\n    cpSync(buildinfoPath, resolve(destinationPath, 'buildinfo-template.txt'));\r\n    cpSync(readmePath, resolve(destinationPath, 'README-template.md'));\r\n\r\n    const packageJsonPath = resolve(destinationPath, 'package.json');\r\n    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));\r\n    packageJson.name = packageName;\r\n    writeFileSync(packageJsonPath, JSON.stringify(packageJson, 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",
     "import { resolve } from 'path';\r\nimport { fileURLToPath } from 'url';\r\n\r\n\r\nexport const packageUrl: URL = new URL('../', import.meta.url);\r\nexport const packagePath: string = resolve(fileURLToPath(packageUrl));\r\n\r\nexport const templatePath: string = resolve(packagePath, 'template/');\r\n\r\nexport const changelogPath: string = resolve(packagePath, 'CHANGELOG.md');\r\nexport const buildinfoPath: string = resolve(packagePath, 'buildinfo.txt');\r\nexport const readmePath: string = resolve(packagePath, 'README.md');\r\n"
   ],
   "mappings": ";AAEA,iBAAS,kBAAQ,gBAAc,mBAAY,WAC3C,kBAAS,aCHT,kBAAS,aACT,wBAAS,YAGF,IAAM,EAAkB,IAAI,IAAI,MAAO,YAAY,GAAG,EAChD,EAAsB,EAAQ,EAAc,CAAU,CAAC,EAEvD,EAAuB,EAAQ,EAAa,WAAW,EAEvD,EAAwB,EAAQ,EAAa,cAAc,EAC3D,EAAwB,EAAQ,EAAa,eAAe,EAC5D,EAAqB,EAAQ,EAAa,WAAW,EDClE,GAAI,CAEA,IAAM,EAAsB,QAAQ,KAAK,GACzC,GAAI,CAAC,EAAqB,MAAU,MAAM,0EAA0E,EACpH,IAAM,EAAc,EAAoB,QAAQ,MAAO,GAAG,EAEpD,EAAkB,EAAQ,QAAQ,IAAI,EAAG,CAAW,EAE1D,EAAO,EAAc,EAAiB,CAAE,UAAW,EAAK,CAAC,EACzD,EAAO,EAAe,EAAQ,EAAiB,uBAAuB,CAAC,EACvE,EAAO,EAAe,EAAQ,EAAiB,wBAAwB,CAAC,EACxE,EAAO,EAAY,EAAQ,EAAiB,oBAAoB,CAAC,EAEjE,IAAM,EAAkB,EAAQ,EAAiB,cAAc,EACzD,EAAc,KAAK,MAAM,EAAa,EAAiB,OAAO,CAAC,EACrE,EAAY,KAAO,EACnB,EAAc,EAAiB,KAAK,UAAU,EAAa,KAAM,CAAC,CAAC,EAEnE,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",

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { cpSync, readFileSync, renameSync, writeFileSync } from 'fs';
-import { resolve, basename } from 'path';
+import { resolve } from 'path';
 import { templatePath, changelogPath, buildinfoPath, readmePath } from './constants.js';
 try {
     const packageNameArgument = process.argv[2];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temir.ra/create-ts-lib",
-  "version": "0.6.0",
+  "version": "0.6.3",
   "description": "Typescript library template",
   "author": "temir.ra",
   "license": "MIT",
@@ -27,15 +27,14 @@
   ],
   "scripts": {
     "clean:dist": "rm -rf dist/",
-    "clean:tsbuildinfo": "rm -f tsconfig.build.tsbuildinfo",
+    "clean:tsbuildinfo": "rm -f tsconfig.tsbuildinfo 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"
+    "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/template/README.md

@@ -5,9 +5,8 @@
 ## Table of Contents
 
 1. [Quick Start](#quick-start)
-2. [AI Assistant Context](#ai-assistant-context)
-3. [Documentation](#documentation)
-4. [DevOps](#devops)
+2. [Documentation](#documentation)
+3. [DevOps](#devops)
     1. [Change Management](#change-management)
     2. [Publish](#publish)
         1. [npmjs.org](#npmjsorg)
@@ -16,13 +15,13 @@
 # Quick Start
 
 ```bash
-# remove dist/ and tsconfig.build.tsbuildinfo
+# remove dist/ and tsconfig.tsbuildinfo and tsconfig.build.tsbuildinfo
 bun run clean
 
 # remove dist/ only
 bun run clean:dist
 
-# remove tsconfig.build.tsbuildinfo only
+# remove tsconfig.tsbuildinfo and tsconfig.build.tsbuildinfo only
 bun run clean:tsbuildinfo
 
 # compile + bundle
@@ -35,30 +34,10 @@ bun run tests
 bun run dev
 ```
 
-**Publish** - see [Publish](#publish).
-
-# AI Assistant Context
-
-To generate an AI coding assistant context file for this project:
-
-> Generate an AI coding assistant context file. `README-template.md` is available now and documents the architectural conventions of this package — use it as your primary source. The generated context file must be self-contained: `README-template.md` will be deleted after context generation, so do not reference it in the output. Give particular attention to: the dual tsconfig setup and the import constraints it imposes, the `#src/*.js` alias and where it may and may not be used, the custom `entrypoint` export condition, and the asset resolution contract.
-
 # Documentation
 
 *<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
@@ -95,9 +74,9 @@ bun publish --registry https://registry.npmjs.org/ --access public
 
 ```bash
 # placeholder:
-    # <SCOPE_WITHOUT_AT: <SCOPE_WITHOUT_AT>
-    # <REGISTRY_URL: <REGISTRY_URL>
-    # <BUN_PUBLISH_AUTH_TOKEN: <BUN_PUBLISH_AUTH_TOKEN>
+  # <SCOPE_WITHOUT_AT: <SCOPE_WITHOUT_AT>
+  # <REGISTRY_URL: <REGISTRY_URL>
+  # <BUN_PUBLISH_AUTH_TOKEN: <BUN_PUBLISH_AUTH_TOKEN>
 ```
 
 `~/.bunfig.toml` or `bunfig.toml`:

package/template/package.json

@@ -30,7 +30,7 @@
   ],
   "scripts": {
     "clean:dist": "rm -rf dist/",
-    "clean:tsbuildinfo": "rm -f tsconfig.build.tsbuildinfo",
+    "clean:tsbuildinfo": "rm -f tsconfig.tsbuildinfo tsconfig.build.tsbuildinfo",
     "clean": "bun run clean:dist && bun run clean:tsbuildinfo",
     "prebuild": "bun run scripts/buildinfo.ts",
     "tests": "bun test",