@webstir-io/webstir 0.1.0

package/src/init.ts

@@ -0,0 +1,339 @@
+import path from 'node:path';
+import { cp, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import { getModeScaffoldAssets, getRootScaffoldAssets } from './init-assets.ts';
+import { monorepoRoot } from './paths.ts';
+import type { WorkspaceMode } from './types.ts';
+
+const PACKAGE_MANAGER = 'bun@1.3.5';
+const REPO_WORKSPACE_PATTERNS = [
+  'packages/contracts/*',
+  'packages/tooling/*',
+  'orchestrators/bun',
+  'apps/*',
+  'examples/demos/*',
+  'examples/demos/ssg/*',
+] as const;
+
+const MODE_DESCRIPTIONS: Record<WorkspaceMode, string> = {
+  ssg: 'Static site (SSG) workspace for Webstir.',
+  spa: 'SPA frontend workspace for Webstir.',
+  api: 'Backend API workspace for Webstir.',
+  full: 'Full-stack workspace for Webstir.',
+};
+
+export interface RunInitOptions {
+  readonly args: readonly string[];
+  readonly cwd?: string;
+  readonly workspaceRoot?: string;
+}
+
+export interface InitResult {
+  readonly workspaceRoot: string;
+  readonly mode: WorkspaceMode;
+  readonly packageName: string;
+  readonly changes: readonly string[];
+}
+
+export async function runInit(options: RunInitOptions): Promise<InitResult> {
+  const request = parseInitRequest(options.args, options.workspaceRoot, options.cwd ?? process.cwd());
+  return scaffoldWorkspace(request.mode, request.workspaceRoot, { force: false });
+}
+
+export async function scaffoldWorkspace(
+  mode: WorkspaceMode,
+  workspaceRoot: string,
+  options: { readonly force: boolean }
+): Promise<InitResult> {
+  if (existsSync(workspaceRoot) && !options.force && !(await isDirectoryEmpty(workspaceRoot))) {
+    throw new Error(`Refusing to initialize non-empty directory: ${workspaceRoot}`);
+  }
+
+  await mkdir(workspaceRoot, { recursive: true });
+
+  const packageName = resolvePackageName(workspaceRoot);
+  const dependencySpecs = await resolveDependencySpecs(workspaceRoot);
+  const changes: string[] = [];
+
+  for (const asset of getRootScaffoldAssets()) {
+    const targetPath = path.join(workspaceRoot, asset.targetPath);
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    await cp(asset.sourcePath, targetPath, { force: true });
+    changes.push(toWorkspaceRelative(workspaceRoot, targetPath));
+  }
+
+  for (const asset of await getModeScaffoldAssets(mode)) {
+    const targetPath = path.join(workspaceRoot, asset.targetPath);
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    await cp(asset.sourcePath, targetPath, { force: true });
+    changes.push(toWorkspaceRelative(workspaceRoot, targetPath));
+  }
+
+  const packageJsonPath = path.join(workspaceRoot, 'package.json');
+  await writeFile(
+    packageJsonPath,
+    `${JSON.stringify(createPackageJson(mode, workspaceRoot, packageName, dependencySpecs), null, 2)}\n`,
+    'utf8'
+  );
+  changes.push('package.json');
+
+  const baseTsconfigPath = path.join(workspaceRoot, 'base.tsconfig.json');
+  await writeFile(baseTsconfigPath, `${JSON.stringify(createBaseTsconfig(mode), null, 2)}\n`, 'utf8');
+  changes.push('base.tsconfig.json');
+
+  return {
+    workspaceRoot,
+    mode,
+    packageName,
+    changes: uniqueSorted(changes),
+  };
+}
+
+function parseInitRequest(
+  args: readonly string[],
+  workspaceOverride: string | undefined,
+  cwd: string
+): { readonly mode: WorkspaceMode; readonly workspaceRoot: string } {
+  const [firstArg, secondArg] = args;
+
+  if (workspaceOverride) {
+    if (!firstArg) {
+      throw new Error('Usage: webstir init <mode> --workspace <path> or webstir init <mode> <directory>.');
+    }
+
+    return {
+      mode: parseWorkspaceMode(firstArg),
+      workspaceRoot: path.resolve(cwd, workspaceOverride),
+    };
+  }
+
+  if (!firstArg) {
+    throw new Error('Usage: webstir init <mode> <directory> or webstir init <directory>.');
+  }
+
+  if (!secondArg) {
+    return {
+      mode: 'full',
+      workspaceRoot: path.resolve(cwd, firstArg),
+    };
+  }
+
+  return {
+    mode: parseWorkspaceMode(firstArg),
+    workspaceRoot: path.resolve(cwd, secondArg),
+  };
+}
+
+function parseWorkspaceMode(value: string): WorkspaceMode {
+  const normalized = value.trim().toLowerCase();
+  if (normalized === 'ssg' || normalized === 'spa' || normalized === 'api' || normalized === 'full') {
+    return normalized;
+  }
+
+  if (normalized === 'fullstack') {
+    return 'full';
+  }
+
+  throw new Error(`Unknown init mode "${value}". Expected ssg, spa, api, or full.`);
+}
+
+async function isRepoWorkspacePath(workspaceRoot: string): Promise<boolean> {
+  if (!monorepoRoot) {
+    return false;
+  }
+
+  const relative = path.relative(monorepoRoot, workspaceRoot).replaceAll(path.sep, '/');
+  if (!relative || relative.startsWith('..')) {
+    return false;
+  }
+
+  return REPO_WORKSPACE_PATTERNS.some((pattern) => matchesWorkspacePattern(relative, pattern));
+}
+
+async function resolveDependencySpecs(workspaceRoot: string): Promise<Record<string, string>> {
+  if (await isRepoWorkspacePath(workspaceRoot)) {
+    return {
+      '@webstir-io/webstir-frontend': 'workspace:*',
+      '@webstir-io/webstir-backend': 'workspace:*',
+      '@webstir-io/webstir-testing': 'workspace:*',
+    };
+  }
+
+  return {
+    '@webstir-io/webstir-frontend': await readInstalledPackageVersion('@webstir-io/webstir-frontend'),
+    '@webstir-io/webstir-backend': await readInstalledPackageVersion('@webstir-io/webstir-backend'),
+    '@webstir-io/webstir-testing': await readInstalledPackageVersion('@webstir-io/webstir-testing'),
+  };
+}
+
+async function readPackageVersion(packageJsonPath: string): Promise<string> {
+  const packageJson = JSON.parse(await readFile(packageJsonPath, 'utf8')) as { readonly version?: string };
+  if (!packageJson.version) {
+    throw new Error(`Missing version in ${packageJsonPath}`);
+  }
+
+  return `^${packageJson.version}`;
+}
+
+function createPackageJson(
+  mode: WorkspaceMode,
+  workspaceRoot: string,
+  packageName: string,
+  dependencySpecs: Record<string, string>
+): Record<string, unknown> {
+  const dependencies: Record<string, string> = {
+    '@webstir-io/webstir-testing': dependencySpecs['@webstir-io/webstir-testing'],
+  };
+
+  if (mode === 'ssg' || mode === 'spa' || mode === 'full') {
+    dependencies['@webstir-io/webstir-frontend'] = dependencySpecs['@webstir-io/webstir-frontend'];
+  }
+
+  if (mode === 'api' || mode === 'full') {
+    dependencies['@webstir-io/webstir-backend'] = dependencySpecs['@webstir-io/webstir-backend'];
+  }
+
+  return {
+    name: packageName,
+    version: '1.0.0',
+    private: true,
+    type: 'module',
+    description: resolveDescription(mode, workspaceRoot),
+    dependencies,
+    devDependencies: {
+      '@types/node': '^20.0.0',
+      autoprefixer: '^10.4.20',
+      esbuild: '^0.25.0',
+      typescript: '^5.4.0',
+    },
+    packageManager: PACKAGE_MANAGER,
+    browserslist: [
+      'last 2 chrome versions',
+      'last 2 firefox versions',
+      'last 2 safari major versions',
+      'iOS >= 14',
+      'not dead',
+    ],
+    webstir: {
+      mode,
+      moduleManifest: {},
+    },
+  };
+}
+
+function createBaseTsconfig(mode: WorkspaceMode): Record<string, unknown> {
+  const references = [];
+  if (mode !== 'api') {
+    if (mode !== 'ssg' && mode !== 'spa') {
+      references.push({ path: 'src/shared' });
+      references.push({ path: 'src/frontend' });
+      references.push({ path: 'src/backend' });
+    } else if (mode === 'spa') {
+      references.push({ path: 'src/shared' });
+      references.push({ path: 'src/frontend' });
+    } else {
+      references.push({ path: 'src/frontend' });
+    }
+  } else {
+    references.push({ path: 'src/shared' });
+    references.push({ path: 'src/backend' });
+  }
+
+  return {
+    files: [],
+    references,
+    compilerOptions: {
+      target: 'ES2022',
+      module: 'esnext',
+      moduleResolution: 'node',
+      strict: true,
+      esModuleInterop: true,
+      skipLibCheck: true,
+      forceConsistentCasingInFileNames: true,
+      sourceMap: true,
+      declaration: false,
+      removeComments: true,
+      typeRoots: [
+        './types',
+        './node_modules/@types',
+      ],
+      inlineSources: true,
+    },
+  };
+}
+
+function resolveDescription(mode: WorkspaceMode, workspaceRoot: string): string {
+  const relative = monorepoRoot
+    ? path.relative(monorepoRoot, workspaceRoot).replaceAll(path.sep, '/')
+    : '';
+  if (relative === 'examples/demos/full') {
+    return 'Webstir frontend defaults and tooling';
+  }
+
+  return MODE_DESCRIPTIONS[mode];
+}
+
+function resolvePackageName(workspaceRoot: string): string {
+  const relative = monorepoRoot
+    ? path.relative(monorepoRoot, workspaceRoot).replaceAll(path.sep, '/')
+    : '';
+  const known = getKnownWorkspacePackageName(relative);
+  if (known) {
+    return known;
+  }
+
+  return sanitizePackageName(path.basename(workspaceRoot));
+}
+
+async function readInstalledPackageVersion(packageName: string): Promise<string> {
+  const packageJsonUrl = import.meta.resolve(`${packageName}/package.json`);
+  const packageJsonPath = fileURLToPath(packageJsonUrl);
+  return await readPackageVersion(packageJsonPath);
+}
+
+function getKnownWorkspacePackageName(relativePath: string): string | undefined {
+  switch (relativePath) {
+    case 'examples/demos/spa':
+      return 'webstir-demo-spa';
+    case 'examples/demos/api':
+      return 'webstir-demo-api';
+    case 'examples/demos/full':
+      return 'webstir-demo-full';
+    case 'examples/demos/ssg/base':
+      return 'webstir-demo-ssg-base';
+    case 'examples/demos/ssg/site':
+      return 'webstir-demo-ssg-site';
+    default:
+      return undefined;
+  }
+}
+
+function sanitizePackageName(value: string): string {
+  const normalized = value.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+  return normalized || 'webstir-project';
+}
+
+async function isDirectoryEmpty(directoryPath: string): Promise<boolean> {
+  const entries = await readdir(directoryPath);
+  return entries.length === 0;
+}
+
+function matchesWorkspacePattern(relativePath: string, pattern: string): boolean {
+  const relativeSegments = relativePath.split('/').filter(Boolean);
+  const patternSegments = pattern.split('/').filter(Boolean);
+  if (relativeSegments.length !== patternSegments.length) {
+    return false;
+  }
+
+  return patternSegments.every((segment, index) => segment === '*' || segment === relativeSegments[index]);
+}
+
+function uniqueSorted(values: readonly string[]): string[] {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+
+function toWorkspaceRelative(workspaceRoot: string, absolutePath: string): string {
+  return path.relative(workspaceRoot, absolutePath).replaceAll(path.sep, '/');
+}

package/src/paths.ts

@@ -0,0 +1,26 @@
+import path from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+export const packageRoot = path.resolve(here, '..');
+export const assetsRoot = path.join(packageRoot, 'assets');
+
+export const monorepoRoot = resolveMonorepoRoot();
+export const repoRoot = monorepoRoot ?? path.resolve(packageRoot, '..', '..');
+
+function resolveMonorepoRoot(): string | null {
+  const candidate = path.resolve(packageRoot, '..', '..');
+  const packageJsonPath = path.join(candidate, 'package.json');
+  if (!existsSync(packageJsonPath)) {
+    return null;
+  }
+
+  try {
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as { name?: string };
+    return packageJson.name === 'webstir' ? candidate : null;
+  } catch {
+    return null;
+  }
+}

package/src/providers.ts

@@ -0,0 +1,88 @@
+import path from 'node:path';
+import { access } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+
+import type { BuildProvider, BuildTargetKind } from './types.ts';
+import { monorepoRoot } from './paths.ts';
+import { resolveRuntimeCommand } from './runtime.ts';
+
+let localPackageBuildPromise: Promise<void> | null = null;
+
+export async function loadProvider(kind: BuildTargetKind): Promise<BuildProvider> {
+  await ensureLocalPackageArtifacts();
+  if (kind === 'frontend') {
+    const mod = await import('@webstir-io/webstir-frontend') as { frontendProvider: BuildProvider };
+    return mod.frontendProvider;
+  }
+
+  const mod = await import('@webstir-io/webstir-backend') as { backendProvider: BuildProvider };
+  return mod.backendProvider;
+}
+
+export async function ensureLocalPackageArtifacts(): Promise<void> {
+  if (!monorepoRoot) {
+    return;
+  }
+
+  const requiredEntries = [
+    path.join(monorepoRoot, 'packages', 'contracts', 'module-contract', 'dist', 'index.js'),
+    path.join(monorepoRoot, 'packages', 'contracts', 'testing-contract', 'dist', 'index.js'),
+    path.join(monorepoRoot, 'packages', 'tooling', 'webstir-frontend', 'dist', 'index.js'),
+    path.join(monorepoRoot, 'packages', 'tooling', 'webstir-frontend', 'dist', 'cli.js'),
+    path.join(monorepoRoot, 'packages', 'tooling', 'webstir-backend', 'dist', 'index.js'),
+    path.join(monorepoRoot, 'packages', 'tooling', 'webstir-backend', 'dist', 'watch.js'),
+    path.join(monorepoRoot, 'packages', 'tooling', 'webstir-testing', 'dist', 'index.js'),
+  ];
+
+  try {
+    await Promise.all(requiredEntries.map(async (entry) => await access(entry)));
+    return;
+  } catch {
+    // Fall through to the build step.
+  }
+
+  if (!localPackageBuildPromise) {
+    localPackageBuildPromise = buildLocalPackages();
+  }
+
+  await localPackageBuildPromise;
+}
+
+async function buildLocalPackages(): Promise<void> {
+  const packages = [
+    '@webstir-io/module-contract',
+    '@webstir-io/testing-contract',
+    '@webstir-io/webstir-frontend',
+    '@webstir-io/webstir-backend',
+    '@webstir-io/webstir-testing',
+  ];
+
+  for (const packageName of packages) {
+    await runRuntimeCommand(['run', '--filter', packageName, 'build']);
+  }
+}
+
+async function runRuntimeCommand(args: readonly string[]): Promise<void> {
+  const cwd = monorepoRoot;
+  if (!cwd) {
+    return;
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn(resolveRuntimeCommand(), args, {
+      cwd,
+      env: process.env,
+      stdio: 'inherit',
+    });
+
+    child.once('error', reject);
+    child.once('close', (code: number | null) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+
+      reject(new Error(`Command failed with exit code ${code}: ${args.join(' ')}`));
+    });
+  });
+}

package/src/publish.ts

@@ -0,0 +1,8 @@
+import type { CommandExecutionResult } from './types.ts';
+import { runCommand, type RunCommandOptions } from './execute.ts';
+
+export type RunPublishOptions = RunCommandOptions;
+
+export async function runPublish(options: RunPublishOptions): Promise<CommandExecutionResult> {
+  return await runCommand('publish', options);
+}

package/src/refresh.ts

@@ -0,0 +1,56 @@
+import path from 'node:path';
+import { mkdir, readdir, rm } from 'node:fs/promises';
+
+import { scaffoldWorkspace } from './init.ts';
+import type { WorkspaceMode } from './types.ts';
+
+export interface RunRefreshOptions {
+  readonly workspaceRoot: string;
+  readonly args: readonly string[];
+  readonly cwd?: string;
+}
+
+export interface RefreshResult {
+  readonly workspaceRoot: string;
+  readonly mode: WorkspaceMode;
+  readonly changes: readonly string[];
+}
+
+export async function runRefresh(options: RunRefreshOptions): Promise<RefreshResult> {
+  const workspaceRoot = path.resolve(options.cwd ?? process.cwd(), options.workspaceRoot);
+  const modeToken = options.args[0];
+  if (!modeToken) {
+    throw new Error('Usage: webstir refresh <mode> --workspace <path>.');
+  }
+
+  const mode = parseWorkspaceMode(modeToken);
+  await mkdir(workspaceRoot, { recursive: true });
+  await emptyDirectory(workspaceRoot);
+
+  const result = await scaffoldWorkspace(mode, workspaceRoot, { force: true });
+  return {
+    workspaceRoot: result.workspaceRoot,
+    mode: result.mode,
+    changes: result.changes,
+  };
+}
+
+async function emptyDirectory(directoryPath: string): Promise<void> {
+  const entries = await readdir(directoryPath, { withFileTypes: true });
+  for (const entry of entries) {
+    await rm(path.join(directoryPath, entry.name), { recursive: true, force: true });
+  }
+}
+
+function parseWorkspaceMode(value: string): WorkspaceMode {
+  const normalized = value.trim().toLowerCase();
+  if (normalized === 'ssg' || normalized === 'spa' || normalized === 'api' || normalized === 'full') {
+    return normalized;
+  }
+
+  if (normalized === 'fullstack') {
+    return 'full';
+  }
+
+  throw new Error(`Unknown refresh mode "${value}". Expected ssg, spa, api, or full.`);
+}