@tangle-network/starter-foundry 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tangle Network
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# starter-foundry
+
+Deterministic project scaffold engine for AI coding platforms. Routes a user prompt to the right project structure, composes files, and gives the AI agent a concrete build plan — all in under 10ms.
+
+```
+"Build a Next.js SaaS with Stripe billing and team management"
+  → nextjs-ts + capability:saas-teams + capability:tailwind + capability:layout-dashboard
+  → 14 files composed
+  → Build plan: create /settings/team, /dashboard, wire /api/team/invite, build TeamMemberList, InviteForm, Sidebar
+```
+
+## How it works
+
+```
+User prompt → planPrompt() → composeStarter() → scaffold + build plan → AI agent starts building
+              ~1ms            ~3ms               ~5ms
+```
+
+The hot path is fully deterministic — no LLM calls, no network. A keyword scorer routes prompts to families, a capability detector attaches specialization layers, and the compose engine writes template files to disk.
+
+## Registry
+
+| | Count | Examples |
+|---|---|---|
+| **Families** | 40 | nextjs-ts, react-vite-ts, agent-service-ts, forge-contracts, solana-program, python-api, go-api, sveltekit-ts |
+| **Capability layers** | 91 | See categories below |
+| **Slot layers** | 18 | database (sqlite/postgres/mongodb/convex), auth (clerk/better-auth/supabase), payments, sdk, queue |
+| **Partners** | 6 | Coinbase, Tangle, EigenLayer, Arbitrum, X Layer, Solana |
+| **Product archetypes** | 115+ | "Twitter clone" → fullstack-ts + realtime-ws + saas-teams |
+
+### Capability layers by category
+
+**Layout (rich UI — production-ready React components):**
+layout-dashboard (sidebar + KPIs + activity feed), layout-landing (hero + features + pricing), layout-chat (message list + streaming input + sidebar), layout-admin (TanStack data table + entity form), layout-auth (sign-in/sign-up pages), layout-settings (profile/billing/team tabs)
+
+**Crypto frontend UI:**
+crypto-swap-ui (DEX swap card + token selector + pool card), crypto-staking-ui (staking dashboard + validator card), crypto-bridge-ui (bridge card + tx history), crypto-portfolio-ui (portfolio overview + token rows), crypto-governance-ui (proposal cards + voting), crypto-launchpad-ui (sale card + vesting schedule)
+
+**AI/Agent UI:**
+ai-chat-sessions (ChatGPT-style session list + folders + header), ai-agent-orchestrator (multi-agent timeline + tool call traces), ai-rag-chat (source citations + knowledge base manager), ai-voice-chat (voice orb + transcript + call controls)
+
+**Agent frameworks:** agent-rag, agent-langgraph, agent-mastra, agent-multi-agent, agent-trading, agent-voice, agent-slack, agent-github, agent-browser, agent-code-review, agent-customer-support, agent-data-pipeline, agent-intel, agent-openclaw, agent-hermes, agent-ai-sdk
+
+**DeFi/Crypto config:** defi-lending, defi-dex, defi-perpetuals, defi-yield, defi-restaking, defi-bridge, solana-amm, solana-perps, solana-staking, solana-nft, solana-prediction, solana-launchpad, solana-keeper, move-amm, move-staking, move-nft, move-oracle, move-launchpad, fhe-private-token, fhe-private-voting, fhe-sealed-auction
+
+**EVM infra:** evm-account-abstraction, evm-chain-monitor, evm-deploy-foundry, evm-layerzero-oft, evm-protocol-api, evm-wallet-dashboard
+
+**Other:** marketplace, webrtc, shadcn, tailwind, chart-widget, json-render, saas-billing, saas-teams, realtime-ws, deploy-docker, deploy-github-actions, infra-k8s, infra-terraform, infra-pulumi, exchange-binance, exchange-coinbase, exchange-okx, gpu-modal, gpu-replicate, gpu-together, effect-ts, logging, webhook-processor, market-sim, icons, typography, tangle-custody, tangle-oracle, ai-chat-ui, ai-agent-dashboard, ai-fine-tuning, admin-crud
+
+### Variants
+
+Layout layers support **visual variants** — different design treatments of the same component structure. The compose engine picks a variant deterministically from the project name, so every scaffold looks distinct but the result is reproducible.
+
+| Layer | Variants |
+|---|---|
+| layout-landing | gradient-hero, minimal-clean, dark-product |
+| layout-dashboard | sidebar, topnav |
+
+## Programmatic API
+
+```typescript
+import { planPrompt, composeStarter, createContextPack } from 'starter-foundry'
+
+const plan = await planPrompt({
+  prompt: 'Build a RAG chatbot with vector search',
+  partner: null,
+})
+
+const result = await composeStarter({ spec: plan.spec, outDir: '/tmp/project' })
+const context = await createContextPack({ spec: plan.spec, outDir: '/tmp/project' })
+```
+
+## CLI
+
+```bash
+npm run build && node dist/cli.js <command>
+```
+
+| Command | Description |
+|---------|-------------|
+| `plan --prompt <text> [--partner <id>]` | Route a prompt to a family + capabilities |
+| `compose --spec <path> --out <dir>` | Compose a starter project |
+| `workspace-compose --spec <path> --out <dir>` | Compose a multi-project workspace |
+| `validate --spec <path>` | Run validation checks |
+| `context --spec <path>` | Generate a context pack with build plan |
+| `bench --spec <path> [--runs <n>]` | Benchmark compose + validate timing |
+| `prove --corpus <path> --out <dir>` | Run proof suite over a prompt corpus |
+| `catalog` | List all families and layers |
+
+## Routing
+
+Three layers, evaluated in order:
+
+1. **Product archetypes** — "Twitter clone" → fullstack-ts. 115+ known product patterns.
+2. **Keyword scoring** — Each family manifest declares tiered keywords. Highest match wins.
+3. **Fuzzy fallback** — Levenshtein distance ≤ 1 catches typos ("Ract" → "react").
+
+After family selection, **capability detection** scans the prompt against capability keywords and attaches matching layers.
+
+## Quality
+
+| Metric | Value |
+|--------|-------|
+| Route accuracy (training corpus, 60 scenarios) | 100% |
+| Route accuracy (held-out corpus, 43 scenarios) | 100% |
+| Route accuracy (IdeasAI corpus, 60 scenarios) | 100% |
+| Unit + integration tests | 343/343 |
+| Compose latency (warm) | ~5ms |
+
+## Install
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+Requires Node.js >= 20.
+
+## Adding families or capabilities
+
+1. Create `registry/families/{id}/manifest.json` or `registry/layers/capability/{id}/manifest.json`
+2. Add template files in `files/` subdirectory
+3. For rich UI layers: provide real `.tsx` components (not config stubs)
+4. For variants: add `variants/` subdirectory with alternative file sets + `"variants": [...]` in manifest
+5. Run `npm run sync:warm-list` to update the container warm cache
+6. Run `npm test` — the meta test enforces every capability has a coverage test
+
+## Integration
+
+starter-foundry powers the free-text scaffold path in blueprint-agent. When a user types a prompt, starter-foundry routes, composes, and provides the build plan.
+
+```typescript
+import { planPrompt, composeStarter } from 'starter-foundry'
+
+const plan = await planPrompt({ prompt: userMessage, partner })
+if (plan.kind === 'starter') {
+  const result = await composeStarter({ spec: plan.spec, outDir })
+}
+```

package/corpus/held-out-validation.json

@@ -0,0 +1,322 @@
+{
+  "name": "held-out-validation",
+  "scenarios": [
+    {
+      "id": "ho-rust-agent",
+      "complexity": "medium",
+      "partner": null,
+      "prompt": "Create a Rust AI agent using rig for autonomous blockchain monitoring.",
+      "expected": { "kind": "starter", "family": "agent-service-rust" }
+    },
+    {
+      "id": "ho-dspy-pipeline",
+      "complexity": "simple",
+      "partner": null,
+      "prompt": "Build an optimized text classification system using DSPy with automated prompt tuning.",
+      "expected": { "kind": "starter", "family": "dspy-pipeline-py" }
+    },
+    {
+      "id": "ho-mcp-server",
+      "complexity": "simple",
+      "partner": null,
+      "prompt": "Create an MCP server that exposes database tools for Claude.",
+      "expected": { "kind": "starter", "family": "mcp-server-ts" }
+    },
+    {
+      "id": "ho-stylus-contract",
+      "complexity": "medium",
+      "partner": null,
+      "prompt": "Deploy a liquidity pool contract using Arbitrum Stylus in Rust.",
+      "expected": { "kind": "starter", "family": "stylus-contracts" }
+    },
+    {
+      "id": "ho-x402-api",
+      "complexity": "medium",
+      "partner": null,
+      "prompt": "Build a pay-per-request API using the x402 protocol for monetized LLM inference.",
+      "expected": { "kind": "starter", "family": "x402-service" }
+    },
+    {
+      "id": "ho-zk-prover",
+      "complexity": "medium",
+      "partner": null,
+      "prompt": "Build a RISC Zero prover service that generates ZK proofs for on-chain verification.",
+      "expected": { "kind": "starter", "family": "zk-prover-service" }
+    },
+    {
+      "id": "ho-eigenlayer-avs",
+      "complexity": "medium",
+      "partner": null,
+      "prompt": "Create an EigenLayer AVS for decentralized oracle data feeds.",
+      "expected": { "kind": "starter", "family": "eigenlayer-avs" }
+    },
+    {
+      "id": "ho-chatbot-vague",
+      "complexity": "simple",
+      "partner": null,
+      "prompt": "I want to build a chatbot for my company.",
+      "expected": { "kind": "starter", "family": "agent-service-ts" }
+    },
+    {
+      "id": "ho-ai-assistant-generic",
+      "complexity": "simple",
+      "partner": null,
+      "prompt": "Build me an AI assistant that can answer questions about our product.",
+      "expected": { "kind": "starter", "family": "agent-service-ts" }
+    },
+    {
+      "id": "ho-saas-minimal",
+      "complexity": "simple",
+      "partner": null,
+      "prompt": "I need a SaaS app.",
+      "expected": { "kind": "starter", "family": "fullstack-ts" }
+    },
+    {
+      "id": "ho-crud-generic",
+      "complexity": "simple",
+      "partner": null,
+      "prompt": "Build a CRUD app for managing inventory.",
+      "expected": { "kind": "starter", "family": "fullstack-ts" }
+    },
+    {
+      "id": "ho-internal-tool",
+      "complexity": "simple",
+      "partner": null,
+      "prompt": "Build an internal tool for our ops team to manage customer accounts.",
+      "expected": { "kind": "starter", "family": "fullstack-ts" }
+    },
+    {
+      "id": "ho-slack-support-bot",
+      "complexity": "medium",
+      "partner": null,
+      "prompt": "Make a Slack bot that handles customer support tickets using AI.",
+      "expected": { "kind": "starter", "family": "agent-service-ts" }
+    },
+    {
+      "id": "ho-github-ci-agent",
+      "complexity": "medium",
+      "partner": null,
+      "prompt": "Build a GitHub bot that reviews code, labels issues, and posts comments on PRs.",
+      "expected": { "kind": "starter", "family": "agent-service-ts" }
+    },
+    {
+      "id": "ho-rag-docs",
+      "complexity": "medium",
+      "partner": null,
+      "prompt": "I need an AI that can search our documentation and answer developer questions.",
+      "expected": { "kind": "starter", "family": "agent-service-ts" }
+    },
+    {
+      "id": "ho-trading-bot-ambiguous",
+      "complexity": "medium",
+      "partner": null,
+      "prompt": "Build a trading bot.",
+      "expected": { "kind": "starter", "family": "worker-job" }
+    },
+    {
+      "id": "ho-trading-agent-explicit",
+      "complexity": "medium",
+      "partner": null,
+      "prompt": "Build an AI trading agent that analyzes market sentiment and executes paper trades.",
+      "expected": { "kind": "starter", "family": "agent-service-ts" }
+    },
+    {
+      "id": "ho-python-crewai",
+      "complexity": "medium",
+      "partner": null,
+      "prompt": "Build a CrewAI multi-agent system in Python for content research and writing.",
+      "expected": { "kind": "starter", "family": "agent-service-py" }
+    },
+    {
+      "id": "ho-nextjs-dashboard-coinbase",
+      "complexity": "medium",
+      "partner": "coinbase",
+      "prompt": "Build a portfolio tracker dashboard with Next.js showing crypto balances and charts.",
+      "expected": { "kind": "starter", "family": "nextjs-ts" }
+    },
+    {
+      "id": "ho-react-simple",
+      "complexity": "simple",
+      "partner": null,
+      "prompt": "Build a simple React app with Vite.",
+      "expected": { "kind": "starter", "family": "react-vite-ts" }
+    },
+    {
+      "id": "ho-go-api-postgres",
+      "complexity": "medium",
+      "partner": null,
+      "prompt": "Create a Go REST API with Postgres for a task management backend.",
+      "expected": { "kind": "starter", "family": "go-api", "slots": { "database": "database:postgres" } }
+    },
+    {
+      "id": "ho-python-fastapi",
+      "complexity": "simple",
+      "partner": null,
+      "prompt": "Build a FastAPI backend for user authentication and file uploads.",
+      "expected": { "kind": "starter", "family": "python-api" }
+    },
+    {
+      "id": "ho-browser-extension-ai",
+      "complexity": "medium",
+      "partner": null,
+      "prompt": "Create a Chrome extension that summarizes web pages using AI.",
+      "expected": { "kind": "starter", "family": "browser-extension-ts" }
+    },
+    {
+      "id": "ho-mobile-wallet",
+      "complexity": "medium",
+      "partner": "coinbase",
+      "prompt": "Build a mobile wallet app with Expo for tracking NFT collections.",
+      "expected": { "kind": "starter", "family": "expo-react-native-ts" }
+    },
+    {
+      "id": "ho-electron-app",
+      "complexity": "simple",
+      "partner": null,
+      "prompt": "Build a desktop note-taking app with Electron.",
+      "expected": { "kind": "starter", "family": "electron-desktop-ts" }
+    },
+    {
+      "id": "ho-tauri-tool",
+      "complexity": "simple",
+      "partner": null,
+      "prompt": "Build a Tauri app for local file encryption and decryption.",
+      "expected": { "kind": "starter", "family": "tauri-desktop" }
+    },
+    {
+      "id": "ho-cli-deploy",
+      "complexity": "simple",
+      "partner": null,
+      "prompt": "Build a CLI tool for deploying Docker containers to multiple servers.",
+      "expected": { "kind": "starter", "family": "cli-ts" }
+    },
+    {
+      "id": "ho-cloudflare-edge",
+      "complexity": "simple",
+      "partner": null,
+      "prompt": "Build a Cloudflare Worker that proxies API requests with rate limiting.",
+      "expected": { "kind": "starter", "family": "cloudflare-worker-ts" }
+    },
+    {
+      "id": "ho-solana-nft",
+      "complexity": "medium",
+      "partner": "solana",
+      "prompt": "Build a Solana NFT marketplace with compressed NFTs and royalty enforcement.",
+      "expected": { "kind": "starter", "family": "solana-program" }
+    },
+    {
+      "id": "ho-forge-erc721",
+      "complexity": "medium",
+      "partner": null,
+      "prompt": "Create an ERC721 NFT collection with Foundry and deploy scripts.",
+      "expected": { "kind": "starter", "family": "forge-contracts" }
+    },
+    {
+      "id": "ho-hardhat-explicit",
+      "complexity": "medium",
+      "partner": "xlayer",
+      "prompt": "Set up a Hardhat project with TypeScript for X Layer contract development.",
+      "expected": { "kind": "starter", "family": "hardhat-contracts" }
+    },
+    {
+      "id": "ho-move-aptos",
+      "complexity": "simple",
+      "partner": null,
+      "prompt": "Write an Aptos Move module for a token vesting contract.",
+      "expected": { "kind": "starter", "family": "move-contracts" }
+    },
+    {
+      "id": "ho-workspace-saas-agent",
+      "complexity": "complex",
+      "partner": null,
+      "prompt": "Build a SaaS helpdesk with a Next.js frontend for ticket management and an AI support bot backend that searches the knowledge base.",
+      "expected": {
+        "kind": "workspace",
+        "primaryProjectId": "web",
+        "projectFamilies": { "web": "nextjs-ts" }
+      }
+    },
+    {
+      "id": "ho-workspace-ecommerce",
+      "complexity": "complex",
+      "partner": "coinbase",
+      "prompt": "Build an e-commerce platform with a React storefront, a Node.js order API with Stripe billing, and Foundry smart contracts for loyalty tokens.",
+      "expected": {
+        "kind": "workspace",
+        "primaryProjectId": "web",
+        "projectFamilies": { "web": "react-vite-ts", "evm": "forge-contracts" }
+      }
+    },
+    {
+      "id": "ho-workspace-data-platform",
+      "complexity": "complex",
+      "partner": null,
+      "prompt": "Build a data platform with a React dashboard for visualizations and a Python API for data processing and report generation.",
+      "expected": {
+        "kind": "workspace",
+        "primaryProjectId": "web",
+        "projectFamilies": { "web": "react-vite-ts", "api": "python-api" }
+      }
+    },
+    {
+      "id": "ho-workspace-go-react",
+      "complexity": "complex",
+      "partner": null,
+      "prompt": "Build a monitoring dashboard with a React frontend and a Go backend for metrics aggregation.",
+      "expected": {
+        "kind": "workspace",
+        "primaryProjectId": "web",
+        "projectFamilies": { "web": "react-vite-ts", "api": "go-api" }
+      }
+    },
+    {
+      "id": "ho-ambiguous-website",
+      "complexity": "simple",
+      "partner": null,
+      "prompt": "Build me a website.",
+      "expected": { "kind": "starter", "family": "frontend-static" }
+    },
+    {
+      "id": "ho-ambiguous-api",
+      "complexity": "simple",
+      "partner": null,
+      "prompt": "Build me an API.",
+      "expected": { "kind": "starter", "family": "api-service" }
+    },
+    {
+      "id": "ho-ambiguous-app",
+      "complexity": "simple",
+      "partner": null,
+      "prompt": "Build me an app.",
+      "expected": { "kind": "starter", "family": "fullstack-ts" }
+    },
+    {
+      "id": "ho-tangle-blueprint",
+      "complexity": "medium",
+      "partner": "tangle",
+      "prompt": "Build a Tangle Blueprint for decentralized storage with FROST threshold signing.",
+      "expected": { "kind": "starter", "family": "tangle-blueprint" }
+    },
+    {
+      "id": "ho-rust-backend",
+      "complexity": "simple",
+      "partner": null,
+      "prompt": "Build a Rust HTTP backend with Axum for a high-throughput API.",
+      "expected": { "kind": "starter", "family": "rust-service" }
+    },
+    {
+      "id": "ho-playwright-scraper",
+      "complexity": "simple",
+      "partner": null,
+      "prompt": "Build a web scraper with Playwright that monitors competitor pricing.",
+      "expected": { "kind": "starter", "family": "playwright-worker" }
+    },
+    {
+      "id": "ho-streamlit-data",
+      "complexity": "simple",
+      "partner": null,
+      "prompt": "Build a Streamlit dashboard for analyzing CSV sales data.",
+      "expected": { "kind": "starter", "family": "python-data-app" }
+    }
+  ]
+}