@mindfoldhq/trellis 0.1.9 → 0.2.2

package/dist/templates/trellis/workflow.md

@@ -33,12 +33,12 @@
 
 This creates:
 - `.trellis/.developer` - Your identity file (gitignored, not committed)
-- `.trellis/agent-traces/<your-name>/` - Your personal traces directory
+- `.trellis/workspace/<your-name>/` - Your personal workspace directory
 
 **Naming suggestions**:
 - Human developers: Use your name, e.g., `john-doe`
-- Cursor AI: `cursor-agent` or `cursor-<feature>`
-- Claude Code: `claude-agent` or `claude-<feature>`
+- Cursor AI: `cursor-agent` or `cursor-<task>`
+- Claude Code: `claude-agent` or `claude-<task>`
 
 ### Step 1: Understand Current Context
 
@@ -48,7 +48,7 @@ This creates:
 
 # Or check manually:
 ./.trellis/scripts/get-developer.sh      # Your identity
-./.trellis/scripts/feature.sh list       # Active features
+./.trellis/scripts/task.sh list          # Active tasks
 git status && git log --oneline -10      # Git state
 ```
 
@@ -58,10 +58,10 @@ git status && git log --oneline -10      # Git state
 
 ```bash
 # Read frontend guidelines index (if applicable)
-cat .trellis/structure/frontend/index.md
+cat .trellis/spec/frontend/index.md
 
 # Read backend guidelines index (if applicable)
-cat .trellis/structure/backend/index.md
+cat .trellis/spec/backend/index.md
 ```
 
 **Why read both?**
@@ -76,16 +76,16 @@ Based on your task, read the **detailed** guidelines:
 
 **Frontend Task**:
 ```bash
-cat .trellis/structure/frontend/hook-guidelines.md      # For hooks
-cat .trellis/structure/frontend/component-guidelines.md # For components
-cat .trellis/structure/frontend/type-safety.md          # For types
+cat .trellis/spec/frontend/hook-guidelines.md      # For hooks
+cat .trellis/spec/frontend/component-guidelines.md # For components
+cat .trellis/spec/frontend/type-safety.md          # For types
 ```
 
 **Backend Task**:
 ```bash
-cat .trellis/structure/backend/database-guidelines.md   # For DB operations
-cat .trellis/structure/backend/type-safety.md           # For types
-cat .trellis/structure/backend/logging-guidelines.md    # For logging
+cat .trellis/spec/backend/database-guidelines.md   # For DB operations
+cat .trellis/spec/backend/type-safety.md           # For types
+cat .trellis/spec/backend/logging-guidelines.md    # For logging
 ```
 
 ---
@@ -95,10 +95,10 @@ cat .trellis/structure/backend/logging-guidelines.md    # For logging
 ### Core Principles
 
 1. **Read Before Write** - Understand context before starting
-2. **Follow Standards** - [!] **MUST read `.trellis/structure/` guidelines before coding**
-3. **Incremental Development** - Complete one feature at a time
+2. **Follow Standards** - [!] **MUST read `.trellis/spec/` guidelines before coding**
+3. **Incremental Development** - Complete one task at a time
 4. **Record Promptly** - Update tracking files immediately after completion
-5. **Document Limits** - [!] **Max 2000 lines per agent-traces document**
+5. **Document Limits** - [!] **Max 2000 lines per journal document**
 
 ### File System
 
@@ -112,18 +112,18 @@ cat .trellis/structure/backend/logging-guidelines.md    # For logging
 |   |   \-- git-context.sh   # Git context implementation
 |   |-- init-developer.sh    # Initialize developer identity
 |   |-- get-developer.sh     # Get current developer name
-|   |-- feature.sh           # Manage features
+|   |-- task.sh              # Manage tasks
 |   |-- get-context.sh       # Get session context
 |   \-- add-session.sh       # One-click session recording
-|-- agent-traces/       # AI Agent work traces records
-|   |-- index.md         # Traces index + Session template
+|-- workspace/           # Developer workspaces
+|   |-- index.md         # Workspace index + Session template
 |   \-- {developer}/     # Per-developer directories
 |       |-- index.md     # Personal index (with @@@auto markers)
-|       |-- features/    # Feature directories
-|       |   \-- {day}-{name}/
-|       |       \-- feature.json
-|       \-- traces-N.md  # Traces files (sequential numbering)
-|-- structure/           # [!] MUST READ before coding
+|       \-- journal-N.md # Journal files (sequential numbering)
+|-- tasks/               # Task tracking
+|   \-- {MM}-{DD}-{name}/
+|       \-- task.json
+|-- spec/                # [!] MUST READ before coding
 |   |-- frontend/        # Frontend guidelines (if applicable)
 |   |   |-- index.md               # Start here - guidelines index
 |   |   \-- *.md                   # Topic-specific docs
@@ -162,49 +162,49 @@ Based on what you'll develop, read the corresponding guidelines:
 **Frontend Development** (if applicable):
 ```bash
 # Read index first, then specific docs based on task
-cat .trellis/structure/frontend/index.md
+cat .trellis/spec/frontend/index.md
 ```
 
 **Backend Development** (if applicable):
 ```bash
 # Read index first, then specific docs based on task
-cat .trellis/structure/backend/index.md
+cat .trellis/spec/backend/index.md
 ```
 
 **Cross-Layer Features**:
 ```bash
 # For features spanning multiple layers
-cat .trellis/structure/guides/cross-layer-thinking-guide.md
+cat .trellis/spec/guides/cross-layer-thinking-guide.md
 ```
 
-### Step 3: Select Feature to Develop
+### Step 3: Select Task to Develop
 
-Use the feature management script:
+Use the task management script:
 
 ```bash
-# List active features
-./.trellis/scripts/feature.sh list
+# List active tasks
+./.trellis/scripts/task.sh list
 
-# Create new feature (creates directory with feature.json)
-./.trellis/scripts/feature.sh create "<title>" --slug <feature-name>
+# Create new task (creates directory with task.json)
+./.trellis/scripts/task.sh create "<title>" --slug <task-name>
 ```
 
 ---
 
 ## Development Process
 
-### Feature Development Flow
+### Task Development Flow
 
 ```
-1. Create or select feature
-   \-> ./.trellis/scripts/feature.sh create "<title>" --slug <name> or list
+1. Create or select task
+   \-> ./.trellis/scripts/task.sh create "<title>" --slug <name> or list
 
 2. Write code according to guidelines
-   \-> Read .trellis/structure/ docs relevant to your task
-   \-> For cross-layer: read .trellis/structure/guides/
+   \-> Read .trellis/spec/ docs relevant to your task
+   \-> For cross-layer: read .trellis/spec/guides/
 
 3. Self-test
-   \-> Run project's lint/test commands (see structure docs)
+   \-> Run project's lint/test commands (see spec docs)
    \-> Manual feature testing
 
 4. Commit code
@@ -224,8 +224,8 @@ Use the feature management script:
 - [OK] Manual feature testing passes
 
 **Project-specific checks**:
-- See `.trellis/structure/frontend/quality-guidelines.md` for frontend
-- See `.trellis/structure/backend/quality-guidelines.md` for backend
+- See `.trellis/spec/frontend/quality-guidelines.md` for frontend
+- See `.trellis/spec/backend/quality-guidelines.md` for backend
 
 ---
 
@@ -243,7 +243,7 @@ After code is committed, use:
 ```
 
 This automatically:
-1. Detects current traces file
+1. Detects current journal file
 2. Creates new file if 2000-line limit exceeded
 3. Appends session content
 4. Updates index.md (sessions count, history table)
@@ -255,40 +255,37 @@ Use `/finish-work` command to run through:
 2. [OK] Session recorded via `add-session.sh`
 3. [OK] No lint/test errors
 4. [OK] Working directory clean (or WIP noted)
-5. [OK] Structure docs updated if needed
+5. [OK] Spec docs updated if needed
 
 ---
 
 ## File Descriptions
 
-### 1. agent-traces/ - Agent Work Traces
+### 1. workspace/ - Developer Workspaces
 
 **Purpose**: Record each AI Agent session's work content
 
 **Structure** (Multi-developer support):
 ```
-agent-traces/
+workspace/
 |-- index.md              # Main index (Active Developers table)
 \-- {developer}/          # Per-developer directory
     |-- index.md          # Personal index (with @@@auto markers)
-    |-- features/         # Feature directories
-    |   \-- {day}-{name}/ # Each feature is a directory
-    |       \-- feature.json
-    \-- traces-N.md     # Traces files (sequential: 1, 2, 3...)
+    \-- journal-N.md      # Journal files (sequential: 1, 2, 3...)
 ```
 
 **When to update**:
 - [OK] End of each session
-- [OK] Complete important feature
+- [OK] Complete important task
 - [OK] Fix important bug
 
-### 2. structure/ - Development Guidelines
+### 2. spec/ - Development Guidelines
 
 **Purpose**: Documented standards for consistent development
 
 **Structure** (Multi-doc format):
 ```
-structure/
+spec/
 |-- frontend/           # Frontend docs (if applicable)
 |   |-- index.md        # Start here
 |   \-- *.md            # Topic-specific docs
@@ -305,26 +302,26 @@ structure/
 - [OK] Bug fixed that reveals missing guidance
 - [OK] New convention established
 
-### 3. Features - Feature Tracking
+### 3. Tasks - Task Tracking
 
-Each feature is a directory containing `feature.json`:
+Each task is a directory containing `task.json`:
 
 ```
-features/
-|-- 13-my-feature/
-|   \-- feature.json
+tasks/
+|-- 01-21-my-task/
+|   \-- task.json
 \-- archive/
-    \-- 2025-01/
-        \-- 13-old-feature/
-            \-- feature.json
+    \-- 2026-01/
+        \-- 01-15-old-task/
+            \-- task.json
 ```
 
 **Commands**:
 ```bash
-./.trellis/scripts/feature.sh create "<title>" [--slug <name>]   # Create feature directory
-./.trellis/scripts/feature.sh archive <name>  # Archive to archive/{year-month}/
-./.trellis/scripts/feature.sh list            # List active features
-./.trellis/scripts/feature.sh list-archive    # List archived features
+./.trellis/scripts/task.sh create "<title>" [--slug <name>]   # Create task directory
+./.trellis/scripts/task.sh archive <name>  # Archive to archive/{year-month}/
+./.trellis/scripts/task.sh list            # List active tasks
+./.trellis/scripts/task.sh list-archive    # List archived tasks
 ```
 
 ---
@@ -335,12 +332,12 @@ features/
 
 1. **Before session start**:
    - Run `./.trellis/scripts/get-context.sh` for full context
-   - [!] **MUST read** relevant `.trellis/structure/` docs
+   - [!] **MUST read** relevant `.trellis/spec/` docs
 
 2. **During development**:
-   - [!] **Follow** `.trellis/structure/` guidelines
+   - [!] **Follow** `.trellis/spec/` guidelines
    - For cross-layer features, use `/check-cross-layer`
-   - Develop only one feature at a time
+   - Develop only one task at a time
    - Run lint and tests frequently
 
 3. **After development complete**:
@@ -351,11 +348,11 @@ features/
 
 ### [X] DON'T - Should Not Do
 
-1. [!] **Don't** skip reading `.trellis/structure/` guidelines
-2. [!] **Don't** let agent-traces single file exceed 2000 lines
-3. **Don't** develop multiple unrelated features simultaneously
+1. [!] **Don't** skip reading `.trellis/spec/` guidelines
+2. [!] **Don't** let journal single file exceed 2000 lines
+3. **Don't** develop multiple unrelated tasks simultaneously
 4. **Don't** commit code with lint/test errors
-5. **Don't** forget to update structure docs after learning something
+5. **Don't** forget to update spec docs after learning something
 6. [!] **Don't** execute `git commit` - AI should not commit code
 
 ---
@@ -386,9 +383,9 @@ git commit -m "type(scope): description"
 ./.trellis/scripts/get-context.sh    # Get full context
 ./.trellis/scripts/add-session.sh    # Record session
 
-# Feature management
-./.trellis/scripts/feature.sh list   # List features
-./.trellis/scripts/feature.sh create "<title>" # Create feature
+# Task management
+./.trellis/scripts/task.sh list      # List tasks
+./.trellis/scripts/task.sh create "<title>" # Create task
 
 # Slash commands
 /finish-work          # Pre-commit checklist
@@ -404,7 +401,7 @@ Following this workflow ensures:
 - [OK] Continuity across multiple sessions
 - [OK] Consistent code quality
 - [OK] Trackable progress
-- [OK] Knowledge accumulation in structure docs
+- [OK] Knowledge accumulation in spec docs
 - [OK] Transparent team collaboration
 
 **Core Philosophy**: Read before write, follow standards, record promptly, capture learnings

package/dist/types/migration.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Migration types for Trellis update command
+ *
+ * These types support intelligent migration during updates,
+ * handling file renames, deletions, and user modification detection.
+ */
+/**
+ * A single migration action (rename, rename-dir, or delete)
+ */
+export interface MigrationItem {
+    /** Type of migration action */
+    type: "rename" | "rename-dir" | "delete";
+    /** Source path (relative to project root) */
+    from: string;
+    /** Target path for renames (relative to project root) */
+    to?: string;
+    /** Human-readable description of the change */
+    description?: string;
+}
+/**
+ * Migration manifest for a specific version
+ */
+export interface MigrationManifest {
+    /** Target version this migration upgrades to */
+    version: string;
+    /** List of migration actions */
+    migrations: MigrationItem[];
+}
+/**
+ * Classification of how a migration should be handled
+ */
+export type MigrationClassification = "auto" | "confirm" | "conflict" | "skip";
+/**
+ * Classified migration item with its determined action
+ */
+export interface ClassifiedMigrationItem extends MigrationItem {
+    classification: MigrationClassification;
+}
+/**
+ * Result of classifying all migrations
+ */
+export interface ClassifiedMigrations {
+    /** Unmodified files - safe to auto-migrate */
+    auto: MigrationItem[];
+    /** User-modified files - need confirmation */
+    confirm: MigrationItem[];
+    /** Conflict - both old and new exist */
+    conflict: MigrationItem[];
+    /** Skip - old file doesn't exist */
+    skip: MigrationItem[];
+}
+/**
+ * Result of executing migrations
+ */
+export interface MigrationResult {
+    /** Number of files renamed */
+    renamed: number;
+    /** Number of files deleted */
+    deleted: number;
+    /** Number of files skipped (user choice or no action needed) */
+    skipped: number;
+    /** Number of conflicts encountered */
+    conflicts: number;
+}
+/**
+ * User action choice for migration confirmation
+ */
+export type MigrationAction = "rename" | "backup-rename" | "skip" | "view-diff";
+/**
+ * Template hashes storage structure
+ * Maps relative file paths to their SHA256 hashes
+ */
+export type TemplateHashes = Record<string, string>;
+//# sourceMappingURL=migration.d.ts.map

package/dist/types/migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../../src/types/migration.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,+BAA+B;IAC/B,IAAI,EAAE,QAAQ,GAAG,YAAY,GAAG,QAAQ,CAAC;IACzC,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,UAAU,EAAE,aAAa,EAAE,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAC/B,MAAM,GACN,SAAS,GACT,UAAU,GACV,MAAM,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,aAAa;IAC5D,cAAc,EAAE,uBAAuB,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,8CAA8C;IAC9C,IAAI,EAAE,aAAa,EAAE,CAAC;IACtB,8CAA8C;IAC9C,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,wCAAwC;IACxC,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,oCAAoC;IACpC,IAAI,EAAE,aAAa,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,QAAQ,GACR,eAAe,GACf,MAAM,GACN,WAAW,CAAC;AAEhB;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC"}

package/dist/types/migration.js

@@ -0,0 +1,8 @@
+/**
+ * Migration types for Trellis update command
+ *
+ * These types support intelligent migration during updates,
+ * handling file renames, deletions, and user modification detection.
+ */
+export {};
+//# sourceMappingURL=migration.js.map

package/dist/types/migration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration.js","sourceRoot":"","sources":["../../src/types/migration.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/utils/template-hash.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Template hash utilities for detecting user modifications
+ *
+ * Stores SHA256 hashes of template files at install time.
+ * Used to determine if users have modified templates.
+ */
+import type { TemplateHashes } from "../types/migration.js";
+/**
+ * Compute SHA256 hash of content
+ */
+export declare function computeHash(content: string): string;
+/**
+ * Load stored template hashes
+ */
+export declare function loadHashes(cwd: string): TemplateHashes;
+/**
+ * Save template hashes
+ */
+export declare function saveHashes(cwd: string, hashes: TemplateHashes): void;
+/**
+ * Update hashes for specific files
+ *
+ * @param cwd - Working directory
+ * @param files - Map of relative paths to file contents
+ */
+export declare function updateHashes(cwd: string, files: Map<string, string>): void;
+/**
+ * Update hash for a single file by reading its current content
+ */
+export declare function updateHashFromFile(cwd: string, relativePath: string): void;
+/**
+ * Remove hash entry for a file (e.g., after deletion)
+ */
+export declare function removeHash(cwd: string, relativePath: string): void;
+/**
+ * Rename hash entry (used after file rename)
+ */
+export declare function renameHash(cwd: string, oldPath: string, newPath: string): void;
+/**
+ * Check if a template file has been modified by the user
+ *
+ * @param cwd - Working directory
+ * @param relativePath - Relative path to the file
+ * @param hashes - Stored template hashes
+ * @returns true if file has been modified from template, false otherwise
+ */
+export declare function isTemplateModified(cwd: string, relativePath: string, hashes: TemplateHashes): boolean;
+/**
+ * Check if a file matches its original template content
+ * (Useful for determining if a file can be safely auto-migrated)
+ *
+ * @param cwd - Working directory
+ * @param relativePath - Relative path to the file
+ * @param originalContent - Original template content
+ * @returns true if file matches original template
+ */
+export declare function matchesOriginalTemplate(cwd: string, relativePath: string, originalContent: string): boolean;
+/**
+ * Get modification status for multiple files
+ *
+ * @param cwd - Working directory
+ * @param relativePaths - Array of relative paths to check
+ * @param hashes - Stored template hashes
+ * @returns Map of path to modification status
+ */
+export declare function getModificationStatus(cwd: string, relativePaths: string[], hashes: TemplateHashes): Map<string, boolean>;
+/**
+ * Initialize template hashes after init
+ *
+ * Scans all template directories and computes hashes for files.
+ * This should be called at the end of `trellis init` to enable
+ * modification detection on subsequent updates.
+ *
+ * @param cwd - Working directory
+ * @returns Number of files hashed
+ */
+export declare function initializeHashes(cwd: string): number;
+//# sourceMappingURL=template-hash.d.ts.map

package/dist/utils/template-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-hash.d.ts","sourceRoot":"","sources":["../../src/utils/template-hash.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAK5D;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AASD;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAYtD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAGpE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GACzB,IAAI,CAQN;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAU1E;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAIlE;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,IAAI,CAON;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,cAAc,GACrB,OAAO,CAmBT;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,EACpB,eAAe,EAAE,MAAM,GACtB,OAAO,CAST;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,MAAM,EAAE,EACvB,MAAM,EAAE,cAAc,GACrB,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAQtB;AAsED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAoBpD"}