workspai 0.43.0

package/templates/generator.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+/**
+ * Workspai Project Generator
+ * This script is called by the Workspai CLI to generate projects
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const { execSync } = require('child_process');
+
+const TEMPLATES_DIR = path.join(__dirname, 'templates');
+
+async function generateProject(projectPath, template, useDefaults, skipGit, skipInstall) {
+  const projectName = path.basename(projectPath);
+  const templateDir = template === 'nestjs' ? 'nestjs-standard' : 'fastapi-standard';
+  const templatePath = path.join(TEMPLATES_DIR, templateDir);
+
+  // Check template exists
+  try {
+    await fs.access(templatePath);
+  } catch {
+    console.error('❌ Template not found:', templateDir);
+    process.exit(1);
+  }
+
+  // Create project directory
+  await fs.mkdir(projectPath, { recursive: true });
+
+  // Build context
+  const context = {
+    project_name: template === 'nestjs' 
+      ? projectName.replace(/_/g, '-').toLowerCase() 
+      : projectName.replace(/-/g, '_').toLowerCase(),
+    author: process.env.USER || 'Workspai User',
+    description: template === 'nestjs' 
+      ? 'NestJS application generated with Workspai'
+      : 'FastAPI service generated with Workspai',
+    app_version: '0.1.0',
+    license: 'MIT',
+    package_manager: 'npm',
+    created_at: new Date().toISOString(),
+    rapidkit_version: require('./config.json').rapidkit_version || '0.12.0',
+  };
+
+  // Copy and render template files
+  await copyTemplateDir(templatePath, projectPath, context);
+
+  console.log('✅ Project files created!');
+
+  // Git initialization
+  if (!skipGit) {
+    try {
+      execSync('git init', { cwd: projectPath, stdio: 'pipe' });
+      execSync('git add .', { cwd: projectPath, stdio: 'pipe' });
+      const commitMsg = 'Initial commit: ' + (template === 'nestjs' ? 'NestJS' : 'FastAPI') + ' project via Workspai';
+      execSync(`git commit -m "${commitMsg}"`, { cwd: projectPath, stdio: 'pipe' });
+      console.log('✅ Git repository initialized');
+    } catch (e) {
+      console.log('⚠️  Could not initialize git');
+    }
+  }
+
+  // Install dependencies
+  if (!skipInstall) {
+    if (template === 'nestjs') {
+      console.log('📦 Installing dependencies...');
+      try {
+        execSync('npm install', { cwd: projectPath, stdio: 'inherit' });
+        console.log('✅ Dependencies installed');
+      } catch {
+        console.log('⚠️  Could not install dependencies. Run npm install manually.');
+      }
+    }
+  }
+
+  // Success message
+  const templateName = template === 'nestjs' ? 'NestJS' : 'FastAPI';
+  console.log('');
+  console.log('✨ ' + templateName + ' project created successfully!');
+  console.log('');
+  console.log('🚀 Get started:');
+  console.log('  cd ' + projectName);
+  if (template === 'fastapi') {
+    console.log('  workspai init    # poetry install');
+    console.log('  workspai dev     # Start dev server');
+  } else {
+    if (skipInstall) {
+      console.log('  workspai init    # npm install');
+    }
+    console.log('  cp .env.example .env');
+    console.log('  workspai dev     # Start dev server');
+  }
+  console.log('');
+}
+
+function renderTemplate(content, context) {
+  let result = content;
+  
+  for (const [key, value] of Object.entries(context)) {
+    // Simple variable replacement: {{ key }}
+    const simpleRegex = new RegExp(`\\{\\{\\s*${key}\\s*\\}\\}`, 'g');
+    result = result.replace(simpleRegex, String(value));
+    
+    // With replace filter: {{ key | replace('a', 'b') }}
+    const replaceRegex = new RegExp(
+      `\\{\\{\\s*${key}\\s*\\|\\s*replace\\s*\\(\\s*['"]([^'"]+)['"]\\s*,\\s*['"]([^'"]*)['"]\\s*\\)\\s*\\}\\}`,
+      'g'
+    );
+    result = result.replace(replaceRegex, (match, from, to) => {
+      return String(value).replace(new RegExp(from, 'g'), to);
+    });
+    
+    // With lower filter: {{ key | lower }}
+    const lowerRegex = new RegExp(`\\{\\{\\s*${key}\\s*\\|\\s*lower\\s*\\}\\}`, 'g');
+    result = result.replace(lowerRegex, String(value).toLowerCase());
+    
+    // Combined: {{ key | replace('a', 'b') | lower }}
+    const combinedRegex = new RegExp(
+      `\\{\\{\\s*${key}\\s*\\|\\s*replace\\s*\\(\\s*['"]([^'"]+)['"]\\s*,\\s*['"]([^'"]*)['"]\\s*\\)\\s*\\|\\s*lower\\s*\\}\\}`,
+      'g'
+    );
+    result = result.replace(combinedRegex, (match, from, to) => {
+      return String(value).replace(new RegExp(from, 'g'), to).toLowerCase();
+    });
+  }
+  
+  return result;
+}
+
+async function copyTemplateDir(src, dest, context) {
+  const entries = await fs.readdir(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destName = entry.name.replace(/\.j2$/, '');
+    const destPath = path.join(dest, destName);
+
+    if (entry.isDirectory()) {
+      await fs.mkdir(destPath, { recursive: true });
+      await copyTemplateDir(srcPath, destPath, context);
+    } else {
+      let content = await fs.readFile(srcPath, 'utf-8');
+
+      // Render template if it's a .j2 file
+      if (entry.name.endsWith('.j2')) {
+        content = renderTemplate(content, context);
+      }
+
+      await fs.writeFile(destPath, content);
+
+      // Make scripts executable
+      if (
+        destName === 'rapidkit' ||
+        (destName.endsWith('.py') &&
+          (destPath.includes('.workspai') || destPath.includes('.rapidkit')))
+      ) {
+        await fs.chmod(destPath, 0o755);
+      }
+    }
+  }
+}
+
+// Main
+const args = process.argv.slice(2);
+const projectPath = args[0];
+const template = args[1] || 'fastapi';
+const useDefaults = args.includes('--yes');
+const skipGit = args.includes('--skip-git');
+const skipInstall = args.includes('--skip-install');
+
+if (!projectPath) {
+  console.error('Usage: node generator.js <project-path> <template> [--yes] [--skip-git] [--skip-install]');
+  process.exit(1);
+}
+
+generateProject(projectPath, template, useDefaults, skipGit, skipInstall).catch(err => {
+  console.error('Error:', err);
+  process.exit(1);
+});

package/templates/kits/fastapi-ddd/README.md.j2

@@ -0,0 +1,117 @@
+# {{ project_name }}
+
+Domain-driven FastAPI service generated with Workspai. Python-backed module commands use [RapidKit Core](https://github.com/rapidkitlabs/rapidkit-core).
+
+## Quick start
+
+```bash
+# Bootstrap dependencies (creates .venv + installs Poetry deps)
+npx workspai init  # use make init if you prefer a Make target
+
+# Copy env templates and install hooks/tooling
+./bootstrap.sh
+
+# Type-check, lint, and test
+make lint
+make typecheck
+make test
+
+# Run the service
+make dev
+
+# Use the project-local RapidKit Core helpers when you prefer auto-detected environments
+npx workspai dev
+npx workspai lint
+npx workspai test
+
+# Run supply-chain and dependency audits
+make audit
+```
+
+> Re-run `npx workspai init` (or `make init`) when dependencies change. If you only need to refresh tooling/hooks, run `SKIP_INIT=1 make install` or rely on `./bootstrap.sh`.
+
+> Lockfiles are generated automatically during scaffolding. Set `RAPIDKIT_SKIP_LOCKS=1` (or `RAPIDKIT_GENERATE_LOCKS=0`) before running `workspai create` if you want to skip the lockfile attempt.
+
+> Need to see every project-local RapidKit Core command? Run `rapidkit --help` when RapidKit Core is installed, or use `npx workspai --help` for workspace-level commands.
+
+## Project structure
+
+```
+src/
+  app/
+    application/   # Use cases and service contracts
+    domain/        # Aggregates, entities, and value objects
+    infrastructure/ # Adapters and repositories
+    presentation/  # API routers and dependencies
+    shared/        # Cross-cutting primitives (Result, types, etc.)
+  routing/         # Glue for module-provided routers
+  modules/         # RapidKit Core module bootstrapping
+```
+
+## Layer overview
+
+- **Domain** – Pure business rules (`src/app/domain`).
+- **Application** – Orchestrates use-cases and enforces boundaries (`src/app/application`).
+- **Infrastructure** – Implements gateways and repositories (`src/app/infrastructure`).
+- **Presentation** – Exposes the API using FastAPI (`src/app/presentation`).
+
+Modules added via `rapidkit add module ...` integrate automatically using the preserved
+injection anchors inside `src/main.py` and `src/routing/__init__.py`.
+
+## Example feature
+
+An in-memory notes module is included under `/api/examples/notes` to demonstrate how the domain, application, infrastructure, and presentation layers collaborate:
+
+```bash
+# Create a note
+curl -s -X POST http://localhost:8000/api/examples/notes \
+  -H "Content-Type: application/json" \
+  -d '{"title":"design","body":"Describe your bounded context here."}'
+
+# Retrieve the newly created note
+curl -s http://localhost:8000/api/examples/notes/1 | jq
+```
+
+Swap the in-memory repository with a RapidKit Core database module when you are ready for persistence.
+
+## Deployment
+
+- `Dockerfile` packages the service for container hosting with production-ready defaults.
+- `docker-compose.yml` provisions the FastAPI app plus dependencies (for example PostgreSQL) for local production parity.
+- Run `docker compose up --build` to start the stack; copy `.env.example` to `.env` to configure credentials before deploying.
+- CI/CD workflows under `.github/workflows/` demonstrate automated deployment pipelines.
+
+## Testing
+
+```bash
+npx workspai test
+```
+
+The scaffold ships with a smoke test (`tests/test_app_factory.py`) that validates the
+health endpoint and the application factory.
+
+---
+
+## Local development
+
+- `npx workspai init` bootstraps dependencies via the project-aware CLI.
+- `make init` is an optional alias for `npx workspai init` when you prefer Make targets.
+- `make install` re-runs `npx workspai init` unless `SKIP_INIT=1` is set and refreshes developer tooling such as pre-commit hooks.
+- `./bootstrap.sh` copies `.env.example` to `.env` (when missing) and runs `SKIP_INIT=1 make install` for you.
+- `make dev` or `npx workspai dev` starts the FastAPI server with hot-reload and ensures environment variables from `.env` are loaded.
+- `make lint`, `make typecheck`, and `make test` (or `npx workspai lint` / `npx workspai test`) are thin wrappers around Ruff, mypy, and pytest for consistent CI parity.
+- `make audit` runs `pip-audit` and `npm audit` to surface vulnerable dependencies early.
+
+Pre-commit is configured with Ruff, Black, mypy, and hygiene hooks; `./bootstrap.sh` installs them automatically (or run `SKIP_INIT=1 make install`). Use the project-local launcher variants when you need auto-discovery of the right virtual environment inside automation scripts.
+
+<!-- <<<inject:module-snippet>>> -->
+
+## 📄 License
+
+This project is licensed under the **{{ license }}** License - see the `LICENSE` file included at the project root for details.
+
+## 🔒 Security & secrets
+
+- Copy `.env.example` to `.env` and populate secrets (`SECRET_KEY`, DB credentials, etc.) before deploying.
+- **Do not** commit real secrets or `.env` to git; `.gitignore` already contains `.env` to protect accidental commits.
+- For production, tighten CORS and allowed hosts rather than using wildcard settings provided for convenience in dev.

package/templates/kits/fastapi-ddd/common/env.example.j2

@@ -0,0 +1,10 @@
+# Workspai environment defaults
+PROJECT_NAME="{{ project_name | default('workspai-app') }}"
+ENV="development"
+DEBUG="true"
+APP_HOST="0.0.0.0"
+APP_PORT="8000"
+LOG_LEVEL="info"
+
+# Module-specific environment variables
+# <<<inject:module-env>>>

package/templates/kits/fastapi-ddd/env.example.j2

@@ -0,0 +1 @@
+{% include 'common/env.example.j2' %}

package/templates/kits/fastapi-ddd/pyproject.toml.j2

@@ -0,0 +1,64 @@
+[tool.poetry]
+name = "{{ project_name }}"
+version = "{{ app_version }}"
+description = "{{ description }}"
+authors = ["{{ author }} <you@example.com>"]
+license = "{{ license }}"
+packages = [{ include = "src" }]
+
+[tool.poetry.scripts]
+dev = "src.cli:dev"
+start = "src.cli:start"
+build = "src.cli:build"
+test = "src.cli:test"
+lint = "src.cli:lint"
+format = "src.cli:format"
+help = "src.cli:help_cmd"
+
+[tool.poetry.dependencies]
+python = "^{{ python_version }}"
+fastapi = "^0.128.0"
+uvicorn = { extras = ["standard"], version = "^0.40.0" }
+pydantic = "^2.12.5"
+{% if has_settings -%}
+pydantic-settings = { version = "^2.12.0", extras = ["yaml"] }
+{% endif %}
+# <<<inject:poetry-dependencies>>>
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^9.0.2"
+pytest-asyncio = "^1.3.0"
+pytest-cov = "^7.0.0"
+httpx = "^0.28.1"
+ruff = "^0.14.10"
+black = "^25.12.0"
+isort = "^7.0.0"
+mypy = "^1.19.1"
+build = "^1.3.0"
+
+# <<<inject:poetry-dev-dependencies>>>
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+markers = [
+	"integration: mark tests as integration tests",
+	"template_integration: mark template integration tests",
+]
+
+[tool.ruff]
+line-length = 100
+exclude = [".workspai/vendor", ".rapidkit/vendor"]
+
+[tool.ruff.lint]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "{{ python_version }}"
+ignore_missing_imports = true
+warn_unused_configs = false
+show_error_codes = true
+# Ignore vendor snapshots and generated health shims from strict static checking
+exclude = "(^\\.workspai/vendor/|^\\.rapidkit/vendor/|src/health/|src/main.py$|src/app/)"

package/templates/kits/fastapi-ddd/src/__init__.py.j2

@@ -0,0 +1,3 @@
+"""{{ project_name }} package."""
+
+__all__ = ["app", "main"]

package/templates/kits/fastapi-ddd/src/app/__init__.py.j2

@@ -0,0 +1,11 @@
+"""Domain-driven application layers for {{ project_name }}."""
+
+__all__ = [
+    "main",
+    "config",
+    "application",
+    "domain",
+    "infrastructure",
+    "presentation",
+    "shared",
+]

package/templates/kits/fastapi-ddd/src/app/application/__init__.py.j2

@@ -0,0 +1,5 @@
+"""Application layer orchestrating use cases and service contracts."""
+
+from .interfaces import HealthStatusProvider, NoteRepository, ServiceContext
+
+__all__ = ["HealthStatusProvider", "NoteRepository", "ServiceContext"]

package/templates/kits/fastapi-ddd/src/app/application/interfaces.py.j2

@@ -0,0 +1,43 @@
+"""Contracts between the application layer and infrastructure adapters."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from src.app.domain.models import HealthStatus, Note, NoteDraft
+
+
+class HealthStatusProvider(Protocol):
+    """Protocol describing how to obtain the current health status."""
+
+    def get_status(self) -> HealthStatus:
+        """Return the latest domain health status snapshot."""
+        ...
+
+
+class NoteRepository(Protocol):
+    """Protocol for managing example notes."""
+
+    def create(self, draft: NoteDraft) -> Note:
+        """Persist a note draft and return the resulting entity."""
+        ...
+
+    def list(self) -> list[Note]:
+        """Return all available notes."""
+        ...
+
+    def get(self, note_id: int) -> Note | None:
+        """Return a single note or None if it does not exist."""
+        ...
+
+
+@dataclass(slots=True)
+class ServiceContext:
+    """Aggregates infrastructure adapters used by application use-cases."""
+
+    health_provider: HealthStatusProvider
+    note_repository: NoteRepository
+
+
+__all__ = ["HealthStatusProvider", "NoteRepository", "ServiceContext"]

package/templates/kits/fastapi-ddd/src/app/application/use_cases/__init__.py.j2

@@ -0,0 +1,6 @@
+"""Application use-cases exposed to delivery mechanisms."""
+
+from .health import get_service_health
+from .notes import create_note, get_note, list_notes
+
+__all__ = ["get_service_health", "create_note", "get_note", "list_notes"]

package/templates/kits/fastapi-ddd/src/app/application/use_cases/health.py.j2

@@ -0,0 +1,14 @@
+"""Example use-case exposing service health information."""
+
+from __future__ import annotations
+
+from src.app.application.interfaces import ServiceContext
+from src.app.domain.models import HealthStatus
+
+
+def get_service_health(context: ServiceContext) -> dict[str, str]:
+    """Retrieve an immutable health snapshot for presentation layers."""
+    status = context.health_provider.get_status()
+    if isinstance(status, HealthStatus):
+        return status.to_dict()
+    return {"status": str(status)}

package/templates/kits/fastapi-ddd/src/app/application/use_cases/notes.py.j2

@@ -0,0 +1,24 @@
+"""Application use-cases orchestrating the example notes feature."""
+
+from __future__ import annotations
+
+from src.app.application.interfaces import ServiceContext
+from src.app.domain.models import Note, NoteDraft
+
+
+def list_notes(context: ServiceContext) -> list[Note]:
+    """Return every note currently stored."""
+
+    return context.note_repository.list()
+
+
+def create_note(context: ServiceContext, draft: NoteDraft) -> Note:
+    """Create a new note."""
+
+    return context.note_repository.create(draft)
+
+
+def get_note(context: ServiceContext, note_id: int) -> Note | None:
+    """Retrieve a single note by identifier."""
+
+    return context.note_repository.get(note_id)

package/templates/kits/fastapi-ddd/src/app/config/__init__.py.j2

@@ -0,0 +1,16 @@
+"""Configuration primitives for the application layer."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class AppConfig:
+    """Application-level configuration aggregated from RapidKit Core settings."""
+
+    environment: str = "development"
+    service_name: str = "{{ project_name }}"
+
+
+__all__ = ["AppConfig"]

package/templates/kits/fastapi-ddd/src/app/domain/__init__.py.j2

@@ -0,0 +1,3 @@
+"""Domain layer primitives for {{ project_name }}."""
+
+__all__ = ["models"]

package/templates/kits/fastapi-ddd/src/app/domain/models/__init__.py.j2

@@ -0,0 +1,6 @@
+"""Domain models and value objects."""
+
+from .health import HealthStatus
+from .note import Note, NoteDraft
+
+__all__ = ["HealthStatus", "Note", "NoteDraft"]

package/templates/kits/fastapi-ddd/src/app/domain/models/health.py.j2

@@ -0,0 +1,16 @@
+"""Domain entity representing system health."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class HealthStatus:
+    """Immutable representation of the service health state."""
+
+    status: str = "ok"
+
+    def to_dict(self) -> dict[str, str]:
+        """Serialize the status for transport layers."""
+        return {"status": self.status}

package/templates/kits/fastapi-ddd/src/app/domain/models/note.py.j2

@@ -0,0 +1,27 @@
+"""Domain entity and value object for example notes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class NoteDraft:
+    """Value object describing the data needed to create a note."""
+
+    title: str
+    body: str
+
+
+@dataclass(slots=True)
+class Note:
+    """Domain entity representing an immutable note."""
+
+    id: int
+    title: str
+    body: str
+
+    def to_dict(self) -> dict[str, str | int]:
+        """Serialize the note for presentation layers."""
+
+        return {"id": self.id, "title": self.title, "body": self.body}

package/templates/kits/fastapi-ddd/src/app/infrastructure/__init__.py.j2

@@ -0,0 +1,5 @@
+"""Infrastructure adapters for the application layer."""
+
+from .repositories import StaticHealthRepository
+
+__all__ = ["StaticHealthRepository"]

package/templates/kits/fastapi-ddd/src/app/infrastructure/repositories/__init__.py.j2

@@ -0,0 +1,6 @@
+"""Repository implementations bridging the domain and infrastructure."""
+
+from .health import StaticHealthRepository
+from .notes import InMemoryNoteRepository
+
+__all__ = ["StaticHealthRepository", "InMemoryNoteRepository"]

package/templates/kits/fastapi-ddd/src/app/infrastructure/repositories/health.py.j2

@@ -0,0 +1,17 @@
+"""Infrastructure repository providing health status data."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from src.app.domain.models import HealthStatus
+
+
+@dataclass(slots=True)
+class StaticHealthRepository:
+    """Simple repository returning a constant health status."""
+
+    status: str = "ok"
+
+    def get_status(self) -> HealthStatus:
+        return HealthStatus(status=self.status)

package/templates/kits/fastapi-ddd/src/app/infrastructure/repositories/notes.py.j2

@@ -0,0 +1,28 @@
+"""In-memory repository backing the example notes use-case."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List
+
+from src.app.domain.models import Note, NoteDraft
+
+
+@dataclass(slots=True)
+class InMemoryNoteRepository:
+    """Very small repository storing notes in process memory."""
+
+    _store: Dict[int, Note] = field(default_factory=dict)
+    _next_id: int = 1
+
+    def create(self, draft: NoteDraft) -> Note:
+        note = Note(id=self._next_id, title=draft.title, body=draft.body)
+        self._store[self._next_id] = note
+        self._next_id += 1
+        return note
+
+    def list(self) -> List[Note]:
+        return list(self._store.values())
+
+    def get(self, note_id: int) -> Note | None:
+        return self._store.get(note_id)