@stackweld/core 0.2.0

package/src/engine/stack-engine.ts

@@ -0,0 +1,258 @@
+/**
+ * Stack Engine — CRUD operations for stack definitions.
+ * Handles creation, validation, versioning, and persistence.
+ */
+
+import { randomUUID } from "node:crypto";
+import { getDatabase } from "../db/database.js";
+import type {
+  StackDefinition,
+  StackProfile,
+  StackTechnology,
+  StackVersion,
+  ValidationResult,
+} from "../types/index.js";
+import type { RulesEngine } from "./rules-engine.js";
+
+export class StackEngine {
+  private rules: RulesEngine;
+
+  constructor(rules: RulesEngine) {
+    this.rules = rules;
+  }
+
+  /**
+   * Create a new stack definition.
+   * Validates technologies and auto-resolves dependencies.
+   */
+  create(opts: {
+    name: string;
+    description?: string;
+    profile?: StackProfile;
+    technologies: StackTechnology[];
+    tags?: string[];
+  }): { stack: StackDefinition; validation: ValidationResult } {
+    const validation = this.rules.validate(opts.technologies);
+
+    // Add auto-resolved dependencies
+    const allTechs = [...opts.technologies];
+    for (const depId of validation.resolvedDependencies) {
+      const tech = this.rules.getTechnology(depId);
+      if (tech) {
+        allTechs.push({
+          technologyId: depId,
+          version: tech.defaultVersion,
+          port: validation.portAssignments[depId],
+        });
+      }
+    }
+
+    // Apply port assignments to existing techs
+    for (const t of allTechs) {
+      if (validation.portAssignments[t.technologyId]) {
+        t.port = validation.portAssignments[t.technologyId];
+      }
+    }
+
+    const now = new Date().toISOString();
+    const stack: StackDefinition = {
+      id: randomUUID(),
+      name: opts.name,
+      description: opts.description || "",
+      profile: opts.profile || "standard",
+      technologies: allTechs,
+      createdAt: now,
+      updatedAt: now,
+      version: 1,
+      tags: opts.tags || [],
+    };
+
+    if (validation.valid) {
+      this.persist(stack);
+    }
+
+    return { stack, validation };
+  }
+
+  /**
+   * Get a stack by ID.
+   */
+  get(id: string): StackDefinition | null {
+    const db = getDatabase();
+    const row = db.prepare("SELECT * FROM stacks WHERE id = ?").get(id) as
+      | Record<string, unknown>
+      | undefined;
+    if (!row) return null;
+
+    const techRows = db
+      .prepare("SELECT * FROM stack_technologies WHERE stack_id = ?")
+      .all(id) as Record<string, unknown>[];
+
+    return {
+      id: row.id as string,
+      name: row.name as string,
+      description: row.description as string,
+      profile: row.profile as StackProfile,
+      version: row.version as number,
+      createdAt: row.created_at as string,
+      updatedAt: row.updated_at as string,
+      tags: JSON.parse(row.tags as string),
+      technologies: techRows.map((t) => ({
+        technologyId: t.technology_id as string,
+        version: t.version as string,
+        port: t.port as number | undefined,
+        config: JSON.parse((t.config as string) || "{}"),
+      })),
+    };
+  }
+
+  /**
+   * List all stacks.
+   */
+  list(): StackDefinition[] {
+    const db = getDatabase();
+    const rows = db.prepare("SELECT id FROM stacks ORDER BY updated_at DESC").all() as {
+      id: string;
+    }[];
+    return rows.map((r) => this.get(r.id)!).filter(Boolean);
+  }
+
+  /**
+   * Delete a stack.
+   */
+  delete(id: string): boolean {
+    const db = getDatabase();
+    const result = db.prepare("DELETE FROM stacks WHERE id = ?").run(id);
+    return result.changes > 0;
+  }
+
+  /**
+   * Update a stack. Auto-increments version and saves snapshot.
+   */
+  update(
+    id: string,
+    changes: Partial<
+      Pick<StackDefinition, "name" | "description" | "profile" | "technologies" | "tags">
+    >,
+  ): {
+    stack: StackDefinition;
+    validation: ValidationResult;
+  } | null {
+    const existing = this.get(id);
+    if (!existing) return null;
+
+    const techs = changes.technologies || existing.technologies;
+    const validation = this.rules.validate(techs);
+
+    const now = new Date().toISOString();
+    const newVersion = existing.version + 1;
+
+    const db = getDatabase();
+    db.prepare(`
+      UPDATE stacks SET
+        name = ?, description = ?, profile = ?, version = ?,
+        updated_at = ?, tags = ?
+      WHERE id = ?
+    `).run(
+      changes.name || existing.name,
+      changes.description ?? existing.description,
+      changes.profile || existing.profile,
+      newVersion,
+      now,
+      JSON.stringify(changes.tags || existing.tags),
+      id,
+    );
+
+    // Replace technologies
+    db.prepare("DELETE FROM stack_technologies WHERE stack_id = ?").run(id);
+    for (const t of techs) {
+      db.prepare(`
+        INSERT INTO stack_technologies (stack_id, technology_id, version, port, config)
+        VALUES (?, ?, ?, ?, ?)
+      `).run(id, t.technologyId, t.version, t.port || null, JSON.stringify(t.config || {}));
+    }
+
+    // Save version snapshot
+    const updatedStack = this.get(id)!;
+    this.saveVersionSnapshot(updatedStack, `Updated to v${newVersion}`);
+
+    return { stack: updatedStack, validation };
+  }
+
+  /**
+   * Get version history for a stack.
+   */
+  getVersionHistory(stackId: string): StackVersion[] {
+    const db = getDatabase();
+    const rows = db
+      .prepare("SELECT * FROM stack_versions WHERE stack_id = ? ORDER BY version DESC")
+      .all(stackId) as Record<string, unknown>[];
+
+    return rows.map((r) => ({
+      version: r.version as number,
+      timestamp: r.created_at as string,
+      changelog: r.changelog as string,
+      snapshot: JSON.parse(r.snapshot as string),
+    }));
+  }
+
+  /**
+   * Rollback to a specific version.
+   */
+  rollback(stackId: string, targetVersion: number): StackDefinition | null {
+    const db = getDatabase();
+    const versionRow = db
+      .prepare("SELECT snapshot FROM stack_versions WHERE stack_id = ? AND version = ?")
+      .get(stackId, targetVersion) as { snapshot: string } | undefined;
+
+    if (!versionRow) return null;
+
+    const snapshot = JSON.parse(versionRow.snapshot) as StackDefinition;
+    this.update(stackId, {
+      name: snapshot.name,
+      description: snapshot.description,
+      profile: snapshot.profile,
+      technologies: snapshot.technologies,
+      tags: snapshot.tags,
+    });
+
+    return this.get(stackId);
+  }
+
+  // ─── Private ────────────────────────────────────────────
+
+  private persist(stack: StackDefinition): void {
+    const db = getDatabase();
+
+    db.prepare(`
+      INSERT INTO stacks (id, name, description, profile, version, created_at, updated_at, tags)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      stack.id,
+      stack.name,
+      stack.description,
+      stack.profile,
+      stack.version,
+      stack.createdAt,
+      stack.updatedAt,
+      JSON.stringify(stack.tags),
+    );
+
+    for (const t of stack.technologies) {
+      db.prepare(`
+        INSERT INTO stack_technologies (stack_id, technology_id, version, port, config)
+        VALUES (?, ?, ?, ?, ?)
+      `).run(stack.id, t.technologyId, t.version, t.port || null, JSON.stringify(t.config || {}));
+    }
+
+    this.saveVersionSnapshot(stack, "Initial creation");
+  }
+
+  private saveVersionSnapshot(stack: StackDefinition, changelog: string): void {
+    const db = getDatabase();
+    db.prepare(`
+      INSERT OR REPLACE INTO stack_versions (stack_id, version, changelog, snapshot)
+      VALUES (?, ?, ?, ?)
+    `).run(stack.id, stack.version, changelog, JSON.stringify(stack));
+  }
+}

package/src/engine/stack-serializer.ts

@@ -0,0 +1,95 @@
+/**
+ * Stack Serializer — Compress/decompress stack definitions into URL-safe strings.
+ * Uses zlib deflate + base64url encoding. No server needed.
+ */
+
+import { deflateSync, inflateSync } from "node:zlib";
+
+export interface ShareableStack {
+  name: string;
+  profile: string;
+  technologies: Array<{ id: string; version?: string; port?: number }>;
+}
+
+const DEFAULT_BASE_URL = "https://stackweld.dev/s/#";
+
+/**
+ * Compress a stack into a URL-safe base64 string.
+ * Flow: JSON → deflate → base64url
+ */
+export function serializeStack(stack: ShareableStack): string {
+  const json = JSON.stringify({
+    n: stack.name,
+    p: stack.profile,
+    t: stack.technologies.map((t) => {
+      const entry: Record<string, unknown> = { i: t.id };
+      if (t.version) entry.v = t.version;
+      if (t.port) entry.p = t.port;
+      return entry;
+    }),
+  });
+
+  const compressed = deflateSync(Buffer.from(json, "utf-8"));
+  return toBase64Url(compressed);
+}
+
+/**
+ * Decompress from a base64url string back to a stack definition.
+ * Flow: base64url → inflate → JSON
+ */
+export function deserializeStack(encoded: string): ShareableStack {
+  const buffer = fromBase64Url(encoded);
+  const json = inflateSync(buffer).toString("utf-8");
+
+  const data = JSON.parse(json) as {
+    n: string;
+    p: string;
+    t: Array<{ i: string; v?: string; p?: number }>;
+  };
+
+  return {
+    name: data.n,
+    profile: data.p,
+    technologies: data.t.map((t) => ({
+      id: t.i,
+      version: t.v,
+      port: t.p,
+    })),
+  };
+}
+
+/**
+ * Generate a full shareable URL for a stack.
+ */
+export function generateShareUrl(
+  stack: ShareableStack,
+  baseUrl: string = DEFAULT_BASE_URL,
+): string {
+  return `${baseUrl}${serializeStack(stack)}`;
+}
+
+/**
+ * Extract the encoded payload from a share URL.
+ */
+export function extractFromShareUrl(url: string): string {
+  const hashIndex = url.indexOf("#");
+  if (hashIndex === -1) {
+    throw new Error("Invalid share URL: no hash fragment found.");
+  }
+  return url.substring(hashIndex + 1);
+}
+
+// ─── Base64url helpers ────────────────────────────────
+
+function toBase64Url(buffer: Buffer): string {
+  return buffer.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function fromBase64Url(str: string): Buffer {
+  let base64 = str.replace(/-/g, "+").replace(/_/g, "/");
+  // Add padding
+  const pad = base64.length % 4;
+  if (pad === 2) base64 += "==";
+  else if (pad === 3) base64 += "=";
+  return Buffer.from(base64, "base64");
+}

package/src/engine/standards-linter.ts

@@ -0,0 +1,210 @@
+/**
+ * Stack Standards Linter — Validates stacks against team-defined standards.
+ * Reads .stackweldrc config and checks compliance.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { StackDefinition } from "../types/index.js";
+
+// ─── Types ────────────────────────────────────────────
+
+export interface StackStandards {
+  team?: string;
+  allowedTechnologies?: string[];
+  blockedTechnologies?: string[];
+  requiredTechnologies?: string[];
+  minProfile?: string;
+  requireDocker?: boolean;
+  requireTests?: boolean;
+  requireTypeScript?: boolean;
+  customRules?: Array<{ name: string; check: string; message: string }>;
+}
+
+export interface LintResult {
+  passed: boolean;
+  violations: LintViolation[];
+  warnings: LintWarning[];
+}
+
+export interface LintViolation {
+  rule: string;
+  message: string;
+  severity: "error" | "warning";
+}
+
+export type LintWarning = LintViolation;
+
+// ─── Profile Ordering ─────────────────────────────────
+
+const PROFILE_ORDER: Record<string, number> = {
+  lightweight: 0,
+  rapid: 1,
+  standard: 2,
+  production: 3,
+  enterprise: 4,
+};
+
+function profileLevel(profile: string): number {
+  return PROFILE_ORDER[profile] ?? -1;
+}
+
+// ─── Testing Frameworks ───────────────────────────────
+
+const TESTING_FRAMEWORKS = new Set([
+  "vitest",
+  "jest",
+  "playwright",
+  "cypress",
+  "mocha",
+  "ava",
+  "tap",
+  "pytest",
+  "unittest",
+  "go-test",
+  "cargo-test",
+]);
+
+// ─── Lint Function ────────────────────────────────────
+
+export function lintStack(stack: StackDefinition, standards: StackStandards): LintResult {
+  const violations: LintViolation[] = [];
+  const warnings: LintWarning[] = [];
+
+  const techIds = new Set(stack.technologies.map((t) => t.technologyId));
+
+  // Allowed technologies check
+  if (standards.allowedTechnologies && standards.allowedTechnologies.length > 0) {
+    const allowed = new Set(standards.allowedTechnologies);
+    for (const id of techIds) {
+      if (!allowed.has(id)) {
+        violations.push({
+          rule: "allowedTechnologies",
+          message: `Technology "${id}" is not in the allowed list`,
+          severity: "error",
+        });
+      }
+    }
+  }
+
+  // Blocked technologies check
+  if (standards.blockedTechnologies && standards.blockedTechnologies.length > 0) {
+    for (const blocked of standards.blockedTechnologies) {
+      if (techIds.has(blocked)) {
+        violations.push({
+          rule: "blockedTechnologies",
+          message: `Blocked technology "${blocked}" found — remove it`,
+          severity: "error",
+        });
+      }
+    }
+  }
+
+  // Required technologies check
+  if (standards.requiredTechnologies && standards.requiredTechnologies.length > 0) {
+    for (const required of standards.requiredTechnologies) {
+      if (!techIds.has(required)) {
+        violations.push({
+          rule: "requiredTechnologies",
+          message: `Required technology "${required}" is missing`,
+          severity: "error",
+        });
+      }
+    }
+  }
+
+  // Minimum profile check
+  if (standards.minProfile) {
+    const minLevel = profileLevel(standards.minProfile);
+    const currentLevel = profileLevel(stack.profile);
+    if (minLevel >= 0 && currentLevel < minLevel) {
+      warnings.push({
+        rule: "minProfile",
+        message: `Profile "${stack.profile}" is below minimum "${standards.minProfile}"`,
+        severity: "warning",
+      });
+    }
+  }
+
+  // Require Docker
+  if (standards.requireDocker) {
+    if (!techIds.has("docker") && !techIds.has("docker-compose")) {
+      violations.push({
+        rule: "requireDocker",
+        message: "Docker is required but not present in the stack",
+        severity: "error",
+      });
+    }
+  }
+
+  // Require tests
+  if (standards.requireTests) {
+    const hasTestFramework = Array.from(techIds).some((id) => TESTING_FRAMEWORKS.has(id));
+    if (!hasTestFramework) {
+      warnings.push({
+        rule: "requireTests",
+        message: "No testing framework found (vitest, jest, playwright, cypress, etc.)",
+        severity: "warning",
+      });
+    }
+  }
+
+  // Require TypeScript
+  if (standards.requireTypeScript) {
+    if (!techIds.has("typescript")) {
+      violations.push({
+        rule: "requireTypeScript",
+        message: "TypeScript is required but not present in the stack",
+        severity: "error",
+      });
+    }
+  }
+
+  // Custom rules (simple presence/absence checks)
+  if (standards.customRules) {
+    for (const rule of standards.customRules) {
+      if (rule.check === "present") {
+        if (!techIds.has(rule.name)) {
+          violations.push({
+            rule: `custom:${rule.name}`,
+            message: rule.message,
+            severity: "error",
+          });
+        }
+      } else if (rule.check === "absent") {
+        if (techIds.has(rule.name)) {
+          violations.push({
+            rule: `custom:${rule.name}`,
+            message: rule.message,
+            severity: "error",
+          });
+        }
+      }
+    }
+  }
+
+  const hasErrors = violations.some((v) => v.severity === "error");
+
+  return {
+    passed: !hasErrors,
+    violations,
+    warnings,
+  };
+}
+
+// ─── Config Loader ────────────────────────────────────
+
+export function loadStandards(projectPath: string): StackStandards | null {
+  const configPath = path.resolve(projectPath, ".stackweldrc");
+  if (!fs.existsSync(configPath)) {
+    return null;
+  }
+
+  try {
+    const content = fs.readFileSync(configPath, "utf-8");
+    const parsed = JSON.parse(content) as StackStandards;
+    return parsed;
+  } catch {
+    return null;
+  }
+}