@aion0/forge 0.3.4 → 0.3.6

package/CLAUDE.md

@@ -47,6 +47,21 @@ forge watch <id>         # live stream task output
 - npm package: `@aion0/forge`
 - GitHub: `github.com/aiwatching/forge`
 
+### Help Docs Rule
+When adding or changing a feature, check if `lib/help-docs/` needs updating. Each file covers one module:
+- `00-overview.md` — install, start, data paths
+- `01-settings.md` — all settings fields
+- `02-telegram.md` — bot setup and commands
+- `03-tunnel.md` — remote access
+- `04-tasks.md` — background tasks
+- `05-pipelines.md` — DAG workflows
+- `06-skills.md` — marketplace
+- `07-projects.md` — project management
+- `08-rules.md` — CLAUDE.md templates
+- `09-issue-autofix.md` — GitHub issue scanner
+- `10-troubleshooting.md` — common issues
+If a feature change affects user-facing behavior, update the corresponding help doc in the same commit.
+
 ### Architecture
 - `forge-server.mjs` starts: Next.js + terminal-standalone + telegram-standalone
 - `pnpm dev` / `start.sh dev` starts: Next.js (init.ts spawns terminal + telegram)

package/app/api/favorites/route.ts

@@ -0,0 +1,26 @@
+import { NextResponse } from 'next/server';
+import { getDb } from '@/src/core/db/database';
+import { getDbPath } from '@/src/config';
+
+function db() { return getDb(getDbPath()); }
+
+// GET /api/favorites — list all favorites
+export async function GET() {
+  const rows = db().prepare('SELECT project_path FROM project_favorites ORDER BY created_at ASC').all() as any[];
+  return NextResponse.json(rows.map(r => r.project_path));
+}
+
+// POST /api/favorites — add or remove
+export async function POST(req: Request) {
+  const { action, projectPath } = await req.json();
+  if (!projectPath) return NextResponse.json({ error: 'projectPath required' }, { status: 400 });
+
+  if (action === 'add') {
+    db().prepare('INSERT OR IGNORE INTO project_favorites (project_path) VALUES (?)').run(projectPath);
+  } else if (action === 'remove') {
+    db().prepare('DELETE FROM project_favorites WHERE project_path = ?').run(projectPath);
+  }
+
+  const rows = db().prepare('SELECT project_path FROM project_favorites ORDER BY created_at ASC').all() as any[];
+  return NextResponse.json(rows.map(r => r.project_path));
+}

package/app/api/git/route.ts

@@ -1,8 +1,9 @@
 import { NextResponse, type NextRequest } from 'next/server';
-import { execSync } from 'node:child_process';
+import { execSync, exec } from 'node:child_process';
 import { existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
+import { promisify } from 'node:util';
 import { loadSettings } from '@/lib/settings';
 
 function isUnderProjectRoot(dir: string): boolean {
@@ -11,8 +12,17 @@ function isUnderProjectRoot(dir: string): boolean {
   return roots.some(root => dir.startsWith(root) || dir === root);
 }
 
-function git(cmd: string, cwd: string): string {
-  return execSync(`git ${cmd}`, { cwd, encoding: 'utf-8', timeout: 15000, stdio: ['pipe', 'pipe', 'pipe'] }).toString().trim();
+const execAsync = promisify(exec);
+
+function gitSync(cmd: string, cwd: string): string {
+  return execSync(`git ${cmd}`, { cwd, encoding: 'utf-8', timeout: 10000, stdio: ['pipe', 'pipe', 'pipe'] }).toString().trim();
+}
+
+async function gitAsync(cmd: string, cwd: string): Promise<string> {
+  try {
+    const { stdout } = await execAsync(`git ${cmd}`, { cwd, encoding: 'utf-8', timeout: 10000 });
+    return stdout.trim();
+  } catch { return ''; }
 }
 
 // GET /api/git?dir=<path> — git status for a project
@@ -23,38 +33,33 @@ export async function GET(req: NextRequest) {
   }
 
   try {
-    const branch = git('rev-parse --abbrev-ref HEAD', dir);
-    const statusRaw = execSync('git status --porcelain -u', { cwd: dir, encoding: 'utf-8', timeout: 15000, stdio: ['pipe', 'pipe', 'pipe'] }).toString();
-    const changes = statusRaw.replace(/\n$/, '').split('\n').filter(Boolean).map(line => ({
+    // Run all git commands in parallel
+    const [branchOut, statusOut, remoteOut, lastCommitOut, logOut] = await Promise.all([
+      gitAsync('rev-parse --abbrev-ref HEAD', dir),
+      gitAsync('status --porcelain -u', dir),
+      gitAsync('remote get-url origin', dir),
+      gitAsync('log -1 --format="%h %s"', dir),
+      gitAsync('log --format="%h||%s||%an||%ar" -10', dir),
+    ]);
+
+    const branch = branchOut;
+    const changes = statusOut ? statusOut.split('\n').filter(Boolean).map(line => ({
       status: line.substring(0, 2).trim() || 'M',
       path: line.substring(3).replace(/\/$/, ''),
-    }));
-
-    let remote = '';
-    try { remote = git('remote get-url origin', dir); } catch {}
+    })) : [];
 
-    let ahead = 0;
-    let behind = 0;
+    let ahead = 0, behind = 0;
     try {
-      const counts = git(`rev-list --left-right --count HEAD...origin/${branch}`, dir);
-      const [a, b] = counts.split('\t');
-      ahead = parseInt(a) || 0;
-      behind = parseInt(b) || 0;
+      const counts = await gitAsync(`rev-list --left-right --count HEAD...origin/${branch}`, dir);
+      if (counts) { const [a, b] = counts.split('\t'); ahead = parseInt(a) || 0; behind = parseInt(b) || 0; }
     } catch {}
 
-    const lastCommit = git('log -1 --format="%h %s" 2>/dev/null || echo ""', dir);
-
-    // Git log — recent commits
-    let log: { hash: string; message: string; author: string; date: string }[] = [];
-    try {
-      const logOut = git('log --format="%h||%s||%an||%ar" -20', dir);
-      log = logOut.split('\n').filter(Boolean).map(line => {
-        const [hash, message, author, date] = line.split('||');
-        return { hash, message, author, date };
-      });
-    } catch {}
+    const log = logOut ? logOut.split('\n').filter(Boolean).map(line => {
+      const [hash, message, author, date] = line.split('||');
+      return { hash, message, author, date };
+    }) : [];
 
-    return NextResponse.json({ branch, changes, remote, ahead, behind, lastCommit, log });
+    return NextResponse.json({ branch, changes, remote: remoteOut, ahead, behind, lastCommit: lastCommitOut, log });
   } catch (e: any) {
     return NextResponse.json({ error: e.message }, { status: 500 });
   }
@@ -96,30 +101,30 @@ export async function POST(req: NextRequest) {
       if (!message) return NextResponse.json({ error: 'message required' }, { status: 400 });
       if (files && files.length > 0) {
         for (const f of files) {
-          git(`add "${f}"`, dir);
+          gitSync(`add "${f}"`, dir);
         }
       } else {
-        git('add -A', dir);
+        gitSync('add -A', dir);
       }
-      git(`commit -m "${message.replace(/"/g, '\\"')}"`, dir);
+      gitSync(`commit -m "${message.replace(/"/g, '\\"')}"`, dir);
       return NextResponse.json({ ok: true });
     }
 
     if (action === 'push') {
-      const output = git('push', dir);
+      const output = gitSync('push', dir);
       return NextResponse.json({ ok: true, output });
     }
 
     if (action === 'pull') {
-      const output = git('pull', dir);
+      const output = gitSync('pull', dir);
       return NextResponse.json({ ok: true, output });
     }
 
     if (action === 'stage') {
       if (files && files.length > 0) {
-        for (const f of files) git(`add "${f}"`, dir);
+        for (const f of files) gitSync(`add "${f}"`, dir);
       } else {
-        git('add -A', dir);
+        gitSync('add -A', dir);
       }
       return NextResponse.json({ ok: true });
     }

package/app/api/help/route.ts

@@ -0,0 +1,78 @@
+import { NextResponse } from 'next/server';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getConfigDir } from '@/lib/dirs';
+import { loadSettings } from '@/lib/settings';
+import { execSync } from 'node:child_process';
+
+const HELP_DIR = join(getConfigDir(), 'help');
+const SOURCE_HELP_DIR = join(process.cwd(), 'lib', 'help-docs');
+
+/** Ensure help docs are copied to ~/.forge/help/ */
+function ensureHelpDocs() {
+  if (!existsSync(HELP_DIR)) mkdirSync(HELP_DIR, { recursive: true });
+  if (existsSync(SOURCE_HELP_DIR)) {
+    for (const file of readdirSync(SOURCE_HELP_DIR)) {
+      if (!file.endsWith('.md')) continue;
+      const src = join(SOURCE_HELP_DIR, file);
+      const dest = join(HELP_DIR, file);
+      // Always overwrite to keep docs up to date
+      writeFileSync(dest, readFileSync(src));
+    }
+  }
+}
+
+/** Check if any agent CLI is available */
+function detectAgent(): { name: string; path: string } | null {
+  const settings = loadSettings();
+  if (settings.claudePath) {
+    try {
+      execSync(`"${settings.claudePath}" --version`, { timeout: 5000, stdio: 'pipe' });
+      return { name: 'claude', path: settings.claudePath };
+    } catch {}
+  }
+  for (const agent of ['claude', 'codex', 'aider']) {
+    try {
+      const path = execSync(`which ${agent}`, { encoding: 'utf-8', timeout: 3000, stdio: 'pipe' }).trim();
+      if (path) return { name: agent, path };
+    } catch {}
+  }
+  return null;
+}
+
+// GET /api/help
+export async function GET(req: Request) {
+  const { searchParams } = new URL(req.url);
+  const action = searchParams.get('action') || 'status';
+
+  if (action === 'status') {
+    const agent = detectAgent();
+    ensureHelpDocs();
+    const docs = existsSync(HELP_DIR)
+      ? readdirSync(HELP_DIR).filter(f => f.endsWith('.md')).sort()
+      : [];
+    return NextResponse.json({ agent, docsCount: docs.length, helpDir: HELP_DIR });
+  }
+
+  if (action === 'docs') {
+    ensureHelpDocs();
+    const docs = existsSync(HELP_DIR)
+      ? readdirSync(HELP_DIR).filter(f => f.endsWith('.md')).sort().map(f => ({
+          name: f,
+          title: f.replace(/^\d+-/, '').replace(/\.md$/, '').replace(/-/g, ' '),
+        }))
+      : [];
+    return NextResponse.json({ docs });
+  }
+
+  if (action === 'doc') {
+    const name = searchParams.get('name');
+    if (!name) return NextResponse.json({ error: 'name required' }, { status: 400 });
+    ensureHelpDocs();
+    const file = join(HELP_DIR, name);
+    if (!existsSync(file)) return NextResponse.json({ error: 'Not found' }, { status: 404 });
+    return NextResponse.json({ content: readFileSync(file, 'utf-8') });
+  }
+
+  return NextResponse.json({ error: 'Invalid action' }, { status: 400 });
+}

package/app/api/skills/route.ts

@@ -99,8 +99,6 @@ export async function GET(req: Request) {
       return NextResponse.json({ content: '(Failed to load)' });
     }
   }
-  // Refresh install state from filesystem
-  refreshInstallState(getProjectPaths());
   const skills = listSkills();
   const projects = getProjectPaths().map(p => ({ path: p, name: p.split('/').pop() || p }));
   return NextResponse.json({ skills, projects });

package/app/api/tabs/route.ts

@@ -0,0 +1,25 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { getDb } from '@/src/core/db/database';
+import { getDbPath } from '@/src/config';
+
+function db() { return getDb(getDbPath()); }
+
+export async function GET(req: NextRequest) {
+  const type = req.nextUrl.searchParams.get('type') || 'projects';
+  try {
+    const row = db().prepare('SELECT data FROM tab_state WHERE type = ?').get(type) as any;
+    if (row?.data) return NextResponse.json(JSON.parse(row.data));
+  } catch {}
+  return NextResponse.json({ tabs: [], activeTabId: 0 });
+}
+
+export async function POST(req: NextRequest) {
+  const type = req.nextUrl.searchParams.get('type') || 'projects';
+  try {
+    const body = await req.json();
+    db().prepare('INSERT OR REPLACE INTO tab_state (type, data) VALUES (?, ?)').run(type, JSON.stringify(body));
+    return NextResponse.json({ ok: true });
+  } catch (e: any) {
+    return NextResponse.json({ ok: false, error: e.message }, { status: 500 });
+  }
+}

package/bin/forge-server.mjs

@@ -189,7 +189,7 @@ if (!isStop) {
     writeFileSync(settingsFile, YAML.stringify(settings), 'utf-8');
     console.log('[forge] Admin password saved');
 
-    if (resetPassword && !isDev && !isBackground && !isRestart) {
+    if (resetPassword) {
       process.exit(0);
     }
   }

package/components/Dashboard.tsx

@@ -18,6 +18,7 @@ const CodeViewer = lazy(() => import('./CodeViewer'));
 const ProjectManager = lazy(() => import('./ProjectManager'));
 const PreviewPanel = lazy(() => import('./PreviewPanel'));
 const PipelineView = lazy(() => import('./PipelineView'));
+const HelpDialog = lazy(() => import('./HelpDialog'));
 const SkillsPanel = lazy(() => import('./SkillsPanel'));
 
 interface UsageSummary {
@@ -47,6 +48,7 @@ export default function Dashboard({ user }: { user: any }) {
   const [showNewTask, setShowNewTask] = useState(false);
   const [showSettings, setShowSettings] = useState(false);
   const [showMonitor, setShowMonitor] = useState(false);
+  const [showHelp, setShowHelp] = useState(false);
   const [usage, setUsage] = useState<UsageSummary[]>([]);
   const [providers, setProviders] = useState<ProviderInfo[]>([]);
   const [projects, setProjects] = useState<ProjectInfo[]>([]);
@@ -262,6 +264,15 @@ export default function Dashboard({ user }: { user: any }) {
               + New Task
             </button>
           )}
+          {/* Help */}
+          <button
+            onClick={() => setShowHelp(v => !v)}
+            className={`text-[10px] px-2 py-0.5 border rounded transition-colors ${
+              showHelp
+                ? 'border-[var(--accent)] text-[var(--accent)]'
+                : 'border-[var(--border)] text-[var(--text-secondary)] hover:text-[var(--text-primary)] hover:border-[var(--text-secondary)]'
+            }`}
+          >?</button>
           {/* Preview + Tunnel */}
           <button
             onClick={() => setViewMode('preview')}
@@ -597,6 +608,11 @@ export default function Dashboard({ user }: { user: any }) {
       {showSettings && (
         <SettingsModal onClose={() => { setShowSettings(false); fetchData(); refreshDisplayName(); }} />
       )}
+      {showHelp && (
+        <Suspense fallback={null}>
+          <HelpDialog onClose={() => setShowHelp(false)} />
+        </Suspense>
+      )}
     </div>
   );
 }

package/components/DocsViewer.tsx

@@ -2,9 +2,21 @@
 
 import { useState, useEffect, useCallback, useRef, lazy, Suspense } from 'react';
 import MarkdownContent from './MarkdownContent';
+import TabBar from './TabBar';
 
 const DocTerminal = lazy(() => import('./DocTerminal'));
 
+interface DocTab {
+  id: number;
+  filePath: string;
+  fileName: string;
+  rootIdx: number;
+  content: string | null;
+  isImage: boolean;
+}
+
+function genTabId(): number { return Date.now() + Math.floor(Math.random() * 10000); }
+
 interface FileNode {
   name: string;
   path: string;
@@ -89,6 +101,141 @@ export default function DocsViewer() {
   const [saving, setSaving] = useState(false);
   const dragRef = useRef<{ startY: number; startH: number } | null>(null);
 
+  // Doc tabs
+  const [docTabs, setDocTabs] = useState<DocTab[]>([]);
+  const [activeDocTabId, setActiveDocTabId] = useState(0);
+  const saveTimerRef = useRef<any>(null);
+
+  // Load tabs from DB on mount
+  useEffect(() => {
+    fetch('/api/tabs?type=docs').then(r => r.json())
+      .then(data => {
+        if (Array.isArray(data.tabs) && data.tabs.length > 0) {
+          setDocTabs(data.tabs);
+          setActiveDocTabId(data.activeTabId || data.tabs[0].id);
+          // Set selectedFile to active tab's file
+          const activeId = data.activeTabId || data.tabs[0].id;
+          const active = data.tabs.find((t: any) => t.id === activeId);
+          if (active) {
+            setSelectedFile(active.filePath);
+            // Content not stored in DB, fetch it
+            if (!active.isImage) {
+              fetch(`/api/docs?root=${active.rootIdx}&file=${encodeURIComponent(active.filePath)}`)
+                .then(r => r.json())
+                .then(d => { setContent(d.content || null); })
+                .catch(() => {});
+            }
+          }
+        }
+      }).catch(() => {});
+  }, []);
+
+  // Persist tabs (debounced)
+  const persistDocTabs = useCallback((tabs: DocTab[], activeId: number) => {
+    if (saveTimerRef.current) clearTimeout(saveTimerRef.current);
+    saveTimerRef.current = setTimeout(() => {
+      fetch('/api/tabs?type=docs', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          tabs: tabs.map(t => ({ id: t.id, filePath: t.filePath, fileName: t.fileName, rootIdx: t.rootIdx, isImage: t.isImage })),
+          activeTabId: activeId,
+        }),
+      }).catch(() => {});
+    }, 500);
+  }, []);
+
+  // Open file in tab
+  const openFileInTab = useCallback(async (path: string) => {
+    setSelectedFile(path);
+    setEditing(false);
+    setFileWarning(null);
+
+    const isImg = isImageFile(path);
+    const fileName = path.split('/').pop() || path;
+
+    // Check if tab already exists (use functional update to get latest state)
+    let found = false;
+    setDocTabs(prev => {
+      const existing = prev.find(t => t.filePath === path);
+      if (existing) {
+        found = true;
+        setActiveDocTabId(existing.id);
+        setContent(existing.content);
+        persistDocTabs(prev, existing.id);
+      }
+      return prev;
+    });
+    if (found) return;
+
+    // Fetch content
+    let fileContent: string | null = null;
+    if (!isImg) {
+      setLoading(true);
+      const res = await fetch(`/api/docs?root=${activeRoot}&file=${encodeURIComponent(path)}`);
+      const data = await res.json();
+      if (data.tooLarge) {
+        setFileWarning(`File too large (${data.sizeLabel})`);
+      } else {
+        fileContent = data.content || null;
+      }
+      setLoading(false);
+    }
+    setContent(fileContent);
+
+    const newTab: DocTab = { id: genTabId(), filePath: path, fileName, rootIdx: activeRoot, isImage: isImg, content: fileContent };
+    setDocTabs(prev => {
+      // Double-check no duplicate
+      if (prev.find(t => t.filePath === path)) return prev;
+      const updated = [...prev, newTab];
+      setActiveDocTabId(newTab.id);
+      persistDocTabs(updated, newTab.id);
+      return updated;
+    });
+  }, [activeRoot, persistDocTabs]);
+
+  const closeDocTab = useCallback((tabId: number) => {
+    setDocTabs(prev => {
+      const updated = prev.filter(t => t.id !== tabId);
+      let newActiveId = activeDocTabId;
+      if (tabId === activeDocTabId) {
+        const idx = prev.findIndex(t => t.id === tabId);
+        const next = updated[Math.min(idx, updated.length - 1)];
+        newActiveId = next?.id || 0;
+        if (next) { setSelectedFile(next.filePath); setContent(next.content); }
+        else { setSelectedFile(null); setContent(null); }
+      }
+      setActiveDocTabId(newActiveId);
+      persistDocTabs(updated, newActiveId);
+      return updated;
+    });
+  }, [activeDocTabId, persistDocTabs]);
+
+  const activateDocTab = useCallback(async (tabId: number) => {
+    const tab = docTabs.find(t => t.id === tabId);
+    if (tab) {
+      setActiveDocTabId(tabId);
+      setSelectedFile(tab.filePath);
+      setEditing(false);
+      if (tab.rootIdx !== activeRoot) setActiveRoot(tab.rootIdx);
+      persistDocTabs(docTabs, tabId);
+
+      // Use cached content or re-fetch
+      if (tab.content) {
+        setContent(tab.content);
+      } else if (!tab.isImage) {
+        setLoading(true);
+        const res = await fetch(`/api/docs?root=${tab.rootIdx}&file=${encodeURIComponent(tab.filePath)}`);
+        const data = await res.json();
+        const fetched = data.content || null;
+        setContent(fetched);
+        // Cache in tab
+        setDocTabs(prev => prev.map(t => t.id === tabId ? { ...t, content: fetched } : t));
+        setLoading(false);
+      }
+    }
+  }, [docTabs, activeRoot, persistDocTabs]);
+
   // Fetch tree
   const fetchTree = useCallback(async (rootIdx: number) => {
     const res = await fetch(`/api/docs?root=${rootIdx}`);
@@ -223,7 +370,7 @@ export default function DocsViewer() {
                   filtered.map(f => (
                     <button
                       key={f.path}
-                      onClick={() => { openFile(f.path); setSearch(''); }}
+                      onClick={() => { openFileInTab(f.path); setSearch(''); }}
                       className={`w-full text-left px-2 py-1 rounded text-xs truncate ${
                         selectedFile === f.path ? 'bg-[var(--accent)]/20 text-[var(--accent)]' : 'hover:bg-[var(--bg-tertiary)] text-[var(--text-secondary)]'
                       }`}
@@ -236,15 +383,25 @@ export default function DocsViewer() {
                 )
               ) : (
                 tree.map(node => (
-                  <TreeNode key={node.path} node={node} depth={0} selected={selectedFile} onSelect={openFile} />
+                  <TreeNode key={node.path} node={node} depth={0} selected={selectedFile} onSelect={openFileInTab} />
                 ))
               )}
             </div>
           </aside>
         )}
 
-        {/* Main content — full width markdown */}
+        {/* Main content */}
         <main className="flex-1 flex flex-col min-w-0">
+          {/* Doc tab bar */}
+          {docTabs.length > 0 && (
+            <TabBar
+              tabs={docTabs.map(t => ({ id: t.id, label: t.fileName.replace(/\.md$/, '') }))}
+              activeId={activeDocTabId}
+              onActivate={activateDocTab}
+              onClose={closeDocTab}
+            />
+          )}
+
           {/* Top bar */}
           <div className="px-3 py-1.5 border-b border-[var(--border)] shrink-0 flex items-center gap-2">
             <button