@gravito/scaffold 1.1.0 → 2.0.0

package/dist/index.cjs

@@ -393,6 +393,30 @@ var BaseGenerator = class {
       this.generateArchitectureDoc(context)
     );
     await this.generateCheckScripts(context);
+    await this.generateSkills(context);
+  }
+  /**
+   * Copy AI Skills to the project
+   */
+  async generateSkills(context) {
+    const skillsDir = import_node_path2.default.resolve(this.config.templatesDir, "skills");
+    const targetSkillsDir = import_node_path2.default.join(".skills");
+    try {
+      await import_promises2.default.access(skillsDir);
+    } catch {
+      return;
+    }
+    const files = await walk(skillsDir);
+    for (const filePath of files) {
+      const relativePath = import_node_path2.default.relative(skillsDir, filePath);
+      const targetPath = import_node_path2.default.join(targetSkillsDir, relativePath);
+      let content = await import_promises2.default.readFile(filePath, "utf-8");
+      try {
+        content = this.stubGenerator.render(content, context);
+      } catch {
+      }
+      await this.writeFile(context.targetDir, targetPath, content);
+    }
   }
   /**
    * Apply profile-specific overlays
@@ -5094,6 +5118,115 @@ Created with \u2764\uFE0F using Gravito Framework
   }
 };
 
+// src/generators/StandaloneEngineGenerator.ts
+var StandaloneEngineGenerator = class extends BaseGenerator {
+  get architectureType() {
+    return "standalone-engine";
+  }
+  get displayName() {
+    return "Standalone Engine";
+  }
+  get description() {
+    return "High-performance pure Gravito Engine (minimal)";
+  }
+  getDirectoryStructure(context) {
+    return [
+      {
+        type: "directory",
+        name: "src",
+        children: [
+          {
+            type: "file",
+            name: "index.ts",
+            content: this.getIndexContent()
+          }
+        ]
+      },
+      {
+        type: "file",
+        name: "README.md",
+        content: this.getReadmeContent(context)
+      }
+    ];
+  }
+  async generateCommonFiles(context) {
+    await this.writeFile(context.targetDir, "package.json", this.generatePackageJson(context));
+    await this.writeFile(context.targetDir, "tsconfig.json", this.generateTsConfig());
+    await this.writeFile(context.targetDir, ".gitignore", this.generateGitignore());
+  }
+  generatePackageJson(context) {
+    const pkg = {
+      name: context.nameKebabCase,
+      version: "0.1.0",
+      type: "module",
+      scripts: {
+        dev: "bun run --watch src/index.ts",
+        build: "bun build ./src/index.ts --outdir ./dist --target bun",
+        start: "bun run dist/index.js",
+        test: "bun test"
+      },
+      dependencies: {
+        "@gravito/core": "^1.1.0"
+      },
+      devDependencies: {
+        "bun-types": "latest",
+        typescript: "^5.0.0"
+      }
+    };
+    return JSON.stringify(pkg, null, 2);
+  }
+  generateArchitectureDoc(_context) {
+    return "";
+  }
+  getIndexContent() {
+    return `import { Gravito } from '@gravito/core/engine'
+
+const app = new Gravito()
+
+// Basic Route
+app.get('/', (c) => c.text('Hello Gravito Engine!'))
+
+// JSON Response
+app.get('/json', (c) => c.json({ message: 'High Performance' }))
+
+// Path Parameters
+app.get('/user/:name', (c) => {
+  const name = c.req.param('name')
+  return c.text(\`Hello \${name}\`)
+})
+
+export default app
+`;
+  }
+  getReadmeContent(context) {
+    return `# ${context.name}
+
+A high-performance web application powered by Gravito Engine.
+
+## Getting Started
+
+### Install Dependencies
+
+\`\`\`bash
+bun install
+\`\`\`
+
+### Run Development Server
+
+\`\`\`bash
+bun run dev
+\`\`\`
+
+### Production Build
+
+\`\`\`bash
+bun run build
+bun start
+\`\`\`
+`;
+  }
+};
+
 // src/Scaffold.ts
 var Scaffold = class {
   templatesDir;
@@ -5127,6 +5260,11 @@ var Scaffold = class {
         name: "Action Domain",
         description: "Single Action Controllers pattern for high-clarity APIs"
       },
+      {
+        type: "standalone-engine",
+        name: "Standalone Engine",
+        description: "High-performance pure Gravito Engine (minimal)"
+      },
       {
         type: "satellite",
         name: "Gravito Satellite",
@@ -5202,6 +5340,8 @@ var Scaffold = class {
         return new ActionDomainGenerator(config);
       case "satellite":
         return new SatelliteGenerator(config);
+      case "standalone-engine":
+        return new StandaloneEngineGenerator(config);
       default:
         throw new Error(`Unknown architecture type: ${type}`);
     }

package/dist/index.d.cts

@@ -47,7 +47,7 @@ declare class FileMerger {
 /**
  * Architecture types supported by the scaffolding system.
  */
-type ArchitectureType = 'enterprise-mvc' | 'clean' | 'ddd' | 'satellite' | 'action-domain';
+type ArchitectureType = 'enterprise-mvc' | 'clean' | 'ddd' | 'satellite' | 'action-domain' | 'standalone-engine';
 /**
  * Options for scaffolding a new project.
  */
@@ -319,6 +319,10 @@ declare abstract class BaseGenerator {
      * Generate common files (package.json, .env, etc.)
      */
     protected generateCommonFiles(context: GeneratorContext): Promise<void>;
+    /**
+     * Copy AI Skills to the project
+     */
+    protected generateSkills(context: GeneratorContext): Promise<void>;
     /**
      * Apply profile-specific overlays
      */

package/dist/index.d.ts

@@ -47,7 +47,7 @@ declare class FileMerger {
 /**
  * Architecture types supported by the scaffolding system.
  */
-type ArchitectureType = 'enterprise-mvc' | 'clean' | 'ddd' | 'satellite' | 'action-domain';
+type ArchitectureType = 'enterprise-mvc' | 'clean' | 'ddd' | 'satellite' | 'action-domain' | 'standalone-engine';
 /**
  * Options for scaffolding a new project.
  */
@@ -319,6 +319,10 @@ declare abstract class BaseGenerator {
      * Generate common files (package.json, .env, etc.)
      */
     protected generateCommonFiles(context: GeneratorContext): Promise<void>;
+    /**
+     * Copy AI Skills to the project
+     */
+    protected generateSkills(context: GeneratorContext): Promise<void>;
     /**
      * Apply profile-specific overlays
      */

package/dist/index.js

@@ -347,6 +347,30 @@ var BaseGenerator = class {
       this.generateArchitectureDoc(context)
     );
     await this.generateCheckScripts(context);
+    await this.generateSkills(context);
+  }
+  /**
+   * Copy AI Skills to the project
+   */
+  async generateSkills(context) {
+    const skillsDir = path2.resolve(this.config.templatesDir, "skills");
+    const targetSkillsDir = path2.join(".skills");
+    try {
+      await fs2.access(skillsDir);
+    } catch {
+      return;
+    }
+    const files = await walk(skillsDir);
+    for (const filePath of files) {
+      const relativePath = path2.relative(skillsDir, filePath);
+      const targetPath = path2.join(targetSkillsDir, relativePath);
+      let content = await fs2.readFile(filePath, "utf-8");
+      try {
+        content = this.stubGenerator.render(content, context);
+      } catch {
+      }
+      await this.writeFile(context.targetDir, targetPath, content);
+    }
   }
   /**
    * Apply profile-specific overlays
@@ -5048,6 +5072,115 @@ Created with \u2764\uFE0F using Gravito Framework
   }
 };
 
+// src/generators/StandaloneEngineGenerator.ts
+var StandaloneEngineGenerator = class extends BaseGenerator {
+  get architectureType() {
+    return "standalone-engine";
+  }
+  get displayName() {
+    return "Standalone Engine";
+  }
+  get description() {
+    return "High-performance pure Gravito Engine (minimal)";
+  }
+  getDirectoryStructure(context) {
+    return [
+      {
+        type: "directory",
+        name: "src",
+        children: [
+          {
+            type: "file",
+            name: "index.ts",
+            content: this.getIndexContent()
+          }
+        ]
+      },
+      {
+        type: "file",
+        name: "README.md",
+        content: this.getReadmeContent(context)
+      }
+    ];
+  }
+  async generateCommonFiles(context) {
+    await this.writeFile(context.targetDir, "package.json", this.generatePackageJson(context));
+    await this.writeFile(context.targetDir, "tsconfig.json", this.generateTsConfig());
+    await this.writeFile(context.targetDir, ".gitignore", this.generateGitignore());
+  }
+  generatePackageJson(context) {
+    const pkg = {
+      name: context.nameKebabCase,
+      version: "0.1.0",
+      type: "module",
+      scripts: {
+        dev: "bun run --watch src/index.ts",
+        build: "bun build ./src/index.ts --outdir ./dist --target bun",
+        start: "bun run dist/index.js",
+        test: "bun test"
+      },
+      dependencies: {
+        "@gravito/core": "^1.1.0"
+      },
+      devDependencies: {
+        "bun-types": "latest",
+        typescript: "^5.0.0"
+      }
+    };
+    return JSON.stringify(pkg, null, 2);
+  }
+  generateArchitectureDoc(_context) {
+    return "";
+  }
+  getIndexContent() {
+    return `import { Gravito } from '@gravito/core/engine'
+
+const app = new Gravito()
+
+// Basic Route
+app.get('/', (c) => c.text('Hello Gravito Engine!'))
+
+// JSON Response
+app.get('/json', (c) => c.json({ message: 'High Performance' }))
+
+// Path Parameters
+app.get('/user/:name', (c) => {
+  const name = c.req.param('name')
+  return c.text(\`Hello \${name}\`)
+})
+
+export default app
+`;
+  }
+  getReadmeContent(context) {
+    return `# ${context.name}
+
+A high-performance web application powered by Gravito Engine.
+
+## Getting Started
+
+### Install Dependencies
+
+\`\`\`bash
+bun install
+\`\`\`
+
+### Run Development Server
+
+\`\`\`bash
+bun run dev
+\`\`\`
+
+### Production Build
+
+\`\`\`bash
+bun run build
+bun start
+\`\`\`
+`;
+  }
+};
+
 // src/Scaffold.ts
 var Scaffold = class {
   templatesDir;
@@ -5081,6 +5214,11 @@ var Scaffold = class {
         name: "Action Domain",
         description: "Single Action Controllers pattern for high-clarity APIs"
       },
+      {
+        type: "standalone-engine",
+        name: "Standalone Engine",
+        description: "High-performance pure Gravito Engine (minimal)"
+      },
       {
         type: "satellite",
         name: "Gravito Satellite",
@@ -5156,6 +5294,8 @@ var Scaffold = class {
         return new ActionDomainGenerator(config);
       case "satellite":
         return new SatelliteGenerator(config);
+      case "standalone-engine":
+        return new StandaloneEngineGenerator(config);
       default:
         throw new Error(`Unknown architecture type: ${type}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravito/scaffold",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "Project scaffolding engine for Gravito - Generate enterprise-grade architecture templates",
   "type": "module",
   "main": "dist/index.js",

package/templates/skills/SKILLS_USAGE.md

@@ -0,0 +1,54 @@
+# 🎓 Gravito Skills: Usage Guide
+
+Welcome to the Gravito Skills ecosystem. These are specialized "onboarding modules" designed to help AI agents (like Antigravity or Claude) and developers build high-quality software using Gravito's best practices.
+
+## 🧠 The Concept: Skill Summoning
+
+A "Skill" is a set of rules, blueprints, and SOPs. You don't just "read" them; you **summon** them to perform a task.
+
+### How to use with AI Agents
+When you are working with an AI agent, you can explicitly tell it which skills to apply.
+
+**Example Prompts:**
+- *"Antigravity, use `mvc-master` and `commerce-blueprint` to implement a shopping cart."*
+- *"Use `adr-scaffold` and `identity-hub` to build a new user registration flow."*
+- *"Follow `clean-architect` to refactor my domain logic."*
+
+## 🏗️ Skill Composition: Horizontal + Vertical
+
+To handle complexity, we use a modular composition strategy:
+
+| Skill Type | Purpose | Example |
+| :--- | :--- | :--- |
+| **Horizontal (Architecture)** | Defines **where** the code goes (Structure). | `mvc-master`, `adr-scaffold`, `clean-architect` |
+| **Vertical (Domain)** | Defines **what** the code does (Business Logic). | `commerce-blueprint`, `identity-hub`, `cms-engine` |
+
+### 🚀 Standard Workflow
+If you have just scaffolded an MVC project and want to develop a shopping cart:
+
+1.  **Architecture Initialization**: You already have the MVC structure.
+2.  **Summon Domain Skill**: Ask the agent to apply `commerce-blueprint`.
+3.  **Cross-Reference**: The agent will look at `mvc-master` for file locations (Controllers in `src/Http/Controllers`) and `commerce-blueprint` for business rules (Price snapshots, State machines).
+
+## 🛠️ List of Available Skills
+
+### Architecture (Horizontal)
+- `mvc-master`: Enterprise Model-View-Controller.
+- `adr-scaffold`: Action-Domain-Responder pattern.
+- `clean-architect`: Pure Domain & Use Case isolation.
+- `ddd-domain-expert`: Aggregate Roots & Bounded Contexts.
+- `freeze-static`: Static Site Generation (SSG).
+
+### Domain (Vertical)
+- `commerce-blueprint`: Cart, Checkout, SKU management.
+- `identity-hub`: Auth, RBAC, Multi-tenancy.
+- `cms-engine`: Publishing workflows, Blogs, Media.
+
+### Operations & Quality
+- `fortify-security`: CSP, Security Headers, Auth middleware.
+- `test-guardian`: Testing strategies (Unit, E2E).
+- `ops-commander`: Docker, CI/CD, Fly.io.
+- `performance-tuner`: Caching, DB indexing, Optimization.
+
+---
+Created by Antigravity for the Gravito Framework.

package/templates/skills/adr-scaffold/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: adr-scaffold
+description: Specializes in generating Action-Domain-Responder (ADR) boilerplate for Gravito projects. Trigger this when adding new features or modules using the ADR pattern.
+---
+
+# ADR Scaffold Expert
+
+You are a Gravito Architect specialized in the Action-Domain-Responder pattern. Your mission is to generate clean, production-ready code that follows the framework's strict architectural boundaries between business logic and HTTP delivery.
+
+## 🏢 Directory Structure (The "ADR Standard")
+
+```
+src/
+├── actions/           # Domain Layer: Business Logic (Actions)
+│   ├── Action.ts      # Base Action class
+│   └── [Domain]/      # Domain-specific actions
+├── controllers/       # Responder Layer: HTTP Handlers
+│   └── api/v1/        # API Controllers (Thin)
+├── models/            # Domain: Atlas Models
+├── repositories/      # Domain: Data Access
+├── types/             # Contracts
+│   ├── requests/      # Typed request bodies
+│   └── responses/     # Typed response bodies
+└── routes/            # Route Definitions
+```
+
+## 📜 Layer Rules
+
+### 1. Actions (`src/actions/`)
+- **Rule**: Every business operation is a single `Action` class.
+- **Task**: Implement the `execute` method. Actions should be framework-agnostic.
+- **SOP**: Use `DB.transaction` inside actions for multi-row operations.
+
+### 2. Controllers (`src/controllers/`)
+- **Rule**: Thin Responder Layer. NO business logic.
+- **Task**: Parse params -> Call Action -> Return formatted JSON.
+
+## 🏗️ Code Blueprints
+
+### Base Action
+```typescript
+export abstract class Action<TInput = unknown, TOutput = unknown> {
+  abstract execute(input: TInput): Promise<TOutput> | TOutput
+}
+```
+
+### Typical Action Implementation
+```typescript
+export class CreateOrderAction extends Action<OrderInput, OrderResponse> {
+  async execute(input: OrderInput) {
+    return await DB.transaction(async (trx) => {
+      // 1. Validate...
+      // 2. Persist...
+      // 3. Trigger events...
+    })
+  }
+}
+```
+
+## 🚀 Workflow (SOP)
+
+1. **Entities**: Define the Atlas Model in `src/models/`.
+2. **Persistence**: Build the Repository in `src/repositories/`.
+3. **Contracts**: Define Request/Response types in `src/types/`.
+4. **Logic**: Implement the Single Action in `src/actions/[Domain]/`.
+5. **Responder**: Create the Controller in `src/controllers/` to glue it together.
+6. **Routing**: Map the route in `src/routes/api.ts`.

package/templates/skills/adr-scaffold/references/adr-rules.md

@@ -0,0 +1,29 @@
+# Gravito ADR Reference
+
+## Component Rules
+
+### 1. Models (Atlas)
+- Location: `src/models/`
+- Rules: Extend `Model`, define `static table`, use `@column`.
+
+### 2. Repositories
+- Location: `src/repositories/`
+- Rules: Dedicated classes for DB access. No logic, only queries.
+
+### 3. Actions
+- Location: `src/actions/[Domain]/`
+- Rules: Single Responsibility. One class per use case. Extend `Action<Input, Output>`.
+
+### 4. Controllers
+- Location: `src/controllers/api/v[N]/`
+- Rules: Thin layer. Use `c.get('parsed_body')` for body caching.
+
+## Directory Layout
+```
+src/
+├── actions/
+├── models/
+├── repositories/
+├── controllers/
+└── routes/
+```

package/templates/skills/architecture-refiner/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: architecture-refiner
+description: Expert in Gravito architecture and clean code. Trigger this for refactoring, design pattern implementation, or architectural audits.
+---
+
+# Architecture Refiner
+
+You are a lead architect dedicated to the "Singularity" principle. Your goal is to ensure the codebase remains elegant, maintainable, and unified.
+
+## Workflow
+
+### 1. Audit
+- Identify technical debt or architectural violations (e.g., logic in controllers).
+- Review the modularity of the current implementation.
+
+### 2. Refinement
+1. **Decoupling**: Extract business logic into specialized `Actions`.
+2. **Standardization**: Align code with the `GRAVITO_AGENT_GUIDE.md`.
+3. **Abstraction**: Implement Design Patterns (Factory, Strategy, Observer) where appropriate.
+
+### 3. Standards
+- Follow the **Action-Domain-Responder** pattern strictly.
+- Ensure **Zero-Ambiguity** in naming and structure.
+- Adhere to the **Artisan's Apprentice** voice in internal documentation.
+
+## Resources
+- **References**: Pattern catalog for Gravito.
+- **Assets**: Refactoring checklists.

package/templates/skills/atlas-expert/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: atlas-expert
+description: Specialized in Atlas ORM and database design for Gravito. Trigger this for schema design, migrations, or complex query building.
+---
+
+# Atlas ORM Expert
+
+You are a database architect specialized in the Atlas ORM. Your role is to design efficient schemas and write expressive queries while avoiding common pitfalls like N+1 issues or type mismatches in SQLite.
+
+## Workflow
+
+### 1. Schema Design
+When asked to design a database:
+- Identify entities and their attributes.
+- Define primary keys and foreign keys.
+- Choose appropriate TypeScript types for columns.
+
+### 2. Relationship Mapping
+- Map relationships using `@HasOne`, `@HasMany`, and `@BelongsTo`.
+- Ensure foreign keys are defined in the database schema (via migrations).
+
+### 3. Query Optimization
+- Use `preload()` to avoid N+1 problems.
+- Use `where()` and `first()` for efficient single-row lookups.
+- Wrap modifications in `DB.transaction()`.
+
+## SQLite Considerations
+- SQLite is loosely typed. Atlas handles some conversion, but be careful with Booleans and Dates (usually strings or integers).
+- Read `references/decorators.md` for the latest syntax.
+
+## Implementation Steps
+1. Plan the schema on paper/markdown.
+2. Generate the Atlas Model class.
+3. Generate the Migration script if needed.

package/templates/skills/atlas-expert/references/decorators.md

@@ -0,0 +1,24 @@
+# Atlas Decorators Cheat Sheet
+
+| Decorator | Purpose | Usage |
+|-----------|---------|-------|
+| `@column({ isPrimary: true })` | Primary key | `@column({ isPrimary: true }) id!: number` |
+| `@column()` | Standard database column | `@column() name!: string` |
+| `@HasOne(() => Target)` | 1:1 relationship | `@HasOne(() => Profile) profile!: Profile` |
+| `@HasMany(() => Target)` | 1:N relationship | `@HasMany(() => Post) posts!: Post[]` |
+| `@BelongsTo(() => Target)` | Inverse of HasOne/Many | `@BelongsTo(() => User) user!: User` |
+
+## Model Definition Template
+```typescript
+import { Model, column } from '@gravito/atlas'
+
+export class MyModel extends Model {
+  static table = 'my_table'
+
+  @column({ isPrimary: true })
+  id!: number
+
+  @column()
+  createdAt!: string
+}
+```