@weebet/spike 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,214 @@
+# `@weebet/spike`
+
+Internal development scaffolding CLI.
+Standardizes infrastructure bootstrapping across services at Weebet.io
+
+## Overview
+
+`@weebet/spike`is a lightweight, extensible CLI that standardizes development environments across repositories
+
+It allows teams to:
+
+- Initialize a repo with approved baseline tooling
+- Add infrastructure components (Postgres, Elasticsearch, etc.)
+- Enforce consistent Docker, Makefile, and environment setups
+- Scaffold services across multiple languages (Node, Python, Go, Rust)
+- Integrate with private registries (GitHub Packages / Artifactory)
+
+This eliminates configuration drift and reduces onboarding friction.
+
+**Why `@weebet/spike` Exists**
+As weebet scales we need:
+
+- Centralized tooling
+- Reproducible dev environments
+- Cross-service consistency
+- Registry independence
+- Multi-language compatibility
+
+`@weebet/spike` ensures every service follows the same standards.
+
+## Installation
+
+Public (npm)
+
+```
+npm install @weebet/spike
+```
+
+Install globally
+
+```
+npm install -g @weebet/spike
+```
+
+## Usage
+
+**Internalize dev environment**
+
+```
+npx weebet-spike init
+```
+
+**Creates**
+
+```
+docker-compose.yml
+.env.dev
+Makefile
+/scripts/seed.ts
+```
+
+## Files Installed
+
+| File                | Purpose                                      |
+| ------------------- | -------------------------------------------- |
+| docker-composed.yml | Standard Postgres + Elasticsearch containers |
+| .env.dev            | Development environment variables            |
+| Makefile            | Development commands abstraction             |
+| scripts/seeds.ts    | Seed entry point                             |
+
+## Architecture Overview
+
+`@weebet/spike` follows a template-driven architecture.
+
+```
+                    ┌────────────────────┐
+                    │  User runs CLI     │
+                    │  spike init        │
+                    └─────────┬──────────┘
+                              │
+                              ▼
+                   ┌─────────────────────┐
+                   │  Commander Router   │
+                   │  (Command parsing)  │
+                   └─────────┬───────────┘
+                             │
+                             ▼
+                  ┌──────────────────────┐
+                  │  initCommand()       │
+                  │  Build file plan     │
+                  └─────────┬────────────┘
+                            │
+                            ▼
+              ┌────────────────────────────┐
+              │ Template Resolver           │
+              │ (dist → package root)       │
+              └─────────┬──────────────────┘
+                        │
+                        ▼
+              ┌────────────────────────────┐
+              │ Safe Copy Engine           │
+              │ - check exists             │
+              │ - dry-run mode             │
+              │ - force overwrite          │
+              └─────────┬──────────────────┘
+                        │
+                        ▼
+              ┌────────────────────────────┐
+              │ Project Directory          │
+              │ docker-compose.yml         │
+              │ Makefile                   │
+              │ .env.dev                   │
+              └────────────────────────────┘
+```
+
+## Infrastructure Standards
+
+Every generated service includes
+
+### Postgres
+
+- Version pinned (e.g, `postgres:16-alpine`)
+- Configurable port mapping
+- Healthcheck via `pg_isready``
+- Named volume
+
+### Elasticsearch
+
+- Single-node dev cluster
+- Memory limited config
+- Health endpoint validation
+
+## Makefile Commands
+
+| Command                  | Description                      |
+| ------------------------ | -------------------------------- |
+| `make help `             | Display available commands       |
+| `make system-deps`       | Install Docker/Colima (OS-aware) |
+| `make up store=all`      | Start Postgres + Elsaticsearch   |
+| `make up store=postgres` | Start Postgres only              |
+| `make up store=es`       | Start Elastic only               |
+| `make health`            | Block until services healthy     |
+| `make seed`              | Run database seed                |
+| `make logs`              | Tail logs                        |
+| `make reset`             | Destroy volumes and restart      |
+| `make down`              | Stop containers                  |
+
+## How it Works
+
+- CLI copies version-controlled templates into your repo.
+- Docker Compose defines infrastructure.
+- Makefile wraps Docker commands for a consistent interface.
+- Health checks block until services are ready.
+- Seed script initializes data safely.
+
+## Security & Compliance
+
+- `.env.dev`contains no secrets
+- Intended for local development only
+- Private package restricted to org members
+- No production credentials included
+
+## Versioning Policy
+
+Follows Semantic Versioning:
+
+- **Patch** -> Bug fixes
+- **Minor** -> New features
+- **Major** -> Breaking changes
+
+## Future Roadmap
+
+`@weebet/spike`is not limited to Node services.
+
+Planned and supported scafolds:
+| Language | Support |
+| -------- | ------- |
+| Node | Full support |
+| Python | uvx / uv setup |
+| Go | Module bootsrap |
+| Rust | Cargo-based scafollding |
+
+---
+
+Registry abstraction (GitHub Packages)
+`@weebet/spike`is registry-agnostic.
+
+Supported backedns:
+
+- GitHub Packages
+- Artifactory
+- Local Adapter
+
+Future design includes a registry abstraction layer:
+
+```
+        Spike CLI
+             │
+     Registry Adapter Interface
+        ├── GitHub Adapter
+        ├── Artifactory Adapter
+        └── Local Adapter
+```
+
+This enables:
+
+- Centralized publishing
+- Cross-language package distribution
+- Token-based CI publishing
+- Scoped package governance
+
+## Maintained By
+
+Weebet.io

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@weebet/spike",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "",
   "bin": {
     "weebet-spike": "./dist/cli.js"
   },
-  "files": ["dist", "templates"],
+  "files": [
+    "dist",
+    "templates"
+  ],
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
     "build": "tsc -p tsconfig.json",
@@ -17,6 +20,7 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
+    "@weebet/spike": "^0.1.0",
     "commander": "^14.0.3"
   },
   "devDependencies": {

package/templates/Makefile

@@ -24,6 +24,7 @@ DOCKER_COMPOSE := $(shell \
 
 help: ## Show available commands
 	@echo "Available commands:"
+	@echo "  make help 			  - Show 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"