npm - mikoshi-construct - Versions diffs - 0.1.0 - Mend

mikoshi-construct 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (96) hide show

package/templates/presets/node-frontend/baseline/tsconfig.json ADDED Viewed

@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "types": ["node", "vite/client"]
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts", "scripts/**/*.ts", "vitest.config.ts"],
+  "exclude": ["**/node_modules/**", "**/dist/**"]
+}

package/templates/presets/node-frontend/baseline/vitest.config.ts ADDED Viewed

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitest/config'
+export default defineConfig({
+  test: {
+    projects: [
+      { test: { name: 'app', include: ['tests/**/*.test.ts'], environment: 'happy-dom' } },
+      { test: { name: 'scripts', include: ['scripts/tests/**/*.test.ts'], environment: 'node' } },
+    ],
+  },
+})

package/templates/presets/node-frontend/sample/architecture/app.md ADDED Viewed

@@ -0,0 +1,37 @@
+# Application
+The bootstrap path and the wiring below are rendered from
+[composition/app.yaml](composition/app.yaml). Edit the model, then run `pnpm composition:render`;
+`pnpm composition:check` fails when the diagram and the model drift apart.
+<!-- composition:app -->
+`src/main.ts` is the composition root: it finds the mount point in `index.html`, loads the design tokens and the component styles, and hands the root element to `createApp`. State crosses into CSS as `data-*` attributes; nothing else writes styles from JavaScript.
+```mermaid
+flowchart LR
+  subgraph b_bootstrap["Bootstrap"]
+    main["main.ts"]
+  end
+  subgraph b_ui["UI"]
+    app["createApp(root)"]
+    counter["createCounter(button)"]
+  end
+  subgraph b_styles["Styles"]
+    tokens["tokens.css"]
+    css["app.css"]
+  end
+  main -.->|"imports"| tokens
+  main -.->|"imports"| css
+  main --> app
+  app --> counter
+  counter -.->|"data-tone"| css
+```
+<!-- /composition:app -->
+## Conventions
+`src/main.ts` is the only file that touches `document` at module scope; everything else receives its
+root element. State that CSS must see is written as a `data-*` or ARIA attribute (a lint rule rejects
+`classList` mutation and inline style writes in `src/`). Tokens live in
+[src/styles/tokens.css](../src/styles/tokens.css); a raw colour, length or duration in a component is a
+missing token. Layout reacts to its container, never to the viewport.

package/templates/presets/node-frontend/sample/architecture/composition/app.yaml ADDED Viewed

@@ -0,0 +1,41 @@
+id: app
+title: Application composition
+description: >-
+  `src/main.ts` is the composition root: it finds the mount point in `index.html`, loads the design
+  tokens and the component styles, and hands the root element to `createApp`. State crosses into CSS
+  as `data-*` attributes; nothing else writes styles from JavaScript.
+doc: architecture/app.md
+boundaries:
+  - id: bootstrap
+    label: Bootstrap
+  - id: ui
+    label: UI
+  - id: styles
+    label: Styles
+nodes:
+  - id: main
+    label: main.ts
+    path: src/main.ts
+    boundary: bootstrap
+  - id: app
+    label: createApp(root)
+    path: src/app.ts
+    boundary: ui
+  - id: counter
+    label: createCounter(button)
+    path: src/app.ts
+    boundary: ui
+  - id: tokens
+    label: tokens.css
+    path: src/styles/tokens.css
+    boundary: styles
+  - id: css
+    label: app.css
+    path: src/styles/app.css
+    boundary: styles
+edges:
+  - {from: main, to: tokens, kind: wires, label: imports}
+  - {from: main, to: css, kind: wires, label: imports}
+  - {from: main, to: app, kind: sequence}
+  - {from: app, to: counter, kind: sequence}
+  - {from: counter, to: css, kind: wires, label: data-tone}

package/templates/presets/node-frontend/sample/index.html.eta ADDED Viewed

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{projectName}}</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/templates/presets/node-frontend/sample/src/app.ts ADDED Viewed

@@ -0,0 +1,32 @@
+export interface Counter {
+  element: HTMLButtonElement
+  value: () => number
+  increment: () => void
+}
+function render(element: HTMLButtonElement, count: number): void {
+  element.dataset.count = String(count)
+  element.dataset.tone = count > 0 ? 'active' : 'idle'
+  element.textContent = `Clicked ${count} ${count === 1 ? 'time' : 'times'}`
+}
+export function createCounter(element: HTMLButtonElement): Counter {
+  let count = 0
+  render(element, count)
+  element.addEventListener('click', () => {
+    count += 1
+    render(element, count)
+  })
+  return { element, value: () => count, increment: () => element.click() }
+}
+export function createApp(root: HTMLElement): Counter {
+  const document = root.ownerDocument
+  const heading = document.createElement('h1')
+  heading.textContent = document.title
+  const button = document.createElement('button')
+  button.type = 'button'
+  button.className = 'counter'
+  root.replaceChildren(heading, button)
+  return createCounter(button)
+}

package/templates/presets/node-frontend/sample/src/main.ts ADDED Viewed

@@ -0,0 +1,9 @@
+import { createApp } from './app.js'
+import './styles/tokens.css'
+import './styles/app.css'
+const root = document.querySelector<HTMLElement>('#app')
+if (root == null)
+  throw new Error('index.html must contain <div id="app">')
+createApp(root)

package/templates/presets/node-frontend/sample/src/styles/app.css ADDED Viewed

@@ -0,0 +1,43 @@
+body {
+  margin: 0;
+  background: var(--color-surface);
+  color: var(--color-on-surface);
+  font-family: system-ui, sans-serif;
+}
+#app {
+  container: app / inline-size;
+  display: grid;
+  gap: var(--space-4);
+  max-inline-size: var(--body-max-inline-size);
+  margin-inline: auto;
+  padding-block: var(--space-8);
+  padding-inline: var(--space-4);
+}
+.counter {
+  --_bg: var(--color-surface);
+  --_fg: var(--color-on-surface);
+  --_bd: var(--color-on-surface);
+  justify-self: start;
+  padding: 0.25lh 1ch;
+  border: 1px solid var(--_bd);
+  border-radius: var(--radius-md);
+  background: var(--_bg);
+  color: var(--_fg);
+  font: inherit;
+  transition: background var(--duration-fast) ease;
+  &[data-tone='active'] {
+    --_bg: var(--color-primary);
+    --_fg: var(--color-on-primary);
+    --_bd: transparent;
+  }
+}
+@container app (inline-size <= 30rem) {
+  .counter {
+    justify-self: stretch;
+  }
+}

package/templates/presets/node-frontend/sample/src/styles/tokens.css ADDED Viewed

@@ -0,0 +1,16 @@
+:root {
+  color-scheme: light dark;
+  --color-surface: light-dark(oklch(98% 0.01 250), oklch(18% 0.02 250));
+  --color-on-surface: light-dark(oklch(22% 0.02 250), oklch(94% 0.01 250));
+  --color-primary: light-dark(oklch(52% 0.2 265), oklch(78% 0.14 265));
+  --color-on-primary: light-dark(oklch(99% 0 0), oklch(18% 0.05 265));
+  --space-2: 0.5rem;
+  --space-4: 1rem;
+  --space-8: 2rem;
+  --radius-md: 0.5rem;
+  --duration-fast: 120ms;
+  --body-max-inline-size: 65ch;
+  --bp-cq-sm: 30rem;
+}

package/templates/presets/node-frontend/sample/tests/app.test.ts ADDED Viewed

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest'
+import { createApp } from '../src/app.js'
+describe('createApp', () => {
+  it('mounts the counter and keeps its state in data attributes', () => {
+    const root = document.createElement('div')
+    document.body.append(root)
+    const counter = createApp(root)
+    expect(root.querySelector('h1')).not.toBeNull()
+    expect(counter.element.dataset.count).toBe('0')
+    expect(counter.element.dataset.tone).toBe('idle')
+    counter.increment()
+    counter.increment()
+    expect(counter.value()).toBe(2)
+    expect(counter.element.dataset.count).toBe('2')
+    expect(counter.element.dataset.tone).toBe('active')
+    expect(counter.element.className).toBe('counter')
+  })
+})

package/templates/stacks/express-api/app/src/app.ts ADDED Viewed

@@ -0,0 +1,27 @@
+import type { AppConfig } from './config.js'
+import type { HealthProbe } from './health/health.service.js'
+import express from 'express'
+import { HealthController } from './health/health.controller.js'
+import { alwaysUp, HealthService } from './health/health.service.js'
+import { createApiContractValidator } from './http/api-contract.middleware.js'
+import { errorHandler } from './http/error-handler.middleware.js'
+export interface AppDependencies {
+  healthProbe?: HealthProbe
+}
+export function createApp(config: AppConfig, dependencies: AppDependencies = {}): express.Express {
+  const app = express()
+  app.disable('x-powered-by')
+  app.use(express.json())
+  app.use(createApiContractValidator(config))
+  const health = new HealthService(config.serviceName, dependencies.healthProbe ?? alwaysUp)
+  const router = express.Router()
+  HealthController.register(router, health)
+  app.use(router)
+  app.use(errorHandler)
+  return app
+}

package/templates/stacks/express-api/app/src/config.ts.eta ADDED Viewed

@@ -0,0 +1,30 @@
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+const DEFAULT_CONTRACT_PATH = fileURLToPath(new URL('{{contractPathFromConfig}}', import.meta.url))
+export interface AppConfig {
+  port: number
+  serviceName: string
+  apiContractPath: string
+  validateApiResponses: boolean
+}
+function integer(name: string, fallback: number): number {
+  const raw = process.env[name]
+  if (raw == null || raw === '')
+    return fallback
+  const parsed = Number(raw)
+  if (!Number.isInteger(parsed))
+    throw new Error(`${name} must be an integer, got "${raw}"`)
+  return parsed
+}
+export function readConfig(env: NodeJS.ProcessEnv = process.env): AppConfig {
+  return {
+    port: integer('PORT', 3000),
+    serviceName: env.SERVICE_NAME ?? '{{projectName}}',
+    apiContractPath: env.API_CONTRACT_PATH ?? DEFAULT_CONTRACT_PATH,
+    validateApiResponses: env.NODE_ENV !== 'production',
+  }
+}

package/templates/stacks/express-api/app/src/contracts/types.ts.eta ADDED Viewed

	@@ -0,0 +1 @@
1	+ export type { components } from '{{contractTypesImport}}'

package/templates/stacks/express-api/app/src/health/health.controller.ts ADDED Viewed

@@ -0,0 +1,12 @@
+import type { Router } from 'express'
+import type { HealthService } from './health.service.js'
+import { asyncHandler } from '../http/async-handler.middleware.js'
+export class HealthController {
+  static register(router: Router, health: HealthService): void {
+    router.get('/health', asyncHandler(async (_req, res) => {
+      const snapshot = await health.snapshot()
+      res.status(snapshot.status === 'ok' ? 200 : 503).json(snapshot)
+    }))
+  }
+}

package/templates/stacks/express-api/app/src/health/health.service.ts ADDED Viewed

@@ -0,0 +1,23 @@
+import type { components } from '../contracts/types.js'
+export type HealthResponse = components['schemas']['HealthResponse']
+export interface HealthProbe {
+  ping: () => Promise<boolean>
+}
+export const alwaysUp: HealthProbe = {
+  ping: async () => true,
+}
+export class HealthService {
+  constructor(
+    private readonly serviceName: string,
+    private readonly probe: HealthProbe,
+  ) {}
+  async snapshot(): Promise<HealthResponse> {
+    const up = await this.probe.ping()
+    return { status: up ? 'ok' : 'error', service: this.serviceName, time: new Date().toISOString() }
+  }
+}

package/templates/stacks/express-api/app/src/http/api-contract.middleware.ts ADDED Viewed

@@ -0,0 +1,13 @@
+import type { RequestHandler } from 'express'
+import type { AppConfig } from '../config.js'
+import { middleware as openApiValidator } from 'express-openapi-validator'
+export function createApiContractValidator(config: AppConfig): RequestHandler[] {
+  return openApiValidator({
+    apiSpec: config.apiContractPath,
+    validateRequests: { allowUnknownQueryParameters: true },
+    validateResponses: config.validateApiResponses,
+    validateSecurity: false,
+    ignoreUndocumented: true,
+  })
+}

package/templates/stacks/express-api/app/src/http/app-error.ts ADDED Viewed

@@ -0,0 +1,14 @@
+export class AppError extends Error {
+  constructor(
+    readonly code: string,
+    readonly status: number,
+    message: string,
+  ) {
+    super(message)
+    this.name = 'AppError'
+  }
+}
+export function isAppError(error: unknown): error is AppError {
+  return error instanceof AppError
+}

package/templates/stacks/express-api/app/src/http/async-handler.middleware.ts ADDED Viewed

@@ -0,0 +1,7 @@
+import type { NextFunction, Request, RequestHandler, Response } from 'express'
+export function asyncHandler(handler: (req: Request, res: Response, next: NextFunction) => Promise<void>): RequestHandler {
+  return (req, res, next) => {
+    handler(req, res, next).catch(next)
+  }
+}

package/templates/stacks/express-api/app/src/http/error-handler.middleware.ts ADDED Viewed

@@ -0,0 +1,50 @@
+import type express from 'express'
+import type { components } from '../contracts/types.js'
+import { isAppError } from './app-error.js'
+type ErrorResponse = components['schemas']['ErrorResponse']
+interface ContractError extends Error {
+  status: number
+  errors: Array<{ path: string, message: string }>
+}
+function isContractError(error: unknown): error is ContractError {
+  return error instanceof Error
+    && typeof (error as ContractError).status === 'number'
+    && Array.isArray((error as ContractError).errors)
+}
+function contractErrorPayload(error: ContractError): ErrorResponse {
+  const message = error.errors.map(item => `${item.path} ${item.message}`).join('; ') || error.message
+  if (error.status === 404)
+    return { error: 'NOT_FOUND', message }
+  if (error.status >= 500)
+    return { error: 'INTERNAL_ERROR', message }
+  return { error: 'VALIDATION_ERROR', message }
+}
+export function errorHandler(
+  error: unknown,
+  _req: express.Request,
+  res: express.Response,
+  _next: express.NextFunction,
+): void {
+  if (res.headersSent)
+    return
+  if (isAppError(error)) {
+    const payload: ErrorResponse = { error: error.code, message: error.message }
+    res.status(error.status).json(payload)
+    return
+  }
+  if (isContractError(error)) {
+    res.status(error.status).json(contractErrorPayload(error))
+    return
+  }
+  console.error('[Unhandled error]', error)
+  const payload: ErrorResponse = { error: 'INTERNAL_ERROR', message: 'Internal server error' }
+  res.status(500).json(payload)
+}

package/templates/stacks/express-api/app/src/server.ts ADDED Viewed

@@ -0,0 +1,9 @@
+import { createApp } from './app.js'
+import { readConfig } from './config.js'
+const config = readConfig()
+const app = createApp(config)
+app.listen(config.port, () => {
+  console.log(`${config.serviceName} listening on http://localhost:${config.port}`)
+})

package/templates/stacks/express-api/app/tests/health.test.ts ADDED Viewed

@@ -0,0 +1,28 @@
+import type { HealthResponse } from '../src/health/health.service.js'
+import request from 'supertest'
+import { describe, expect, it } from 'vitest'
+import { createApp } from '../src/app.js'
+import { readConfig } from '../src/config.js'
+const config = readConfig({ NODE_ENV: 'test' })
+describe('health endpoint', () => {
+  it('answers ok with the contract shape', async () => {
+    const response = await request(createApp(config)).get('/health')
+    expect(response.status).toBe(200)
+    expect(response.body).toEqual({ status: 'ok', service: config.serviceName, time: expect.any(String) })
+    expect(response.headers['x-powered-by']).toBeUndefined()
+  })
+  it('answers 503 when the probe fails', async () => {
+    const app = createApp(config, { healthProbe: { ping: async () => false } })
+    const response = await request(app).get('/health')
+    expect(response.status).toBe(503)
+    expect((response.body as HealthResponse).status).toBe('error')
+  })
+  it('answers 404 for a route outside the contract', async () => {
+    const response = await request(createApp(config)).get('/nowhere')
+    expect(response.status).toBe(404)
+  })
+})

package/templates/stacks/express-api/app/tests/http/error-handler.middleware.test.ts ADDED Viewed

@@ -0,0 +1,48 @@
+import type { NextFunction, Request, Response } from 'express'
+import { describe, expect, it, vi } from 'vitest'
+import { AppError } from '../../src/http/app-error.js'
+import { errorHandler } from '../../src/http/error-handler.middleware.js'
+interface CapturedResponse {
+  statusCode: number
+  body: unknown
+}
+function handle(error: unknown): CapturedResponse {
+  const captured: CapturedResponse = { statusCode: 0, body: undefined }
+  const res = {
+    headersSent: false,
+    status(code: number) {
+      captured.statusCode = code
+      return this
+    },
+    json(payload: unknown) {
+      captured.body = payload
+    },
+  }
+  errorHandler(error, {} as Request, res as unknown as Response, (() => {}) as NextFunction)
+  return captured
+}
+describe('errorHandler', () => {
+  it('answers an AppError with its status, code and message only', () => {
+    expect(handle(new AppError('THING_MISSING', 404, 'no such thing')))
+      .toEqual({ statusCode: 404, body: { error: 'THING_MISSING', message: 'no such thing' } })
+  })
+  it('maps a contract validation failure to VALIDATION_ERROR with the offending paths', () => {
+    const contractError = Object.assign(new Error('request failed'), {
+      status: 400,
+      errors: [{ path: '/body/name', message: 'must be string' }],
+    })
+    expect(handle(contractError))
+      .toEqual({ statusCode: 400, body: { error: 'VALIDATION_ERROR', message: '/body/name must be string' } })
+  })
+  it('hides the cause of an unexpected error behind a generic 500 body', () => {
+    const log = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const result = handle(new Error('connect ECONNREFUSED db:5432 password=hunter2'))
+    log.mockRestore()
+    expect(result).toEqual({ statusCode: 500, body: { error: 'INTERNAL_ERROR', message: 'Internal server error' } })
+  })
+})

package/templates/stacks/express-api/repo/architecture/composition/http.yaml.eta ADDED Viewed

@@ -0,0 +1,45 @@
+id: http
+title: HTTP API composition
+description: >-
+  `createApp(config, dependencies)` is the composition root: middleware runs in the order shown, every
+  service is constructed there and handed to a controller, and nothing else constructs a service.
+  Dotted edges are wiring, solid edges are the request path.
+doc: architecture/http.md
+boundaries:
+  - id: middleware
+    label: Middleware, in order
+  - id: routes
+    label: Controllers by route
+  - id: services
+    label: Services
+nodes:
+  - id: app
+    label: createApp(config, dependencies)
+    path: {{appRoot}}src/app.ts
+    boundary: middleware
+  - id: body
+    label: express.json
+    boundary: middleware
+  - id: contract
+    label: API contract validator
+    path: {{appRoot}}src/http/api-contract.middleware.ts
+    boundary: middleware
+  - id: errors
+    label: errorHandler
+    path: {{appRoot}}src/http/error-handler.middleware.ts
+    boundary: middleware
+  - id: c_health
+    label: GET /health
+    path: {{appRoot}}src/health/health.controller.ts
+    boundary: routes
+  - id: s_health
+    label: HealthService
+    path: {{appRoot}}src/health/health.service.ts
+    boundary: services
+edges:
+  - {from: app, to: body, kind: sequence}
+  - {from: body, to: contract, kind: sequence}
+  - {from: contract, to: c_health, kind: route}
+  - {from: c_health, to: s_health, kind: sequence}
+  - {from: c_health, to: errors, kind: sequence, label: on error}
+  - {from: app, to: s_health, kind: wires, label: constructs}

package/templates/stacks/express-api/repo/architecture/http.md ADDED Viewed

@@ -0,0 +1,39 @@
+# HTTP API
+The request path and the wiring below are rendered from
+[composition/http.yaml](composition/http.yaml). Edit the model, then run `pnpm composition:render`;
+`pnpm composition:check` fails when the diagram and the model drift apart.
+<!-- composition:http -->
+`createApp(config, dependencies)` is the composition root: middleware runs in the order shown, every service is constructed there and handed to a controller, and nothing else constructs a service. Dotted edges are wiring, solid edges are the request path.
+```mermaid
+flowchart LR
+  subgraph b_middleware["Middleware, in order"]
+    app["createApp(config, dependencies)"]
+    body["express.json"]
+    contract["API contract validator"]
+    errors["errorHandler"]
+  end
+  subgraph b_routes["Controllers by route"]
+    c_health["GET /health"]
+  end
+  subgraph b_services["Services"]
+    s_health["HealthService"]
+  end
+  app --> body
+  body --> contract
+  contract --> c_health
+  c_health --> s_health
+  c_health -->|"on error"| errors
+  app -.->|"constructs"| s_health
+```
+<!-- /composition:http -->
+## Conventions
+File names carry the role: `*.controller.ts` (routing and HTTP), `*.service.ts` (business logic),
+`*.middleware.ts` (Express middleware). One feature per directory. `src/config.ts` is the only reader
+of `process.env`; `src/http/` is the only place that reads `req.body`, `req.query` or `req.params`
+(both are lint rules). Expected failures throw `AppError(code, status, message)`; the global
+`errorHandler` turns it into `{ error, message }`, and anything else becomes a 500 with a generic body.

package/templates/stacks/http-contract/_github/workflows/api-contract.yml ADDED Viewed

@@ -0,0 +1,36 @@
+name: API contract
+on:
+  pull_request:
+    paths:
+      - contracts/**
+permissions:
+  contents: read
+jobs:
+  breaking-changes:
+    name: Breaking changes against ${{ github.base_ref }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: Check whether the base branch has the contract
+        id: base
+        run: |
+          if git cat-file -e "origin/${{ github.base_ref }}:contracts/api/openapi.yaml" 2>/dev/null; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::contracts/api/openapi.yaml is not on origin/${{ github.base_ref }}; skipping the breaking-change comparison"
+          fi
+      - name: Compare with the base branch
+        if: steps.base.outputs.exists == 'true'
+        uses: oasdiff/oasdiff-action/breaking@v0
+        with:
+          base: origin/${{ github.base_ref }}:contracts/api/openapi.yaml
+          revision: HEAD:contracts/api/openapi.yaml
+          fail-on: ERR