@webstir-io/webstir-backend 0.1.15 → 0.1.16

package/templates/backend/session/sqlite.ts

@@ -0,0 +1,152 @@
+import { mkdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+import type {
+  SessionFlashMessage,
+  SessionStore,
+  SessionStoreRecord,
+} from '@webstir-io/webstir-backend/runtime/session';
+
+import { resolveWorkspaceRoot } from '../env.js';
+
+interface SqliteSessionStoreOptions {
+  url?: string;
+}
+
+interface SqliteSessionRow {
+  id: string;
+  value: string;
+  flash: string;
+  runtime: string;
+  createdAt: string;
+  expiresAt: string;
+}
+
+type SqliteDatabase = {
+  prepare(sql: string): {
+    run(...params: unknown[]): void;
+    get(...params: unknown[]): SqliteSessionRow | undefined;
+    all(...params: unknown[]): { name: string }[];
+  };
+};
+
+const DEFAULT_SQLITE_SESSION_STORE_URL = 'file:./data/sessions.sqlite';
+const SESSION_TABLE_NAME = 'webstir_sessions';
+const require = createRequire(import.meta.url);
+
+export function createSqliteSessionStore<
+  TSession extends Record<string, unknown> = Record<string, unknown>,
+>(options: SqliteSessionStoreOptions = {}): SessionStore<TSession> {
+  const Database = loadBunSqlite();
+  const target = normalizeSqlitePath(options.url ?? DEFAULT_SQLITE_SESSION_STORE_URL);
+  mkdirSync(path.dirname(target), { recursive: true });
+
+  const db = new Database(target) as SqliteDatabase;
+  db.prepare(`
+    CREATE TABLE IF NOT EXISTS ${SESSION_TABLE_NAME} (
+      id TEXT PRIMARY KEY,
+      value TEXT NOT NULL,
+      flash TEXT NOT NULL,
+      runtime TEXT NOT NULL DEFAULT '{}',
+      created_at TEXT NOT NULL,
+      expires_at TEXT NOT NULL
+    )
+  `).run();
+  ensureRuntimeColumn(db);
+  db.prepare(`
+    CREATE INDEX IF NOT EXISTS ${SESSION_TABLE_NAME}_expires_at_idx
+    ON ${SESSION_TABLE_NAME} (expires_at)
+  `).run();
+
+  const deleteExpiredStatement = db.prepare(
+    `DELETE FROM ${SESSION_TABLE_NAME} WHERE expires_at <= ?`,
+  );
+  const getStatement = db.prepare(`
+    SELECT id, value, flash, runtime, created_at AS createdAt, expires_at AS expiresAt
+    FROM ${SESSION_TABLE_NAME}
+    WHERE id = ?
+  `);
+  const setStatement = db.prepare(`
+    INSERT INTO ${SESSION_TABLE_NAME} (id, value, flash, runtime, created_at, expires_at)
+    VALUES (?, ?, ?, ?, ?, ?)
+    ON CONFLICT(id) DO UPDATE SET
+      value = excluded.value,
+      flash = excluded.flash,
+      runtime = excluded.runtime,
+      created_at = excluded.created_at,
+      expires_at = excluded.expires_at
+  `);
+  const deleteStatement = db.prepare(`DELETE FROM ${SESSION_TABLE_NAME} WHERE id = ?`);
+
+  return {
+    get(sessionId) {
+      deleteExpiredStatement.run(new Date().toISOString());
+      const row = getStatement.get(sessionId);
+      return row ? deserializeSessionRecord<TSession>(row) : undefined;
+    },
+    set(record) {
+      setStatement.run(
+        record.id,
+        JSON.stringify(record.value),
+        JSON.stringify(record.flash ?? []),
+        JSON.stringify(record.runtime ?? {}),
+        record.createdAt,
+        record.expiresAt,
+      );
+    },
+    delete(sessionId) {
+      deleteStatement.run(sessionId);
+    },
+  };
+}
+
+function ensureRuntimeColumn(db: SqliteDatabase): void {
+  const columns = db.prepare(`PRAGMA table_info(${SESSION_TABLE_NAME})`).all();
+  if (columns.some((column) => column.name === 'runtime')) {
+    return;
+  }
+
+  db.prepare(
+    `ALTER TABLE ${SESSION_TABLE_NAME} ADD COLUMN runtime TEXT NOT NULL DEFAULT '{}'`,
+  ).run();
+}
+
+function loadBunSqlite(): new (filename: string) => SqliteDatabase {
+  try {
+    const sqliteModule = require('bun:sqlite');
+    return sqliteModule.Database ?? sqliteModule.default ?? sqliteModule;
+  } catch (error) {
+    throw new Error(
+      `[session] Failed to load bun:sqlite. Run the SQLite session store with Bun or switch SESSION_STORE_DRIVER to "memory". (${(error as Error).message})`,
+    );
+  }
+}
+
+function normalizeSqlitePath(url: string): string {
+  const workspaceRoot = resolveWorkspaceRoot();
+  const target = url.startsWith('file:') ? url.slice('file:'.length) : url;
+  return path.isAbsolute(target) ? path.resolve(target) : path.resolve(workspaceRoot, target);
+}
+
+function deserializeSessionRecord<TSession extends Record<string, unknown>>(
+  row: SqliteSessionRow,
+): SessionStoreRecord<TSession> {
+  try {
+    const flash = JSON.parse(row.flash) as SessionFlashMessage[];
+    const runtime = JSON.parse(row.runtime) as SessionStoreRecord<TSession>['runtime'];
+    const legacyFlash = Array.isArray(runtime?.flash) || flash.length === 0 ? undefined : flash;
+    return {
+      id: row.id,
+      value: JSON.parse(row.value) as TSession,
+      ...(legacyFlash ? { flash: legacyFlash } : {}),
+      ...(runtime ? { runtime } : {}),
+      createdAt: row.createdAt,
+      expiresAt: row.expiresAt,
+    };
+  } catch (error) {
+    throw new Error(
+      `[session] Failed to deserialize SQLite session row '${row.id}': ${(error as Error).message}`,
+    );
+  }
+}

package/templates/backend/session/store.ts

@@ -0,0 +1,45 @@
+import {
+  createInMemorySessionStore,
+  type SessionStore,
+} from '@webstir-io/webstir-backend/runtime/session';
+import { createSqliteSessionStore } from './sqlite.js';
+
+const DEFAULT_SQLITE_SESSION_STORE_URL = 'file:./data/sessions.sqlite';
+
+export function createSessionStoreFromEnv<
+  TSession extends Record<string, unknown> = Record<string, unknown>,
+>(env: NodeJS.ProcessEnv = process.env): SessionStore<TSession> {
+  const driver = normalizeSessionStoreDriver(env);
+
+  if (driver === 'memory') {
+    return createInMemorySessionStore<TSession>();
+  }
+
+  if (driver === 'sqlite') {
+    return createSqliteSessionStore<TSession>({
+      url: normalizeSessionStoreUrl(env.SESSION_STORE_URL),
+    });
+  }
+
+  throw new Error(
+    `[session] Unsupported SESSION_STORE_DRIVER '${driver}'. Use "memory" or "sqlite".`,
+  );
+}
+
+export const sessionStore = createSessionStoreFromEnv<Record<string, unknown>>();
+
+function normalizeSessionStoreDriver(env: NodeJS.ProcessEnv): 'memory' | 'sqlite' | string {
+  const normalized = env.SESSION_STORE_DRIVER?.trim().toLowerCase();
+  if (!normalized) {
+    if (env.SESSION_STORE_URL?.trim()) {
+      return 'sqlite';
+    }
+    return env.NODE_ENV?.trim().toLowerCase() === 'production' ? 'sqlite' : 'memory';
+  }
+  return normalized;
+}
+
+function normalizeSessionStoreUrl(value: string | undefined): string {
+  const normalized = value?.trim();
+  return normalized || DEFAULT_SQLITE_SESSION_STORE_URL;
+}

package/templates/backend/tsconfig.json

@@ -11,7 +11,7 @@
     "rootDir": ".",
     "declaration": false,
     "sourceMap": true,
-    "types": ["node"],
+    "types": ["node", "bun"],
     "resolveJsonModule": true
   },
   "include": ["**/*"],

package/tests/add.test.js

@@ -0,0 +1,327 @@
+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 { backendProvider, runAddJob, runAddRoute, runUpdateRouteContract } from '../dist/index.js';
+
+async function createTempWorkspace(prefix = 'webstir-backend-add-') {
+  return await fs.mkdtemp(path.join(os.tmpdir(), prefix));
+}
+
+async function ensureDir(dir) {
+  await fs.mkdir(dir, { recursive: true });
+}
+
+async function copyAssetByTarget(workspace, targetPath) {
+  const assets = await backendProvider.getScaffoldAssets();
+  const asset = assets.find((entry) => entry.targetPath === targetPath);
+  assert.ok(asset, `expected scaffold asset ${targetPath}`);
+  const destination = path.join(workspace, targetPath);
+  await ensureDir(path.dirname(destination));
+  await fs.copyFile(asset.sourcePath, destination);
+}
+
+async function readJson(filePath) {
+  return JSON.parse(await fs.readFile(filePath, 'utf8'));
+}
+
+test('runAddRoute writes manifest metadata without scaffolding server-specific files', async () => {
+  const workspace = await createTempWorkspace();
+
+  await fs.writeFile(
+    path.join(workspace, 'package.json'),
+    JSON.stringify(
+      {
+        name: '@demo/api',
+        version: '1.0.0',
+        type: 'module',
+        webstir: { mode: 'api', moduleManifest: {} },
+      },
+      null,
+      2,
+    ),
+    'utf8',
+  );
+
+  const result = await runAddRoute({
+    workspaceRoot: workspace,
+    name: 'accounts',
+    method: 'POST',
+    path: '/api/accounts',
+    summary: 'List accounts',
+    description: 'Returns the current account list',
+    tags: ['accounts', 'api', 'accounts'],
+    interaction: 'mutation',
+    sessionMode: 'required',
+    sessionWrite: true,
+    formUrlEncoded: true,
+    formCsrf: true,
+    fragmentTarget: 'accounts-panel',
+    fragmentMode: 'replace',
+    paramsSchema: 'zod:AccountParams@src/shared/contracts/accounts.ts',
+    responseSchema: 'AccountList@src/shared/contracts/accounts.ts',
+    responseStatus: '201',
+  });
+
+  assert.equal(result.subject, 'route');
+  assert.ok(result.changes.includes('package.json'));
+  assert.deepEqual(result.changes, ['package.json']);
+
+  const pkg = await readJson(path.join(workspace, 'package.json'));
+  assert.deepEqual(pkg.webstir.moduleManifest.routes, [
+    {
+      name: 'accounts',
+      method: 'POST',
+      path: '/api/accounts',
+      summary: 'List accounts',
+      description: 'Returns the current account list',
+      tags: ['accounts', 'api'],
+      interaction: 'mutation',
+      session: {
+        mode: 'required',
+        write: true,
+      },
+      form: {
+        contentType: 'application/x-www-form-urlencoded',
+        csrf: true,
+      },
+      fragment: {
+        target: 'accounts-panel',
+        mode: 'replace',
+      },
+      input: {
+        params: {
+          kind: 'zod',
+          name: 'AccountParams',
+          source: 'src/shared/contracts/accounts.ts',
+        },
+      },
+      output: {
+        body: {
+          kind: 'zod',
+          name: 'AccountList',
+          source: 'src/shared/contracts/accounts.ts',
+        },
+        status: 201,
+      },
+    },
+  ]);
+});
+
+test('runAddRoute preserves interaction, session, form, and fragment metadata', async () => {
+  const workspace = await createTempWorkspace('webstir-backend-add-route-metadata-');
+
+  await fs.writeFile(
+    path.join(workspace, 'package.json'),
+    JSON.stringify(
+      {
+        name: '@demo/api',
+        version: '1.0.0',
+        type: 'module',
+        webstir: { mode: 'api', moduleManifest: {} },
+      },
+      null,
+      2,
+    ),
+    'utf8',
+  );
+
+  const result = await runAddRoute({
+    workspaceRoot: workspace,
+    name: 'session-sign-in',
+    method: 'POST',
+    path: '/session/sign-in',
+    interaction: 'mutation',
+    sessionMode: 'required',
+    sessionWrite: true,
+    formUrlEncoded: true,
+    formCsrf: true,
+    fragmentTarget: 'session-panel',
+    fragmentSelector: '#session-panel',
+    fragmentMode: 'replace',
+  });
+
+  assert.equal(result.subject, 'route');
+  assert.deepEqual(result.changes, ['package.json']);
+
+  const pkg = await readJson(path.join(workspace, 'package.json'));
+  assert.deepEqual(pkg.webstir.moduleManifest.routes, [
+    {
+      name: 'session-sign-in',
+      method: 'POST',
+      path: '/session/sign-in',
+      interaction: 'mutation',
+      session: {
+        mode: 'required',
+        write: true,
+      },
+      form: {
+        contentType: 'application/x-www-form-urlencoded',
+        csrf: true,
+      },
+      fragment: {
+        target: 'session-panel',
+        selector: '#session-panel',
+        mode: 'replace',
+      },
+    },
+  ]);
+});
+
+test('runAddJob writes a job scaffold and preserves description in a valid manifest', async () => {
+  const workspace = await createTempWorkspace('webstir-backend-add-job-');
+
+  await copyAssetByTarget(workspace, path.join('src', 'backend', 'index.ts'));
+  await fs.writeFile(
+    path.join(workspace, 'package.json'),
+    JSON.stringify(
+      {
+        name: '@demo/api',
+        version: '1.0.0',
+        type: 'module',
+        webstir: { mode: 'api', moduleManifest: {} },
+      },
+      null,
+      2,
+    ),
+    'utf8',
+  );
+
+  const result = await runAddJob({
+    workspaceRoot: workspace,
+    name: 'nightly',
+    schedule: 'rate(5 minutes)',
+    description: 'Nightly maintenance run',
+    priority: '5',
+  });
+
+  assert.equal(result.subject, 'job');
+  assert.ok(result.changes.includes('package.json'));
+  assert.ok(result.changes.includes('src/backend/jobs/nightly/index.ts'));
+
+  const pkg = await readJson(path.join(workspace, 'package.json'));
+  assert.deepEqual(pkg.webstir.moduleManifest.jobs, [
+    {
+      name: 'nightly',
+      schedule: 'rate(5 minutes)',
+      description: 'Nightly maintenance run',
+      priority: 5,
+    },
+  ]);
+
+  const buildResult = await backendProvider.build({
+    workspaceRoot: workspace,
+    env: {
+      WEBSTIR_MODULE_MODE: 'build',
+      WEBSTIR_BACKEND_TYPECHECK: 'skip',
+      PATH: process.env.PATH ?? '',
+    },
+    incremental: false,
+  });
+
+  assert.deepEqual(buildResult.manifest.module?.jobs, [
+    {
+      name: 'nightly',
+      schedule: 'rate(5 minutes)',
+      description: 'Nightly maintenance run',
+      priority: 5,
+    },
+  ]);
+});
+
+test('runAddJob rejects malformed rate schedules before writing files', async () => {
+  const workspace = await createTempWorkspace('webstir-backend-add-job-rate-');
+
+  await assert.rejects(
+    runAddJob({
+      workspaceRoot: workspace,
+      name: 'nightly',
+      schedule: 'rate(0 seconds)',
+    }),
+    /Expected rate\(<positive integer> second\(s\)\|minute\(s\)\|hour\(s\)\)/,
+  );
+});
+
+test('runUpdateRouteContract merges advanced metadata onto an existing route', async () => {
+  const workspace = await createTempWorkspace('webstir-backend-update-route-contract-');
+
+  await fs.writeFile(
+    path.join(workspace, 'package.json'),
+    JSON.stringify(
+      {
+        name: '@demo/api',
+        version: '1.0.0',
+        type: 'module',
+        webstir: {
+          mode: 'api',
+          moduleManifest: {
+            routes: [
+              {
+                name: 'session-sign-in',
+                method: 'POST',
+                path: '/session/sign-in',
+                summary: 'Sign in',
+                interaction: 'mutation',
+              },
+            ],
+          },
+        },
+      },
+      null,
+      2,
+    ),
+    'utf8',
+  );
+
+  const result = await runUpdateRouteContract({
+    workspaceRoot: workspace,
+    method: 'POST',
+    path: '/session/sign-in',
+    sessionMode: 'required',
+    sessionWrite: true,
+    formUrlEncoded: true,
+    formCsrf: true,
+    fragmentTarget: 'session-panel',
+    fragmentSelector: '#session-panel',
+    fragmentMode: 'replace',
+    responseSchema: 'SessionSignInResponse@src/shared/contracts/session.ts',
+    responseStatus: 200,
+  });
+
+  assert.equal(result.subject, 'route');
+  assert.deepEqual(result.changes, ['package.json']);
+
+  const pkg = await readJson(path.join(workspace, 'package.json'));
+  assert.deepEqual(pkg.webstir.moduleManifest.routes, [
+    {
+      name: 'session-sign-in',
+      method: 'POST',
+      path: '/session/sign-in',
+      summary: 'Sign in',
+      interaction: 'mutation',
+      session: {
+        mode: 'required',
+        write: true,
+      },
+      form: {
+        contentType: 'application/x-www-form-urlencoded',
+        csrf: true,
+      },
+      fragment: {
+        target: 'session-panel',
+        selector: '#session-panel',
+        mode: 'replace',
+      },
+      output: {
+        body: {
+          kind: 'zod',
+          name: 'SessionSignInResponse',
+          source: 'src/shared/contracts/session.ts',
+        },
+        status: 200,
+      },
+    },
+  ]);
+});