@cbnventures/nova 0.14.0 → 0.15.1

package/build/templates/generators/must-haves/agent-conventions/PROJECT_RULES.md

@@ -0,0 +1,290 @@
+# PROJECT_RULES.md
+
+## Project Identity
+
+### Name and Description
+
+<!--
+The canonical project name, a one-line description, and the primary programming language.
+
+- **Project name:** Name
+- **Description:** One-line description.
+- **Primary language:** Language
+- **Framework / runtime:** Framework or runtime (e.g. Next.js, Express, SwiftUI, Spring Boot)
+-->
+
+### Repository URL
+
+<!--
+The full GitHub URL for this repository.
+
+- **URL:** https://github.com/owner/repo
+-->
+
+## Repository Layout
+
+<!--
+A top-level directory tree showing every folder at the first two levels. Annotate each entry with a short description. Files that live at the root level should also be listed.
+
+```
+repo-root/
+├── .github/              — GitHub Actions workflows, issue templates, funding
+├── docs/                 — Documentation site source (Docusaurus)
+├── src/                  — Application source code
+│   ├── lib/              — Shared libraries and utilities
+│   ├── cli/              — CLI entry points and commands
+│   ├── types/            — TypeScript type definitions (.d.ts)
+│   └── tests/            — Unit and integration tests
+├── scripts/              — Build, deploy, and maintenance scripts
+├── .editorconfig         — Editor formatting rules
+├── .gitignore            — Git ignore patterns
+├── CHANGELOG.md          — Release history
+├── LICENSE               — MIT license
+├── README.md             — Project overview and badges
+├── package.json          — Node.js manifest and scripts
+└── tsconfig.json         — TypeScript compiler configuration
+```
+-->
+
+## Source Structure
+
+<!--
+A detailed directory tree of the primary source folder (e.g. `src/`, `app/`, `lib/`). Go as deep as needed to show every module, grouped by domain. Annotate each file or folder with its responsibility.
+
+```
+src/
+├── cli/
+│   ├── commands/
+│   │   ├── build.ts      — `build` command handler
+│   │   └── publish.ts    — `publish` command handler
+│   └── index.ts          — CLI entry point, argument parsing
+├── lib/
+│   ├── config.ts         — Configuration loader and validator
+│   ├── schema.ts         — Zod schemas for external API responses
+│   └── regex.ts          — Shared regex patterns
+├── toolkit/
+│   ├── logger.ts         — Structured logging utility
+│   ├── markdown-table.ts — Markdown table builder
+│   └── index.ts          — Barrel exports for toolkit
+├── types/
+│   ├── cli/
+│   │   └── commands.d.ts — Types for CLI commands
+│   ├── lib/
+│   │   └── config.d.ts   — Types for configuration
+│   └── shared.d.ts       — Shared type aliases
+└── tests/
+    ├── cli/
+    │   └── commands.test.ts
+    └── lib/
+        └── config.test.ts
+```
+-->
+
+## Key Files
+
+<!--
+List the most important files a contributor or AI agent should know about. Include the file path, what it does, and when you would need to touch it.
+
+| File                | Purpose         | When to modify                                         |
+|---------------------|-----------------|--------------------------------------------------------|
+| `src/cli/index.ts`  | CLI entry point | Adding or changing CLI commands                        |
+| `src/lib/config.ts` | Config loader   | Changing configuration shape or defaults               |
+| `package.json`      | Manifest        | Adding dependencies, changing scripts, bumping version |
+| `tsconfig.json`     | TS config       | Changing compiler options or path aliases              |
+| `CHANGELOG.md`      | Release notes   | Every user-facing change                               |
+-->
+
+## Build and Tooling
+
+### Prerequisites
+
+<!--
+List every tool that must be installed before building, with minimum version requirements.
+
+| Tool    | Version | Purpose                     |
+|---------|---------|-----------------------------|
+| Node.js | >= 22.x | Runtime                     |
+| npm     | >= 10.x | Package manager             |
+| Docker  | >= 27.x | Container builds (optional) |
+-->
+
+### Commands
+
+<!--
+List every build, test, lint, and dev command available. Use the exact command the developer runs.
+
+| Command         | What it does                             |
+|-----------------|------------------------------------------|
+| `npm install`   | Install all dependencies                 |
+| `npm run build` | Compile TypeScript to JavaScript         |
+| `npm run dev`   | Start development server with hot reload |
+| `npm run lint`  | Run ESLint across the project            |
+| `npm test`      | Run the test suite                       |
+-->
+
+### Environment Variables
+
+<!--
+List every environment variable the project reads, its purpose, and whether it is required or optional.
+
+| Variable    | Required | Purpose                                   |
+|-------------|----------|-------------------------------------------|
+| `API_KEY`   | Yes      | Authentication token for the external API |
+| `LOG_LEVEL` | No       | Logging verbosity (default: `info`)       |
+-->
+
+## Workspace Rules
+
+### Naming Conventions
+
+<!--
+Summarize the naming rules that apply specifically to this project (beyond the universal conventions). Include examples.
+
+| Entity          | Convention        | Example                            |
+|-----------------|-------------------|------------------------------------|
+| CLI commands    | kebab-case verb   | `sync-packages`, `write-changelog` |
+| Config keys     | camelCase         | `workingDir`, `packageName`        |
+| Database tables | snake_case plural | `user_sessions`, `api_tokens`      |
+-->
+
+### Do / Don't
+
+<!--
+Project-specific rules that are not covered by the language convention files. These are guardrails for contributors and AI agents.
+
+**Do:**
+- Rule with rationale.
+- Rule with rationale.
+
+**Don't:**
+- Anti-pattern with explanation of why.
+- Anti-pattern with explanation of why.
+-->
+
+## Project-Specific Patterns
+
+### Architecture
+
+<!--
+Describe the high-level architecture pattern this project follows (e.g. layered, hexagonal, MVC, CLI pipeline). Include a diagram if helpful.
+
+```
+User Input
+  │
+  ▼
+CLI Layer (argument parsing, validation)
+  │
+  ▼
+Service Layer (business logic, orchestration)
+  │
+  ▼
+Data Layer (file I/O, API calls, database)
+```
+-->
+
+### Data Flow
+
+<!--
+Describe how data moves through the system from input to output. Name the key stages and the module responsible for each.
+
+1. **Input** — Where data enters (CLI args, HTTP request, file read). Module: `src/cli/index.ts`.
+2. **Validation** — How input is validated. Module: `src/lib/config.ts`.
+3. **Processing** — Core transformation or business logic. Module: `src/lib/processor.ts`.
+4. **Output** — Where results go (stdout, file write, API call). Module: `src/cli/index.ts`.
+-->
+
+### Error Strategy
+
+<!--
+How does this project handle errors at each layer? List the approach per layer.
+
+| Layer              | Strategy                                             |
+|--------------------|------------------------------------------------------|
+| CLI entry point    | Catch all, log, set `process.exitCode = 1`, return   |
+| Service functions  | Throw on failure (caller catches)                    |
+| External API calls | Zod `.parse()` for validation, try/catch for network |
+| File I/O           | try/catch, descriptive error message with file path  |
+-->
+
+## Documentation Site
+
+### Framework
+
+<!--
+Which documentation framework is used, and where its source lives.
+
+- **Framework:** Docusaurus / None
+- **Source directory:** `docs/`
+- **Build output:** `docs/build/`
+-->
+
+### Site Structure
+
+<!--
+A directory tree of the documentation source showing every page and sidebar category.
+
+```
+docs/
+├── docusaurus.config.ts  — Site configuration
+├── sidebars.ts           — Sidebar navigation structure
+├── docs/
+│   ├── intro.md          — Getting started guide
+│   ├── installation.md   — Installation instructions
+│   ├── configuration.md  — Configuration reference
+│   └── api/
+│       ├── overview.md   — API overview
+│       └── endpoints.md  — Endpoint reference
+└── static/
+    └── img/              — Static images
+```
+-->
+
+### Commands
+
+<!--
+Commands for building and previewing the documentation site locally.
+
+| Command              | What it does                           |
+|----------------------|----------------------------------------|
+| `npm run docs:dev`   | Start local dev server with hot reload |
+| `npm run docs:build` | Build the static site for production   |
+-->
+
+## Publishing and Deployment
+
+### Release Process
+
+<!--
+Step-by-step description of how a new version goes from code to release.
+
+1. All changes committed, `git status --short` is clean.
+2. Changelog consolidated, version bumped, build number recalculated (if applicable).
+3. Commit with version subject line.
+4. Tag the commit (e.g. `v1.2.0`).
+5. Push commit and tag.
+6. GitHub Release triggers CI workflows.
+-->
+
+### CI/CD Workflows
+
+<!--
+Map each GitHub Actions workflow to what it does and when it runs.
+
+| Workflow file               | Trigger           | What it does                     |
+|-----------------------------|-------------------|----------------------------------|
+| `publish-to-npm.yml`        | Release published | Build and publish to npm         |
+| `publish-to-docker-hub.yml` | Release published | Multi-arch Docker build and push |
+| `lock-inactive-issues.yml`  | Weekly cron       | Lock issues inactive > 30 days   |
+-->
+
+### Environments
+
+<!--
+List every deployment target and its URL or identifier.
+
+| Environment  | URL / Identifier                      | Purpose                 |
+|--------------|---------------------------------------|-------------------------|
+| npm          | `https://www.npmjs.com/package/name`  | Public package registry |
+| Docker Hub   | `https://hub.docker.com/r/owner/name` | Container registry      |
+| GitHub Pages | `https://owner.github.io/repo`        | Documentation site      |
+-->

package/build/templates/generators/must-haves/agent-conventions/VISION.md

@@ -0,0 +1,62 @@
+# VISION.md
+
+## Purpose
+
+### Problem Statement
+
+<!-- What specific problem, pain point, or unmet need does this project address? Be precise about the gap in existing solutions. -->
+
+### Target Audience
+
+<!--
+Who are the primary users of this project? List each audience segment and their relationship to the problem.
+
+- **Segment name** — Description of who they are and why they need this.
+- **Segment name** — Description of who they are and why they need this.
+-->
+
+### Value Proposition
+
+<!-- What makes this project the right solution? In 2-3 sentences, state what the project does and why it is better than the alternatives (or why no real alternative exists). -->
+
+## Marketing Copy
+
+### Tagline
+
+<!-- One sentence (under 15 words) that captures the essence of the project. This appears in social cards, repo descriptions, and badges. -->
+
+### Elevator Pitch
+
+<!-- A short paragraph (3-5 sentences) suitable for a README introduction, conference talk abstract, or landing page hero section. Cover what it does, who it is for, and one compelling differentiator. -->
+
+### Key Features
+
+<!--
+List the headline features a new user would care about most. Use action-oriented language.
+
+- **Feature name** — What it does and why it matters.
+- **Feature name** — What it does and why it matters.
+- **Feature name** — What it does and why it matters.
+-->
+
+### Differentiators
+
+<!--
+What sets this project apart from comparable tools or services? Focus on architectural decisions, performance characteristics, developer experience, or ecosystem fit.
+
+| This project                   | Alternatives                 |
+|--------------------------------|------------------------------|
+| Difference this project offers | What alternatives do instead |
+| Difference this project offers | What alternatives do instead |
+-->
+
+## Glossary
+
+<!--
+Define every domain-specific term, abbreviation, and concept used in this project. The AI agent and all contributors should use these terms consistently.
+
+| Term | Definition                                    |
+|------|-----------------------------------------------|
+| Term | What it means in the context of this project. |
+| Term | What it means in the context of this project. |
+-->

package/build/templates/generators/must-haves/agent-conventions/conventions/csharp.md

@@ -0,0 +1,317 @@
+# C# Conventions
+
+Quotes: Double (only option). Indentation: 4-space. File naming: PascalCase matching class name (e.g., `EntityRepository.cs`).
+
+## Documentation Style
+
+- Comment syntax: `///`
+- Padding tag: `<remarks>Since v1.0.0</remarks>` (XML doc tag)
+- Param format: `<param name="x">X</param>` (description matches the parameter name, capitalized, no trailing period inside XML tags)
+- Return format: `<returns>Type</returns>`
+- Blank `///` at top and bottom of every comment block.
+- No `@private` tag needed (access control is in the declaration).
+
+### Example
+
+```csharp
+///
+/// Entity Repository.
+///
+/// <remarks>Since v1.0.0</remarks>
+///
+public class EntityRepository {
+    ///
+    /// Entity Repository - Database.
+    ///
+    /// <remarks>Since v1.0.0</remarks>
+    ///
+    private readonly Database _database;
+
+    ///
+    /// Entity Repository - Constructor.
+    ///
+    /// <param name="database">Database</param>
+    ///
+    /// <remarks>Since v1.0.0</remarks>
+    ///
+    public EntityRepository(Database database) { ... }
+
+    ///
+    /// Entity Repository - Find By ID.
+    ///
+    /// <param name="id">ID</param>
+    ///
+    /// <returns>Entity?</returns>
+    ///
+    /// <remarks>Since v1.0.0</remarks>
+    ///
+    public async Task<Entity?> FindById(Guid id) { ... }
+}
+```
+
+## Code Style
+
+### Explicit Access Modifiers
+
+All class members require explicit `public`, `private`, `protected`, or `internal`. Never rely on C#'s default `private` for members or `internal` for types.
+
+```csharp
+// BAD — implicit private
+void ProcessData(string input) { ... }
+
+// GOOD — explicit modifier
+public void ProcessData(string input) { ... }
+private void ValidateInput(string input) { ... }
+```
+
+### `readonly` on Fields
+
+Use `readonly` for fields assigned once in the constructor, never reassigned after.
+
+```csharp
+// GOOD — assigned once, never reassigned
+private readonly Database _database;
+
+// No readonly — reassigned during lifecycle
+private string _selectedCategory;
+```
+
+### Method Overloads vs Generic Parameters
+
+Prefer overloads when the return type or behavior differs per input type. A single parameter type (e.g., `object`) is fine when the handling is identical regardless of input type.
+
+```csharp
+// GOOD — overloads (different behavior per type)
+private static string Format(string value) {
+    return value.Trim();
+}
+
+private static string Format(int value) {
+    return value.ToString("F2");
+}
+
+// GOOD — single param (same handling regardless)
+private static bool Validate(object value) {
+    return value != null;
+}
+```
+
+### Method Ordering
+
+1. Public methods first.
+2. Private methods second (async grouped, then non-async grouped).
+
+Each method separated by a blank line. No blank line after opening brace or before closing brace of the class.
+
+### Expression-Bodied Members
+
+Use expression body (`=>`) for single-expression methods, properties, and read-only accessors. Use block body for anything with multiple statements.
+
+```csharp
+// GOOD — expression-bodied property
+public string FullName => $"{FirstName} {LastName}";
+
+// GOOD — expression-bodied simple method
+public bool IsActive() => Status == Status.Active;
+
+// GOOD — block body for multiple statements
+public async Task<Entity?> FindById(Guid id) {
+    var entity = await _database.GetAsync(id);
+
+    return entity;
+}
+```
+
+### Switch Statements — Always Block-Scoped
+
+Every `case` and `default` uses block scoping with `{ }`. Always include a `default` case, even if there's nothing to handle. Prefer `switch` expressions with pattern matching where appropriate.
+
+```csharp
+switch (category) {
+    case "added": {
+        logger.Info("New feature.");
+        break;
+    }
+
+    case "fixed": {
+        logger.Info("Bug fix.");
+        break;
+    }
+
+    default: {
+        logger.Warn("Unknown category.");
+        break;
+    }
+}
+
+// Switch expression — acceptable for value mapping
+var label = category switch {
+    "added" => "New feature",
+    "fixed" => "Bug fix",
+    _ => "Unknown",
+};
+```
+
+### Explicit Null Checks — Avoid Optional Chaining
+
+Avoid `?.` chaining — prefer explicit null checks with early returns. Nullish coalescing (`??`) is fine for providing defaults. Don't combine them.
+
+```csharp
+// BAD — optional chaining
+var name = config?.Name;
+
+// GOOD — explicit check
+if (config == null) {
+    return;
+}
+
+var name = config.Name;
+
+// GOOD — null coalescing for defaults
+var timeout = options.Timeout ?? 5000;
+var label = config.Name ?? "default";
+
+// BAD — chained together
+var name = config?.Name ?? "default";
+```
+
+### `var` vs Explicit Type
+
+Use `var` when the type is obvious from the right-hand side. Use explicit types when the type is not immediately clear.
+
+```csharp
+// GOOD — type obvious from constructor/method
+var config = new Config();
+var items = GetItems();
+
+// GOOD — explicit type when not obvious
+List<string> names = ParseNames(rawInput);
+```
+
+### LINQ Method Syntax vs Query Syntax
+
+Prefer method syntax (`.Where()`, `.Select()`, `.FirstOrDefault()`). Query syntax is acceptable for complex joins.
+
+- `.Where()`, `.Select()`, `.FirstOrDefault()` — transforming or searching, returns a new value.
+- `foreach` — side effects (logging, mutating external collections, async operations).
+- `.Aggregate()` — acceptable, but `foreach` with a mutable accumulator is also fine.
+
+### Block Body vs Expression Body in Lambdas
+
+- **Block body** (`=> { ... }`): When accessing properties of the param, or when multiple statements needed.
+- **Expression body** (`=> expression`): When the lambda is a direct comparison or single method call.
+
+```csharp
+// Block body — accessing properties, multiple operations
+items.Select(item => {
+    var itemName = item.Name;
+    var itemRole = item.Role;
+
+    return new ItemResult(itemName, itemRole);
+});
+
+// Expression body — direct comparison
+validCategories.FirstOrDefault(
+    validCategory => validCategory == value
+);
+
+// Expression body — single property check
+items.Where(item => item.IsActive);
+```
+
+### Descriptive Lambda Parameter Names
+
+Derive from the collection name in singular form. Array and iterable variable names must end with a plural noun so the singular form can be derived naturally. No single-letter abbreviations.
+
+```csharp
+// BAD
+validCategories.Where(c => c == value);
+
+// GOOD
+validCategories.Where(validCategory => validCategory == value);
+```
+
+### Variable Names Chain from Parent
+
+When extracting properties from an object, the variable name chains from the parent variable name.
+
+```csharp
+var workspaceConfig = workspace.Config;
+var workspaceConfigName = workspaceConfig.Name;
+var workspaceConfigRole = workspaceConfig.Role;
+```
+
+### `async`/`await` Patterns
+
+Use `Task.WhenAll` for parallel execution. Suffix async methods with `Async`.
+
+```csharp
+// GOOD — parallel execution
+var (data, configRaw) = await (
+    FetchDataAsync(),
+    File.ReadAllTextAsync(configPath)
+);
+
+// GOOD — Async suffix convention
+public async Task<Entity?> FindByIdAsync(Guid id) { ... }
+private async Task<Config> LoadConfigAsync() { ... }
+```
+
+### Comment Placement in Method Bodies
+
+Comments describe the process/intent. Placement rules:
+- Comment sits above the code block it describes.
+- Blank line before the comment (except at the start of a scope).
+- No comment needed on the first block if it's self-explanatory.
+- No trailing comments (same-line comments after code). Exception: multi-line conditions may use inline `//` comments after each condition line to explain the check.
+
+### No Stacked Comments
+
+One descriptive comment per code block. No consecutive comments without code between them.
+
+### Quote File Names in Comments and Log Messages
+
+Wrap file names in double quotes inside comments and log strings (e.g., `"config.json"`, `"CHANGELOG.md"`).
+
+### Blank Lines between Distinct Operations
+
+Separate method calls, `await` statements, and different logical blocks with blank lines. Variable declarations and loops also need blank line separation.
+
+### Bare Side-Effect Statements Get Their Own Visual Group
+
+When a method call has no assignment (return value unused), separate it from surrounding assignments with a blank line.
+
+### Return Directly When Immediately Returned
+
+Don't assign to an intermediate variable just to return it on the next line.
+
+### Extract Nested Function Calls into Variables
+
+Don't nest function calls as arguments to other function calls. Extract into its own named variable for readability.
+
+### One Entry per Line in Collections
+
+Array initializers, list initializers, and similar collections use one entry per line in multiline constructs.
+
+### Mixed Logical Conditions
+
+When mixing `&&`/`||`, parenthesized groups go on their own lines, each condition on its own line.
+
+### No Multi-Line Boolean Variable Assignments for `if`
+
+Don't extract a multi-condition boolean into a named variable just to check it once. Inline conditions directly in `if` blocks.
+
+### Ternary Expressions
+
+- No nested ternaries.
+- No ternaries inside string interpolation — extract to a variable first.
+
+### Readability — All Generated Code Must Be Human-Readable
+
+Don't inline complex expressions into string interpolation or other expressions. Break them into named variables so each step is clear.
+
+### Error Handling
+
+- **Creator** (method designer): may design a method to throw on failure — that's the API contract.
+- **Consumer** (method caller): always wraps calls to throwing methods in try/catch.
+- CLI entry points never throw — set the appropriate exit code with `Environment.ExitCode` and return.