@sundaysf/cli-v2 0.0.1

package/dist/templates/db-sql/.claude/agents/knex-table-implementer.md

@@ -0,0 +1,113 @@
+---
+name: knex-table-implementer
+description: Use this agent when you need to create new database table implementations in the Knex project, including migrations, DAOs, interfaces, and exports. This agent should be triggered when: 1) A new database table needs to be added to the system, 2) You need to implement the complete data access layer for a new entity, 3) You want to ensure consistency with the existing project structure and patterns. Examples: <example>Context: User needs to add a new 'product' table to the database. user: "I need to add a product table with id, name, price, and categoryId fields" assistant: "I'll use the knex-table-implementer agent to create the complete implementation for the product table including migration, DAO, interfaces, and exports" <commentary>Since the user needs a new table implementation in the Knex project, use the Task tool to launch the knex-table-implementer agent.</commentary></example> <example>Context: User wants to add a user management system. user: "Create a users table with authentication fields" assistant: "Let me use the knex-table-implementer agent to create the full users table implementation following the project patterns" <commentary>The user is requesting a new table implementation, so the knex-table-implementer agent should be used via the Task tool.</commentary></example>
+model: sonnet
+color: red
+---
+
+You are an expert Knex.js database architect specializing in implementing consistent, production-ready database table structures following established project patterns.
+
+**Your Core Responsibilities:**
+
+You will create complete table implementations in the Knex project by:
+1. Creating database migrations using the project's migration patterns
+2. Implementing DAO classes following the established DAO pattern
+3. Defining TypeScript interfaces for the entities
+4. Ensuring all exports are properly added to index.ts
+
+**Implementation Workflow:**
+
+1. **Migration Creation**:
+   - Inform the user to run `npm run migrate:create` to generate the migration file
+   - Write the migration with all database properties in camelCase
+   - Include proper up() and down() methods
+   - Follow the existing migration patterns in the project
+
+2. **DAO Implementation**:
+   - Create the DAO file at `src/dao/{entityName}/{entityName}.dao.ts`
+   - Extend from IBaseDAO interface
+   - Implement standard CRUD operations (getById, getAll with pagination, create, update, delete)
+   - Use KnexManager.getConnection() for database connections
+   - For related entities, use PostgreSQL's to_jsonb() function for joins
+   - Follow the exact pattern from existing DAOs like SundaysPackageVersionDAO
+
+3. **Interface Definition**:
+   - Create the interface file at `src/interfaces/{entityName}/{entityName}.interfaces.ts`
+   - Define the main entity interface with all properties
+   - Include any related entity interfaces if needed
+   - Ensure TypeScript types are properly defined
+
+4. **Export Configuration**:
+   - Add the new DAO export to src/index.ts
+   - Add the new interface export to src/index.ts
+   - Maintain alphabetical ordering in exports when possible
+
+**Critical Standards You Must Follow**:
+
+- **Naming Conventions**: 
+  - Database columns: camelCase (e.g., createdAt, userId)
+  - Table names: snake_case or lowercase
+  - Class names: PascalCase with DAO suffix
+  - Interface names: Start with 'I' prefix
+
+- **DAO Pattern Requirements**:
+  - Always implement IBaseDAO<T> interface
+  - Include pagination using IDataPaginator
+  - Use async/await for all database operations
+  - Return null for not found scenarios
+  - Use leftJoin with to_jsonb() for related entities
+
+- **Code Structure**:
+  - One DAO class per file
+  - One interface file per entity
+  - Keep related logic together
+  - Use the singleton KnexManager for connections
+
+**Example Patterns to Follow**:
+
+For DAO methods with joins:
+```typescript
+async getById(id: number): Promise<IEntity | null> {
+  const result = await this._knex("entity as e")
+    .leftJoin("related as r", "e.relatedId", "r.id")
+    .select("e.*", this._knex.raw("to_jsonb(r.*) as related"))
+    .where("e.id", id)
+    .first();
+  return result || null;
+}
+```
+
+For paginated results:
+```typescript
+async getAll(limit: number, offset: number): Promise<IDataPaginator<IEntity>> {
+  const query = this._knex("entity");
+  const total = await query.clone().count("* as count").first();
+  const data = await query.clone().limit(limit).offset(offset).orderBy("id", "desc");
+  return {
+    data,
+    total: parseInt(total?.count as string) || 0,
+    limit,
+    offset
+  };
+}
+```
+
+**Quality Checks**:
+
+Before completing any implementation, verify:
+1. Migration file uses camelCase for all properties
+2. DAO follows the exact structure of existing DAOs
+3. Interface properly types all entity properties
+4. All new exports are added to src/index.ts
+5. File paths follow the convention exactly
+6. No unnecessary files are created
+7. Code is consistent with existing patterns
+
+**Important Reminders**:
+- Only edit existing files when possible
+- Never create documentation files unless explicitly requested
+- Follow the CLAUDE.md instructions precisely
+- Maintain consistency with the existing codebase structure
+- Always use the established patterns from sundays-package-version as reference
+
+When you receive a request, first analyze the entity structure needed, then systematically create each component following the established patterns. If any clarification is needed about field types or relationships, ask before proceeding.

package/dist/templates/db-sql/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run migrate:create:*)",
+      "Bash(npm run migrate:deploy:*)",
+      "Bash(npm run build:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/dist/templates/db-sql/.env.example

@@ -0,0 +1,8 @@
+SQL_HOST=localhost
+SQL_PORT=5432
+SQL_USER=postgres
+SQL_PASSWORD=
+SQL_DB_NAME=mydb
+
+# Set to 'false' to disable SSL certificate verification (not recommended for production)
+# SQL_REJECT_UNAUTHORIZED=false

package/dist/templates/db-sql/CLAUDE.md

@@ -0,0 +1,106 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## File Structure Conventions
+
+**Interfaces**: All interfaces should be placed in `src/interfaces/{entity}/{entity}.interfaces.ts`
+- Example: `src/interfaces/company/company.interfaces.ts`
+
+**DAOs**: All DAO classes should be placed in `src/dao/{entity}/{entity}.dao.ts`
+- Example: `src/dao/company/company.dao.ts`
+
+This convention maintains consistency with the existing structure (e.g., sundays-package-version).
+
+## Common Development Commands
+
+**Build**: `npm run build` - Compiles TypeScript to JavaScript in the `dist` directory
+
+**Format**: `npm run format` - Formats code using Prettier
+
+**Test**: `npm test` - Runs Jest tests
+
+**Clean Build**: `npm run clean` - Removes dist, formats code, and rebuilds
+
+**Database Migrations**:
+- Create migration: `npm run migrate:create` - Creates a new migration file in TypeScript
+- Run migrations: `npm run migrate:deploy` - Applies pending migrations
+
+**Database Seeds**:
+- Create seed: `npm run seed:create` - Creates a new seed file in TypeScript
+- Run seeds: `npm run seed:run` - Executes seed files
+
+## Architecture Overview
+
+This is a Knex.js database module (`@dupin/knex-v2`) that provides a PostgreSQL connection manager and data access layer.
+
+**Key Components**:
+
+1. **KnexManager** (`src/KnexConnection.ts`): Singleton pattern for managing database connections
+   - Handles connection pooling with configurable min/max connections
+   - Uses environment variables for database configuration (SQL_HOST, SQL_USER, SQL_PASSWORD, SQL_DB_NAME, SQL_PORT)
+   - Supports SSL connections with `rejectUnauthorized: false`
+
+2. **DAO Pattern**: Data Access Objects implement the `IBaseDAO<T>` interface
+   - Example: `SundaysPackageVersionDAO` provides CRUD operations
+   - All DAOs use the shared KnexManager connection
+   - Includes pagination support via `IDataPaginator`
+
+3. **Database Configuration** (`knexfile.ts`): Supports development, staging, and production environments
+   - All environments use PostgreSQL client
+   - Configuration reads from environment variables
+   - Migration table: `knex_migrations`
+
+4. **Type System**: 
+   - Interfaces in `src/interfaces/` define data models
+   - Common types in `src/d.types.ts` (IBaseDAO, IDataPaginator)
+   - All exports centralized in `src/index.ts`
+
+**Environment Requirements**:
+- SQL_HOST: PostgreSQL host
+- SQL_USER: Database user
+- SQL_PASSWORD: Database password
+- SQL_DB_NAME: Database name
+- SQL_PORT: Database port (defaults to 5432)
+
+## DAO Implementation Patterns
+
+### Join Pattern for Related Entities
+
+When implementing DAOs that need to include related entities, use PostgreSQL's `to_jsonb()` function for clean and efficient joins:
+
+```typescript
+async getById(id: number): Promise<IEntity | null> {
+  const result = await this._knex("entity as e")
+    .leftJoin("related as r", "e.relatedId", "r.id")
+    .select("e.*", this._knex.raw("to_jsonb(r.*) as related"))
+    .where("e.id", id)
+    .first();
+  return result || null;
+}
+```
+
+**Key Points:**
+- Use table aliases for clarity (`as e`, `as r`)
+- `to_jsonb(r.*)` automatically converts the joined row to JSON
+- Returns `null` if no related entity is found (with leftJoin)
+- No manual mapping required - PostgreSQL handles the conversion
+
+**For paginated results:**
+```typescript
+const query = this._knex("entity as e")
+  .leftJoin("related as r", "e.relatedId", "r.id")
+  .select("e.*", this._knex.raw("to_jsonb(r.*) as related"));
+
+const data = await query
+  .clone()
+  .limit(limit)
+  .offset(offset)
+  .orderBy("e.id", "desc");
+```
+
+## Known Issues and Solutions
+
+**Migration Error "require is not defined"**: The knexfile.ts uses ES module syntax. If you encounter this error, ensure the file uses:
+- `import dotenv from "dotenv"` instead of `require("dotenv")`
+- `export default config` instead of `module.exports = config`

package/dist/templates/db-sql/knexfile.ts

@@ -0,0 +1,33 @@
+import type { Knex } from "knex";
+import dotenv from "dotenv";
+dotenv.config();
+
+const isLocalhost = process.env.SQL_HOST === 'localhost' || process.env.SQL_HOST === '127.0.0.1';
+const rejectUnauthorized = process.env.SQL_REJECT_UNAUTHORIZED !== 'false';
+
+const sharedConfig: Knex.Config = {
+  client: "postgresql",
+  connection: {
+    database: process.env.SQL_DB_NAME,
+    user: process.env.SQL_USER,
+    password: process.env.SQL_PASSWORD,
+    host: process.env.SQL_HOST,
+    port: process.env.SQL_PORT ? +process.env.SQL_PORT : 5432,
+    ssl: isLocalhost ? false : { rejectUnauthorized },
+  },
+  pool: {
+    min: 2,
+    max: 10,
+  },
+  migrations: {
+    tableName: "knex_migrations",
+  },
+};
+
+const config: { [key: string]: Knex.Config } = {
+  development: sharedConfig,
+  staging: sharedConfig,
+  production: sharedConfig,
+};
+
+export default config;

package/dist/templates/db-sql/migrations/001_create_sundays_package_version.ts

@@ -0,0 +1,13 @@
+import type { Knex } from "knex";
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.createTable("sundays_package_version", (table) => {
+    table.increments("id").primary();
+    table.string("versionName").notNullable();
+    table.timestamps(true, true); // created_at, updated_at
+  });
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.dropTableIfExists("sundays_package_version");
+}

package/dist/templates/db-sql/seeds/001_sundays_package_version_seed.ts

@@ -0,0 +1,11 @@
+import { Knex } from "knex";
+
+export async function seed(knex: Knex): Promise<void> {
+    // Deletes ALL existing entries
+    await knex("sundays_package_version").del();
+
+    // Inserts seed entries
+    await knex("sundays_package_version").insert([
+        { versionName: "1.0.0" }
+    ]);
+}

package/dist/templates/db-sql/src/KnexConnection.ts

@@ -0,0 +1,74 @@
+import { knex, Knex } from 'knex';
+
+class KnexManager {
+  private static knexInstance: Knex<any, unknown[]> | null = null;
+
+  /**
+   * Open a new connection. Reuse the already existing one if there's any.
+   */
+  static async connect(
+    config?: Knex.Config,
+    connections?: number
+  ): Promise<Knex<any, unknown[]>> {
+    if (!KnexManager.knexInstance) {
+      const isLocalhost = process.env.SQL_HOST === 'localhost' || process.env.SQL_HOST === '127.0.0.1';
+      const rejectUnauthorized = process.env.SQL_REJECT_UNAUTHORIZED !== 'false';
+      const defaultConfig = {
+        client: 'pg',
+        connection: {
+          host: process.env.SQL_HOST,
+          user: process.env.SQL_USER,
+          password: process.env.SQL_PASSWORD,
+          database: process.env.SQL_DB_NAME,
+          port: Number(process.env.SQL_PORT) || 5432,
+          ssl: isLocalhost ? false : { rejectUnauthorized },
+        },
+        pool: {
+          min: 1,
+          max: connections || 15,
+          idleTimeoutMillis: 20000,
+          acquireTimeoutMillis: 30000,
+        },
+        migrations: {
+          tableName: 'knex_migrations',
+        },
+      };
+      KnexManager.knexInstance = knex(config || defaultConfig);
+      try {
+        await KnexManager.knexInstance.raw('SELECT 1');
+        console.info(`Knex connection established`);
+      } catch (error) {
+        console.error(`Failed to establish Knex connection:`, error);
+        KnexManager.knexInstance = null;
+        throw error;
+      }
+    }
+
+    return KnexManager.knexInstance;
+  }
+
+  /**
+   * Returns the active connection.
+   */
+  static getConnection(): Knex<any, unknown[]> {
+    if (!KnexManager.knexInstance) {
+      throw new Error(
+        'Knex connection has not been established. Call connect() first.'
+      );
+    }
+    return KnexManager.knexInstance;
+  }
+
+  /**
+   * Closes the connection and destroys the instance.
+   */
+  static async disconnect(): Promise<void> {
+    if (KnexManager.knexInstance) {
+      await KnexManager.knexInstance.destroy();
+      KnexManager.knexInstance = null;
+      console.info(`Knex connection closed`);
+    }
+  }
+}
+
+export default KnexManager;

package/dist/templates/db-sql/src/d.types.ts

@@ -0,0 +1,18 @@
+export interface IBaseDAO<T> {
+    create(item: T): Promise<T>;
+    getById(id: number): Promise<T | null>;
+    getByUuid(uuid: string): Promise<T | null>;
+    update(id: number, item: Partial<T>): Promise<T | null>;
+    delete(id: number): Promise<boolean>;
+    getAll(page: number, limit: number): Promise<IDataPaginator<T>>;
+}
+
+export interface IDataPaginator<T> {
+    success: boolean;
+    data: T[];
+    page: number;
+    limit: number;
+    count: number;
+    totalCount: number;
+    totalPages: number;
+}

package/dist/templates/db-sql/src/dao/sundays-package-version/sundays-package-version.dao.ts

@@ -0,0 +1,71 @@
+import { Knex } from "knex";
+import { IBaseDAO, IDataPaginator } from "../../d.types";
+import { ISundaysPackageVersion } from "../../interfaces/sundays-package-version/sundays-package-version.interfaces";
+import KnexManager from "../../KnexConnection";
+
+export class SundaysPackageVersionDAO implements IBaseDAO<ISundaysPackageVersion> {
+    private _knex: Knex<any, unknown[]> = KnexManager.getConnection();
+
+    async create(item: ISundaysPackageVersion): Promise<ISundaysPackageVersion> {
+        const [created] = await this._knex("sundays_package_version").insert(item).returning("*");
+        return created;
+    }
+
+    async getById(id: number): Promise<ISundaysPackageVersion | null> {
+        const result = await this._knex("sundays_package_version")
+            .select("*")
+            .where("id", id)
+            .first();
+        return result || null;
+    }
+
+    async getByUuid(uuid: string): Promise<ISundaysPackageVersion | null> {
+        const result = await this._knex("sundays_package_version")
+            .select("*")
+            .where("uuid", uuid)
+            .first();
+        return result || null;
+    }
+
+    async update(id: number, item: Partial<ISundaysPackageVersion>): Promise<ISundaysPackageVersion | null> {
+        const [updated] = await this._knex("sundays_package_version")
+            .where({ id })
+            .update(item)
+            .returning("*");
+        return updated || null;
+    }
+
+    async delete(id: number): Promise<boolean> {
+        const result = await this._knex("sundays_package_version").where({ id }).del();
+        return result > 0;
+    }
+
+    async getAll(page: number, limit: number): Promise<IDataPaginator<ISundaysPackageVersion>> {
+        const safeLimit = Math.max(limit, 1);
+        const offset = (page - 1) * safeLimit;
+
+        const query = this._knex("sundays_package_version").select("*");
+
+        const [countResult] = await query.clone().clearSelect().count("* as count");
+        const totalCount = +countResult.count;
+        const data = await query.clone().limit(safeLimit).offset(offset).orderBy("id", "desc");
+
+        return {
+            success: true,
+            data,
+            page,
+            limit: safeLimit,
+            count: data.length,
+            totalCount,
+            totalPages: Math.ceil(totalCount / safeLimit),
+        };
+    }
+
+    async getLatestVersion(): Promise<ISundaysPackageVersion | null> {
+        const result = await this._knex("sundays_package_version")
+            .select("*")
+            .orderBy("id", "desc")
+            .first();
+        return result || null;
+    }
+}

package/dist/templates/db-sql/src/index.ts

@@ -0,0 +1,9 @@
+// DAOs
+export { SundaysPackageVersionDAO } from "./dao/sundays-package-version/sundays-package-version.dao";
+
+// Interfaces
+export { IDataPaginator } from "./d.types";
+export { ISundaysPackageVersion } from "./interfaces/sundays-package-version/sundays-package-version.interfaces";
+
+import KnexManager from './KnexConnection';
+export { KnexManager };

package/dist/templates/db-sql/src/interfaces/sundays-package-version/sundays-package-version.interfaces.ts

@@ -0,0 +1,6 @@
+export interface ISundaysPackageVersion {
+  id: number;
+  versionName: string;
+  createdAt: string;
+  updatedAt: string;
+}

package/dist/templates/db-sql/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "module": "CommonJS",
+    "target": "ES2022",
+    "sourceMap": true,
+    "esModuleInterop": true,
+    "strict": true,
+    "declaration": true,
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/dist/templates/module/CLAUDE.md

@@ -0,0 +1,159 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Module Template Overview
+
+This is a basic npm module template created by the Sundays Framework SDK. It provides a minimal starting point for creating reusable Node.js modules.
+
+## Commands
+
+### Development
+
+- `npm run build` - Compile TypeScript to JavaScript (output to dist/)
+- `npm test` - Run tests (no test framework configured by default)
+- `npm run format` - Format code (if Prettier is configured)
+
+### Publishing
+
+- `npm run npm:publish` - Publish the module to npm registry
+
+## Project Structure
+
+```
+module/
+├── src/           # TypeScript source files
+│   └── index.ts   # Main entry point
+├── dist/          # Compiled JavaScript output (generated)
+├── tsconfig.json  # TypeScript configuration
+├── package.json   # Module metadata and dependencies
+└── .gitignore     # Git ignore patterns
+```
+
+## Configuration
+
+### TypeScript Setup
+
+The module is configured with TypeScript for type safety:
+- Source files in `src/`
+- Compiled output to `dist/`
+- Strict mode enabled
+- ES2020 target with CommonJS modules
+- Declaration files generated for TypeScript consumers
+
+### Package.json
+
+Key fields to configure:
+- `name`: Your module name (scoped or unscoped)
+- `version`: Semantic version (start with 0.1.0)
+- `description`: Brief description of the module
+- `main`: Entry point (usually `dist/index.js`)
+- `types`: TypeScript declarations (usually `dist/index.d.ts`)
+- `author`: Your name or organization
+- `license`: License type (MIT, ISC, etc.)
+
+## Getting Started
+
+1. **Initialize the module**:
+   ```bash
+   npm install
+   ```
+
+2. **Write your module code** in `src/index.ts`:
+   ```typescript
+   export function myFunction() {
+     return "Hello from my module!";
+   }
+   
+   export class MyClass {
+     // Your implementation
+   }
+   ```
+
+3. **Build the module**:
+   ```bash
+   npm run build
+   ```
+
+4. **Test locally** before publishing:
+   ```bash
+   npm link
+   # In another project:
+   npm link your-module-name
+   ```
+
+5. **Publish to npm**:
+   ```bash
+   npm run npm:publish
+   ```
+
+## Best Practices
+
+1. **Export Strategy**: Use named exports for clarity
+   ```typescript
+   export { MyClass, myFunction, MyInterface };
+   ```
+
+2. **Type Definitions**: Always include TypeScript definitions
+   - Helps consumers with IntelliSense
+   - Prevents type-related bugs
+
+3. **Documentation**: Add JSDoc comments to exported functions/classes
+   ```typescript
+   /**
+    * Calculates the sum of two numbers
+    * @param a First number
+    * @param b Second number
+    * @returns The sum of a and b
+    */
+   export function add(a: number, b: number): number {
+     return a + b;
+   }
+   ```
+
+4. **Versioning**: Follow semantic versioning (semver)
+   - MAJOR: Breaking changes
+   - MINOR: New features (backward compatible)
+   - PATCH: Bug fixes
+
+5. **Testing**: Consider adding a test framework
+   - Jest for unit testing
+   - Include test scripts in package.json
+
+6. **Dependencies**: Keep dependencies minimal
+   - Use `dependencies` for runtime requirements
+   - Use `devDependencies` for build/test tools
+   - Consider marking some as `peerDependencies`
+
+## Common Module Patterns
+
+### Singleton Pattern
+```typescript
+class MySingleton {
+  private static instance: MySingleton;
+  
+  private constructor() {}
+  
+  static getInstance(): MySingleton {
+    if (!MySingleton.instance) {
+      MySingleton.instance = new MySingleton();
+    }
+    return MySingleton.instance;
+  }
+}
+```
+
+### Factory Pattern
+```typescript
+export function createInstance(config: Config): MyClass {
+  return new MyClass(config);
+}
+```
+
+### Plugin/Extension Pattern
+```typescript
+export interface Plugin {
+  name: string;
+  install(app: any): void;
+}
+```

package/dist/templates/module/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Sundays Framework Module
+ *
+ * Replace this with your module exports.
+ */
+
+export const hello = (): string => {
+  return 'Hello from Sundays module';
+};