@sha3/code 1.0.0

package/templates/node-lib/README.md

@@ -0,0 +1,172 @@
+# 📚 {{packageName}}
+
+Small TypeScript library that exposes package metadata through one stable, package-root API.
+
+## TL;DR
+
+```bash
+npm install
+npm run check
+npm run build
+```
+
+```ts
+import { PackageInfoService } from "{{packageName}}";
+
+const packageInfoService = PackageInfoService.createDefault();
+console.log(packageInfoService.readPackageInfo());
+```
+
+## Why
+
+Use this package when other modules, diagnostics code, or adapters need the package name without reaching into private files.
+It gives consumers one stable import path and keeps the metadata mapping in a single service instead of scattering string literals through the codebase.
+
+## Main Capabilities
+
+- Exposes package metadata through a stable package-root import.
+- Keeps the configured package name behind one service instead of repeating config access in callers.
+- Returns plain serializable data that is easy to log, test, or hand to HTTP or CLI adapters.
+
+## Installation
+
+```bash
+npm install {{packageName}}
+```
+
+## Usage
+
+```ts
+import { PackageInfoService } from "{{packageName}}";
+
+const packageInfoService = PackageInfoService.createDefault();
+const packageInfo = packageInfoService.readPackageInfo();
+
+console.log(packageInfo.packageName);
+```
+
+This is the intended integration path: import from the package root, create the default service once, and reuse it anywhere you need package metadata.
+
+## Examples
+
+Read package metadata for logging or diagnostics:
+
+```ts
+import { PackageInfoService, type PackageInfo } from "{{packageName}}";
+
+const packageInfoService = PackageInfoService.createDefault();
+const packageInfo: PackageInfo = packageInfoService.readPackageInfo();
+
+console.log(`[package] ${packageInfo.packageName}`);
+```
+
+Create the default service once and reuse it across boundaries:
+
+```ts
+import { PackageInfoService } from "{{packageName}}";
+
+const packageInfoService = PackageInfoService.createDefault();
+const firstRead = packageInfoService.readPackageInfo();
+const secondRead = packageInfoService.readPackageInfo();
+```
+
+## Public API
+
+### `PackageInfoService`
+
+Primary entrypoint for reading the package metadata exposed by the library.
+
+```ts
+import { PackageInfoService } from "{{packageName}}";
+
+const packageInfoService = PackageInfoService.createDefault();
+```
+
+#### `createDefault()`
+
+Creates a `PackageInfoService` using the package configuration.
+
+Parameters:
+
+- none
+
+Returns:
+
+- a ready-to-use `PackageInfoService`
+
+Behavior notes:
+
+- reads the default package name from `config.PACKAGE_NAME`
+- keeps callers out of `src/config.ts`
+- gives consumers a stable construction path that stays valid if the internals change
+
+#### `readPackageInfo()`
+
+Reads the package metadata exposed by the public API.
+
+Parameters:
+
+- none
+
+Returns:
+
+- a `PackageInfo` object containing the configured package name
+
+Behavior notes:
+
+- returns a plain serializable object
+- performs no filesystem or network I/O
+- is safe to call from application code, tests, and adapters
+
+### `PackageInfo`
+
+Public type that describes the shape returned by `readPackageInfo()`.
+
+```ts
+type PackageInfo = { packageName: string };
+```
+
+## Compatibility
+
+- Node.js 20+
+- ESM (`"type": "module"`)
+- Strict TypeScript
+
+## Configuration
+
+Configuration is centralized in `src/config.ts`.
+
+- `config.PACKAGE_NAME`: package name returned by `readPackageInfo()` and exposed to consumers of this package.
+
+## Scripts
+
+- `npm run standards:check`: verify deterministic project contract rules
+- `npm run check`: standards + lint + format + typecheck + tests
+- `npm run fix`: Biome autofix + format write
+- `npm run build`: compile to `dist/`
+- `npm run test`: run Node test runner with `tsx`
+
+## Structure
+
+- `src/config.ts`: canonical hardcoded configuration
+- `src/package-info/package-info.service.ts`: implementation of the public metadata service
+- `src/index.ts`: public exports
+- `test/package-info.test.ts`: behavior test
+
+## Troubleshooting
+
+### Import errors
+
+Ensure the consumer project supports Node.js ESM and TypeScript extension rewriting.
+
+### Standards warnings
+
+Run `npm run standards:check` for contract errors, README coverage problems, and advisory warnings from the project verifier.
+
+## AI Workflow
+
+- Read `AGENTS.md`, `ai/contract.json`, and the relevant `ai/<assistant>.md` file before coding.
+- Do not edit managed contract/tooling files during normal implementation.
+- Keep this README focused on consumer-facing behavior, configuration, and public API.
+- Rewrite examples and API notes whenever the exported behavior changes.
+- Run `npm run check` before finalizing changes.

package/templates/node-lib/biome.json

@@ -0,0 +1,37 @@
+{
+  "files": {
+    "ignoreUnknown": true,
+    "ignore": [".code-standards", "dist"]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 160
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "correctness": {
+        "noUnusedFunctionParameters": "error",
+        "noUnusedImports": "error",
+        "noUnusedPrivateClassMembers": "error",
+        "noUnusedVariables": "error"
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "semicolons": "always",
+      "arrowParentheses": "always",
+      "bracketSpacing": true
+    }
+  },
+  "json": {
+    "formatter": {
+      "enabled": true
+    }
+  }
+}

package/templates/node-lib/gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+coverage/
+.code-standards/
+*.tsbuildinfo
+.DS_Store

package/templates/node-lib/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "npm run standards:check && npm run lint && npm run format:check && npm run typecheck && npm run test",
+    "fix": "npm run lint:fix && npm run format:write",
+    "lint": "biome check .",
+    "lint:fix": "biome check . --write",
+    "format:check": "biome format .",
+    "format:write": "biome format . --write",
+    "standards:check": "code-standards verify",
+    "typecheck": "tsc --noEmit",
+    "test": "node scripts/run-tests.mjs",
+    "publish": "node scripts/release-publish.mjs"
+  },
+  "dependencies": {
+    "@sha3/logger": "^2.0.0"
+  },
+  "devDependencies": {
+    "@sha3/code": "^{{packageVersion}}",
+    "@biomejs/biome": "^1.9.4",
+    "@types/node": "^22.13.10",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  }
+}

package/templates/node-lib/scripts/release-publish.mjs

@@ -0,0 +1,106 @@
+import { spawn } from "node:child_process";
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+function run(command, args, cwd, stdio = "inherit") {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, stdio, shell: process.platform === "win32" });
+    let stdout = "";
+    let stderr = "";
+
+    if (stdio === "pipe") {
+      child.stdout.on("data", (chunk) => {
+        stdout += String(chunk);
+      });
+
+      child.stderr.on("data", (chunk) => {
+        stderr += String(chunk);
+      });
+    }
+
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      resolve({ code: code ?? 1, stdout, stderr });
+    });
+  });
+}
+
+function isNotFoundError(output) {
+  const lower = output.toLowerCase();
+  return lower.includes("e404") || lower.includes("404 not found") || lower.includes("no match found");
+}
+
+function parseSemver(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
+  if (!match) {
+    throw new Error(`Unsupported version format: ${version}. Expected x.y.z`);
+  }
+
+  return { major: Number.parseInt(match[1], 10), minor: Number.parseInt(match[2], 10), patch: Number.parseInt(match[3], 10) };
+}
+
+function bumpMinor(version) {
+  const parsed = parseSemver(version);
+  return `${parsed.major}.${parsed.minor + 1}.0`;
+}
+
+async function readPackageJson(packageJsonPath) {
+  const raw = await readFile(packageJsonPath, "utf8");
+  return JSON.parse(raw);
+}
+
+async function writePackageJson(packageJsonPath, pkg) {
+  await writeFile(packageJsonPath, `${JSON.stringify(pkg, null, 2)}\n`, "utf8");
+}
+
+async function versionExistsOnNpm(packageName, version, cwd) {
+  const result = await run("npm", ["view", `${packageName}@${version}`, "version", "--json"], cwd, "pipe");
+  const combined = `${result.stdout}\n${result.stderr}`;
+  if (result.code === 0) {
+    return true;
+  }
+  if (isNotFoundError(combined)) {
+    return false;
+  }
+
+  throw new Error(`Unable to verify npm version ${packageName}@${version}: ${combined.trim()}`);
+}
+
+async function main() {
+  const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+  const projectRoot = path.resolve(scriptDir, "..");
+  const packageJsonPath = path.join(projectRoot, "package.json");
+  const packageJson = await readPackageJson(packageJsonPath);
+  if (typeof packageJson.name !== "string" || packageJson.name.length === 0) {
+    throw new Error("package.json name is required.");
+  }
+  if (typeof packageJson.version !== "string" || packageJson.version.length === 0) {
+    throw new Error("package.json version is required.");
+  }
+
+  const exists = await versionExistsOnNpm(packageJson.name, packageJson.version, projectRoot);
+  if (exists) {
+    const nextVersion = bumpMinor(packageJson.version);
+    packageJson.version = nextVersion;
+    await writePackageJson(packageJsonPath, packageJson);
+    console.log(`Version ${packageJson.name}@${packageJson.version} already existed. Bumped to ${nextVersion}.`);
+  } else {
+    console.log(`Publishing new version ${packageJson.name}@${packageJson.version}.`);
+  }
+
+  const build = await run("npm", ["run", "build"], projectRoot);
+  if (build.code !== 0) {
+    throw new Error("npm run build failed.");
+  }
+
+  const publish = await run("npm", ["publish", "--access", "public", "--ignore-scripts"], projectRoot);
+  if (publish.code !== 0) {
+    throw new Error("npm publish failed.");
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/templates/node-lib/scripts/run-tests.mjs

@@ -0,0 +1,65 @@
+import { spawn } from "node:child_process";
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+
+const rootDir = process.cwd();
+const testRoots = ["test", "src"];
+
+async function collectTestsFrom(directoryPath, collector) {
+  let entries;
+
+  try {
+    entries = await readdir(directoryPath, { withFileTypes: true });
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return;
+    }
+
+    throw error;
+  }
+
+  for (const entry of entries) {
+    const absolutePath = path.join(directoryPath, entry.name);
+    if (entry.isDirectory()) {
+      await collectTestsFrom(absolutePath, collector);
+      continue;
+    }
+    if (!entry.isFile()) {
+      continue;
+    }
+    if (entry.name.endsWith(".test.ts")) {
+      collector.push(path.relative(rootDir, absolutePath));
+    }
+  }
+}
+
+function runNodeTests(files) {
+  return new Promise((resolve, reject) => {
+    const args = ["--import", "tsx", "--test", ...files];
+    const child = spawn(process.execPath, args, { cwd: rootDir, stdio: "inherit", shell: process.platform === "win32" });
+
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      resolve(code ?? 1);
+    });
+  });
+}
+
+async function main() {
+  const testFiles = [];
+
+  for (const root of testRoots) {
+    await collectTestsFrom(path.join(rootDir, root), testFiles);
+  }
+
+  const uniqueFiles = [...new Set(testFiles)].sort((left, right) => left.localeCompare(right));
+  const exitCode = await runNodeTests(uniqueFiles);
+  if (exitCode !== 0) {
+    process.exit(exitCode);
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/templates/node-lib/src/config.ts

@@ -0,0 +1,3 @@
+const config = { PACKAGE_NAME: "{{packageName}}" } as const;
+
+export default config;

package/templates/node-lib/src/index.ts

@@ -0,0 +1,2 @@
+export { PackageInfoService } from "./package-info/package-info.service.ts";
+export type { PackageInfo } from "./package-info/package-info.service.ts";

package/templates/node-lib/src/logger.ts

@@ -0,0 +1,7 @@
+import Logger from "@sha3/logger";
+
+const PACKAGE_NAME = "{{packageName}}";
+const LOGGER_NAME = PACKAGE_NAME.startsWith("@") ? PACKAGE_NAME.split("/")[1] || PACKAGE_NAME : PACKAGE_NAME;
+const logger = new Logger({ loggerName: LOGGER_NAME });
+
+export default logger;

package/templates/node-lib/src/package-info/package-info.service.ts

@@ -0,0 +1,47 @@
+/**
+ * @section imports:internals
+ */
+
+import config from "../config.ts";
+
+/**
+ * @section types
+ */
+
+export type PackageInfo = { packageName: string };
+
+/**
+ * @section class
+ */
+
+export class PackageInfoService {
+  /**
+   * @section private:attributes
+   */
+
+  private readonly packageName: string;
+
+  /**
+   * @section constructor
+   */
+
+  public constructor(packageName: string) {
+    this.packageName = packageName;
+  }
+
+  /**
+   * @section factory
+   */
+
+  public static createDefault(): PackageInfoService {
+    return new PackageInfoService(config.PACKAGE_NAME);
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  public readPackageInfo(): PackageInfo {
+    return { packageName: this.packageName };
+  }
+}

package/templates/node-lib/test/package-info.test.ts

@@ -0,0 +1,10 @@
+import * as assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { PackageInfoService } from "../src/index.ts";
+
+test("PackageInfoService exposes the configured package name", () => {
+  const packageInfoService = PackageInfoService.createDefault();
+
+  assert.deepEqual(packageInfoService.readPackageInfo(), { packageName: "{{packageName}}" });
+});

package/templates/node-lib/tsconfig.build.json

@@ -0,0 +1 @@
+{ "extends": "./tsconfig.json", "compilerOptions": { "noEmit": false, "rootDir": "./src", "outDir": "./dist" }, "exclude": ["test/**/*.ts"] }

package/templates/node-lib/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "@sha3/code/tsconfig/node-lib.json",
+  "compilerOptions": { "types": ["node"], "rootDir": ".", "allowImportingTsExtensions": true, "rewriteRelativeImportExtensions": true },
+  "include": ["src/**/*.ts", "test/**/*.ts"]
+}

package/templates/node-service/.biomeignore

@@ -0,0 +1,10 @@
+node_modules
+dist
+coverage
+.code-standards
+AGENTS.md
+PROMPT.md
+SKILLS.md
+ai
+prompts
+skills

package/templates/node-service/.vscode/extensions.json

@@ -0,0 +1 @@
+{ "recommendations": ["biomejs.biome"], "unwantedRecommendations": ["dbaeumer.vscode-eslint", "esbenp.prettier-vscode", "rvest.vs-code-prettier-eslint"] }

package/templates/node-service/.vscode/settings.json

@@ -0,0 +1,9 @@
+{
+  "editor.formatOnSave": true,
+  "editor.formatOnSaveMode": "file",
+  "editor.defaultFormatter": "biomejs.biome",
+  "[typescript]": { "editor.defaultFormatter": "biomejs.biome", "editor.formatOnSave": true },
+  "[javascript]": { "editor.defaultFormatter": "biomejs.biome", "editor.formatOnSave": true },
+  "[json]": { "editor.defaultFormatter": "biomejs.biome", "editor.formatOnSave": true },
+  "[jsonc]": { "editor.defaultFormatter": "biomejs.biome", "editor.formatOnSave": true }
+}