gherkin-ai 1.0.0

package/dist/utils/file-system.d.ts

@@ -0,0 +1,5 @@
+export declare function ensureDirSync(dirPath: string): void;
+export declare function writeFileSync(filePath: string, content: string): void;
+export declare function readFileSync(filePath: string): string;
+export declare function fileExistsSync(filePath: string): boolean;
+//# sourceMappingURL=file-system.d.ts.map

package/dist/utils/file-system.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-system.d.ts","sourceRoot":"","sources":["../../src/utils/file-system.ts"],"names":[],"mappings":"AAOA,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAInD;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAIrE;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAExD"}

package/dist/utils/file-system.js

@@ -0,0 +1,31 @@
+"use strict";
+/* ==========================================================================
+   gherkin-ai-cli - File System Helper Utility
+   ========================================================================== */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureDirSync = ensureDirSync;
+exports.writeFileSync = writeFileSync;
+exports.readFileSync = readFileSync;
+exports.fileExistsSync = fileExistsSync;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+function ensureDirSync(dirPath) {
+    if (!fs_1.default.existsSync(dirPath)) {
+        fs_1.default.mkdirSync(dirPath, { recursive: true });
+    }
+}
+function writeFileSync(filePath, content) {
+    const dir = path_1.default.dirname(filePath);
+    ensureDirSync(dir);
+    fs_1.default.writeFileSync(filePath, content, 'utf-8');
+}
+function readFileSync(filePath) {
+    return fs_1.default.readFileSync(filePath, 'utf-8');
+}
+function fileExistsSync(filePath) {
+    return fs_1.default.existsSync(filePath);
+}
+//# sourceMappingURL=file-system.js.map

package/dist/utils/file-system.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-system.js","sourceRoot":"","sources":["../../src/utils/file-system.ts"],"names":[],"mappings":";AAAA;;gFAEgF;;;;;AAKhF,sCAIC;AAED,sCAIC;AAED,oCAEC;AAED,wCAEC;AArBD,4CAAoB;AACpB,gDAAwB;AAExB,SAAgB,aAAa,CAAC,OAAe;IAC3C,IAAI,CAAC,YAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,YAAE,CAAC,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7C,CAAC;AACH,CAAC;AAED,SAAgB,aAAa,CAAC,QAAgB,EAAE,OAAe;IAC7D,MAAM,GAAG,GAAG,cAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,aAAa,CAAC,GAAG,CAAC,CAAC;IACnB,YAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAC/C,CAAC;AAED,SAAgB,YAAY,CAAC,QAAgB;IAC3C,OAAO,YAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AAC5C,CAAC;AAED,SAAgB,cAAc,CAAC,QAAgB;IAC7C,OAAO,YAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;AACjC,CAAC"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,8 @@
+export declare const logger: {
+    info(message: string): void;
+    success(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    banner(): void;
+};
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,MAAM;kBACH,MAAM,GAAG,IAAI;qBAIV,MAAM,GAAG,IAAI;kBAIhB,MAAM,GAAG,IAAI;mBAIZ,MAAM,GAAG,IAAI;cAIlB,IAAI;CAOf,CAAC"}

package/dist/utils/logger.js

@@ -0,0 +1,28 @@
+"use strict";
+/* ==========================================================================
+   gherkin-ai-cli - Logger Utility (English CLI Output)
+   ========================================================================== */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+exports.logger = {
+    info(message) {
+        console.log(`\x1b[36mℹ\x1b[0m ${message}`);
+    },
+    success(message) {
+        console.log(`\x1b[32m✔\x1b[0m ${message}`);
+    },
+    warn(message) {
+        console.warn(`\x1b[33m⚠\x1b[0m ${message}`);
+    },
+    error(message) {
+        console.error(`\x1b[31m✖\x1b[0m ${message}`);
+    },
+    banner() {
+        console.log(`
+\x1b[35m🥒 gherkin-ai CLI v1.0.0\x1b[0m
+\x1b[90mExecutable Prompt & Contract Generator for AI Coding Agents\x1b[0m
+\x1b[90mWebsite: https://fennereduardo.com/pages/GherkinIATool/\x1b[0m
+`);
+    }
+};
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":";AAAA;;gFAEgF;;;AAEnE,QAAA,MAAM,GAAG;IACpB,IAAI,CAAC,OAAe;QAClB,OAAO,CAAC,GAAG,CAAC,oBAAoB,OAAO,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED,OAAO,CAAC,OAAe;QACrB,OAAO,CAAC,GAAG,CAAC,oBAAoB,OAAO,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED,IAAI,CAAC,OAAe;QAClB,OAAO,CAAC,IAAI,CAAC,oBAAoB,OAAO,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED,KAAK,CAAC,OAAe;QACnB,OAAO,CAAC,KAAK,CAAC,oBAAoB,OAAO,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM;QACJ,OAAO,CAAC,GAAG,CAAC;;;;CAIf,CAAC,CAAC;IACD,CAAC;CACF,CAAC"}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,63 @@
+# 🏗️ `gherkin-ai` CLI Architecture & Agent Pipeline Design
+
+This document details the internal design, Abstract Syntax Tree (AST) parsing pipeline, and contract generation mechanisms of `gherkin-ai` CLI.
+
+---
+
+## 1. System Architecture Diagram
+
+```text
+ ┌──────────────────────┐
+ │ Gherkin (.feature)   │
+ └──────────┬───────────┘
+            │
+            ▼
+ ┌──────────────────────┐      ┌───────────────────────┐
+ │ gherkin-parser.ts    ├─────►│ ParsedFeature (AST)   │
+ └──────────────────────┘      └──────────┬────────────┘
+                                          │
+                                          ▼
+ ┌──────────────────────┐      ┌───────────────────────┐
+ │ config.ts            ├─────►│ Execution Context     │
+ └──────────────────────┘      └──────────┬────────────┘
+                                          │
+               ┌──────────────────────────┼──────────────────────────┐
+               ▼                          ▼                          ▼
+ ┌──────────────────────────┐ ┌───────────────────────┐ ┌───────────────────────┐
+ │ contracts.ts Generator   │ │ fixtures.ts Generator │ │ prompts.ts Generator  │
+ └─────────────┬────────────┘ └───────────┬───────────┘ └───────────┬───────────┘
+               │                          │                         │
+               ▼                          ▼                         ▼
+      contracts.ts / ADRs            seed.sql / TS             Agent Prompts
+```
+
+---
+
+## 2. Core Components
+
+### 2.1 AST Parser (`src/core/gherkin-parser.ts`)
+Parses `.feature` text into structured models:
+- **Feature Title & Business Goal**
+- **Scenarios & Given/When/Then Steps**
+- **Domain Analysis**: Automatically classifies step phrases into Actors, Commands (When), Queries (Then), Events (Domain Events), and Fixtures (Given).
+
+### 2.2 Architecture Rules Engine (`src/core/arch-rules.ts`)
+Defines strict layer import boundaries for 10 architecture patterns. Ensures that domain entities generated by AI agents never import HTTP or ORM dependencies.
+
+### 2.3 Contract & DTO Generator (`src/generators/contracts.ts`)
+Transforms parsed AST commands into valid Zod validation schemas and TypeScript interfaces:
+- `IDomainEvent` & explicit event schemas.
+- Command DTO schemas for input validation.
+- Outbound repository ports (`IRepository`).
+
+### 2.4 Test Fixture Engine (`src/generators/fixtures.ts`)
+Generates concrete setup fixtures and SQL seeds (hashed passwords via `bcrypt`, pre-conditions) to resolve the ambiguity of `Given` steps.
+
+---
+
+## 3. Agent Execution Strategy
+
+To prevent AI coding agents from diverging or producing uncompilable code:
+1. **Domain Architect Agent** reads `contracts.ts` and implements pure business logic without external dependencies.
+2. **Backend Developer Agent** uses `contracts.ts` and `fixtures.ts` to implement Use Cases, Controllers, and ORM Repositories.
+3. **QA Automation Agent** uses `fixtures.ts` and `.feature` files to write deterministic unit and integration tests.

package/docs/USAGE_GUIDE.md

@@ -0,0 +1,125 @@
+# 📘 `gherkin-ai` CLI Usage Guide & Tutorial
+
+This guide provides step-by-step instructions for installing, configuring, and executing `gherkin-ai` CLI in your development workflow.
+
+---
+
+## Table of Contents
+
+1. [Installation](#installation)
+2. [CLI Configuration (`gherkin-ai.config.json`)](#cli-configuration)
+3. [Writing Gherkin Features](#writing-gherkin-features)
+4. [Command Reference](#command-reference)
+   - [`init`](#init)
+   - [`generate`](#generate)
+   - [`validate`](#validate)
+   - [`export`](#export)
+5. [Feeding Generated Prompts into AI Agents](#feeding-prompts-into-ai-agents)
+
+---
+
+## 1. Installation
+
+You can run `gherkin-ai` directly without installation using `npx`:
+
+```bash
+npx gherkin-ai --version
+```
+
+Or install it globally using npm:
+
+```bash
+npm install -g gherkin-ai
+```
+
+---
+
+## 2. CLI Configuration
+
+Run `gherkin-ai init` to generate a `gherkin-ai.config.json` file in your root folder:
+
+```json
+{
+  "projectName": "auth-service",
+  "architecture": "hexagonal",
+  "stack": {
+    "language": "typescript",
+    "framework": "nestjs",
+    "orm": "prisma",
+    "database": "postgresql",
+    "validation": "zod",
+    "auth": "jwt-bcrypt",
+    "messaging": "rabbitmq",
+    "testing": "jest"
+  },
+  "rules": {
+    "bcryptCostFactor": 12,
+    "jwtTtlSeconds": 3600,
+    "strictLayerBoundaries": true,
+    "coverageTarget": 85
+  },
+  "outputDir": "./generated-specs"
+}
+```
+
+---
+
+## 3. Writing Gherkin Features
+
+Create a feature file (e.g. `./specs/auth.feature`):
+
+```gherkin
+Feature: User Authentication & Token Issuance
+  As a registered system user
+  I want to authenticate using valid credentials
+  So that I obtain a JWT token to access protected APIs
+
+  Scenario: Successful login with valid credentials
+    Given a registered user exists with email "dev@example.com" and password "Pass123!"
+    When sending an authentication request with email "dev@example.com" and password "Pass123!"
+    Then the system responds with HTTP status 200 OK
+    And returns a short-lived access JWT token
+    And emits a "UserAuthenticated" domain event
+```
+
+---
+
+## 4. Command Reference
+
+### `gherkin-ai generate`
+
+Generates TypeScript contracts, DTO schemas, test fixtures, docker-compose, and role prompts:
+
+```bash
+gherkin-ai generate --feature ./specs/auth.feature --config ./gherkin-ai.config.json
+```
+
+### `gherkin-ai validate`
+
+Validates that your feature spec and project setup adhere to chosen architecture boundaries:
+
+```bash
+gherkin-ai validate --feature ./specs/auth.feature
+```
+
+### `gherkin-ai export`
+
+Exports a single Markdown or JSON context bundle for AI coding agents:
+
+```bash
+gherkin-ai export --feature ./specs/auth.feature --format md --output ./agent-context.md
+```
+
+---
+
+## 5. Feeding Generated Prompts into AI Agents
+
+### For Claude Code / Terminal Agents:
+```bash
+claude "Read generated-specs/prompts/domain-agent.md and generated-specs/contracts.ts. Implement the domain entities in src/domain/."
+```
+
+### For Cursor / Windsurf / IDE Agents:
+1. Open `@generated-specs/contracts.ts` in your workspace.
+2. Load `@generated-specs/prompts/backend-agent.md` as context.
+3. Instruct the AI agent: *"Implement the application use cases and controllers following contracts.ts."*

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "gherkin-ai",
+  "version": "1.0.0",
+  "description": "CLI tool & contract engine translating Gherkin specs into production-grade executable prompts, TypeScript contracts, and seed fixtures for AI Coding Agents.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "gherkin-ai": "./bin/gherkin-ai.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "LICENSE",
+    "docs"
+  ],
+  "keywords": [
+    "gherkin",
+    "bdd",
+    "ai-agent",
+    "prompts",
+    "architecture",
+    "ddd",
+    "cqrs",
+    "clean-architecture",
+    "hexagonal-architecture",
+    "claude-code",
+    "cursor",
+    "antigravity"
+  ],
+  "author": "Fenner Eduardo <contact@fennereduardo.com> (https://fennereduardo.com)",
+  "license": "MIT",
+  "homepage": "https://fennereduardo.com/pages/GherkinIATool/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FennerEduardo/gherkin-ai-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/FennerEduardo/gherkin-ai-cli/issues"
+  },
+  "scripts": {
+    "build": "npx tsc",
+    "start": "node ./bin/gherkin-ai.js",
+    "dev": "npx tsc --watch",
+    "test": "npx ts-node tests/parser.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^12.1.0",
+    "inquirer": "^8.2.6"
+  },
+  "devDependencies": {
+    "@types/inquirer": "^8.2.10",
+    "@types/node": "^20.14.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.4.5"
+  }
+}