@stackweld/core 0.2.0

package/src/engine/performance-profiler.ts

@@ -0,0 +1,354 @@
+/**
+ * Performance Profiler — Estimates performance characteristics of a tech stack.
+ */
+
+import type { Technology, TechnologyCategory } from "../types/technology.js";
+
+// ─── Types ────────────────────────────────────────────
+
+export interface TechPerformance {
+  id: string;
+  name: string;
+  category: TechnologyCategory;
+  perf: "fast" | "moderate" | "heavy";
+  note: string;
+}
+
+export interface PerformanceProfile {
+  stackName: string;
+  rating: "blazing" | "fast" | "moderate" | "heavy";
+  estimatedReqPerSec: string;
+  estimatedColdStart: string;
+  estimatedMemory: string;
+  notes: string[];
+  techProfiles: TechPerformance[];
+}
+
+// ─── Knowledge Maps ───────────────────────────────────
+
+const RUNTIME_PERF: Record<string, { perf: TechPerformance["perf"]; note: string }> = {
+  go: { perf: "fast", note: "Compiled, goroutines, minimal GC pause" },
+  rust: { perf: "fast", note: "Zero-cost abstractions, no GC" },
+  bun: { perf: "fast", note: "Native-speed JS runtime with built-in bundler" },
+  nodejs: { perf: "moderate", note: "V8 JIT, single-threaded event loop" },
+  deno: { perf: "moderate", note: "V8 JIT, secure by default" },
+  python: { perf: "heavy", note: "Interpreted, GIL limits concurrency" },
+  php: { perf: "heavy", note: "Process-per-request model, opcache helps" },
+};
+
+const FRAMEWORK_PERF: Record<string, { perf: TechPerformance["perf"]; note: string }> = {
+  fastify: { perf: "fast", note: "Schema-based serialization, low overhead" },
+  hono: { perf: "fast", note: "Ultra-lightweight, works on edge runtimes" },
+  gin: { perf: "fast", note: "High-performance Go HTTP framework" },
+  echo: { perf: "fast", note: "Minimal Go framework, fast router" },
+  fastapi: { perf: "fast", note: "Async Python with Starlette + Pydantic" },
+  actix: { perf: "fast", note: "Rust actor framework, top benchmark scores" },
+  express: { perf: "moderate", note: "Mature middleware stack, moderate throughput" },
+  nestjs: { perf: "moderate", note: "Decorator-heavy, adds abstraction overhead" },
+  django: { perf: "moderate", note: "Batteries-included, ORM adds overhead" },
+  flask: { perf: "moderate", note: "Minimal but synchronous by default" },
+  nextjs: { perf: "moderate", note: "SSR/SSG adds build complexity" },
+  nuxt: { perf: "moderate", note: "Vue SSR framework, similar profile to Next" },
+  remix: { perf: "moderate", note: "Nested routes, server-first rendering" },
+  laravel: { perf: "moderate", note: "Full PHP framework, Eloquent ORM overhead" },
+  sveltekit: { perf: "moderate", note: "Compiled output is fast, SSR moderate" },
+};
+
+const DATABASE_PERF: Record<string, { perf: TechPerformance["perf"]; note: string }> = {
+  redis: { perf: "fast", note: "In-memory, sub-millisecond latency" },
+  sqlite: { perf: "fast", note: "Embedded, zero network overhead" },
+  postgresql: { perf: "moderate", note: "ACID-compliant, excellent query planner" },
+  mysql: { perf: "moderate", note: "Widely optimized, good read performance" },
+  mongodb: { perf: "moderate", note: "Document store, flexible but heavier writes" },
+  mariadb: { perf: "moderate", note: "MySQL fork, comparable performance" },
+};
+
+const SERVICE_PERF: Record<string, { perf: TechPerformance["perf"]; note: string }> = {
+  grafana: { perf: "heavy", note: "Dashboard rendering, query aggregation" },
+  prometheus: { perf: "heavy", note: "Time-series storage, scraping overhead" },
+  elasticsearch: { perf: "heavy", note: "JVM-based, memory-intensive indexing" },
+  rabbitmq: { perf: "moderate", note: "Erlang-based message broker" },
+  kafka: { perf: "moderate", note: "High-throughput streaming, JVM overhead" },
+  nginx: { perf: "fast", note: "Event-driven, very low resource usage" },
+  traefik: { perf: "fast", note: "Go-based reverse proxy, auto-discovery" },
+};
+
+const ALL_PERF_MAPS: Record<
+  string,
+  Record<string, { perf: TechPerformance["perf"]; note: string }>
+> = {
+  runtime: RUNTIME_PERF,
+  backend: FRAMEWORK_PERF,
+  frontend: FRAMEWORK_PERF,
+  database: DATABASE_PERF,
+  service: SERVICE_PERF,
+};
+
+// ─── Benchmark Estimates ──────────────────────────────
+
+interface BenchmarkKey {
+  runtime?: string;
+  framework?: string;
+  database?: string;
+}
+
+const BENCHMARKS: Array<{
+  match: BenchmarkKey;
+  reqPerSec: string;
+  coldStart: string;
+  memory: string;
+}> = [
+  {
+    match: { runtime: "rust", framework: "actix", database: "postgresql" },
+    reqPerSec: "~30k req/s",
+    coldStart: "~50ms",
+    memory: "~32MB",
+  },
+  {
+    match: { runtime: "go", framework: "gin", database: "postgresql" },
+    reqPerSec: "~25k req/s",
+    coldStart: "~80ms",
+    memory: "~48MB",
+  },
+  {
+    match: { runtime: "go", framework: "echo", database: "postgresql" },
+    reqPerSec: "~25k req/s",
+    coldStart: "~80ms",
+    memory: "~48MB",
+  },
+  {
+    match: { runtime: "bun", framework: "hono", database: "postgresql" },
+    reqPerSec: "~20k req/s",
+    coldStart: "~100ms",
+    memory: "~64MB",
+  },
+  {
+    match: { runtime: "nodejs", framework: "fastify", database: "postgresql" },
+    reqPerSec: "~15k req/s",
+    coldStart: "~200ms",
+    memory: "~128MB",
+  },
+  {
+    match: { runtime: "nodejs", framework: "express", database: "postgresql" },
+    reqPerSec: "~8k req/s",
+    coldStart: "~300ms",
+    memory: "~128MB",
+  },
+  {
+    match: { runtime: "nodejs", framework: "nestjs", database: "postgresql" },
+    reqPerSec: "~6k req/s",
+    coldStart: "~500ms",
+    memory: "~192MB",
+  },
+  {
+    match: { runtime: "python", framework: "fastapi", database: "postgresql" },
+    reqPerSec: "~5k req/s",
+    coldStart: "~400ms",
+    memory: "~128MB",
+  },
+  {
+    match: { runtime: "python", framework: "django", database: "postgresql" },
+    reqPerSec: "~2k req/s",
+    coldStart: "~600ms",
+    memory: "~192MB",
+  },
+  {
+    match: { runtime: "python", framework: "flask", database: "postgresql" },
+    reqPerSec: "~3k req/s",
+    coldStart: "~400ms",
+    memory: "~128MB",
+  },
+  {
+    match: { runtime: "php", framework: "laravel", database: "mysql" },
+    reqPerSec: "~1.5k req/s",
+    coldStart: "~500ms",
+    memory: "~192MB",
+  },
+  // Partial matches (no database)
+  {
+    match: { runtime: "go", framework: "gin" },
+    reqPerSec: "~40k req/s",
+    coldStart: "~50ms",
+    memory: "~32MB",
+  },
+  {
+    match: { runtime: "rust", framework: "actix" },
+    reqPerSec: "~50k req/s",
+    coldStart: "~30ms",
+    memory: "~16MB",
+  },
+  {
+    match: { runtime: "nodejs", framework: "fastify" },
+    reqPerSec: "~25k req/s",
+    coldStart: "~150ms",
+    memory: "~96MB",
+  },
+  {
+    match: { runtime: "nodejs", framework: "express" },
+    reqPerSec: "~12k req/s",
+    coldStart: "~200ms",
+    memory: "~96MB",
+  },
+  {
+    match: { runtime: "python", framework: "fastapi" },
+    reqPerSec: "~8k req/s",
+    coldStart: "~300ms",
+    memory: "~96MB",
+  },
+];
+
+// ─── Rating Logic ─────────────────────────────────────
+
+const PERF_RANK: Record<TechPerformance["perf"], number> = {
+  fast: 3,
+  moderate: 2,
+  heavy: 1,
+};
+
+function perfToRating(perf: TechPerformance["perf"]): PerformanceProfile["rating"] {
+  switch (perf) {
+    case "fast":
+      return "blazing";
+    case "moderate":
+      return "fast";
+    case "heavy":
+      return "moderate";
+  }
+}
+
+function worstPerf(perfs: TechPerformance["perf"][]): TechPerformance["perf"] {
+  if (perfs.length === 0) return "moderate";
+  let worst: TechPerformance["perf"] = "fast";
+  for (const p of perfs) {
+    if (PERF_RANK[p] < PERF_RANK[worst]) worst = p;
+  }
+  return worst;
+}
+
+// ─── Main Function ────────────────────────────────────
+
+export function profilePerformance(technologies: Technology[]): PerformanceProfile {
+  const techProfiles: TechPerformance[] = [];
+  const criticalPerfs: TechPerformance["perf"][] = [];
+  const notes: string[] = [];
+
+  // Identify key components
+  let runtimeId: string | undefined;
+  let frameworkId: string | undefined;
+  let databaseId: string | undefined;
+
+  for (const tech of technologies) {
+    const perfMap = ALL_PERF_MAPS[tech.category];
+    const entry = perfMap?.[tech.id];
+
+    if (entry) {
+      techProfiles.push({
+        id: tech.id,
+        name: tech.name,
+        category: tech.category,
+        perf: entry.perf,
+        note: entry.note,
+      });
+
+      // Track critical path components
+      if (
+        tech.category === "runtime" ||
+        tech.category === "backend" ||
+        tech.category === "database"
+      ) {
+        criticalPerfs.push(entry.perf);
+      }
+    } else {
+      // Unknown tech — assume moderate
+      techProfiles.push({
+        id: tech.id,
+        name: tech.name,
+        category: tech.category,
+        perf: "moderate",
+        note: "No benchmark data available",
+      });
+    }
+
+    if (tech.category === "runtime") runtimeId = tech.id;
+    if (tech.category === "backend") frameworkId = tech.id;
+    if (tech.category === "database") databaseId = tech.id;
+  }
+
+  // Overall rating based on slowest critical-path component
+  const worst = worstPerf(criticalPerfs);
+  const rating = criticalPerfs.length > 0 ? perfToRating(worst) : "moderate";
+
+  // Build stack name
+  const stackName = technologies.map((t) => t.name).join(" + ");
+
+  // Find matching benchmark
+  let estimatedReqPerSec = "Varies by implementation";
+  let estimatedColdStart = "N/A";
+  let estimatedMemory = "N/A";
+
+  // Try exact match first, then partial
+  const matchKey: BenchmarkKey = {
+    runtime: runtimeId,
+    framework: frameworkId,
+    database: databaseId,
+  };
+
+  let bestMatch: (typeof BENCHMARKS)[number] | undefined;
+  let bestMatchScore = 0;
+
+  for (const bench of BENCHMARKS) {
+    let score = 0;
+    let valid = true;
+
+    for (const [key, value] of Object.entries(bench.match)) {
+      const actual = matchKey[key as keyof BenchmarkKey];
+      if (value && actual === value) {
+        score++;
+      } else if (value) {
+        valid = false;
+        break;
+      }
+    }
+
+    if (valid && score > bestMatchScore) {
+      bestMatch = bench;
+      bestMatchScore = score;
+    }
+  }
+
+  if (bestMatch) {
+    estimatedReqPerSec = bestMatch.reqPerSec;
+    estimatedColdStart = bestMatch.coldStart;
+    estimatedMemory = bestMatch.memory;
+  }
+
+  // Generate notes
+  const fastTechs = techProfiles.filter((t) => t.perf === "fast");
+  const heavyTechs = techProfiles.filter((t) => t.perf === "heavy");
+
+  if (fastTechs.length > 0 && heavyTechs.length === 0) {
+    notes.push("All components are high-performance — excellent stack choice.");
+  }
+  if (heavyTechs.length > 0) {
+    notes.push(`Bottleneck: ${heavyTechs.map((t) => t.name).join(", ")} may limit throughput.`);
+  }
+  if (runtimeId && !frameworkId) {
+    notes.push("No framework detected — raw runtime performance may differ with framework choice.");
+  }
+  if (!databaseId) {
+    notes.push("No database detected — estimates assume compute-only workload.");
+  }
+  if (rating === "blazing") {
+    notes.push("This stack is suitable for high-traffic production workloads.");
+  }
+
+  return {
+    stackName,
+    rating,
+    estimatedReqPerSec,
+    estimatedColdStart,
+    estimatedMemory,
+    notes,
+    techProfiles,
+  };
+}

package/src/engine/plugin-loader.ts

@@ -0,0 +1,216 @@
+/**
+ * Plugin Loader — Discovers, installs, and loads Stackweld plugins.
+ *
+ * Plugins live in ~/.stackweld/plugins/<name>/ and expose a
+ * stackweld.plugin.json manifest describing their capabilities.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { Technology } from "../types/technology.js";
+import type { Template } from "../types/template.js";
+
+// ─── Types ────────────────────────────────────────────
+
+export interface PluginCommand {
+  name: string;
+  description: string;
+  handler: string;
+}
+
+export interface StackweldPlugin {
+  name: string;
+  version: string;
+  description: string;
+  technologies?: Technology[];
+  templates?: Template[];
+  commands?: PluginCommand[];
+}
+
+export interface PluginManifest {
+  name: string;
+  version: string;
+  description: string;
+  main: string;
+  type: "technology" | "template" | "command" | "mixed";
+}
+
+// ─── Plugin Directory ─────────────────────────────────
+
+export function getPluginDir(): string {
+  return path.join(os.homedir(), ".stackweld", "plugins");
+}
+
+function ensurePluginDir(): void {
+  const dir = getPluginDir();
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+// ─── List Plugins ─────────────────────────────────────
+
+export function listPlugins(): PluginManifest[] {
+  const dir = getPluginDir();
+  if (!fs.existsSync(dir)) return [];
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const manifests: PluginManifest[] = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const manifestPath = path.join(dir, entry.name, "stackweld.plugin.json");
+    if (!fs.existsSync(manifestPath)) continue;
+
+    try {
+      const raw = fs.readFileSync(manifestPath, "utf-8");
+      const manifest = JSON.parse(raw) as PluginManifest;
+      manifests.push(manifest);
+    } catch {
+      // Skip malformed manifests
+    }
+  }
+
+  return manifests;
+}
+
+// ─── Install Plugin ───────────────────────────────────
+
+export function installPlugin(nameOrPath: string): PluginManifest {
+  ensurePluginDir();
+
+  const sourcePath = path.resolve(nameOrPath);
+
+  if (!fs.existsSync(sourcePath)) {
+    throw new Error(`Plugin source not found: ${sourcePath}`);
+  }
+
+  if (!fs.statSync(sourcePath).isDirectory()) {
+    throw new Error(`Plugin source must be a directory: ${sourcePath}`);
+  }
+
+  const manifestPath = path.join(sourcePath, "stackweld.plugin.json");
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error(`No stackweld.plugin.json found in: ${sourcePath}`);
+  }
+
+  let manifest: PluginManifest;
+  try {
+    const raw = fs.readFileSync(manifestPath, "utf-8");
+    manifest = JSON.parse(raw) as PluginManifest;
+  } catch {
+    throw new Error(`Invalid stackweld.plugin.json in: ${sourcePath}`);
+  }
+
+  if (!manifest.name || !manifest.version || !manifest.main) {
+    throw new Error("Plugin manifest must have name, version, and main fields.");
+  }
+
+  const destDir = path.join(getPluginDir(), manifest.name);
+
+  // Remove existing installation
+  if (fs.existsSync(destDir)) {
+    fs.rmSync(destDir, { recursive: true, force: true });
+  }
+
+  // Copy plugin directory
+  copyDirRecursive(sourcePath, destDir);
+
+  return manifest;
+}
+
+function copyDirRecursive(src: string, dest: string): void {
+  fs.mkdirSync(dest, { recursive: true });
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      // Skip node_modules and .git
+      if (entry.name === "node_modules" || entry.name === ".git") continue;
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+// ─── Remove Plugin ────────────────────────────────────
+
+export function removePlugin(name: string): void {
+  const pluginDir = path.join(getPluginDir(), name);
+
+  if (!fs.existsSync(pluginDir)) {
+    throw new Error(`Plugin "${name}" is not installed.`);
+  }
+
+  fs.rmSync(pluginDir, { recursive: true, force: true });
+}
+
+// ─── Load Plugin ──────────────────────────────────────
+
+export function loadPlugin(name: string): StackweldPlugin | null {
+  const pluginDir = path.join(getPluginDir(), name);
+  const manifestPath = path.join(pluginDir, "stackweld.plugin.json");
+
+  if (!fs.existsSync(manifestPath)) return null;
+
+  try {
+    const raw = fs.readFileSync(manifestPath, "utf-8");
+    const manifest = JSON.parse(raw) as PluginManifest;
+    const mainPath = path.join(pluginDir, manifest.main);
+
+    if (!fs.existsSync(mainPath)) return null;
+
+    // Read the main file and parse it as JSON data (for static plugins)
+    // or return manifest-only info
+    const mainRaw = fs.readFileSync(mainPath, "utf-8");
+    const pluginData = JSON.parse(mainRaw) as StackweldPlugin;
+
+    return {
+      name: manifest.name,
+      version: manifest.version,
+      description: manifest.description,
+      technologies: pluginData.technologies || [],
+      templates: pluginData.templates || [],
+      commands: pluginData.commands || [],
+    };
+  } catch {
+    return null;
+  }
+}
+
+// ─── Get Plugin Info ──────────────────────────────────
+
+export function getPluginInfo(name: string): PluginManifest | null {
+  const manifestPath = path.join(getPluginDir(), name, "stackweld.plugin.json");
+
+  if (!fs.existsSync(manifestPath)) return null;
+
+  try {
+    const raw = fs.readFileSync(manifestPath, "utf-8");
+    return JSON.parse(raw) as PluginManifest;
+  } catch {
+    return null;
+  }
+}
+
+// ─── Load All Plugin Technologies ─────────────────────
+
+export function loadPluginTechnologies(): Technology[] {
+  const plugins = listPlugins();
+  const allTechs: Technology[] = [];
+
+  for (const manifest of plugins) {
+    const plugin = loadPlugin(manifest.name);
+    if (plugin?.technologies) {
+      allTechs.push(...plugin.technologies);
+    }
+  }
+
+  return allTechs;
+}

package/src/engine/preferences.ts

@@ -0,0 +1,85 @@
+/**
+ * Preferences — Persistent user preferences stored in SQLite.
+ */
+
+import { getDatabase } from "../db/database.js";
+
+export interface UserPreferences {
+  editor: string;
+  packageManager: string;
+  shell: string;
+  dockerMode: string;
+  defaultProfile: string;
+  theme: string;
+}
+
+const DEFAULTS: UserPreferences = {
+  editor: "code",
+  packageManager: "pnpm",
+  shell: "zsh",
+  dockerMode: "compose",
+  defaultProfile: "standard",
+  theme: "dark",
+};
+
+function ensureTable(): void {
+  const db = getDatabase();
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS preferences (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    )
+  `);
+}
+
+/** Get all preferences, merged with defaults. */
+export function getPreferences(): UserPreferences {
+  ensureTable();
+  const db = getDatabase();
+  const rows = db.prepare("SELECT key, value FROM preferences").all() as {
+    key: string;
+    value: string;
+  }[];
+
+  const prefs = { ...DEFAULTS };
+  for (const row of rows) {
+    if (row.key in prefs) {
+      (prefs as Record<string, string>)[row.key] = row.value;
+    }
+  }
+  return prefs;
+}
+
+/** Get a single preference. */
+export function getPreference(key: keyof UserPreferences): string {
+  ensureTable();
+  const db = getDatabase();
+  const row = db.prepare("SELECT value FROM preferences WHERE key = ?").get(key) as
+    | { value: string }
+    | undefined;
+  return row?.value ?? DEFAULTS[key];
+}
+
+/** Set a single preference. */
+export function setPreference(key: keyof UserPreferences, value: string): void {
+  ensureTable();
+  const db = getDatabase();
+  db.prepare("INSERT OR REPLACE INTO preferences (key, value) VALUES (?, ?)").run(key, value);
+}
+
+/** Reset all preferences to defaults. */
+export function resetPreferences(): void {
+  ensureTable();
+  const db = getDatabase();
+  db.prepare("DELETE FROM preferences").run();
+}
+
+/** Get the list of valid preference keys. */
+export function getPreferenceKeys(): (keyof UserPreferences)[] {
+  return Object.keys(DEFAULTS) as (keyof UserPreferences)[];
+}
+
+/** Get default values. */
+export function getDefaultPreferences(): UserPreferences {
+  return { ...DEFAULTS };
+}