diff --git a/.gitignore b/.gitignore index d4a1c53..13d3f48 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,6 @@ node_modules/ dist/ *.js.map -# Research archive β€” lives at ../knowledgebase/ outside this repo. +# Research archive - lives at ../knowledgebase/ outside this repo. # Ignored here as a safety net in case it gets re-introduced by mistake. knowledgebase/ diff --git a/README.md b/README.md index 1f69957..f134b50 100755 --- a/README.md +++ b/README.md @@ -1,80 +1,132 @@
-# hyperstack +![Hyperstack Banner](assets/banner.jpeg) -**A disciplined MCP server and AI skill system that forces your agent to use real docs, real designs, and real verification before shipping.** +**A disciplined engineering harness that forces AI agents to use ground-truth docs, precise designs, and programmatic verification.**

MIT TypeScript - MCP - Node Docker + MCP

- Plugins + Plugins Skills Hook

-

- React Flow - Motion - Lenis - Tailwind - shadcn - Echo - Rust -

-
--- -## ⚑ What is this? +## πŸš€ What is Hyperstack? + +**Hyperstack is a disciplined engineering harness for AI coding agents.** + +It provides the necessary **Ground Truth** (via 79 specialized MCP tools) and **Adversarial Enforcement** (via 21 rigorous skills) to transform a generic LLM into a high-precision Senior Engineer. + +Unlike standard "polite" instructions, Hyperstack uses **Iron Laws** and a **SessionStart hook** to force agents to check real documentation, follow precise design specs, and provide binary verification before shipping. + +## πŸš€ Installation + +### 1. Recommended: Agentic (autopilot) + +The fastest way to install Hyperstack is to let your AI agent do it for you. This works with **Cursor, Windsurf, Roo Code, Claude Code, or Gemini**. Simply paste this command: + +> **Fetch and follow the instructions at https://raw.githubusercontent.com/orkait/hyperstack/main/install.md** + +The autopilot will autonomously detect your environment, install the MCP server (Docker or Local), and **automatically link the Skills repository**. This is the only step required. + +--- + +### 2. Manual Configuration (Advanced) -Hyperstack is a coding-agent harness made of three tightly-coupled layers: +If you aren't using the Autopilot, follow the **Unified Bootstrap** to set up both the MCP server and the Skills: -1. **An internal harness** that bootstraps the agent, enforces global invariants, and routes internal roles like `hyper` and `website-builder`. -2. **A TypeScript MCP server** with 11 plugins and 79 tools. Your AI calls these for ground-truth API signatures, component specs, design decisions, and architectural patterns. No hallucinated imports. -3. **A skill system with enforcement teeth.** 21 skills with Iron Laws, rationalization tables, and a SessionStart hook that force-injects discipline on every session. Your AI cannot "just try one thing" without the gate firing. +1. **Clone & Initialize**: + ```bash + git clone https://github.com/orkait/hyperstack.git ~/.hyperstack + cd ~/.hyperstack && bun install + ``` -The combination turns a generic coding assistant into a disciplined agent system that: +2. **Run the Setup Script**: + ```bash + bun scripts/setup.ts + ``` -- checks docs before writing code -- writes a DESIGN.md before visual work -- routes website-heavy work to a specialist role -- refuses to claim completion without verification evidence +3. **Follow the CLI**: The script auto-detects your IDE, generates the JSON patch, and outputs the symlink command for your skill directory. -**You should use this if** you are tired of AI agents inventing API shapes, shipping AI-slop UIs, or claiming "tests pass" without running them. +**Supported platforms** (verified April 2026, from official docs): -**Skip this if** you want a frictionless autocomplete. Hyperstack is the opposite of frictionless - it is intentional friction that catches bugs before they ship. +| IDE / CLI | MCP Config Path | Skill Path | Schema | +|---|---|---|---| +| **Claude Code** | `~/.claude.json` | `~/.claude/skills/hyperstack` | JSON `mcpServers` | +| **Gemini CLI** | `~/.gemini/settings.json` | - | JSON `mcpServers` | +| **Qwen Code** | `~/.qwen/settings.json` | `~/.qwen/skills/hyperstack` | JSON `mcpServers` | +| **Codex CLI** | `~/.codex/config.toml` | - | TOML `mcp_servers` | +| **Cursor** | `~/.cursor/mcp.json` | `.cursor/rules/` (project) | JSON `mcpServers` | +| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | - | JSON `mcpServers` | +| **Kiro** | `~/.kiro/settings/mcp.json` | - | JSON `mcpServers` | +| **Zed** | `~/.config/zed/settings.json` | - | JSON `context_servers` | +| **VS Code + Copilot** | `~/.config/Code/User/mcp.json` | `.vscode/` (project) | JSON `mcpServers` | +| **Roo Code** | `.roo/mcp.json` (project) | `.roo/rules/` (project) | JSON `mcpServers` | +| **Cline** | `~/.config/Code/User/globalStorage/.../cline_mcp_settings.json` | - | JSON `mcpServers` | +| **Continue.dev** | `.continue/mcpServers/mcp.json` (project) | - | JSON `mcpServers` | -## πŸ€– Agent View +> [!TIP] +> Run `bun scripts/setup.ts` and it will auto-detect your platform and output the exact patch - in the right format for your IDE. Codex users get TOML, everyone else gets JSON. -If you are an agent reading this README, the shortest correct mental model is: +## ⚑ The Manifesto -- Hyperstack is not just an MCP server -- Hyperstack is not just a skills pack -- Hyperstack is a harness that combines internal role routing, MCP grounding, and workflow gates +It is not just a library; it is a **disciplined harness** made of three tightly-coupled layers: -Current internal role model: +1. **The Harness**: Bootstraps the agent, routes internal specialist roles (`hyper`, `website-builder`), and enforces global development invariants. +2. **The MCP Ground Truth**: 12 TypeScript plugins (80 tools) that provide deterministic data. No hallucinated imports or invented component specs. +3. **The Adversarial Gates**: 21 skills with **"Enforcement Teeth"**. These aren't suggestions; they are Iron Laws supported by rationalization tables that counter every excuse an agent uses to skip quality gates. -- `hyper` - conductor, gatekeeper, verifier, delivery owner -- `website-builder` - specialist for website-facing design and implementation work +> [!IMPORTANT] +> **Use Hyperstack if** you want to force your agent to check docs, write designs first, and prove its work. +> **Skip Hyperstack if** you want frictionless autocomplete. We prioritize intentional friction that catches bugs before they ship. -Public surface: +## πŸ—οΈ Architecture + +```mermaid +graph TD + User([User Request]) --> Harness[Internal Harness] + Harness --> Gates{Adversarial Gates} + + subgraph "The Enforcement Layer" + Gates -->|Iron Laws| Skills[21 Skills with Enforcement Teeth] + Skills -->|SessionStart| Injection[Auto-Context Injection] + end + + subgraph "The Knowledge Layer" + Skills -->|Ground Truth| MCP[12 MCP Plugins / 80 Tools] + MCP -->|Designer| Design[DESIGN.md Pipeline] + MCP -->|Verified| Code[Programmatic Compliance Check] + end + + Code -->|Verification Evidence| User + + linkStyle 0 stroke:#9ca3af,stroke-width:2px + linkStyle 1 stroke:#9ca3af,stroke-width:2px + linkStyle 2 stroke:#9ca3af,stroke-width:2px + linkStyle 3 stroke:#9ca3af,stroke-width:2px + linkStyle 4 stroke:#9ca3af,stroke-width:2px + linkStyle 5 stroke:#9ca3af,stroke-width:2px + linkStyle 6 stroke:#9ca3af,stroke-width:2px + linkStyle 7 stroke:#9ca3af,stroke-width:2px +``` -- MCP plugins for deterministic knowledge -- skills for process enforcement -- SessionStart hook for bootstrap context injection +## πŸ€– Agent Model -Internal surface: +If you are an agent reading this, your mental model must be: **Process is Priority.** You are operating within a system that requires deterministic grounding and formal design before implementation. -- role contracts in `agents/` -- orchestration contracts in `harness/` -- generated runtime bootstrap artifacts in `generated/runtime-context/` +- **Conductance**: `hyper` owners classification and gate verification. +- **Specialization**: `website-builder` handles visual and frontend implementation. +- **Persistence**: You run in a stable Docker container with a persistent lifecycle. --- @@ -117,11 +169,13 @@ docker run -d --name hyperstack-mcp --restart unless-stopped \ If you are using Claude Code, Cursor, Windsurf, Roo Code, or Gemini, you can use the autopilot to self-configure. Paste this at your agent: -> Fetch and follow the instructions at https://raw.githubusercontent.com/orkait/hyperstack/main/install.md - +```text +Fetch and follow the instructions at https://raw.githubusercontent.com/orkait/hyperstack/main/install.md +``` The autopilot will detect your environment and propose the correct Docker-based configuration block. + ### πŸ”§ Install the skills The MCP server gives you tools. The skills give you discipline. Install both: @@ -148,36 +202,37 @@ Node 18+ required. --- -## 🧠 The two-layer system +## 🧠 The Two-Layer System + +Hyperstack's strength comes from the friction between **Ground Truth** (MCP) and **Enforcement** (Skills). -The public product still has two user-facing layers, but they now sit inside an -internal harness. +### Layer 1: MCP Plugins (Ground Truth) -### Layer 1: MCP Plugins (deterministic knowledge) +Your AI calls these for deterministic data. Memory is not acceptable. Every plugin serves curated TypeScript data and architectural patterns. -Your AI calls these for exact API data. Memory is not acceptable. Every plugin serves typed TypeScript data + `.txt` snippets bundled with the plugin. +| Category | Plugins | Domain Coverage | +|---|---|---| +| πŸ› οΈ **System** | `hyperstack` | Autonomous Environment Detection, MCP Configuration Patching, Lifecycle | +| 🎨 **UI Engine** | `designer`, `design-tokens`, `ui-ux`, `shadcn` | Design Systems, OKLCH, Typography, Accessibility, Component Specs | +| βš›οΈ **Frontend** | `react`, `reactflow`, `motion`, `lenis` | Next.js 15, RSC, Animation Curves, Smooth Scroll, DAG Layouts | +| 🐹 **Backend** | `echo`, `golang`, `rust` | Professional Go Recipes, Rust Borrow Checker patterns, Clean Architecture | -| Plugin | Tools | Domain | -|---|:---:|---| -| 🎨 **designer** | 19 | Design decision engine - 6 personality clusters, 15 industry rules, 11 cognitive laws, 13 page templates, 9 presets (Linear, Stripe, Vercel, Apple, Carbon, shadcn, Notion, Supabase, Figma), 21 font pairings, DESIGN.md pipeline | -| ✨ **design-tokens** | 7 | Tailwind v4 + OKLCH token systems, 10 categories, 8 build procedures | -| πŸ’… **ui-ux** | 6 | Typography scales, spacing grids, accessibility checklists, component patterns | -| 🧩 **shadcn** | 5 | shadcn/ui Base UI edition - rules, components, compositions, snippets | -| βš›οΈ **reactflow** | 9 | @xyflow/react v12 - 56 APIs, 17 patterns, templates, migration guides | -| 🎬 **motion** | 7 | Motion for React v12 - 33 APIs, transition reference, animation generators | -| 🌊 **lenis** | 6 | Smooth scroll - 7 recipes, GSAP integration, React hooks | -| βš›οΈ **react** | 4 | React 19 + Next.js - RSC patterns, Zustand hierarchy, data fetching rules | -| 🐹 **echo** | 6 | Echo Go framework - 19 recipes, 13 middleware, decision matrices | -| 🐹 **golang** | 6 | Go - 18 practices, 10 design patterns, anti-patterns | -| πŸ¦€ **rust** | 4 | Rust - 18 practices, ownership guide, performance tips | +> [!TIP] +> **80 Tools Total**. Every tool is designed to provide the "Senior Engineer" answer, bypassing the "AI Slop" default. -**79 tools total.** +### Layer 2: Skills (Enforcement Teeth) -### Layer 2: Skills (process enforcement) +Markdown with adversarial enforcement. Each skill contains an **Iron Law** that the agent is bound to follow. -Markdown with adversarial enforcement. Each gate skill has an Iron Law, a 1% Rule, and a rationalization table that names the exact excuses your AI will use to skip the gate and counters each one. +> [!CAUTION] +> ### βš–οΈ The Iron Laws of Hyperstack +> - **NO CODE** without MCP grounding. +> - **NO VISUAL CODE** without an approved `DESIGN.md`. +> - **NO COMPLETION CLAIMS** without programmatic verification evidence. +> - **NO REFACTOR** without a failing test first. +> - **NO PATTERN** without a named Force. -The `using-hyperstack` skill is injected into every session by `hooks/session-start.mjs`. You do not have to invoke it manually. +These laws are backed by **Rationalization Tables**-pre-written counters to every excuse an AI agent uses to skip quality gates. ### Internal Harness (role routing + bootstrap) @@ -237,47 +292,35 @@ Full index at `skills/INDEX.md`. Regenerate with `bash scripts/generate-skills-i --- -## πŸ”’ Why adversarial enforcement? +## πŸ”’ Adversarial Enforcement -Ordinary skill markdown is polite suggestion. Polite suggestion fails when the model is under pressure to "be helpful fast." Hyperstack gate skills are written adversarially, inspired by [obra/superpowers](https://github.com/obra/superpowers): +Ordinary skill markdown is a polite suggestion. Polite suggestion fails when an AI model is under pressure to "be helpful fast." Hyperstack skills are written adversarially: -- **Iron Laws** in all-caps that spell out the non-negotiable rule -- **1% Rule** - if there is even a 1% chance a skill applies, invoke it -- **Rationalization tables** listing the exact excuses your AI will use to skip the gate, with counters -- **"Spirit of the rule is the letter of the rule"** clause to close loophole-hunting -- **SessionStart hook** that injects `using-hyperstack` into every new session so the AI cannot forget the system exists +- **1% Rule**: If there is even a 1% chance a skill applies, the agent **must** invoke it. +- **Rationalization Tables**: We have already written down every excuse your AI will use to skip a gate, with a firm technical counter for each. +- **Loophole Closure**: The "Spirit of the Law" is explicitly defined as the "Letter of the Law" to prevent shortcut-hunting. -Examples of Iron Laws enforced today: - -``` -NO CODE WITHOUT MCP GROUND-TRUTH DATA -NO VISUAL CODE WITHOUT AN APPROVED DESIGN.md -NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE -NO REFACTOR WITHOUT A FAILING TEST FIRST -NO PATTERN WITHOUT A NAMED FORCE -``` --- -## 🎨 The designer workflow (flagship example) +## 🎨 The designer agent -The designer plugin + skill is the clearest illustration of how hyperstack composes all three layers. +When you say, **β€œbuild me a SaaS dashboard”**: -When you say *"build me a SaaS dashboard"*: +1. **SessionStart** already puts in `using-hyperstack`, so AI know system is there. +2. **Blueprint skill** sees visual job and sends it to `hyperstack:designer`. +3. **Designer skill** runs `designer_resolve_intent(product)` to guess industry, personality, style, density, and mode. +4. Designer asks **3 questions** in base mode, or **12 questions** in advanced mode. +5. Like **Q11b** will ask what component library to use: shadcn, raw Tailwind, MUI, Mantine, Chakra, Ant Design, or custom. +6. Designer makes a **DESIGN.md** contract with 10 parts: theme, colors, type, spacing, components, motion, elevation, do/don’ts, responsive rules, and anti-patterns. +7. User approves the **DESIGN.md**. +8. **Forge-plan** reads it and makes one task for each section. If user picked shadcn, it calls `shadcn_get_component`. If not, it builds from the DESIGN.md spec. +9. Build tasks run with MCP tools as ground truth. +10. **designer_verify_implementation** checks build against **DESIGN.md**. +11. **Ship-gate** blocks final completion unless build passes the **DESIGN.md** rules. -1. **SessionStart hook** has already injected `using-hyperstack` - the AI knows the system exists -2. **Blueprint skill** detects visual work and routes to `hyperstack:designer` -3. **Designer skill** calls `designer_resolve_intent(product)` to auto-detect industry, personality, style, density, mode -4. **Designer asks 3 questions** (base mode) or 12 questions (advanced mode) -5. **Q11b** asks which component library - shadcn, raw Tailwind, MUI, Mantine, Chakra, Ant Design, or custom -6. **Designer produces a DESIGN.md contract** with 10 sections (theme, colors, typography, spacing, components, motion, elevation, do/don'ts, responsive, anti-patterns) -7. **User approves** the DESIGN.md -8. **Forge-plan skill** reads the DESIGN.md and generates one task per section. For Section 5 (components), it calls `shadcn_get_component` for each component (only if Q11b chose shadcn - otherwise hand-builds from DESIGN.md spec) -9. **Implementation tasks** execute with the ground truth from MCP tools -10. **designer_verify_implementation** runs a programmatic compliance check against DESIGN.md before ship-gate -11. **Ship-gate** enforces the DESIGN.md compliance table (10 sections x specific rules) before allowing any completion claim +AI cannot jump ahead. Every step has hard gate. Excuses already blocked by rationalization tables. -At every step, the AI cannot skip ahead. The hard gates are enforced by rationalization tables that have already written down every excuse your AI will try. --- @@ -415,85 +458,22 @@ Only invoked when the user explicitly chose shadcn in designer Q11b. --- -## πŸ—οΈ Architecture - -Everything runs from source. The published `hyperstack` bin is a small Node wrapper that boots `src/index.ts` through `tsx`, and Docker uses the same source-first runtime. No `dist/` output, no build step for deployment - just type checking. - -```text -bin/ -└── hyperstack.mjs # Published CLI wrapper - boots src/index.ts via tsx - -src/ -β”œβ”€β”€ index.ts # Entry - creates McpServer, loads all 11 plugins -β”œβ”€β”€ registry.ts # Plugin interface + loadPlugins() -β”œβ”€β”€ shared/ -β”‚ └── loader-factory.ts # createSnippetLoader() reads .txt at module init -└── plugins/ - β”œβ”€β”€ designer/ # 19 tools, data.ts with distilled research - β”œβ”€β”€ shadcn/ # 5 tools, bundled component catalog - β”œβ”€β”€ design-tokens/ # 7 tools - β”œβ”€β”€ ui-ux/ # 6 tools - β”œβ”€β”€ reactflow/ # 9 tools - β”œβ”€β”€ motion/ # 7 tools - β”œβ”€β”€ lenis/ # 6 tools - β”œβ”€β”€ react/ # 4 tools - β”œβ”€β”€ echo/ # 6 tools - β”œβ”€β”€ golang/ # 6 tools - └── rust/ # 4 tools - -skills/ -β”œβ”€β”€ INDEX.md # Auto-generated from frontmatter category field -β”œβ”€β”€ using-hyperstack/ # Force-injected by SessionStart hook -β”œβ”€β”€ (20 other skills)/ - -hooks/ -β”œβ”€β”€ hooks.json # Registers the SessionStart hook -β”œβ”€β”€ session-start.mjs # Cross-platform hook entrypoint for auto-injecting using-hyperstack -β”œβ”€β”€ session-start # Legacy shell helper -└── run-hook.cmd # Windows dispatcher - -scripts/ -└── generate-skills-index.sh # Regenerates skills/INDEX.md from frontmatter -``` - -Each plugin follows the same structure: `index.ts` registers tools from `tools/`, data lives in `data.ts`, code snippets live in `snippets/*.txt` and are loaded at module init time via `loader.ts`. - ---- - -## 🚧 Boundaries and current status - -- **Platform:** Claude Code, Cursor, Gemini CLI, Copilot CLI, OpenCode, Codex, and any MCP-compatible client. Tested primarily on Claude Code. -- **Node:** 18 or newer. -- **No build step:** runs via `tsx`. Do not add a `dist/` folder. -- **Knowledgebase:** The original 25 research files that seeded the designer plugin are NOT in this repo anymore. They live at `../knowledgebase/` outside the repo, gitignored for safety. All actionable content is distilled into `src/plugins/designer/data.ts`. -- **shadcn plugin:** Ships with 4 curated components (Button, Dialog, Field, Select) as reference. For a full catalog, you still need your project's own shadcn files. -- **Enforcement vs suggestion:** Hyperstack skills are markdown-based prose gates. They depend on the AI reading them. The SessionStart hook makes this harder to skip, but it is not a hard runtime block. True enforcement would require tool-level hooks. -- **Branch Protection:** The `main` branch is protected by a strict ruleset. Direct pushes are blocked, and all changes must go through a Pull Request that passes 100% of the CI verification suite. -- **Testing skills:** `testing-skills` defines a RED-GREEN-REFACTOR methodology for pressure-testing skills with subagents. Scenario files exist for 3 skills (ship-gate, designer, blueprint). Other gate skills need their own scenarios. - ---- - ## 🀝 Contributing -Fork, branch, open a PR. All new plugins must follow the existing file structure (`index.ts` + `data.ts` + `tools/` + `snippets/`). All new skills must include a `category:` frontmatter field (core, domain, or meta) so they appear in `skills/INDEX.md`. +We welcome contributions that follow the **Disciplined Engineering** standard. -After adding or editing any skill: +1. **Plugins**: Must follow the `index.ts` + `data.ts` + `tools/` + `snippets/` pattern. +2. **Skills**: Must include `category` frontmatter and adhere to the Adversarial Enforcement style. +3. **Verification**: All PRs must pass the full `npm run build` (Type-check) and CI suite. ```bash +# Regenerate the skills index after editing bash scripts/generate-skills-index.sh ``` -Run type checking before opening a PR: - -```bash -npm run build # tsc --noEmit -``` - ---- - ## πŸ“„ License -MIT Β© [Orkait](https://github.com/orkait) +MIT Β© [Orkait](https://github.com/orkait) | Adversarial philosophy inspired by [Jesse Vincent's Superpowers](https://github.com/obra/superpowers). --- diff --git a/assets/banner.jpeg b/assets/banner.jpeg new file mode 100644 index 0000000..e1bc606 Binary files /dev/null and b/assets/banner.jpeg differ diff --git a/docs/AGENTS.md b/docs/AGENTS.md new file mode 100644 index 0000000..439eb06 --- /dev/null +++ b/docs/AGENTS.md @@ -0,0 +1,73 @@ +# final steering doc + +## 1. core law + +* facts first. +* no bluff. +* no fake results. +* no puppy talk. +* less talk. more work. +* evidence beats guess. +* fast isolated test beats hypothesis. +* suggestion is not truth. treat research hits as maybe true until verified. +* if unsure, say so. +* if change gives no gain, stop, alert user, suggest better path. + +## 2. role + +* role: autonomous operations agent +* default mode: act, verify, report +* use tools and direct evidence before making claims +* treat local steering files as binding input when present + +## 3. source priority + +use this order: + +1. explicit user instruction in current task +2. system and platform hard limits +3. local steering docs and skill docs +4. repository code and config +5. tests, command output, logs, api responses +6. docs and research notes +7. prior belief or intuition + +rules: + +* do not impose beliefs as facts. +* do not claim cause and effect without proof. +* do not present hypothesis as result. +* one verified fact beats ten plausible guesses. + +## 4. local steering files + +load and obey when present: + +* `~/.claude/CLAUDE.md` +* `./skills/using-hyperstack/SKILL.md` +* any task-specific skill doc the user points to +* repo-local agent or steering docs + +rules: + +* if user says `recall memory`, also read `~/.claude/CLAUDE.md`. +* if using codemode or exploring codebase, follow codemode fully. no shortcuts. +* read files before semantic linking. no context = no real linking. + +## 5. tool-first execution + +always prefer tools over guess. + +## 6. deployment & project context + +| key | value | +|---|---| +| pages project | `nitrogen-orkait` | +| production url | `nitrogen-orkait.pages.dev` | +| mcp server | user scope in `~/.claude.json` | +| wrangler | auth via oauth, use `npx wrangler` | + +```bash +# deployment command +wrangler pages deploy --project-name nitrogen-orkait --branch main +``` diff --git a/install.md b/install.md index 1e2073d..1a14c9c 100644 --- a/install.md +++ b/install.md @@ -18,7 +18,7 @@ If you only remember four things, remember these: Three tightly-coupled pieces, installed together: 1. **An internal harness** - bootstrap, internal role routing, and workflow control. Current internal roles include `main` and `website-builder`. -2. **An MCP server** with 11 plugins and 79 tools - deterministic knowledge for React Flow v12, Motion v12, Lenis, React 19 / Next.js, Echo, Go, Rust, design tokens, UI/UX principles, shadcn/ui (Base UI edition), and the `designer` DESIGN.md pipeline. +2. **An MCP server** with 12 plugins and 80 tools - deterministic knowledge for React Flow v12, Motion v12, Lenis, React 19 / Next.js, Echo, Go, Rust, design tokens, UI/UX principles, shadcn/ui (Base UI edition), and the `designer` DESIGN.md pipeline. 3. **A skill system** with 21 skills including adversarial enforcement gates (`blueprint`, `designer`, `forge-plan`, `ship-gate`, `engineering-discipline`) and a SessionStart hook that force-injects the `using-hyperstack` skill at every session start. The install steps below wire the public pieces the user actually needs: the MCP @@ -53,7 +53,9 @@ If Docker is not available, you can explicitly request the local method: `hypers ## Step 2: Install the Skills -Clone the repository to a stable location on your system. +The skills contain the adversarial enforcement gates. You must clone them to a stable central location and then link them to the specific IDE/CLI rule directory. + +### 1. Central Repository **macOS / Linux (Shell):** ```bash @@ -67,6 +69,19 @@ $EXT_DIR = Join-Path $HOME ".hyperstack" if (Test-Path $EXT_DIR) { git -C $EXT_DIR pull } else { git clone https://github.com/orkait/hyperstack.git $EXT_DIR } ``` +### 2. Environment-Specific Linking + +Based on the environment you detected in Step 1, identify the correct target directory to enable the skills: + +| IDE/CLI | Target Skill Path | Type | +|---|---|---| +| **Claude Code** | `~/.claude/skills/hyperstack` | Global | +| **Cursor** | `.cursor/rules/` | Project-level | +| **Roo Code** | `.roo/rules/` | Project-level | +| **Windsurf** | `.codeium/windsurf/` | Project-level | + +As an agent, you should **symlink** the `~/.hyperstack/skills` directory to the target path above. This ensures updates to the central repo are immediately reflected in your active session. + ## Step 3: Configure the MCP Server ```json @@ -183,16 +198,16 @@ Once the pre-check passes, start a fresh session in the target environment (or r 2. **Skills are on disk:** Confirm the skills directory exists and has content: ```bash - ls ~/.claude/skills/hyperstack/skills/ # or ~/.qwen/skills/hyperstack/skills/ for Qwen Code + ls ~/.hyperstack/skills/ ``` Should show 21 directories plus `INDEX.md`. If missing or empty, the clone failed. -3. **Skills are auto-loaded (platforms with hooks only):** Ask: *"What Hyperstack skills are available?"* The agent should list skills from `skills/INDEX.md` (21 total, grouped into core / domain / meta). On platforms without hook support (e.g., Qwen Code), skip this - skills are on disk but not auto-injected. +3. **Skills are auto-loaded (platforms with hooks only):** Ask: *"What Hyperstack skills are available?"* The agent should list skills from `skills/INDEX.md` (21 total, grouped into core / domain / meta). On platforms without hook support, skip this - skills are on disk but not auto-injected. If any of these three checks fail, do not proceed. Fix the issue first: - MCP tool unknown β†’ verify config file location and JSON syntax, then restart the session - Skills missing β†’ re-run the clone command and confirm the path -- Skills not auto-loaded β†’ check that the platform supports `.claude-plugin/hooks.json`; if not, this is expected behavior +- Skills not auto-loaded β†’ check if your tool (e.g. Claude Code) supports hooks/plugin auto-loading. --- @@ -272,3 +287,20 @@ On Qwen Code, there is no plugin system or hook mechanism. Skills are available ### `bun: command not found` when using Option B Install Bun: `curl -fsSL https://bun.sh/install | bash`, then open a new shell so the path update takes effect. + +## Step 5: Welcome the User to Hyperstack + +Once all verifications pass, your final action is to explain the new reality to the user. Do not just say "installed." Explain the **Disciplined Engineering Harness**. + +**Recommended Success Message:** + +> "System Synchronized. Hyperstack is now active. +> +> I have installed the **Disciplined Engineering Harness** with 12 plugins and 80 tools. I have also established your **Iron Laws** (~/.hyperstack/skills). +> +> From now on: +> - I will not refactor code without a failing test. +> - I will not propose designs without a DESIGN.md contract. +> - I will use the ground-truth primitives provided by the Hyperstack vault. +> +> We are now operating under a professional engineering discipline. How should we begin our first high-integrity task?" diff --git a/package.json b/package.json index e83d217..bdacc35 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "@orkait-ai/hyperstack", "version": "1.0.5", - "description": "Disciplined MCP server + skill system. 11 plugins, 79 tools, 21 skills with adversarial enforcement. Designer/DESIGN.md pipeline, shadcn/ui, React Flow, Motion, Lenis, React 19, Echo, Go, Rust, design tokens, UI/UX.", + "description": "Disciplined MCP server + skill system. 12 plugins, 80 tools, 21 skills with adversarial enforcement. Designer/DESIGN.md pipeline, shadcn/ui, React Flow, Motion, Lenis, React 19, Echo, Go, Rust, design tokens, UI/UX.", "bin": { "hyperstack": "bin/hyperstack.mjs" }, diff --git a/scripts/setup.ts b/scripts/setup.ts index 441b67d..648390d 100644 --- a/scripts/setup.ts +++ b/scripts/setup.ts @@ -6,33 +6,55 @@ async function main() { console.log("\nπŸš€ Hyperstack Autonomous Setup (CLI)"); console.log("=====================================\n"); - const platform = setup.detectEnvironment(); - console.log(`πŸ“‘ Detected platform: ${platform}`); + const hintedPlatform = setup.detectEnvironment(); + console.log(`πŸ“‘ Hinted platform: ${hintedPlatform}`); + + const configPath = setup.findConfigFile(hintedPlatform); - const configPath = setup.findConfigFile(platform); - if (!configPath) { - console.warn("⚠️ Could not automatically find an MCP configuration file."); - console.log(`Check ${platform} documentation for the correct 'mcp.json' or settings path.`); + console.warn("⚠️ Could not find an MCP configuration file in any known location."); + console.log("Tried: .claude.json, .cursor/mcp.json, .codeium/windsurf/mcp_config.json, .roo/mcp.json, .gemini/settings.json, .kiro/settings/mcp.json, .qwen/settings.json"); + console.log("\nπŸ’‘ OpenAI Codex CLI? Run: codex mcp add hyperstack -- bun ~/.hyperstack/bin/hyperstack.mjs"); + console.log(" For any unknown IDE, use the Agentic Autopilot instead."); process.exit(1); } - console.log(`βœ… Found config: ${configPath}`); + // Resolve the actual platform from the found config path + const platform = setup.detectPlatformFromConfigPath(configPath); + console.log(`βœ… Found config: ${configPath} (${platform})`); + + const skillPath = setup.findSkillPath(platform); + if (skillPath) { + const hyperstackSkills = path.join(process.cwd(), "skills"); + const skillTarget = path.join(skillPath, "hyperstack"); + console.log(`\nπŸ“š Skill target: ${skillTarget}`); + console.log(`Run this to activate adversarial gates:`); + console.log(` ln -s "${hyperstackSkills}" "${skillTarget}"`); + } const pluginRoot = process.cwd(); - const patch = setup.generateMcpPatch(configPath, pluginRoot); + const patch = setup.generateMcpPatch(configPath, pluginRoot, platform); - console.log("\nProposed MCP Configuration Patch:"); + console.log("\nπŸ“‹ Proposed Configuration Patch:"); console.log("---------------------------------"); - console.log(JSON.stringify(patch, null, 2)); - console.log("---------------------------------\n"); - - console.log("To apply this patch:"); - console.log(`1. Open ${configPath}`); - console.log("2. Merged the 'hyperstack' entry into your 'mcpServers' or 'extensions' block."); - console.log("3. Restart your AI client."); - - console.log("\nFor an automated autopilot installation, call the 'hyperstack_setup' tool from within your AI assistant.\n"); + + if (patch.format === "toml-mcp_servers") { + console.log("# Append this to:", configPath); + console.log(patch.content as string); + console.log("---------------------------------\n"); + console.log("To finish manual setup:"); + console.log(`1. Run the symlink command above (if applicable).`); + console.log(`2. Append the TOML block above to ${configPath}`); + console.log("3. Run 'codex /mcp' to verify the connection."); + } else { + console.log(JSON.stringify(patch.content, null, 2)); + console.log("---------------------------------\n"); + console.log("To finish manual setup:"); + console.log(`1. Run the symlink command above (if applicable).`); + console.log(`2. Open ${configPath}`); + console.log("3. Merge the patch above into your config (deep-merge, don't replace)."); + console.log("4. Restart your AI client."); + } } main().catch(console.error); diff --git a/skills/designer/SKILL.md b/skills/designer/SKILL.md index 92f78ed..caf30c8 100644 --- a/skills/designer/SKILL.md +++ b/skills/designer/SKILL.md @@ -36,7 +36,7 @@ references: - examples/ecommerce-checkout.md --- -# Designer Skill β€” Intention Gate +# Designer Skill - Intention Gate > AI UIs all look same because AI skip decision process, jump to code. > Skill force every design decision through evidence before code generation. @@ -68,7 +68,7 @@ DO NOT GENERATE VISUAL CODE UNTIL: **Apply when:** task changes how something **looks, feels, moves, or is interacted with.** **Skip when:** pure backend, single CSS bug fix (same colors/spacing), adding to existing design system with established tokens, perf optimization no visual change, infrastructure. -## RED FLAGS β€” STOP +## RED FLAGS - STOP | Thought | Reality | |---|---| @@ -115,13 +115,13 @@ Reverse escalation: forge-plan β†’ designer (gap), behaviour-analysis β†’ design Every DESIGN.md must resolve these 7: -1. **Primary path** β€” user's main JTBD + single primary action -2. **Information scent** β€” "Where am I, what can I do, what happens next?" -3. **State coverage** β€” loading, empty, error, success, disabled, destructive -4. **Form/auth friction** β€” labels persistent, validation humane, paste allowed, password managers supported -5. **Performance budget** β€” LCP, INP, CLS, payload-sensitive media targets -6. **Accessibility floor** β€” focus visibility, focus not obscured, target size, reduced motion, keyboard usage -7. **Responsive content priority** β€” what survives first on mobile, what deferred +1. **Primary path** - user's main JTBD + single primary action +2. **Information scent** - "Where am I, what can I do, what happens next?" +3. **State coverage** - loading, empty, error, success, disabled, destructive +4. **Form/auth friction** - labels persistent, validation humane, paste allowed, password managers supported +5. **Performance budget** - LCP, INP, CLS, payload-sensitive media targets +6. **Accessibility floor** - focus visibility, focus not obscured, target size, reduced motion, keyboard usage +7. **Responsive content priority** - what survives first on mobile, what deferred Use [website-experience-cheatsheet](references/website-experience-cheatsheet.md). @@ -271,7 +271,7 @@ Routing: `shadcn/ui` β†’ `hyperstack:shadcn-expert` | `Raw Tailwind` β†’ forge-p Every MCP call fills specific DESIGN.md section. No call without purpose. -## Core Calls (Every Design Task β€” 4 calls, run in parallel) +## Core Calls (Every Design Task - 4 calls, run in parallel) ### Call 1: `designer_resolve_intent(product_description)` **FILLS:** All sections (defaults) @@ -280,7 +280,7 @@ Every MCP call fills specific DESIGN.md section. No call without purpose. ### Call 2: `designer_get_personality(resolved_cluster)` **FILLS:** Sections 1, 2, 3, 4, 6, 7 -**PURPOSE:** Concrete visual vocabulary β€” tracking, radius range, shadow style, motion timing, density, CSS example. Single most important data source. +**PURPOSE:** Concrete visual vocabulary - tracking, radius range, shadow style, motion timing, density, CSS example. Single most important data source. **USE:** Set every visual property. Personality vocabulary IS design system skeleton. ### Call 3: `designer_get_page_template(page_type)` @@ -313,7 +313,7 @@ NOT routine. Call ONLY when product has these specific features: | Premium feel | `designer_get_design_system("stripe")` or `("vercel-geist")` | S1 | Stripe weight 300/500, Vercel -0.04em tracking | | Enterprise | `designer_get_design_system("ibm-carbon")` | S1 | Carbon 12px spacing-04, IBM Plex, a11y-first | -## Token Calls (Phase 5 only β€” when generating code) +## Token Calls (Phase 5 only - when generating code) Do NOT call during design resolution: ``` @@ -538,7 +538,7 @@ Layer 3: Rules β†’ what constraints enforce it consistently? |---|---|---| | Colors | Warm-tinted: oklch(0.98 0.012 78) not oklch(0.98 0 0) | 0.012 chroma at hue 78 = "premium notebook" not "cold SaaS". Highest-leverage single decision. | | Typography | Serif or humanist sans, 18px body, 1.6-1.75 lh | Serif = trust. Larger body + generous leading = comfort. | -| Radius | 12-20px | Rounded = friendly (Gestalt). Cap 20px β€” beyond = childish. | +| Radius | 12-20px | Rounded = friendly (Gestalt). Cap 20px - beyond = childish. | | Shadows | Warm-tinted (oklch(0.22 0.006 56 / 0.06)) | Cold rgba shadows disconnected on warm surfaces. | | Motion | 200-300ms, ease-in-out, gentle | Spring/bounce = tonally wrong. | | Density | Comfortable (96px sections, 40px cards, 18px body) | Reading requires breathing room. | @@ -635,16 +635,16 @@ For full detail: `designer_get_industry_rules(industry)` # COGNITIVE LAWS (11) -> Source: Laws of UX, NNG, Smashing Magazine. Not opinions β€” empirically documented. +> Source: Laws of UX, NNG, Smashing Magazine. Not opinions - empirically documented. ## Fitts' Law -`T = a + b * log2(2D/W)` β€” Halving distance > doubling size. +`T = a + b * log2(2D/W)` - Halving distance > doubling size. - Touch targets β‰₯ 44px (WCAG) / 48px (Material). Screen edges = infinite mouse targets, hardest for touch. - Submit CTA at bottom of form (pointer already near last field). Destructive actions β‰₯ 8px from safe. - **Violations:** Icon-only buttons (16px visual β‰  44px target), Delete beside Save < 8px gap. ## Hick's Law -`RT = a + b * log2(n + 1)` β€” 2β†’4 choices costs more than 20β†’22. First added choices most expensive. +`RT = a + b * log2(n + 1)` - 2β†’4 choices costs more than 20β†’22. First added choices most expensive. - Minimize choices at irreversible points. Wizard pattern for multi-step. Surface recommended option. - Applies to decisions, not recognition. 15-item nav with clear categories = fine. 15-option modal = not. - **Violations:** All features on first login, pricing with no highlighted plan, 50+ unsorted dropdowns. @@ -703,14 +703,14 @@ Remembered = avg(peak intensity + final moment). Duration neglect. > Source: NNG (1.5M fixations, 57,453 fold fixations), A List Apart, Smashing Magazine -## Visual Hierarchy β€” 6 Levers (priority order) +## Visual Hierarchy - 6 Levers (priority order) -1. **Size** β€” Bigger = more important. Max 3 size variations. Never equal size for different priorities. -2. **Contrast** β€” Squint test: blur 5-10px, primary action must be first visible. -3. **Color** β€” Warm/saturated advances, cool/muted recedes. Red = destructive only. -4. **Typography** β€” Weight is primary signal. Everything emphasized = nothing emphasized. -5. **Spacing** β€” More surrounding space = more attention. Use before borders/fills. -6. **Position** β€” Top-left = most attention. Optical center above mathematical center. +1. **Size** - Bigger = more important. Max 3 size variations. Never equal size for different priorities. +2. **Contrast** - Squint test: blur 5-10px, primary action must be first visible. +3. **Color** - Warm/saturated advances, cool/muted recedes. Red = destructive only. +4. **Typography** - Weight is primary signal. Everything emphasized = nothing emphasized. +5. **Spacing** - More surrounding space = more attention. Use before borders/fills. +6. **Position** - Top-left = most attention. Optical center above mathematical center. ## CRAP Principles - **Contrast:** If different, make VERY different. Same-same = no hierarchy. @@ -723,7 +723,7 @@ Remembered = avg(peak intensity + final moment). Duration neglect. ## The Fold (NNG: 57,453 fixations) - Above fold: **102% more views**. 57% viewing time above fold. -- **Never fill exact viewport height** β€” bleed 40-80px of next section. False floor = users think page done. +- **Never fill exact viewport height** - bleed 40-80px of next section. False floor = users think page done. - First 100px must be relevant or users leave. ## Reading Patterns @@ -777,7 +777,7 @@ Every empty state = onboarding moment. Headline + copy + CTA. First-use: encoura --- -# DESIGN MASTERS β€” 5 CONVERGENCE POINTS +# DESIGN MASTERS - 5 CONVERGENCE POINTS > 7 masters (Rams, Norman, Vignelli, Spiekermann, Ive, Tufte, Kare) converged independently. @@ -797,7 +797,7 @@ Custom typeface = purchased differentiation. Open apertures for screen legibilit Maximize toward 1.0. "Can this be erased without info loss?" Lie Factor = effect shown / effect in data (1.0 = honest). Small multiples. Sparklines. ## Ive/Apple: Simplicity = Purpose -"Simplicity not absence of clutter β€” that's a consequence." Clarity (transparent carrier), Deference (UI steps back), Depth (spring physics = signifiers). +"Simplicity not absence of clutter - that's a consequence." Clarity (transparent carrier), Deference (UI steps back), Depth (spring physics = signifiers). ## Kare: Icons as Universal Language Meaningful (real metaphors), Memorable (one-trial learning), Clear (traffic sign test). @@ -843,16 +843,16 @@ ANY present β†’ go back to Phase 3: Assemble all decisions into 10-section DESIGN.md. See [template](references/design-md-template.md). See [examples](examples/) for worked outputs. ``` -1. Visual Theme & Atmosphere β€” emotional target, personality, system inspiration, identity -2. Color Palette β€” brand ramp (OKLCH 11 stops), semantic tokens, dark mode strategy -3. Typography β€” scale table, font pairing + rationale, fluid vs fixed -4. Spacing β€” semantic tokens, density, grid (12-col), content max-width -5. Component Specs β€” button/input/card/nav with ALL variants + ALL states -6. Motion β€” duration scale, easing rules, prefers-reduced-motion strategy -7. Elevation β€” shadow system (light), bg-color elevation (dark), z-index scale -8. Do's and Don'ts β€” 10 rules for THIS product, each traced to evidence -9. Responsive β€” behavior at 375/768/1024/1280/1440px -10. Anti-Patterns β€” industry violations, AI slop checks this design passes +1. Visual Theme & Atmosphere - emotional target, personality, system inspiration, identity +2. Color Palette - brand ramp (OKLCH 11 stops), semantic tokens, dark mode strategy +3. Typography - scale table, font pairing + rationale, fluid vs fixed +4. Spacing - semantic tokens, density, grid (12-col), content max-width +5. Component Specs - button/input/card/nav with ALL variants + ALL states +6. Motion - duration scale, easing rules, prefers-reduced-motion strategy +7. Elevation - shadow system (light), bg-color elevation (dark), z-index scale +8. Do's and Don'ts - 10 rules for THIS product, each traced to evidence +9. Responsive - behavior at 375/768/1024/1280/1440px +10. Anti-Patterns - industry violations, AI slop checks this design passes ``` **Present to user. Wait for approval. No code until approved.** @@ -965,7 +965,7 @@ forge-plan reads 10 sections β†’ generates tasks: Invocation: *"DESIGN.md approved and saved at ``. Invoking `hyperstack:forge-plan` with this as input spec."* -**To `shadcn` MCP plugin β€” ONLY if Q11b=shadcn:** +**To `shadcn` MCP plugin - ONLY if Q11b=shadcn:** ``` shadcn_get_rules β†’ architectural constraints (ALWAYS first) shadcn_get_composition(page_type) β†’ which components compose for this page @@ -976,7 +976,7 @@ for each component in DESIGN.md S5: ``` No shadcn component matching DESIGN.md spec β†’ escalate to `hyperstack:designer`, don't invent hybrid. -**To raw Tailwind β€” ONLY if Q11b=raw Tailwind:** +**To raw Tailwind - ONLY if Q11b=raw Tailwind:** ``` design_tokens_get_category("component-sizing") ui_ux_get_component_pattern(name) @@ -1028,6 +1028,6 @@ Before completion claim. Verifies: ## Announcement Protocol -When invoked: *"Using hyperstack:designer β€” producing DESIGN.md contract for [task type]."* +When invoked: *"Using hyperstack:designer - producing DESIGN.md contract for [task type]."* When handing off: *"DESIGN.md complete at [path]. Invoking hyperstack:forge-plan with this as input spec."* -When escalating back: *"[from-skill] escalating to designer β€” [reason]."* \ No newline at end of file +When escalating back: *"[from-skill] escalating to designer - [reason]."* \ No newline at end of file diff --git a/src/internal/setup-hyperstack.ts b/src/internal/setup-hyperstack.ts index ad516e1..81aec3f 100644 --- a/src/internal/setup-hyperstack.ts +++ b/src/internal/setup-hyperstack.ts @@ -5,58 +5,162 @@ import * as os from "node:os"; export interface SetupResult { detectedPlatform: string; configPath: string | null; + skillPath: string | null; status: "success" | "pending_research" | "error"; proposedPatch?: any; message: string; } -const KNOWN_PLATFORMS: Record = { +export type PlatformFormat = "json-mcpServers" | "json-contextServers" | "toml-mcp_servers" | "json-mcpServers-nested"; + +const KNOWN_PLATFORMS: Record = { + // ─── AI CLIs ──────────────────────────────────────────────── + + // Claude Code (CLI) - global user config + // Source: docs.anthropic.com, inventivehq.com (April 2025, multiple) "claude-code": { env: ["CLAUDE_PLUGIN_ROOT"], configFiles: [".claude.json"], + skillPath: ".claude/skills", + format: "json-mcpServers", + }, + // Gemini CLI - global user config + // Source: geminicli.com, augmentcode.com (April 2025, multiple) + "gemini-cli": { + configFiles: [".gemini/settings.json"], + format: "json-mcpServers", + notes: "Run '/mcp' inside Gemini CLI to verify connection", + }, + // Qwen Code (Alibaba) - global user config + // Source: github.io/qwen-code official docs (April 2025) + "qwen-code": { + configFiles: [".qwen/settings.json"], + skillPath: ".qwen/skills", + format: "json-mcpServers", + notes: "CLI alternative: qwen mcp add ", }, + // OpenAI Codex CLI - global user config (TOML format) + // Source: openai.com official docs (April 2025) + "codex": { + configFiles: [".codex/config.toml"], + format: "toml-mcp_servers", + notes: "CLI alternative: codex mcp add hyperstack -- bun ~/.hyperstack/bin/hyperstack.mjs", + }, + + // ─── AI IDEs ──────────────────────────────────────────────── + + // Cursor IDE - global user config + // Source: cursor.com docs, confirmed via 10+ tutorials (April 2025) "cursor": { env: ["CURSOR_PLUGIN_ROOT"], configFiles: [".cursor/mcp.json"], + skillPath: ".cursor/rules", + format: "json-mcpServers", + notes: "Project-level: .cursor/mcp.json in project root", }, + // Windsurf IDE (Codeium) - global user config + // Source: windsurf.com official docs, bito.ai, zapier (April 2025) "windsurf": { configFiles: [".codeium/windsurf/mcp_config.json"], + format: "json-mcpServers", + notes: "Click 'Refresh' in Cascade panel after editing", }, + // Kiro (Amazon AI IDE) - global user config + // Source: kiro.dev official docs, aws.com (April 2025) + "kiro": { + configFiles: [".kiro/settings/mcp.json"], + format: "json-mcpServers", + notes: "Workspace-level: .kiro/settings/mcp.json in project root", + }, + // Zed editor - global user config (uses 'context_servers' key, not 'mcpServers') + // Source: zed.dev official docs, skeet.build (April 2025) + "zed": { + configFiles: [".config/zed/settings.json"], + format: "json-contextServers", + notes: "Uses 'context_servers' key instead of 'mcpServers'", + }, + + // ─── VS Code Extensions ───────────────────────────────────── + + // VS Code + GitHub Copilot - platform-specific global config + // Source: code.visualstudio.com official docs (April 2025) + "vscode": { + env: ["VSCODE_PID"], + configFiles: [ + ".config/Code/User/mcp.json", // Linux + "Library/Application Support/Code/User/mcp.json", // macOS + ], + format: "json-mcpServers", + notes: "Project-level: .vscode/mcp.json in project root", + }, + // Roo Code (VS Code extension) + // Global config has no fixed home path (stored in VS Code extension storage). + // Source: roocode.com official docs (April 2025) "roo-code": { - configFiles: [".roo/mcp.json", "mcp_settings.json"], + configFiles: [".roo/mcp.json"], + skillPath: ".roo/rules", + format: "json-mcpServers", + notes: "Global config: open via Roo Code UI > Edit Global MCP", }, - "gemini-cli": { - configFiles: [".gemini/settings.json"], + // Cline (VS Code extension) - Linux global path + // Source: cline.bot official docs, reddit (April 2025) + "cline": { + configFiles: [ + ".config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json", // Linux + ".cline/data/settings/cline_mcp_settings.json", // Cline CLI fallback + ], + format: "json-mcpServers", + notes: "Access via Cline panel > MCP Servers > Configure", + }, + // Continue.dev (VS Code extension) - project-level only + // Source: continue.dev official docs (April 2025) + "continue-dev": { + configFiles: [".continue/mcpServers/mcp.json"], + format: "json-mcpServers", + notes: "Requires Agent Mode. Place config in .continue/mcpServers/ directory", }, }; + export function detectEnvironment(): string { - // Check environment variables first + // Env-var hints (fast path, but unreliable in nested terminals) if (process.env.CLAUDE_PLUGIN_ROOT) return "claude-code"; if (process.env.CURSOR_PLUGIN_ROOT) return "cursor"; - if (process.env.VSCODE_PID) return "vscode-derivative"; // Likely Roo Code or Windsurf or VS Code - + // VSCODE_PID fires inside any VS Code-hosted terminal (Gemini, Roo Code, etc.) + // Do NOT short-circuit here - fall through to config-file probing below. return "unknown"; } export function findConfigFile(platform: string): string | null { const home = os.homedir(); - - if (platform === "unknown") { - // Probe common locations - for (const [p, info] of Object.entries(KNOWN_PLATFORMS)) { + + // Always probe all known config files - this is the authoritative source of truth. + // Even if `platform` was resolved from env vars, the config file must exist. + const candidates: Array<{ platform: string; file: string }> = []; + + if (platform !== "unknown" && KNOWN_PLATFORMS[platform]) { + // Try hinted platform first + for (const file of KNOWN_PLATFORMS[platform].configFiles) { + candidates.push({ platform, file }); + } + } + + // Always append all other platforms as fallback probes + for (const [p, info] of Object.entries(KNOWN_PLATFORMS)) { + if (p !== platform) { for (const file of info.configFiles) { - const fullPath = path.join(home, file); - if (fs.existsSync(fullPath)) return fullPath; + candidates.push({ platform: p, file }); } } - return null; } - const info = KNOWN_PLATFORMS[platform]; - if (!info) return null; - - for (const file of info.configFiles) { + for (const { file } of candidates) { const fullPath = path.join(home, file); if (fs.existsSync(fullPath)) return fullPath; } @@ -64,49 +168,77 @@ export function findConfigFile(platform: string): string | null { return null; } +export function detectPlatformFromConfigPath(configPath: string): string { + for (const [p, info] of Object.entries(KNOWN_PLATFORMS)) { + for (const file of info.configFiles) { + if (configPath.endsWith(file)) return p; + } + } + return "unknown"; +} + +export function findSkillPath(platform: string): string | null { + const info = KNOWN_PLATFORMS[platform]; + if (!info || !info.skillPath) return null; + + return path.join(os.homedir(), info.skillPath); +} + + +export function getPlatformFormat(platform: string): PlatformFormat { + return KNOWN_PLATFORMS[platform]?.format ?? "json-mcpServers"; +} export function generateMcpPatch( configPath: string, pluginRoot: string, + platform: string, method: "docker" | "local" = "docker" -) { - const isClaude = configPath.endsWith(".claude.json"); - const isGemini = configPath.includes("settings.json") && configPath.includes(".gemini"); - +): { format: PlatformFormat; content: string | object } { const binaryPath = path.join(pluginRoot, "bin", "hyperstack.mjs"); - const localConfig = { + const localServerConfig = { command: "node", args: [binaryPath], - env: { - HYPERSTACK_ROOT: pluginRoot, - }, + env: { HYPERSTACK_ROOT: pluginRoot }, }; - - const dockerConfig = { + const dockerServerConfig = { command: "docker", args: ["exec", "-i", "hyperstack-mcp", "bun", "/app/src/index.ts"], - env: { - HYPERSTACK_ROOT: pluginRoot, // Still helpful for skills indexing - }, + env: { HYPERSTACK_ROOT: pluginRoot }, }; + const serverConfig = method === "docker" ? dockerServerConfig : localServerConfig; + const format = getPlatformFormat(platform); - const serverConfig = method === "docker" ? dockerConfig : localConfig; - - if (isGemini) { + // Zed uses 'context_servers' key instead of 'mcpServers' + // Source: zed.dev official docs (April 2025) + if (format === "json-contextServers") { return { - extensions: { - hyperstack: { - ...serverConfig, - type: "stdio", + format, + content: { + context_servers: { + hyperstack: serverConfig, }, }, }; } - // Default MCP schema (Claude, Cursor, Windsurf, Roo Code) + // Codex CLI uses TOML format: [mcp_servers.] + // Source: openai.com official docs (April 2025) + if (format === "toml-mcp_servers") { + const tomlBlock = method === "docker" + ? `[mcp_servers.hyperstack]\ncommand = "docker"\nargs = ["exec", "-i", "hyperstack-mcp", "bun", "/app/src/index.ts"]\n[mcp_servers.hyperstack.env]\nHYPERSTACK_ROOT = "${pluginRoot}"` + : `[mcp_servers.hyperstack]\ncommand = "node"\nargs = ["${binaryPath}"]\n[mcp_servers.hyperstack.env]\nHYPERSTACK_ROOT = "${pluginRoot}"`; + return { format, content: tomlBlock }; + } + + // Default: standard mcpServers JSON schema + // Covers: Claude Code, Cursor, Windsurf, Roo Code, VS Code, Kiro, Qwen, Gemini, Cline, Continue.dev return { - mcpServers: { - hyperstack: serverConfig, + format, + content: { + mcpServers: { + hyperstack: serverConfig, + }, }, }; }