@amrishkhan05/frankly 0.1.0

package/src/integrations/cli/index.ts

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+
+/**
+ * Frankly CLI
+ * Command-line interface for Frankly analysis
+ */
+
+import { createAnalysisEngine } from "../../core/engine.js";
+import { createReportFormatter } from "../../report/json.js";
+import type { FranklyConfig } from "../../core/config.js";
+import type { ExecutedTest } from "../../core/models.js";
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+async function main(): Promise<void> {
+    const args = process.argv.slice(2);
+
+    if (args.length === 0 || args[0] === "help") {
+        printHelp();
+        return;
+    }
+
+    const command = args[0];
+    const cwd = process.cwd();
+
+    try {
+        switch (command) {
+            case "review": {
+                await handleReview(args.slice(1), cwd);
+                break;
+            }
+
+            case "plan": {
+                await handlePlan(args.slice(1), cwd);
+                break;
+            }
+
+            case "verify": {
+                await handleVerify(args.slice(1), cwd);
+                break;
+            }
+
+            case "mcp": {
+                const { startMcpServer } = await import("../mcp/server.js");
+                console.log("Starting MCP server...");
+                await startMcpServer(cwd);
+                break;
+            }
+
+            case "config": {
+                await handleConfig(args.slice(1), cwd);
+                break;
+            }
+
+            default:
+                console.error(`Unknown command: ${command}`);
+                printHelp();
+                process.exit(1);
+        }
+    } catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+}
+
+async function handleReview(args: string[], cwd: string): Promise<void> {
+    let task = "Review current changes";
+
+    // Parse arguments
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--task" && args[i + 1]) {
+            task = args[++i];
+        }
+    }
+
+  const engine = await createAnalysisEngine(cwd);
+  const result = await engine.analyze(task, reviewOverrides(args), args.includes("--run-tests") ? runTests(cwd) : []);
+
+  const formatter = createReportFormatter();
+  console.log(args.includes("--json") ? formatter.formatAsJson(result) : args.includes("--markdown") ? formatter.formatAsMarkdown(result) : args.includes("--ci") ? formatter.formatAsCi(result) : formatter.formatAsTerminal(result));
+
+  if (args.includes("--ci") && result.review.verdict !== "CLEAN") {
+        process.exit(1);
+    }
+}
+
+async function handlePlan(args: string[], cwd: string): Promise<void> {
+    let task = "Plan changes";
+
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--task" && args[i + 1]) {
+            task = args[++i];
+        }
+    }
+
+    const engine = await createAnalysisEngine(cwd);
+    const plan = await engine.plan(task);
+
+    console.log(`FRANKLY · PLAN
+
+Task: ${task}
+Normalized intent: ${plan.normalizedIntent}
+Keywords: ${plan.keywords.join(", ") || "none"}
+Estimated files: ${plan.estimatedFiles}
+Likely touched areas: ${plan.likelyTouchedAreas.length > 0 ? plan.likelyTouchedAreas.join(", ") : "none"}
+Reuse candidates: ${plan.reuseCandidates.join(", ") || "none"}
+Confidence: ${plan.confidence}
+
+Concerns:
+${plan.concerns.length > 0 ? plan.concerns.map((item) => `- ${item}`).join("\n") : "- none"}
+  `);
+}
+
+async function handleVerify(args: string[], cwd: string): Promise<void> {
+    let task = "Verify changes";
+
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--task" && args[i + 1]) {
+            task = args[++i];
+        }
+    }
+
+  const engine = await createAnalysisEngine(cwd);
+  const result = await engine.analyze(task, reviewOverrides(args), args.includes("--run-tests") ? runTests(cwd) : []);
+
+    const formatter = createReportFormatter();
+
+    if (result.review.verdict === "CLEAN") {
+        console.log("✓ Verification passed");
+        console.log(formatter.formatAsSummary(result));
+    } else {
+        console.log("✗ Verification failed");
+        console.log(formatter.formatAsTerminal(result));
+        process.exit(1);
+    }
+}
+
+function runTests(cwd: string): ExecutedTest[] {
+  const command = fs.existsSync(path.join(cwd, "pnpm-lock.yaml")) ? "pnpm" : fs.existsSync(path.join(cwd, "yarn.lock")) ? "yarn" : "npm";
+  const args = ["test"];
+  const started = Date.now();
+  const result = spawnSync(command, args, { cwd, encoding: "utf8", stdio: "inherit" });
+  return [{ path: cwd, name: "project test command", status: result.status === 0 ? "PASSED" : "FAILED", duration: Date.now() - started }];
+}
+
+function reviewOverrides(args: string[]): Partial<FranklyConfig> {
+  const intensity = args[args.indexOf("--intensity") + 1] as FranklyConfig["intensity"] | undefined;
+  const personality = args[args.indexOf("--personality") + 1] as FranklyConfig["personality"] | undefined;
+  return {
+    ...(args.includes("--intensity") && intensity ? { intensity } : {}),
+    ...(args.includes("--personality") && personality ? { personality } : {}),
+  };
+}
+
+async function handleConfig(args: string[], cwd: string): Promise<void> {
+    if (args.length === 0 || args[0] === "show") {
+        console.log(`Frankly configuration for ${cwd}`);
+        console.log(
+            `
+Default configuration:
+  trigger: checkpoint
+  action: correct
+  intensity: full
+  personality: senior
+  maxCorrectionPasses: 1
+
+Configuration file: frankly.config.json
+      `,
+        );
+    } else {
+        console.error("Unknown config subcommand");
+    }
+}
+
+function printHelp(): void {
+    console.log(`
+Frankly - Change Intelligence for AI Coding Agents
+
+Usage:
+  frankly <command> [options]
+
+Commands:
+  review              Analyze current changes and produce Red Ink Review
+  plan                Plan a change and estimate scope
+  verify              Verify that a change is complete and correct
+  mcp                 Start MCP server for agent integration
+  config              Show or manage configuration
+  help                Show this help message
+
+Options:
+  --task <text>       Task description
+  --intensity <level> Analysis intensity: lite, full, ultra, off
+  --personality       Review personality: conservative, senior, witty
+  --run-tests         Execute the repository test script and record the result
+  --json|--markdown   Select an output format
+  --ci                Emit compact CI JSON and fail on non-clean verdict
+
+Examples:
+  frankly review --task "Fix HTTP 429 retry"
+  frankly verify --task "Add retry logic"
+  frankly mcp
+
+Documentation: https://github.com/amrishkhan05/frankly
+  `);
+}
+
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/src/integrations/mcp/index.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { startMcpServer } from "./server.js";
+
+startMcpServer().catch((error) => {
+  console.error("Frankly MCP server failed:", error);
+  process.exit(1);
+});

package/src/integrations/mcp/server.ts

@@ -0,0 +1,257 @@
+/**
+ * MCP (Model Context Protocol) Server
+ * Exposes Frankly analysis to coding agents
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { createAnalysisEngine } from "../../core/engine.js";
+import type { FranklyConfig } from "../../core/config.js";
+import { createReportFormatter } from "../../report/json.js";
+
+const AnalyzeChangeSchema = z.object({
+    task: z.string().describe("The task or change description"),
+    repositoryRoot: z.string().optional().describe("Path to repository root"),
+    intensity: z.enum(["lite", "full", "ultra", "off"]).optional(),
+  personality: z.enum(["conservative", "senior", "witty"]).optional(),
+  executedTests: z.array(z.object({
+    path: z.string(),
+    name: z.string(),
+    status: z.enum(["PASSED", "FAILED", "SKIPPED", "NOT_RUN"]),
+    duration: z.number().optional(),
+  })).optional(),
+});
+
+const PlanChangeSchema = z.object({
+    task: z.string().describe("The planned task"),
+    repositoryRoot: z.string().optional().describe("Path to repository root"),
+});
+
+const VerifyChangeSchema = z.object({
+    task: z.string().describe("The task that was completed"),
+  repositoryRoot: z.string().optional().describe("Path to repository root"),
+  executedTests: AnalyzeChangeSchema.shape.executedTests,
+});
+
+const MinimizeChangeSchema = z.object({
+  task: z.string(),
+  repositoryRoot: z.string().optional(),
+});
+
+export class FranklyMcpServer {
+  private server: Server;
+
+    constructor(private repositoryRoot: string = process.cwd()) {
+    this.server = new Server(
+      { name: "frankly", version: "0.1.0" },
+      { capabilities: { tools: {} } },
+    );
+
+        this.setupHandlers();
+    }
+
+    private setupHandlers(): void {
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+            return {
+                tools: [
+                    {
+                        name: "analyze_change",
+                        description:
+                            "Analyze a code change and provide Red Ink Review with findings and recommendations",
+                        inputSchema: {
+                            type: "object" as const,
+                            properties: {
+                                task: {
+                                    type: "string",
+                                    description: "The task or change description",
+                                },
+                                repositoryRoot: {
+                                    type: "string",
+                                    description: "Path to repository root (optional, uses current working directory)",
+                                },
+                                intensity: {
+                                    type: "string",
+                                    enum: ["lite", "full", "ultra", "off"],
+                                    description: "Analysis intensity level",
+                                },
+                personality: {
+                                    type: "string",
+                                    enum: ["conservative", "senior", "witty"],
+                  description: "Review personality style",
+                },
+                executedTests: {
+                  type: "array",
+                  description: "Tests actually run by the caller; never use this for predictions",
+                  items: {
+                    type: "object",
+                    properties: {
+                      path: { type: "string" },
+                      name: { type: "string" },
+                      status: { type: "string", enum: ["PASSED", "FAILED", "SKIPPED", "NOT_RUN"] },
+                      duration: { type: "number" },
+                    },
+                    required: ["path", "name", "status"],
+                  },
+                },
+                            },
+                            required: ["task"],
+                        },
+                    },
+                    {
+                        name: "plan_change",
+                        description:
+                            "Plan a change and get expected scope, budget, and potential issues before implementation",
+                        inputSchema: {
+                            type: "object" as const,
+                            properties: {
+                                task: {
+                                    type: "string",
+                                    description: "The planned task",
+                                },
+                                repositoryRoot: {
+                                    type: "string",
+                                    description: "Path to repository root (optional)",
+                                },
+                            },
+                            required: ["task"],
+                        },
+                    },
+          {
+            name: "minimize_change",
+            description: "Return one constrained correction pass backed by the current analysis",
+            inputSchema: {
+              type: "object" as const,
+              properties: {
+                task: { type: "string", description: "The task or change description" },
+                repositoryRoot: { type: "string", description: "Path to repository root (optional)" },
+              },
+              required: ["task"],
+            },
+          },
+          {
+            name: "verify_change",
+                        description:
+                            "Verify that a completed change correctly addresses the task with no excess modifications",
+                        inputSchema: {
+                            type: "object" as const,
+                            properties: {
+                                task: {
+                                    type: "string",
+                                    description: "The task that was completed",
+                                },
+                                repositoryRoot: {
+                                    type: "string",
+                                    description: "Path to repository root (optional)",
+                                },
+                            },
+                            required: ["task"],
+                        },
+                    },
+                ],
+            };
+        });
+
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const { params } = request;
+            const name = params.name;
+            const args = params.arguments || {};
+
+            try {
+                const result = await this.handleToolCall(name, args);
+                return {
+                    content: [
+                        {
+                            type: "text" as const,
+                            text: result,
+                        },
+                    ],
+                };
+            } catch (error) {
+                return {
+                    content: [
+                        {
+                            type: "text" as const,
+                            text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        });
+    }
+
+    private async handleToolCall(name: string, args: unknown): Promise<string> {
+        switch (name) {
+            case "analyze_change": {
+                const parsed = AnalyzeChangeSchema.parse(args);
+                const repo = parsed.repositoryRoot || this.repositoryRoot;
+                const engine = await createAnalysisEngine(repo);
+
+                const configOverrides: Partial<FranklyConfig> = {};
+                if (parsed.intensity) configOverrides.intensity = parsed.intensity;
+                if (parsed.personality) configOverrides.personality = parsed.personality;
+
+        const result = await engine.analyze(parsed.task, configOverrides, parsed.executedTests);
+                const formatter = createReportFormatter();
+
+                return formatter.formatAsTerminal(result);
+            }
+
+            case "plan_change": {
+                const parsed = PlanChangeSchema.parse(args);
+                const repo = parsed.repositoryRoot || this.repositoryRoot;
+                const engine = await createAnalysisEngine(repo);
+                const plan = await engine.plan(parsed.task);
+
+                return `FRANKLY · PLAN CHANGE
+
+Task: ${parsed.task}
+Normalized intent: ${plan.normalizedIntent}
+Keywords: ${plan.keywords.join(", ") || "none"}
+Estimated files: ${plan.estimatedFiles}
+Likely touched areas: ${plan.likelyTouchedAreas.join(", ") || "none"}
+Reuse candidates: ${plan.reuseCandidates.join(", ") || "none"}
+Confidence: ${plan.confidence}
+
+Concerns:
+${plan.concerns.length > 0 ? plan.concerns.map((item) => `- ${item}`).join("\n") : "- none"}`;
+            }
+
+      case "verify_change": {
+                const parsed = VerifyChangeSchema.parse(args);
+                const repo = parsed.repositoryRoot || this.repositoryRoot;
+                const engine = await createAnalysisEngine(repo);
+        const result = await engine.analyze(parsed.task, { action: "observe" }, parsed.executedTests);
+
+                if (result.review.verdict === "CLEAN") {
+                    return "✓ Change verified successfully";
+                } else {
+                    return `⚠ Verification found issues:\n${result.review.recommendation}`;
+                }
+            }
+
+            case "minimize_change": {
+                const parsed = MinimizeChangeSchema.parse(args);
+                const engine = await createAnalysisEngine(parsed.repositoryRoot || this.repositoryRoot);
+                const result = await engine.analyze(parsed.task, { action: "correct" });
+                return result.review.correction?.instruction || "No correction pass is warranted by the current evidence.";
+            }
+
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+
+    async start(): Promise<void> {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        console.error("Frankly MCP Server started");
+    }
+}
+
+export async function startMcpServer(repositoryRoot?: string): Promise<void> {
+    const server = new FranklyMcpServer(repositoryRoot);
+    await server.start();
+}