@weebet/spike 0.1.0

package/dist/cli.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { mkdir, copyFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const program = new Command();
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// dist/cli.js -> package root is one level up from dist/
+const packageRoot = path.resolve(__dirname, "..");
+const templatesRoot = path.join(packageRoot, "templates");
+async function exists(filePath) {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function ensureDir(dirPath, dryRun) {
+    if (dryRun)
+        return;
+    await mkdir(dirPath, { recursive: true });
+}
+async function copyTemplateFile(params) {
+    const { from, to, force, dryRun } = params;
+    const targetExists = await exists(to);
+    if (targetExists && !force) {
+        console.log(`⏭️  Skipped (exists): ${path.relative(process.cwd(), to)}`);
+        return;
+    }
+    if (dryRun) {
+        console.log(`🧪 Would write: ${path.relative(process.cwd(), to)}`);
+        return;
+    }
+    await ensureDir(path.dirname(to), dryRun);
+    try {
+        await copyFile(from, to);
+        console.log(`✅ Wrote: ${path.relative(process.cwd(), to)}`);
+    }
+    catch (err) {
+        console.error(`❌ Failed to write: ${path.relative(process.cwd(), to)}`);
+        console.error(err);
+        process.exitCode = 1;
+    }
+}
+async function initCommand(options) {
+    const force = Boolean(options.force);
+    const dryRun = Boolean(options.dryRun);
+    const targetDir = options.dir
+        ? path.resolve(process.cwd(), options.dir)
+        : process.cwd();
+    const plan = [
+        {
+            from: path.join(templatesRoot, "docker-compose.yml"),
+            to: path.join(targetDir, "docker-compose.yml"),
+        },
+        {
+            from: path.join(templatesRoot, ".env.dev"),
+            to: path.join(targetDir, ".env.dev"),
+        },
+        {
+            from: path.join(templatesRoot, "Makefile"),
+            to: path.join(targetDir, "Makefile"),
+        },
+        {
+            from: path.join(templatesRoot, "scripts", "seed.ts"),
+            to: path.join(targetDir, "scripts", "seed.ts"),
+        },
+    ];
+    // sanity check: templates exist inside the installed package
+    const missingTemplates = [];
+    for (const item of plan) {
+        if (!(await exists(item.from)))
+            missingTemplates.push(item.from);
+    }
+    if (missingTemplates.length > 0) {
+        console.error("❌ Missing templates inside package:");
+        for (const p of missingTemplates)
+            console.error("  -", p);
+        process.exit(1);
+    }
+    console.log("🚀 spike init");
+    console.log(`📁 Target: ${targetDir}`);
+    if (dryRun)
+        console.log("🧪 Dry run enabled (no files will be written)");
+    if (force)
+        console.log("⚠️  Force enabled (existing files may be overwritten)");
+    for (const item of plan) {
+        await copyTemplateFile({ ...item, force, dryRun });
+    }
+    console.log("\n🎉 Done. Next steps:");
+    console.log("  1) make help");
+    console.log("  2) make up store=all");
+    console.log("  3) make health");
+    console.log("  4) make seed");
+}
+program
+    .name("spike")
+    .description("Internal devtools scaffolder (docker-compose + Makefile + seed)")
+    .version("0.1.0");
+program
+    .command("init")
+    .description("Copy dev environment templates into the current repo")
+    .option("-f, --force", "overwrite existing files")
+    .option("--dry-run", "print actions without writing files")
+    .option("-d, --dir <path>", "target directory (default: current directory)")
+    .action(initCommand);
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@weebet/spike",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "",
+  "bin": {
+    "weebet-spike": "./dist/cli.js"
+  },
+  "files": ["dist", "templates"],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "commander": "^14.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}

package/templates/.env.dev

@@ -0,0 +1,16 @@
+# Local dev defaults (NO secrets)
+
+# Postgres
+POSTGRES_DB=app_dev
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=postgres
+POSTGRES_PORT=5433
+# POSTGRES_HOST isnt required since we are utilize container
+
+# Connection string the application app can use later (optional but convenient)
+DATABASE_URL=postgresql://postgres:postgres@localhost:5433/app_dev
+
+# Elasticsearch
+ELASTICSEARCH_PORT=9200
+ELASTICSEARCH_URL=http://localhost:9200
+

package/templates/Makefile

@@ -0,0 +1,169 @@
+# Use bash for better scripting support
+SHELL := /bin/bash
+
+# Detect operating system (Darwin = macOS)
+OS := $(shell uname -s)
+
+# Detect docker compose command (v1 vs v2)
+DOCKER_COMPOSE := $(shell \
+	if command -v docker-compose >/dev/null 2>&1; then \
+		echo docker-compose; \
+	else \
+		echo "docker compose"; \
+	fi \
+)
+
+# Declare non-file targets
+.PHONY: help up down reset logs health seed system-deps \
+	_ensure-docker _ensure-colima _start-containers _wait-for-health \
+	_install_logic_macos _install_logic_linux
+
+## ---------------------------
+## Public developer commands
+## ---------------------------
+
+help: ## Show available commands
+	@echo "Available commands:"
+	@echo "  make up [store=postgres|es|all] - Start local dev environment"
+	@echo "  make down                       - Stop local dev environment"
+	@echo "  make reset                      - Tear down and restart with clean volumes"
+	@echo "  make logs                       - Tail logs of all containers"
+	@echo "  make health                     - Check if all services are healthy"
+	@echo "  make seed                       - Populate local dev data"
+	@echo "  make system-deps                - Install required system dependencies"
+
+up: _ensure-docker ## Start local dev environment
+	@echo "🚀 Starting local development environment..."
+	@if [ "$(OS)" = "Darwin" ]; then $(MAKE) _ensure-colima; fi
+	@$(MAKE) _start-containers
+	@$(MAKE) _wait-for-health
+	@echo "🎉 Local development environment is ready!"
+
+down: ## Stop containers and Colima
+	@echo "🛑 Stopping local dev environment..."
+	@$(DOCKER_COMPOSE) down
+	@if [ "$(OS)" = "Darwin" ]; then colima stop; fi
+
+reset: ## Reset containers and volumes
+	@echo "♻️ Resetting local dev environment..."
+	@$(DOCKER_COMPOSE) --env-file .env.dev down -v
+	@$(MAKE) up
+
+logs: ## Tail container logs
+	@echo "📜 Tailing container logs..."
+	@$(DOCKER_COMPOSE) logs -f
+
+seed: ## Seed development data
+	@echo "🌱 Seeding data for $(store)..."
+	@if [ "$(store)" = "postgres" ]; then \
+		$(DOCKER_COMPOSE) --env-file .env.dev run --rm seed npm run seed:postgres; \
+	elif [ "$(store)" = "es" ]; then \
+		$(DOCKER_COMPOSE) --env-file .env.dev run --rm seed npm run seed:es; \
+	else \
+		$(DOCKER_COMPOSE) --env-file .env.dev run --rm seed npm run seed; \
+	fi
+
+## ---------------------------
+## Health & readiness
+## ---------------------------
+
+_wait-for-health:
+	@echo "⏳ Waiting for services to become healthy..."
+	@$(MAKE) health
+
+health: ## Check service health via service-level probes
+	@echo "🔎 Checking health status..."
+
+	@# --- Postgres ---
+	@if $(DOCKER_COMPOSE) ps -q postgres >/dev/null 2>&1; then \
+		echo "🐘 Checking Postgres..."; \
+		until $(DOCKER_COMPOSE) exec postgres pg_isready >/dev/null 2>&1; do \
+			echo "  ⏳ Postgres is starting..."; \
+			sleep 2; \
+		done; \
+		echo "  ✅ Postgres is healthy"; \
+	fi
+
+	@# --- Elasticsearch ---
+	@if $(DOCKER_COMPOSE) ps -q elasticsearch >/dev/null 2>&1; then \
+		echo "🔍 Checking Elasticsearch..."; \
+		until curl -s http://localhost:9200/_cluster/health >/dev/null; do \
+			echo "  ⏳ Elasticsearch is starting..."; \
+			sleep 2; \
+		done; \
+		echo "  ✅ Elasticsearch is healthy"; \
+	fi
+
+## ---------------------------
+## Internal helper targets
+## ---------------------------
+
+_ensure-docker:
+	@echo "🐳 Checking Docker availability..."
+	@command -v docker >/dev/null 2>&1 || \
+		(echo "❌ Docker not found. 👉 Run: make system-deps"; exit 1)
+
+_ensure-colima:
+	@echo "🖥️  Ensuring Colima is running..."
+	@colima status >/dev/null 2>&1 || \
+		(echo "🔄 Starting Colima..." && colima start)
+
+_start-containers:
+	@echo "📦 Starting containers..."
+	@if [ "$(store)" = "postgres" ]; then \
+		$(DOCKER_COMPOSE) --env-file .env.dev up -d postgres; \
+	elif [ "$(store)" = "elasticsearch" ] || [ "$(store)" = "es" ]; then \
+		$(DOCKER_COMPOSE) --env-file .env.dev up -d elasticsearch; \
+	else \
+		$(DOCKER_COMPOSE) --env-file .env.dev up -d; \
+	fi
+
+## ---------------------------
+## System dependency setup
+## ---------------------------
+
+system-deps: ## Install required system dependencies
+	@echo "🔍 Detecting OS..."
+	@case "$(OS)" in \
+		"Darwin") \
+			echo "🍎 macOS detected"; \
+			$(MAKE) _install_logic_macos ;; \
+		"Linux") \
+			echo "🐧 Linux detected"; \
+			$(MAKE) _install_logic_linux ;; \
+		*) \
+			echo "🪟 Windows/WSL detected"; \
+			echo "👉 Search: 'install docker on windows wsl2'"; \
+			exit 1 ;; \
+	esac
+
+_install_logic_macos:
+	@echo "🔍 Checking dependencies (brew, docker, colima)..."
+	@HAS_BREW=$$(command -v brew >/dev/null 2>&1 && echo 1 || echo 0); \
+	HAS_DOCKER=$$(command -v docker >/dev/null 2>&1 && echo 1 || echo 0); \
+	HAS_COLIMA=$$(command -v colima >/dev/null 2>&1 && echo 1 || echo 0); \
+	if [ $$HAS_BREW -eq 1 ] && [ $$HAS_DOCKER -eq 1 ] && [ $$HAS_COLIMA -eq 1 ]; then \
+		echo "✅ All dependencies already installed"; exit 0; \
+	fi; \
+	echo "👉 Search: 'install docker on macos'"; \
+	echo "👉 Search: 'install colima macos'"; \
+	read -p "❓ Attempt automatic installation via Homebrew? (y/n) " yn; \
+	if [ "$$yn" = "y" ]; then \
+		if [ $$HAS_BREW -eq 0 ]; then /bin/bash -c "$$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" || exit 1; fi; \
+		if [ $$HAS_DOCKER -eq 0 ]; then brew install docker || exit 1; fi; \
+		if [ $$HAS_COLIMA -eq 0 ]; then brew install colima || exit 1; fi; \
+		echo "✅ Installation successful"; \
+	else \
+		echo "❌ Installation aborted"; exit 1; \
+	fi
+
+_install_logic_linux:
+	@if command -v docker >/dev/null 2>&1; then \
+		echo "✅ Docker already installed"; \
+	else \
+		echo "👉 Search: 'install docker on linux'"; \
+		read -p "❓ Attempt installation via get.docker.com? (y/n) " yn; \
+		if [ "$$yn" = "y" ]; then \
+			curl -fsSL https://get.docker.com | sh || exit 1; \
+		fi; \
+	fi

package/templates/docker-compose.yml

@@ -0,0 +1,83 @@
+services:
+  postgres:
+    image: postgres:16-alpine
+    restart: unless-stopped
+
+    # Loads defaults from .env.dev (Whne you run: docker compose --env-file .env.dev ....)
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+      POSTGRES_DB: ${POSTGRES_DB}
+
+    ports:
+      - "${POSTGRES_PORT:-5433}:5432"
+
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+    # Required healthcheck: pg_isready
+    healthcheck:
+      test:
+        [
+          "CMD-SHELL",
+          "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB} -h 127.0.0.1 -p 5432",
+        ]
+      interval: 5s
+      timeout: 3s
+      retries: 20
+      start_period: 10s
+
+  elasticsearch:
+    image: docker.elastic.co/elasticsearch/elasticsearch:8.13.4
+    restart: unless-stopped
+
+    environment:
+      - discovery.type=single-node
+      - xpack.security.enabled=false
+      - ES_JAVA_OPTS=-Xms512m -Xmx512m
+
+    ports:
+      - "${ELASTICSEARCH_PORT:-9200}:9200"
+      - "9300:9300"
+
+    volumes:
+      - elasticsearch_data:/usr/share/elasticsearch/data
+
+    # Useful for ES stability on Linux; harmless elsewhere
+    ulimits:
+      memlock:
+        soft: -1
+        hard: -1
+
+    # Required healthcheck: curl http://localhost:9200/_cluster/health
+    healthcheck:
+      test:
+        [
+          "CMD-SHELL",
+          "curl -fsS http://127.0.0.1:9200/_cluster/health?wait_for_status=yellow&timeout=5s > /dev/null || exit 1",
+        ]
+      interval: 5s
+      timeout: 5s
+      retries: 30
+      start_period: 20s
+
+  seed:
+    image: node:20-alpine
+    container_name: dev-seed
+    working_dir: /app
+    volumes:
+      - .:/app
+    env_file:
+      - .env.dev
+    environment:
+      POSTGRES_HOST: postgres
+
+    depends_on:
+      postgres:
+        condition: service_healthy
+      elasticsearch:
+        condition: service_healthy
+
+volumes:
+  postgres_data:
+  elasticsearch_data:

package/templates/scripts/seed.ts

@@ -0,0 +1,293 @@
+import { Pool } from "pg";
+import dotenv from "dotenv";
+import path from "path";
+import { fileURLToPath } from "url";
+
+// Get the directory of the current file
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Load .env.dev from the project root
+dotenv.config({ path: path.join(__dirname, "../.env.dev") });
+
+// ========== SEED DATA Objects ==========
+
+interface UserData {
+  id: string;
+  name: string;
+  email: string;
+  password: string;
+  created_at: Date;
+}
+
+interface ConversationData {
+  id: string;
+  user_id: string;
+  title: string;
+  created_at: Date;
+  updated_at: Date;
+}
+
+interface MessageData {
+  id: string;
+  conversation_id: string;
+  user_id: string;
+  content: string;
+  role: string;
+  created_at: Date;
+}
+
+interface MessageDataList extends Array<MessageData> {}
+
+// create a postgres database connection pool
+const PostgresDatabasePool = {
+  user: process.env["POSTGRES_USER"],
+  password: process.env["POSTGRES_PASSWORD"],
+  port:
+    process.env["POSTGRES_HOST"] === "postgres"
+      ? 5432
+      : parseInt(process.env["POSTGRES_PORT"] || "5432"),
+  database: process.env["POSTGRES_DB"],
+  host: process.env["POSTGRES_HOST"] || "localhost",
+};
+
+console.log("📊 Database config:", PostgresDatabasePool);
+
+const pool = new Pool(PostgresDatabasePool);
+
+// ========== MIGRATION FUNCTIONS ==========
+async function runMigrations(): Promise<void> {
+  log("🔄", "Running database migrations...");
+
+  const createTablesSQL = `
+    -- Create users table
+    CREATE TABLE IF NOT EXISTS users (
+      id VARCHAR(255) PRIMARY KEY,
+      email VARCHAR(255) UNIQUE NOT NULL,
+      password VARCHAR(255) NOT NULL,
+      name VARCHAR(255) NOT NULL,
+      created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+    );
+
+    -- Create conversations table
+    CREATE TABLE IF NOT EXISTS conversations (
+      id VARCHAR(255) PRIMARY KEY,
+      user_id VARCHAR(255) NOT NULL REFERENCES users(id),
+      title VARCHAR(255) NOT NULL,
+      created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+    );
+
+    -- Create messages table
+    CREATE TABLE IF NOT EXISTS messages (
+      id VARCHAR(255) PRIMARY KEY,
+      conversation_id VARCHAR(255) NOT NULL REFERENCES conversations(id),
+      user_id VARCHAR(255) NOT NULL REFERENCES users(id),
+      content TEXT NOT NULL,
+      role VARCHAR(50) NOT NULL,
+      created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+    );
+  `;
+
+  try {
+    await pool.query(createTablesSQL);
+    log("✅", "Migrations completed successfully");
+  } catch (error) {
+    await logError(error as Error, "runMigrations");
+    throw error;
+  }
+}
+
+// ========== HELPER FUNCTIONS ==========
+async function userExists(email: string): Promise<boolean> {
+  // this function checks if user data is already exists
+  const result = await pool.query(
+    "SELECT COUNT(*) FROM users WHERE email = $1",
+    [email],
+  );
+  return parseInt(result.rows[0].count) > 0;
+}
+
+function log(emoji: string, message: string): void {
+  // this function displays output friendly and scannable
+  console.log(`${emoji} ${message}`);
+}
+
+async function logError(error: Error, context: string): Promise<void> {
+  // this function provides consistent error logging
+  console.error(`❌ Error in ${context}:`, error.message);
+}
+
+// ========== SEED DATA ==========
+const sampleUserData: UserData = {
+  id: "user-001",
+  email: "dev@example.com",
+  password: "devpass123", // In production, this would be hashed
+  name: "Dev User",
+  created_at: new Date("2024-01-01T08:00:00Z"),
+};
+
+const sampleConversationData: ConversationData = {
+  id: "conv-001",
+  user_id: "user-001",
+  title: "Getting Started guide",
+  created_at: new Date("2024-01-01T10:00:00"),
+  updated_at: new Date("2024-01-01T10:30:00"),
+};
+
+const sampleMessages: MessageDataList = [
+  {
+    id: "msg-001",
+    conversation_id: "conv-001",
+    user_id: "user-001",
+    content: "Hello! How do I get started?",
+    role: "user",
+    created_at: new Date("2024-01-01T10:00:00"),
+  },
+  {
+    id: "msg-002",
+    conversation_id: "conv-001",
+    user_id: "user-001",
+    content: "Welcome! Here are the first steps",
+    role: "assistant",
+    created_at: new Date("2024-01-01T10:05:00"),
+  },
+];
+
+// ========== SEED FUNCTIONS ==========
+async function seedUsers(): Promise<void> {
+  log("🌱", "Seeding users...");
+
+  // Check if user already exists (idempotency)
+  const exists = await userExists(sampleUserData.email);
+  if (exists) {
+    log("⏭️", `User ${sampleUserData.email} already exists, skipping`);
+    return;
+  }
+
+  // Insert the user
+  const query = `
+    INSERT INTO users (id, email, password, name, created_at)
+    VALUES ($1, $2, $3, $4, $5)
+    ON CONFLICT (email) DO NOTHING
+  `;
+
+  try {
+    await pool.query(query, [
+      sampleUserData.id,
+      sampleUserData.email,
+      sampleUserData.password,
+      sampleUserData.name,
+      sampleUserData.created_at,
+    ]);
+    log("✅", `Created user: ${sampleUserData.email}`);
+  } catch (error) {
+    await logError(error as Error, "seedUsers");
+  }
+}
+
+async function seedConversations(): Promise<void> {
+  log("🌱", "Seeding conversations...");
+
+  // Check if conversation already exists
+  const existsResult = await pool.query(
+    "SELECT COUNT(*) FROM conversations WHERE id = $1",
+    [sampleConversationData.id],
+  );
+
+  if (parseInt(existsResult.rows[0].count) > 0) {
+    log("⏭️", "Sample conversation already exists, skipping");
+    return;
+  }
+
+  // Insert conversation
+  const insertQuery = `
+    INSERT INTO conversations (id, user_id, title, created_at, updated_at)
+    VALUES ($1, $2, $3, $4, $5)
+  `;
+
+  try {
+    await pool.query(insertQuery, [
+      sampleConversationData.id,
+      sampleConversationData.user_id,
+      sampleConversationData.title,
+      sampleConversationData.created_at,
+      sampleConversationData.updated_at,
+    ]);
+    log("✅", "Sample conversation created");
+  } catch (error) {
+    await logError(error as Error, "seedConversations");
+  }
+}
+
+async function seedMessages(): Promise<void> {
+  log("🌱", "Seeding messages...");
+  let createdCount = 0;
+
+  for (const message of sampleMessages) {
+    // Check if message already exists
+    const existsResult = await pool.query(
+      "SELECT COUNT(*) FROM messages WHERE id = $1",
+      [message.id],
+    );
+
+    if (parseInt(existsResult.rows[0].count) > 0) {
+      log("⏭️", `Message ${message.id} already exists, skipping`);
+      continue;
+    }
+
+    // Insert message
+    const insertQuery = `
+      INSERT INTO messages (id, conversation_id, user_id, content, role, created_at)
+      VALUES ($1, $2, $3, $4, $5, $6)
+    `;
+
+    try {
+      await pool.query(insertQuery, [
+        message.id,
+        message.conversation_id,
+        message.user_id,
+        message.content,
+        message.role,
+        message.created_at,
+      ]);
+      createdCount++;
+    } catch (error) {
+      await logError(error as Error, `seedMessages for ${message.id}`);
+    }
+    log("✅", `Messages seeded: ${createdCount} created`);
+  }
+
+  log("✅", `All messages created (${sampleMessages.length} total)`);
+}
+
+// Orchestrate all seeding
+async function seedDatabase(): Promise<void> {
+  try {
+    log("🚀", "Starting database seeding...");
+    log(
+      "📊",
+      `Connecting to ${PostgresDatabasePool.host}:${PostgresDatabasePool.port}/${PostgresDatabasePool.database}`,
+    );
+
+    // Run migrations first
+    await runMigrations();
+
+    // Run seeds in order (respecting foreign key dependencies)
+    await seedUsers();
+    await seedConversations();
+    await seedMessages();
+
+    log("✨", "Database migration and seeding complete!");
+    process.exit(0);
+  } catch (error) {
+    log("❌", "Seeding failed!");
+    console.error(error);
+    process.exit(1);
+  } finally {
+    // Always close the database connection
+    await pool.end();
+  }
+}
+
+seedDatabase();