@cliangdev/flux-plugin 0.2.0-dev.dc5e2c4 → 0.2.0-dev.e34d43b

package/src/server/tools/__tests__/mcp-interface.test.ts

@@ -10,7 +10,12 @@ process.env.FLUX_PROJECT_ROOT = TEST_DIR;
 import { z } from "zod";
 import { config } from "../../config.js";
 import { closeDb, initDb } from "../../db/index.js";
-import { createError, registerTools, type ToolDefinition } from "../index.js";
+import {
+  createError,
+  createProjectNotInitializedError,
+  registerTools,
+  type ToolDefinition,
+} from "../index.js";
 
 describe("MCP Interface", () => {
   beforeEach(() => {
@@ -44,6 +49,42 @@ describe("MCP Interface", () => {
     });
   });
 
+  describe("createProjectNotInitializedError", () => {
+    test("creates error with setup instructions", () => {
+      const error = createProjectNotInitializedError("/test/cwd", "/test/root");
+
+      expect(error.error).toBe(true);
+      expect(error.code).toBe("PROJECT_NOT_INITIALIZED");
+      expect(error.message).toContain("/test/cwd");
+      expect(error.message).toContain("/test/root");
+      expect(error.setup.instructions).toBeDefined();
+      expect(error.setup.options).toHaveLength(2);
+    });
+
+    test("includes command option for interactive setup", () => {
+      const error = createProjectNotInitializedError("/cwd", "/root");
+      const commandOption = error.setup.options.find(
+        (o) => o.method === "command",
+      );
+
+      expect(commandOption).toBeDefined();
+      expect(commandOption?.name).toBe("/flux");
+      expect(commandOption?.description).toContain("Interactive");
+    });
+
+    test("includes tool option with required params", () => {
+      const error = createProjectNotInitializedError("/cwd", "/root");
+      const toolOption = error.setup.options.find((o) => o.method === "tool");
+
+      expect(toolOption).toBeDefined();
+      expect(toolOption?.name).toBe("init_project");
+      expect(toolOption?.params).toBeDefined();
+      expect(toolOption?.params?.name).toBeDefined();
+      expect(toolOption?.params?.vision).toBeDefined();
+      expect(toolOption?.params?.adapter).toBeDefined();
+    });
+  });
+
   describe("registerTools", () => {
     test("sets up list tools handler", () => {
       const handlers: Record<string, Function> = {};
@@ -287,7 +328,7 @@ describe("Project Validation", () => {
     }
   });
 
-  test("returns PROJECT_NOT_FOUND for tools requiring project", async () => {
+  test("returns PROJECT_NOT_INITIALIZED with setup instructions for tools requiring project", async () => {
     const handlers: Record<string, Function> = {};
     const mockServer = {
       setRequestHandler: mock((schema: any, handler: Function) => {
@@ -317,7 +358,11 @@ describe("Project Validation", () => {
     expect(result.isError).toBe(true);
     const parsedError = JSON.parse(result.content[0].text);
     expect(parsedError.error).toBe(true);
-    expect(parsedError.code).toBe("PROJECT_NOT_FOUND");
+    expect(parsedError.code).toBe("PROJECT_NOT_INITIALIZED");
+    expect(parsedError.setup).toBeDefined();
+    expect(parsedError.setup.instructions).toBeDefined();
+    expect(parsedError.setup.options).toBeDefined();
+    expect(parsedError.setup.options.length).toBe(2);
   });
 
   test("allows init_project without existing project", async () => {
@@ -353,7 +398,7 @@ describe("Project Validation", () => {
     expect(handlerMock).toHaveBeenCalled();
   });
 
-  test("allows get_project_context without existing project", async () => {
+  test("allows get_version without existing project", async () => {
     const handlers: Record<string, Function> = {};
     const mockServer = {
       setRequestHandler: mock((schema: any, handler: Function) => {
@@ -363,11 +408,11 @@ describe("Project Validation", () => {
       }),
     };
 
-    const handlerMock = mock(async () => ({ initialized: false }));
+    const handlerMock = mock(async () => ({ version: "1.0.0" }));
 
     const testTool: ToolDefinition = {
-      name: "get_project_context",
-      description: "Get project context",
+      name: "get_version",
+      description: "Get version",
       inputSchema: z.object({}),
       handler: handlerMock,
     };
@@ -377,7 +422,7 @@ describe("Project Validation", () => {
     const callHandler = handlers.call;
     const result = await callHandler({
       params: {
-        name: "get_project_context",
+        name: "get_version",
         arguments: {},
       },
     });
@@ -385,4 +430,49 @@ describe("Project Validation", () => {
     expect(result.isError).toBeUndefined();
     expect(handlerMock).toHaveBeenCalled();
   });
+
+  test("setup options have correct structure", async () => {
+    const handlers: Record<string, Function> = {};
+    const mockServer = {
+      setRequestHandler: mock((schema: any, handler: Function) => {
+        if (schema.shape?.method?.value === "tools/call") {
+          handlers.call = handler;
+        }
+      }),
+    };
+
+    const testTool: ToolDefinition = {
+      name: "query_entities",
+      description: "Query entities",
+      inputSchema: z.object({ type: z.string() }),
+      handler: async () => ({ items: [] }),
+    };
+
+    registerTools(mockServer as any, [testTool]);
+
+    const callHandler = handlers.call;
+    const result = await callHandler({
+      params: {
+        name: "query_entities",
+        arguments: { type: "prd" },
+      },
+    });
+
+    expect(result.isError).toBe(true);
+    const parsedError = JSON.parse(result.content[0].text);
+
+    const commandOption = parsedError.setup.options.find(
+      (o: any) => o.method === "command",
+    );
+    expect(commandOption.name).toBe("/flux");
+    expect(commandOption.description).toBeTruthy();
+
+    const toolOption = parsedError.setup.options.find(
+      (o: any) => o.method === "tool",
+    );
+    expect(toolOption.name).toBe("init_project");
+    expect(toolOption.params.name).toBeTruthy();
+    expect(toolOption.params.vision).toBeTruthy();
+    expect(toolOption.params.adapter).toBeTruthy();
+  });
 });

package/src/server/tools/__tests__/query.test.ts

@@ -16,7 +16,6 @@ import { createPrdTool } from "../create-prd.js";
 import { createTaskTool } from "../create-task.js";
 import { addDependencyTool } from "../dependencies.js";
 import { getEntityTool } from "../get-entity.js";
-import { getProjectContextTool } from "../get-project-context.js";
 import { getStatsTool } from "../get-stats.js";
 import { initProjectTool } from "../init-project.js";
 import { queryEntitiesTool } from "../query-entities.js";
@@ -242,24 +241,6 @@ describe("Query MCP Tools", () => {
     });
   });
 
-  describe("get_project_context", () => {
-    test("returns project context when initialized", async () => {
-      const result = (await getProjectContextTool.handler({})) as any;
-
-      expect(result.initialized).toBe(true);
-      expect(result.name).toBe("test-project");
-      expect(result.ref_prefix).toBe("TEST");
-    });
-
-    test("returns initialized false when no project", async () => {
-      // Remove the project.json
-      rmSync(join(FLUX_DIR, "project.json"));
-
-      const result = (await getProjectContextTool.handler({})) as any;
-      expect(result.initialized).toBe(false);
-    });
-  });
-
   describe("get_stats", () => {
     test("returns zeroes for empty project", async () => {
       const result = (await getStatsTool.handler({})) as any;

package/src/server/tools/index.ts

@@ -7,11 +7,7 @@ import { z } from "zod";
 import { config } from "../config.js";
 import { logger } from "../utils/logger.js";
 
-const TOOLS_WITHOUT_PROJECT = [
-  "init_project",
-  "get_project_context",
-  "get_version",
-];
+const TOOLS_WITHOUT_PROJECT = ["init_project", "get_version"];
 
 export interface ToolDefinition {
   name: string;
@@ -26,10 +22,56 @@ export interface ToolError {
   code: string;
 }
 
+export interface ProjectNotInitializedError extends ToolError {
+  code: "PROJECT_NOT_INITIALIZED";
+  setup: {
+    instructions: string;
+    options: Array<{
+      method: "command" | "tool";
+      name: string;
+      description: string;
+      params?: Record<string, string>;
+    }>;
+  };
+}
+
 export function createError(message: string, code: string): ToolError {
   return { error: true, message, code };
 }
 
+export function createProjectNotInitializedError(
+  cwd: string,
+  projectRoot: string,
+): ProjectNotInitializedError {
+  return {
+    error: true,
+    code: "PROJECT_NOT_INITIALIZED",
+    message: `No Flux project found. Current directory: ${cwd}, resolved project root: ${projectRoot}`,
+    setup: {
+      instructions:
+        "Initialize a Flux project before using Flux tools. Use one of the following options:",
+      options: [
+        {
+          method: "command",
+          name: "/flux",
+          description:
+            "Interactive setup with guided prompts (recommended for first-time setup)",
+        },
+        {
+          method: "tool",
+          name: "init_project",
+          description: "Direct initialization via MCP tool",
+          params: {
+            name: "Project name (required)",
+            vision: "Brief project description (required)",
+            adapter: "local | linear (default: local)",
+          },
+        },
+      ],
+    },
+  };
+}
+
 export function registerTools(server: Server, tools: ToolDefinition[]) {
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: tools.map((t) => ({
@@ -60,13 +102,16 @@ export function registerTools(server: Server, tools: ToolDefinition[]) {
     }
 
     if (!TOOLS_WITHOUT_PROJECT.includes(toolName) && !config.projectExists) {
-      const message = `No Flux project found. Run init_project first or ensure you're in a directory with a .flux folder (or a subdirectory of one). Current directory: ${process.cwd()}, resolved project root: ${config.projectRoot}`;
-      logger.error(message);
+      const error = createProjectNotInitializedError(
+        process.cwd(),
+        config.projectRoot,
+      );
+      logger.error(error.message);
       return {
         content: [
           {
             type: "text",
-            text: JSON.stringify(createError(message, "PROJECT_NOT_FOUND")),
+            text: JSON.stringify(error, null, 2),
           },
         ],
         isError: true,
@@ -104,7 +149,6 @@ export { deleteEntityTool } from "./delete-entity.js";
 export { addDependencyTool, removeDependencyTool } from "./dependencies.js";
 export { getEntityTool } from "./get-entity.js";
 export { getLinearUrlTool } from "./get-linear-url.js";
-export { getProjectContextTool } from "./get-project-context.js";
 export { getStatsTool } from "./get-stats.js";
 export { getVersionTool } from "./get-version.js";
 export { initProjectTool } from "./init-project.js";

package/src/server/tools/init-project.ts

@@ -102,7 +102,7 @@ async function handler(input: unknown) {
 export const initProjectTool: ToolDefinition = {
   name: "init_project",
   description:
-    "Initialize a new Flux project. Required: name, vision. Optional: adapter (local|specflux|linear|notion, default 'local'). Creates .flux/ directory with project.json and SQLite database. Returns {success, project, message}. Fails if .flux/ already exists. Run get_project_context first to check.",
+    "Initialize a new Flux project. Required: name, vision. Optional: adapter (local|specflux|linear|notion, default 'local'). Creates .flux/ directory with project.json and SQLite database. Returns {success, project, message}. Fails if .flux/ already exists.",
   inputSchema,
   handler,
 };

package/skills/prd-template/SKILL.md

@@ -1,242 +0,0 @@
----
-name: flux:prd-template
-description: PRD structure and patterns for Flux. Use when creating or refining product requirement documents. PRDs should be concise for humans but detailed enough for AI agents to implement.
-user-invocable: false
----
-
-# PRD Template Skill
-
-PRDs should be **concise for human review** but contain **enough detail for AI implementation**.
-
-## PRD Structure (Required)
-
-```markdown
-# {Project Name}
-
-## Table of Contents
-- [Problem](#problem)
-- [Users](#users)
-- [Solution](#solution)
-- [Features (MVP)](#features-mvp)
-  - [P0: Must Have](#p0-must-have)
-  - [P1: Should Have](#p1-should-have)
-  - [Out of Scope](#out-of-scope)
-- [Constraints](#constraints)
-- [Open Questions](#open-questions)
-
-## Problem
-{2-3 sentences: What problem are we solving? Why does it matter?}
-
-## Users
-{Who has this problem? 1-2 user segments.}
-
-## Solution
-{1 paragraph: What are we building to solve this?}
-
-## Features (MVP)
-
-### P0: Must Have
-- **{Feature 1}**: {One sentence description}
-  - {Acceptance criterion 1}
-  - {Acceptance criterion 2}
-- **{Feature 2}**: {One sentence description}
-  - {Acceptance criterion}
-
-### P1: Should Have
-- **{Feature}**: {Description}
-
-### Out of Scope
-- {What we're NOT building}
-- {Future considerations}
-
-## Constraints
-- **Tech Stack**: {Required technologies, if any}
-- **Timeline**: {Any deadlines}
-- **Other**: {Budget, compliance, etc.}
-
-## Open Questions
-- {Unresolved decisions needing input}
-```
-
-### TOC Guidelines
-
-**For Local Adapter** (files in `.flux/prds/`):
-- Include TOC with anchor links (e.g., `[Problem](#problem)`)
-- Use lowercase with hyphens for anchors
-- Nest sub-sections under parent sections
-
-**For External Adapters** (Linear, Notion):
-- **Skip TOC** - External systems have their own navigation (Linear's outline, collapsible sections)
-- Linear generates unique anchor suffixes making pre-built links impossible
-
-## Guidelines
-
-### Keep It Short
-- Problem: 2-3 sentences max
-- Features: 3-5 P0 features for MVP
-- Each feature: 1 sentence + 2-4 acceptance criteria
-- Total PRD: 1-2 pages
-
-### Write for AI Implementation
-- Acceptance criteria should be testable
-- Use specific, unambiguous language
-- Include edge cases in criteria when important
-
-### Bad vs Good Examples
-
-**Bad feature:**
-> - User authentication
-
-**Good feature:**
-> - **User Authentication**: Users can sign up and log in with email/password
->   - Sign up requires email, password (min 8 chars), and name
->   - Login with email + password returns JWT token
->   - Invalid credentials show error message
->   - Forgot password sends reset email
-
-## Supporting Documents (Optional)
-
-Generate based on **agent confidence** and **user request**.
-
-| Document | When to Generate |
-|----------|------------------|
-| `architecture.md` | Complex systems, multiple components, API integrations |
-| `wireframes.md` | UI-heavy features, user specifically requests |
-| `data-model.md` | Custom data storage, complex relationships |
-| `user-flows.md` | Multi-step processes, complex user journeys |
-
-### Asking About Supporting Docs
-
-After PRD outline approval, ask:
-
-```
-PRD outline looks good. I can also generate:
-- Architecture diagram (recommended for this project)
-- UI wireframes
-- Data model
-
-Which would you like? Or should I proceed with just the PRD?
-```
-
-Recommend based on project type:
-- **Web App**: architecture, wireframes
-- **API/Backend**: architecture, data-model
-- **CLI Tool**: usually just PRD
-- **Mobile App**: architecture, wireframes
-
-## Supporting Doc Templates
-
-### architecture.md
-
-```markdown
-# Architecture
-
-## Overview
-{One paragraph system description}
-
-## Components
-
-```mermaid
-graph TB
-    Client[Client] --> API[API Server]
-    API --> DB[(Database)]
-    API --> Cache[(Redis)]
-```
-
-## API Endpoints
-
-| Method | Path | Description |
-|--------|------|-------------|
-| POST | /api/users | Create user |
-| GET | /api/users/:id | Get user |
-
-## Data Flow
-{Describe key data flows}
-
-## Tech Stack
-- **Frontend**: {tech}
-- **Backend**: {tech}
-- **Database**: {tech}
-```
-
-### wireframes.md
-
-```markdown
-# Wireframes
-
-## Screen: {Name}
-
-```
-+----------------------------------+
-|  Logo              [Login] [Sign Up]
-+----------------------------------+
-|                                  |
-|     Welcome to {App Name}        |
-|                                  |
-|     [  Email  ]                  |
-|     [Password ]                  |
-|     [  Login  ]                  |
-|                                  |
-|     Forgot password?             |
-+----------------------------------+
-```
-
-**Elements:**
-- Logo: links to home
-- Login button: submits form
-- Forgot password: opens reset flow
-```
-
-### data-model.md
-
-```markdown
-# Data Model
-
-## ERD
-
-```mermaid
-erDiagram
-    User ||--o{ Post : creates
-    Post ||--o{ Comment : has
-```
-
-## Tables
-
-### users
-| Column | Type | Constraints |
-|--------|------|-------------|
-| id | uuid | PK |
-| email | varchar | unique, not null |
-| created_at | timestamp | default now() |
-
-### posts
-| Column | Type | Constraints |
-|--------|------|-------------|
-| id | uuid | PK |
-| user_id | uuid | FK users.id |
-| content | text | not null |
-```
-
-## Workflow
-
-Check adapter type via `get_project_context` to determine storage behavior.
-
-### Local Adapter (`adapter.type === "local"`)
-
-1. **Interview** → Collect answers via AskUserQuestion
-2. **Outline** → Generate brief outline, ask for approval
-3. **Create entity** → Call `create_prd` with title and short description
-4. **Write PRD** → Write full PRD to `.flux/prds/{slug}/prd.md`
-5. **Set folder_path** → Call `update_entity` with `folder_path`: `.flux/prds/{slug}`
-6. **Ask about docs** → Offer relevant supporting docs
-7. **Generate docs** → Write requested docs to same folder
-
-### External Adapters (`adapter.type === "linear"`, `"notion"`, etc.)
-
-1. **Interview** → Collect answers via AskUserQuestion
-2. **Outline** → Generate brief outline, ask for approval
-3. **Create entity** → Call `create_prd` with title and short description
-4. **Sync content** → Call `update_entity` with `description`: Full PRD markdown content
-5. **Ask about docs** → Offer relevant supporting docs (stored as attachments in external system)
-
-**Note**: External adapters store all content in the external system. No local `.flux/prds/` files are created.

package/src/server/tools/get-project-context.ts

@@ -1,33 +0,0 @@
-import { existsSync, readFileSync } from "node:fs";
-import { z } from "zod";
-import { config } from "../config.js";
-import type { ToolDefinition } from "./index.js";
-
-const inputSchema = z.object({});
-
-async function handler(_input: unknown) {
-  const projectJsonPath = config.projectJsonPath;
-
-  if (!existsSync(projectJsonPath)) {
-    return { initialized: false };
-  }
-
-  try {
-    const content = readFileSync(projectJsonPath, "utf-8");
-    const project = JSON.parse(content);
-    return { initialized: true, ...project };
-  } catch (_err) {
-    return {
-      initialized: false,
-      error: "Failed to read project.json",
-    };
-  }
-}
-
-export const getProjectContextTool: ToolDefinition = {
-  name: "get_project_context",
-  description:
-    "Get project context from .flux/project.json. No parameters required. Returns {initialized: boolean, name?, vision?, ref_prefix?, adapter?: {type: 'local'|'specflux'|'linear'|'notion'}, created_at?}. Use this to check if a Flux project exists before other operations.",
-  inputSchema,
-  handler,
-};