@mod-computer/cli 0.1.0

package/commands/spec.md

@@ -0,0 +1,169 @@
+---
+version: 1.0.0
+updated: 2025-12-13
+checksum: d4e5f6g7h8i9j0k1
+description: Create comprehensive spec from feature description
+---
+
+# ModSpec Creation Guide
+
+Given this high-level feature description: "$ARGUMENTS"
+
+## Branch Creation and Setup
+
+**BEFORE writing the specification:**
+
+**Automatic Specification Branch Creation:**
+1. **Extract spec title** from the feature description arguments
+2. **Check for existing branch** that matches the specification:
+   ```bash
+   # Check if specification branch already exists
+   mod branch list | grep "feature-[package-]spec-name"
+   ```
+3. **Create or switch to specification branch**:
+   ```bash
+   # If branch exists, switch to it
+   mod branch switch feature-mod-cli-branching-cli
+   
+   # If branch doesn't exist, create it with package prefix
+   mod branch create feature-mod-cli-branching-cli --spec mod-cli/branching-cli.spec.md
+   ```
+4. **Verify branch setup**:
+   ```bash
+   mod branch status
+   # Should show: Active branch: feature-mod-cli-branching-cli [spec] (specification)
+   # Should show: ✓ Linked to specification: .mod/specs/mod-cli/branching-cli.spec.md
+   ```
+
+**Package-Prefixed Branch Naming:**
+- **Pattern**: `feature-{package}-{spec-name}`
+- **Examples**: 
+  - `feature-mod-cli-branching-cli`
+  - `feature-mod-core-workspace-management`
+  - `feature-mod-ui-component-library`
+- **Benefits**: Clear package ownership, avoids name collisions
+
+**Background Sync Integration:**
+- The mod sync daemon automatically tracks specification file changes
+- Branch switching preserves working directory state
+- Real-time change monitoring enables seamless development flow
+
+## Pre-Specification Research
+
+**BEFORE writing the specification:**
+1. Research existing codebase for related functionality and patterns
+2. Check `.mod/specs/` for similar specifications  
+3. Identify reusable code, services, and integration points
+4. Understand the target package's architecture and conventions
+
+## ModSpec Structure
+
+Include:
+
+**Required Header:**
+```markdown
+---
+title: [feature-name]
+type: specification
+---
+# [Feature Name] Specification
+```
+
+**Core Sections:**
+1. **Abstract** - One concise sentence describing key capabilities
+2. **Motivation** - Problems and impact in bullet points
+3. **Approach** - Technical decisions and integration points
+4. **UX Requirements (UX-*)** - UI components, user flows, and accessibility
+5. **Business Logic Requirements (BUS-*)** - Business logic, workflows, and validation rules
+6. **Data Model Requirements (DATA-*)** - TypeScript interfaces, data structures, and service extensions (be conservative - prefer extending existing over creating new)
+7. **Integration Requirements (INT-*)** - APIs, external services, and data exchange
+8. **Infrastructure Requirements (INFRA-*)** - System architecture, deployment, and scaling
+9. **Quality Requirements (QUAL-*)** - Testing, performance, and security criteria
+
+### Quality Requirements Playbook
+Default to four numbered blocks so every spec documents the same test tiers; add REQ-QUAL-5+ if the feature needs specialty coverage (security, privacy, chaos, compliance, etc.). Keep every entry succinct and include the test type + success metric in the requirement text. Under each block, add sub-numbered requirements (REQ-QUAL-X.Y.Z) that describe the specific test case so it can be traced back to automation or manual checklists.
+
+1. **REQ-QUAL-1: Unit Quality** — Core modules and invariants guarded by unit tests (coverage targets, fixtures, failure injection).
+2. **REQ-QUAL-2: Integration Quality** — Extension/service interactions, persistence, external APIs validated through integration harnesses.
+3. **REQ-QUAL-3: End-to-End / Scenario Quality** — Real workflows (happy + negative), manual UX steps, plus the evidence reviewers must archive.
+4. **REQ-QUAL-4: Performance & Telemetry** — Bench methodology, latency/throughput budgets, soak expectations, telemetry metrics + alert thresholds.
+5. **REQ-QUAL-5+: Optional Specialty** — Security, resilience, localization, etc., only when needed.
+
+Reference `mod-ide-plugin/12-spec-branch-creation-and-change-tracking.spec.md` for tone and structure when in doubt.
+
+**Critical Requirements for Agent Execution:**
+- Use hierarchical numbered requirements with concise, clear descriptions:
+  - REQ-{CATEGORY}: Top-level category (REQ-UX, REQ-BUS, REQ-DATA, REQ-INT, REQ-INFRA, REQ-QUAL)
+  - REQ-{CATEGORY}-N: User story-level groupings (REQ-UX-1: Dashboard access with recent activity)
+  - REQ-{CATEGORY}-N.N: Feature sections within user story (REQ-UX-1.1: Default State)
+  - REQ-{CATEGORY}-N.N.N: Granular implementation details (REQ-UX-1.1.1: Available dashboard view)
+- Write concisely: remove redundant words, use bullet points, avoid verbose descriptions
+- Include exact implementation details (bcrypt cost=12, not "hash securely")
+- Specify concrete behavior that agents can implement directly
+- Be direct and scannable - eliminate wordy, repetitive language
+
+## Specification Output Location and Chronological Ordering
+
+**IMPORTANT**: Create the specification file at:
+`.mod/specs/<appropriate-folder>/<feature-name>.spec.md`
+
+**Chronological Ordering System:**
+1. **Use Creation Date**: Specs are ordered by creation date for stable, conflict-free sequencing
+2. **Add Created Frontmatter**: Include `created: YYYY-MM-DD` in the YAML frontmatter for explicit ordering
+3. **Fallback to File Stats**: If no `created` field exists, use file system creation time as backup
+4. **Display Numbers**: Show position numbers (1., 2., 3.) in navigation UI based on chronological order
+
+**Directory Selection:**
+Choose the appropriate folder based on the feature's primary domain. If unsure, use the package name that will contain the primary implementation.
+
+**Frontmatter Template:**
+```markdown
+---
+title: feature-name
+type: specification  
+created: 2024-01-15
+---
+```
+
+**Benefits of Date-Based Ordering:**
+- **No file renaming**: New specs don't affect existing filenames
+- **Merge conflict free**: Multiple developers can create specs simultaneously
+- **Stable references**: Spec filenames never change after creation
+- **Natural chronology**: Order reflects development timeline
+
+## Quality Checklist
+
+Before finalizing your specification, ensure:
+
+✅ **Concise**: Abstract is one sentence, motivation uses bullet points, requirements are direct
+✅ **Traceability**: Every requirement maps to specific implementation files
+✅ **Testability**: Every requirement can be validated through testing  
+✅ **Measurability**: Performance targets include specific metrics
+✅ **Completeness**: All user workflows are covered by requirements
+✅ **Clarity**: Each requirement has unambiguous acceptance criteria
+✅ **Implementation Ready**: Developers know exactly what to build and where
+✅ **File Location**: Spec is saved to `.mod/specs/<appropriate-folder>/<feature-name>.spec.md`
+
+## Examples
+
+### Hierarchical Requirements Structure:
+```markdown
+## REQ-UX: User Experience Requirements
+
+### REQ-UX-1: Real-time email validation feedback for error correction
+
+**REQ-UX-1.1: Form Components**
+- REQ-UX-1.1.1: Email input with real-time validation feedback
+- REQ-UX-1.1.2: Password input with strength indicator
+- REQ-UX-1.1.3: Submit button with loading/disabled states
+- REQ-UX-1.1.4: Error display areas with ARIA attributes
+
+**REQ-UX-1.2: Validation Logic**
+- REQ-UX-1.2.1: Email format validation on blur event
+- REQ-UX-1.2.2: Password strength calculation with visual feedback
+- REQ-UX-1.2.3: Form submission validation with error handling
+- REQ-UX-1.2.4: Success state with redirect to verification
+
+```
+
+Now generate your specification following this template, ensuring every requirement is traceable from business value to implementation code and can be validated through testing.

package/dist/app.js

@@ -0,0 +1,227 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { Box, Text } from 'ink';
+import TextInput from 'ink-text-input';
+import WorkspacesContainer from './containers/workspaces-container.js';
+import ThreadContainer from './containers/thread-container.js';
+import DirectoryContainer from './containers/directory-container.js';
+import BranchesContainer from './containers/branches-container.js';
+import { useInput } from 'ink';
+import { readModConfig, writeModConfig } from './services/mod-config.js';
+// Removed legacy sync commands and services
+import { BranchService } from '@mod/mod-core/services/branch-service';
+import { getFeatureFlags, shouldEnableBackgroundWatch } from './services/feature-flags.js';
+export default function App({ repo, featureFlags: providedFeatureFlags, }) {
+    const featureFlags = useMemo(() => providedFeatureFlags ?? getFeatureFlags(), [providedFeatureFlags]);
+    const tasksEnabled = featureFlags['tasks-panel'];
+    const directoryEnabled = featureFlags['directory-view'];
+    // Routing: 'workspaces' | 'thread' | 'directory' | 'branches' | 'tasks'
+    const [route, setRoute] = useState('workspaces');
+    const [selectedWorkspace, setSelectedWorkspace] = useState(null);
+    const [selectedThread, setSelectedThread] = useState(null);
+    const [inputValue, setInputValue] = useState('');
+    const [pendingChatInput, setPendingChatInput] = useState('');
+    // const watcherRef = useRef<FileWatcherService | null>(null); // Removed
+    const initialUploadDoneRef = useRef(false); // reserved (disabled)
+    // Keyboard shortcuts for navigation (only Esc to reset)
+    useInput((input, key) => {
+        if (key.escape) {
+            setRoute('workspaces');
+            setSelectedWorkspace(null);
+            setSelectedThread(null);
+            setInputValue('');
+        }
+    });
+    // Command prompt handler
+    const handleInputSubmit = (value) => {
+        const trimmed = value.trim();
+        if (trimmed === '/workspaces') {
+            setRoute('workspaces');
+            setSelectedWorkspace(null);
+            setSelectedThread(null);
+        }
+        else if ((trimmed === '/threads' || trimmed === '/branches') && selectedWorkspace) {
+            setRoute('branches');
+            setSelectedThread(null);
+        }
+        else if (trimmed === '/files' && directoryEnabled) {
+            setRoute('directory');
+        }
+        else if (trimmed === '/tasks' && tasksEnabled && selectedWorkspace) {
+            setRoute('tasks');
+        }
+        else if (trimmed === '/thread' && selectedWorkspace && selectedThread) {
+            setRoute('thread');
+        }
+        else if (trimmed === '/exit') {
+            process.exit(0);
+        }
+        else if (trimmed === '/upload') {
+            // Upload all files in current working directory to active workspace/thread
+            // uploadWorkspaceCommand([], repo).catch(err => console.error('[upload] Failed:', err)); // Removed
+        }
+        else if (trimmed === '/download') {
+            // Download all workspace files to current working directory
+            // downloadWorkspaceCommand([], repo).catch(err => console.error('[download] Failed:', err)); // Removed
+        }
+        else if (route === 'thread' && selectedThread) {
+            // Send message to thread
+            setPendingChatInput(value);
+        }
+        setInputValue('');
+    };
+    // Bootstrap: if .mod/config.json has workspace/branch, jump to thread view (branch-first)
+    useEffect(() => {
+        let cancelled = false;
+        (async () => {
+            try {
+                const cfg = readModConfig();
+                if (!cfg?.workspaceId)
+                    return;
+                const wsHandle = await repo.find(cfg.workspaceId);
+                const wsDoc = await wsHandle.doc();
+                // Branch-first: read branch.threadId
+                const activeBranchId = (cfg.activeBranchId || wsDoc?.activeBranchId);
+                let thread = null;
+                const branchesDocId = wsDoc?.branchesDocId;
+                if (activeBranchId && branchesDocId) {
+                    try {
+                        const branchService = new BranchService(repo);
+                        const branch = await branchService.getBranch(activeBranchId, branchesDocId);
+                        const tid = branch?.threadId;
+                        if (tid) {
+                            try {
+                                const tHandle = await repo.find(tid);
+                                const tDoc = await tHandle.doc();
+                                thread = { id: tDoc?.id || tid, name: tDoc?.name || 'Thread' };
+                            }
+                            catch {
+                                thread = { id: tid, name: 'Thread' };
+                            }
+                        }
+                    }
+                    catch { }
+                }
+                // No implicit thread creation on startup; prefer fast load and let user pick
+                if (!cancelled) {
+                    setSelectedWorkspace({ id: wsDoc.id, name: wsDoc.name });
+                    if (thread) {
+                        setSelectedThread(thread);
+                        setRoute('thread');
+                    }
+                    else {
+                        setRoute('branches');
+                    }
+                }
+            }
+            catch {
+                // ignore
+            }
+        })();
+        return () => { cancelled = true; };
+    }, [repo]);
+    // Background sync: start file watcher when workspace/thread are active (initial bulk upload disabled)
+    useEffect(() => {
+        let cancelled = false;
+        (async () => {
+            try {
+                const workspaceId = selectedWorkspace?.id || readModConfig()?.workspaceId;
+                const threadId = selectedThread?.id;
+                if (!repo || !workspaceId || !threadId)
+                    return;
+                const autoWatch = shouldEnableBackgroundWatch();
+                if (!autoWatch)
+                    return;
+                // Initial bulk upload is intentionally disabled to avoid heavy concurrent writes
+                // File watching removed - using AutomaticFileTracker instead
+                /*
+                if (!watcherRef.current) {
+                  try {
+                    const watcher = new FileWatcherService(repo);
+                    await watcher.startWatching({
+                      workspaceId: workspaceId as any,
+                      threadId: threadId as any,
+                      watchDirectory: process.cwd(),
+                      debounceMs: 300,
+                      verbose: false,
+                    });
+                    if (!cancelled) watcherRef.current = watcher;
+                  } catch (err) {
+                    // Non-blocking
+                  }
+                }
+                */
+            }
+            catch {
+                // ignore
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [repo, selectedWorkspace, selectedThread]);
+    let content = null;
+    if (route === 'workspaces') {
+        content = (_jsx(WorkspacesContainer, { repo: repo, onSelect: ws => {
+                setSelectedWorkspace(ws);
+                try {
+                    writeModConfig({ workspaceId: ws.id });
+                }
+                catch { }
+                setRoute('branches');
+            } }));
+    }
+    else if (route === 'thread' && selectedWorkspace && selectedThread) {
+        content = (_jsx(ThreadContainer, { repo: repo, activeThread: selectedThread, workspace: selectedWorkspace, pendingChatInput: pendingChatInput, onChatInputHandled: () => setPendingChatInput(''), handleInputSubmit: handleInputSubmit }));
+    }
+    else if (route === 'branches' && selectedWorkspace) {
+        content = (_jsx(BranchesContainer, { repo: repo, workspace: selectedWorkspace, onSelect: async (thread) => {
+                setSelectedThread(thread);
+                setRoute('thread');
+                // Persist activeBranchId is handled inside BranchesContainer on select
+                // Legacy sync and watcher removed - using AutomaticFileTracker instead
+                /*
+                // Stop watcher while syncing
+                try { watcherRef.current?.stopWatching(); } catch {}
+                // Perform web -> local sync for the selected branch/thread
+                try {
+                  const wsId = (selectedWorkspace as any).id;
+                  const syncSvc = new WorkspaceSyncService(repo as any);
+                  await syncSvc.syncWorkspaceFiles(wsId as any, (thread as any).id as any, { force: true, verbose: true });
+                } catch (err) {
+                  console.error('[branches] Sync after selection failed:', err);
+                }
+                // Restart watcher on the selected thread
+                try {
+                  const watcher = watcherRef.current || new FileWatcherService(repo);
+                  await watcher.startWatching({
+                    workspaceId: (selectedWorkspace as any).id as any,
+                    threadId: (thread as any).id as any,
+                    watchDirectory: process.cwd(),
+                    debounceMs: 300,
+                    verbose: false,
+                  });
+                  watcherRef.current = watcher;
+                } catch {}
+                */
+            } }));
+    }
+    else if (route === 'tasks' && tasksEnabled && selectedWorkspace) {
+        content = ({ /* TasksContainer removed - legacy task management */});
+    }
+    else if (route === 'directory' && directoryEnabled) {
+        content = (_jsx(DirectoryContainer, { repo: repo, selectedWorkspace: selectedWorkspace, selectedThread: selectedThread }));
+    }
+    else {
+        content = _jsx(Text, { children: "Unknown route." });
+    }
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Box, { flexDirection: "column", flexGrow: 1, children: content }), _jsxs(Box, { borderStyle: "single", paddingX: 1, borderColor: "gray", children: [_jsxs(Text, { color: "gray", children: ['>', " "] }), _jsx(TextInput, { value: inputValue, onChange: setInputValue, onSubmit: handleInputSubmit, focus: true, showCursor: true, placeholder: `Type ${[
+                            '/workspaces',
+                            '/branches',
+                            directoryEnabled ? '/files' : null,
+                            tasksEnabled ? '/tasks' : null,
+                            '/upload',
+                            '/download',
+                            '/exit',
+                        ].filter(Boolean).join(', ')}` })] })] }));
+}