@webstir-io/webstir 0.1.3 → 0.1.4

package/assets/features/search/search.ts

@@ -313,15 +313,6 @@ function ensureBackdrop(root: HTMLElement): void {
         return;
     }
 
-    const legacy = root.querySelector<HTMLElement>('.webstir-search__backdrop');
-    if (legacy) {
-        legacy.classList.add('ws-drawer-backdrop');
-        legacy.classList.remove('webstir-search__backdrop');
-        legacy.setAttribute('data-webstir-search-close', '');
-        legacy.setAttribute('aria-hidden', 'true');
-        return;
-    }
-
     const created = document.createElement('div');
     created.className = 'ws-drawer-backdrop';
     created.setAttribute('data-webstir-search-close', '');

package/assets/templates/api/src/backend/index.ts

@@ -1,4 +1,6 @@
 import crypto from 'node:crypto';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import {
   createDefaultBunBackendBootstrap,
@@ -54,19 +56,8 @@ export async function start(): Promise<void> {
   );
 }
 
-const isMain = (() => {
-  try {
-    const argv1 = process.argv?.[1];
-    if (!argv1) return false;
-    const here = new URL(import.meta.url);
-    const run = new URL(`file://${argv1}`);
-    return here.pathname === run.pathname;
-  } catch {
-    return false;
-  }
-})();
-
-if (isMain) {
+const entrypointPath = process.argv[1];
+if (entrypointPath && path.resolve(entrypointPath) === fileURLToPath(import.meta.url)) {
   start().catch((err) => {
     console.error(err);
     process.exitCode = 1;

package/assets/templates/full/src/backend/index.ts

@@ -1,4 +1,6 @@
 import crypto from 'node:crypto';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import {
   createDefaultBunBackendBootstrap,
@@ -54,19 +56,8 @@ export async function start(): Promise<void> {
   );
 }
 
-const isMain = (() => {
-  try {
-    const argv1 = process.argv?.[1];
-    if (!argv1) return false;
-    const here = new URL(import.meta.url);
-    const run = new URL(`file://${argv1}`);
-    return here.pathname === run.pathname;
-  } catch {
-    return false;
-  }
-})();
-
-if (isMain) {
+const entrypointPath = process.argv[1];
+if (entrypointPath && path.resolve(entrypointPath) === fileURLToPath(import.meta.url)) {
   start().catch((err) => {
     console.error(err);
     process.exitCode = 1;

package/assets/templates/full/src/backend/module.ts

@@ -4,8 +4,8 @@ import { fileURLToPath } from 'node:url';
 
 import type { RouteHandlerResult } from '@webstir-io/webstir-backend/runtime/bun';
 
-const ROOT_PATH = '/';
-const DEMO_PATH = '/demo/progressive-enhancement';
+const ROOT_PATH = '/api';
+const DEMO_PATH = '/api/demo/progressive-enhancement';
 const FRAGMENT_TARGET = 'greeting-preview';
 const SESSION_PANEL_TARGET = 'session-panel';
 const SESSION_COOKIE_NAME = 'webstir_demo_session';

package/assets/templates/full/src/backend/tests/progressive-enhancement.test.ts

@@ -2,7 +2,7 @@ import { assert, test } from '@webstir-io/webstir-testing';
 
 test('progressive enhancement demo page renders a form shell', async () => {
   const ctx = requireBackendTestContext();
-  const response = await ctx.request('/demo/progressive-enhancement');
+  const response = await ctx.request('/api/demo/progressive-enhancement');
   const html = await response.text();
 
   assert.equal(response.status, 200);
@@ -23,7 +23,7 @@ test('progressive enhancement demo page renders a form shell', async () => {
 
 test('native form submissions redirect back to the document route', async () => {
   const ctx = requireBackendTestContext();
-  const response = await ctx.request('/demo/progressive-enhancement', {
+  const response = await ctx.request('/api/demo/progressive-enhancement', {
     method: 'POST',
     headers: {
       'content-type': 'application/x-www-form-urlencoded'
@@ -35,7 +35,7 @@ test('native form submissions redirect back to the document route', async () =>
   assert.equal(response.status, 303);
   assert.equal(
     response.headers.get('location'),
-    '/demo/progressive-enhancement?source=redirect&name=Native%20Flow'
+    '/api/demo/progressive-enhancement?source=redirect&name=Native%20Flow'
   );
   assert.equal(response.headers.get('x-webstir-fragment-target'), null);
   assert.equal(response.headers.get('content-type'), null);
@@ -43,7 +43,7 @@ test('native form submissions redirect back to the document route', async () =>
 
 test('redirected document route preserves the no-javascript form flow', async () => {
   const ctx = requireBackendTestContext();
-  const response = await ctx.request('/demo/progressive-enhancement?source=redirect&name=Native%20Flow');
+  const response = await ctx.request('/api/demo/progressive-enhancement?source=redirect&name=Native%20Flow');
   const html = await response.text();
 
   assert.equal(response.status, 200);
@@ -55,7 +55,7 @@ test('redirected document route preserves the no-javascript form flow', async ()
 
 test('enhanced form submissions return fragment metadata and html', async () => {
   const ctx = requireBackendTestContext();
-  const response = await ctx.request('/demo/progressive-enhancement', {
+  const response = await ctx.request('/api/demo/progressive-enhancement', {
     method: 'POST',
     headers: {
       'content-type': 'application/x-www-form-urlencoded',
@@ -80,7 +80,7 @@ test('enhanced form submissions return fragment metadata and html', async () =>
 
 test('native session sign-in redirects and sets a session cookie', async () => {
   const ctx = requireBackendTestContext();
-  const response = await ctx.request('/demo/progressive-enhancement/session/sign-in', {
+  const response = await ctx.request('/api/demo/progressive-enhancement/session/sign-in', {
     method: 'POST',
     headers: {
       'content-type': 'application/x-www-form-urlencoded'
@@ -90,13 +90,13 @@ test('native session sign-in redirects and sets a session cookie', async () => {
   });
 
   assert.equal(response.status, 303);
-  assert.equal(response.headers.get('location'), '/demo/progressive-enhancement?session=signed-in');
+  assert.equal(response.headers.get('location'), '/api/demo/progressive-enhancement?session=signed-in');
   assert.isTrue(String(response.headers.get('set-cookie')).includes('webstir_demo_session=Casey%20Proxy'));
 });
 
 test('enhanced session sign-in returns a fragment and persists on the next document request', async () => {
   const ctx = requireBackendTestContext();
-  const response = await ctx.request('/demo/progressive-enhancement/session/sign-in', {
+  const response = await ctx.request('/api/demo/progressive-enhancement/session/sign-in', {
     method: 'POST',
     headers: {
       'content-type': 'application/x-www-form-urlencoded',
@@ -115,7 +115,7 @@ test('enhanced session sign-in returns a fragment and persists on the next docum
   assert.isTrue(html.includes('Signed in as <strong>Casey Proxy</strong>'));
   assert.isTrue(html.includes('id="demo-sign-out"'));
 
-  const documentResponse = await ctx.request('/demo/progressive-enhancement', {
+  const documentResponse = await ctx.request('/api/demo/progressive-enhancement', {
     headers: {
       cookie
     }
@@ -129,7 +129,7 @@ test('enhanced session sign-in returns a fragment and persists on the next docum
 
 test('enhanced session sign-out returns a fragment and clears the session cookie', async () => {
   const ctx = requireBackendTestContext();
-  const signInResponse = await ctx.request('/demo/progressive-enhancement/session/sign-in', {
+  const signInResponse = await ctx.request('/api/demo/progressive-enhancement/session/sign-in', {
     method: 'POST',
     headers: {
       'content-type': 'application/x-www-form-urlencoded',
@@ -139,7 +139,7 @@ test('enhanced session sign-out returns a fragment and clears the session cookie
   });
   const cookie = requireCookie(signInResponse.headers.get('set-cookie'));
 
-  const response = await ctx.request('/demo/progressive-enhancement/session/sign-out', {
+  const response = await ctx.request('/api/demo/progressive-enhancement/session/sign-out', {
     method: 'POST',
     headers: {
       'x-webstir-client-nav': '1',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webstir-io/webstir",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
   "bin": {
     "webstir": "src/cli.ts"
@@ -46,8 +46,8 @@
     "@modelcontextprotocol/sdk": "1.28.0",
     "@webstir-io/module-contract": "^0.1.16",
     "@webstir-io/testing-contract": "^0.1.8",
-    "@webstir-io/webstir-backend": "^0.1.16",
-    "@webstir-io/webstir-frontend": "^0.1.41",
+    "@webstir-io/webstir-backend": "^0.1.17",
+    "@webstir-io/webstir-frontend": "^0.1.42",
     "@webstir-io/webstir-testing": "^0.1.6",
     "typescript": "^5.7.2",
     "zod": "^3.23.8"

package/src/add-backend.ts

@@ -1,13 +1,14 @@
-import type {
-  AddJobOptions,
-  AddRouteOptions,
-  UpdateRouteContractOptions as BackendUpdateRouteContractOptions,
+import {
+  runAddJob as runBackendAddJob,
+  runAddRoute as runBackendAddRoute,
+  runUpdateRouteContract as runBackendUpdateRouteContract,
+  type AddJobOptions,
+  type AddRouteOptions,
+  type UpdateRouteContractOptions as BackendUpdateRouteContractOptions,
 } from '@webstir-io/webstir-backend';
 
 import type { AddCommandResult } from './add.ts';
 
-import { monorepoRoot } from './paths.ts';
-
 export interface RunAddBackendOptions {
   readonly workspaceRoot: string;
   readonly rawArgs: readonly string[];
@@ -27,8 +28,7 @@ export async function runAddRouteCommand(options: RunAddBackendOptions): Promise
 export async function runAddRouteScaffold(
   options: AddRouteScaffoldOptions,
 ): Promise<AddCommandResult> {
-  const backendAdd = await loadBackendAddModule();
-  const result = await backendAdd.runAddRoute(options);
+  const result = await runBackendAddRoute(options);
 
   return {
     workspaceRoot: options.workspaceRoot,
@@ -46,8 +46,7 @@ export async function runAddJobCommand(options: RunAddBackendOptions): Promise<A
 }
 
 export async function runAddJobScaffold(options: AddJobScaffoldOptions): Promise<AddCommandResult> {
-  const backendAdd = await loadBackendAddModule();
-  const result = await backendAdd.runAddJob(options);
+  const result = await runBackendAddJob(options);
 
   return {
     workspaceRoot: options.workspaceRoot,
@@ -60,8 +59,7 @@ export async function runAddJobScaffold(options: AddJobScaffoldOptions): Promise
 export async function runUpdateRouteContract(
   options: UpdateRouteContractOptions,
 ): Promise<AddCommandResult> {
-  const backendAdd = await loadBackendAddModule();
-  const result = await backendAdd.runUpdateRouteContract(options);
+  const result = await runBackendUpdateRouteContract(options);
 
   return {
     workspaceRoot: options.workspaceRoot,
@@ -167,66 +165,6 @@ interface ParsedBackendCommandArgs {
   readonly booleans: ReadonlySet<string>;
 }
 
-interface BackendAddResult {
-  readonly target: string;
-  readonly changes: readonly string[];
-}
-
-interface BackendAddModule {
-  readonly runAddRoute: (options: AddRouteOptions) => Promise<BackendAddResult>;
-  readonly runAddJob: (options: AddJobOptions) => Promise<BackendAddResult>;
-  readonly runUpdateRouteContract: (
-    options: UpdateRouteContractOptions,
-  ) => Promise<BackendAddResult>;
-}
-
-let backendAddModulePromise: Promise<BackendAddModule> | null = null;
-
-async function loadBackendAddModule(): Promise<BackendAddModule> {
-  if (backendAddModulePromise) {
-    return await backendAddModulePromise;
-  }
-
-  backendAddModulePromise = import('@webstir-io/webstir-backend').then(async (module) => {
-    if (
-      typeof module.runAddRoute === 'function' &&
-      typeof module.runAddJob === 'function' &&
-      typeof module.runUpdateRouteContract === 'function'
-    ) {
-      return module as BackendAddModule;
-    }
-
-    if (monorepoRoot) {
-      throw new Error(
-        'Installed @webstir-io/webstir-backend package does not export runAddRoute/runAddJob/runUpdateRouteContract.',
-      );
-    }
-
-    const compat = await import('./add-backend-compat.ts');
-    return {
-      async runAddRoute(options: AddRouteOptions): Promise<BackendAddResult> {
-        return await compat.runAddRoute(options);
-      },
-      async runAddJob(options: AddJobOptions): Promise<BackendAddResult> {
-        return await compat.runAddJob({
-          workspaceRoot: options.workspaceRoot,
-          name: options.name,
-          schedule: options.schedule,
-          description: options.description,
-          ...(options.priority !== undefined ? { priority: String(options.priority) } : {}),
-        });
-      },
-      async runUpdateRouteContract(): Promise<BackendAddResult> {
-        throw new Error(
-          'Installed @webstir-io/webstir-backend package does not export runUpdateRouteContract.',
-        );
-      },
-    };
-  });
-
-  return await backendAddModulePromise;
-}
-
 function parseBackendCommandArgs(
   rawArgs: readonly string[],
   spec: ParseSpec,

package/src/bun-spa-routes.ts

@@ -57,15 +57,10 @@ export function createBunFrontendFetchHandler(options: BunFrontendFetchHandlerOp
 }
 
 function getApiProxyPath(pathname: string): string | null {
-  if (pathname === '/api') {
-    return '/';
+  const normalizedPath = pathname.startsWith('/') ? path.posix.normalize(pathname) : null;
+  if (normalizedPath === '/api' || normalizedPath?.startsWith('/api/')) {
+    return normalizedPath;
   }
-
-  if (pathname.startsWith('/api/')) {
-    const normalizedPath = path.posix.normalize(pathname.slice('/api'.length));
-    return normalizedPath.startsWith('/') ? normalizedPath : `/${normalizedPath}`;
-  }
-
   return null;
 }
 
@@ -132,7 +127,7 @@ function rewriteProxyLocation(value: string, targetUrl: URL): string {
   }
 
   if (trimmed.startsWith('/')) {
-    return prefixApiMount(trimmed);
+    return trimmed;
   }
 
   try {
@@ -140,20 +135,12 @@ function rewriteProxyLocation(value: string, targetUrl: URL): string {
     if (resolved.origin !== targetUrl.origin) {
       return value;
     }
-    return prefixApiMount(`${resolved.pathname}${resolved.search}${resolved.hash}`);
+    return `${resolved.pathname}${resolved.search}${resolved.hash}`;
   } catch {
     return value;
   }
 }
 
-function prefixApiMount(pathname: string): string {
-  if (pathname === '/api' || pathname.startsWith('/api/')) {
-    return pathname;
-  }
-
-  return pathname === '/' ? '/api' : `/api${pathname}`;
-}
-
 function methodAllowsBody(method: string): boolean {
   return method !== 'GET' && method !== 'HEAD';
 }

package/src/dev-server.ts

@@ -303,15 +303,10 @@ export function getStaticCandidatePaths(pathname: string): readonly string[] {
 }
 
 export function getApiProxyPath(pathname: string): string | null {
-  if (pathname === '/api') {
-    return '/';
+  const normalizedPath = pathname.startsWith('/') ? path.posix.normalize(pathname) : null;
+  if (normalizedPath === '/api' || normalizedPath?.startsWith('/api/')) {
+    return normalizedPath;
   }
-
-  if (pathname.startsWith('/api/')) {
-    const normalizedPath = path.posix.normalize(pathname.slice('/api'.length));
-    return normalizedPath.startsWith('/') ? normalizedPath : `/${normalizedPath}`;
-  }
-
   return null;
 }
 
@@ -357,7 +352,7 @@ function rewriteProxyLocation(value: string, targetUrl: URL): string {
   }
 
   if (trimmed.startsWith('/')) {
-    return prefixApiMount(trimmed);
+    return trimmed;
   }
 
   try {
@@ -365,20 +360,12 @@ function rewriteProxyLocation(value: string, targetUrl: URL): string {
     if (resolved.origin !== targetUrl.origin) {
       return value;
     }
-    return prefixApiMount(`${resolved.pathname}${resolved.search}${resolved.hash}`);
+    return `${resolved.pathname}${resolved.search}${resolved.hash}`;
   } catch {
     return value;
   }
 }
 
-function prefixApiMount(pathname: string): string {
-  if (pathname === '/api' || pathname.startsWith('/api/')) {
-    return pathname;
-  }
-
-  return pathname === '/' ? '/api' : `/api${pathname}`;
-}
-
 async function resolveStaticFile(
   buildRoot: string,
   relativePaths: readonly string[],

package/src/add-backend-compat.ts

@@ -1,628 +0,0 @@
-import path from 'node:path';
-import { existsSync } from 'node:fs';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-
-import type {
-  FragmentUpdateMode,
-  HttpMethod,
-  JobDefinition,
-  RouteDefinition,
-  SchemaReference,
-  SessionAccessMode,
-} from '@webstir-io/module-contract';
-
-const ALLOWED_METHODS = ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'] as const;
-const ALLOWED_SCHEMA_KINDS = ['zod', 'json-schema', 'ts-rest'] as const;
-const ALLOWED_INTERACTIONS = ['navigation', 'mutation'] as const;
-const ALLOWED_SESSION_MODES = ['optional', 'required'] as const;
-const ALLOWED_FRAGMENT_MODES = ['replace', 'append', 'prepend'] as const;
-const ALLOWED_SCHEDULE_MACROS = [
-  'yearly',
-  'annually',
-  'monthly',
-  'weekly',
-  'daily',
-  'midnight',
-  'hourly',
-  'reboot',
-] as const;
-const RATE_SCHEDULE_PATTERN = /^rate\((\d+)\s+(second|seconds|minute|minutes|hour|hours)\)$/i;
-
-interface WorkspacePackageJson {
-  readonly webstir?: {
-    readonly moduleManifest?: {
-      readonly routes?: RouteDefinition[];
-      readonly jobs?: JobDefinition[];
-      readonly [key: string]: unknown;
-    };
-    readonly [key: string]: unknown;
-  };
-  readonly [key: string]: unknown;
-}
-
-type MutableWorkspacePackageJson = WorkspacePackageJson & {
-  webstir?: Record<string, unknown>;
-  [key: string]: unknown;
-};
-
-export interface AddRouteOptions {
-  readonly workspaceRoot: string;
-  readonly name: string;
-  readonly method?: string;
-  readonly path?: string;
-  readonly summary?: string;
-  readonly description?: string;
-  readonly tags?: readonly string[];
-  readonly interaction?: string;
-  readonly sessionMode?: string;
-  readonly sessionWrite?: boolean;
-  readonly formUrlEncoded?: boolean;
-  readonly formCsrf?: boolean;
-  readonly fragmentTarget?: string;
-  readonly fragmentSelector?: string;
-  readonly fragmentMode?: string;
-  readonly paramsSchema?: string;
-  readonly querySchema?: string;
-  readonly bodySchema?: string;
-  readonly headersSchema?: string;
-  readonly responseSchema?: string;
-  readonly responseStatus?: string | number;
-  readonly responseHeadersSchema?: string;
-}
-
-export interface AddJobOptions {
-  readonly workspaceRoot: string;
-  readonly name: string;
-  readonly schedule?: string;
-  readonly description?: string;
-  readonly priority?: string;
-}
-
-export interface BackendAddResult {
-  readonly subject: 'route' | 'job';
-  readonly target: string;
-  readonly changes: readonly string[];
-}
-
-export async function runAddRoute(options: AddRouteOptions): Promise<BackendAddResult> {
-  const name = normalizeRequiredName(options.name, 'route');
-  const method = normalizeMethod(options.method);
-  const routePath = normalizeRoutePath(options.path, name);
-  const summary = normalizeOptionalString(options.summary);
-  const description = normalizeOptionalString(options.description);
-  const tags = normalizeTags(options.tags);
-  const interaction = normalizeInteraction(options.interaction);
-  const session = buildRouteSession(options.sessionMode, options.sessionWrite);
-  const form = buildRouteForm(options.formUrlEncoded, options.formCsrf);
-  const fragment = buildRouteFragment(
-    options.fragmentTarget,
-    options.fragmentSelector,
-    options.fragmentMode,
-  );
-  const paramsSchema = parseSchemaReference(options.paramsSchema, '--params-schema');
-  const querySchema = parseSchemaReference(options.querySchema, '--query-schema');
-  const bodySchema = parseSchemaReference(options.bodySchema, '--body-schema');
-  const headersSchema = parseSchemaReference(options.headersSchema, '--headers-schema');
-  const responseSchema = parseSchemaReference(options.responseSchema, '--response-schema');
-  const responseHeadersSchema = parseSchemaReference(
-    options.responseHeadersSchema,
-    '--response-headers-schema',
-  );
-  const responseStatus = parseResponseStatus(options.responseStatus);
-
-  if ((responseHeadersSchema || responseStatus !== undefined) && !responseSchema) {
-    throw new Error('--response-schema is required when setting response headers or status.');
-  }
-
-  const packageJsonPath = path.join(options.workspaceRoot, 'package.json');
-  const trackedPaths = [packageJsonPath];
-  const before = await captureFileState(trackedPaths);
-
-  const pkg = await readWorkspacePackageJson(packageJsonPath);
-  const webstir = asObject(pkg.webstir);
-  const moduleManifest = asObject(webstir.moduleManifest);
-  const routes = Array.isArray(moduleManifest.routes) ? [...moduleManifest.routes] : [];
-  const routeIndex = routes.findIndex(
-    (entry) => entry?.method === method && entry?.path === routePath,
-  );
-
-  const nextRoute: RouteDefinition = {
-    name,
-    method,
-    path: routePath,
-    ...(summary ? { summary } : {}),
-    ...(description ? { description } : {}),
-    ...(tags.length > 0 ? { tags } : {}),
-    ...(interaction ? { interaction } : {}),
-    ...(session ? { session } : {}),
-    ...(form ? { form } : {}),
-    ...(fragment ? { fragment } : {}),
-    ...buildRouteInput(paramsSchema, querySchema, bodySchema, headersSchema),
-    ...buildRouteOutput(responseSchema, responseHeadersSchema, responseStatus),
-  };
-
-  if (routeIndex >= 0) {
-    routes[routeIndex] = nextRoute;
-  } else {
-    routes.push(nextRoute);
-  }
-
-  moduleManifest.routes = routes;
-  webstir.moduleManifest = moduleManifest;
-  pkg.webstir = webstir;
-  await writeWorkspacePackageJson(packageJsonPath, pkg);
-
-  return {
-    subject: 'route',
-    target: `${method} ${routePath}`,
-    changes: await collectChangedFiles(options.workspaceRoot, trackedPaths, before),
-  };
-}
-
-export async function runAddJob(options: AddJobOptions): Promise<BackendAddResult> {
-  const name = normalizeRequiredName(options.name, 'job');
-  const schedule = normalizeOptionalString(options.schedule);
-  const description = normalizeOptionalString(options.description);
-  const priority = normalizeOptionalString(options.priority);
-
-  if (schedule) {
-    validateSchedule(schedule);
-  }
-
-  const packageJsonPath = path.join(options.workspaceRoot, 'package.json');
-  const jobDirectory = path.join(options.workspaceRoot, 'src', 'backend', 'jobs', name);
-  const jobFilePath = path.join(jobDirectory, 'index.ts');
-  const trackedPaths = [packageJsonPath, jobFilePath];
-  const before = await captureFileState(trackedPaths);
-
-  if (existsSync(jobDirectory)) {
-    throw new Error(`Job '${name}' already exists.`);
-  }
-
-  await mkdir(jobDirectory, { recursive: true });
-  await writeTextFile(jobFilePath, buildJobTemplate(name));
-
-  const pkg = await readWorkspacePackageJson(packageJsonPath);
-  const webstir = asObject(pkg.webstir);
-  const moduleManifest = asObject(webstir.moduleManifest);
-  const jobs = Array.isArray(moduleManifest.jobs) ? [...moduleManifest.jobs] : [];
-  const jobIndex = jobs.findIndex((entry) => entry?.name === name);
-
-  const nextJob: JobDefinition & { description?: string } = {
-    name,
-    ...(schedule ? { schedule } : {}),
-    ...(description ? { description } : {}),
-    ...parsePriority(priority),
-  };
-
-  if (jobIndex >= 0) {
-    jobs[jobIndex] = nextJob;
-  } else {
-    jobs.push(nextJob);
-  }
-
-  moduleManifest.jobs = jobs;
-  webstir.moduleManifest = moduleManifest;
-  pkg.webstir = webstir;
-  await writeWorkspacePackageJson(packageJsonPath, pkg);
-
-  return {
-    subject: 'job',
-    target: name,
-    changes: await collectChangedFiles(options.workspaceRoot, trackedPaths, before),
-  };
-}
-
-function buildRouteInput(
-  paramsSchema?: SchemaReference,
-  querySchema?: SchemaReference,
-  bodySchema?: SchemaReference,
-  headersSchema?: SchemaReference,
-): { input?: RouteDefinition['input'] } {
-  const input = {
-    ...(paramsSchema ? { params: paramsSchema } : {}),
-    ...(querySchema ? { query: querySchema } : {}),
-    ...(bodySchema ? { body: bodySchema } : {}),
-    ...(headersSchema ? { headers: headersSchema } : {}),
-  };
-
-  return Object.keys(input).length > 0 ? { input } : {};
-}
-
-function buildRouteOutput(
-  responseSchema?: SchemaReference,
-  responseHeadersSchema?: SchemaReference,
-  responseStatus?: number,
-): { output?: RouteDefinition['output'] } {
-  if (!responseSchema) {
-    return {};
-  }
-
-  return {
-    output: {
-      body: responseSchema,
-      ...(responseStatus !== undefined ? { status: responseStatus } : {}),
-      ...(responseHeadersSchema ? { headers: responseHeadersSchema } : {}),
-    },
-  };
-}
-
-function normalizeInteraction(value?: string): RouteDefinition['interaction'] | undefined {
-  const normalized = normalizeOptionalString(value);
-  if (!normalized) {
-    return undefined;
-  }
-
-  if (normalized === 'navigation' || normalized === 'mutation') {
-    return normalized;
-  }
-
-  throw new Error(
-    `Invalid --interaction value '${normalized}'. Allowed values: ${ALLOWED_INTERACTIONS.join(', ')}.`,
-  );
-}
-
-function buildRouteSession(mode?: string, write?: boolean): RouteDefinition['session'] | undefined {
-  const normalizedMode = normalizeSessionMode(mode);
-  if (!normalizedMode && !write) {
-    return undefined;
-  }
-
-  return {
-    ...(normalizedMode ? { mode: normalizedMode } : {}),
-    ...(write ? { write: true } : {}),
-  };
-}
-
-function normalizeSessionMode(value?: string): SessionAccessMode | undefined {
-  const normalized = normalizeOptionalString(value);
-  if (!normalized) {
-    return undefined;
-  }
-
-  if (normalized === 'optional' || normalized === 'required') {
-    return normalized;
-  }
-
-  throw new Error(
-    `Invalid --session value '${normalized}'. Allowed values: ${ALLOWED_SESSION_MODES.join(', ')}.`,
-  );
-}
-
-function buildRouteForm(urlEncoded?: boolean, csrf?: boolean): RouteDefinition['form'] | undefined {
-  if (!urlEncoded && !csrf) {
-    return undefined;
-  }
-
-  return {
-    ...(urlEncoded ? { contentType: 'application/x-www-form-urlencoded' } : {}),
-    ...(csrf ? { csrf: true } : {}),
-  };
-}
-
-function buildRouteFragment(
-  target?: string,
-  selector?: string,
-  mode?: string,
-): RouteDefinition['fragment'] | undefined {
-  const normalizedTarget = normalizeOptionalString(target);
-  const normalizedSelector = normalizeOptionalString(selector);
-  const normalizedMode = normalizeFragmentMode(mode);
-
-  if (!normalizedTarget && !normalizedSelector && !normalizedMode) {
-    return undefined;
-  }
-
-  if (!normalizedTarget) {
-    throw new Error('--fragment-target is required when setting fragment metadata.');
-  }
-
-  return {
-    target: normalizedTarget,
-    ...(normalizedSelector ? { selector: normalizedSelector } : {}),
-    ...(normalizedMode ? { mode: normalizedMode } : {}),
-  };
-}
-
-function normalizeFragmentMode(value?: string): FragmentUpdateMode | undefined {
-  const normalized = normalizeOptionalString(value);
-  if (!normalized) {
-    return undefined;
-  }
-
-  if (normalized === 'replace' || normalized === 'append' || normalized === 'prepend') {
-    return normalized;
-  }
-
-  throw new Error(
-    `Invalid --fragment-mode value '${normalized}'. Allowed values: ${ALLOWED_FRAGMENT_MODES.join(', ')}.`,
-  );
-}
-
-function buildJobTemplate(name: string): string {
-  return `// Generated by webstir add-job
-export async function run(): Promise<void> {
-  console.info('[job:${name}] ran at', new Date().toISOString());
-}
-
-// Execute when launched directly: \`bun build/backend/jobs/${name}/index.js\`
-const isMain = (() => {
-  try {
-    const argv1 = process.argv?.[1];
-    if (!argv1) return false;
-    const here = new URL(import.meta.url);
-    const run = new URL(\`file://\${argv1}\`);
-    return here.pathname === run.pathname;
-  } catch {
-    return false;
-  }
-})();
-
-if (isMain) {
-  run().catch((err) => {
-    console.error(err);
-    process.exitCode = 1;
-  });
-}
-`;
-}
-
-function normalizeRequiredName(name: string, subject: 'route' | 'job'): string {
-  const normalized = name.trim();
-  if (!normalized) {
-    throw new Error(`Missing ${subject} name.`);
-  }
-  return normalized;
-}
-
-function normalizeMethod(value?: string): HttpMethod {
-  const candidate = (value ?? 'GET').trim().toUpperCase();
-  if (!ALLOWED_METHODS.includes(candidate as HttpMethod)) {
-    throw new Error(
-      `Invalid --method value '${candidate}'. Allowed values: ${ALLOWED_METHODS.join(', ')}.`,
-    );
-  }
-  return candidate as HttpMethod;
-}
-
-function normalizeRoutePath(value: string | undefined, name: string): string {
-  const routePath = value?.trim() || `/api/${name}`;
-  return routePath.startsWith('/') ? routePath : `/${routePath}`;
-}
-
-function normalizeOptionalString(value?: string): string | undefined {
-  const normalized = value?.trim();
-  return normalized ? normalized : undefined;
-}
-
-function normalizeTags(tags: readonly string[] | undefined): string[] {
-  if (!tags || tags.length === 0) {
-    return [];
-  }
-
-  const seen = new Set<string>();
-  const normalized: string[] = [];
-  for (const tag of tags) {
-    const candidate = tag.trim();
-    if (!candidate) {
-      continue;
-    }
-
-    const key = candidate.toLowerCase();
-    if (seen.has(key)) {
-      continue;
-    }
-
-    seen.add(key);
-    normalized.push(candidate);
-  }
-
-  return normalized;
-}
-
-function parseSchemaReference(
-  value: string | undefined,
-  flag: string,
-): SchemaReference | undefined {
-  if (!value) {
-    return undefined;
-  }
-
-  const trimmed = value.trim();
-  let kind = 'zod';
-  let remainder = trimmed;
-  const colonIndex = trimmed.indexOf(':');
-  if (colonIndex >= 0) {
-    if (colonIndex === 0) {
-      throw new Error(`Invalid ${flag} value '${value}'. Missing schema name.`);
-    }
-    kind = trimmed.slice(0, colonIndex).trim().toLowerCase();
-    remainder = trimmed.slice(colonIndex + 1);
-  }
-
-  let source: string | undefined;
-  const atIndex = remainder.indexOf('@');
-  if (atIndex >= 0) {
-    source = remainder.slice(atIndex + 1).trim();
-    remainder = remainder.slice(0, atIndex);
-  }
-
-  const name = remainder.trim();
-  if (!name) {
-    throw new Error(`Invalid ${flag} value '${value}'. Schema name is required.`);
-  }
-
-  if (!ALLOWED_SCHEMA_KINDS.includes(kind as (typeof ALLOWED_SCHEMA_KINDS)[number])) {
-    throw new Error(
-      `Invalid schema kind '${kind}' in ${flag}. Allowed kinds: ${ALLOWED_SCHEMA_KINDS.join(', ')}.`,
-    );
-  }
-
-  return {
-    kind: kind as SchemaReference['kind'],
-    name,
-    ...(source ? { source } : {}),
-  };
-}
-
-function parseResponseStatus(value: string | number | undefined): number | undefined {
-  if (value === undefined) {
-    return undefined;
-  }
-
-  const raw = typeof value === 'number' ? String(value) : value.trim();
-  if (!raw) {
-    return undefined;
-  }
-
-  const status = Number.parseInt(raw, 10);
-  if (!Number.isInteger(status) || status < 100 || status > 599) {
-    throw new Error(
-      `Invalid --response-status value '${raw}'. Status must be between 100 and 599.`,
-    );
-  }
-
-  return status;
-}
-
-function parsePriority(priority: string | undefined): { priority?: number | string } {
-  if (!priority) {
-    return {};
-  }
-
-  const numeric = Number.parseInt(priority, 10);
-  if (Number.isInteger(numeric) && String(numeric) === priority) {
-    return { priority: numeric };
-  }
-
-  return { priority };
-}
-
-function validateSchedule(schedule: string): void {
-  const trimmed = schedule.trim();
-  if (!trimmed) {
-    throw new Error('--schedule value cannot be empty or whitespace.');
-  }
-
-  if (trimmed.startsWith('@')) {
-    const macro = trimmed.slice(1);
-    if (
-      !ALLOWED_SCHEDULE_MACROS.includes(
-        macro.toLowerCase() as (typeof ALLOWED_SCHEDULE_MACROS)[number],
-      )
-    ) {
-      throw new Error(
-        `Invalid --schedule value '${schedule}'. Allowed macros: ${ALLOWED_SCHEDULE_MACROS.map((value) => `@${value}`).join(', ')}.`,
-      );
-    }
-    return;
-  }
-
-  if (trimmed.toLowerCase().startsWith('rate(')) {
-    validateRateSchedule(schedule, trimmed);
-    return;
-  }
-
-  const parts = trimmed.split(/\s+/);
-  if (parts.length < 5 || parts.length > 7) {
-    throw new Error(
-      `Invalid --schedule value '${schedule}'. Expected 5-7 space-separated cron fields, @macro, or rate(...).`,
-    );
-  }
-
-  for (const part of parts) {
-    if (!isValidCronField(part)) {
-      throw new Error(`Invalid cron field '${part}' in --schedule value '${schedule}'.`);
-    }
-  }
-}
-
-function validateRateSchedule(schedule: string, trimmed: string): void {
-  const match = RATE_SCHEDULE_PATTERN.exec(trimmed);
-  const value = match ? Number.parseInt(match[1], 10) : 0;
-  if (!match || value <= 0) {
-    throw new Error(
-      `Invalid --schedule value '${schedule}'. Expected rate(<positive integer> second(s)|minute(s)|hour(s)).`,
-    );
-  }
-}
-
-function isValidCronField(field: string): boolean {
-  for (const character of field) {
-    if (/[A-Za-z0-9]/.test(character)) {
-      continue;
-    }
-
-    if ('*/, -?#LWC'.includes(character)) {
-      continue;
-    }
-
-    return false;
-  }
-
-  return true;
-}
-
-async function readWorkspacePackageJson(
-  packageJsonPath: string,
-): Promise<MutableWorkspacePackageJson> {
-  if (!existsSync(packageJsonPath)) {
-    throw new Error('package.json not found in workspace root.');
-  }
-
-  return JSON.parse(await readTextFile(packageJsonPath)) as MutableWorkspacePackageJson;
-}
-
-async function writeWorkspacePackageJson(
-  packageJsonPath: string,
-  pkg: Record<string, unknown>,
-): Promise<void> {
-  await writeTextFile(packageJsonPath, `${JSON.stringify(pkg, null, 2)}\n`);
-}
-
-function asObject(value: unknown): Record<string, unknown> {
-  return typeof value === 'object' && value !== null
-    ? { ...(value as Record<string, unknown>) }
-    : {};
-}
-
-async function captureFileState(
-  absolutePaths: readonly string[],
-): Promise<Map<string, string | null>> {
-  const state = new Map<string, string | null>();
-  for (const absolutePath of absolutePaths) {
-    state.set(absolutePath, await readFileIfExists(absolutePath));
-  }
-  return state;
-}
-
-async function collectChangedFiles(
-  workspaceRoot: string,
-  absolutePaths: readonly string[],
-  before: ReadonlyMap<string, string | null>,
-): Promise<string[]> {
-  const changes: string[] = [];
-  for (const absolutePath of absolutePaths) {
-    const current = await readFileIfExists(absolutePath);
-    if (current !== before.get(absolutePath)) {
-      changes.push(path.relative(workspaceRoot, absolutePath).replaceAll(path.sep, '/'));
-    }
-  }
-  return changes;
-}
-
-async function readFileIfExists(absolutePath: string): Promise<string | null> {
-  if (!existsSync(absolutePath)) {
-    return null;
-  }
-
-  return await readTextFile(absolutePath);
-}
-
-async function readTextFile(filePath: string): Promise<string> {
-  return await readFile(filePath, 'utf8');
-}
-
-async function writeTextFile(filePath: string, contents: string): Promise<void> {
-  await writeFile(filePath, contents, 'utf8');
-}