@sansavision/aurora 0.1.0-alpha.20260212.4

package/src/create-route.ts

@@ -0,0 +1,581 @@
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+import { type CommandContext, type CommandResult } from "./registry";
+
+export type RouteKind = "crud" | "read-only" | "form" | "dashboard" | "empty";
+export type RouteDataSource = "database" | "api" | "none";
+
+export interface RouteScaffoldOptions {
+  routeSlug: string;
+  routeName: string;
+  kind: RouteKind;
+  dataSource: RouteDataSource;
+  auth: string;
+  realtime: boolean;
+}
+
+export interface RouteScaffoldReport {
+  mode: "create-route";
+  cwd: string;
+  routeSlug: string;
+  routeName: string;
+  routeRoot: string;
+  kind: RouteKind;
+  dataSource: RouteDataSource;
+  auth: string;
+  realtime: boolean;
+  createdFileCount: number;
+}
+
+interface ParsedCreateRouteOptions extends RouteScaffoldOptions {
+  rawName: string;
+}
+
+interface ScaffoldRouteExecutionOptions {
+  commandName?: string;
+}
+
+const ROUTE_KINDS: readonly RouteKind[] = [
+  "crud",
+  "read-only",
+  "form",
+  "dashboard",
+  "empty",
+];
+const ROUTE_DATA_SOURCES: readonly RouteDataSource[] = ["database", "api", "none"];
+
+function parseCreateRouteOptions(
+  args: ReadonlyArray<string>,
+): ParsedCreateRouteOptions | CommandResult {
+  if (args.length === 0) {
+    return {
+      exitCode: 2,
+      stderr: "aurora create-route: route name is required",
+    };
+  }
+
+  const firstArg = args[0];
+  if (!firstArg || firstArg.startsWith("-")) {
+    return {
+      exitCode: 2,
+      stderr: "aurora create-route: route name must be provided before options",
+    };
+  }
+
+  const routeSlug = toRouteSlug(firstArg);
+  if (!routeSlug) {
+    return {
+      exitCode: 2,
+      stderr:
+        "aurora create-route: route name must include at least one letter or number",
+    };
+  }
+
+  const options: ParsedCreateRouteOptions = {
+    rawName: firstArg,
+    routeSlug,
+    routeName: toRouteName(routeSlug),
+    kind: "form",
+    dataSource: "database",
+    auth: "public",
+    realtime: false,
+  };
+
+  for (let i = 1; i < args.length; i += 1) {
+    const arg = args[i];
+
+    if (arg === "--kind") {
+      const value = args[i + 1];
+      if (!value || !isRouteKind(value)) {
+        return {
+          exitCode: 2,
+          stderr:
+            `aurora create-route: --kind requires one of ${ROUTE_KINDS.join("|")}`,
+        };
+      }
+
+      options.kind = value;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--data") {
+      const value = args[i + 1];
+      if (!value || !isRouteDataSource(value)) {
+        return {
+          exitCode: 2,
+          stderr:
+            `aurora create-route: --data requires one of ${ROUTE_DATA_SOURCES.join("|")}`,
+        };
+      }
+
+      options.dataSource = value;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--auth") {
+      const value = args[i + 1];
+      if (!value) {
+        return {
+          exitCode: 2,
+          stderr:
+            "aurora create-route: --auth requires 'public', 'user', 'admin', or 'permission:<name>'",
+        };
+      }
+
+      const parsedAuth = parseAuthMode(value);
+      if (!parsedAuth) {
+        return {
+          exitCode: 2,
+          stderr:
+            "aurora create-route: --auth requires 'public', 'user', 'admin', or 'permission:<name>'",
+        };
+      }
+
+      options.auth = parsedAuth;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--realtime") {
+      options.realtime = true;
+      continue;
+    }
+
+    if (arg === "--no-realtime") {
+      options.realtime = false;
+      continue;
+    }
+
+    return {
+      exitCode: 2,
+      stderr: `aurora create-route: unknown option '${arg}'`,
+    };
+  }
+
+  return options;
+}
+
+function isRouteKind(value: string): value is RouteKind {
+  return ROUTE_KINDS.includes(value as RouteKind);
+}
+
+function isRouteDataSource(value: string): value is RouteDataSource {
+  return ROUTE_DATA_SOURCES.includes(value as RouteDataSource);
+}
+
+function parseAuthMode(value: string): string | undefined {
+  const normalized = value.trim();
+  if (normalized === "public" || normalized === "user" || normalized === "admin") {
+    return normalized;
+  }
+
+  if (/^permission:[a-z0-9:_-]+$/i.test(normalized)) {
+    return normalized;
+  }
+
+  return undefined;
+}
+
+export function toRouteSlug(rawName: string): string {
+  return rawName
+    .trim()
+    .replace(/[^a-zA-Z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .replace(/-+/g, "-")
+    .toLowerCase();
+}
+
+export function toRouteName(routeSlug: string): string {
+  const pascal = routeSlug
+    .split("-")
+    .filter((part) => part.length > 0)
+    .map((part) => part[0].toUpperCase() + part.slice(1))
+    .join("");
+
+  if (/^[A-Za-z_]/.test(pascal)) {
+    return pascal;
+  }
+
+  return `Route${pascal}`;
+}
+
+function isNonEmptyDirectory(path: string): boolean {
+  if (!existsSync(path)) {
+    return false;
+  }
+
+  try {
+    return readdirSync(path).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+function buildRouteScaffoldFiles(
+  options: RouteScaffoldOptions,
+): ReadonlyArray<{ path: string; content: string }> {
+  return [
+    {
+      path: "page.tsx",
+      content: buildPageModule(options),
+    },
+    {
+      path: `${options.routeSlug}.client.tsx`,
+      content: buildClientModule(options),
+    },
+    {
+      path: `${options.routeSlug}.server.ts`,
+      content: buildServerModule(options),
+    },
+  ];
+}
+
+function buildServerModule(options: RouteScaffoldOptions): string {
+  const lines = [
+    "// Safe route defaults: explicit runtime/auth/scope for predictable behavior.",
+    'export const runtime = "node";',
+    `export const auth = "${options.auth}";`,
+    `export const scope = "${options.routeSlug}";`,
+    `export const dataSource = "${options.dataSource}";`,
+    "",
+  ];
+
+  if (options.kind === "form") {
+    lines.push(...buildFormServerModule(options));
+  } else if (options.kind === "read-only") {
+    lines.push(...buildReadOnlyServerModule(options));
+  } else if (options.kind === "crud") {
+    lines.push(...buildCrudServerModule(options));
+  } else if (options.kind === "dashboard") {
+    lines.push(...buildDashboardServerModule(options));
+  } else {
+    lines.push(...buildEmptyServerModule(options));
+  }
+
+  if (options.realtime) {
+    lines.push(
+      "",
+      `export function ${options.routeName}RealtimeChannel(): string {`,
+      `  return "${options.routeSlug}";`,
+      "}",
+    );
+  }
+
+  return lines.join("\n");
+}
+
+function buildFormServerModule(options: RouteScaffoldOptions): string[] {
+  const itemType = `${options.routeName}Item`;
+  const listName = `list${options.routeName}`;
+  const submitInputType = `Submit${options.routeName}Input`;
+  const submitName = `submit${options.routeName}`;
+
+  return [
+    `export interface ${itemType} {`,
+    "  id: string;",
+    "  label: string;",
+    "  createdAt: number;",
+    "}",
+    "",
+    `const seed${options.routeName}: ${itemType}[] = [`,
+    "  {",
+    `    id: "${options.routeSlug}-seed-1",`,
+    "    label: " + JSON.stringify(`${options.routeName} starter entry`) + ",",
+    "    createdAt: 1707609600000,",
+    "  },",
+    "];",
+    "",
+    `export async function ${listName}(): Promise<${itemType}[]> {`,
+    `  return seed${options.routeName};`,
+    "}",
+    "",
+    `export interface ${submitInputType} {`,
+    "  label: string;",
+    "}",
+    "",
+    `export async function ${submitName}(input: ${submitInputType}): Promise<${itemType}> {`,
+    "  return {",
+    "    id: `${scope}-${Date.now()}`,",
+    "    label: input.label,",
+    "    createdAt: Date.now(),",
+    "  };",
+    "}",
+  ];
+}
+
+function buildReadOnlyServerModule(options: RouteScaffoldOptions): string[] {
+  const itemType = `${options.routeName}Item`;
+  const listName = `list${options.routeName}`;
+
+  return [
+    `export interface ${itemType} {`,
+    "  id: string;",
+    "  label: string;",
+    "  updatedAt: number;",
+    "}",
+    "",
+    `export async function ${listName}(): Promise<${itemType}[]> {`,
+    "  return [",
+    "    {",
+    `      id: "${options.routeSlug}-readonly-1",`,
+    "      label: " + JSON.stringify(`${options.routeName} readonly sample`) + ",",
+    "      updatedAt: 1707609600000,",
+    "    },",
+    "  ];",
+    "}",
+  ];
+}
+
+function buildCrudServerModule(options: RouteScaffoldOptions): string[] {
+  const itemType = `${options.routeName}Item`;
+  const listName = `list${options.routeName}`;
+  const createInputType = `Create${options.routeName}Input`;
+  const createName = `create${options.routeName}`;
+  const updateName = `update${options.routeName}`;
+  const removeName = `remove${options.routeName}`;
+
+  return [
+    `export interface ${itemType} {`,
+    "  id: string;",
+    "  label: string;",
+    "  createdAt: number;",
+    "}",
+    "",
+    `export interface ${createInputType} {`,
+    "  label: string;",
+    "}",
+    "",
+    `export async function ${listName}(): Promise<${itemType}[]> {`,
+    "  return [];",
+    "}",
+    "",
+    `export async function ${createName}(input: ${createInputType}): Promise<${itemType}> {`,
+    "  return {",
+    "    id: `${scope}-${Date.now()}`,",
+    "    label: input.label,",
+    "    createdAt: Date.now(),",
+    "  };",
+    "}",
+    "",
+    `export async function ${updateName}(id: string, input: ${createInputType}): Promise<${itemType}> {`,
+    "  return {",
+    "    id,",
+    "    label: input.label,",
+    "    createdAt: Date.now(),",
+    "  };",
+    "}",
+    "",
+    `export async function ${removeName}(id: string): Promise<{ id: string; removed: boolean }> {`,
+    "  return { id, removed: true };",
+    "}",
+  ];
+}
+
+function buildDashboardServerModule(options: RouteScaffoldOptions): string[] {
+  const metricType = `${options.routeName}Metric`;
+  const loadName = `load${options.routeName}Metrics`;
+
+  return [
+    `export interface ${metricType} {`,
+    "  id: string;",
+    "  label: string;",
+    "  value: number;",
+    "}",
+    "",
+    `export async function ${loadName}(): Promise<${metricType}[]> {`,
+    "  return [",
+    "    { id: \"throughput\", label: \"Throughput\", value: 24 },",
+    "    { id: \"error-rate\", label: \"Error Rate\", value: 1.2 },",
+    "  ];",
+    "}",
+  ];
+}
+
+function buildEmptyServerModule(options: RouteScaffoldOptions): string[] {
+  const loadName = `load${options.routeName}Page`;
+
+  return [
+    `export async function ${loadName}(): Promise<{ ready: boolean }> {`,
+    "  return { ready: true };",
+    "}",
+  ];
+}
+
+function buildClientModule(options: RouteScaffoldOptions): string {
+  const lines = [
+    "// Client shell generated with novice-friendly defaults.",
+  ];
+
+  if (options.kind === "dashboard") {
+    const metricType = `${options.routeName}Metric`;
+    lines.push(
+      `import type { ${metricType} } from "./${options.routeSlug}.server";`,
+      "",
+      `export interface ${options.routeName}ClientProps {`,
+      `  metrics: ReadonlyArray<${metricType}>;`,
+      "}",
+      "",
+      `export function render${options.routeName}Client(props: ${options.routeName}ClientProps): string {`,
+      `  return \`<section data-route=\"${options.routeSlug}\"><h1>${options.routeName}</h1><p>metrics: \${props.metrics.length}</p></section>\`;`,
+      "}",
+    );
+
+    return lines.join("\n");
+  }
+
+  if (options.kind === "empty") {
+    lines.push(
+      "",
+      `export function render${options.routeName}Client(): string {`,
+      `  return \`<section data-route=\"${options.routeSlug}\"><h1>${options.routeName}</h1><p>route scaffold ready</p></section>\`;`,
+      "}",
+    );
+
+    return lines.join("\n");
+  }
+
+  const itemType = `${options.routeName}Item`;
+
+  lines.push(
+    `import type { ${itemType} } from "./${options.routeSlug}.server";`,
+    "",
+    `export interface ${options.routeName}ClientProps {`,
+    `  items: ReadonlyArray<${itemType}>;`,
+    "}",
+    "",
+    `export function render${options.routeName}Client(props: ${options.routeName}ClientProps): string {`,
+    `  return \`<section data-route=\"${options.routeSlug}\"><h1>${options.routeName}</h1><p>items: \${props.items.length}</p></section>\`;`,
+    "}",
+  );
+
+  return lines.join("\n");
+}
+
+function buildPageModule(options: RouteScaffoldOptions): string {
+  const pageName = `${options.routeName}Page`;
+  const lines = [
+    `import { render${options.routeName}Client } from "./${options.routeSlug}.client";`,
+  ];
+
+  if (options.kind === "form" || options.kind === "read-only" || options.kind === "crud") {
+    lines.push(
+      `import { list${options.routeName} } from "./${options.routeSlug}.server";`,
+      "",
+      `export async function ${pageName}(): Promise<string> {`,
+      `  const items = await list${options.routeName}();`,
+      `  return render${options.routeName}Client({ items });`,
+      "}",
+    );
+
+    return lines.join("\n");
+  }
+
+  if (options.kind === "dashboard") {
+    lines.push(
+      `import { load${options.routeName}Metrics } from "./${options.routeSlug}.server";`,
+      "",
+      `export async function ${pageName}(): Promise<string> {`,
+      `  const metrics = await load${options.routeName}Metrics();`,
+      `  return render${options.routeName}Client({ metrics });`,
+      "}",
+    );
+
+    return lines.join("\n");
+  }
+
+  lines.push(
+    `import { load${options.routeName}Page } from "./${options.routeSlug}.server";`,
+    "",
+    `export async function ${pageName}(): Promise<string> {`,
+    `  await load${options.routeName}Page();`,
+    `  return render${options.routeName}Client();`,
+    "}",
+  );
+
+  return lines.join("\n");
+}
+
+export function scaffoldRoute(
+  options: RouteScaffoldOptions,
+  context: CommandContext,
+  executionOptions: ScaffoldRouteExecutionOptions = {},
+): RouteScaffoldReport | CommandResult {
+  const commandName = executionOptions.commandName ?? "aurora create-route";
+  const routeRoot = resolve(context.cwd, "src/routes", options.routeSlug);
+
+  if (isNonEmptyDirectory(routeRoot)) {
+    return {
+      exitCode: 2,
+      stderr: `${commandName}: target directory already exists and is not empty: ${routeRoot}`,
+    };
+  }
+
+  const files = buildRouteScaffoldFiles(options);
+
+  try {
+    mkdirSync(routeRoot, { recursive: true });
+
+    for (const file of files) {
+      const absolutePath = join(routeRoot, file.path);
+      mkdirSync(dirname(absolutePath), { recursive: true });
+      writeFileSync(absolutePath, `${file.content}\n`, "utf8");
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      exitCode: 1,
+      stderr: `${commandName}: failed to scaffold route at ${routeRoot}: ${message}`,
+    };
+  }
+
+  return {
+    mode: "create-route",
+    cwd: context.cwd,
+    routeSlug: options.routeSlug,
+    routeName: options.routeName,
+    routeRoot,
+    kind: options.kind,
+    dataSource: options.dataSource,
+    auth: options.auth,
+    realtime: options.realtime,
+    createdFileCount: files.length,
+  };
+}
+
+function renderCreateRouteReport(report: RouteScaffoldReport): string {
+  return [
+    "aurora create-route bootstrap",
+    `cwd: ${report.cwd}`,
+    `route_slug: ${report.routeSlug}`,
+    `route_name: ${report.routeName}`,
+    `route_kind: ${report.kind}`,
+    `data_source: ${report.dataSource}`,
+    `auth: ${report.auth}`,
+    `realtime: ${report.realtime ? "enabled" : "disabled"}`,
+    `route_root: ${report.routeRoot}`,
+    `created_files: ${report.createdFileCount}`,
+  ].join("\n");
+}
+
+export function runCreateRouteCommand(
+  args: ReadonlyArray<string>,
+  context: CommandContext,
+): CommandResult {
+  const options = parseCreateRouteOptions(args);
+  if ("exitCode" in options) {
+    return options;
+  }
+
+  const report = scaffoldRoute(options, context);
+  if ("exitCode" in report) {
+    return report;
+  }
+
+  return {
+    exitCode: 0,
+    stdout: renderCreateRouteReport(report),
+  };
+}