forgecraft-mcp 1.2.0 → 1.4.0

package/dist/registry/renderer-skeletons.js

@@ -11,42 +11,42 @@
  * @returns Status.md content ready to write
  */
 export function renderStatusMd(context) {
-    return `# Status.md
-
-## Last Updated: ${new Date().toISOString().split("T")[0]}
-## Session Summary
-Project initialized with ForgeCraft. Tags: ${context.tags.join(", ")}.
-
-## Project Structure
-\`\`\`
-[Run 'tree -L 3 --dirsfirst' to populate]
-\`\`\`
-
-## Feature Tracker
-| Feature | Status | Branch | Notes |
-|---------|--------|--------|-------|
-| | ⬚ Not Started | | |
-
-## Known Bugs
-| ID | Description | Severity | Status |
-|----|-------------|----------|--------|
-| | | | |
-
-## Technical Debt
-| Item | Impact | Effort | Priority |
-|------|--------|--------|----------|
-| | | | |
-
-## Current Context
-- Working on:
-- Blocked by:
-- Decisions pending:
-- Next steps:
-
-## Architecture Decision Log
-| Date | Decision | Rationale | Status |
-|------|----------|-----------|--------|
-| | | | |
+    return `# Status.md
+
+## Last Updated: ${new Date().toISOString().split("T")[0]}
+## Session Summary
+Project initialized with ForgeCraft. Tags: ${context.tags.join(", ")}.
+
+## Project Structure
+\`\`\`
+[Run 'tree -L 3 --dirsfirst' to populate]
+\`\`\`
+
+## Feature Tracker
+| Feature | Status | Branch | Notes |
+|---------|--------|--------|-------|
+| | ⬚ Not Started | | |
+
+## Known Bugs
+| ID | Description | Severity | Status |
+|----|-------------|----------|--------|
+| | | | |
+
+## Technical Debt
+| Item | Impact | Effort | Priority |
+|------|--------|--------|----------|
+| | | | |
+
+## Current Context
+- Working on:
+- Blocked by:
+- Decisions pending:
+- Next steps:
+
+## Architecture Decision Log
+| Date | Decision | Rationale | Status |
+|------|----------|-----------|--------|
+| | | | |
 `;
 }
 /**
@@ -56,33 +56,33 @@ Project initialized with ForgeCraft. Tags: ${context.tags.join(", ")}.
  * @returns PRD.md content ready to write
  */
 export function renderPrdSkeleton(context) {
-    return `# PRD: ${context.projectName}
-
-## Background & Context
-[Why this project exists, what problem it solves]
-
-## Stakeholders
-[Who owns it, who uses it, who's affected]
-
-## User Stories
-[Organized by feature area]
-- US-001: As a [type], I want [action] so that [benefit]
-
-## Requirements
-### Functional Requirements
-- FR-001: [requirement]
-
-### Non-Functional Requirements
-[Generated from active tags: ${context.tags.join(", ")}]
-
-## Out of Scope
-[Explicitly list what this project does NOT do]
-
-## Success Metrics
-[How do we know this project succeeded?]
-
-## Open Questions
-[Unresolved decisions]
+    return `# PRD: ${context.projectName}
+
+## Background & Context
+[Why this project exists, what problem it solves]
+
+## Stakeholders
+[Who owns it, who uses it, who's affected]
+
+## User Stories
+[Organized by feature area]
+- US-001: As a [type], I want [action] so that [benefit]
+
+## Requirements
+### Functional Requirements
+- FR-001: [requirement]
+
+### Non-Functional Requirements
+[Generated from active tags: ${context.tags.join(", ")}]
+
+## Out of Scope
+[Explicitly list what this project does NOT do]
+
+## Success Metrics
+[How do we know this project succeeded?]
+
+## Open Questions
+[Unresolved decisions]
 `;
 }
 /**
@@ -92,35 +92,35 @@ export function renderPrdSkeleton(context) {
  * @returns TechSpec.md content ready to write
  */
 export function renderTechSpecSkeleton(context) {
-    return `# Tech Spec: ${context.projectName}
-
-## Overview
-[One paragraph translating PRD to technical approach]
-
-## Architecture
-### System Diagram
-[Mermaid diagram or description of components]
-
-### Tech Stack
-- Runtime: ${context.language}
-- Framework: ${context.framework ?? "[TBD]"}
-
-### Data Flow
-[How data moves through the system]
-
-## API Contracts
-[Key endpoints, request/response shapes]
-
-## Security & Compliance
-[Auth approach, encryption, audit logging]
-
-## Dependencies
-[External services, APIs, libraries with version pins]
-
-## Risks & Mitigations
-| Risk | Likelihood | Impact | Mitigation |
-|------|-----------|--------|------------|
-| | H/M/L | H/M/L | |
+    return `# Tech Spec: ${context.projectName}
+
+## Overview
+[One paragraph translating PRD to technical approach]
+
+## Architecture
+### System Diagram
+[Mermaid diagram or description of components]
+
+### Tech Stack
+- Runtime: ${context.language}
+- Framework: ${context.framework ?? "[TBD]"}
+
+### Data Flow
+[How data moves through the system]
+
+## API Contracts
+[Key endpoints, request/response shapes]
+
+## Security & Compliance
+[Auth approach, encryption, audit logging]
+
+## Dependencies
+[External services, APIs, libraries with version pins]
+
+## Risks & Mitigations
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| | H/M/L | H/M/L | |
 `;
 }
 //# sourceMappingURL=renderer-skeletons.js.map

package/dist/shared/gs-score-logger.js

@@ -11,12 +11,12 @@ import { appendFileSync, existsSync, mkdirSync, writeFileSync } from "fs";
 import { join } from "path";
 // ── Constants ────────────────────────────────────────────────────────
 const GS_SCORE_FILE = "docs/gs-score.md";
-const GS_SCORE_HEADER = `# GS Score Log
-
-Tracks S_realized and GS property scores per loop.
-
-| date | loop | roadmap_item | s_realized | self-describing | bounded | verifiable | defended | auditable | composable | executable |
-|------|------|--------------|------------|-----------------|---------|-----------|----------|-----------|-----------|-----------|
+const GS_SCORE_HEADER = `# GS Score Log
+
+Tracks S_realized and GS property scores per loop.
+
+| date | loop | roadmap_item | s_realized | self-describing | bounded | verifiable | defended | auditable | composable | executable |
+|------|------|--------------|------------|-----------------|---------|-----------|----------|-----------|-----------|-----------|
 `;
 const GS_PROPERTY_ORDER = [
     "self-describing",

package/dist/shared/result-utils.d.ts

@@ -0,0 +1,27 @@
+/**
+ * MCP tool result size utilities.
+ *
+ * Prevents silent schema truncation at the MCP transport layer by:
+ * - Annotating large results with their size (chars + lines)
+ * - Truncating results that exceed the limit with an explicit marker
+ *   so the caller knows to refine their query rather than acting on
+ *   incomplete data.
+ */
+/** Maximum characters returned in a single tool result. */
+export declare const MAX_TOOL_RESULT_CHARS = 50000;
+/**
+ * Annotate a tool result text with its size and truncate if necessary.
+ *
+ * - Under `maxChars` and over `SIZE_ANNOTATION_THRESHOLD`: appends a compact
+ *   footer showing char/line count.
+ * - Over `maxChars`: truncates to `maxChars` and appends a `[TRUNCATED]`
+ *   footer so the caller knows the response is incomplete.
+ * - Under `SIZE_ANNOTATION_THRESHOLD`: returned as-is (no footer noise for
+ *   short replies like "No violations recorded.").
+ *
+ * @param text - Raw tool result text
+ * @param maxChars - Truncation limit (default: MAX_TOOL_RESULT_CHARS)
+ * @returns Annotated (and possibly truncated) text
+ */
+export declare function annotateResult(text: string, maxChars?: number): string;
+//# sourceMappingURL=result-utils.d.ts.map

package/dist/shared/result-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-utils.d.ts","sourceRoot":"","sources":["../../src/shared/result-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,2DAA2D;AAC3D,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAK5C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,MAA8B,GACvC,MAAM,CAgBR"}

package/dist/shared/result-utils.js

@@ -0,0 +1,41 @@
+/**
+ * MCP tool result size utilities.
+ *
+ * Prevents silent schema truncation at the MCP transport layer by:
+ * - Annotating large results with their size (chars + lines)
+ * - Truncating results that exceed the limit with an explicit marker
+ *   so the caller knows to refine their query rather than acting on
+ *   incomplete data.
+ */
+/** Maximum characters returned in a single tool result. */
+export const MAX_TOOL_RESULT_CHARS = 50_000;
+/** Minimum size (chars) before a size annotation is appended. */
+const SIZE_ANNOTATION_THRESHOLD = 1_000;
+/**
+ * Annotate a tool result text with its size and truncate if necessary.
+ *
+ * - Under `maxChars` and over `SIZE_ANNOTATION_THRESHOLD`: appends a compact
+ *   footer showing char/line count.
+ * - Over `maxChars`: truncates to `maxChars` and appends a `[TRUNCATED]`
+ *   footer so the caller knows the response is incomplete.
+ * - Under `SIZE_ANNOTATION_THRESHOLD`: returned as-is (no footer noise for
+ *   short replies like "No violations recorded.").
+ *
+ * @param text - Raw tool result text
+ * @param maxChars - Truncation limit (default: MAX_TOOL_RESULT_CHARS)
+ * @returns Annotated (and possibly truncated) text
+ */
+export function annotateResult(text, maxChars = MAX_TOOL_RESULT_CHARS) {
+    const total = text.length;
+    if (total <= SIZE_ANNOTATION_THRESHOLD)
+        return text;
+    if (total <= maxChars) {
+        const lines = text.split("\n").length;
+        return `${text}\n\n---\n_↩ ${total.toLocaleString()} chars · ${lines.toLocaleString()} lines_`;
+    }
+    const truncated = text.slice(0, maxChars);
+    return (`${truncated}\n\n---\n` +
+        `_[TRUNCATED: showing first ${maxChars.toLocaleString()} of ${total.toLocaleString()} chars — ` +
+        `use a more specific query or smaller scope to see the rest]_`);
+}
+//# sourceMappingURL=result-utils.js.map

package/dist/shared/result-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-utils.js","sourceRoot":"","sources":["../../src/shared/result-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,2DAA2D;AAC3D,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAE5C,iEAAiE;AACjE,MAAM,yBAAyB,GAAG,KAAK,CAAC;AAExC;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAY,EACZ,WAAmB,qBAAqB;IAExC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC;IAE1B,IAAI,KAAK,IAAI,yBAAyB;QAAE,OAAO,IAAI,CAAC;IAEpD,IAAI,KAAK,IAAI,QAAQ,EAAE,CAAC;QACtB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;QACtC,OAAO,GAAG,IAAI,eAAe,KAAK,CAAC,cAAc,EAAE,YAAY,KAAK,CAAC,cAAc,EAAE,SAAS,CAAC;IACjG,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC1C,OAAO,CACL,GAAG,SAAS,WAAW;QACvB,8BAA8B,QAAQ,CAAC,cAAc,EAAE,OAAO,KAAK,CAAC,cAAc,EAAE,WAAW;QAC/F,8DAA8D,CAC/D,CAAC;AACJ,CAAC"}

package/dist/tools/add-module.js

@@ -60,97 +60,97 @@ function generateTypeScriptModule(moduleDir, moduleName, className, tags) {
     const files = [];
     const relBase = `src/modules/${moduleName}`;
     // Types
-    const typesContent = `/**
- * ${className} module types.
- */
-
-export interface ${className} {
-  readonly id: string;
-  // TODO: Define ${className} properties
-}
-
-export interface Create${className}Input {
-  // TODO: Define creation input
-}
-
-export interface Update${className}Input {
-  readonly id: string;
-  // TODO: Define update input
-}
+    const typesContent = `/**
+ * ${className} module types.
+ */
+
+export interface ${className} {
+  readonly id: string;
+  // TODO: Define ${className} properties
+}
+
+export interface Create${className}Input {
+  // TODO: Define creation input
+}
+
+export interface Update${className}Input {
+  readonly id: string;
+  // TODO: Define update input
+}
 `;
     writeFileSync(join(moduleDir, "types.ts"), typesContent);
     files.push(`${relBase}/types.ts`);
     // Interface
-    const interfaceContent = `/**
- * ${className} service interface.
- *
- * Defines the contract — implementations are swappable.
- */
-
-import type { ${className}, Create${className}Input, Update${className}Input } from "./types.js";
-
-export interface I${className}Service {
-  create(input: Create${className}Input): Promise<${className}>;
-  findById(id: string): Promise<${className} | null>;
-  update(input: Update${className}Input): Promise<${className}>;
-  delete(id: string): Promise<void>;
-}
+    const interfaceContent = `/**
+ * ${className} service interface.
+ *
+ * Defines the contract — implementations are swappable.
+ */
+
+import type { ${className}, Create${className}Input, Update${className}Input } from "./types.js";
+
+export interface I${className}Service {
+  create(input: Create${className}Input): Promise<${className}>;
+  findById(id: string): Promise<${className} | null>;
+  update(input: Update${className}Input): Promise<${className}>;
+  delete(id: string): Promise<void>;
+}
 `;
     writeFileSync(join(moduleDir, "interface.ts"), interfaceContent);
     files.push(`${relBase}/interface.ts`);
     // Service implementation
-    const serviceContent = `/**
- * ${className} service implementation.
- */
-
-import type { ${className}, Create${className}Input, Update${className}Input } from "./types.js";
-import type { I${className}Service } from "./interface.js";
-
-export class ${className}Service implements I${className}Service {
-  async create(input: Create${className}Input): Promise<${className}> {
-    // TODO: Implement creation logic
-    throw new Error("Not implemented");
-  }
-
-  async findById(id: string): Promise<${className} | null> {
-    // TODO: Implement find logic
-    throw new Error("Not implemented");
-  }
-
-  async update(input: Update${className}Input): Promise<${className}> {
-    // TODO: Implement update logic
-    throw new Error("Not implemented");
-  }
-
-  async delete(id: string): Promise<void> {
-    // TODO: Implement delete logic
-    throw new Error("Not implemented");
-  }
-}
+    const serviceContent = `/**
+ * ${className} service implementation.
+ */
+
+import type { ${className}, Create${className}Input, Update${className}Input } from "./types.js";
+import type { I${className}Service } from "./interface.js";
+
+export class ${className}Service implements I${className}Service {
+  async create(input: Create${className}Input): Promise<${className}> {
+    // TODO: Implement creation logic
+    throw new Error("Not implemented");
+  }
+
+  async findById(id: string): Promise<${className} | null> {
+    // TODO: Implement find logic
+    throw new Error("Not implemented");
+  }
+
+  async update(input: Update${className}Input): Promise<${className}> {
+    // TODO: Implement update logic
+    throw new Error("Not implemented");
+  }
+
+  async delete(id: string): Promise<void> {
+    // TODO: Implement delete logic
+    throw new Error("Not implemented");
+  }
+}
 `;
     writeFileSync(join(moduleDir, "service.ts"), serviceContent);
     files.push(`${relBase}/service.ts`);
     // Index barrel
-    const indexContent = `export type { ${className}, Create${className}Input, Update${className}Input } from "./types.js";
-export type { I${className}Service } from "./interface.js";
-export { ${className}Service } from "./service.js";
+    const indexContent = `export type { ${className}, Create${className}Input, Update${className}Input } from "./types.js";
+export type { I${className}Service } from "./interface.js";
+export { ${className}Service } from "./service.js";
 `;
     writeFileSync(join(moduleDir, "index.ts"), indexContent);
     files.push(`${relBase}/index.ts`);
     // API routes if API tag present
     if (tags.includes("API")) {
-        const routesContent = `/**
- * ${className} API routes.
- */
-
-// TODO: Register routes with your HTTP framework
-// Example:
-// router.post("/${moduleName}", create${className}Handler);
-// router.get("/${moduleName}/:id", get${className}Handler);
-// router.put("/${moduleName}/:id", update${className}Handler);
-// router.delete("/${moduleName}/:id", delete${className}Handler);
-
-export {};
+        const routesContent = `/**
+ * ${className} API routes.
+ */
+
+// TODO: Register routes with your HTTP framework
+// Example:
+// router.post("/${moduleName}", create${className}Handler);
+// router.get("/${moduleName}/:id", get${className}Handler);
+// router.put("/${moduleName}/:id", update${className}Handler);
+// router.delete("/${moduleName}/:id", delete${className}Handler);
+
+export {};
 `;
         writeFileSync(join(moduleDir, "routes.ts"), routesContent);
         files.push(`${relBase}/routes.ts`);
@@ -158,17 +158,17 @@ export {};
     // Test file
     const testDir = join(moduleDir, "__tests__");
     mkdirSync(testDir, { recursive: true });
-    const testContent = `import { describe, it, expect } from "vitest";
-import { ${className}Service } from "../service.js";
-
-describe("${className}Service", () => {
-  it("should be defined", () => {
-    const service = new ${className}Service();
-    expect(service).toBeDefined();
-  });
-
-  // TODO: Add comprehensive tests
-});
+    const testContent = `import { describe, it, expect } from "vitest";
+import { ${className}Service } from "../service.js";
+
+describe("${className}Service", () => {
+  it("should be defined", () => {
+    const service = new ${className}Service();
+    expect(service).toBeDefined();
+  });
+
+  // TODO: Add comprehensive tests
+});
 `;
     writeFileSync(join(testDir, `${moduleName}.test.ts`), testContent);
     files.push(`${relBase}/__tests__/${moduleName}.test.ts`);
@@ -185,48 +185,48 @@ function generatePythonModule(moduleDir, moduleName, className, _tags) {
     writeFileSync(join(moduleDir, "__init__.py"), `"""${className} module."""\n`);
     files.push(`${relBase}/__init__.py`);
     // models.py
-    const modelsContent = `"""${className} data models."""
-
-from dataclasses import dataclass
-
-
-@dataclass
-class ${className}:
-    id: str
-    # TODO: Define ${className} fields
-
-
-@dataclass
-class Create${className}Input:
-    # TODO: Define creation input
-    pass
-
-
-@dataclass
-class Update${className}Input:
-    id: str
-    # TODO: Define update input
+    const modelsContent = `"""${className} data models."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class ${className}:
+    id: str
+    # TODO: Define ${className} fields
+
+
+@dataclass
+class Create${className}Input:
+    # TODO: Define creation input
+    pass
+
+
+@dataclass
+class Update${className}Input:
+    id: str
+    # TODO: Define update input
 `;
     writeFileSync(join(moduleDir, "models.py"), modelsContent);
     files.push(`${relBase}/models.py`);
     // service.py
-    const serviceContent = `"""${className} service."""
-
-from .models import ${className}, Create${className}Input, Update${className}Input
-
-
-class ${className}Service:
-    async def create(self, input: Create${className}Input) -> ${className}:
-        raise NotImplementedError
-
-    async def find_by_id(self, id: str) -> ${className} | None:
-        raise NotImplementedError
-
-    async def update(self, input: Update${className}Input) -> ${className}:
-        raise NotImplementedError
-
-    async def delete(self, id: str) -> None:
-        raise NotImplementedError
+    const serviceContent = `"""${className} service."""
+
+from .models import ${className}, Create${className}Input, Update${className}Input
+
+
+class ${className}Service:
+    async def create(self, input: Create${className}Input) -> ${className}:
+        raise NotImplementedError
+
+    async def find_by_id(self, id: str) -> ${className} | None:
+        raise NotImplementedError
+
+    async def update(self, input: Update${className}Input) -> ${className}:
+        raise NotImplementedError
+
+    async def delete(self, id: str) -> None:
+        raise NotImplementedError
 `;
     writeFileSync(join(moduleDir, "service.py"), serviceContent);
     files.push(`${relBase}/service.py`);

package/dist/tools/advice-registry.js

@@ -189,24 +189,24 @@ export function smokeConfigExample(tags) {
     if (hasApi) {
         projects.push("    // API smoke uses APIRequestContext — no browser project needed");
     }
-    return `
-## Example: playwright.smoke.config.ts
-
-\`\`\`typescript
-import { defineConfig${hasBrowser ? ", devices" : ""} } from '@playwright/test';
-
-export default defineConfig({
-  testMatch: '**/*.smoke.ts',
-  retries: 1,          // one retry — smoke fail = broken deploy
-  timeout: 15_000,
-  use: {
-    baseURL: process.env['PLAYWRIGHT_BASE_URL'] ?? 'http://localhost:3000',
-    // Never run smoke against localhost in CI — use staging URL
-  },${hasBrowser ? `\n  projects: [\n${projects.join(",\n")}\n  ],` : ""}
-});
-\`\`\`
-
-Run with: \`npx playwright test --config playwright.smoke.config.ts\`
+    return `
+## Example: playwright.smoke.config.ts
+
+\`\`\`typescript
+import { defineConfig${hasBrowser ? ", devices" : ""} } from '@playwright/test';
+
+export default defineConfig({
+  testMatch: '**/*.smoke.ts',
+  retries: 1,          // one retry — smoke fail = broken deploy
+  timeout: 15_000,
+  use: {
+    baseURL: process.env['PLAYWRIGHT_BASE_URL'] ?? 'http://localhost:3000',
+    // Never run smoke against localhost in CI — use staging URL
+  },${hasBrowser ? `\n  projects: [\n${projects.join(",\n")}\n  ],` : ""}
+});
+\`\`\`
+
+Run with: \`npx playwright test --config playwright.smoke.config.ts\`
 `;
 }
 //# sourceMappingURL=advice-registry.js.map