@sha3/code 1.0.0

package/templates/node-service/README.md

@@ -0,0 +1,244 @@
+# 🚀 {{packageName}}
+
+HTTP service package with one runtime entrypoint for composing or starting a Hono server.
+
+## TL;DR
+
+```bash
+npm install
+npm run check
+npm run start
+```
+
+```ts
+import { ServiceRuntime } from "{{packageName}}";
+
+const serviceRuntime = ServiceRuntime.createDefault();
+const server = serviceRuntime.buildServer();
+```
+
+## Why
+
+Use this package when you want one small runtime surface for booting the service and one small HTTP boundary that is easy to test.
+It keeps startup, route wiring, and the default response contract behind a public runtime class so callers do not need to understand the internal composition.
+
+## Main Capabilities
+
+- Builds the HTTP server without binding a port when tests or orchestration code need control.
+- Handles a single request without opening a socket when tests only need the HTTP contract.
+- Starts the default runtime with one public method when the process should listen immediately.
+- Exposes the root endpoint payload as a public type so other code can depend on the response contract.
+- Keeps transport concerns small and explicit around Hono.
+
+## Installation
+
+```bash
+npm install
+```
+
+## Running Locally
+
+```bash
+npm run start
+```
+
+The default runtime listens on `http://localhost:3000`.
+
+## Usage
+
+```ts
+import { ServiceRuntime } from "{{packageName}}";
+
+const serviceRuntime = ServiceRuntime.createDefault();
+const server = serviceRuntime.startServer();
+```
+
+This is the intended runtime integration path: construct the default runtime once, then either build or start the Hono-backed server depending on who owns process startup.
+
+## Examples
+
+Build the HTTP server without listening:
+
+```ts
+import { ServiceRuntime } from "{{packageName}}";
+
+const serviceRuntime = ServiceRuntime.createDefault();
+const server = serviceRuntime.buildServer();
+```
+
+Handle one request directly:
+
+```ts
+import { ServiceRuntime } from "{{packageName}}";
+
+const serviceRuntime = ServiceRuntime.createDefault();
+const response = await serviceRuntime.handleRequest(new Request("http://localhost/"));
+```
+
+Call the default endpoint:
+
+```bash
+curl http://localhost:3000/
+```
+
+## HTTP API
+
+### `GET /`
+
+Returns the default service info payload from the default Hono route.
+
+Response shape:
+
+```json
+{
+  "ok": true,
+  "serviceName": "service-name"
+}
+```
+
+Behavior notes:
+
+- responds with status `200`
+- returns JSON
+- is implemented with `hono`
+- uses the `content-type` configured in `src/config.ts`
+
+## Public API
+
+### `ServiceRuntime`
+
+Primary runtime entrypoint for composing or starting the service.
+
+```ts
+import { ServiceRuntime } from "{{packageName}}";
+
+const serviceRuntime = ServiceRuntime.createDefault();
+```
+
+#### `createDefault()`
+
+Creates a `ServiceRuntime` with the default Hono HTTP server wiring.
+
+Parameters:
+
+- none
+
+Returns:
+
+- a ready-to-use `ServiceRuntime`
+
+Behavior notes:
+
+- wires the default Hono HTTP server stack
+- keeps configuration centralized in `src/config.ts`
+
+#### `buildServer()`
+
+Builds the Hono Node server without binding a port.
+
+Parameters:
+
+- none
+
+Returns:
+
+- a Hono Node `ServerType` instance
+
+Behavior notes:
+
+- useful for integration tests and manual orchestration
+- does not call `listen()`
+- returns the exact server instance that `startServer()` would later bind
+
+#### `handleRequest(request)`
+
+Runs one request through the default Hono pipeline without binding a port.
+
+Parameters:
+
+- `request`: standard `Request` object routed through the service
+
+Returns:
+
+- a `Promise<Response>` with the route result
+
+Behavior notes:
+
+- useful for tests that only need to validate HTTP behavior
+- avoids opening a socket during request handling checks
+- uses the same route wiring as the default runtime
+
+#### `startServer()`
+
+Builds the HTTP server and starts listening on `config.DEFAULT_PORT`.
+
+Parameters:
+
+- none
+
+Returns:
+
+- the started Hono Node `ServerType` instance
+
+Behavior notes:
+
+- logs the listening address through the package logger
+- binds immediately to the configured default port
+- keeps startup behavior centralized in one public method
+
+### `AppInfoPayload`
+
+Public type for the default root payload returned by the root endpoint.
+
+```ts
+type AppInfoPayload = { ok: true; serviceName: string };
+```
+
+## Compatibility
+
+- Node.js 20+
+- ESM (`"type": "module"`)
+- Strict TypeScript
+
+## Configuration
+
+Configuration is centralized in `src/config.ts`.
+
+- `config.RESPONSE_CONTENT_TYPE`: response `content-type` header sent by the root endpoint.
+- `config.DEFAULT_PORT`: port used by `startServer()` when the service binds locally.
+- `config.SERVICE_NAME`: service name included in the root endpoint payload.
+
+## 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 start`: launch the service with `tsx`
+- `npm run build`: compile the module output to `dist/`
+
+## Structure
+
+- `src/config.ts`: canonical runtime configuration
+- `src/app-info/app-info.service.ts`: builds the root endpoint payload
+- `src/http/http-server.service.ts`: constructs the Hono HTTP server
+- `src/app/service-runtime.service.ts`: public runtime orchestration
+- `src/main.ts`: bootstrap entrypoint
+- `test/service-runtime.test.ts`: behavior test
+
+## Troubleshooting
+
+### Port conflicts
+
+Override `PORT` in `.env` or your shell before running `npm run start`.
+
+### Standards warnings
+
+Run `npm run standards:check` to detect contract errors, README coverage gaps, and advisory warnings from the project verifier.
+
+## AI Workflow
+
+- Read `AGENTS.md`, `ai/contract.json`, and the relevant `ai/<assistant>.md` before coding.
+- Keep managed contract/tooling files read-only during feature work.
+- Keep this README focused on the runtime surface, HTTP contract, configuration, and public API.
+- Rewrite examples and endpoint notes whenever exported behavior changes.
+- Run `npm run check` before finalizing changes.

package/templates/node-service/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-service/ecosystem.config.cjs

@@ -0,0 +1,3 @@
+module.exports = {
+  apps: [{ name: "{{packageName}}", script: "node", args: "--import tsx src/main.ts", env: { NODE_ENV: "production" } }],
+};

package/templates/node-service/gitignore

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

package/templates/node-service/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "start": "node --import tsx src/main.ts",
+    "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": {
+    "@hono/node-server": "^1.19.11",
+    "@sha3/logger": "^2.0.0",
+    "dotenv": "^16.6.1",
+    "hono": "^4.12.7"
+  },
+  "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-service/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-service/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-service/src/app/service-runtime.service.ts

@@ -0,0 +1,57 @@
+import type { ServerType } from "@hono/node-server";
+
+/**
+ * @section imports:internals
+ */
+
+import config from "../config.ts";
+import { HttpServerService } from "../http/http-server.service.ts";
+import logger from "../logger.ts";
+
+/**
+ * @section class
+ */
+
+export class ServiceRuntime {
+  /**
+   * @section private:attributes
+   */
+
+  private readonly httpServerService: HttpServerService;
+
+  /**
+   * @section constructor
+   */
+
+  public constructor(httpServerService: HttpServerService) {
+    this.httpServerService = httpServerService;
+  }
+
+  /**
+   * @section factory
+   */
+
+  public static createDefault(): ServiceRuntime {
+    return new ServiceRuntime(HttpServerService.createDefault());
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  public buildServer(): ServerType {
+    return this.httpServerService.buildServer();
+  }
+
+  public async handleRequest(request: Request): Promise<Response> {
+    return this.httpServerService.handleRequest(request);
+  }
+
+  public startServer(): ServerType {
+    const server = this.buildServer();
+    server.listen(config.DEFAULT_PORT, () => {
+      logger.info(`service listening on http://localhost:${config.DEFAULT_PORT}`);
+    });
+    return server;
+  }
+}

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

@@ -0,0 +1,47 @@
+/**
+ * @section imports:internals
+ */
+
+import config from "../config.ts";
+
+/**
+ * @section types
+ */
+
+export type AppInfoPayload = { ok: true; serviceName: string };
+
+/**
+ * @section class
+ */
+
+export class AppInfoService {
+  /**
+   * @section private:attributes
+   */
+
+  private readonly serviceName: string;
+
+  /**
+   * @section constructor
+   */
+
+  public constructor(serviceName: string) {
+    this.serviceName = serviceName;
+  }
+
+  /**
+   * @section factory
+   */
+
+  public static createDefault(): AppInfoService {
+    return new AppInfoService(config.SERVICE_NAME);
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  public buildPayload(): AppInfoPayload {
+    return { ok: true, serviceName: this.serviceName };
+  }
+}

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

@@ -0,0 +1,11 @@
+import "dotenv/config";
+
+const ENV = process.env;
+
+const config = {
+  RESPONSE_CONTENT_TYPE: ENV.RESPONSE_CONTENT_TYPE || "application/json",
+  DEFAULT_PORT: Number(ENV.PORT || 3000),
+  SERVICE_NAME: ENV.SERVICE_NAME || "{{packageName}}",
+} as const;
+
+export default config;

package/templates/node-service/src/http/http-server.service.ts

@@ -0,0 +1,66 @@
+/**
+ * @section imports:externals
+ */
+
+import { createAdaptorServer } from "@hono/node-server";
+import type { ServerType } from "@hono/node-server";
+import { Hono } from "hono";
+
+/**
+ * @section imports:internals
+ */
+
+import { AppInfoService } from "../app-info/app-info.service.ts";
+import config from "../config.ts";
+
+/**
+ * @section class
+ */
+
+export class HttpServerService {
+  /**
+   * @section private:attributes
+   */
+
+  private readonly appInfoService: AppInfoService;
+
+  /**
+   * @section constructor
+   */
+
+  public constructor(appInfoService: AppInfoService) {
+    this.appInfoService = appInfoService;
+  }
+
+  /**
+   * @section factory
+   */
+
+  public static createDefault(): HttpServerService {
+    return new HttpServerService(AppInfoService.createDefault());
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  public async handleRequest(request: Request): Promise<Response> {
+    const app = new Hono();
+    app.get("/", (context) => {
+      const payload = this.appInfoService.buildPayload();
+      context.header("content-type", config.RESPONSE_CONTENT_TYPE);
+      return context.json(payload, 200);
+    });
+    return app.fetch(request);
+  }
+
+  public buildServer(): ServerType {
+    const app = new Hono();
+    app.get("/", (context) => {
+      const payload = this.appInfoService.buildPayload();
+      context.header("content-type", config.RESPONSE_CONTENT_TYPE);
+      return context.json(payload, 200);
+    });
+    return createAdaptorServer({ fetch: app.fetch });
+  }
+}

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

@@ -0,0 +1,2 @@
+export { ServiceRuntime } from "./app/service-runtime.service.ts";
+export type { AppInfoPayload } from "./app-info/app-info.service.ts";

package/templates/node-service/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;