@aion0/forge 0.5.48 → 0.5.50

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, '.*');
+}

package/lib/crafts/registry.ts

@@ -0,0 +1,272 @@
+// Craft marketplace — slim version of skills.ts.
+//
+// Mirrors the Forge skills marketplace pattern: a GitHub-hosted repo with
+// `registry.json` at the root + per-craft folders containing the manifest
+// and ui.tsx/server.ts. Default repo: aiwatching/forge-crafts. Override via
+// settings.craftsRepoUrl.
+//
+// Install state for crafts is implicit (file-system): if
+// <project>/.forge/crafts/<name>/ exists, it's installed. No DB rows needed.
+
+import { existsSync, mkdirSync, writeFileSync, readFileSync, rmSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import * as YAML from 'yaml';
+import { loadSettings } from '../settings';
+import type { CraftManifest, CraftRequirements } from './types';
+import { matchesRequirements, listProjectCrafts } from './loader';
+
+export interface RegistryEntry {
+  name: string;
+  displayName: string;
+  description?: string;
+  version: string;
+  author?: string;
+  tags?: string[];
+  requires?: CraftRequirements;
+  files: string[];                   // relative paths inside the craft dir on the registry
+  sourceUrl?: string;                // GitHub web URL for browsing
+}
+
+export interface RegistryItem extends RegistryEntry {
+  // Per-project install info (populated by listMarketplace for a given project)
+  installed: boolean;
+  installedVersion?: string;
+  hasUpdate: boolean;
+  compatible: boolean;               // requires gate against the project
+}
+
+function getBaseUrl(): string {
+  const s = loadSettings();
+  return (s as any).craftsRepoUrl || 'https://raw.githubusercontent.com/aiwatching/forge-crafts/main';
+}
+
+function compareVersions(a: string, b: string): number {
+  const pa = (a || '0.0.0').split('.').map(Number);
+  const pb = (b || '0.0.0').split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+
+// ── Registry fetch ─────────────────────────────────────
+
+let cachedRegistry: { fetchedAt: number; entries: RegistryEntry[] } | null = null;
+// Short TTL — registry.json is tiny + GitHub Pages caches independently anyway.
+// 5-minute cache used to leave users staring at stale data after their own
+// publish landed; 30s is the right "barely noticeable but still saves repeat
+// hits during a single UI session" balance.
+const REGISTRY_TTL_MS = 30_000;
+
+export function invalidateRegistry() {
+  cachedRegistry = null;
+}
+
+export async function fetchRegistry(force = false): Promise<RegistryEntry[]> {
+  if (!force && cachedRegistry && Date.now() - cachedRegistry.fetchedAt < REGISTRY_TTL_MS) {
+    return cachedRegistry.entries;
+  }
+  const baseUrl = getBaseUrl();
+  try {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), 10000);
+    const res = await fetch(`${baseUrl}/registry.json?_t=${Date.now()}`, {
+      signal: ctrl.signal,
+      headers: { 'Accept': 'application/json', 'Cache-Control': 'no-cache' },
+    });
+    clearTimeout(t);
+    if (!res.ok) {
+      console.warn(`[craft-registry] fetch failed: ${res.status}`);
+      return cachedRegistry?.entries || [];
+    }
+    const data = await res.json() as { crafts?: RegistryEntry[] };
+    const entries = (data.crafts || []).filter(e => e.name && e.version && Array.isArray(e.files));
+    cachedRegistry = { fetchedAt: Date.now(), entries };
+    return entries;
+  } catch (e) {
+    console.warn('[craft-registry] fetch error', e);
+    return cachedRegistry?.entries || [];
+  }
+}
+
+// ── Per-project marketplace listing ────────────────────
+
+export async function listMarketplace(projectPath: string): Promise<RegistryItem[]> {
+  const [entries, projectCrafts] = await Promise.all([
+    fetchRegistry(),
+    Promise.resolve(listProjectCrafts(projectPath)),
+  ]);
+  const installedByName = new Map(projectCrafts.filter(c => c.__scope === 'project').map(c => [c.name, c]));
+
+  return entries.map(e => {
+    const inst = installedByName.get(e.name);
+    const installedVersion = inst?.version;
+    const hasUpdate = !!installedVersion && compareVersions(e.version, installedVersion) > 0;
+    const compatible = e.requires ? matchesRequirements(e.requires, projectPath) : true;
+    return {
+      ...e,
+      installed: !!inst,
+      installedVersion,
+      hasUpdate,
+      compatible,
+    };
+  });
+}
+
+// ── Install / uninstall ────────────────────────────────
+
+export async function installCraft(name: string, projectPath: string): Promise<{ ok: boolean; error?: string }> {
+  // Always pull fresh on install — user just clicked install, can't be stale.
+  const entries = await fetchRegistry(true);
+  const entry = entries.find(e => e.name === name);
+  if (!entry) return { ok: false, error: `craft "${name}" not in registry` };
+
+  const baseUrl = getBaseUrl();
+  const targetDir = join(projectPath, '.forge', 'crafts', name);
+  if (existsSync(targetDir)) {
+    return { ok: false, error: `craft "${name}" already installed at ${targetDir} (uninstall first to upgrade)` };
+  }
+  mkdirSync(targetDir, { recursive: true });
+  mkdirSync(join(targetDir, 'data'), { recursive: true });
+
+  for (const rel of entry.files) {
+    try {
+      const url = `${baseUrl}/${name}/${rel}?_t=${Date.now()}`;
+      const res = await fetch(url, { headers: { 'Cache-Control': 'no-cache' } });
+      if (!res.ok) throw new Error(`${url}: ${res.status}`);
+      const text = await res.text();
+      const dest = join(targetDir, rel);
+      mkdirSync(join(dest, '..'), { recursive: true });
+      writeFileSync(dest, text, 'utf8');
+    } catch (e: any) {
+      // Roll back partial install
+      try { rmSync(targetDir, { recursive: true, force: true }); } catch {}
+      return { ok: false, error: `download failed: ${e?.message || e}` };
+    }
+  }
+  return { ok: true };
+}
+
+export function uninstallCraft(name: string, projectPath: string): { ok: boolean; error?: string } {
+  const targetDir = join(projectPath, '.forge', 'crafts', name);
+  if (!existsSync(targetDir)) return { ok: false, error: 'not installed' };
+  rmSync(targetDir, { recursive: true, force: true });
+  return { ok: true };
+}
+
+// In-place update — preserves <project>/.forge/crafts/<name>/data/ (which holds
+// useStore JSON) and overwrites everything else. Atomic: downloads first, then
+// writes; if any download fails the existing install is untouched.
+export async function updateCraft(name: string, projectPath: string): Promise<{ ok: boolean; error?: string; from?: string; to?: string }> {
+  const targetDir = join(projectPath, '.forge', 'crafts', name);
+  if (!existsSync(targetDir)) return { ok: false, error: 'not installed' };
+
+  const entries = await fetchRegistry(true);
+  const entry = entries.find(e => e.name === name);
+  if (!entry) return { ok: false, error: `craft "${name}" not in registry` };
+
+  // Read current version from local craft.yaml for the response
+  let fromVersion: string | undefined;
+  try {
+    const m = YAML.parse(readFileSync(join(targetDir, 'craft.yaml'), 'utf8')) as any;
+    fromVersion = m?.version;
+  } catch {}
+
+  // Download everything into memory first
+  const baseUrl = getBaseUrl();
+  const downloaded: { rel: string; content: string }[] = [];
+  for (const rel of entry.files) {
+    try {
+      const res = await fetch(`${baseUrl}/${name}/${rel}?_t=${Date.now()}`, { headers: { 'Cache-Control': 'no-cache' } });
+      if (!res.ok) throw new Error(`${rel}: HTTP ${res.status}`);
+      downloaded.push({ rel, content: await res.text() });
+    } catch (e: any) {
+      return { ok: false, error: `download failed for ${rel}: ${e?.message || e}` };
+    }
+  }
+
+  // All downloads succeeded — write them. data/ stays intact.
+  const fs = require('node:fs');
+  for (const d of downloaded) {
+    const dest = join(targetDir, d.rel);
+    mkdirSync(dest.split('/').slice(0, -1).join('/'), { recursive: true });
+    fs.writeFileSync(dest, d.content, 'utf8');
+  }
+  return { ok: true, from: fromVersion, to: entry.version };
+}
+
+// Returns just the names of installed crafts that have updates available.
+// Used by the dropdown badge — cheap, no per-craft enrichment beyond version
+// compare.
+export async function listAvailableUpdates(projectPath: string): Promise<{ name: string; from?: string; to: string }[]> {
+  const items = await listMarketplace(projectPath);
+  return items
+    .filter(it => it.installed && it.hasUpdate)
+    .map(it => ({ name: it.name, from: it.installedVersion, to: it.version }));
+}
+
+// ── File scanner ───────────────────────────────────────
+
+const EXCLUDE_DIRS = new Set(['data', '.git', 'node_modules', '.next', 'dist', 'build', '.cache']);
+const EXCLUDE_FILES = new Set(['prompt.md', '.DS_Store']);
+const INCLUDE_EXT = new Set(['.yaml', '.yml', '.tsx', '.ts', '.jsx', '.js', '.md', '.json', '.css']);
+const MAX_FILE_BYTES = 1024 * 1024;   // 1 MB per file
+
+function collectCraftFiles(dir: string): { path: string; content: string }[] {
+  const out: { path: string; content: string }[] = [];
+  const walk = (d: string) => {
+    for (const name of readdirSync(d)) {
+      if (name.startsWith('.') && name !== '.gitignore') continue;
+      if (EXCLUDE_FILES.has(name)) continue;
+      const full = join(d, name);
+      const st = statSync(full);
+      if (st.isDirectory()) {
+        if (EXCLUDE_DIRS.has(name)) continue;
+        walk(full);
+        continue;
+      }
+      if (!st.isFile()) continue;
+      if (st.size > MAX_FILE_BYTES) continue;
+      const ext = name.lastIndexOf('.') >= 0 ? name.slice(name.lastIndexOf('.')) : '';
+      if (ext && !INCLUDE_EXT.has(ext)) continue;
+      out.push({ path: relative(dir, full), content: readFileSync(full, 'utf8') });
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+// ── Publish helper ─────────────────────────────────────
+// MVP: returns a registry-entry JSON snippet + a tar of the craft dir for
+// the user to attach to a PR on the registry repo. Real "press a button to
+// publish" requires GitHub auth + write — out of scope for v1.
+
+export function bundleCraftForPublish(projectPath: string, craftName: string): { entry: RegistryEntry; files: { path: string; content: string }[]; error?: string } {
+  const dir = join(projectPath, '.forge', 'crafts', craftName);
+  if (!existsSync(dir)) return { entry: null as any, files: [], error: 'craft not found' };
+
+  let manifest: CraftManifest;
+  try {
+    manifest = YAML.parse(readFileSync(join(dir, 'craft.yaml'), 'utf8'));
+  } catch {
+    return { entry: null as any, files: [], error: 'craft.yaml unreadable' };
+  }
+
+  // Recursive scan — pick up arbitrary multi-file crafts (e.g. server.ts split
+  // into _types.ts / _runner.ts / etc.) while excluding runtime data, history,
+  // and anything obviously not source.
+  const files = collectCraftFiles(dir);
+
+  const entry: RegistryEntry = {
+    name: manifest.name,
+    displayName: manifest.displayName || manifest.name,
+    description: manifest.description,
+    version: manifest.version || '0.1.0',
+    author: manifest.author,
+    tags: manifest.tags,
+    requires: manifest.requires,
+    files: files.map(f => f.path),
+  };
+  return { entry, files };
+}