@temir.ra/create-workspace 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Version 0
+
+## 0.2.0
+
+1. Removed **AI Assistant Context** section from the `README.md` files.
+2. Alligned `README.md` with the `ts-lib@0.6.2` template.
+3. Cleaned up **Publish** section in `README.md`.
+4. Rephrased the `README.md` to reflect that the generated package is workspace-aware but not necessarily a root package.
+5. Renamed the package from `create-monorepo` to `create-workspace`.
+
+## 0.1.1
+
+1. Fixed upstream repository URL in package.json.
+
+## 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,320 @@
+# Introduction
+
+A template for a package with build metadata, tests, and workspace-aware scripts. The generated package works standalone; add a `workspaces` field to scale it into a monorepo.
+
+The following templates are available in this ecosystem:
+
+| Template | Purpose |
+|---|---|
+| [`create-ts-lib`](#create-ts-lib) | TypeScript library distributed via registry |
+| [`create-hono-server`](#create-hono-server) | Bun/Hono HTTP server |
+| [`create-hono-spa`](#create-hono-spa) | Frontend SPA as a Hono sub-app library |
+| [`create-workspace`](#packagejson) | Package with workspace support *(this template)* |
+
+## Table of Contents
+
+1. [Quick Start](#quick-start)
+2. [Documentation](#documentation)
+    1. [`package.json`](#packagejson)
+    2. [Workspaces](#workspaces)
+    3. [Cross-workspace Dependencies](#cross-workspace-dependencies)
+    4. [Scaffolding Patterns](#scaffolding-patterns)
+        1. [Library](#library)
+        2. [Server](#server)
+        3. [Server + SPA](#server--spa)
+        4. [Full-Stack with Shared Types](#full-stack-with-shared-types)
+3. [DevOps](#devops)
+    1. [Change Management](#change-management)
+    2. [Publish](#publish)
+
+# 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>
+    # <@_VERSION: <@_VERSION>
+
+# identify the latest version of the template package as <@_VERSION.
+bun info "@temir.ra/create-workspace" version
+# create a new package from the template version
+bun create --no-install --no-git "@temir.ra/create-workspace<@_VERSION>" <PACKAGE>
+
+# or
+
+# clear package manager cache to ensure the latest template version is used
+bun pm cache rm
+# create a new package from the latest template version
+bun create --no-install --no-git "@temir.ra/create-workspace" <PACKAGE>
+
+# dependencies must be installed manually
+cd <PACKAGE>
+bun install
+```
+
+# Documentation
+
+The following sections explain the configurations and conventions baked into the generated package. Useful when adapting it to fit specific needs.
+
+## `package.json`
+
+See npmjs documentation on [package.json](https://docs.npmjs.com/cli/v11/configuring-npm/package-json) for detailed explanations of all fields.
+
+```json
+{
+  "name": "",
+  "version": "0.0.0",
+
+  "description": "",
+  "author": "",
+  "license": "",
+
+  // prevents publishing to a registry
+  "private": true,
+
+  "scripts": {
+
+    // removes dist/
+    "clean:dist": "rm -rf dist/",
+
+    // removes dist/ and propagates clean to any workspace packages
+    "clean": "bun run clean:dist && bun run --filter '*' clean",
+
+    // generates buildinfo.txt before each build
+    "prebuild": "bun run scripts/buildinfo.ts",
+
+    // propagates build to any workspace packages
+    "build": "bun run --filter '*' build",
+
+    // runs local tests and propagates tests to any workspace packages
+    "tests": "bun test && bun run --filter '*' tests",
+
+    // propagates typecheck to any workspace packages
+    "typecheck": "bun run --filter '*' typecheck"
+
+  }
+
+}
+```
+
+The `--filter '*'` scripts forward to any workspace packages when a `workspaces` field is present; they are no-ops otherwise. See [Workspaces](#workspaces) for how to opt in.
+
+## Workspaces
+
+To extend the package into a monorepo, add a `workspaces` field to `package.json` and run `bun install`:
+
+```json
+{
+  "workspaces": [
+    "packages/*"
+  ]
+}
+```
+
+The execution environment installs all workspace dependencies into a single shared `node_modules/` at the root and symlinks each workspace package by its `name` field. Cross-workspace imports resolve by package name without path aliases or module mapping.
+
+```
+<PACKAGE>/
+├── package.json          ← root
+└── packages/
+    ├── pkg-a/
+    │   ├── package.json
+    │   └── ...
+    └── pkg-b/
+        ├── package.json
+        └── ...
+```
+
+### Cross-workspace Dependencies
+
+To use one workspace package from another, declare it as a dependency using the `workspace:` protocol:
+
+```json
+// packages/pkg-a/package.json
+{
+  "dependencies": {
+
+    // workspace: resolves to the local package instead of fetching from a registry;
+    // workspace:* tracks the exact local version;
+    // workspace:^ is replaced by ^version on publish, tracking the semver range in the registry
+    "@scope/pkg-b": "workspace:*"
+
+  }
+}
+```
+
+Run `bun install` after adding the entry. The execution environment creates the symlink in `node_modules/` so imports resolve by package name at runtime and at the type level - no path alias or `paths` mapping required.
+
+### Scaffolding Patterns
+
+Scaffold the package first, add `workspaces` to `package.json`, then scaffold workspace packages inside it. After scaffolding each workspace package, update its `package.json` with the correct `name`, `version`, `description`, `author`, `license`, and `repository` fields. To wire cross-workspace dependencies, add the `workspace:*` entry to the consuming package's `package.json` and run `bun install` from the root.
+
+#### Library
+
+```
+<package>/
+└── packages/
+    └── my-lib/        ← create-ts-lib
+```
+
+```bash
+bun create --no-install --no-git "@temir.ra/create-workspace" <package>
+cd <package>
+bun create --no-install --no-git "@temir.ra/ts-lib" packages/my-lib
+bun install
+```
+
+##### `create-ts-lib`
+
+Starting point for any package distributed via a registry. See the full documentation at [`@temir.ra/create-ts-lib`](https://www.npmjs.com/package/@temir.ra/create-ts-lib).
+
+- Dual `tsconfig`: `tsconfig.json` (dev, `bundler` resolution, includes `tests/` + `scripts/`) and `tsconfig.build.json` (prod, `nodenext`, `src/` only, emits JS + `.d.ts`)
+- `exports` conditions: `entrypoint` (custom, source entry for the bundle script), `types`, `browser` (bundled output), `import` (compiled ESM)
+- `imports` field: `#src/*.js` → `./src/*.ts` - runtime alias for `dev.ts`, `tests/`, `scripts/` only
+- Build metadata: `scripts/buildinfo.ts` generates `buildinfo.txt` (version + git hash) as a `prebuild` hook
+- Bundle script: `scripts/build-lib-bundle.ts` bundles via Bun; supports CDN specifier rewriting via `cdn-rewrite-map.json`
+- Asset resolution contract: assets under `assets/@scope/lib-name/`, accessed via `import.meta.url` + `fetch()`
+- Optional CLI entry point via `bin` field and `build:cli-bundle` script
+
+#### Server
+
+```
+<package>/
+└── packages/
+    └── server/        ← create-hono-server
+```
+
+```bash
+bun create --no-install --no-git "@temir.ra/create-workspace" <package>
+cd <package>
+bun create --no-install --no-git "@temir.ra/hono-server" packages/server
+bun install
+```
+
+##### `create-hono-server`
+
+Starting point for any HTTP backend. See the full documentation at [`@temir.ra/create-hono-server`](https://www.npmjs.com/package/@temir.ra/create-hono-server).
+
+- `createAppHost(options)` - configures and returns a `Hono<AppEnv>` instance
+- Built-in middleware pipeline: `Logging`, `requestId`, `RequestLogger`, `compress`, `secureHeaders`
+- Built-in endpoints: `/health`, `/buildinfo`, OpenAPI spec, Scalar UI
+- `endpointGroups` - mounts additional `Hono` sub-apps; integration point for SPA packages
+- `AppEnv` - exported, extensible context type; extend it to carry custom variables through the context
+- `startServerHost(options)` - wraps `Bun.serve()`, default port 7200, graceful shutdown on SIGINT/SIGTERM
+
+#### Server + SPA
+
+```
+<package>/
+└── packages/
+    ├── server/        ← create-hono-server
+    └── spa/           ← create-hono-spa
+```
+
+```bash
+bun create --no-install --no-git "@temir.ra/create-workspace" <package>
+cd <package>
+bun create --no-install --no-git "@temir.ra/hono-server" packages/server
+bun create --no-install --no-git "@temir.ra/hono-spa" packages/spa
+bun install
+```
+
+Add the SPA as a dependency of the server, then reinstall:
+
+```json
+// packages/server/package.json
+{
+  "dependencies": {
+    "@scope/spa": "workspace:*"
+  }
+}
+```
+
+```bash
+bun install
+```
+
+##### `create-hono-spa`
+
+Starting point for a frontend SPA distributed as a Hono sub-app library. See the full documentation at [`@temir.ra/create-hono-spa`](https://www.npmjs.com/package/@temir.ra/create-hono-spa).
+
+- `createSpa(options)` - returns a `Hono` sub-app serving the SPA shell
+- `/app/*` wildcard handles client-side routing; `<base href>` patched at request time from `basePath` and `path`
+- Assets resolved via `import.meta.url`; no file copying or static serving config needed on the consuming server
+- PWA scaffold in `assets/`: `index.html`, `favicon.svg`, `manifest.webmanifest`, screenshots
+- Distributed as a library (`exports` + `dist/` + `assets/`); consumed via `workspace:*` in the server
+
+#### Full-Stack with Shared Types
+
+```
+<package>/
+└── packages/
+    ├── server/        ← create-hono-server
+    ├── spa/           ← create-hono-spa
+    └── types/         ← create-ts-lib
+```
+
+```bash
+bun create --no-install --no-git "@temir.ra/create-workspace" <package>
+cd <package>
+bun create --no-install --no-git "@temir.ra/hono-server" packages/server
+bun create --no-install --no-git "@temir.ra/hono-spa" packages/spa
+bun create --no-install --no-git "@temir.ra/ts-lib" packages/types
+bun install
+```
+
+Add the types package as a dependency of both the server and the SPA, then reinstall:
+
+```json
+// packages/server/package.json  and  packages/spa/package.json
+{
+  "dependencies": {
+    "@scope/types": "workspace:*"
+  }
+}
+```
+
+```bash
+bun install
+```
+
+# DevOps
+
+```bash
+# remove dist/ and tsconfig.tsbuildinfo and tsconfig.build.tsbuildinfo
+bun run clean
+
+# remove dist/ only
+bun run clean:dist
+
+# remove tsconfig.tsbuildinfo and tsconfig.build.tsbuildinfo only
+bun run clean:tsbuildinfo
+
+# compile + bundle
+bun run build
+
+# create a new test package in example/
+bun run dist/cli.bundle.js -- example
+```
+
+## 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. Pull request the branch.
+6. After merge, run `bun run build` - ensures artifacts are current before publish.
+7. Publish.
+
+## Publish
+
+Publish to the public npm registry.
+
+```powershell
+# authenticate
+npm login
+# publish
+bun publish --registry https://registry.npmjs.org/ --access public
+```

package/buildinfo.txt

@@ -0,0 +1 @@
+0.2.0+19ecc29

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,26 @@
+#!/usr/bin/env node
+import { cpSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { resolve, basename } from 'path';
+import { templatePath, changelogPath, buildinfoPath, readmePath } from './constants.js';
+try {
+    const packageNameArgument = process.argv[2];
+    if (!packageNameArgument)
+        throw new Error('Package name argument is required. Usage: `create-workspace <package-name>`');
+    const packageName = packageNameArgument.replace(/\\/g, '/');
+    const destinationPath = resolve(process.cwd(), packageName);
+    cpSync(templatePath, destinationPath, { recursive: true });
+    cpSync(changelogPath, resolve(destinationPath, 'CHANGELOG-template.md'));
+    cpSync(buildinfoPath, resolve(destinationPath, 'buildinfo-template.txt'));
+    cpSync(readmePath, resolve(destinationPath, 'README-template.md'));
+    const packageJsonPath = resolve(destinationPath, 'package.json');
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    packageJson.name = packageName;
+    writeFileSync(packageJsonPath, JSON.stringify(packageJson, 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/constants.d.ts

@@ -0,0 +1,7 @@
+export declare const packageUrl: URL;
+export declare const packagePath: string;
+export declare const templatePath: string;
+export declare const changelogPath: string;
+export declare const buildinfoPath: string;
+export declare const readmePath: string;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,UAAU,EAAE,GAAqC,CAAC;AAC/D,eAAO,MAAM,WAAW,EAAE,MAA2C,CAAC;AAEtE,eAAO,MAAM,YAAY,EAAE,MAA0C,CAAC;AAEtE,eAAO,MAAM,aAAa,EAAE,MAA6C,CAAC;AAC1E,eAAO,MAAM,aAAa,EAAE,MAA8C,CAAC;AAC3E,eAAO,MAAM,UAAU,EAAE,MAA0C,CAAC"}

package/dist/constants.js

@@ -0,0 +1,8 @@
+import { resolve } from 'path';
+import { fileURLToPath } from 'url';
+export const packageUrl = new URL('../', import.meta.url);
+export const packagePath = resolve(fileURLToPath(packageUrl));
+export const templatePath = resolve(packagePath, 'template/');
+export const changelogPath = resolve(packagePath, 'CHANGELOG.md');
+export const buildinfoPath = resolve(packagePath, 'buildinfo.txt');
+export const readmePath = resolve(packagePath, 'README.md');

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@temir.ra/create-workspace",
+  "version": "0.2.0",
+  "description": "Package scaffold with workspace support",
+  "author": "temir.ra",
+  "license": "MIT",
+  "keywords": [
+    "typescript",
+    "template",
+    "workspace",
+    "bun"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://git.chimps.quest/trs/create-workspace.git"
+  },
+  "type": "module",
+  "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": "^6.0.2"
+  }
+}

package/template/CHANGELOG.md

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

package/template/README.md

@@ -0,0 +1,76 @@
+# 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)
+        1. [npmjs.org](#npmjsorg)
+        2. [Custom registry](#custom-registry)
+
+# Quick Start
+
+*<QUICK START INSTRUCTIONS>*
+
+# 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. Pull request the branch.
+6. After merge, run `bun run build` - ensures artifacts are current before publish.
+7. Publish.
+
+## 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
+# authenticate
+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/template/buildinfo.txt

@@ -0,0 +1 @@
+0.0.0

package/template/gitignore

@@ -0,0 +1 @@
+node_modules

package/template/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "",
+  "version": "0.0.0",
+  "description": "",
+  "author": "",
+  "license": "",
+  "private": true,
+  "scripts": {
+    "clean:dist": "rm -rf dist/",
+    "clean": "bun run clean:dist && bun run --filter '*' clean",
+    "prebuild": "bun run scripts/buildinfo.ts",
+    "build": "bun run --filter '*' build",
+    "tests": "bun test && bun run --filter '*' tests",
+    "typecheck": "bun run --filter '*' typecheck"
+  }
+}

package/template/scripts/buildinfo.ts

@@ -0,0 +1,25 @@
+import { execSync } from 'child_process';
+import { readFileSync, writeFileSync } from 'fs';
+
+
+const BUILD_INFO_FILE = 'buildinfo.txt';
+const GIT_COMMAND = 'git rev-parse --short HEAD';
+
+const version: string = JSON.parse(readFileSync('package.json', 'utf-8')).version;
+
+let gitHash = '';
+try {
+    gitHash = execSync(GIT_COMMAND, { stdio: ['ignore', 'pipe', 'ignore'] })
+        .toString()
+        .trim();
+} catch { }
+
+const buildinfo = gitHash
+    ? version.includes('+')
+        ? `${version}.${gitHash}`
+        : `${version}+${gitHash}`
+    : version;
+
+writeFileSync(BUILD_INFO_FILE, buildinfo.trim(), 'utf-8');
+
+console.log(`'${BUILD_INFO_FILE}' has been updated with build info: ${buildinfo}`);

package/template/tests/buildinfo.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'bun:test';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+
+
+const buildinfoUrl = new URL('../buildinfo.txt', import.meta.url);
+
+// taken from https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string
+// Captures: [1]=major, [2]=minor, [3]=patch, [4]=pre-release, [5]=build-metadata
+const SEMVER_REGEX =
+    /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+
+function readBuildinfo(): string {
+    return readFileSync(fileURLToPath(buildinfoUrl), 'utf-8').trim();
+}
+
+describe('buildInfo', () => {
+
+    it('should be a valid semver string', () => {
+        expect(readBuildinfo()).toMatch(SEMVER_REGEX);
+    });
+
+});

package/template/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "lib": [
+      "ESNext",
+      "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
+  },
+  "include": [
+    "tests/**/*.ts",
+    "scripts/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}