@webstir-io/webstir 0.1.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@webstir-io/webstir",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "webstir": "src/cli.ts"
+  },
+  "scripts": {
+    "build": "node scripts/sync-assets.mjs && bun run build:deps && tsc -p tsconfig.json",
+    "build:deps": "bun run --filter @webstir-io/module-contract build && bun run --filter @webstir-io/testing-contract build && bun run --filter @webstir-io/webstir-frontend build && bun run --filter @webstir-io/webstir-backend build && bun run --filter @webstir-io/webstir-testing build",
+    "test": "bun run build && bun test ./tests/*.ts ./tests/**/*.ts",
+    "clean": "rm -rf dist",
+    "prepack": "node scripts/sync-assets.mjs",
+    "pack:local": "bun pm pack",
+    "pack:standalone": "node scripts/pack-standalone.mjs"
+  },
+  "files": [
+    "assets",
+    "scripts",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "bun": ">=1.3.5"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "dependencies": {
+    "@webstir-io/module-contract": "^0.1.14",
+    "@webstir-io/testing-contract": "^0.1.7",
+    "@webstir-io/webstir-backend": "^0.1.15",
+    "@webstir-io/webstir-frontend": "^0.1.40",
+    "@webstir-io/webstir-testing": "^0.1.5",
+    "typescript": "^5.7.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.21"
+  }
+}

package/scripts/pack-standalone.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { cp, mkdir, mkdtemp, readFile, rename, rm, writeFile } from 'node:fs/promises';
+
+const scriptRoot = path.dirname(new URL(import.meta.url).pathname);
+const packageRoot = path.resolve(scriptRoot, '..');
+const repoRoot = path.resolve(packageRoot, '..', '..');
+const outputRoot = path.join(packageRoot, 'artifacts');
+
+const internalPackages = [
+  ['@webstir-io/module-contract', path.join(repoRoot, 'packages', 'contracts', 'module-contract')],
+  ['@webstir-io/testing-contract', path.join(repoRoot, 'packages', 'contracts', 'testing-contract')],
+  ['@webstir-io/webstir-frontend', path.join(repoRoot, 'packages', 'tooling', 'webstir-frontend')],
+  ['@webstir-io/webstir-backend', path.join(repoRoot, 'packages', 'tooling', 'webstir-backend')],
+  ['@webstir-io/webstir-testing', path.join(repoRoot, 'packages', 'tooling', 'webstir-testing')],
+];
+
+async function main() {
+  run('bun', ['run', 'build:deps'], packageRoot);
+  run('node', ['scripts/sync-assets.mjs'], packageRoot);
+
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'webstir-standalone-pack-'));
+  const tarballRoot = path.join(tempRoot, 'tarballs');
+  const stageRoot = path.join(tempRoot, 'stage');
+
+  await mkdir(tarballRoot, { recursive: true });
+  await mkdir(stageRoot, { recursive: true });
+  await mkdir(outputRoot, { recursive: true });
+
+  try {
+    const tarballs = new Map();
+    for (const [name, cwd] of internalPackages) {
+      tarballs.set(name, await packPackage(cwd, tarballRoot));
+    }
+
+    await cp(path.join(packageRoot, 'assets'), path.join(stageRoot, 'assets'), { recursive: true });
+    await cp(path.join(packageRoot, 'src'), path.join(stageRoot, 'src'), { recursive: true });
+    await cp(path.join(packageRoot, 'README.md'), path.join(stageRoot, 'README.md'));
+
+    const packageJson = JSON.parse(await readFile(path.join(packageRoot, 'package.json'), 'utf8'));
+    const originalDependencies = { ...packageJson.dependencies };
+    packageJson.dependencies = Object.fromEntries(
+      Object.entries(originalDependencies).map(([name, version]) => {
+        const tarballPath = tarballs.get(name);
+        if (!tarballPath) {
+          return [name, version];
+        }
+
+        return [name, `file:${path.relative(stageRoot, tarballPath).split(path.sep).join('/')}`];
+      })
+    );
+    packageJson.bundledDependencies = Object.keys(packageJson.dependencies);
+    packageJson.files = ['assets', 'src', 'README.md'];
+    delete packageJson.scripts;
+    delete packageJson.devDependencies;
+
+    await writeFile(path.join(stageRoot, 'package.json'), `${JSON.stringify(packageJson, null, 2)}\n`, 'utf8');
+
+    run('bun', ['install'], stageRoot);
+    packageJson.dependencies = originalDependencies;
+    await writeFile(path.join(stageRoot, 'package.json'), `${JSON.stringify(packageJson, null, 2)}\n`, 'utf8');
+    const tarballName = run('bun', ['pm', 'pack'], stageRoot)
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line.endsWith('.tgz'))
+      .at(-1);
+
+    if (!tarballName) {
+      throw new Error('Failed to locate standalone tarball output.');
+    }
+
+    const standaloneName = tarballName.replace(/\.tgz$/, '-standalone.tgz');
+    const destination = path.join(outputRoot, standaloneName);
+    await rm(destination, { force: true });
+    await rename(path.join(stageRoot, tarballName), destination);
+    console.log(destination);
+  } finally {
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+}
+
+async function packPackage(cwd, outputDir) {
+  const tarballName = run('bun', ['pm', 'pack'], cwd)
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.endsWith('.tgz'))
+    .at(-1);
+
+  if (!tarballName) {
+    throw new Error(`Failed to pack ${cwd}`);
+  }
+
+  const source = path.join(cwd, tarballName);
+  const destination = path.join(outputDir, tarballName);
+  await rename(source, destination);
+  return destination;
+}
+
+function run(command, args, cwd) {
+  const result = spawnSync(command, args, {
+    cwd,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf8',
+    env: process.env,
+  });
+
+  if (result.stdout) {
+    process.stdout.write(result.stdout);
+  }
+  if (result.stderr) {
+    process.stderr.write(result.stderr);
+  }
+
+  if (result.status !== 0) {
+    throw new Error(`Command failed (${result.status ?? 'unknown'}): ${command} ${args.join(' ')}`);
+  }
+
+  return result.stdout ?? '';
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/scripts/sync-assets.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+import { cp, mkdir, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(here, '..');
+const repoRoot = path.resolve(packageRoot, '..', '..');
+const assetsRoot = path.join(packageRoot, 'assets');
+const templatesRoot = path.join(assetsRoot, 'templates');
+const featuresRoot = path.join(assetsRoot, 'features');
+
+const rootAssets = [
+  'Errors.404.html',
+  'Errors.500.html',
+  'Errors.default.html',
+  'types.global.d.ts',
+  path.join('types', 'global.d.ts'),
+];
+
+const modeTemplates = [
+  {
+    mode: 'ssg',
+    roots: [
+      { source: path.join(repoRoot, 'examples', 'demos', 'ssg', 'base', 'src', 'frontend'), target: path.join('src', 'frontend') },
+    ],
+  },
+  {
+    mode: 'spa',
+    roots: [
+      { source: path.join(repoRoot, 'examples', 'demos', 'spa', 'src', 'frontend'), target: path.join('src', 'frontend') },
+      { source: path.join(repoRoot, 'examples', 'demos', 'spa', 'src', 'shared'), target: path.join('src', 'shared') },
+    ],
+  },
+  {
+    mode: 'api',
+    roots: [
+      { source: path.join(repoRoot, 'examples', 'demos', 'api', 'src', 'backend'), target: path.join('src', 'backend') },
+      { source: path.join(repoRoot, 'examples', 'demos', 'api', 'src', 'shared'), target: path.join('src', 'shared') },
+    ],
+  },
+  {
+    mode: 'full',
+    roots: [
+      { source: path.join(repoRoot, 'examples', 'demos', 'full', 'src', 'frontend'), target: path.join('src', 'frontend') },
+      { source: path.join(repoRoot, 'examples', 'demos', 'full', 'src', 'backend'), target: path.join('src', 'backend') },
+      { source: path.join(repoRoot, 'examples', 'demos', 'full', 'src', 'shared'), target: path.join('src', 'shared') },
+    ],
+  },
+];
+
+const features = [
+  { source: path.join(repoRoot, 'orchestrators', 'dotnet', 'Engine', 'Resources', 'features', 'router'), target: 'router' },
+  { source: path.join(repoRoot, 'orchestrators', 'dotnet', 'Engine', 'Resources', 'features', 'client_nav'), target: 'client_nav' },
+  { source: path.join(repoRoot, 'orchestrators', 'dotnet', 'Engine', 'Resources', 'features', 'search'), target: 'search' },
+  { source: path.join(repoRoot, 'orchestrators', 'dotnet', 'Engine', 'Resources', 'features', 'content_nav'), target: 'content_nav' },
+];
+
+async function main() {
+  await rm(assetsRoot, { recursive: true, force: true });
+  await mkdir(templatesRoot, { recursive: true });
+  await mkdir(featuresRoot, { recursive: true });
+
+  for (const relativePath of rootAssets) {
+    const sourcePath = path.join(repoRoot, 'examples', 'demos', 'spa', relativePath);
+    const targetPath = path.join(templatesRoot, 'shared', relativePath);
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    await cp(sourcePath, targetPath, { recursive: true });
+  }
+
+  for (const template of modeTemplates) {
+    for (const root of template.roots) {
+      const targetPath = path.join(templatesRoot, template.mode, root.target);
+      await mkdir(path.dirname(targetPath), { recursive: true });
+      await cp(root.source, targetPath, { recursive: true });
+    }
+  }
+
+  for (const feature of features) {
+    const targetPath = path.join(featuresRoot, feature.target);
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    await cp(feature.source, targetPath, { recursive: true });
+  }
+}
+
+await main();

package/src/add-backend.ts

@@ -0,0 +1,164 @@
+import type { AddCommandResult } from './add.ts';
+
+import { runAddJob, runAddRoute } from '@webstir-io/webstir-backend';
+
+export interface RunAddBackendOptions {
+  readonly workspaceRoot: string;
+  readonly rawArgs: readonly string[];
+}
+
+export async function runAddRouteCommand(options: RunAddBackendOptions): Promise<AddCommandResult> {
+  const parsed = parseBackendCommandArgs(options.rawArgs, {
+    valueFlags: new Set([
+      '--method',
+      '--path',
+      '--summary',
+      '--description',
+      '--tags',
+      '--params-schema',
+      '--query-schema',
+      '--body-schema',
+      '--headers-schema',
+      '--response-schema',
+      '--response-status',
+      '--response-headers-schema',
+    ]),
+    booleanFlags: new Set(['--fastify']),
+  });
+
+  const name = parsed.positionals[0];
+  if (!name) {
+    throw new Error(
+      'Usage: webstir add-route <name> --workspace <path> [--method <METHOD>] [--path <path>] [--fastify].'
+    );
+  }
+
+  const tags = parsed.values.get('--tags')
+    ?.split(',')
+    .map((tag) => tag.trim())
+    .filter(Boolean);
+
+  const result = await runAddRoute({
+    workspaceRoot: options.workspaceRoot,
+    name,
+    method: parsed.values.get('--method'),
+    path: parsed.values.get('--path'),
+    fastify: parsed.booleans.has('--fastify'),
+    summary: parsed.values.get('--summary'),
+    description: parsed.values.get('--description'),
+    tags,
+    paramsSchema: parsed.values.get('--params-schema'),
+    querySchema: parsed.values.get('--query-schema'),
+    bodySchema: parsed.values.get('--body-schema'),
+    headersSchema: parsed.values.get('--headers-schema'),
+    responseSchema: parsed.values.get('--response-schema'),
+    responseStatus: parsed.values.get('--response-status'),
+    responseHeadersSchema: parsed.values.get('--response-headers-schema'),
+  });
+
+  return {
+    workspaceRoot: options.workspaceRoot,
+    subject: 'route',
+    target: result.target,
+    changes: result.changes,
+  };
+}
+
+export async function runAddJobCommand(options: RunAddBackendOptions): Promise<AddCommandResult> {
+  const parsed = parseBackendCommandArgs(options.rawArgs, {
+    valueFlags: new Set(['--schedule', '--description', '--priority']),
+    booleanFlags: new Set(),
+  });
+
+  const name = parsed.positionals[0];
+  if (!name) {
+    throw new Error('Usage: webstir add-job <name> --workspace <path> [--schedule <expression>].');
+  }
+
+  const result = await runAddJob({
+    workspaceRoot: options.workspaceRoot,
+    name,
+    schedule: parsed.values.get('--schedule'),
+    description: parsed.values.get('--description'),
+    priority: parsed.values.get('--priority'),
+  });
+
+  return {
+    workspaceRoot: options.workspaceRoot,
+    subject: 'job',
+    target: result.target,
+    changes: result.changes,
+  };
+}
+
+interface ParseSpec {
+  readonly valueFlags: ReadonlySet<string>;
+  readonly booleanFlags: ReadonlySet<string>;
+}
+
+interface ParsedBackendCommandArgs {
+  readonly positionals: readonly string[];
+  readonly values: ReadonlyMap<string, string>;
+  readonly booleans: ReadonlySet<string>;
+}
+
+function parseBackendCommandArgs(rawArgs: readonly string[], spec: ParseSpec): ParsedBackendCommandArgs {
+  const positionals: string[] = [];
+  const values = new Map<string, string>();
+  const booleans = new Set<string>();
+
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index];
+
+    if (!arg.startsWith('-')) {
+      positionals.push(arg);
+      continue;
+    }
+
+    if (arg === '--workspace' || arg === '-w') {
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--help' || arg === '-h') {
+      continue;
+    }
+
+    const [flag, inlineValue] = splitInlineOption(arg);
+
+    if (spec.booleanFlags.has(flag)) {
+      booleans.add(flag);
+      continue;
+    }
+
+    if (spec.valueFlags.has(flag)) {
+      const value = inlineValue ?? rawArgs[index + 1];
+      if (!value || value.startsWith('-')) {
+        throw new Error(`Missing value for ${flag}.`);
+      }
+
+      values.set(flag, value);
+      if (inlineValue === undefined) {
+        index += 1;
+      }
+      continue;
+    }
+
+    throw new Error(`Unknown option "${arg}".`);
+  }
+
+  return {
+    positionals,
+    values,
+    booleans,
+  };
+}
+
+function splitInlineOption(arg: string): readonly [string, string | undefined] {
+  const equalsIndex = arg.indexOf('=');
+  if (equalsIndex < 0) {
+    return [arg, undefined];
+  }
+
+  return [arg.slice(0, equalsIndex), arg.slice(equalsIndex + 1)];
+}

package/src/add.ts

@@ -0,0 +1,112 @@
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+
+import { runAddPage } from '@webstir-io/webstir-frontend';
+import { runAddTest } from '@webstir-io/webstir-testing';
+
+export interface RunAddPageOptions {
+  readonly workspaceRoot: string;
+  readonly args: readonly string[];
+}
+
+export interface RunAddTestOptions {
+  readonly workspaceRoot: string;
+  readonly args: readonly string[];
+}
+
+export interface AddCommandResult {
+  readonly workspaceRoot: string;
+  readonly subject: 'page' | 'test' | 'route' | 'job';
+  readonly target: string;
+  readonly changes: readonly string[];
+  readonly note?: string;
+}
+
+export async function runAddPageCommand(options: RunAddPageOptions): Promise<AddCommandResult> {
+  const pageName = options.args[0];
+  if (!pageName) {
+    throw new Error('Usage: webstir add-page <name> --workspace <path>.');
+  }
+
+  const pageRoot = path.join(options.workspaceRoot, 'src', 'frontend', 'pages', pageName);
+  const trackedPaths = [
+    path.join(pageRoot, 'index.html'),
+    path.join(pageRoot, 'index.css'),
+    path.join(pageRoot, 'index.ts'),
+    path.join(pageRoot, 'tests', `${path.basename(pageName)}.test.ts`),
+    path.join(options.workspaceRoot, 'package.json'),
+  ];
+  const before = await captureFileState(trackedPaths);
+
+  await runAddPage({
+    workspaceRoot: options.workspaceRoot,
+    pageName,
+  });
+
+  const changes = await collectChangedFiles(options.workspaceRoot, trackedPaths, before);
+
+  return {
+    workspaceRoot: options.workspaceRoot,
+    subject: 'page',
+    target: pageName,
+    changes,
+  };
+}
+
+export async function runAddTestCommand(options: RunAddTestOptions): Promise<AddCommandResult> {
+  const nameArg = options.args[0];
+  if (!nameArg) {
+    throw new Error('Usage: webstir add-test <name-or-path> --workspace <path>.');
+  }
+
+  const result = await runAddTest({
+    workspaceRoot: options.workspaceRoot,
+    name: nameArg,
+  });
+
+  return {
+    workspaceRoot: options.workspaceRoot,
+    subject: 'test',
+    target: result.normalizedName,
+    changes: result.created ? [result.relativePath.replaceAll(path.sep, '/')] : [],
+    note: result.created ? undefined : `File already exists: ${result.relativePath.replaceAll(path.sep, '/')}`,
+  };
+}
+
+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(toWorkspaceRelative(workspaceRoot, absolutePath));
+    }
+  }
+
+  return changes;
+}
+
+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 readFileIfExists(absolutePath: string): Promise<string | null> {
+  if (!existsSync(absolutePath)) {
+    return null;
+  }
+
+  return await readFile(absolutePath, 'utf8');
+}
+
+function toWorkspaceRelative(workspaceRoot: string, absolutePath: string): string {
+  return path.relative(workspaceRoot, absolutePath).replaceAll(path.sep, '/');
+}

package/src/api-watch.ts

@@ -0,0 +1,84 @@
+import path from 'node:path';
+import { startBackendWatch } from '@webstir-io/webstir-backend';
+
+import { BackendRuntimeSupervisor } from './backend-runtime.ts';
+import { createWorkspaceRuntimeEnv } from './runtime.ts';
+import { createStopSignal } from './stop-signal.ts';
+import type { WorkspaceDescriptor } from './types.ts';
+import type { WatchIo, WatchOptions } from './watch.ts';
+
+export interface ApiWatchSession {
+  readonly origin: string;
+  stop(): Promise<void>;
+}
+
+export async function runApiWatch(
+  workspace: WorkspaceDescriptor,
+  options: WatchOptions,
+  io: WatchIo
+): Promise<void> {
+  const session = await startApiWatchSession(workspace, options, io);
+
+  io.stdout.write(
+    `[webstir] watch starting\nworkspace: ${workspace.name}\nmode: ${workspace.mode}\nurl: ${session.origin}\n`
+  );
+
+  const stopSignal = createStopSignal();
+  try {
+    await stopSignal.promise;
+  } finally {
+    stopSignal.dispose();
+    await session.stop();
+  }
+}
+
+export async function startApiWatchSession(
+  workspace: WorkspaceDescriptor,
+  options: WatchOptions,
+  io: WatchIo
+): Promise<ApiWatchSession> {
+  const runtimeEnv = createWorkspaceRuntimeEnv(workspace.root, 'build', options.env);
+  const runtime = new BackendRuntimeSupervisor({
+    workspaceRoot: workspace.root,
+    buildRoot: path.join(workspace.root, 'build', 'backend'),
+    host: options.host ?? '127.0.0.1',
+    port: options.port,
+    env: runtimeEnv,
+    io,
+  });
+
+  await runtime.prepare();
+
+  let initialReadyLogged = false;
+  const watchHandle = await startBackendWatch({
+    workspaceRoot: workspace.root,
+    env: runtimeEnv,
+    onEvent: async (event) => {
+      if (event.type !== 'build-complete') {
+        return;
+      }
+
+      if (event.succeeded !== true) {
+        io.stderr.write('[webstir] backend rebuild failed; keeping the current runtime process.\n');
+        return;
+      }
+
+      await runtime.restart();
+      if (!initialReadyLogged) {
+        initialReadyLogged = true;
+        io.stdout.write(`[webstir] backend ready at ${runtime.getOrigin()}\n`);
+        return;
+      }
+
+      io.stdout.write(`[webstir] backend restarted at ${runtime.getOrigin()}\n`);
+    },
+  });
+
+  return {
+    origin: runtime.getOrigin(),
+    async stop() {
+      await runtime.stop();
+      await watchHandle.stop();
+    },
+  };
+}

package/src/backend-inspect.ts

@@ -0,0 +1,45 @@
+import type { ModuleManifest } from '@webstir-io/module-contract';
+import type { WorkspaceDescriptor } from './types.ts';
+
+import { loadProvider } from './providers.ts';
+import { createWorkspaceRuntimeEnv } from './runtime.ts';
+import { readWorkspaceDescriptor } from './workspace.ts';
+
+export interface RunBackendInspectOptions {
+  readonly workspaceRoot: string;
+  readonly env?: Record<string, string | undefined>;
+}
+
+export interface BackendInspectResult {
+  readonly workspace: WorkspaceDescriptor;
+  readonly buildRoot: string;
+  readonly manifest: ModuleManifest;
+}
+
+export async function runBackendInspect(options: RunBackendInspectOptions): Promise<BackendInspectResult> {
+  const workspace = await readWorkspaceDescriptor(options.workspaceRoot);
+  if (workspace.mode !== 'api' && workspace.mode !== 'full') {
+    throw new Error(`backend-inspect only supports api and full workspaces. Received mode "${workspace.mode}".`);
+  }
+
+  const provider = await loadProvider('backend');
+  const resolvedWorkspace = await provider.resolveWorkspace({
+    workspaceRoot: workspace.root,
+    config: {},
+  });
+  const result = await provider.build({
+    workspaceRoot: workspace.root,
+    env: createWorkspaceRuntimeEnv(workspace.root, 'build', options.env),
+    incremental: false,
+  });
+  const manifest = result.manifest.module;
+  if (!manifest) {
+    throw new Error('Backend manifest was not produced by the backend build.');
+  }
+
+  return {
+    workspace,
+    buildRoot: resolvedWorkspace.buildRoot,
+    manifest,
+  };
+}