@webstir-io/webstir-backend 0.1.15

package/dist/watch.d.ts

@@ -0,0 +1,8 @@
+export interface WatchHandle {
+    stop(): Promise<void>;
+}
+export interface StartWatchOptions {
+    readonly workspaceRoot: string;
+    readonly env?: Record<string, string | undefined>;
+}
+export declare function startBackendWatch(options: StartWatchOptions): Promise<WatchHandle>;

package/dist/watch.js

@@ -0,0 +1,159 @@
+import path from 'node:path';
+import { existsSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { performance } from 'node:perf_hooks';
+import { context as createEsbuildContext } from 'esbuild';
+import { collectOutputSizes, formatEsbuildMessage, shouldTypeCheck } from './build/pipeline.js';
+import { discoverEntryPoints } from './build/entries.js';
+import { loadBackendModuleManifest } from './manifest/pipeline.js';
+import { createCacheReporter } from './cache/reporters.js';
+import { normalizeMode, resolveWorkspacePaths } from './workspace.js';
+export async function startBackendWatch(options) {
+    const { workspaceRoot } = options;
+    const env = options.env ?? {};
+    const paths = resolveWorkspacePaths(workspaceRoot);
+    const tsconfigPath = path.join(paths.sourceRoot, 'tsconfig.json');
+    const mode = normalizeMode(env.WEBSTIR_MODULE_MODE);
+    const entryPoints = await discoverEntryPoints(paths.sourceRoot);
+    if (entryPoints.length === 0) {
+        console.warn(`[webstir-backend] watch: no entry found under ${paths.sourceRoot} (index.ts/js)`);
+        throw new Error('No backend entry point found.');
+    }
+    const nodeEnv = env.NODE_ENV ?? (mode === 'publish' ? 'production' : 'development');
+    const diagMax = (() => {
+        const raw = env.WEBSTIR_BACKEND_DIAG_MAX;
+        const n = typeof raw === 'string' ? parseInt(raw, 10) : NaN;
+        return Number.isFinite(n) && n > 0 ? n : 20;
+    })();
+    console.info(`[webstir-backend] watch:start (${mode})`);
+    // Start type-checker in watch mode (no emit) unless explicitly skipped for DX.
+    const shouldRunTypecheck = shouldTypeCheck(mode, env);
+    let tscProc;
+    if (shouldRunTypecheck) {
+        const tscArgs = ['-p', tsconfigPath, '--noEmit', '--watch'];
+        tscProc = spawn('tsc', tscArgs, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, ...env, NODE_ENV: nodeEnv },
+            cwd: workspaceRoot,
+        });
+        tscProc.stdout?.on('data', (chunk) => {
+            const text = chunk.toString();
+            for (const line of text.split(/\r?\n/)) {
+                if (line)
+                    console.info(`[webstir-backend][tsc] ${line}`);
+            }
+        });
+        tscProc.stderr?.on('data', (chunk) => {
+            const text = chunk.toString();
+            for (const line of text.split(/\r?\n/)) {
+                if (line)
+                    console.warn(`[webstir-backend][tsc] ${line}`);
+            }
+        });
+    }
+    else {
+        console.info('[webstir-backend] watch: type-check skipped by WEBSTIR_BACKEND_TYPECHECK');
+    }
+    const timingPlugin = {
+        name: 'webstir-watch-logger',
+        setup(build) {
+            let start = 0;
+            build.onStart(() => {
+                start = performance.now();
+            });
+            build.onEnd(async (result) => {
+                const end = performance.now();
+                const warnCount = result.warnings?.length ?? 0;
+                // errors is not in the typed result, but present at runtime
+                const errorList = result.errors ?? [];
+                const errorCount = Array.isArray(errorList) ? errorList.length : 0;
+                // Print detailed diagnostics with file:line when available (capped for readability)
+                if (errorCount > 0) {
+                    for (const msg of errorList.slice(0, diagMax)) {
+                        const text = formatEsbuildMessage(msg);
+                        console.error(`[webstir-backend][esbuild] ${text}`);
+                    }
+                    if (errorCount > diagMax) {
+                        console.error(`[webstir-backend][esbuild] ... ${errorCount - diagMax} more error(s) omitted`);
+                    }
+                }
+                if (warnCount > 0) {
+                    for (const msg of result.warnings.slice(0, diagMax)) {
+                        const text = formatEsbuildMessage(msg);
+                        console.warn(`[webstir-backend][esbuild] ${text}`);
+                    }
+                    if (warnCount > diagMax) {
+                        console.warn(`[webstir-backend][esbuild] ... ${warnCount - diagMax} more warning(s) omitted`);
+                    }
+                }
+                console.info(`[webstir-backend] watch:esbuild ${errorCount} error(s), ${warnCount} warning(s) in ${(end - start).toFixed(1)}ms`);
+                if (errorCount === 0) {
+                    const diagBuffer = [];
+                    const cacheReporter = createCacheReporter({
+                        workspaceRoot,
+                        buildRoot: paths.buildRoot,
+                        env,
+                        diagnostics: diagBuffer
+                    });
+                    try {
+                        const metafile = result.metafile;
+                        if (metafile && metafile.outputs) {
+                            const outputs = collectOutputSizes(metafile, paths.buildRoot);
+                            await cacheReporter.diffOutputs(outputs, mode);
+                        }
+                        const manifest = await loadBackendModuleManifest({
+                            workspaceRoot,
+                            buildRoot: paths.buildRoot,
+                            entryPoints,
+                            diagnostics: diagBuffer
+                        });
+                        await cacheReporter.diffManifest(manifest);
+                    }
+                    catch {
+                        // cache or manifest diff failure should not break watch
+                    }
+                    finally {
+                        for (const diag of diagBuffer) {
+                            const logger = diag.severity === 'error' ? console.error : diag.severity === 'warn' ? console.warn : console.info;
+                            logger(diag.message);
+                        }
+                    }
+                }
+            });
+        },
+    };
+    const ctx = await createEsbuildContext({
+        entryPoints,
+        bundle: false,
+        platform: 'node',
+        target: 'node20',
+        format: 'esm',
+        sourcemap: true,
+        outdir: paths.buildRoot,
+        outbase: paths.sourceRoot,
+        metafile: true,
+        tsconfig: existsSync(tsconfigPath) ? tsconfigPath : undefined,
+        define: { 'process.env.NODE_ENV': JSON.stringify(nodeEnv) },
+        logLevel: 'silent',
+        plugins: [timingPlugin],
+    });
+    await ctx.watch();
+    console.info('[webstir-backend] watch:ready');
+    return {
+        async stop() {
+            try {
+                await ctx.dispose();
+            }
+            catch {
+                // ignore
+            }
+            try {
+                tscProc?.kill('SIGINT');
+            }
+            catch {
+                // ignore
+            }
+            console.info('[webstir-backend] watch:stopped');
+        },
+    };
+}

package/dist/workspace.d.ts

@@ -0,0 +1,4 @@
+import type { ResolvedModuleWorkspace } from '@webstir-io/module-contract';
+export type BackendBuildMode = 'build' | 'publish' | 'test';
+export declare function resolveWorkspacePaths(workspaceRoot: string): ResolvedModuleWorkspace;
+export declare function normalizeMode(rawMode: unknown): BackendBuildMode;

package/dist/workspace.js

@@ -0,0 +1,15 @@
+import path from 'node:path';
+export function resolveWorkspacePaths(workspaceRoot) {
+    return {
+        sourceRoot: path.join(workspaceRoot, 'src', 'backend'),
+        buildRoot: path.join(workspaceRoot, 'build', 'backend'),
+        testsRoot: path.join(workspaceRoot, 'src', 'backend', 'tests')
+    };
+}
+export function normalizeMode(rawMode) {
+    if (typeof rawMode !== 'string') {
+        return 'build';
+    }
+    const normalized = rawMode.toLowerCase();
+    return normalized === 'publish' || normalized === 'test' ? normalized : 'build';
+}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@webstir-io/webstir-backend",
+  "version": "0.1.15",
+  "description": "Reserved manifest for the future Webstir backend tooling package.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./provider": {
+      "types": "./dist/provider.d.ts",
+      "import": "./dist/provider.js",
+      "default": "./dist/provider.js"
+    },
+    "./watch": {
+      "types": "./dist/watch.d.ts",
+      "import": "./dist/watch.js",
+      "default": "./dist/watch.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js",
+      "default": "./dist/testing/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node -e \"const { spawnSync } = require('node:child_process'); const glob = require('glob'); const files = glob.sync('tests/**/*.test.js'); if (!files.length) { console.error('No backend test files found'); process.exit(1); } const result = spawnSync(process.execPath, ['--test', ...files], { stdio: 'inherit' }); process.exit(result.status ?? 1);\"",
+    "clean": "rm -rf dist",
+    "prepare": "npm run build",
+    "watch": "npm run build && node -e \"import('./dist/watch.js').then(m=>m.startBackendWatch({workspaceRoot:process.cwd(),env:{WEBSTIR_MODULE_MODE:'build'}}));\"",
+    "dev": "npm run watch",
+    "dev:fast": "WEBSTIR_BACKEND_TYPECHECK=skip npm run watch",
+    "smoke": "npm run build && node scripts/smoke.mjs",
+    "release": "bash scripts/publish.sh"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "src",
+    "scripts",
+    "tests",
+    "tsconfig.json",
+    "package-lock.json"
+  ],
+  "engines": {
+    "node": ">=20.18.1"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/webstir-io/webstir-backend.git"
+  },
+  "dependencies": {
+    "@webstir-io/module-contract": "^0.1.13",
+    "esbuild": "^0.25.10",
+    "glob": "^10.4.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.21",
+    "fastify": "^5.6.2",
+    "pino": "^10.1.0",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}

package/scripts/publish.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: scripts/publish.sh <patch|minor|major|x.y.z> [--no-push]
+
+Examples:
+  scripts/publish.sh patch
+  scripts/publish.sh 0.1.0
+
+The script requires a clean git worktree.
+
+By default, the script pushes the version bump commit and tag. To skip pushing,
+pass --no-push or set PUBLISH_NO_PUSH=1.
+EOF
+  exit 1
+}
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+main() {
+  if [[ $# -lt 1 ]]; then
+    echo "error: version bump argument missing" >&2
+    usage
+  fi
+
+  local bump="$1"; shift || true
+  local no_push="false"
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --no-push)
+        no_push="true"
+        ;;
+      *)
+        echo "error: unknown option '$1'" >&2
+        usage
+        ;;
+    esac
+    shift || true
+  done
+
+  if [[ ! $bump =~ ^(patch|minor|major)$ && ! $bump =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+    echo "error: invalid bump '$bump'" >&2
+    usage
+  fi
+
+  ensure_clean_git
+
+  cd "$ROOT_DIR"
+
+  echo "› npm version $bump"
+  npm version "$bump" -m "v%s"
+
+  echo "› npm install --package-lock-only"
+  npm install --package-lock-only
+
+  echo "› npm run clean"
+  npm run clean
+
+  echo "› npm run build"
+  npm run build
+
+  echo "› npm test"
+  npm test
+
+  echo "› npm run smoke"
+  npm run smoke
+
+  echo "› Skipping direct npm publish; pushing commit+tag will trigger the release workflow."
+
+  if [[ "$no_push" == "true" || "${PUBLISH_NO_PUSH:-}" =~ ^([Yy][Ee][Ss]|[Yy]|1|true)$ ]]; then
+    echo "› Skipping git push (no-push)."
+    echo "  To publish upstream later, run: git push && git push --tags"
+    return 0
+  fi
+
+  echo "› git push"
+  git push
+  echo "› git push --tags"
+  git push --tags
+}
+
+ensure_clean_git() {
+  cd "$ROOT_DIR"
+  if ! git diff --quiet --ignore-submodules HEAD; then
+    echo "error: git worktree has uncommitted changes" >&2
+    exit 1
+  fi
+  if ! git diff --quiet --cached --ignore-submodules; then
+    echo "error: git index has staged changes" >&2
+    exit 1
+  fi
+}
+
+main "$@"

package/scripts/smoke.mjs

@@ -0,0 +1,241 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import { backendProvider } from '../dist/index.js';
+import { CONTRACT_VERSION } from '@webstir-io/module-contract';
+
+function getLocalBinPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const pkgRoot = path.resolve(here, '..');
+  return path.join(pkgRoot, 'node_modules', '.bin');
+}
+
+async function ensureDir(dir) {
+  await fs.mkdir(dir, { recursive: true });
+}
+
+async function copyFile(src, dest) {
+  await ensureDir(path.dirname(dest));
+  await fs.copyFile(src, dest);
+}
+
+async function installPackages(workspace, packages, options = { dev: false }) {
+  if (!packages || packages.length === 0) return;
+  const args = ['install', '--silent', ...packages];
+  if (options.dev) {
+    args.push('-D');
+  }
+  await new Promise((resolve, reject) => {
+    const child = spawn('npm', args, { cwd: workspace, stdio: 'ignore' });
+    child.on('error', reject);
+    child.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`npm install failed (${code})`))));
+  });
+}
+
+async function main() {
+  const workspace = await fs.mkdtemp(path.join(os.tmpdir(), 'webstir-backend-smoke-'));
+  const assets = await backendProvider.getScaffoldAssets();
+  await Promise.all(
+    assets.map(async (asset) => {
+      const target = path.join(workspace, asset.targetPath);
+      await copyFile(asset.sourcePath, target);
+    })
+  );
+
+  const backendTsconfigPath = path.join(workspace, 'src', 'backend', 'tsconfig.json');
+  try {
+    const backendTsconfigRaw = await fs.readFile(backendTsconfigPath, 'utf8');
+    const backendTsconfig = JSON.parse(backendTsconfigRaw);
+    if (backendTsconfig?.compilerOptions) {
+      delete backendTsconfig.compilerOptions.types;
+    }
+    await fs.writeFile(backendTsconfigPath, `${JSON.stringify(backendTsconfig, null, 2)}\n`, 'utf8');
+  } catch (error) {
+    console.warn('[smoke] failed to adjust backend tsconfig:', error);
+  }
+
+  const packageJsonPath = path.join(workspace, 'package.json');
+  const packageJson = {
+    name: '@smoke/backend',
+    version: '0.0.0',
+    private: true,
+    type: 'module',
+    webstir: {
+      module: {
+        contractVersion: CONTRACT_VERSION,
+        name: '@smoke/backend',
+        version: '0.0.0',
+        kind: 'backend',
+        capabilities: [],
+        routes: [],
+        views: []
+      }
+    }
+  };
+  await fs.writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`, 'utf8');
+
+  await installPackages(workspace, ['pino', 'better-sqlite3']);
+
+  if (process.env.WEBSTIR_BACKEND_SMOKE_FASTIFY !== 'skip') {
+    // Add optional Fastify dependency so the scaffold type-checks if present
+    try {
+      await installPackages(workspace, ['fastify', '@types/node@^20'], { dev: true });
+    } catch (err) {
+      console.warn('[smoke] skipping Fastify install:', err);
+    }
+  } else {
+    console.info('[smoke] fastify install skipped by WEBSTIR_BACKEND_SMOKE_FASTIFY=skip');
+  }
+
+  const rootTsconfigPath = path.join(workspace, 'tsconfig.json');
+  const rootTsconfig = {
+    compilerOptions: {
+      target: 'ES2022',
+      module: 'NodeNext',
+      moduleResolution: 'NodeNext',
+      resolveJsonModule: true,
+      strict: true,
+      isolatedModules: true,
+      esModuleInterop: true,
+      skipLibCheck: true
+    }
+  };
+  await fs.writeFile(rootTsconfigPath, `${JSON.stringify(rootTsconfig, null, 2)}\n`, 'utf8');
+
+  const envBase = {
+    PATH: `${getLocalBinPath()}${path.delimiter}${process.env.PATH ?? ''}`,
+    WEBSTIR_BACKEND_TYPECHECK: 'skip',
+    // Exercise provider diagnostic filtering: suppress info by default
+    WEBSTIR_BACKEND_LOG_LEVEL: 'warn'
+  };
+
+  console.info('[smoke] build mode');
+  const buildResult = await backendProvider.build({
+    workspaceRoot: workspace,
+    env: { ...envBase, WEBSTIR_MODULE_MODE: 'build' },
+    incremental: false
+  });
+  const buildEntries = buildResult.manifest.entryPoints;
+  const buildFunctions = buildEntries.filter((p) => p.startsWith('functions/')).length;
+  const buildJobs = buildEntries.filter((p) => p.startsWith('jobs/')).length;
+  const buildServer = buildEntries.filter((p) => p === 'index.js' || /(^|\/)index\.js$/.test(p) && !/^(functions|jobs)\//.test(p)).length;
+  console.info('[smoke] build entryPoints:', buildEntries);
+  console.info('[smoke] build entry counts:', { server: buildServer, functions: buildFunctions, jobs: buildJobs });
+  if (buildFunctions < 1 || buildJobs < 1) {
+    throw new Error(`[smoke] expected scaffold to include functions and jobs (got functions=${buildFunctions}, jobs=${buildJobs})`);
+  }
+  const buildModule = buildResult.manifest.module ?? {};
+  console.info('[smoke] build routes/views summary:', {
+    routes: Array.isArray(buildModule.routes) ? buildModule.routes.length : 0,
+    views: Array.isArray(buildModule.views) ? buildModule.views.length : 0
+  });
+  console.info('[smoke] build diagnostics (>=warn):', buildResult.manifest.diagnostics.map((d) => d.message));
+
+  console.info('[smoke] publish mode');
+  const publishResult = await backendProvider.build({
+    workspaceRoot: workspace,
+    // Intentionally clear PATH so `tsc` is not found; provider will warn and continue
+    env: { ...envBase, WEBSTIR_MODULE_MODE: 'publish', PATH: '' },
+    incremental: false
+  });
+  const publishEntries = publishResult.manifest.entryPoints;
+  const publishFunctions = publishEntries.filter((p) => p.startsWith('functions/')).length;
+  const publishJobs = publishEntries.filter((p) => p.startsWith('jobs/')).length;
+  const publishServer = publishEntries.filter((p) => p === 'index.js' || /(^|\/)index\.js$/.test(p) && !/^(functions|jobs)\//.test(p)).length;
+  console.info('[smoke] publish entryPoints:', publishEntries);
+  console.info('[smoke] publish entry counts:', { server: publishServer, functions: publishFunctions, jobs: publishJobs });
+  if (publishFunctions < 1 || publishJobs < 1) {
+    throw new Error(`[smoke] expected scaffold to include functions and jobs after publish (got functions=${publishFunctions}, jobs=${publishJobs})`);
+  }
+  const publishModule = publishResult.manifest.module ?? {};
+  console.info('[smoke] publish routes/views summary:', {
+    routes: Array.isArray(publishModule.routes) ? publishModule.routes.length : 0,
+    views: Array.isArray(publishModule.views) ? publishModule.views.length : 0
+  });
+  const publishDiagnostics = publishResult.manifest.diagnostics
+    .map((d) => ({ ...d, message: d.message.trim() }))
+    .filter((d) => d.severity !== 'info');
+  const unexpectedPublishDiagnostics = publishDiagnostics.filter((d) => !/TypeScript compiler \(tsc\) not found|Type checking failed/.test(d.message));
+  if (unexpectedPublishDiagnostics.length > 0) {
+    console.info('[smoke] publish diagnostics (non-info):', unexpectedPublishDiagnostics.map((d) => d.message));
+  }
+
+  if (process.env.WEBSTIR_BACKEND_SMOKE_FASTIFY !== 'skip') {
+    // Fastify scaffold type-check (no run): ensure tsc sees server/fastify.ts
+    console.info('[smoke] fastify type-check');
+    const typecheckResult = await backendProvider.build({
+      workspaceRoot: workspace,
+      env: { PATH: envBase.PATH, WEBSTIR_BACKEND_LOG_LEVEL: 'warn', WEBSTIR_MODULE_MODE: 'build', WEBSTIR_BACKEND_TYPECHECK: 'skip' },
+      incremental: false
+    });
+    const typecheckErrors = typecheckResult.manifest.diagnostics.filter((d) => d.severity === 'error');
+    if (typecheckErrors.length > 0) {
+      throw new Error(`[smoke] fastify type-check reported errors: ${typecheckErrors.map((d) => d.message).join('; ')}`);
+    }
+
+    // Optionally run server and hit /api/health
+    if (process.env.WEBSTIR_BACKEND_SMOKE_FASTIFY_RUN !== 'skip') {
+      console.info('[smoke] fastify run + health check');
+      const port = 47891;
+      const child = spawn(process.execPath, ['build/backend/server/fastify.js'], {
+        cwd: workspace,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env, PORT: String(port) }
+      });
+
+      let ready = false;
+      const outChunks = [];
+      child.stdout.on('data', (c) => {
+        const s = c.toString();
+        outChunks.push(s);
+        if (!ready && s.includes('API server running')) {
+          ready = true;
+          (async () => {
+            try {
+              const res = await fetch(`http://127.0.0.1:${port}/api/health`);
+              if (!res.ok) throw new Error(`health returned ${res.status}`);
+              const json = await res.json();
+              if (!json || json.ok !== true) throw new Error('health payload invalid');
+            } catch (err) {
+              console.error('[smoke] fastify health check failed:', err);
+              child.kill();
+              throw err;
+            } finally {
+              child.kill();
+            }
+          })().catch((err) => {
+            console.error(err);
+            process.exitCode = 1;
+          });
+        }
+      });
+
+      await new Promise((resolve) => {
+        const timer = setTimeout(() => {
+          if (!ready) {
+            console.error('[smoke] fastify did not reach readiness');
+            child.kill();
+          }
+          resolve(null);
+        }, 8000);
+        child.on('close', () => {
+          clearTimeout(timer);
+          resolve(null);
+        });
+      });
+    } else {
+      console.info('[smoke] fastify run skipped by WEBSTIR_BACKEND_SMOKE_FASTIFY_RUN=skip');
+    }
+  } else {
+    console.info('[smoke] fastify type-check skipped by WEBSTIR_BACKEND_SMOKE_FASTIFY=skip');
+  }
+
+  console.info('[smoke] completed: build ✔ publish ✔ fastify ✔');
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});