@lousy-agents/cli 2.2.0 → 2.3.0

package/api/copilot-with-fastify/biome.json

@@ -1,6 +1,6 @@
 {
     "root": false,
-    "$schema": "https://biomejs.dev/schemas/2.3.11/schema.json",
+    "$schema": "https://biomejs.dev/schemas/2.3.13/schema.json",
     "vcs": {
         "enabled": true,
         "clientKind": "git",

package/cli/copilot-with-citty/.devcontainer/devcontainer.json

@@ -0,0 +1,76 @@
+{
+    "name": "<%= it.projectName %>",
+    "image": "mcr.microsoft.com/devcontainers/javascript-node:24-bookworm",
+    "features": {
+        "ghcr.io/devcontainers/features/github-cli:1": {
+            "version": "2.83.2"
+        },
+        "ghcr.io/rocker-org/devcontainer-features/apt-packages:1": {
+            "packages": "yamllint, shellcheck",
+            "upgradePackages": true
+        },
+        "ghcr.io/devcontainers-extra/features/actionlint:1": {
+            "version": "1.7.9"
+        }
+    },
+    "forwardPorts": [],
+    "postCreateCommand": "npm cache add @upstash/context7-mcp @modelcontextprotocol/server-sequential-thinking",
+    "waitFor": "postCreateCommand",
+    "remoteUser": "node",
+    "customizations": {
+        "vscode": {
+            "extensions": [
+                "biomejs.biome",
+                "editorconfig.editorconfig",
+                "vitest.explorer",
+                "ms-vscode-remote.remote-containers",
+                "GitHub.codespaces",
+                "GitHub.Copilot",
+                "GitHub.Copilot-Chat",
+                "GitHub.github-vscode-theme",
+                "redhat.vscode-yaml"
+            ],
+            "settings": {
+                "editor.formatOnSave": true,
+                "editor.defaultFormatter": "biomejs.biome",
+                "[json]": {
+                    "editor.defaultFormatter": "biomejs.biome"
+                },
+                "[javascript]": {
+                    "editor.defaultFormatter": "biomejs.biome"
+                },
+                "[typescript]": {
+                    "editor.defaultFormatter": "biomejs.biome"
+                },
+                "[yaml]": {
+                    "editor.defaultFormatter": "redhat.vscode-yaml",
+                    "editor.tabSize": 2
+                },
+                "vitest.enable": true,
+                "vitest.commandLine": "vitest",
+                "github.copilot.chat.agent.model": "claude-sonnet-4.5",
+                "github.copilot.chat.ask.model": "claude-sonnet-4.5",
+                "yaml.schemas": {
+                    "https://json.schemastore.org/github-workflow.json": ".github/workflows/*.yml"
+                },
+                "github.copilot.chat.mcp.enabled": true
+            },
+            "mcp": {
+                "servers": {
+                    "context7": {
+                        "type": "stdio",
+                        "command": "npx",
+                        "args": ["-y", "@upstash/context7-mcp"]
+                    },
+                    "sequential-thinking": {
+                        "command": "npx",
+                        "args": [
+                            "-y",
+                            "@modelcontextprotocol/server-sequential-thinking"
+                        ]
+                    }
+                }
+            }
+        }
+    }
+}

package/cli/copilot-with-citty/.editorconfig

@@ -0,0 +1,16 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+max_line_length = off
+trim_trailing_whitespace = true
+
+[{*.json}]
+indent_size = 4
+
+[{*.yaml,*.yml}]
+indent_size = 2

package/cli/copilot-with-citty/.github/ISSUE_TEMPLATE/feature-to-spec.yml

@@ -0,0 +1,54 @@
+---
+name: Copilot Feature To Spec
+description: Create a spec for the Copilot coding agent.
+title: "[Spec]: "
+labels: ["copilot-ready", "enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Copilot Specification
+        Please fill out the details below.
+        This structure is parsed by the Copilot Agent.
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Context & Goal
+      description: What is the goal? What part of the codebase?
+      placeholder: |
+        We need to add a new command to the CLI
+        tool...
+    validations:
+      required: true
+
+  - type: textarea
+    id: acceptance-criteria
+    attributes:
+      label: Acceptance Criteria
+      description: How will we verify this is done?
+      placeholder: |
+        I run `npm run dev -- my-command`.
+        I see the expected output.
+    validations:
+      required: true
+
+  # ---------------------------------------------------------
+  # This section triggers the GitHub Script integration
+  # ---------------------------------------------------------
+  - type: textarea
+    id: extra-instructions
+    attributes:
+      label: Extra Instructions
+      description: Specific prompt engineering for the agent. This will be posted as a comment to guide the bot.
+      value: |
+        1. Review .github/instructions/spec.instructions.md for more details and use this as your guide for the feature specification.
+        2. Ensure you review all other repository instructions before starting work to understand engineering requirements.
+        3. Create your final spec output in the .github/specs directory and ensure requirements are captured in the EARS format.
+        4. Create a data flow diagram and sequence diagram to illustrate the feature's operation.
+        5. Break down the feature into manageable tasks with clear descriptions.
+        6. As you complete each task in the spec, mark the checkboxes as complete in the spec file using [x] notation.
+        7. If you need to make assumptions, ask questions on the issue.
+        8. Use the diagrams to inform your implementation plan.
+    validations:
+      required: false

package/cli/copilot-with-citty/.github/copilot-instructions.md

@@ -0,0 +1,228 @@
+---
+applyTo: "**"
+---
+
+# CLI Application
+
+A TypeScript CLI application using citty for command handling and consola for terminal output, following Test-Driven Development, Clean Architecture, and strict validation workflows.
+
+## Commands
+
+Run `nvm use` before any npm command. During development, use file-scoped commands for faster feedback, and run the full validation suite (`npx biome check && npm test && npm run build`) before commits.
+
+```bash
+# ALWAYS run first
+nvm use
+
+# Core commands
+npm install              # Install deps (updates package-lock.json)
+npm test                 # Run tests (vitest)
+npm run build            # Production build
+npm run dev              # Start development with hot reload
+npx biome check          # Lint check
+npx biome check --write  # Auto-fix lint/format
+
+# File-scoped (faster feedback)
+npx biome check path/to/file.ts
+npm test path/to/file.test.ts
+
+# Validation suite (run before commits)
+npx biome check && npm test && npm run build
+
+# Other
+npm audit                # Security check
+npm run lint:workflows   # Validate GitHub Actions (actionlint)
+npm run lint:yaml        # Validate YAML (yamllint)
+```
+
+## Workflow: TDD Required
+
+Follow this exact sequence for ALL code changes. Work in small increments — make one change at a time and validate before proceeding.
+
+1. **Research**: Search codebase for existing patterns, commands, utilities. Use Context7 MCP tools for library/API documentation.
+2. **Write failing test**: Create test describing desired behavior
+3. **Verify failure**: Run `npm test` — confirm clear failure message
+4. **Implement minimal code**: Write just enough to pass
+5. **Verify pass**: Run `npm test` — confirm pass
+6. **Refactor**: Clean up, remove duplication, keep tests green
+7. **Validate**: `npx biome check && npm test && npm run build`
+
+Task is NOT complete until all validation passes.
+
+## Tech Stack
+
+- **Framework**: citty — lightweight CLI framework with command definitions and argument parsing
+- **Language**: TypeScript (strict mode)
+- **Terminal Output**: consola — elegant console logging with levels and formatting
+- **Validation**: Zod for runtime validation of external data
+- **Testing**: Vitest (never Jest), Chance.js for test fixtures
+- **Linting**: Biome (never ESLint/Prettier separately)
+- **HTTP**: fetch API only (for external service calls)
+- **Architecture**: Clean Architecture principles
+
+## Project Structure
+
+```
+.github/           GitHub Actions workflows
+src/               Application source code
+  entities/        Layer 1: Business domain entities
+  use-cases/       Layer 2: Application business rules
+  gateways/        Layer 3: External system adapters
+  commands/        Layer 3: CLI command handlers
+  lib/             Utilities and helpers
+  index.ts         Application entry point
+tests/             Test files (mirror src/ structure)
+.nvmrc             Node.js version (latest LTS)
+```
+
+## Code Style
+
+```typescript
+import { defineCommand } from 'citty';
+import { consola } from 'consola';
+import { z } from 'zod';
+
+// Define schema for runtime validation
+const ConfigSchema = z.object({
+  name: z.string(),
+  version: z.string(),
+});
+
+type Config = z.infer<typeof ConfigSchema>;
+
+// ✅ Good - small, typed, single purpose, descriptive names, runtime validation
+async function loadConfig(filePath: string): Promise<Config> {
+  if (!filePath) {
+    throw new Error('File path required');
+  }
+
+  const content = await readFile(filePath, 'utf-8');
+  const data: unknown = JSON.parse(content);
+  return ConfigSchema.parse(data);
+}
+
+// ❌ Bad - untyped, no validation, multiple responsibilities
+async function doStuff(x) {
+  console.log('loading');
+  const data = JSON.parse(await readFile(x));
+  return data as Config;
+}
+```
+
+**Rules:**
+- Always use TypeScript type hints
+- Use descriptive names for variables, functions, and modules
+- Functions must be small and have single responsibility
+- Avoid god functions and classes — break into smaller, focused units
+- Avoid repetitive code — extract reusable functions
+- Extract functions when there are multiple code paths
+- Favor immutability and pure functions
+- Avoid temporal coupling
+- Keep cyclomatic complexity low
+- Remove all unused imports and variables
+- Validate external data at runtime with Zod — never use type assertions (`as Type`) on API responses
+- Run lint and tests after EVERY change
+
+## Testing Standards
+
+Tests are executable documentation. Use Arrange-Act-Assert pattern. Generate test fixtures with Chance.js.
+
+```typescript
+import Chance from 'chance';
+import { describe, it, expect, vi } from 'vitest';
+import { createConfigLoader } from './config-loader';
+
+const chance = new Chance();
+
+// ✅ Good - describes behavior, uses generated fixtures, mocks dependencies
+describe('Config Loader', () => {
+  describe('given a valid config file path', () => {
+    it('loads and validates the configuration', async () => {
+      // Arrange
+      const configPath = chance.word() + '.json';
+      const expectedConfig = {
+        name: chance.word(),
+        version: chance.semver(),
+      };
+      const mockReader = vi.fn().mockResolvedValue(JSON.stringify(expectedConfig));
+      const loader = createConfigLoader(mockReader);
+
+      // Act
+      const result = await loader.load(configPath);
+
+      // Assert
+      expect(result).toEqual(expectedConfig);
+      expect(mockReader).toHaveBeenCalledWith(configPath);
+    });
+  });
+
+  describe('given an empty file path', () => {
+    it('throws a validation error', async () => {
+      // Arrange
+      const mockReader = vi.fn();
+      const loader = createConfigLoader(mockReader);
+
+      // Act & Assert
+      await expect(loader.load('')).rejects.toThrow('File path required');
+    });
+  });
+});
+```
+
+**Rules:**
+- Tests are executable documentation — describe behavior, not implementation
+- Name `describe` blocks for features/scenarios, not function names
+- Name `it` blocks as specifications that read as complete sentences
+- Use nested `describe` blocks for "given/when" context
+- Use Chance.js to generate test fixtures — avoid hardcoded test data
+- Extract test data to constants — never duplicate values across arrange/act/assert
+- Use Vitest (never Jest)
+- Follow Arrange-Act-Assert pattern
+- Tests must be deterministic — same result every run
+- Avoid conditional logic in tests unless absolutely necessary
+- Ensure all code paths have corresponding tests
+- Test happy paths, unhappy paths, and edge cases
+- Never modify tests to pass without understanding root cause
+
+## Dependencies
+
+- Use latest LTS Node.js — check with `nvm ls-remote --lts`, update `.nvmrc`
+- Pin ALL dependencies to exact versions (no ^ or ~)
+- Use explicit version numbers when adding new dependencies
+- Search npm for latest stable version before adding
+- Run `npm audit` after any dependency change
+- Ensure `package-lock.json` is updated correctly
+- Use Dependabot to keep dependencies current
+
+## GitHub Actions
+
+- Validation must be automated via GitHub Actions and runnable locally the same way
+- Validate all workflows using actionlint
+- Validate all YAML files using yamllint
+- Pin all 3rd party Actions to specific version or commit SHA
+- Keep all 3rd party Actions updated to latest version
+
+## Boundaries
+
+**✅ Always do:**
+- Run `nvm use` before any npm command
+- Write tests before implementation (TDD)
+- Run lint and tests after every change
+- Run full validation before commits
+- Use existing patterns from codebase
+- Work in small increments
+- Validate all external data with Zod
+- Use Context7 MCP tools for code generation and documentation
+
+**⚠️ Ask first:**
+- Adding new dependencies
+- Changing project structure
+- Modifying GitHub Actions workflows
+
+**🚫 Never do:**
+- Skip the TDD workflow
+- Store secrets in code (use environment variables)
+- Use Jest (use Vitest)
+- Modify tests to pass without fixing root cause
+- Add dependencies without explicit version numbers
+- Use type assertions (`as Type`) on external/API data

package/cli/copilot-with-citty/.github/instructions/pipeline.instructions.md

@@ -0,0 +1,92 @@
+---
+applyTo: ".github/workflows/*.{yml,yaml}"
+---
+
+# Pipeline Instructions for CLI
+
+## MANDATORY: After Modifying Workflows
+
+Run these validation commands in order:
+
+```bash
+npm run lint:workflows  # Validate GitHub Actions workflows with actionlint
+npm run lint:yaml       # Validate YAML syntax with yamllint
+```
+
+## Workflow Structure Requirements
+
+1. Every workflow MUST include test and lint jobs.
+2. Reference Node.js version from `.nvmrc` using `actions/setup-node` with `node-version-file` input.
+3. Use official setup actions: `actions/checkout`, `actions/setup-node`, `actions/cache`.
+
+## Action Pinning Format
+
+Pin ALL third-party actions to exact commit SHA with version comment:
+
+```yaml
+# CORRECT format:
+uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11  # v4.1.1
+
+# INCORRECT formats (do NOT use):
+uses: actions/checkout@v4        # ❌ version tag only
+uses: actions/checkout@v4.1.1    # ❌ version tag only
+uses: actions/checkout@main      # ❌ branch reference
+```
+
+Before adding any action:
+1. Check GitHub for the LATEST stable version
+2. Find the full commit SHA for that version
+3. Add both SHA and version comment
+
+## Runner Requirements
+
+| Workflow | Runner |
+|----------|--------|
+| Default (all workflows) | `ubuntu-latest` |
+
+## Example CI Workflow
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4.4.0
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+      - run: npm ci
+      - run: npx biome check
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4.4.0
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm test
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4.4.0
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run build
+```

package/cli/copilot-with-citty/.github/instructions/software-architecture.instructions.md

@@ -0,0 +1,166 @@
+---
+applyTo: "src/**/*.ts"
+---
+
+# Clean Architecture Instructions for CLI
+
+## The Dependency Rule
+
+Dependencies point inward only. Outer layers depend on inner layers, never the reverse.
+
+**Layers (innermost to outermost):**
+1. Entities — Enterprise business rules
+2. Use Cases — Application business rules
+3. Adapters — Interface converters (commands, gateways)
+4. Infrastructure — Frameworks, drivers, composition root
+
+## Directory Structure
+
+```
+src/
+├── entities/                  # Layer 1: Business domain entities
+├── use-cases/                 # Layer 2: Application business rules
+├── gateways/                  # Layer 3: External system adapters (file system, APIs)
+├── commands/                  # Layer 3: CLI command handlers
+├── lib/                       # Layer 3: Configuration and utilities
+└── index.ts                   # Layer 4: Composition root
+```
+
+## Layer 1: Entities
+
+**Location:** `src/entities/`
+
+- MUST NOT import from any other layer
+- MUST NOT depend on frameworks or infrastructure
+- MUST NOT use non-deterministic or side-effect-producing global APIs (e.g., `crypto.randomUUID()`, `Date.now()`)
+- MUST be plain TypeScript objects/classes with business logic
+- MAY contain validation and business rules
+
+```typescript
+// src/entities/project.ts
+export interface Project {
+  readonly name: string;
+  readonly version: string;
+  readonly type: ProjectType;
+}
+
+export type ProjectType = 'cli' | 'webapp' | 'api';
+
+export function isValidProjectName(name: string): boolean {
+  return /^[a-z][a-z0-9._-]*$/.test(name) && name.length <= 214;
+}
+```
+
+## Layer 2: Use Cases
+
+**Location:** `src/use-cases/`
+
+- MUST only import from entities and ports (interfaces)
+- MUST define input/output DTOs
+- MUST define ports for external dependencies
+- MUST NOT import concrete implementations
+
+```typescript
+// src/use-cases/initialize-project.ts
+import type { Project } from '../entities/project';
+
+export interface InitializeProjectInput {
+  name: string;
+  type: string;
+}
+
+export interface ProjectGateway {
+  createStructure(project: Project): Promise<void>;
+}
+
+export class InitializeProjectUseCase {
+  constructor(private readonly gateway: ProjectGateway) {}
+
+  async execute(input: InitializeProjectInput): Promise<void> {
+    if (!input.name) {
+      throw new Error('Project name is required');
+    }
+    await this.gateway.createStructure({
+      name: input.name,
+      version: '0.1.0',
+      type: input.type as any,
+    });
+  }
+}
+```
+
+## Layer 3: Adapters
+
+**Location:** `src/commands/`, `src/gateways/`, and `src/lib/`
+
+- MUST implement ports defined by use cases
+- MAY import from entities and use cases
+- MAY use framework-specific code
+- MUST NOT contain business logic
+
+```typescript
+// src/commands/init.ts
+import { defineCommand } from 'citty';
+import { consola } from 'consola';
+
+export const initCommand = defineCommand({
+  meta: {
+    name: 'init',
+    description: 'Initialize a new project',
+  },
+  args: {
+    name: { type: 'string', description: 'Project name' },
+  },
+  async run({ args }) {
+    consola.info(`Initializing project: ${args.name}`);
+    // Delegate to use case
+  },
+});
+```
+
+## Layer 4: Infrastructure
+
+**Location:** `src/index.ts` (composition root)
+
+- Composition root wires dependencies
+- MAY import from all layers
+
+```typescript
+// src/index.ts
+import { defineCommand, runMain } from 'citty';
+import { initCommand } from './commands/init';
+
+const main = defineCommand({
+  meta: { name: 'my-cli', description: 'My CLI tool' },
+  subCommands: { init: initCommand },
+});
+
+runMain(main);
+```
+
+## Import Rules Summary
+
+| From | Entities | Use Cases | Commands/Gateways/Lib | Index (Root) |
+|------|----------|-----------|----------------------|--------------|
+| Entities | ✓ | ✗ | ✗ | ✗ |
+| Use Cases | ✓ | ✓ | ✗ | ✗ |
+| Commands/Gateways/Lib | ✓ | ✓ | ✓ | ✗ |
+| Index (Root) | ✓ | ✓ | ✓ | ✓ |
+
+## Anti-Patterns
+
+**Anemic Domain Model:** Entities as data-only containers with logic in services. Put business rules in entities.
+
+**Leaky Abstractions:** Ports exposing framework types. Use domain concepts only.
+
+**Business Logic in Adapters:** Validation rules or decisions in commands. Move to entities/use cases.
+
+**Framework Coupling:** Use cases accepting CLI `args` objects. Use plain DTOs.
+
+## Code Review Checklist
+
+- Entities have zero imports from other layers
+- Use cases define ports for all external dependencies
+- Adapters implement ports, contain no business logic
+- Only composition root instantiates concrete implementations
+- Use cases testable with simple mocks (no file system, no HTTP)