@stackweld/core 0.2.0

package/src/db/database.ts

@@ -0,0 +1,112 @@
+/**
+ * Database — SQLite persistence layer for stacks, projects, and versions.
+ * Uses better-sqlite3 for synchronous, reliable access.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import Database from "better-sqlite3";
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS stacks (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL UNIQUE,
+  description TEXT NOT NULL DEFAULT '',
+  profile TEXT NOT NULL DEFAULT 'standard',
+  version INTEGER NOT NULL DEFAULT 1,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  tags TEXT NOT NULL DEFAULT '[]'
+);
+
+CREATE TABLE IF NOT EXISTS stack_technologies (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  stack_id TEXT NOT NULL REFERENCES stacks(id) ON DELETE CASCADE,
+  technology_id TEXT NOT NULL,
+  version TEXT NOT NULL,
+  port INTEGER,
+  config TEXT DEFAULT '{}',
+  UNIQUE(stack_id, technology_id)
+);
+
+CREATE TABLE IF NOT EXISTS stack_versions (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  stack_id TEXT NOT NULL REFERENCES stacks(id) ON DELETE CASCADE,
+  version INTEGER NOT NULL,
+  changelog TEXT NOT NULL DEFAULT '',
+  snapshot TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  UNIQUE(stack_id, version)
+);
+
+CREATE TABLE IF NOT EXISTS project_instances (
+  id TEXT PRIMARY KEY,
+  stack_id TEXT NOT NULL REFERENCES stacks(id),
+  name TEXT NOT NULL,
+  path TEXT NOT NULL,
+  template_id TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  last_opened_at TEXT
+);
+
+CREATE TABLE IF NOT EXISTS project_services (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  project_id TEXT NOT NULL REFERENCES project_instances(id) ON DELETE CASCADE,
+  service_name TEXT NOT NULL,
+  technology_id TEXT,
+  port INTEGER,
+  docker_container_id TEXT,
+  status TEXT DEFAULT 'not_started',
+  UNIQUE(project_id, service_name)
+);
+
+CREATE TABLE IF NOT EXISTS user_tech_notes (
+  tech_id TEXT PRIMARY KEY,
+  rating INTEGER CHECK(rating >= 1 AND rating <= 5),
+  notes TEXT DEFAULT '',
+  last_used_at TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_stack_tech_stack ON stack_technologies(stack_id);
+CREATE INDEX IF NOT EXISTS idx_stack_versions_stack ON stack_versions(stack_id);
+CREATE INDEX IF NOT EXISTS idx_projects_stack ON project_instances(stack_id);
+CREATE INDEX IF NOT EXISTS idx_project_services_project ON project_services(project_id);
+
+CREATE TABLE IF NOT EXISTS custom_templates (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL UNIQUE,
+  description TEXT NOT NULL DEFAULT '',
+  profile TEXT NOT NULL DEFAULT 'standard',
+  technology_ids TEXT NOT NULL DEFAULT '[]',
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+`;
+
+let db: Database.Database | null = null;
+
+export function getDatabase(dbPath?: string): Database.Database {
+  if (db) return db;
+
+  const resolvedPath = dbPath || getDefaultDbPath();
+  const dir = path.dirname(resolvedPath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  db = new Database(resolvedPath);
+  db.pragma("journal_mode = WAL");
+  db.pragma("foreign_keys = ON");
+  db.exec(SCHEMA);
+
+  return db;
+}
+
+export function closeDatabase(): void {
+  if (db) {
+    db.close();
+    db = null;
+  }
+}
+
+export function getDefaultDbPath(): string {
+  const home = process.env.HOME || process.env.USERPROFILE || ".";
+  return path.join(home, ".stackweld", "stackweld.db");
+}

package/src/db/index.ts

@@ -0,0 +1 @@
+export { closeDatabase, getDatabase, getDefaultDbPath } from "./database.js";

package/src/engine/compatibility-scorer.ts

@@ -0,0 +1,222 @@
+/**
+ * Compatibility Scorer — Calculates a 0-100 score for technology combinations.
+ * Goes beyond binary compatible/incompatible to show nuanced pairing quality.
+ */
+
+import type { Technology } from "../types/index.js";
+
+export interface CompatibilityResult {
+  score: number; // 0-100
+  grade: "S" | "A" | "B" | "C" | "D" | "F";
+  factors: CompatibilityFactor[];
+  recommendation: string;
+}
+
+export interface CompatibilityFactor {
+  label: string;
+  points: number;
+  description: string;
+}
+
+export interface StackScoreResult {
+  overall: number;
+  grade: string;
+  pairs: Array<{ a: string; b: string; score: number }>;
+}
+
+// ─── Complementary category pairs ─────────────────────
+
+const COMPLEMENTARY_PAIRS: ReadonlySet<string> = new Set([
+  "frontend:backend",
+  "backend:frontend",
+  "database:orm",
+  "orm:database",
+  "frontend:styling",
+  "styling:frontend",
+  "frontend:orm",
+  "orm:frontend",
+  "backend:database",
+  "database:backend",
+  "runtime:frontend",
+  "frontend:runtime",
+  "runtime:backend",
+  "backend:runtime",
+  "backend:auth",
+  "auth:backend",
+  "frontend:auth",
+  "auth:frontend",
+]);
+
+// ─── Grade thresholds & recommendations ───────────────
+
+function getGrade(score: number): "S" | "A" | "B" | "C" | "D" | "F" {
+  if (score >= 90) return "S";
+  if (score >= 75) return "A";
+  if (score >= 60) return "B";
+  if (score >= 45) return "C";
+  if (score >= 25) return "D";
+  return "F";
+}
+
+const RECOMMENDATIONS: Record<"S" | "A" | "B" | "C" | "D" | "F", string> = {
+  S: "Excellent combination — these technologies are designed to work together.",
+  A: "Strong pairing with good ecosystem support.",
+  B: "Compatible — works well with minor configuration needed.",
+  C: "Neutral — no known issues but limited synergy.",
+  D: "Weak pairing — consider alternatives.",
+  F: "Incompatible — these technologies conflict.",
+};
+
+// ─── Runtime detection ────────────────────────────────
+
+function getRuntime(tech: Technology): string | null {
+  if (tech.category === "runtime") return tech.id;
+  for (const req of tech.requires) {
+    if (["nodejs", "python", "go", "rust", "php", "bun", "deno"].includes(req)) {
+      return req;
+    }
+  }
+  return null;
+}
+
+// ─── Core scoring ─────────────────────────────────────
+
+/**
+ * Score the compatibility between two technologies (0-100).
+ */
+export function scoreCompatibility(techA: Technology, techB: Technology): CompatibilityResult {
+  const factors: CompatibilityFactor[] = [];
+  let score = 50; // neutral baseline
+
+  // +25 if suggested pairing (either direction)
+  const aSuggestsB = techA.suggestedWith.includes(techB.id);
+  const bSuggestsA = techB.suggestedWith.includes(techA.id);
+  if (aSuggestsB || bSuggestsA) {
+    factors.push({
+      label: "Suggested pairing",
+      points: 25,
+      description:
+        aSuggestsB && bSuggestsA
+          ? `${techA.name} and ${techB.name} mutually recommend each other`
+          : aSuggestsB
+            ? `${techA.name} suggests ${techB.name}`
+            : `${techB.name} suggests ${techA.name}`,
+    });
+    score += 25;
+  }
+
+  // +15 if shared runtime
+  const runtimeA = getRuntime(techA);
+  const runtimeB = getRuntime(techB);
+  if (runtimeA && runtimeB && runtimeA === runtimeB && techA.id !== techB.id) {
+    const runtimeName = runtimeA === "nodejs" ? "Node.js" : runtimeA;
+    factors.push({
+      label: "Shared runtime",
+      points: 15,
+      description: `Both use ${runtimeName}`,
+    });
+    score += 15;
+  }
+
+  // +10 if complementary categories
+  const catPair = `${techA.category}:${techB.category}`;
+  if (COMPLEMENTARY_PAIRS.has(catPair)) {
+    factors.push({
+      label: "Complementary categories",
+      points: 10,
+      description: `${techA.category} + ${techB.category}`,
+    });
+    score += 10;
+  }
+
+  // -50 if incompatible (either direction) — applied after positives, then clamp
+  const aIncompatB = techA.incompatibleWith.includes(techB.id);
+  const bIncompatA = techB.incompatibleWith.includes(techA.id);
+  if (aIncompatB || bIncompatA) {
+    factors.push({
+      label: "Incompatible",
+      points: -50,
+      description:
+        aIncompatB && bIncompatA
+          ? `${techA.name} and ${techB.name} are mutually incompatible`
+          : aIncompatB
+            ? `${techA.name} lists ${techB.name} as incompatible`
+            : `${techB.name} lists ${techA.name} as incompatible`,
+    });
+    score -= 50;
+  }
+
+  // -15 if same category AND same runtime (competing technologies)
+  if (
+    techA.category === techB.category &&
+    techA.id !== techB.id &&
+    runtimeA &&
+    runtimeB &&
+    runtimeA === runtimeB
+  ) {
+    factors.push({
+      label: "Same category and runtime",
+      points: -15,
+      description: `Both are ${techA.category} technologies for ${runtimeA === "nodejs" ? "Node.js" : runtimeA}`,
+    });
+    score -= 15;
+  }
+
+  // -5 if same default port (minor conflict)
+  if (
+    techA.defaultPort &&
+    techB.defaultPort &&
+    techA.defaultPort === techB.defaultPort &&
+    techA.id !== techB.id
+  ) {
+    factors.push({
+      label: "Port conflict",
+      points: -5,
+      description: `Both default to port ${techA.defaultPort}`,
+    });
+    score -= 5;
+  }
+
+  // Clamp
+  score = Math.max(0, Math.min(100, score));
+
+  const grade = getGrade(score);
+
+  return {
+    score,
+    grade,
+    factors,
+    recommendation: RECOMMENDATIONS[grade],
+  };
+}
+
+/**
+ * Score an entire stack by evaluating all unique pairs.
+ */
+export function scoreStack(technologies: Technology[]): StackScoreResult {
+  if (technologies.length < 2) {
+    return { overall: 100, grade: "S", pairs: [] };
+  }
+
+  const pairs: Array<{ a: string; b: string; score: number }> = [];
+
+  for (let i = 0; i < technologies.length; i++) {
+    for (let j = i + 1; j < technologies.length; j++) {
+      const result = scoreCompatibility(technologies[i], technologies[j]);
+      pairs.push({
+        a: technologies[i].id,
+        b: technologies[j].id,
+        score: result.score,
+      });
+    }
+  }
+
+  const overall =
+    pairs.length > 0 ? Math.round(pairs.reduce((sum, p) => sum + p.score, 0) / pairs.length) : 100;
+
+  return {
+    overall,
+    grade: getGrade(overall),
+    pairs,
+  };
+}

package/src/engine/compose-generator.ts

@@ -0,0 +1,134 @@
+/**
+ * Compose Generator — Pure function that generates docker-compose.yml content.
+ * No disk I/O — returns structured data for preview or writing.
+ */
+
+export interface ComposePreviewResult {
+  yaml: string;
+  services: string[];
+  ports: Record<string, number>;
+  volumes: string[];
+}
+
+interface ComposeTechnology {
+  id: string;
+  name: string;
+  category?: string;
+  dockerImage?: string;
+  defaultPort?: number;
+  envVars?: Record<string, string>;
+  healthCheck?: {
+    endpoint?: string;
+    command?: string;
+    interval?: string;
+    timeout?: string;
+    retries?: number;
+  };
+  port?: number; // Override port from stack definition
+}
+
+const DATA_MOUNTS: Record<string, string> = {
+  postgresql: "/var/lib/postgresql/data",
+  mysql: "/var/lib/mysql",
+  mongodb: "/data/db",
+  redis: "/data",
+};
+
+/**
+ * Generate a docker-compose.yml preview from a list of technologies.
+ * Only includes technologies that have a `dockerImage`.
+ */
+export function generateComposePreview(
+  technologies: ComposeTechnology[],
+  projectName: string,
+): ComposePreviewResult {
+  const services: string[] = [];
+  const ports: Record<string, number> = {};
+  const volumes: string[] = [];
+  const lines: string[] = ["services:"];
+
+  const networkName = `${projectName.toLowerCase().replace(/[^a-z0-9-]/g, "-")}_net`;
+
+  for (const tech of technologies) {
+    if (!tech.dockerImage) continue;
+
+    services.push(tech.id);
+    const port = tech.port ?? tech.defaultPort;
+
+    lines.push(`  ${tech.id}:`);
+    lines.push(`    image: ${tech.dockerImage}`);
+    lines.push("    restart: unless-stopped");
+
+    // Ports
+    if (port) {
+      lines.push("    ports:");
+      lines.push(`      - "${port}:${port}"`);
+      ports[tech.id] = port;
+    }
+
+    // Environment variables
+    const envVars = tech.envVars ? Object.entries(tech.envVars) : [];
+    if (envVars.length > 0) {
+      lines.push("    environment:");
+      for (const [key, value] of envVars) {
+        lines.push(`      ${key}: "${value}"`);
+      }
+    }
+
+    // Health check
+    if (tech.healthCheck) {
+      lines.push("    healthcheck:");
+      if (tech.healthCheck.command) {
+        lines.push(`      test: ["CMD-SHELL", "${tech.healthCheck.command}"]`);
+      } else if (tech.healthCheck.endpoint) {
+        lines.push(`      test: ["CMD-SHELL", "curl -f ${tech.healthCheck.endpoint} || exit 1"]`);
+      }
+      if (tech.healthCheck.interval) {
+        lines.push(`      interval: ${tech.healthCheck.interval}`);
+      }
+      if (tech.healthCheck.timeout) {
+        lines.push(`      timeout: ${tech.healthCheck.timeout}`);
+      }
+      if (tech.healthCheck.retries) {
+        lines.push(`      retries: ${tech.healthCheck.retries}`);
+      }
+    }
+
+    // Volumes for databases
+    const mountPath = DATA_MOUNTS[tech.id];
+    if (mountPath && tech.category === "database") {
+      const volName = `${tech.id}_data`;
+      lines.push("    volumes:");
+      lines.push(`      - ${volName}:${mountPath}`);
+      volumes.push(volName);
+    }
+
+    // Network
+    lines.push("    networks:");
+    lines.push(`      - ${networkName}`);
+
+    lines.push("");
+  }
+
+  // Named volumes
+  if (volumes.length > 0) {
+    lines.push("volumes:");
+    for (const vol of volumes) {
+      lines.push(`  ${vol}:`);
+    }
+    lines.push("");
+  }
+
+  // Network
+  lines.push("networks:");
+  lines.push(`  ${networkName}:`);
+  lines.push("    driver: bridge");
+  lines.push("");
+
+  return {
+    yaml: lines.join("\n"),
+    services,
+    ports,
+    volumes,
+  };
+}