@webstir-io/webstir-backend 0.1.15

package/tests/cacheReporter.test.js

@@ -0,0 +1,89 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { createCacheReporter } from '../dist/cache/reporters.js';
+
+async function createWorkspace(prefix = 'webstir-backend-cache-') {
+  return await fs.mkdtemp(path.join(os.tmpdir(), prefix));
+}
+
+function makeManifest(overrides = {}) {
+  return {
+    contractVersion: '1.0.0',
+    name: '@demo/test',
+    version: '0.0.1',
+    kind: 'backend',
+    capabilities: [],
+    routes: [],
+    views: [],
+    jobs: [],
+    events: [],
+    services: [],
+    ...overrides
+  };
+}
+
+test('cache reporter emits diagnostics for output and manifest diffs', async () => {
+  const workspaceRoot = await createWorkspace();
+  const diagnostics = [];
+  const reporter = createCacheReporter({
+    workspaceRoot,
+    buildRoot: path.join(workspaceRoot, 'build', 'backend'),
+    env: {},
+    diagnostics
+  });
+
+  await reporter.diffOutputs({ 'index.js': 128 }, 'build');
+  assert.ok(
+    diagnostics.some((d) => d.message.includes('changed 1 file')),
+    'expected first diff to report changed files'
+  );
+
+  diagnostics.length = 0;
+
+  await reporter.diffOutputs({ 'index.js': 256 }, 'build');
+  assert.ok(
+    diagnostics.some((d) => d.message.includes('changed 1 file')),
+    'expected subsequent diffs to report changed files'
+  );
+
+  diagnostics.length = 0;
+
+  await reporter.diffManifest(makeManifest());
+  assert.equal(diagnostics.length, 0, 'first manifest digest should not emit diagnostics');
+
+  await reporter.diffManifest(
+    makeManifest({
+      routes: [{ method: 'GET', path: '/accounts' }]
+    })
+  );
+  assert.ok(
+    diagnostics.some((d) => d.message.includes('manifest changed')),
+    'expected manifest changes to produce diagnostics'
+  );
+});
+
+test('cache reporter can silence diagnostics via env', async () => {
+  const workspaceRoot = await createWorkspace();
+  const diagnostics = [];
+  const reporter = createCacheReporter({
+    workspaceRoot,
+    buildRoot: path.join(workspaceRoot, 'build', 'backend'),
+    env: { WEBSTIR_BACKEND_CACHE_LOG: 'off' },
+    diagnostics
+  });
+
+  await reporter.diffOutputs({ 'index.js': 128 }, 'build');
+  await reporter.diffOutputs({ 'index.js': 256 }, 'build');
+  await reporter.diffManifest(makeManifest());
+  await reporter.diffManifest(
+    makeManifest({
+      routes: [{ method: 'POST', path: '/silent' }]
+    })
+  );
+
+  assert.equal(diagnostics.length, 0, 'expected diagnostics to stay empty when logging disabled');
+});

package/tests/envLoader.test.js

@@ -0,0 +1,64 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { backendProvider } from '../dist/index.js';
+
+async function createTempWorkspace(prefix = 'webstir-backend-env-') {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), prefix));
+  return dir;
+}
+
+async function copyFile(src, dest) {
+  await fs.mkdir(path.dirname(dest), { recursive: true });
+  await fs.copyFile(src, dest);
+}
+
+function getLocalBinPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const pkgRoot = path.resolve(here, '..');
+  return path.join(pkgRoot, 'node_modules', '.bin');
+}
+
+test('env loader reads .env files and surfaces typed config', async () => {
+  const workspace = await createTempWorkspace();
+  const assets = await backendProvider.getScaffoldAssets();
+  for (const asset of assets) {
+    await copyFile(asset.sourcePath, path.join(workspace, asset.targetPath));
+  }
+  await fs.writeFile(
+    path.join(workspace, 'package.json'),
+    JSON.stringify(
+      {
+        name: '@demo/env-loader',
+        version: '0.0.0',
+        type: 'module'
+      },
+      null,
+      2
+    ),
+    'utf8'
+  );
+
+  const envContents = `NODE_ENV=development\nPORT=5055\nAPI_BASE_URL=https://api.example.com\n`;
+  await fs.writeFile(path.join(workspace, '.env'), envContents, 'utf8');
+
+  const env = {
+    WEBSTIR_MODULE_MODE: 'build',
+    WEBSTIR_BACKEND_TYPECHECK: 'skip',
+    NODE_OPTIONS: '--experimental-transform-types',
+    PATH: `${getLocalBinPath()}${path.delimiter}${process.env.PATH ?? ''}`
+  };
+
+  await backendProvider.build({ workspaceRoot: workspace, env, incremental: false });
+
+  const builtEnvModule = path.join(workspace, 'build', 'backend', 'env.js');
+  const mod = await import(pathToFileURL(builtEnvModule).href);
+  const loaded = mod.loadEnv();
+
+  assert.equal(loaded.PORT, 5055);
+  assert.equal(loaded.API_BASE_URL, 'https://api.example.com');
+});

package/tests/integration.test.js

@@ -0,0 +1,108 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import fssync from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { backendProvider } from '../dist/index.js';
+
+async function createTempWorkspace(prefix = 'webstir-backend-workspace-') {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), prefix));
+  return dir;
+}
+
+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 hydrateBackendScaffold(workspace) {
+  const assets = await backendProvider.getScaffoldAssets();
+
+  for (const asset of assets) {
+    const normalized = asset.targetPath.replace(/\\/g, '/');
+    if (!normalized.includes('src/backend/')) {
+      continue;
+    }
+
+    const target = path.join(workspace, asset.targetPath);
+    await copyFile(asset.sourcePath, target);
+  }
+}
+
+
+function getLocalBinPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const pkgRoot = path.resolve(here, '..');
+  return path.join(pkgRoot, 'node_modules', '.bin');
+}
+
+test('build mode produces transpiled output and manifest', async () => {
+  const workspace = await createTempWorkspace();
+  await hydrateBackendScaffold(workspace);
+
+  const bin = getLocalBinPath();
+  const env = {
+    WEBSTIR_MODULE_MODE: 'build',
+    WEBSTIR_BACKEND_TYPECHECK: 'skip',
+    PATH: `${bin}${path.delimiter}${process.env.PATH ?? ''}`,
+  };
+
+  const result = await backendProvider.build({ workspaceRoot: workspace, env, incremental: false });
+
+  const buildRoot = path.join(workspace, 'build', 'backend');
+  const outFile = path.join(buildRoot, 'index.js');
+  assert.equal(fssync.existsSync(outFile), true, 'expected build/backend/index.js to exist');
+
+  assert.ok(Array.isArray(result.manifest.entryPoints));
+  assert.ok(result.manifest.entryPoints.some((e) => e.endsWith('index.js')));
+});
+
+test('publish mode bundles output and manifest has entry', async () => {
+  const workspace = await createTempWorkspace();
+  await hydrateBackendScaffold(workspace);
+
+  const bin = getLocalBinPath();
+  const env = {
+    WEBSTIR_MODULE_MODE: 'publish',
+    WEBSTIR_BACKEND_TYPECHECK: 'skip',
+    PATH: `${bin}${path.delimiter}${process.env.PATH ?? ''}`,
+  };
+
+  const result = await backendProvider.build({ workspaceRoot: workspace, env, incremental: false });
+
+  const buildRoot = path.join(workspace, 'build', 'backend');
+  const outFile = path.join(buildRoot, 'index.js');
+  assert.equal(fssync.existsSync(outFile), true, 'expected build/backend/index.js to exist');
+
+  assert.ok(result.manifest.entryPoints.length >= 1);
+});
+
+test('publish mode emits sourcemaps when opt-in flag is set', async () => {
+  const workspace = await createTempWorkspace();
+  await hydrateBackendScaffold(workspace);
+
+  const bin = getLocalBinPath();
+  const env = {
+    WEBSTIR_MODULE_MODE: 'publish',
+    WEBSTIR_BACKEND_SOURCEMAPS: 'on',
+    WEBSTIR_BACKEND_TYPECHECK: 'skip',
+    PATH: `${bin}${path.delimiter}${process.env.PATH ?? ''}`,
+  };
+
+  const result = await backendProvider.build({ workspaceRoot: workspace, env, incremental: false });
+
+  const buildRoot = path.join(workspace, 'build', 'backend');
+  const mapFile = path.join(buildRoot, 'index.js.map');
+  assert.equal(fssync.existsSync(mapFile), true, 'expected build/backend/index.js.map to exist');
+  assert.ok(
+    result.artifacts.some((artifact) => artifact.path.endsWith('index.js.map') && artifact.type === 'asset'),
+    'expected index.js.map to be included as an asset artifact'
+  );
+});

package/tests/manifest.test.js

@@ -0,0 +1,159 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { backendProvider } from '../dist/index.js';
+
+async function createTempWorkspace(prefix = 'webstir-backend-manifest-') {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), prefix));
+  return dir;
+}
+
+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);
+}
+
+function getLocalBinPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const pkgRoot = path.resolve(here, '..');
+  return path.join(pkgRoot, 'node_modules', '.bin');
+}
+
+async function seedBackendEntry(workspace) {
+  const assets = await backendProvider.getScaffoldAssets();
+  for (const asset of assets) {
+    if (!asset.targetPath.endsWith(path.join('backend', 'index.ts'))) continue;
+    const target = path.join(workspace, asset.targetPath);
+    await copyFile(asset.sourcePath, target);
+  }
+}
+
+test('manifest loader honors package overrides', async () => {
+  const workspace = await createTempWorkspace();
+  await seedBackendEntry(workspace);
+
+  const pkgJson = {
+    name: '@demo/backend',
+    version: '1.0.0',
+    type: 'module',
+    webstir: {
+      moduleManifest: {
+        contractVersion: '1.0.0',
+        name: '@demo/custom',
+        version: '2.0.0',
+        kind: 'backend',
+        capabilities: ['db']
+      }
+    }
+  };
+  await fs.writeFile(path.join(workspace, 'package.json'), JSON.stringify(pkgJson, null, 2), 'utf8');
+
+  const env = {
+    WEBSTIR_MODULE_MODE: 'build',
+    PATH: `${getLocalBinPath()}${path.delimiter}${process.env.PATH ?? ''}`
+  };
+
+  const result = await backendProvider.build({ workspaceRoot: workspace, env, incremental: false });
+  const moduleManifest = result.manifest.module;
+
+  assert.equal(moduleManifest?.name, '@demo/custom');
+  assert.equal(moduleManifest?.version, '2.0.0');
+  assert.deepEqual(moduleManifest?.capabilities, ['db']);
+});
+
+test('manifest loader falls back to package name/version when no overrides present', async () => {
+  const workspace = await createTempWorkspace();
+  await seedBackendEntry(workspace);
+
+  const pkgJson = {
+    name: '@demo/fallback',
+    version: '4.5.6',
+    type: 'module'
+  };
+  await fs.writeFile(path.join(workspace, 'package.json'), JSON.stringify(pkgJson, null, 2), 'utf8');
+
+  const env = {
+    WEBSTIR_MODULE_MODE: 'build',
+    PATH: `${getLocalBinPath()}${path.delimiter}${process.env.PATH ?? ''}`
+  };
+
+  const result = await backendProvider.build({ workspaceRoot: workspace, env, incremental: false });
+  const moduleManifest = result.manifest.module;
+
+  assert.equal(moduleManifest?.name, '@demo/fallback');
+  assert.equal(moduleManifest?.version, '4.5.6');
+});
+
+test('manifest loader merges compiled module definition metadata', async () => {
+  const workspace = await createTempWorkspace();
+  await seedBackendEntry(workspace);
+
+  const moduleSource = `export const module = {
+  manifest: {
+    contractVersion: '1.0.0',
+    name: '@demo/with-module',
+    version: '9.9.9',
+    kind: 'backend',
+    capabilities: ['search'],
+    routes: [],
+    views: []
+  }
+};
+`;
+
+  await fs.writeFile(path.join(workspace, 'src', 'backend', 'module.ts'), moduleSource, 'utf8');
+  await fs.writeFile(
+    path.join(workspace, 'package.json'),
+    JSON.stringify({ name: '@demo/fallback-package', version: '0.0.1', type: 'module' }, null, 2),
+    'utf8'
+  );
+
+  const env = {
+    WEBSTIR_MODULE_MODE: 'build',
+    PATH: `${getLocalBinPath()}${path.delimiter}${process.env.PATH ?? ''}`
+  };
+
+  const result = await backendProvider.build({ workspaceRoot: workspace, env, incremental: false });
+  const moduleManifest = result.manifest.module;
+
+  assert.equal(moduleManifest?.name, '@demo/with-module');
+  assert.equal(moduleManifest?.version, '9.9.9');
+  assert.deepEqual(moduleManifest?.capabilities, ['search']);
+  assert.deepEqual(moduleManifest?.capabilities, ['search']);
+});
+
+test('scaffold assets expose core backend templates', async () => {
+  const assets = await backendProvider.getScaffoldAssets();
+  const targetSet = new Set(assets.map((asset) => asset.targetPath));
+
+  const requiredTargets = [
+    path.join('src', 'backend', 'tsconfig.json'),
+    path.join('src', 'backend', 'index.ts'),
+    path.join('src', 'backend', 'module.ts'),
+    path.join('src', 'backend', 'server', 'fastify.ts'),
+    path.join('src', 'backend', 'auth', 'adapter.ts'),
+    path.join('src', 'backend', 'observability', 'logger.ts'),
+    path.join('src', 'backend', 'observability', 'metrics.ts'),
+    path.join('src', 'backend', 'functions', 'hello', 'index.ts'),
+    path.join('src', 'backend', 'jobs', 'nightly', 'index.ts'),
+    path.join('src', 'backend', 'jobs', 'runtime.ts'),
+    path.join('src', 'backend', 'jobs', 'scheduler.ts'),
+    path.join('src', 'backend', 'db', 'connection.ts'),
+    path.join('src', 'backend', 'db', 'migrate.ts'),
+    path.join('src', 'backend', 'db', 'migrations', '0001-example.ts'),
+    path.join('src', 'backend', 'db', 'types.d.ts'),
+    path.join('.env.example')
+  ];
+
+  for (const target of requiredTargets) {
+    assert.ok(targetSet.has(target), `expected scaffold assets to include ${target}`);
+  }
+});

package/tests/watch.test.js

@@ -0,0 +1,100 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { startBackendWatch } from '../dist/watch.js';
+import { backendProvider } from '../dist/index.js';
+
+async function createTempWorkspace(prefix = 'webstir-backend-watch-') {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), prefix));
+  return dir;
+}
+
+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 seedBackendEntry(workspace) {
+  const assets = await backendProvider.getScaffoldAssets();
+  for (const asset of assets) {
+    if (!asset.targetPath.endsWith(path.join('backend', 'index.ts'))) continue;
+    const target = path.join(workspace, asset.targetPath);
+    await copyFile(asset.sourcePath, target);
+  }
+}
+
+function getLocalBinPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const pkgRoot = path.resolve(here, '..');
+  return path.join(pkgRoot, 'node_modules', '.bin');
+}
+
+async function waitFor(checkFn, timeoutMs = 5000, pollMs = 100) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (await checkFn()) return;
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+  throw new Error('waitFor timed out');
+}
+
+test('startBackendWatch updates cache files after rebuild', async () => {
+  const workspace = await createTempWorkspace();
+  await seedBackendEntry(workspace);
+
+  const env = {
+    WEBSTIR_MODULE_MODE: 'build',
+    WEBSTIR_BACKEND_TYPECHECK: 'skip',
+    PATH: `${getLocalBinPath()}${path.delimiter}${process.env.PATH ?? ''}`
+  };
+
+  const handle = await startBackendWatch({ workspaceRoot: workspace, env });
+  try {
+    const outputsPath = path.join(workspace, '.webstir', 'backend-outputs.json');
+
+    await waitFor(async () => {
+      try {
+        await fs.access(outputsPath);
+        return true;
+      } catch {
+        return false;
+      }
+    });
+
+    const before = JSON.parse(await fs.readFile(outputsPath, 'utf8'));
+    const indexPath = path.join(workspace, 'src', 'backend', 'index.ts');
+    await fs.appendFile(indexPath, '\nconsole.log("watch-test");\n', 'utf8');
+
+    await waitFor(async () => {
+      try {
+        const after = JSON.parse(await fs.readFile(outputsPath, 'utf8'));
+        const key = Object.keys(after)[0];
+        return before[key] !== after[key];
+      } catch {
+        return false;
+      }
+    });
+
+    const manifestDigestPath = path.join(workspace, '.webstir', 'backend-manifest-digest.json');
+    await waitFor(async () => {
+      try {
+        await fs.access(manifestDigestPath);
+        return true;
+      } catch {
+        return false;
+      }
+    });
+
+    assert.ok(true, 'watch updated cache files after rebuild');
+  } finally {
+    await handle.stop();
+  }
+});

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": false,
+    "sourceMap": false,
+    "types": [
+      "node"
+    ],
+    "resolveJsonModule": true
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "dist",
+    "node_modules"
+  ]
+}