@mindfoldhq/trellis 0.1.1 → 0.1.3

package/dist/.trellis/structure/backend/logging-guidelines.md

@@ -0,0 +1,266 @@
+# Logging Guidelines
+
+> How console output and logging is done in this CLI project.
+
+---
+
+## Overview
+
+This CLI project uses **chalk** for colored console output. Since this is a user-facing CLI tool, we use `console.log()` and `console.error()` directly rather than a structured logging library. Output follows consistent color conventions to help users quickly understand the nature of each message.
+
+---
+
+## Color Conventions
+
+| Color | Chalk Method | Usage | Example |
+|-------|--------------|-------|---------|
+| **Cyan** | `chalk.cyan()` | Headers, banners, section titles | `"Next steps:"` |
+| **Blue** | `chalk.blue()` | Action in progress, step indicators | `"Creating workflow structure..."` |
+| **Green** | `chalk.green()` | Success messages | `"Trellis initialized successfully!"` |
+| **Yellow** | `chalk.yellow()` | Warnings, coming soon, skipped items | `"Coming soon: update command"` |
+| **Red** | `chalk.red()` | Errors | `"Error:"` prefix |
+| **Gray** | `chalk.gray()` | Secondary info, hints, paths | Descriptions, file paths |
+| **White** | `chalk.white()` | Highlighted inline text | Commands to run |
+
+---
+
+## Message Patterns
+
+### Section Headers (Cyan)
+
+```typescript
+console.log(chalk.cyan("Next steps:"));
+console.log(chalk.cyan("Generated structure files:"));
+```
+
+### Progress Steps (Blue with Emoji)
+
+```typescript
+console.log(chalk.blue("📁 Creating workflow structure..."));
+console.log(chalk.blue("📝 Configuring Cursor commands..."));
+console.log(chalk.blue("🤖 Configuring Multi-Agent Pipeline..."));
+console.log(chalk.blue("📄 Created init-agent.md"));
+```
+
+### Sub-steps (Gray with Indentation)
+
+```typescript
+console.log(chalk.gray("   - Creating agent configurations..."));
+console.log(chalk.gray("   - Creating hook configurations..."));
+```
+
+### Success (Green with Emoji)
+
+```typescript
+console.log(chalk.green("\n✅ Trellis initialized successfully!\n"));
+```
+
+### Warnings (Yellow with Emoji)
+
+```typescript
+console.log(chalk.yellow("Coming soon: update command"));
+console.log(chalk.yellow("No tools selected. At least one tool is required."));
+console.log(chalk.yellow(`⚠️  Failed to initialize developer: ${message}`));
+```
+
+### Errors (Red)
+
+```typescript
+console.error(
+  chalk.red("Error:"),
+  error instanceof Error ? error.message : error,
+);
+```
+
+### Informational (Mixed Colors)
+
+```typescript
+// Key-value pairs
+console.log(chalk.blue("👤 Developer:"), chalk.gray(developerName));
+console.log(chalk.blue("🔍 Project type:"), chalk.gray(projectDescription));
+
+// Instructions with highlighted commands
+console.log(
+  chalk.gray(`${stepNum}. Use `) +
+  chalk.white("/start") +
+  chalk.gray(" command in your AI tool to begin a session"),
+);
+```
+
+---
+
+## Output Structure
+
+### Banner and Introduction
+
+```typescript
+// ASCII art banner (cyan)
+const banner = figlet.textSync("Trellis", { font: "Rebel" });
+console.log(chalk.cyan(`\n${banner.trimEnd()}`));
+
+// Tagline (gray)
+console.log(chalk.gray("\n  AI-assisted development workflow framework\n"));
+```
+
+### Progress Output
+
+```typescript
+// Mode indicator
+console.log(chalk.gray("Mode: Force overwrite existing files\n"));
+
+// Detection results
+console.log(chalk.blue("👤 Developer:"), chalk.gray(developerName));
+console.log(chalk.blue("🔍 Project type:"), chalk.gray(description));
+
+// Configuration summary
+console.log(chalk.gray(`\nConfiguring: ${tools.join(", ")}`));
+console.log(chalk.gray(`Project type: ${typeDescription}\n`));
+
+// Step progress
+console.log(chalk.blue("📁 Creating workflow structure..."));
+console.log(chalk.blue("📝 Configuring Cursor commands..."));
+```
+
+### Completion Summary
+
+```typescript
+// Success message
+console.log(chalk.green("\n✅ Trellis initialized successfully!\n"));
+
+// Next steps
+console.log(chalk.cyan("Next steps:"));
+console.log(
+  chalk.gray(`1. Use `) +
+  chalk.white("/start") +
+  chalk.gray(" command in your AI tool"),
+);
+
+// Generated files
+console.log(chalk.cyan("Generated structure files:"));
+console.log(chalk.gray(`  ${PATHS.STRUCTURE}/guides/   - Thinking guides`));
+```
+
+---
+
+## Emoji Usage
+
+| Emoji | Usage |
+|-------|-------|
+| 📁 | Directory/folder operations |
+| 📝 | Configuration/file writing |
+| 📄 | Single file creation |
+| 🤖 | AI/agent related |
+| 👤 | User/developer related |
+| 🔍 | Detection/analysis |
+| ✅ | Success completion |
+| ⚠️ | Warnings |
+
+---
+
+## Indentation
+
+Use indentation to show hierarchy:
+
+```typescript
+// Top level (no indent)
+console.log(chalk.blue("🤖 Configuring Multi-Agent Pipeline..."));
+
+// Sub-level (3 spaces + dash)
+console.log(chalk.gray("   - Creating agent configurations..."));
+console.log(chalk.gray("   - Creating hook configurations..."));
+
+// File listings (2 spaces)
+console.log(chalk.gray(`  ${PATHS.STRUCTURE}/guides/   - Thinking guides`));
+console.log(chalk.gray(`  ${PATHS.STRUCTURE}/frontend/ - Frontend guidelines`));
+```
+
+---
+
+## DO / DON'T
+
+### DO
+
+- Use `chalk` for all colored output
+- Follow the color convention consistently
+- Use emojis for visual scanning (sparingly)
+- Use indentation to show hierarchy
+- Add blank lines between sections for readability
+- Use `console.error()` for errors
+
+### DON'T
+
+- Don't use raw ANSI escape codes
+- Don't mix color meanings (e.g., red for non-error)
+- Don't overuse emojis
+- Don't log sensitive information (paths with usernames excepted for context)
+- Don't use `console.log()` for errors (use `console.error()`)
+- Don't output debug information in production
+
+---
+
+## Examples
+
+### Complete Init Output Flow
+
+```typescript
+// 1. Banner
+console.log(chalk.cyan(`\n${banner.trimEnd()}`));
+console.log(chalk.gray("\n  AI-assisted development workflow framework\n"));
+
+// 2. Mode (if special mode)
+if (options.force) {
+  console.log(chalk.gray("Mode: Force overwrite existing files\n"));
+}
+
+// 3. Detection results
+console.log(chalk.blue("👤 Developer:"), chalk.gray(developerName));
+console.log(chalk.blue("🔍 Project type:"), chalk.gray(typeDescription));
+
+// 4. Configuration summary
+console.log(chalk.gray(`\nConfiguring: ${tools.join(", ")}\n`));
+
+// 5. Progress steps
+console.log(chalk.blue("📁 Creating workflow structure..."));
+console.log(chalk.blue("📝 Configuring Cursor commands..."));
+console.log(chalk.blue("🤖 Configuring Multi-Agent Pipeline..."));
+console.log(chalk.gray("   - Creating agent configurations..."));
+
+// 6. Success
+console.log(chalk.green("\n✅ Trellis initialized successfully!\n"));
+
+// 7. Next steps
+console.log(chalk.cyan("Next steps:"));
+console.log(
+  chalk.gray("1. Use ") +
+  chalk.white("/start") +
+  chalk.gray(" command to begin"),
+);
+```
+
+### Error Output
+
+```typescript
+try {
+  await init(options);
+} catch (error) {
+  console.error(
+    chalk.red("Error:"),
+    error instanceof Error ? error.message : error,
+  );
+  process.exit(1);
+}
+```
+
+### Warning Output
+
+```typescript
+// Non-critical warning
+console.log(
+  chalk.yellow(
+    `⚠️  Failed to initialize developer: ${message}`,
+  ),
+);
+
+// Coming soon feature
+console.log(chalk.yellow("Coming soon: update command"));
+```

package/dist/.trellis/structure/backend/quality-guidelines.md

@@ -0,0 +1,313 @@
+# Quality Guidelines
+
+> Code quality standards for backend/CLI development.
+
+---
+
+## Overview
+
+This project enforces strict TypeScript and ESLint rules to maintain code quality. The configuration prioritizes type safety, explicit declarations, and modern JavaScript patterns.
+
+---
+
+## TypeScript Configuration
+
+### Strict Mode
+
+The project uses `strict: true` in `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext"
+  }
+}
+```
+
+This enables:
+- `strictNullChecks` - Null and undefined must be explicitly handled
+- `strictFunctionTypes` - Function parameter types are checked strictly
+- `strictPropertyInitialization` - Class properties must be initialized
+- `noImplicitAny` - All types must be explicit
+- `noImplicitThis` - `this` must have explicit type
+
+---
+
+## ESLint Rules
+
+### Forbidden Patterns
+
+| Rule | Setting | Reason |
+|------|---------|--------|
+| `@typescript-eslint/no-explicit-any` | `error` | Forces proper typing |
+| `@typescript-eslint/no-non-null-assertion` | `error` | Prevents runtime null errors |
+| `no-var` | `error` | Use `const` or `let` instead |
+
+### Required Patterns
+
+| Rule | Setting | Description |
+|------|---------|-------------|
+| `@typescript-eslint/explicit-function-return-type` | `error` | All functions must declare return type |
+| `@typescript-eslint/prefer-nullish-coalescing` | `error` | Use `??` instead of `\|\|` for defaults |
+| `@typescript-eslint/prefer-optional-chain` | `error` | Use `?.` for optional access |
+| `prefer-const` | `error` | Use `const` when variable is not reassigned |
+
+### Exceptions
+
+```javascript
+// eslint.config.js
+rules: {
+  "@typescript-eslint/explicit-function-return-type": [
+    "error",
+    {
+      allowExpressions: true,          // Arrow functions in callbacks OK
+      allowTypedFunctionExpressions: true,  // Typed function expressions OK
+    },
+  ],
+  "@typescript-eslint/no-unused-vars": [
+    "error",
+    {
+      argsIgnorePattern: "^_",   // Prefix unused params with _
+      varsIgnorePattern: "^_",   // Prefix unused vars with _
+    },
+  ],
+}
+```
+
+---
+
+## Code Patterns
+
+### Return Type Declarations
+
+All functions must have explicit return types:
+
+```typescript
+// Good: Explicit return type
+function detectProjectType(cwd: string): ProjectType {
+  // ...
+}
+
+async function init(options: InitOptions): Promise<void> {
+  // ...
+}
+
+// Bad: Missing return type (ESLint error)
+function detectProjectType(cwd: string) {
+  // ...
+}
+```
+
+### Nullish Coalescing
+
+Use `??` for default values, not `||`:
+
+```typescript
+// Good: Nullish coalescing
+const name = options.name ?? "default";
+const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+const depNames = Object.keys(allDeps ?? {});
+
+// Bad: Logical OR (treats empty string, 0 as falsy)
+const name = options.name || "default";
+```
+
+### Optional Chaining
+
+Use `?.` for optional property access:
+
+```typescript
+// Good: Optional chaining
+const version = config?.version;
+const deps = pkg?.dependencies?.["react"];
+
+// Bad: Manual checks
+const version = config && config.version;
+```
+
+### Const Declarations
+
+Use `const` by default, `let` only when reassignment is needed:
+
+```typescript
+// Good: const for non-reassigned
+const cwd = process.cwd();
+const options: InitOptions = { force: true };
+
+// Good: let for reassigned
+let developerName = options.user;
+if (!developerName) {
+  developerName = detectFromGit();
+}
+
+// Bad: let for non-reassigned
+let cwd = process.cwd();  // ESLint error: prefer-const
+```
+
+### Unused Variables
+
+Prefix unused parameters with underscore:
+
+```typescript
+// Good: Prefixed with underscore
+function handler(_req: Request, res: Response): void {
+  res.send("OK");
+}
+
+// Bad: Unused without prefix (ESLint error)
+function handler(req: Request, res: Response): void {
+  res.send("OK");
+}
+```
+
+---
+
+## Interface and Type Patterns
+
+### Interface Definitions
+
+Define interfaces for structured data:
+
+```typescript
+// Good: Interface for options
+interface InitOptions {
+  cursor?: boolean;
+  claude?: boolean;
+  yes?: boolean;
+  user?: string;
+  force?: boolean;
+}
+
+// Good: Interface for return types
+interface WriteOptions {
+  mode: WriteMode;
+}
+```
+
+### Type Aliases
+
+Use type aliases for unions and computed types:
+
+```typescript
+// Good: Type alias for union
+export type AITool = "claude-code" | "cursor" | "opencode";
+export type WriteMode = "ask" | "force" | "skip" | "append";
+export type ProjectType = "frontend" | "backend" | "fullstack" | "unknown";
+
+// Good: Type alias with const assertion
+export const DIR_NAMES = {
+  WORKFLOW: ".trellis",
+  PROGRESS: "agent-traces",
+} as const;
+```
+
+### Export Patterns
+
+Export types explicitly:
+
+```typescript
+// Good: Explicit type export
+export type { WriteMode, WriteOptions };
+export { writeFile, ensureDir };
+
+// Good: Combined export
+export type WriteMode = "ask" | "force" | "skip" | "append";
+export function writeFile(path: string, content: string): Promise<boolean> {
+  // ...
+}
+```
+
+---
+
+## Forbidden Patterns
+
+### Never Use `any`
+
+```typescript
+// Bad: Explicit any
+function process(data: any): void { }
+
+// Good: Proper typing
+function process(data: Record<string, unknown>): void { }
+function process<T>(data: T): void { }
+```
+
+### Never Use Non-Null Assertion
+
+```typescript
+// Bad: Non-null assertion
+const name = user!.name;
+
+// Good: Proper null check
+const name = user?.name ?? "default";
+if (user) {
+  const name = user.name;
+}
+```
+
+### Never Use `var`
+
+```typescript
+// Bad: var declaration
+var count = 0;
+
+// Good: const or let
+const count = 0;
+let mutableCount = 0;
+```
+
+---
+
+## Quality Checklist
+
+Before committing, ensure:
+
+- [ ] `pnpm lint` passes with no errors
+- [ ] `pnpm typecheck` passes with no errors
+- [ ] All functions have explicit return types
+- [ ] No `any` types in code
+- [ ] No non-null assertions (`!`)
+- [ ] Using `??` instead of `||` for defaults
+- [ ] Using `?.` for optional property access
+- [ ] Using `const` by default, `let` only when needed
+- [ ] Unused variables prefixed with `_`
+
+---
+
+## Running Quality Checks
+
+```bash
+# Run ESLint
+pnpm lint
+
+# Run TypeScript type checking
+pnpm typecheck
+
+# Run both
+pnpm lint && pnpm typecheck
+```
+
+---
+
+## DO / DON'T
+
+### DO
+
+- Declare explicit return types on all functions
+- Use `const` by default
+- Use `??` for default values
+- Use `?.` for optional access
+- Define interfaces for structured data
+- Prefix unused parameters with `_`
+
+### DON'T
+
+- Don't use `any` type
+- Don't use non-null assertion (`!`)
+- Don't use `var`
+- Don't use `||` for default values (use `??`)
+- Don't leave implicit return types
+- Don't ignore ESLint or TypeScript errors

package/dist/.trellis/structure/frontend/component-guidelines.md

@@ -0,0 +1,59 @@
+# Component Guidelines
+
+> How components are built in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's component conventions here.
+
+Questions to answer:
+- What component patterns do you use?
+- How are props defined?
+- How do you handle composition?
+- What accessibility standards apply?
+-->
+
+(To be filled by the team)
+
+---
+
+## Component Structure
+
+<!-- Standard structure of a component file -->
+
+(To be filled by the team)
+
+---
+
+## Props Conventions
+
+<!-- How props should be defined and typed -->
+
+(To be filled by the team)
+
+---
+
+## Styling Patterns
+
+<!-- How styles are applied (CSS modules, styled-components, Tailwind, etc.) -->
+
+(To be filled by the team)
+
+---
+
+## Accessibility
+
+<!-- A11y requirements and patterns -->
+
+(To be filled by the team)
+
+---
+
+## Common Mistakes
+
+<!-- Component-related mistakes your team has made -->
+
+(To be filled by the team)

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

@@ -0,0 +1,54 @@
+# Directory Structure
+
+> How frontend code is organized in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's frontend directory structure here.
+
+Questions to answer:
+- Where do components live?
+- How are features/modules organized?
+- Where are shared utilities?
+- How are assets organized?
+-->
+
+(To be filled by the team)
+
+---
+
+## Directory Layout
+
+```
+<!-- Replace with your actual structure -->
+src/
+├── ...
+└── ...
+```
+
+---
+
+## Module Organization
+
+<!-- How should new features be organized? -->
+
+(To be filled by the team)
+
+---
+
+## Naming Conventions
+
+<!-- File and folder naming rules -->
+
+(To be filled by the team)
+
+---
+
+## Examples
+
+<!-- Link to well-organized modules as examples -->
+
+(To be filled by the team)