@aion0/forge 0.5.49 → 0.5.50

package/lib/forge-skills/craft-builder.md

@@ -0,0 +1,231 @@
+---
+name: craft-builder
+description: Build a Forge "Craft" — a project-scoped mini-app exposed as a tab in Forge. Use when the user asks Forge to "make a tab/dashboard/tool that does X" inside their project.
+---
+
+# Forge Craft Builder
+
+A **Craft** is a project-scoped mini-app that appears as a tab in Forge. It can have:
+
+- A React UI (`ui.tsx`) — renders inside Forge's project view
+- An optional API server (`server.ts`) — handlers run on Forge's Node process
+
+Crafts live at `<project>/.forge/crafts/<craft-name>/` and travel with the project (commit them to git so the team sees the same tabs).
+
+## Your job
+
+When invoked, you produce ALL of these files in `<project>/.forge/crafts/<name>/`:
+
+```
+craft.yaml      # manifest
+ui.tsx          # React component (default export)
+server.ts       # optional — only if user needs server-side work
+prompt.md       # the original user request + iteration history (you maintain this)
+README.md       # 1-paragraph "what it does"
+data/           # auto-created when craft writes via useStore
+```
+
+After writing files, tell the user the new tab will appear in Forge after refresh (or hot-reload if dev mode).
+
+## Naming
+
+Pick a kebab-case `name` based on what the user asked for. Keep it short. Example: "API endpoint dashboard" → `api-dashboard`.
+
+The `displayName` is the tab label — include an emoji prefix matching the function (📊 for dashboards, 🔍 for explorers, ⚡ for runners, 📝 for editors, 🧪 for testers).
+
+## SDK — UI side (`ui.tsx`)
+
+Import from `@forge/craft`. ONLY these hooks are available:
+
+```tsx
+import { useProject, useForgeFetch, useInject, useTask, useStore } from '@forge/craft';
+
+// 1. Project context
+const { projectPath, projectName } = useProject();
+
+// 2. Fetch data — auto-appends ?projectPath=...; returns { data, loading, error, refetch }
+const { data, loading, error, refetch } = useForgeFetch<MyType>('/api/crafts/<your-name>/items');
+// or any Forge core API:
+const git = useForgeFetch('/api/git/status');
+
+// 3. Inject text into the project's bound tmux terminal (auto-resolves session)
+const inject = useInject();
+await inject('Run the test suite');  // sends text + Enter
+
+// 4. Spawn a Forge background task in the project
+const runTask = useTask();
+const t = await runTask('Refactor the auth module per CLAUDE.md');
+const stop = t.watch(entry => console.log(entry), final => console.log('done', final));
+
+// 5. Persistent JSON storage in <project>/.forge/crafts/<name>/data/<file>.json
+const [items, setItems, { loading, reload }] = useStore<Item[]>('items.json', []);
+await setItems([...items!, newItem]);  // writes to disk
+```
+
+Component must `export default` a React component. Use Tailwind classes and Forge CSS variables (`var(--accent)`, `var(--bg-secondary)`, `var(--text-primary)`, `var(--text-secondary)`, `var(--border)`, `var(--bg-primary)`, `var(--bg-tertiary)`) so the tab matches Forge's theme.
+
+The component is rendered inside `<div className="flex-1 flex flex-col min-h-0 overflow-hidden">` — the outermost element should be a fragment or `<div className="flex-1 ...">`.
+
+**Do not** import React directly (it's auto-injected). Do not import any other npm package — only `@forge/craft`.
+
+## SDK — Server side (`server.ts`, optional)
+
+Skip this file entirely if the craft only needs to call existing Forge APIs.
+
+```ts
+import { defineCraftServer } from '@forge/craft/server';
+
+export default defineCraftServer({
+  routes: {
+    'GET /items': async ({ projectPath, query, forge }) => {
+      // Run shell in project cwd
+      const r = forge.exec('git log --oneline -20', { timeout: 10000 });
+      return { lines: r.stdout.split('\n').filter(Boolean) };
+    },
+
+    'POST /create': async ({ body, forge }) => {
+      forge.storage.write('records.json', body);
+      return { ok: true };
+    },
+
+    'GET /load-spec': async ({ forge }) => {
+      const spec = forge.openapi('docs/openapi.json');
+      return { paths: Object.keys(spec?.paths || {}) };
+    },
+
+    'POST /fix': async ({ body, forge }) => {
+      const t = forge.task({ prompt: body.prompt });
+      return { taskId: t.id };
+    },
+
+    'POST /run-cmd': async ({ body, forge }) => {
+      forge.inject(body.cmd);  // paste into bound terminal
+      return { ok: true };
+    },
+  },
+});
+```
+
+`forge` injected helper API:
+- `forge.project` — `{ path, name }`
+- `forge.storage` — `read(file)`, `write(file, data)`, `listFiles()` (scoped to the craft's data dir)
+- `forge.exec(cmd, opts?)` — synchronous shell exec in project cwd, returns `{ stdout, stderr, code }`
+- `forge.task({ prompt, agent? })` — spawn Forge background task, returns `{ id }`
+- `forge.inject(text, opts?)` — paste into bound tmux session
+- `forge.openapi(specPath)` — load + parse OpenAPI JSON from project
+- `forge.log(...)` — structured logging
+
+Routes are auto-mounted at `/api/crafts/<craft-name>/<route>`. The UI calls them via `useForgeFetch`.
+
+## Manifest (`craft.yaml`)
+
+```yaml
+name: api-dashboard           # kebab-case, dir name
+displayName: 📊 API Dashboard  # tab label (with emoji)
+description: One-line summary of what it does
+version: 0.1.0
+icon: "📊"                     # optional, mainly cosmetic
+author: aion0                 # optional, shown in marketplace
+tags:                         # optional — for marketplace browsing
+  - openapi
+  - dashboard
+  - migration
+requires:                     # optional — project-type compatibility gate.
+  hasFile:                    # craft is hidden + can't install if NONE match.
+    - docs/openapi.json
+    - openapi.yaml
+  hasGlob:
+    - "**/*.java"             # any of the matchers passing → compatible
+ui:
+  tab: ui.tsx
+  showWhen: hasFile("docs/openapi.json")  # optional extra UI condition
+server:
+  entry: server.ts             # omit this whole block if no server.ts
+```
+
+**Tags + requires guidance:**
+
+- `tags` are free-form keywords used by the marketplace search. Common ones:
+  language (`java`, `typescript`, `python`), framework (`spring`, `react`),
+  use-case (`migration`, `testing`, `linting`, `debugging`).
+- `requires.hasFile` lists files that MUST exist somewhere in the project for
+  the craft to make sense (any one match = compatible).
+- `requires.hasGlob` is for broader matches like `**/*.java` (project has Java)
+  or `package.json` (Node project).
+- Be specific — a craft tagged `java` + `requires.hasGlob: ["**/*.java"]` won't
+  show up in a TypeScript project's marketplace.
+
+## prompt.md
+
+Always write/update this file with:
+- The original user request (verbatim)
+- Each refine request and what you changed
+- Used by future Refine runs as context
+
+## Iteration
+
+When called to refine an existing craft (the dir already exists), READ existing files first, KEEP what works, change only what the user asked. Append the refine request to `prompt.md`.
+
+## Minimum viable example
+
+```yaml
+# craft.yaml
+name: hello
+displayName: 👋 Hello
+description: Demo craft — counts project files by extension
+version: 0.1.0
+ui:
+  tab: ui.tsx
+server:
+  entry: server.ts
+```
+
+```ts
+// server.ts
+import { defineCraftServer } from '@forge/craft/server';
+
+export default defineCraftServer({
+  routes: {
+    'GET /count': async ({ forge }) => {
+      const r = forge.exec(`git ls-files | awk -F. 'NF>1{print $NF}' | sort | uniq -c | sort -rn | head -20`);
+      return { lines: r.stdout.split('\n').filter(Boolean) };
+    },
+  },
+});
+```
+
+```tsx
+// ui.tsx
+import { useProject, useForgeFetch } from '@forge/craft';
+
+export default function Tab() {
+  const { projectName } = useProject();
+  const { data, loading } = useForgeFetch<{ lines: string[] }>('/api/crafts/hello/count');
+  return (
+    <div className="flex-1 p-4 text-xs overflow-auto">
+      <h2 className="font-semibold mb-2">{projectName} — file counts</h2>
+      {loading && <div className="text-[var(--text-secondary)]">Loading…</div>}
+      {data?.lines.map((l, i) => <div key={i} className="font-mono">{l}</div>)}
+    </div>
+  );
+}
+```
+
+## Style guide
+
+- Tailwind classes only. Use Forge's color variables, not hardcoded colors.
+- Text sizes: `text-xs` (default), `text-[11px]` for dense tables, `text-[10px]` for metadata.
+- Buttons: `text-[10px] px-2 py-1 rounded bg-[var(--accent)]/20 text-[var(--accent)] hover:bg-[var(--accent)]/30`.
+- Sections inside the tab: `flex-1 flex flex-col min-h-0 overflow-auto p-4 gap-3`.
+- For tables/lists, prefer simple `<table>` or `<div>` grids — no extra deps.
+- Match Forge's compact density (rows ~24-28px tall).
+
+## Final report
+
+After writing files, report:
+1. What craft you created (name + displayName)
+2. The route(s) registered (if any server)
+3. The data files used (if any)
+4. Any assumptions you made
+
+End with `[FORGE_DONE]`.

package/lib/help-docs/15-crafts.md

@@ -0,0 +1,127 @@
+# Crafts — project-scoped mini-apps
+
+A **Craft** is a tab inside Forge that lives at `<project>/.forge/crafts/<name>/`. It can be hand-written, AI-generated, or shipped as a Forge builtin (open-source samples). Crafts travel with the project — commit them to git so the team sees the same tabs.
+
+## Quick start
+
+In any project, click **+ Craft** next to the project tabs. Type what you want (e.g. "show all our REST endpoints with migration status, allow batch run + AI fix"). Forge spawns a background task that uses the `craft-builder` skill to generate the files. After ~30-60s the new tab appears.
+
+For an existing craft, switch to its tab and click the small **⚙** badge to refine it ("add a sort button" / "this column should be wider").
+
+## Anatomy
+
+```
+<project>/.forge/crafts/<name>/
+├── craft.yaml      # manifest (name, displayName, icon, conditions)
+├── ui.tsx          # React component (default export)
+├── server.ts       # optional API routes
+├── prompt.md       # original user request + iteration history
+├── README.md       # what this craft does
+└── data/           # craft's persistent JSON storage
+```
+
+## SDK
+
+Imports from `@forge/craft` (UI side):
+
+| Hook | What it does |
+|---|---|
+| `useProject()` | `{ projectPath, projectName }` |
+| `useForgeFetch(path)` | Fetch wrapper, auto-injects `?projectPath=...`, returns `{ data, loading, error, refetch }` |
+| `useInject()` | `(text) => Promise` — paste prompt + Enter into the project's bound tmux session |
+| `useTask()` | `(prompt) => TaskHandle` — spawn Forge background task, watch its log stream |
+| `useStore(file, default)` | `[value, save, { loading, reload }]` — JSON storage in `data/<file>.json` |
+| `useOpenAPI(path)` | Load + parse OpenAPI 3 spec from project |
+| `useFile(path, { watch? })` | Read project file with optional polling |
+| `useShell()` | `(cmd) => Promise<{ stdout, stderr, code }>` — exec in project cwd |
+| `useGit()` | Git status / log info |
+| `useToast()` | `(msg, kind)` — quick top notification |
+
+Server side (`server.ts`):
+
+```ts
+import { defineCraftServer } from '@forge/craft/server';
+
+export default defineCraftServer({
+  routes: {
+    'GET /items': async ({ forge, query, params }) => {
+      const r = forge.exec('git log --oneline -20');
+      return { lines: r.stdout.split('\n') };
+    },
+    'POST /run': async ({ body, forge }) => {
+      const t = forge.task({ prompt: body.prompt });
+      return { taskId: t.id };
+    },
+  },
+});
+```
+
+`forge` injected helpers:
+- `forge.project` — `{ path, name }`
+- `forge.storage` — `read(file)`, `write(file, data)`, `listFiles()` (scoped to craft data dir)
+- `forge.exec(cmd, opts?)` — sync shell exec in project cwd
+- `forge.task({ prompt })` — spawn background task
+- `forge.inject(text)` — paste into bound tmux session
+- `forge.openapi(specPath)` — load + parse OpenAPI JSON
+- `forge.log(...)` — structured logging
+
+Routes are mounted at `/api/crafts/<craft-name>/<route>`. The UI calls them via `useForgeFetch`.
+
+## Manifest
+
+```yaml
+name: api-dashboard           # kebab-case, dir name
+displayName: 📊 API Dashboard  # tab label
+description: One-line summary
+version: 0.1.0
+icon: "📊"
+ui:
+  tab: ui.tsx                 # default
+  showWhen: hasFile("docs/openapi.json")  # optional condition
+server:
+  entry: server.ts            # default; omit if no server
+```
+
+`showWhen` supports `hasFile("path")` (only show tab when file exists) or `always`.
+
+## Builtins
+
+`lib/builtin-crafts/<name>/` is the slot for crafts that ship with Forge by default. Currently empty — every craft is project-local at `<project>/.forge/crafts/<name>/`. Builtins (when present) appear automatically in every project; project-local crafts override builtins by name.
+
+## Marketplace
+
+Crafts can be published to a shared registry (default: `aiwatching/forge-crafts` on GitHub). The marketplace browser is reachable from the **Crafts ▾** dropdown in any project tab — pick **🛒 Marketplace** to see installable crafts filtered by your project's compatibility.
+
+### Browse + install
+- **Compatible / All / Installed** filter
+- Shows version, author, tags, and a per-item Install / Update / Uninstall button
+- Install copies the registry's files into `<project>/.forge/crafts/<name>/`; the new tab appears immediately
+
+### Project-type filtering (`requires`)
+
+Add a `requires` block to `craft.yaml` so the marketplace only suggests the craft to compatible projects:
+
+```yaml
+requires:
+  hasFile:                    # any of these files must exist
+    - docs/openapi.json
+  hasGlob:
+    - "**/*.java"             # any of these globs must match
+```
+
+Either matcher passing is enough (OR logic). With an empty/missing `requires`, the craft is compatible with every project.
+
+### Publish
+
+When a project-local craft is the active tab, the **📦** button next to ⚙ opens the publish modal. It shows:
+1. **How to publish** — step-by-step (open a PR on the registry repo).
+2. **registry.json entry** — JSON snippet to append under `crafts: [...]`.
+3. **Files** — copy each file's contents (`craft.yaml`, `ui.tsx`, `server.ts`, `README.md`) to drop into the registry repo's `<name>/` folder.
+
+Forge does NOT auto-push to GitHub. Submit the PR; once merged, all Forge users see it in their marketplace.
+
+The repo URL is configurable via `craftsRepoUrl` in `~/.forge/data/settings.yaml` so teams can run their own private registry.
+
+## Architectural model
+
+Forge is the **orchestrator**: discovers crafts, mounts UI tabs + API routes, provides the SDK. The craft is **your project's content** — stored in `<project>/.forge/`, not in Forge core. Generic features (Migration Cockpit will eventually move here) end up as crafts that live in your repo, not in Forge.

package/lib/help-docs/CLAUDE.md

@@ -44,6 +44,7 @@ The token is valid for 24 hours. Store it in a variable and reuse for all API ca
 | `11-workspace.md` | Workspace (Forge Smiths) — multi-agent orchestration, daemon, message bus, profiles |
 | `12-usage.md` | Token usage analytics — charts, heatmap, cost estimation, by model/project/source |
 | `13-ide-plugins.md` | VSCode extension + IntelliJ plugin — install, tabs, multi-connection, agent terminal launching |
+| `15-crafts.md` | Crafts — project-scoped mini-app tabs with SDK; AI-generated via "+ Craft" button |
 
 ## Matching questions to docs
 
@@ -67,3 +68,4 @@ The token is valid for 24 hours. Store it in a variable and reuse for all API ca
 - Sidebar collapse/project tabs/favorites → `07-projects.md`
 - VSCode/IntelliJ/IDE plugin/extension/marketplace → `13-ide-plugins.md`
 - vsce/vsix/JetBrains marketplace publish → `13-ide-plugins.md`
+- Craft/custom tab/mini-app/extend project/AI-generated tab/builder → `15-crafts.md`

package/lib/terminal-standalone.ts

@@ -209,6 +209,7 @@ function cleanupOrphanedSessions() {
   for (const s of sessions) {
     if (s.attached) continue;
     if (s.name.startsWith(`${SESSION_PREFIX}forge-`)) continue; // workspace agent session — managed by orchestrator
+    if (s.name.startsWith('mw-craft-')) continue;               // craft session — managed by craft loader
     if (knownSessions.has(s.name)) continue; // saved in terminal state — preserve
     const clients = sessionClients.get(s.name)?.size ?? 0;
     if (clients === 0) {

package/next.config.ts

@@ -10,7 +10,7 @@ const localIPs = Object.values(networkInterfaces())
   .map(i => i!.address);
 
 const nextConfig: NextConfig = {
-  serverExternalPackages: ['better-sqlite3'],
+  serverExternalPackages: ['better-sqlite3', 'esbuild'],
   allowedDevOrigins: localIPs,
   async rewrites() {
     return [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aion0/forge",
-  "version": "0.5.49",
+  "version": "0.5.50",
   "description": "Unified AI workflow platform — multi-model task orchestration, persistent sessions, web terminal, remote access",
   "type": "module",
   "scripts": {
@@ -41,6 +41,7 @@
     "@xyflow/react": "^12.10.1",
     "ai": "^6.0.116",
     "better-sqlite3": "^12.6.2",
+    "esbuild": "^0.27.3",
     "next": "^16.2.1",
     "next-auth": "5.0.0-beta.30",
     "node-pty": "1.0.0",

package/tsconfig.json

@@ -25,6 +25,12 @@
     "paths": {
       "@/*": [
         "./*"
+      ],
+      "@forge/craft": [
+        "./lib/craft-sdk/client.tsx"
+      ],
+      "@forge/craft/server": [
+        "./lib/craft-sdk/server.ts"
       ]
     }
   },