@aion0/forge 0.5.49 → 0.5.50

package/components/ProjectDetail.tsx

@@ -7,6 +7,12 @@ import { TerminalSessionPickerLazy, fetchProjectSessions } from './TerminalLaunc
 const InlinePipelineView = lazy(() => import('./InlinePipelineView'));
 const WorkspaceViewLazy = lazy(() => import('./WorkspaceView'));
 const SessionViewLazy = lazy(() => import('./SessionView'));
+const CraftTabLazy = lazy(() => import('./CraftTabs').then(m => ({ default: m.CraftTab })));
+const CraftBuilderModalLazy = lazy(() => import('./CraftBuilder').then(m => ({ default: m.CraftBuilderModal })));
+const CraftMarketplaceModalLazy = lazy(() => import('./CraftMarketplaceModal'));
+const CraftPublishModalLazy = lazy(() => import('./CraftPublishModal'));
+const CraftManifestEditorLazy = lazy(() => import('./CraftManifestEditor'));
+import CraftsDropdown from './CraftsDropdown';
 
 // ─── Syntax highlighting ─────────────────────────────────
 const KEYWORDS = new Set([
@@ -85,7 +91,27 @@ export default memo(function ProjectDetail({ projectPath, projectName, hasGit }:
   const [diffFile, setDiffFile] = useState<string | null>(null);
   const [projectSkills, setProjectSkills] = useState<{ name: string; displayName: string; type: string; scope: string; version: string; installedVersion: string; hasUpdate: boolean; source: 'registry' | 'local' }[]>([]);
   const [showSkillsDetail, setShowSkillsDetail] = useState(false);
-  const [projectTab, setProjectTab] = useState<'workspace' | 'sessions' | 'code' | 'skills' | 'claudemd' | 'pipelines'>('code');
+  const [projectTab, setProjectTab] = useState<string>('code');
+  const [crafts, setCrafts] = useState<Array<{ name: string; displayName: string; icon?: string; description?: string; scope: string; hasUi: boolean; hasServer: boolean }>>([]);
+  const [craftBuilder, setCraftBuilder] = useState<{ refineName?: string } | null>(null);
+  const [craftMarketplaceOpen, setCraftMarketplaceOpen] = useState(false);
+  const [craftPublishName, setCraftPublishName] = useState<string | null>(null);
+  const [craftManifestName, setCraftManifestName] = useState<string | null>(null);
+  // Once a craft is visited it stays mounted (hidden via CSS) so its terminal + WS persist.
+  const [visitedCrafts, setVisitedCrafts] = useState<Set<string>>(() => new Set());
+  useEffect(() => {
+    if (projectTab.startsWith('craft:')) {
+      const name = projectTab.slice('craft:'.length);
+      setVisitedCrafts(prev => prev.has(name) ? prev : new Set(prev).add(name));
+    }
+  }, [projectTab]);
+  const refreshCrafts = useCallback(() => {
+    fetch(`/api/crafts?projectPath=${encodeURIComponent(projectPath)}`)
+      .then(r => r.ok ? r.json() : { crafts: [] })
+      .then(j => setCrafts(j.crafts || []))
+      .catch(() => {});
+  }, [projectPath]);
+  useEffect(() => { refreshCrafts(); }, [refreshCrafts]);
   // Lazy-mount workspace: only mount after first visit, keep mounted to preserve terminal state
   const [wsMounted, setWsMounted] = useState(false);
   useEffect(() => { if (projectTab === 'workspace') setWsMounted(true); }, [projectTab]);
@@ -617,6 +643,25 @@ export default memo(function ProjectDetail({ projectPath, projectName, hasGit }:
               Pipelines
               {pipelineBindings.length > 0 && <span className="ml-1 text-[9px] opacity-70">({pipelineBindings.length})</span>}
             </button>
+            <CraftsDropdown
+              crafts={crafts}
+              activeTab={projectTab}
+              projectPath={projectPath}
+              onPick={(name) => setProjectTab(`craft:${name}`)}
+              onNew={() => setCraftBuilder({})}
+              onRefine={(name) => setCraftBuilder({ refineName: name })}
+              onPublish={(name) => setCraftPublishName(name)}
+              onMarketplace={() => setCraftMarketplaceOpen(true)}
+              onEditManifest={(name) => setCraftManifestName(name)}
+              onDelete={async (name, displayName) => {
+                if (!confirm(`Delete craft "${displayName}"?\n\nThis removes <project>/.forge/crafts/${name}/ permanently.`)) return;
+                const r = await fetch(`/api/craft-system/delete?projectPath=${encodeURIComponent(projectPath)}&name=${encodeURIComponent(name)}`, { method: 'DELETE' });
+                if (r.ok) {
+                  setProjectTab('code');
+                  refreshCrafts();
+                }
+              }}
+            />
           </div>
         </div>
         {projectTab === 'code' && gitInfo?.lastCommit && (
@@ -1373,6 +1418,65 @@ export default memo(function ProjectDetail({ projectPath, projectName, hasGit }:
         </div>
       )}
 
+      {/* Craft tabs — lazy-mount on first visit, then keep mounted (hidden via CSS)
+          so each craft's terminal panel + WebSocket survive tab switches. */}
+      {crafts.filter(c => visitedCrafts.has(c.name)).map(c => {
+        const isActive = projectTab === `craft:${c.name}`;
+        return (
+          <div key={c.name} className={`flex-1 flex flex-col min-h-0 overflow-hidden ${isActive ? '' : 'hidden'}`}>
+            <Suspense fallback={<div className="p-4 text-xs text-[var(--text-secondary)]">Loading craft {c.displayName}…</div>}>
+              <CraftTabLazy craft={c as any} projectPath={projectPath} projectName={projectName} />
+            </Suspense>
+          </div>
+        );
+      })}
+
+      {/* Craft Marketplace modal */}
+      {craftMarketplaceOpen && (
+        <Suspense fallback={null}>
+          <CraftMarketplaceModalLazy
+            projectPath={projectPath}
+            onClose={() => setCraftMarketplaceOpen(false)}
+            onInstalled={refreshCrafts}
+          />
+        </Suspense>
+      )}
+
+      {/* Craft Publish modal */}
+      {craftPublishName && (
+        <Suspense fallback={null}>
+          <CraftPublishModalLazy
+            projectPath={projectPath}
+            craftName={craftPublishName}
+            onClose={() => setCraftPublishName(null)}
+          />
+        </Suspense>
+      )}
+
+      {/* Craft Manifest editor */}
+      {craftManifestName && (
+        <Suspense fallback={null}>
+          <CraftManifestEditorLazy
+            projectPath={projectPath}
+            craftName={craftManifestName}
+            onClose={() => setCraftManifestName(null)}
+          />
+        </Suspense>
+      )}
+
+      {/* Craft Builder modal */}
+      {craftBuilder && (
+        <Suspense fallback={null}>
+          <CraftBuilderModalLazy
+            projectPath={projectPath}
+            projectName={projectName}
+            refineCraftName={craftBuilder.refineName}
+            onClose={() => setCraftBuilder(null)}
+            onCreated={() => { refreshCrafts(); setCraftBuilder(null); }}
+          />
+        </Suspense>
+      )}
+
       {/* Git panel — bottom (code tab only) */}
       {projectTab === 'code' && gitInfo && (
         <div className="border-t border-[var(--border)] shrink-0">

package/components/SkillsPanel.tsx

@@ -4,6 +4,7 @@ import { useState, useEffect, useCallback, lazy, Suspense } from 'react';
 import { useSidebarResize } from '@/hooks/useSidebarResize';
 
 const PluginsPanel = lazy(() => import('./PluginsPanel'));
+const CraftsMarketplacePanelLazy = lazy(() => import('./CraftsMarketplacePanel'));
 
 type ItemType = 'skill' | 'command';
 
@@ -139,7 +140,7 @@ export default function SkillsPanel({ projectFilter }: { projectFilter?: string
   const [syncing, setSyncing] = useState(false);
   const [loading, setLoading] = useState(true);
   const [installTarget, setInstallTarget] = useState<{ skill: string; show: boolean }>({ skill: '', show: false });
-  const [typeFilter, setTypeFilter] = useState<'all' | 'skill' | 'command' | 'local' | 'rules' | 'plugins'>('all');
+  const [typeFilter, setTypeFilter] = useState<'all' | 'skill' | 'command' | 'local' | 'rules' | 'plugins' | 'crafts'>('all');
   const [localItems, setLocalItems] = useState<{ name: string; type: string; scope: string; fileCount: number; projectPath?: string }[]>([]);
   // Rules (CLAUDE.md templates)
   const [rulesTemplates, setRulesTemplates] = useState<{ id: string; name: string; description: string; tags: string[]; builtin: boolean; isDefault: boolean; content: string }[]>([]);
@@ -372,7 +373,7 @@ export default function SkillsPanel({ projectFilter }: { projectFilter?: string
         <div className="flex items-center gap-2">
           <span className="text-xs font-semibold text-[var(--text-primary)]">Marketplace</span>
           <div className="flex items-center bg-[var(--bg-tertiary)] rounded p-0.5">
-            {([['all', `All (${skills.length})`], ['skill', `Skills (${skillCount})`], ['command', `Commands (${commandCount})`], ['local', `Local (${localCount})`], ['rules', 'Rules'], ['plugins', 'Plugins']] as const).map(([value, label]) => (
+            {([['all', `All (${skills.length})`], ['skill', `Skills (${skillCount})`], ['command', `Commands (${commandCount})`], ['local', `Local (${localCount})`], ['rules', 'Rules'], ['plugins', 'Plugins'], ['crafts', 'Crafts']] as const).map(([value, label]) => (
               <button
                 key={value}
                 onClick={() => setTypeFilter(value)}
@@ -397,7 +398,7 @@ export default function SkillsPanel({ projectFilter }: { projectFilter?: string
         </button>
       </div>
       {/* Search — hide on rules tab */}
-      {typeFilter !== 'rules' && typeFilter !== 'plugins' && <div className="px-3 py-1.5 border-b border-[var(--border)] shrink-0">
+      {typeFilter !== 'rules' && typeFilter !== 'plugins' && typeFilter !== 'crafts' && <div className="px-3 py-1.5 border-b border-[var(--border)] shrink-0">
         <input
           type="text"
           value={searchQuery}
@@ -407,7 +408,7 @@ export default function SkillsPanel({ projectFilter }: { projectFilter?: string
         />
       </div>}
 
-      {typeFilter === 'rules' || typeFilter === 'plugins' ? null : skills.length === 0 ? (
+      {typeFilter === 'rules' || typeFilter === 'plugins' || typeFilter === 'crafts' ? null : skills.length === 0 ? (
         <div className="flex-1 flex flex-col items-center justify-center gap-2 text-[var(--text-secondary)]">
           <p className="text-xs">No skills yet</p>
           <button onClick={sync} className="text-xs px-3 py-1 bg-[var(--accent)] text-white rounded hover:opacity-90">
@@ -984,6 +985,13 @@ export default function SkillsPanel({ projectFilter }: { projectFilter?: string
           <PluginsPanel />
         </Suspense>
       )}
+
+      {/* Crafts — registry browse view */}
+      {typeFilter === 'crafts' && (
+        <Suspense fallback={<div className="p-4 text-xs text-[var(--text-secondary)]">Loading...</div>}>
+          <CraftsMarketplacePanelLazy searchQuery={searchQuery} />
+        </Suspense>
+      )}
     </div>
   );
 }

package/components/TaskDetail.tsx

@@ -184,7 +184,8 @@ export default function TaskDetail({
             </button>
           </div>
         </div>
-        <p className="text-xs text-[var(--text-secondary)] mb-2">{task.prompt}</p>
+        <TaskPromptPreview prompt={task.prompt} />
+
         <div className="flex items-center gap-3 text-[10px] text-[var(--text-secondary)]">
           <span>Created: {new Date(task.createdAt).toLocaleString()}</span>
           {task.startedAt && <span>Started: {new Date(task.startedAt).toLocaleString()}</span>}
@@ -520,3 +521,50 @@ function formatToolContent(content: string): string {
     return content;
   }
 }
+
+// ─── Task prompt preview with click-to-expand ──────────────
+const PROMPT_PREVIEW_MAX = 240;
+
+function TaskPromptPreview({ prompt }: { prompt: string }) {
+  const [open, setOpen] = useState(false);
+  const long = prompt.length > PROMPT_PREVIEW_MAX || prompt.includes('\n');
+  const preview = long ? prompt.slice(0, PROMPT_PREVIEW_MAX).split('\n')[0] : prompt;
+
+  return (
+    <>
+      <div className="flex items-start gap-2 mb-2">
+        <p className="text-xs text-[var(--text-secondary)] flex-1 break-words" title={long ? 'Click to view full prompt' : undefined}>
+          {preview}
+          {long && <span className="text-[var(--text-secondary)] opacity-60">…</span>}
+        </p>
+        {long && (
+          <button
+            onClick={() => setOpen(true)}
+            className="text-[10px] px-1.5 py-0.5 rounded bg-[var(--bg-tertiary)] text-[var(--text-secondary)] hover:bg-[var(--accent)]/20 hover:text-[var(--accent)] shrink-0"
+            title={`${prompt.length} chars · ${prompt.split('\n').length} lines`}
+          >
+            View full
+          </button>
+        )}
+      </div>
+
+      {open && (
+        <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/60 p-4" onClick={() => setOpen(false)}>
+          <div className="bg-[var(--bg-primary)] border border-[var(--border)] rounded-lg shadow-2xl w-[800px] max-w-[95vw] max-h-[85vh] flex flex-col" onClick={e => e.stopPropagation()}>
+            <div className="px-4 py-2 border-b border-[var(--border)] flex items-center gap-2">
+              <span className="text-xs font-semibold text-[var(--text-primary)]">Task prompt</span>
+              <span className="text-[10px] text-[var(--text-secondary)]">{prompt.length.toLocaleString()} chars · {prompt.split('\n').length} lines</span>
+              <div className="flex-1" />
+              <button
+                onClick={() => { navigator.clipboard.writeText(prompt).catch(() => {}); }}
+                className="text-[10px] px-2 py-1 rounded text-[var(--text-secondary)] hover:bg-[var(--bg-tertiary)]"
+              >Copy</button>
+              <button onClick={() => setOpen(false)} className="text-[10px] text-[var(--text-secondary)] hover:text-[var(--text-primary)]">✕</button>
+            </div>
+            <pre className="flex-1 overflow-auto p-4 text-[11px] font-mono whitespace-pre-wrap break-words text-[var(--text-primary)]">{prompt}</pre>
+          </div>
+        </div>
+      )}
+    </>
+  );
+}

package/lib/craft-sdk/client.tsx

@@ -0,0 +1,260 @@
+'use client';
+
+// Client-side SDK exposed to crafts. Lives behind a React context so each craft
+// gets its project + craft scope automatically.
+
+import React, { createContext, useContext, useCallback, useEffect, useState, useRef } from 'react';
+
+interface CraftContextValue {
+  projectPath: string;
+  projectName: string;
+  craftName: string;
+}
+
+const CraftContext = createContext<CraftContextValue | null>(null);
+
+export function CraftSDKProvider({ projectPath, projectName, craftName, children }: {
+  projectPath: string; projectName: string; craftName: string; children: React.ReactNode;
+}) {
+  return <CraftContext.Provider value={{ projectPath, projectName, craftName }}>{children}</CraftContext.Provider>;
+}
+
+function useCraftCtx(): CraftContextValue {
+  const v = useContext(CraftContext);
+  if (!v) throw new Error('Craft SDK hook used outside CraftSDKProvider');
+  return v;
+}
+
+// ── 1. useProject ────────────────────────────────────────
+export interface ProjectInfo {
+  projectPath: string;
+  projectName: string;
+}
+
+export function useProject(): ProjectInfo {
+  const { projectPath, projectName } = useCraftCtx();
+  return { projectPath, projectName };
+}
+
+// ── 2. useForgeFetch ─────────────────────────────────────
+export interface FetchState<T> {
+  data: T | null;
+  loading: boolean;
+  error: string | null;
+  refetch: () => void;
+}
+
+export function useForgeFetch<T = any>(path: string, opts: { auto?: boolean; init?: RequestInit } = {}): FetchState<T> {
+  const { projectPath } = useCraftCtx();
+  const [data, setData] = useState<T | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [tick, setTick] = useState(0);
+
+  const fullPath = path.includes('?') ? `${path}&projectPath=${encodeURIComponent(projectPath)}` : `${path}?projectPath=${encodeURIComponent(projectPath)}`;
+
+  useEffect(() => {
+    if (opts.auto === false) return;
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+    fetch(fullPath, opts.init)
+      .then(async r => {
+        if (!r.ok) throw new Error(`${r.status} ${r.statusText}`);
+        return r.json();
+      })
+      .then(j => { if (!cancelled) { setData(j); setLoading(false); } })
+      .catch(e => { if (!cancelled) { setError(e?.message || String(e)); setLoading(false); } });
+    return () => { cancelled = true; };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [fullPath, tick]);
+
+  return { data, loading, error, refetch: () => setTick(t => t + 1) };
+}
+
+// ── 3. useInject ─────────────────────────────────────────
+export function useInject(): (text: string, opts?: { sessionName?: string }) => Promise<{ ok: boolean; sessionName?: string }> {
+  const { projectPath, projectName, craftName } = useCraftCtx();
+  return useCallback(async (text: string, opts = {}) => {
+    const r = await fetch('/api/craft-system/inject', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ projectPath, text, sessionName: opts.sessionName }),
+    });
+    const j = await r.json();
+    return { ok: !!j.ok, sessionName: j.sessionName };
+  }, [projectPath, projectName, craftName]);
+}
+
+// ── 4. useTask ───────────────────────────────────────────
+export interface TaskHandle {
+  id: string;
+  watch: (onLog: (entry: any) => void, onDone?: (task: any) => void) => () => void;
+  cancel: () => Promise<void>;
+}
+
+export function useTask(): (prompt: string, opts?: { agent?: string }) => Promise<TaskHandle> {
+  const { projectPath, projectName } = useCraftCtx();
+  return useCallback(async (prompt: string, opts = {}) => {
+    const r = await fetch('/api/tasks', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ projectName, projectPath, prompt, agent: opts.agent }),
+    });
+    const t = await r.json();
+    if (!t?.id) throw new Error(t?.error || 'failed to create task');
+    return {
+      id: t.id,
+      watch: (onLog, onDone) => {
+        const es = new EventSource(`/api/tasks/${t.id}/stream`);
+        es.onmessage = (ev) => {
+          try {
+            const data = JSON.parse(ev.data);
+            if (data.type === 'log') onLog(data.entry);
+            else if (data.type === 'complete' && onDone) { onDone(data.task); es.close(); }
+          } catch {}
+        };
+        es.onerror = () => es.close();
+        return () => es.close();
+      },
+      cancel: async () => { await fetch(`/api/tasks/${t.id}/cancel`, { method: 'POST' }); },
+    };
+  }, [projectName, projectPath]);
+}
+
+// ── 5. useStore ──────────────────────────────────────────
+// Stores at <project>/.forge/crafts/<name>/data/<file>.json via /api/crafts/<name>/_store
+export function useStore<T = any>(file: string, defaultValue?: T): [T | null, (next: T) => Promise<void>, { loading: boolean; error: string | null; reload: () => void }] {
+  const { projectPath, craftName } = useCraftCtx();
+  const [value, setValue] = useState<T | null>(defaultValue ?? null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [tick, setTick] = useState(0);
+
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    fetch(`/api/craft-system/storage?projectPath=${encodeURIComponent(projectPath)}&craft=${craftName}&file=${encodeURIComponent(file)}`)
+      .then(async r => r.ok ? r.json() : { value: null })
+      .then(j => { if (!cancelled) { setValue(j.value ?? defaultValue ?? null); setLoading(false); } })
+      .catch(e => { if (!cancelled) { setError(e?.message); setLoading(false); } });
+    return () => { cancelled = true; };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [projectPath, craftName, file, tick]);
+
+  const save = useCallback(async (next: T) => {
+    setValue(next);
+    await fetch(`/api/craft-system/storage?projectPath=${encodeURIComponent(projectPath)}&craft=${craftName}&file=${encodeURIComponent(file)}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ value: next }),
+    });
+  }, [projectPath, craftName, file]);
+
+  return [value, save, { loading, error, reload: () => setTick(t => t + 1) }];
+}
+
+// ── 6. useOpenAPI — load + parse an OpenAPI spec from the project ──
+export interface OpenAPIData {
+  spec: any | null;
+  paths: string[];
+  schemas: Record<string, any>;
+  loading: boolean;
+  error: string | null;
+}
+
+export function useOpenAPI(specPath: string): OpenAPIData {
+  const { projectPath } = useCraftCtx();
+  const [state, setState] = useState<OpenAPIData>({ spec: null, paths: [], schemas: {}, loading: true, error: null });
+  useEffect(() => {
+    let cancelled = false;
+    setState(s => ({ ...s, loading: true }));
+    fetch(`/api/craft-system/helpers/openapi?projectPath=${encodeURIComponent(projectPath)}&path=${encodeURIComponent(specPath)}`)
+      .then(r => r.ok ? r.json() : Promise.reject(new Error(`${r.status}`)))
+      .then(j => { if (!cancelled) setState({ spec: j.spec, paths: j.paths || [], schemas: j.schemas || {}, loading: false, error: null }); })
+      .catch(e => { if (!cancelled) setState(s => ({ ...s, loading: false, error: e.message })); });
+    return () => { cancelled = true; };
+  }, [projectPath, specPath]);
+  return state;
+}
+
+// ── 7. useFile — read a file from the project (optional polling) ──
+export function useFile(path: string, opts: { watch?: number } = {}): { content: string | null; loading: boolean; error: string | null; reload: () => void } {
+  const { projectPath } = useCraftCtx();
+  const [content, setContent] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [tick, setTick] = useState(0);
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    fetch(`/api/craft-system/helpers/file?projectPath=${encodeURIComponent(projectPath)}&path=${encodeURIComponent(path)}`)
+      .then(r => r.ok ? r.text() : Promise.reject(new Error(`${r.status}`)))
+      .then(t => { if (!cancelled) { setContent(t); setLoading(false); } })
+      .catch(e => { if (!cancelled) { setError(e.message); setLoading(false); } });
+    return () => { cancelled = true; };
+  }, [projectPath, path, tick]);
+  useEffect(() => {
+    if (!opts.watch) return;
+    const id = setInterval(() => setTick(t => t + 1), opts.watch);
+    return () => clearInterval(id);
+  }, [opts.watch]);
+  return { content, loading, error, reload: () => setTick(t => t + 1) };
+}
+
+// ── 8. useShell — run a shell command in the project cwd ──
+export function useShell(): (cmd: string, opts?: { timeout?: number }) => Promise<{ stdout: string; stderr: string; code: number }> {
+  const { projectPath } = useCraftCtx();
+  return useCallback(async (cmd, opts = {}) => {
+    const r = await fetch(`/api/craft-system/helpers/shell?projectPath=${encodeURIComponent(projectPath)}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ cmd, timeout: opts.timeout }),
+    });
+    return r.json();
+  }, [projectPath]);
+}
+
+// ── 9. useGit — quick git status / log helpers ──
+export interface GitInfo {
+  branch?: string;
+  changes: { status: string; path: string }[];
+  ahead: number;
+  behind: number;
+  log: { hash: string; message: string; author: string; date: string }[];
+}
+export function useGit(): { info: GitInfo | null; loading: boolean; reload: () => void } {
+  const { projectPath } = useCraftCtx();
+  const [info, setInfo] = useState<GitInfo | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [tick, setTick] = useState(0);
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    fetch(`/api/git?dir=${encodeURIComponent(projectPath)}`)
+      .then(r => r.ok ? r.json() : null)
+      .then(j => { if (!cancelled) { setInfo(j); setLoading(false); } })
+      .catch(() => { if (!cancelled) setLoading(false); });
+    return () => { cancelled = true; };
+  }, [projectPath, tick]);
+  return { info, loading, reload: () => setTick(t => t + 1) };
+}
+
+// ── 10. useToast — quick notification ──
+type ToastFn = (msg: string, kind?: 'info' | 'success' | 'error') => void;
+let globalToast: ToastFn | null = null;
+export function setGlobalToast(fn: ToastFn) { globalToast = fn; }
+export function useToast(): ToastFn {
+  return useCallback((msg, kind = 'info') => {
+    if (globalToast) globalToast(msg, kind);
+    else console.log(`[toast:${kind}]`, msg);
+  }, []);
+}
+
+// Bundle exports for the runtime shim
+export function getSDK() {
+  return {
+    useProject, useForgeFetch, useInject, useTask, useStore,
+    useOpenAPI, useFile, useShell, useGit, useToast,
+  };
+}

package/lib/craft-sdk/server.ts

@@ -0,0 +1,14 @@
+// Server-side SDK — used by craft authors in their `server.ts` file.
+
+import type { CraftServerDef, CraftRouteHandler } from '@/lib/crafts/types';
+
+export function defineCraftServer(def: CraftServerDef): CraftServerDef {
+  // Identity wrapper for type checking + future validation hooks.
+  if (!def || typeof def !== 'object' || !def.routes) {
+    throw new Error('defineCraftServer: routes is required');
+  }
+  return def;
+}
+
+// Re-export types so authors can `import type { ... } from '@forge/craft/server'`.
+export type { CraftServerDef, CraftRouteHandler, ForgeServerApi, CraftRouteHandlerCtx } from '@/lib/crafts/types';

package/lib/crafts/loader.ts

@@ -0,0 +1,117 @@
+// Discovers crafts in a project's .forge/crafts/ + builtins shipped with Forge.
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import * as YAML from 'yaml';
+import type { CraftDescriptor, CraftManifest } from './types';
+
+const BUILTIN_DIR = resolve(process.cwd(), 'lib/builtin-crafts');
+
+function readManifest(dir: string): CraftManifest | null {
+  const yml = join(dir, 'craft.yaml');
+  if (!existsSync(yml)) return null;
+  try {
+    const parsed = YAML.parse(readFileSync(yml, 'utf8')) as CraftManifest;
+    if (!parsed?.name) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function describe(dir: string, scope: 'builtin' | 'project'): CraftDescriptor | null {
+  const m = readManifest(dir);
+  if (!m) return null;
+  const uiFile = m.ui?.tab || 'ui.tsx';
+  const serverFile = m.server?.entry || 'server.ts';
+  return {
+    ...m,
+    __dir: dir,
+    __scope: scope,
+    hasUi: existsSync(join(dir, uiFile)),
+    hasServer: existsSync(join(dir, serverFile)),
+  };
+}
+
+function listChildren(dir: string): string[] {
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];
+  return readdirSync(dir)
+    .filter(n => !n.startsWith('.') && !n.startsWith('_'))
+    .map(n => join(dir, n))
+    .filter(p => statSync(p).isDirectory());
+}
+
+export function listProjectCrafts(projectPath: string): CraftDescriptor[] {
+  const out: CraftDescriptor[] = [];
+  // Builtins first (open-source samples shipped with Forge)
+  for (const dir of listChildren(BUILTIN_DIR)) {
+    const d = describe(dir, 'builtin');
+    if (d) out.push(d);
+  }
+  // Project-local crafts override / extend builtins by name
+  const projDir = join(projectPath, '.forge', 'crafts');
+  for (const dir of listChildren(projDir)) {
+    const d = describe(dir, 'project');
+    if (!d) continue;
+    const idx = out.findIndex(x => x.name === d.name);
+    if (idx >= 0) out[idx] = d; else out.push(d);
+  }
+  return out;
+}
+
+export function getCraft(projectPath: string, name: string): CraftDescriptor | null {
+  return listProjectCrafts(projectPath).find(c => c.name === name) || null;
+}
+
+// Best-effort condition evaluator for showWhen expressions. Tiny DSL only.
+//   hasFile("path/relative/to/project")
+//   always
+export function shouldShow(craft: CraftDescriptor, projectPath: string): boolean {
+  // First gate: requirements (project-type compatibility). If any are declared,
+  // at least one matcher must match. This is the same gate the marketplace uses.
+  if (craft.requires) {
+    if (!matchesRequirements(craft.requires, projectPath)) return false;
+  }
+  // Second gate: explicit ui.showWhen expression
+  const expr = craft.ui?.showWhen;
+  if (!expr || expr.trim() === 'always') return true;
+  const m = expr.match(/^hasFile\(\s*["']([^"']+)["']\s*\)$/);
+  if (m) return existsSync(join(projectPath, m[1]));
+  return true;
+}
+
+// Evaluate craft's requires field against a project path. Returns true when
+// the project satisfies at least one of the declared requirements (OR logic).
+// An empty requires object means "no constraint" → true.
+export function matchesRequirements(req: NonNullable<CraftDescriptor['requires']>, projectPath: string): boolean {
+  const files = req.hasFile || [];
+  const globs = req.hasGlob || [];
+  if (files.length === 0 && globs.length === 0) return true;
+
+  for (const f of files) {
+    if (existsSync(join(projectPath, f))) return true;
+  }
+
+  // Cheap glob match via shell. Bounded; runs once per craft, not per file.
+  for (const g of globs) {
+    try {
+      const r = require('node:child_process').execSync(
+        `find "${projectPath}" -path "${projectPath}/node_modules" -prune -o -path "${projectPath}/.git" -prune -o -name '*' -print 2>/dev/null | head -200 | grep -q -E "${globToRegex(g)}"`,
+        { timeout: 3000, stdio: 'pipe' }
+      );
+      if (r) return true;
+    } catch {
+      // grep -q returns 1 when no match, but execSync throws — ignore
+    }
+  }
+  return false;
+}
+
+function globToRegex(glob: string): string {
+  // Tiny glob → regex: ** → .*, * → [^/]*, . escaped
+  return glob
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*/g, '§§')
+    .replace(/\*/g, '[^/]*')
+    .replace(/§§/g, '.*');
+}