@mindfoldhq/trellis 0.1.3 → 0.1.5

package/dist/.trellis/structure/backend/directory-structure.md

@@ -1,209 +0,0 @@
-# Directory Structure
-
-> How backend/CLI code is organized in this project.
-
----
-
-## Overview
-
-This project is a **TypeScript CLI tool** using ES modules. The source code follows a **dogfooding architecture** - Trellis uses its own configuration files (`.cursor/`, `.claude/`, `.trellis/`) as templates for new projects.
-
----
-
-## Directory Layout
-
-```
-src/
-├── cli/                 # CLI entry point and argument parsing
-│   └── index.ts         # Main CLI entry (Commander.js setup)
-├── commands/            # Command implementations
-│   └── init.ts          # Each command in its own file
-├── configurators/       # Configuration generators
-│   ├── claude.ts        # Copies .claude/ directory
-│   ├── cursor.ts        # Copies .cursor/ directory
-│   ├── opencode.ts      # OpenCode configuration (TODO)
-│   └── workflow.ts      # Creates .trellis/ structure
-├── constants/           # Shared constants and paths
-│   └── paths.ts         # Path constants (centralized)
-├── templates/           # Template utilities and generic templates
-│   ├── markdown/        # Generic markdown templates
-│   │   ├── structure/   # Structure templates (*.md.txt)
-│   │   ├── init-agent.md    # Project root file template
-│   │   ├── agents.md        # Project root file template
-│   │   ├── worktree.yaml.txt # Generic worktree config
-│   │   └── index.ts     # Template exports
-│   └── extract.ts       # Template extraction utilities
-├── types/               # TypeScript type definitions
-│   └── ai-tools.ts      # AI tool types and registry
-├── utils/               # Shared utility functions
-│   ├── file-writer.ts   # File writing with conflict handling
-│   └── project-detector.ts # Project type detection
-└── index.ts             # Package entry point (exports public API)
-```
-
-### Dogfooding Directories (Project Root)
-
-These directories are copied to `dist/` during build and used as templates:
-
-```
-.cursor/                 # Cursor configuration (dogfooded)
-├── commands/            # Slash commands for Cursor
-│   ├── start.md
-│   ├── finish-work.md
-│   └── ...
-
-.claude/                 # Claude Code configuration (dogfooded)
-├── commands/            # Slash commands
-├── agents/              # Multi-agent pipeline agents
-├── hooks/               # Context injection hooks
-└── settings.json        # Hook configuration
-
-.trellis/                # Trellis workflow (partially dogfooded)
-├── scripts/             # Shell scripts (dogfooded)
-│   ├── common/          # Shared utilities
-│   ├── multi-agent/     # Pipeline scripts
-│   └── *.sh             # Main scripts
-├── agent-traces/        # Developer progress tracking
-│   └── index.md         # Index template (dogfooded)
-├── structure/           # Project guidelines (NOT dogfooded)
-│   ├── backend/         # Backend development docs
-│   ├── frontend/        # Frontend development docs
-│   └── guides/          # Thinking guides
-├── workflow.md          # Workflow documentation (dogfooded)
-├── worktree.yaml        # Worktree config (Trellis-specific)
-└── .gitignore           # Git ignore rules (dogfooded)
-```
-
----
-
-## Dogfooding Architecture
-
-### What is Dogfooded
-
-Files that are copied directly from Trellis project to user projects:
-
-| Source | Destination | Description |
-|--------|-------------|-------------|
-| `.cursor/` | `.cursor/` | Entire directory copied |
-| `.claude/` | `.claude/` | Entire directory copied |
-| `.trellis/scripts/` | `.trellis/scripts/` | All scripts copied |
-| `.trellis/workflow.md` | `.trellis/workflow.md` | Direct copy |
-| `.trellis/.gitignore` | `.trellis/.gitignore` | Direct copy |
-| `.trellis/agent-traces/index.md` | `.trellis/agent-traces/index.md` | Direct copy |
-
-### What is NOT Dogfooded
-
-Files that use generic templates (in `src/templates/`):
-
-| Template Source | Destination | Reason |
-|----------------|-------------|--------|
-| `src/templates/markdown/structure/**/*.md.txt` | `.trellis/structure/**/*.md` | User fills with project-specific content |
-| `src/templates/markdown/worktree.yaml.txt` | `.trellis/worktree.yaml` | Language-agnostic template |
-| `src/templates/markdown/init-agent.md` | `init-agent.md` | Project root file |
-| `src/templates/markdown/agents.md` | `AGENTS.md` | Project root file |
-
-### Build Process
-
-```bash
-# scripts/copy-templates.js copies dogfooding sources to dist/
-pnpm build
-
-# Result:
-dist/
-├── .cursor/           # From project root .cursor/
-├── .claude/           # From project root .claude/
-├── .trellis/          # From project root .trellis/ (filtered)
-│   ├── scripts/       # All scripts
-│   ├── agent-traces/
-│   │   └── index.md   # Only index.md, no developer subdirs
-│   ├── workflow.md
-│   ├── worktree.yaml
-│   └── .gitignore
-└── templates/         # From src/templates/ (no .ts files)
-    └── markdown/
-        └── structure/ # Generic templates
-```
-
----
-
-## Module Organization
-
-### Layer Responsibilities
-
-| Layer | Directory | Responsibility |
-|-------|-----------|----------------|
-| CLI | `cli/` | Parse arguments, display help, call commands |
-| Commands | `commands/` | Implement CLI commands, orchestrate actions |
-| Configurators | `configurators/` | Copy/generate configuration for tools |
-| Templates | `templates/` | Extract template content, provide utilities |
-| Types | `types/` | TypeScript type definitions |
-| Utils | `utils/` | Reusable utility functions |
-| Constants | `constants/` | Shared constants (paths, names) |
-
-### Configurator Pattern
-
-Configurators use `cpSync` for direct directory copy (dogfooding):
-
-```typescript
-// configurators/cursor.ts
-export async function configureCursor(cwd: string): Promise<void> {
-  const sourcePath = getCursorSourcePath(); // dist/.cursor/ or .cursor/
-  const destPath = path.join(cwd, ".cursor");
-  cpSync(sourcePath, destPath, { recursive: true });
-}
-```
-
-### Template Extraction
-
-`extract.ts` provides utilities for reading dogfooded files:
-
-```typescript
-// Get path to .trellis/ (works in dev and production)
-getTrellisSourcePath(): string
-
-// Read file from .trellis/
-readTrellisFile(relativePath: string): string
-
-// Copy directory from .trellis/ with executable scripts
-copyTrellisDir(srcRelativePath: string, destPath: string, options?: { executable?: boolean }): void
-```
-
----
-
-## Naming Conventions
-
-### Files and Directories
-
-| Convention | Example | Usage |
-|------------|---------|-------|
-| `kebab-case` | `file-writer.ts` | All TypeScript files |
-| `kebab-case` | `multi-agent/` | All directories |
-| `*.ts` | `init.ts` | TypeScript source files |
-| `*.md.txt` | `index.md.txt` | Template files for markdown |
-| `*.yaml.txt` | `worktree.yaml.txt` | Template files for yaml |
-
-### Why `.txt` Extension for Templates
-
-Templates use `.txt` extension to:
-- Prevent IDE markdown preview from rendering templates
-- Make clear these are template sources, not actual docs
-- Avoid confusion with actual markdown files
-
----
-
-## DO / DON'T
-
-### DO
-
-- Dogfood from project's own config files when possible
-- Use `cpSync` for copying entire directories
-- Keep generic templates in `src/templates/markdown/`
-- Use `.md.txt` or `.yaml.txt` for template files
-- Update dogfooding sources (`.cursor/`, `.claude/`, `.trellis/scripts/`) when making changes
-
-### DON'T
-
-- Don't hardcode file lists - copy entire directories instead
-- Don't duplicate content between templates and dogfooding sources
-- Don't put project-specific content in generic templates
-- Don't use dogfooding for structure/ (users fill these in)

package/dist/.trellis/structure/backend/error-handling.md

@@ -1,278 +0,0 @@
-# Error Handling
-
-> How errors are handled in this CLI project.
-
----
-
-## Overview
-
-This CLI project uses a **top-level catch pattern** where errors bubble up to command handlers and are displayed to users with colored output. The approach prioritizes user-friendly error messages while maintaining proper exit codes for scripting.
-
----
-
-## Error Handling Strategy
-
-### Top-Level Catch Pattern
-
-All command actions are wrapped in try-catch at the CLI level:
-
-```typescript
-// cli/index.ts
-program
-  .command("init")
-  .action(async (options: Record<string, unknown>) => {
-    try {
-      await init(options);
-    } catch (error) {
-      console.error(
-        chalk.red("Error:"),
-        error instanceof Error ? error.message : error,
-      );
-      process.exit(1);
-    }
-  });
-```
-
-### Key Principles
-
-1. **Let errors bubble up** - Don't catch errors in utility functions unless you can handle them meaningfully
-2. **Type guard for error messages** - Always use `error instanceof Error ? error.message : error`
-3. **Exit with code 1** - All errors should result in `process.exit(1)` for scripting
-4. **User-friendly messages** - Display only the message, not the full stack trace
-
----
-
-## Error Patterns
-
-### Pattern 1: Top-Level Command Catch
-
-Used at the CLI command level to catch all errors:
-
-```typescript
-.action(async (options) => {
-  try {
-    await commandAction(options);
-  } catch (error) {
-    console.error(
-      chalk.red("Error:"),
-      error instanceof Error ? error.message : error,
-    );
-    process.exit(1);
-  }
-});
-```
-
-### Pattern 2: Silent Failure for Optional Operations
-
-When an operation is optional and failure is acceptable:
-
-```typescript
-// Git config might not be available
-let developerName: string | undefined;
-try {
-  developerName = execSync("git config user.name", {
-    encoding: "utf-8",
-  }).trim();
-} catch {
-  // Git not available or no user.name configured - silently ignore
-}
-```
-
-### Pattern 3: Graceful Degradation with Warning
-
-When operation fails but we can continue:
-
-```typescript
-try {
-  execSync(`bash "${scriptPath}" "${developerName}"`, { cwd, stdio: "inherit" });
-  developerInitialized = true;
-} catch (error) {
-  console.log(
-    chalk.yellow(
-      `Warning: Failed to initialize developer: ${error instanceof Error ? error.message : error}`,
-    ),
-  );
-  // Continue without developer initialization
-}
-```
-
-### Pattern 4: Return-Based Error Signaling
-
-For functions that check conditions, return a result object or boolean:
-
-```typescript
-function checkPackageJson(cwd: string): { hasFrontend: boolean; hasBackend: boolean } {
-  if (!fs.existsSync(packageJsonPath)) {
-    return { hasFrontend: false, hasBackend: false };
-  }
-
-  try {
-    const content = fs.readFileSync(packageJsonPath, "utf-8");
-    const pkg = JSON.parse(content);
-    // ... analysis logic
-    return { hasFrontend, hasBackend };
-  } catch {
-    return { hasFrontend: false, hasBackend: false };
-  }
-}
-```
-
----
-
-## Type Guard for Errors
-
-Always use the type guard pattern when accessing error properties:
-
-```typescript
-// Correct: Type guard for error.message
-catch (error) {
-  const message = error instanceof Error ? error.message : String(error);
-  console.error(chalk.red("Error:"), message);
-}
-
-// Incorrect: Assuming error is Error
-catch (error) {
-  console.error(error.message); // TypeScript error: 'error' is 'unknown'
-}
-```
-
----
-
-## Exit Codes
-
-| Code | Meaning | Usage |
-|------|---------|-------|
-| `0` | Success | Normal completion (implicit) |
-| `1` | Error | Any error condition |
-
-```typescript
-// Error: exit with code 1
-process.exit(1);
-
-// Success: no explicit exit needed, or:
-process.exit(0);
-```
-
----
-
-## DO / DON'T
-
-### DO
-
-- Catch errors at the top level (command handlers)
-- Use `error instanceof Error ? error.message : error` type guard
-- Exit with code 1 on errors for proper scripting
-- Use empty catch for truly optional operations
-- Show user-friendly messages, not stack traces
-- Use `chalk.red()` for error prefixes
-- Use `chalk.yellow()` for warnings
-
-### DON'T
-
-- Don't catch errors in utility functions unless you can handle them
-- Don't assume `error` is an `Error` type
-- Don't log full stack traces to users (unless in debug mode)
-- Don't use exit code 0 for error conditions
-- Don't swallow errors silently without a comment explaining why
-
----
-
-## Common Mistakes
-
-### Mistake 1: Not using type guard
-
-```typescript
-// Bad: TypeScript error, runtime risk
-catch (error) {
-  console.error(error.message);
-}
-
-// Good: Type guard
-catch (error) {
-  console.error(error instanceof Error ? error.message : error);
-}
-```
-
-### Mistake 2: Catching too early
-
-```typescript
-// Bad: Error caught and re-thrown, losing context
-function readConfig(path: string): Config {
-  try {
-    return JSON.parse(fs.readFileSync(path, "utf-8"));
-  } catch (error) {
-    throw new Error("Failed to read config"); // Lost original error
-  }
-}
-
-// Good: Let it bubble up with original error
-function readConfig(path: string): Config {
-  return JSON.parse(fs.readFileSync(path, "utf-8")); // Caller handles
-}
-```
-
-### Mistake 3: Silent failure without comment
-
-```typescript
-// Bad: Why is this ignored?
-try {
-  doSomething();
-} catch {
-}
-
-// Good: Explain why it's safe to ignore
-try {
-  doSomething();
-} catch {
-  // Optional operation - safe to ignore if it fails
-}
-```
-
----
-
-## Examples
-
-### Complete Command Handler
-
-```typescript
-import chalk from "chalk";
-
-program
-  .command("init")
-  .description("Initialize the project")
-  .action(async (options: InitOptions) => {
-    try {
-      await init(options);
-    } catch (error) {
-      console.error(
-        chalk.red("Error:"),
-        error instanceof Error ? error.message : error,
-      );
-      process.exit(1);
-    }
-  });
-```
-
-### Function with Optional Operation
-
-```typescript
-async function init(options: InitOptions): Promise<void> {
-  const cwd = process.cwd();
-
-  // Optional: detect developer name from git
-  let developerName = options.user;
-  if (!developerName) {
-    try {
-      developerName = execSync("git config user.name", {
-        cwd,
-        encoding: "utf-8",
-      }).trim();
-    } catch {
-      // Git not available - will prompt user later
-    }
-  }
-
-  // Required operation - let errors bubble up
-  await createWorkflowStructure(cwd, options);
-}
-```

package/dist/.trellis/structure/backend/index.md

@@ -1,38 +0,0 @@
-# Backend Development Guidelines
-
-> Best practices for backend development in this project.
-
----
-
-## Overview
-
-This directory contains guidelines for backend development. Fill in each file with your project's specific conventions.
-
----
-
-## Guidelines Index
-
-| Guide | Description | Status |
-|-------|-------------|--------|
-| [Directory Structure](./directory-structure.md) | Module organization and file layout | Done |
-| [Database Guidelines](./database-guidelines.md) | ORM patterns, queries, migrations | N/A (CLI project) |
-| [Error Handling](./error-handling.md) | Error types, handling strategies | Done |
-| [Quality Guidelines](./quality-guidelines.md) | Code standards, forbidden patterns | Done |
-| [Logging Guidelines](./logging-guidelines.md) | Structured logging, log levels | Done |
-
----
-
-## How to Fill These Guidelines
-
-For each guideline file:
-
-1. Document your project's **actual conventions** (not ideals)
-2. Include **code examples** from your codebase
-3. List **forbidden patterns** and why
-4. Add **common mistakes** your team has made
-
-The goal is to help AI assistants and new team members understand how YOUR project works.
-
----
-
-**Language**: All documentation should be written in **English**.