forgetrail 0.3.0

package/scripts/mcp-lib.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+export const FORGETRAIL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+export const MCP_SERVER_DIR = join(FORGETRAIL_ROOT, "mcp-server");
+export const MCP_ENTRY = join(MCP_SERVER_DIR, "dist", "index.js");
+export const WORKFLOW_PATH = join(FORGETRAIL_ROOT, "WORKFLOW.md");
+
+export function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+export function normalizePath(p) {
+  if (!p || typeof p !== "string") return "";
+  return resolve(p.replace(/\//g, "\\").replace(/\\/g, "/").replace(/^([A-Za-z]):/, (_, d) => `${d.toUpperCase()}:`));
+}
+
+/** Find .cursor/mcp.json starting at dir, walking up to root. */
+export function findCursorMcpJson(startDir = process.cwd()) {
+  let dir = resolve(startDir);
+  for (;;) {
+    const candidate = join(dir, ".cursor", "mcp.json");
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return join(FORGETRAIL_ROOT, ".cursor", "mcp.json");
+}
+
+export function analyzeCursorMcpConfig(mcpJsonPath) {
+  const issues = [];
+  const notes = [];
+  if (!existsSync(mcpJsonPath)) {
+    return {
+      path: mcpJsonPath,
+      found: false,
+      issues: ["No .cursor/mcp.json found (checked cwd ancestors and forgetrail root)."],
+      notes: [
+        "Create .cursor/mcp.json with a forgetrail server entry pointing at mcp-server/dist/index.js.",
+        "See mcp-server/README.md or run: forgetrail mcp cursor-config",
+      ],
+    };
+  }
+
+  const raw = readJson(mcpJsonPath);
+  if (!raw?.mcpServers) {
+    return { path: mcpJsonPath, found: true, issues: ["Invalid mcp.json: missing mcpServers."], notes: [] };
+  }
+
+  const forgetrail =
+    raw.mcpServers.forgetrail ??
+    raw.mcpServers["forgetrail-mcp"] ??
+    Object.entries(raw.mcpServers).find(([k]) => /forgetrail/i.test(k))?.[1];
+
+  if (!forgetrail) {
+    issues.push('No "forgetrail" entry under mcpServers.');
+    notes.push('Add a server named "forgetrail" (Cursor shows this name in MCP settings).');
+    return { path: mcpJsonPath, found: true, issues, notes, config: raw };
+  }
+
+  const args = forgetrail.args ?? [];
+  const entryArg = args.find((a) => typeof a === "string" && a.endsWith("index.js"));
+  if (!entryArg) {
+    issues.push("forgetrail MCP args should include mcp-server/dist/index.js");
+  } else if (!existsSync(entryArg)) {
+    issues.push(`Configured server path does not exist: ${entryArg}`);
+    notes.push("Run: forgetrail mcp build");
+  } else if (normalizePath(entryArg) !== normalizePath(MCP_ENTRY)) {
+    notes.push(`Configured entry: ${entryArg}`);
+    notes.push(`This repo build:   ${MCP_ENTRY}`);
+  }
+
+  if (forgetrail.command && forgetrail.command !== "node") {
+    notes.push(`command is "${forgetrail.command}" (node is typical).`);
+  }
+
+  const envRoot = forgetrail.env?.FORGETRAIL_ROOT;
+  if (envRoot && normalizePath(envRoot) !== normalizePath(FORGETRAIL_ROOT)) {
+    notes.push(`FORGETRAIL_ROOT in mcp.json: ${envRoot}`);
+  } else if (!envRoot) {
+    notes.push(
+      "Optional: set env.FORGETRAIL_ROOT in mcp.json if the server lives outside the default parent-of-mcp-server layout."
+    );
+  }
+
+  return { path: mcpJsonPath, found: true, issues, notes, config: raw, entryArg };
+}
+
+export function staticMcpChecks() {
+  const issues = [];
+  const notes = [];
+
+  if (!existsSync(WORKFLOW_PATH)) {
+    issues.push(`WORKFLOW.md missing at ${WORKFLOW_PATH}`);
+  }
+
+  if (!existsSync(join(MCP_SERVER_DIR, "node_modules"))) {
+    issues.push("mcp-server/node_modules missing — run: forgetrail mcp build");
+  }
+
+  if (!existsSync(MCP_ENTRY)) {
+    issues.push("mcp-server/dist/index.js missing — run: forgetrail mcp build");
+  }
+
+  const pkg = readJson(join(MCP_SERVER_DIR, "package.json"));
+  if (pkg?.version) {
+    notes.push(`forgetrail-mcp package version: ${pkg.version}`);
+  }
+
+  notes.push(`FORGETRAIL_ROOT (default): ${FORGETRAIL_ROOT}`);
+
+  return { issues, notes };
+}
+
+export function posixPath(p) {
+  return p.replace(/\\/g, "/");
+}
+
+export function mcpClientConfigObject() {
+  return {
+    mcpServers: {
+      forgetrail: {
+        command: "node",
+        args: [posixPath(MCP_ENTRY)],
+        env: { FORGETRAIL_ROOT: posixPath(FORGETRAIL_ROOT) },
+      },
+    },
+  };
+}
+
+/** Copy-paste MCP client setup — shown after `forgetrail mcp build`. */
+export function printMcpClientSetupBanner({ showBuildComplete = true } = {}) {
+  const entry = posixPath(MCP_ENTRY);
+
+  if (showBuildComplete) {
+    console.log("\n✓ Build complete.\n");
+  }
+
+  console.log("Connect ForgeTrail MCP (Cursor starts the server for you — no `mcp dev` needed):\n");
+  console.log("  Cursor — project .cursor/mcp.json or Settings → MCP → add server:");
+  console.log(JSON.stringify(mcpClientConfigObject(), null, 2));
+  console.log("");
+  console.log("  Claude Desktop — %APPDATA%\\Claude\\claude_desktop_config.json (same mcpServers block)");
+  console.log(`  Claude Code — claude mcp add forgetrail node ${entry}`);
+  console.log("");
+  console.log("  Then reload MCP in Cursor (Settings → MCP) or restart Cursor.");
+  console.log("  Verify: forgetrail mcp ping   |   Reprint: forgetrail mcp cursor-config");
+  console.log("");
+  console.log('  First agent prompt: "Call ForgeTrail getNewProjectKickoff and set up the project."');
+  console.log("");
+}
+
+export function runMcpBuild() {
+  console.log("Building ForgeTrail MCP server...\n");
+  const install = spawnSync("pnpm", ["install"], { cwd: MCP_SERVER_DIR, stdio: "inherit", shell: true });
+  if (install.status !== 0) {
+    process.exit(install.status ?? 1);
+  }
+  const build = spawnSync("pnpm", ["run", "build"], { cwd: MCP_SERVER_DIR, stdio: "inherit", shell: true });
+  if (build.status !== 0) {
+    process.exit(build.status ?? 1);
+  }
+  printMcpClientSetupBanner();
+}
+
+export function printCursorConfigTemplate() {
+  printMcpClientSetupBanner({ showBuildComplete: false });
+}

package/scripts/mcp-status.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  MCP_SERVER_DIR,
+  analyzeCursorMcpConfig,
+  findCursorMcpJson,
+  staticMcpChecks,
+  printCursorConfigTemplate,
+  runMcpBuild,
+} from "./mcp-lib.mjs";
+
+const HELP = `
+ForgeTrail MCP — build, status, and Cursor setup helpers
+
+Usage:
+  forgetrail mcp build              Install deps + compile mcp-server/dist/
+  forgetrail mcp status [--ping]    Static checks + optional live ping tool call
+  forgetrail mcp ping               Live ping only (JSON)
+  forgetrail mcp cursor-config      Print recommended .cursor/mcp.json
+  forgetrail mcp dev                Run server on stdio (blocks; for debugging)
+  forgetrail mcp inspector          Open MCP Inspector in browser
+
+Note: Cursor starts the MCP server itself. You usually do not run \`mcp dev\`
+for normal use — run \`mcp build\` once, then enable MCP in Cursor settings.
+`.trim();
+
+function runLivePing() {
+  const pingScript = join(MCP_SERVER_DIR, "scripts", "mcp-ping.mjs");
+  if (!existsSync(pingScript)) {
+    console.error("Missing mcp-server/scripts/mcp-ping.mjs");
+    process.exit(1);
+  }
+  const r = spawnSync(process.execPath, [pingScript], {
+    cwd: MCP_SERVER_DIR,
+    stdio: "inherit",
+    env: process.env,
+    shell: false,
+  });
+  process.exit(r.status ?? 1);
+}
+
+function runDev() {
+  console.log("Starting ForgeTrail MCP on stdio (Ctrl+C to stop)...\n");
+  const r = spawnSync("pnpm", ["run", "dev"], {
+    cwd: MCP_SERVER_DIR,
+    stdio: "inherit",
+    shell: true,
+  });
+  process.exit(r.status ?? 0);
+}
+
+function runInspector() {
+  if (!existsSync(join(MCP_SERVER_DIR, "dist", "index.js"))) {
+    console.error("Build first: forgetrail mcp build");
+    process.exit(1);
+  }
+  console.log("Opening MCP Inspector (browser)...\n");
+  const r = spawnSync(
+    "npx",
+    ["@modelcontextprotocol/inspector", "node", "dist/index.js"],
+    { cwd: MCP_SERVER_DIR, stdio: "inherit", shell: true }
+  );
+  process.exit(r.status ?? 0);
+}
+
+function runStatus({ withPing = false }) {
+  console.log("ForgeTrail MCP status\n");
+
+  const staticResult = staticMcpChecks();
+  console.log("## Server files");
+  if (staticResult.notes.length) {
+    for (const n of staticResult.notes) console.log(`  ${n}`);
+  }
+  if (staticResult.issues.length) {
+    for (const i of staticResult.issues) console.log(`  ✗ ${i}`);
+  } else {
+    console.log("  ✓ dist/build looks ready");
+  }
+
+  const mcpPath = findCursorMcpJson();
+  const cursor = analyzeCursorMcpConfig(mcpPath);
+  console.log("\n## Cursor MCP config");
+  console.log(`  Path: ${cursor.path}`);
+  if (cursor.found && cursor.issues.length === 0) {
+    console.log("  ✓ forgetrail server entry looks valid");
+  }
+  for (const i of cursor.issues) console.log(`  ✗ ${i}`);
+  for (const n of cursor.notes) console.log(`  · ${n}`);
+
+  console.log("\n## Cursor checklist");
+  console.log("  1. Settings → MCP → forgetrail should show connected (green).");
+  console.log("  2. In Agent chat, ask: Call ForgeTrail ping");
+  console.log("  3. If tools are missing, reload MCP or restart Cursor.");
+
+  const failed = staticResult.issues.length + cursor.issues.length;
+
+  if (withPing) {
+    console.log("\n## Live ping\n");
+    runLivePing();
+    return;
+  }
+
+  if (failed > 0) {
+    console.log("\nFix issues above, then: forgetrail mcp status --ping");
+    process.exit(1);
+  }
+
+  console.log("\nRun live JSON-RPC ping: forgetrail mcp ping");
+}
+
+export function runMcpCommand(argv) {
+  const cmd = argv[0];
+  const rest = argv.slice(1);
+
+  if (!cmd || cmd === "--help" || cmd === "-h") {
+    console.log(HELP);
+    return;
+  }
+
+  switch (cmd) {
+    case "build":
+      runMcpBuild();
+      break;
+    case "status":
+      runStatus({ withPing: rest.includes("--ping") });
+      break;
+    case "ping":
+      runLivePing();
+      break;
+    case "cursor-config":
+      printCursorConfigTemplate();
+      break;
+    case "dev":
+      runDev();
+      break;
+    case "inspector":
+      runInspector();
+      break;
+    default:
+      console.error(`Unknown mcp subcommand: ${cmd}`);
+      console.error("Run: forgetrail mcp --help");
+      process.exit(1);
+  }
+}
+
+const isMain =
+  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (isMain) {
+  runMcpCommand(process.argv.slice(2));
+}

package/scripts/publish-gate.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+
+/**
+ * Pre-publish checks. Does not log in or publish.
+ * Run from the repo root: pnpm run pack:check
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { FORGETRAIL_ROOT, MCP_ENTRY, MCP_SERVER_DIR } from "./mcp-lib.mjs";
+
+const ROOT_PKG = join(FORGETRAIL_ROOT, "package.json");
+const MCP_PKG = join(MCP_SERVER_DIR, "package.json");
+
+function fail(msg) {
+  console.error(`publish-gate: ${msg}`);
+  process.exit(1);
+}
+
+function readPkg(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    fail(`could not read ${path}`);
+  }
+}
+
+function requireFields(pkg, label, fields) {
+  for (const field of fields) {
+    if (!pkg[field]) fail(`${label} is missing "${field}"`);
+  }
+  if (pkg.private === true) fail(`${label} is private: true (unset it to publish)`);
+}
+
+function mustExist(path, label) {
+  if (!existsSync(path)) fail(`missing ${label}: ${path}`);
+}
+
+const root = readPkg(ROOT_PKG);
+const mcp = readPkg(MCP_PKG);
+
+requireFields(root, "forgetrail", [
+  "name",
+  "version",
+  "license",
+  "bin",
+  "files",
+  "repository",
+  "homepage",
+]);
+requireFields(mcp, "forgetrail-mcp", [
+  "name",
+  "version",
+  "license",
+  "bin",
+  "files",
+  "repository",
+]);
+
+if (root.name !== "forgetrail") fail(`root package name is "${root.name}", expected forgetrail`);
+if (mcp.name !== "forgetrail-mcp") fail(`mcp package name is "${mcp.name}", expected forgetrail-mcp`);
+
+mustExist(join(FORGETRAIL_ROOT, "LICENSE"), "LICENSE");
+mustExist(join(FORGETRAIL_ROOT, "README.md"), "README.md");
+mustExist(join(FORGETRAIL_ROOT, "WORKFLOW.md"), "WORKFLOW.md");
+mustExist(join(FORGETRAIL_ROOT, "content", "FORGETRAIL_LITE.md"), "Lite");
+mustExist(join(FORGETRAIL_ROOT, "scripts", "forgetrail-cli.mjs"), "CLI");
+
+const build = spawnSync("pnpm", ["run", "build"], {
+  cwd: MCP_SERVER_DIR,
+  stdio: "inherit",
+  shell: true,
+});
+if (build.status !== 0) fail("mcp-server build failed");
+mustExist(MCP_ENTRY, "mcp-server/dist/index.js");
+
+const pack = spawnSync("pnpm", ["pack", "--dry-run", "--json"], {
+  cwd: FORGETRAIL_ROOT,
+  encoding: "utf8",
+  shell: true,
+});
+if (pack.status !== 0) {
+  console.error(pack.stderr);
+  fail("pnpm pack --dry-run failed for forgetrail");
+}
+
+const packed = pack.stdout ?? "";
+const banned = ["site/", "specs/", ".cursor/", "mcp-server/src/", "mcp-server/node_modules/"];
+for (const needle of banned) {
+  if (packed.includes(needle)) fail(`tarball must not include ${needle}`);
+}
+for (const needed of ["WORKFLOW.md", "README.md", "LICENSE", "content/FORGETRAIL_LITE.md", "scripts/forgetrail-cli.mjs"]) {
+  if (!packed.includes(needed)) fail(`tarball is missing ${needed}`);
+}
+
+console.log("\n✓ forgetrail pack check passed");
+console.log(`  forgetrail@${root.version}`);
+console.log(`  forgetrail-mcp@${mcp.version} (build ok at ${MCP_ENTRY})`);
+console.log("\nPublish (you run these):");
+console.log("  pnpm publish --access public");
+console.log("  pnpm --dir mcp-server publish --access public");
+console.log("\nDry-run first if you want:");
+console.log("  pnpm publish --dry-run --access public");
+
+const here = fileURLToPath(import.meta.url);
+if (resolve(process.argv[1] ?? "") === resolve(here)) {
+  // ran as CLI; work already done above
+}