@sansavision/aurora 0.1.0-alpha.20260212.4

package/src/ai.ts

@@ -0,0 +1,574 @@
+import { runCreateFeatureCommand } from "./create-feature";
+import {
+  toAiReadableDiagnostic,
+  type AiReadableDiagnostic,
+} from "./ai-diagnostics";
+import { type CommandContext, type CommandResult } from "./registry";
+
+type AiOutputFormat = "text" | "json";
+type AiRouteKind = "crud" | "read-only" | "form" | "dashboard" | "empty";
+type AiRouteDataSource = "database" | "api" | "none";
+
+interface AiOptions {
+  prompt: string;
+  format: AiOutputFormat;
+  dryRun: boolean;
+  nameOverride?: string;
+  authOverride?: string;
+}
+
+interface AiInference {
+  featureSlug: string;
+  featureName: string;
+  routeKind: AiRouteKind;
+  routeDataSource: AiRouteDataSource;
+  routeAuth: string;
+  routeRealtime: boolean;
+  confidence: number;
+  rationale: readonly string[];
+  createFeatureArgs: readonly string[];
+}
+
+interface AiScaffoldResult {
+  attempted: boolean;
+  created: boolean;
+  exitCode?: number;
+  stdout?: string;
+  stderr?: string;
+}
+
+interface AiReport {
+  mode: "ai";
+  cwd: string;
+  prompt: string;
+  generatedAt: string;
+  dryRun: boolean;
+  inferred: AiInference;
+  scaffold: AiScaffoldResult;
+  diagnostics: readonly AiReadableDiagnostic[];
+  references: readonly string[];
+  testedExamples: readonly {
+    readonly prompt: string;
+    readonly expectation: string;
+  }[];
+}
+
+const STOP_WORDS = new Set([
+  "a",
+  "an",
+  "add",
+  "and",
+  "app",
+  "build",
+  "create",
+  "feature",
+  "for",
+  "in",
+  "new",
+  "screen",
+  "the",
+  "to",
+  "with",
+]);
+
+const DOC_REFERENCES = [
+  "https://aurora.dev/docs/ai/overview",
+  "https://aurora.dev/docs/ai/prompting-guide",
+  "https://aurora.dev/docs/cli/ai",
+] as const;
+
+const TESTED_EXAMPLES = [
+  {
+    prompt: "add a guestbook feature with reactions and moderation",
+    expectation:
+      "scaffolds feature + route with CRUD defaults and admin auth inference",
+  },
+  {
+    prompt: "create a realtime incident dashboard from api events",
+    expectation: "scaffolds dashboard route with api data mode and realtime enabled",
+  },
+] as const;
+
+export function runAiCommand(
+  args: ReadonlyArray<string>,
+  context: CommandContext,
+): CommandResult {
+  const parsed = parseAiOptions(args);
+  if ("exitCode" in parsed) {
+    return parsed;
+  }
+
+  const diagnostics: AiReadableDiagnostic[] = [];
+  const inference = inferFromPrompt(parsed.prompt, parsed.nameOverride, parsed.authOverride);
+
+  if (inference.featureSlug === "ai-feature") {
+    diagnostics.push(
+      toAiReadableDiagnostic({
+        code: "AI_PROMPT_UNDERSPECIFIED",
+        severity: "warning",
+        message:
+          "Prompt did not include enough domain-specific tokens to infer a stable feature slug.",
+        remediation:
+          "Add domain nouns (for example guestbook, billing, notifications) or pass --name <feature-slug>.",
+        category: "ai",
+      }),
+    );
+  }
+
+  let scaffold: AiScaffoldResult = {
+    attempted: !parsed.dryRun,
+    created: false,
+  };
+
+  if (!parsed.dryRun) {
+    const result = runCreateFeatureCommand(inference.createFeatureArgs, context);
+
+    scaffold = {
+      attempted: true,
+      created: result.exitCode === 0,
+      exitCode: result.exitCode,
+      stdout: result.stdout,
+      stderr: result.stderr,
+    };
+
+    if (result.exitCode !== 0) {
+      diagnostics.push(
+        toAiReadableDiagnostic({
+          code: "AI_SCAFFOLD_FAILED",
+          severity: "error",
+          message:
+            result.stderr ??
+            "AI scaffold execution failed while applying inferred create-feature command.",
+          remediation:
+            "Resolve the scaffold error and rerun `aurora ai` with --dry-run first for quick validation.",
+          category: "ai",
+        }),
+      );
+    }
+  }
+
+  const report: AiReport = {
+    mode: "ai",
+    cwd: context.cwd,
+    prompt: parsed.prompt,
+    generatedAt: new Date().toISOString(),
+    dryRun: parsed.dryRun,
+    inferred: inference,
+    scaffold,
+    diagnostics,
+    references: DOC_REFERENCES,
+    testedExamples: TESTED_EXAMPLES,
+  };
+
+  const exitCode = scaffold.exitCode ?? 0;
+
+  if (parsed.format === "json") {
+    return {
+      exitCode,
+      stdout: JSON.stringify(report, null, 2),
+    };
+  }
+
+  return {
+    exitCode,
+    stdout: renderAiTextReport(report),
+  };
+}
+
+function parseAiOptions(args: ReadonlyArray<string>): AiOptions | CommandResult {
+  const options: Omit<AiOptions, "prompt"> & { promptParts: string[] } = {
+    format: "text",
+    dryRun: false,
+    promptParts: [],
+    nameOverride: undefined,
+    authOverride: undefined,
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+
+    if (arg === "--format") {
+      const value = args[i + 1];
+      if (!value || (value !== "text" && value !== "json")) {
+        return {
+          exitCode: 2,
+          stderr: "aurora ai: --format requires 'text' or 'json'",
+        };
+      }
+
+      options.format = value;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+
+    if (arg === "--name") {
+      const value = args[i + 1];
+      if (!value) {
+        return {
+          exitCode: 2,
+          stderr: "aurora ai: --name requires a feature slug",
+        };
+      }
+
+      const slug = toFeatureSlug(value);
+      if (!slug) {
+        return {
+          exitCode: 2,
+          stderr:
+            "aurora ai: --name must include at least one letter or number",
+        };
+      }
+
+      options.nameOverride = slug;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--auth") {
+      const value = args[i + 1];
+      if (!value) {
+        return {
+          exitCode: 2,
+          stderr:
+            "aurora ai: --auth requires 'public', 'user', 'admin', or 'permission:<name>'",
+        };
+      }
+
+      const parsedAuth = parseAuthMode(value);
+      if (!parsedAuth) {
+        return {
+          exitCode: 2,
+          stderr:
+            "aurora ai: --auth requires 'public', 'user', 'admin', or 'permission:<name>'",
+        };
+      }
+
+      options.authOverride = parsedAuth;
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--")) {
+      return {
+        exitCode: 2,
+        stderr: `aurora ai: unknown option '${arg}'`,
+      };
+    }
+
+    options.promptParts.push(arg);
+  }
+
+  const prompt = options.promptParts.join(" ").trim();
+  if (!prompt) {
+    return {
+      exitCode: 2,
+      stderr: "aurora ai: prompt description is required",
+    };
+  }
+
+  return {
+    prompt,
+    format: options.format,
+    dryRun: options.dryRun,
+    nameOverride: options.nameOverride,
+    authOverride: options.authOverride,
+  };
+}
+
+function inferFromPrompt(
+  prompt: string,
+  nameOverride: string | undefined,
+  authOverride: string | undefined,
+): AiInference {
+  const lowerPrompt = prompt.toLowerCase();
+  const tokens = (lowerPrompt.match(/[a-z0-9]+/g) ?? []).filter((token) => token.length > 1);
+
+  const inferredSlug =
+    nameOverride ??
+    toFeatureSlug(
+      tokens
+        .filter((token) => !STOP_WORDS.has(token))
+        .slice(0, 3)
+        .join("-"),
+    ) ??
+    "ai-feature";
+
+  const featureSlug = inferredSlug.length > 0 ? inferredSlug : "ai-feature";
+  const featureName = toFeatureName(featureSlug);
+
+  const routeKind = inferRouteKind(lowerPrompt);
+  const routeDataSource = inferRouteDataSource(lowerPrompt);
+  const inferredAuth = inferRouteAuth(lowerPrompt);
+  const routeAuth = authOverride ?? inferredAuth.value;
+  const routeRealtime = inferRealtime(lowerPrompt);
+
+  const rationale = [
+    routeKind.reason,
+    routeDataSource.reason,
+    authOverride
+      ? "route auth override applied from --auth"
+      : inferredAuth.reason,
+    routeRealtime
+      ? "detected realtime keywords (live/chat/updates/stream)"
+      : "no realtime keywords detected; realtime scaffold disabled",
+  ];
+
+  const confidence = computeConfidence(prompt, featureSlug, tokens.length, routeRealtime);
+
+  const createFeatureArgs = [
+    featureSlug,
+    "--kind",
+    routeKind.value,
+    "--data",
+    routeDataSource.value,
+    "--auth",
+    routeAuth,
+    routeRealtime ? "--realtime" : "--no-realtime",
+  ] as const;
+
+  return {
+    featureSlug,
+    featureName,
+    routeKind: routeKind.value,
+    routeDataSource: routeDataSource.value,
+    routeAuth,
+    routeRealtime,
+    confidence,
+    rationale,
+    createFeatureArgs,
+  };
+}
+
+function inferRouteKind(prompt: string): { value: AiRouteKind; reason: string } {
+  if (containsAny(prompt, ["dashboard", "analytics", "metric", "chart"])) {
+    return {
+      value: "dashboard",
+      reason: "detected dashboard/analytics terms; selecting dashboard scaffold kind",
+    };
+  }
+
+  if (containsAny(prompt, ["crud", "admin", "moderation", "manage", "delete", "update"])) {
+    return {
+      value: "crud",
+      reason: "detected management/moderation terms; selecting CRUD scaffold kind",
+    };
+  }
+
+  if (containsAny(prompt, ["list", "feed", "timeline", "read", "viewer", "catalog"])) {
+    return {
+      value: "read-only",
+      reason: "detected listing/read patterns; selecting read-only scaffold kind",
+    };
+  }
+
+  if (containsAny(prompt, ["empty", "blank", "starter"])) {
+    return {
+      value: "empty",
+      reason: "detected explicit empty/starter intent; selecting empty scaffold kind",
+    };
+  }
+
+  return {
+    value: "form",
+    reason: "defaulting to form scaffold kind for mutation-first feature generation",
+  };
+}
+
+function inferRouteDataSource(prompt: string): { value: AiRouteDataSource; reason: string } {
+  if (containsAny(prompt, ["api", "rest", "graphql", "webhook", "http"])) {
+    return {
+      value: "api",
+      reason: "detected external API terms; selecting api data source mode",
+    };
+  }
+
+  if (containsAny(prompt, ["static", "local", "mock", "offline", "no data"])) {
+    return {
+      value: "none",
+      reason: "detected static/no-data terms; selecting none data source mode",
+    };
+  }
+
+  return {
+    value: "database",
+    reason: "defaulting to database data source mode",
+  };
+}
+
+function inferRouteAuth(
+  prompt: string,
+): { value: string; reason: string } {
+  const value = inferRouteAuthValue(prompt);
+
+  if (value === "admin") {
+    return {
+      value,
+      reason: "detected admin/moderation intent; selecting admin auth",
+    };
+  }
+
+  if (value === "user") {
+    return {
+      value,
+      reason: "detected account/private intent; selecting user auth",
+    };
+  }
+
+  return {
+    value,
+    reason: "defaulting to public auth",
+  };
+}
+
+function inferRouteAuthValue(prompt: string): string {
+  if (containsAny(prompt, ["admin", "moderation", "moderator", "backoffice"])) {
+    return "admin";
+  }
+
+  if (containsAny(prompt, ["account", "profile", "member", "private", "user"])) {
+    return "user";
+  }
+
+  return "public";
+}
+
+function inferRealtime(prompt: string): boolean {
+  return containsAny(prompt, [
+    "realtime",
+    "real-time",
+    "live",
+    "stream",
+    "chat",
+    "notification",
+    "updates",
+    "socket",
+  ]);
+}
+
+function computeConfidence(
+  prompt: string,
+  featureSlug: string,
+  tokenCount: number,
+  routeRealtime: boolean,
+): number {
+  let confidence = 0.55;
+
+  if (featureSlug !== "ai-feature") {
+    confidence += 0.1;
+  }
+
+  if (prompt.trim().length >= 24) {
+    confidence += 0.1;
+  }
+
+  if (tokenCount >= 6) {
+    confidence += 0.1;
+  }
+
+  if (routeRealtime) {
+    confidence += 0.05;
+  }
+
+  return Math.min(0.95, Math.max(0.4, Number(confidence.toFixed(2))));
+}
+
+function renderAiTextReport(report: AiReport): string {
+  const lines = [
+    "aurora ai bootstrap",
+    `cwd: ${report.cwd}`,
+    `prompt: ${report.prompt}`,
+    `generated_at: ${report.generatedAt}`,
+    `dry_run: ${report.dryRun ? "enabled" : "disabled"}`,
+    `feature_slug: ${report.inferred.featureSlug}`,
+    `feature_name: ${report.inferred.featureName}`,
+    `route_kind: ${report.inferred.routeKind}`,
+    `route_data_source: ${report.inferred.routeDataSource}`,
+    `route_auth: ${report.inferred.routeAuth}`,
+    `route_realtime: ${report.inferred.routeRealtime ? "enabled" : "disabled"}`,
+    `confidence: ${report.inferred.confidence}`,
+    `scaffold_command: aurora create-feature ${report.inferred.createFeatureArgs.join(" ")}`,
+    "rationale:",
+    ...report.inferred.rationale.map((reason) => `- ${reason}`),
+  ];
+
+  if (report.diagnostics.length > 0) {
+    lines.push("diagnostics:");
+    for (const diagnostic of report.diagnostics) {
+      lines.push(`- [${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.whatWentWrong}`);
+      lines.push(`  why: ${diagnostic.why}`);
+      lines.push(`  fix: ${diagnostic.howToFix}`);
+      lines.push(`  docs: ${diagnostic.docs}`);
+    }
+  } else {
+    lines.push("diagnostics: none");
+  }
+
+  lines.push("references:");
+  lines.push(...report.references.map((reference) => `- ${reference}`));
+
+  lines.push("tested_examples:");
+  lines.push(
+    ...report.testedExamples.map(
+      (example) => `- ${example.prompt} -> ${example.expectation}`,
+    ),
+  );
+
+  if (report.scaffold.attempted && report.scaffold.stdout) {
+    lines.push("scaffold_output:");
+    lines.push(...report.scaffold.stdout.split("\n").map((line) => `  ${line}`));
+  }
+
+  if (report.scaffold.attempted && report.scaffold.stderr) {
+    lines.push(`scaffold_error: ${report.scaffold.stderr}`);
+  }
+
+  return lines.join("\n");
+}
+
+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;
+}
+
+function toFeatureSlug(rawName: string): string | undefined {
+  const slug = rawName
+    .trim()
+    .replace(/[^a-zA-Z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .replace(/-+/g, "-")
+    .toLowerCase();
+
+  return slug.length > 0 ? slug : undefined;
+}
+
+function toFeatureName(slug: string): string {
+  const pascal = slug
+    .split("-")
+    .filter((part) => part.length > 0)
+    .map((part) => part[0].toUpperCase() + part.slice(1))
+    .join("");
+
+  if (/^[A-Za-z_]/.test(pascal)) {
+    return pascal;
+  }
+
+  return `Feature${pascal}`;
+}
+
+function containsAny(value: string, keywords: readonly string[]): boolean {
+  return keywords.some((keyword) => value.includes(keyword));
+}