@selfagency/beans-mcp 0.1.0 → 0.1.1

package/dist/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@selfagency/beans-mcp",
+  "version": "0.1.1",
+  "description": "MCP (Model Context Protocol) server for Beans issue tracker",
+  "keywords": [
+    "beans",
+    "mcp",
+    "model-context-protocol",
+    "issue-tracker",
+    "ai"
+  ],
+  "homepage": "https://github.com/hmans/beans",
+  "bugs": {
+    "url": "https://github.com/selfagency/beans-mcp/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/selfagency/beans-mcp.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Daniel Sieradski",
+    "email": "daniel@self.agency",
+    "url": "https://self.agency"
+  },
+  "main": "./index.cjs",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "files": [
+    "./index.cjs",
+    "./index.js",
+    "./index.d.ts"
+  ],
+  "bin": {
+    "beans-mcp": "./beans-mcp-server.cjs"
+  },
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "require": "./index.cjs"
+    }
+  }
+}

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@selfagency/beans-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
+  "private": false,
   "description": "MCP (Model Context Protocol) server for Beans issue tracker",
-  "keywords": [
-    "beans",
-    "mcp",
-    "model-context-protocol",
-    "issue-tracker",
-    "ai"
-  ],
+  "author": {
+    "name": "Daniel Sieradski",
+    "email": "daniel@self.agency",
+    "url": "https://self.agency"
+  },
   "homepage": "https://github.com/hmans/beans",
   "bugs": {
     "url": "https://github.com/selfagency/beans-mcp/issues"
@@ -17,27 +16,65 @@
     "type": "git",
     "url": "https://github.com/selfagency/beans-mcp.git"
   },
-  "license": "MIT",
-  "author": {
-    "name": "Daniel Sieradski",
-    "email": "daniel@self.agency",
-    "url": "https://self.agency"
-  },
-  "main": "./index.cjs",
-  "module": "./index.js",
-  "types": "./index.d.ts",
-  "files": [
-    "./index.cjs",
-    "./index.js",
-    "./index.d.ts"
+  "keywords": [
+    "beans",
+    "mcp",
+    "model-context-protocol",
+    "issue-tracker",
+    "ai"
   ],
-  "bin": {
-    "beans-mcp": "./beans-mcp-server.cjs"
-  },
+  "license": "MIT",
+  "type": "module",
   "exports": {
     ".": {
-      "import": "./index.js",
-      "require": "./index.cjs"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
     }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "beans-mcp": "./dist/beans-mcp-server.cjs"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@octokit/rest": "^22.0.1",
+    "@types/node": "^20.19.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/ui": "4.0.18",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "ora": "^9.3.0",
+    "oxfmt": "^0.35.0",
+    "oxlint": "^1.50.0",
+    "oxlint-tsgolint": "^0.15.0",
+    "tsup": "8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "4.0.18",
+    "zod": "4.3.6",
+    "zx": "^8.8.5"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "lint-staged": {
+    "src/**/*.ts": [
+      "pnpm run lint:fix",
+      "pnpm run format"
+    ]
+  },
+  "scripts": {
+    "build": "tsup",
+    "format": "oxfmt",
+    "lint:fix": "oxlint --fix",
+    "lint": "oxlint",
+    "postbuild": "node ./scripts/write-dist-package.js",
+    "release": "zx ./scripts/release.js",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "test": "vitest run",
+    "type-check": "tsc --noEmit"
   }
-}
+}

package/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+onlyBuiltDependencies:
+  - esbuild

package/scripts/release.js

@@ -0,0 +1,433 @@
+#!/usr/bin/env zx
+
+import { Octokit } from '@octokit/rest';
+import { spawnSync } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import ora from 'ora';
+
+$.verbose = false;
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+cd(ROOT);
+
+// ---------------------------------------------------------------------------
+// Argument validation
+// ---------------------------------------------------------------------------
+
+const version = argv._[0];
+if (!version || !/^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/.test(version)) {
+  console.error('Usage: pnpm release <version>   (e.g. pnpm release 1.0.5)');
+  process.exit(1);
+}
+
+const tag = `v${version}`;
+
+// ---------------------------------------------------------------------------
+// Rollback state
+//   commitLocal  — release commit exists locally but has not been pushed
+//   commitPushed — release commit has been pushed to origin/main
+//   tagPushed    — tag has been pushed but release workflow has not yet succeeded
+//   releaseDone  — release workflow succeeded; nothing to undo
+// ---------------------------------------------------------------------------
+
+let commitLocal = false;
+let commitPushed = false;
+let tagPushed = false;
+let releaseDone = false;
+let gitCmd = 'git';
+
+function runGit(args, options = {}) {
+  const result = spawnSync(gitCmd, args, {
+    cwd: ROOT,
+    encoding: 'utf8',
+    shell: false,
+    ...options,
+  });
+
+  if (result.status !== 0) {
+    const stderr = (result.stderr || '').trim();
+    const stdout = (result.stdout || '').trim();
+    const details = stderr || stdout || `git ${args.join(' ')} failed with exit code ${result.status}`;
+    throw new Error(details);
+  }
+
+  return result;
+}
+
+function resolveGitExecutable() {
+  const direct = spawnSync('git', ['--version'], { stdio: 'ignore', shell: false });
+  if (direct.status === 0) {return 'git';}
+
+  const locatorCommand = process.platform === 'win32' ? 'where' : 'which';
+  const located = spawnSync(locatorCommand, ['git'], { encoding: 'utf8', shell: false });
+  if (located.status === 0) {
+    const candidate = located.stdout
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .find(Boolean);
+    if (candidate) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+async function rollback() {
+  if (releaseDone) {return;}
+  $.verbose = false;
+  try {
+    if (tagPushed) {
+      console.log(`\n⚠️  Release workflow failed or was interrupted. Deleting remote tag ${tag}...`);
+      try {
+        runGit(['push', 'origin', '--delete', tag]);
+        runGit(['tag', '-d', tag]);
+        console.log(`↩️  Tag ${tag} deleted from remote and local.`);
+      } catch {
+        console.error(`❌ Could not delete tag. Manually run:`);
+        console.error(`   git push origin --delete ${tag} && git tag -d ${tag}`);
+      }
+    }
+    if (commitPushed) {
+      console.log('\n⚠️  Reverting release commit on origin/main...');
+      try {
+        runGit(['revert', '--no-edit', 'HEAD']);
+        runGit(['push', 'origin', 'main']);
+        console.log('↩️  Release commit reverted and pushed. Working tree is clean.');
+      } catch {
+        console.error('❌ Automatic revert failed. Manually run:');
+        console.error('   git revert HEAD && git push origin main');
+      }
+    } else if (commitLocal) {
+      console.log('\n⚠️  Release aborted before push. Resetting local release commit...');
+      try {
+        runGit(['reset', '--hard', 'HEAD~1']);
+        console.log('↩️  Local release commit removed. Working tree restored.');
+      } catch {
+        console.error('❌ Reset failed. Manually run: git reset --hard HEAD~1');
+      }
+    }
+  } catch { /* best effort */ }
+}
+
+process.on('SIGINT', async () => { await rollback(); process.exit(130); });
+process.on('SIGTERM', async () => { await rollback(); process.exit(143); });
+
+// ---------------------------------------------------------------------------
+// Main — wrapped so any unhandled error triggers rollback
+// ---------------------------------------------------------------------------
+
+async function main() {
+  // --- Prerequisites -------------------------------------------------------
+
+  const resolvedGit = resolveGitExecutable();
+  if (!resolvedGit) {
+    console.error("❌ 'git' is required but not found in PATH.");
+    process.exit(1);
+  }
+  gitCmd = resolvedGit;
+
+  // Check npm credentials.
+  try {
+    await $`npm whoami`;
+  } catch {
+    console.error('❌ Not logged in to npm. Run: npm login');
+    process.exit(1);
+  }
+
+  // Resolve GitHub auth token: prefer env vars, then ask the gh CLI.
+  let githubToken = process.env.GH_TOKEN ?? process.env.GITHUB_TOKEN ?? '';
+  if (!githubToken) {
+    try {
+      githubToken = (await $`gh auth token`).stdout.trim();
+    } catch {
+      console.error('❌ No GitHub token found. Set GH_TOKEN/GITHUB_TOKEN or run: gh auth login');
+      process.exit(1);
+    }
+  }
+
+  const octokit = new Octokit({ auth: githubToken });
+
+  // --- Precondition checks --------------------------------------------------
+
+  const dirty = runGit(['status', '--porcelain']).stdout.trim();
+  if (dirty) {
+    console.error('❌ Working tree is not clean. Commit or stash changes first.');
+    process.exit(1);
+  }
+
+  const branch = runGit(['rev-parse', '--abbrev-ref', 'HEAD']).stdout.trim();
+  if (branch !== 'main') {
+    console.error(`❌ Must run from 'main'. Current branch: ${branch}`);
+    process.exit(1);
+  }
+
+  console.log('🔄 Fetching latest refs...');
+  runGit(['fetch', 'origin', 'main']);
+  runGit(['pull', '--ff-only', 'origin', 'main']);
+
+  // Derive owner/repo from the git remote URL.
+  const remoteUrl = runGit(['remote', 'get-url', 'origin']).stdout.trim();
+  const repoMatch = remoteUrl.match(/[:/]([^/]+)\/([^/.]+?)(\.git)?$/);
+  if (!repoMatch) {
+    console.error(`❌ Cannot parse owner/repo from remote URL: ${remoteUrl}`);
+    process.exit(1);
+  }
+  const [, owner, repo] = repoMatch;
+
+  // Check for existing local tag.
+  const localTag = runGit(['tag', '-l', tag]).stdout.trim();
+  if (localTag) {
+    console.error(`❌ Local tag ${tag} already exists.`);
+    process.exit(1);
+  }
+
+  // Check for existing remote tag via the API.
+  try {
+    await octokit.git.getRef({ owner, repo, ref: `tags/${tag}` });
+    console.error(`❌ Remote tag ${tag} already exists.`);
+    process.exit(1);
+  } catch (err) {
+    if (err.status !== 404) {
+      throw err;
+    }
+    // 404 = tag does not exist; that's what we want.
+  }
+
+  // --- Previous tag (for release notes diff) --------------------------------
+
+  const tagsResp = await octokit.paginate(octokit.git.listMatchingRefs, {
+    owner,
+    repo,
+    ref: 'tags/v',
+    per_page: 100,
+  });
+
+  const previousTag = tagsResp
+    .map((r) => r.ref.replace('refs/tags/', ''))
+    .filter((t) => t !== tag)
+    .sort((a, b) => {
+      const parse = (v) => v.replace(/^v/, '').split('.').map(Number);
+      const [aMaj, aMin, aPatch] = parse(a);
+      const [bMaj, bMin, bPatch] = parse(b);
+      return aMaj - bMaj || aMin - bMin || aPatch - bPatch;
+    })
+    .at(-1) ?? '';
+
+  // --- Release notes --------------------------------------------------------
+
+  console.log(`📝 Generating release notes for ${tag}...`);
+
+  const notesResp = await octokit.repos.generateReleaseNotes({
+    owner,
+    repo,
+    tag_name: tag,
+    target_commitish: 'main',
+    ...(previousTag ? { previous_tag_name: previousTag } : {}),
+  });
+  const releaseNotes = notesResp.data.body?.trim() || '- No notable changes.';
+
+  // --- Update package.json --------------------------------------------------
+
+  console.log(`🧩 Updating package.json to ${version}...`);
+  const pkgPath = resolve(ROOT, 'package.json');
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+  pkg.version = version;
+  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+
+  // --- Update CHANGELOG.md --------------------------------------------------
+
+  console.log('🧩 Updating CHANGELOG.md...');
+  const changelogPath = resolve(ROOT, 'CHANGELOG.md');
+  const date = new Date().toISOString().slice(0, 10);
+  const heading = `## [${version}] - ${date}`;
+  const sourceLine = previousTag ? `\n\n_Source: changes from ${previousTag} to ${tag}._` : '';
+  const section = `\n${heading}\n\n${releaseNotes}${sourceLine}\n`;
+
+  let original;
+  try {
+    original = readFileSync(changelogPath, 'utf8');
+  } catch {
+    original = '# Change Log\n\n## [Unreleased]\n';
+  }
+
+  if (!original.includes(heading)) {
+    const marker = '## [Unreleased]';
+    const idx = original.indexOf(marker);
+    const updated =
+      idx >= 0
+        ? `${original.slice(0, idx + marker.length)}\n${section}${original.slice(idx + marker.length)}`
+        : `${original}\n${section}`;
+    writeFileSync(changelogPath, updated);
+  } else {
+    console.log('ℹ️  CHANGELOG already contains this release heading; skipping.');
+  }
+
+  // --- Commit + push --------------------------------------------------------
+
+  const hasChanges = runGit(['diff', '--name-only', '--', 'package.json', 'CHANGELOG.md']).stdout.trim();
+  if (hasChanges) {
+    console.log('📦 Committing release metadata changes...');
+    runGit(['add', 'package.json', 'CHANGELOG.md']);
+    runGit(['commit', '-m', `chore(release): update version and changelog for ${tag}`]);
+    commitLocal = true;
+  } else {
+    console.log('ℹ️  No version/changelog changes detected; nothing to commit.');
+  }
+
+  console.log('🚀 Pushing main...');
+  runGit(['push', 'origin', 'main']);
+  commitPushed = true;
+  commitLocal = false;
+
+  const headSha = runGit(['rev-parse', 'HEAD']).stdout.trim();
+
+  // --- Wait for required workflows (sequential to avoid concurrent-spinner visual corruption) ------
+
+  const shortSha = headSha.slice(0, 7);
+  console.log(`🔎 Waiting for required workflows on ${shortSha}...`);
+  // Give GitHub a moment to register the push before we start polling.
+  await sleep(10_000);
+
+  const spinner = ora({ text: 'Tests: queued' }).start();
+  for (const name of ['Test & Build']) {
+    spinner.text = `${name}: queued`;
+    spinner.start();
+    await waitForWorkflow(octokit, name, owner, repo, headSha, spinner);
+  }
+
+  // --- Tag + publish --------------------------------------------------------
+
+  console.log(`🏷️  Creating annotated tag ${tag} at ${headSha}...`);
+
+  const tagMessage = [
+    `Release ${tag}`,
+    releaseNotes,
+    previousTag ? `Source: changes from ${previousTag} to ${tag}.` : '',
+    `Target commit: ${headSha}`,
+  ]
+    .filter(Boolean)
+    .join('\n\n');
+
+  runGit(['tag', '-a', tag, headSha, '-m', tagMessage]);
+
+  console.log(`🚀 Pushing tag ${tag}...`);
+  runGit(['push', 'origin', tag]);
+  tagPushed = true;
+
+  // --- Watch the release workflow ------------------------------------------
+
+  spinner.text = 'Release: waiting for workflow to trigger...';
+  spinner.start();
+  await waitForWorkflow(octokit, 'Release', owner, repo, headSha, spinner, {
+    autoDispatch: false,
+    branch: null,
+  });
+
+  releaseDone = true;
+  console.log(`✅ GitHub release complete: ${tag} → ${headSha}`);
+
+  // --- npm publish ----------------------------------------------------------
+
+  console.log('📦 Building package...');
+  $.verbose = true;
+  await $`pnpm build`;
+  $.verbose = false;
+
+  const distTag = version.includes('-') ? 'next' : 'latest';
+  console.log(`🚀 Publishing ${tag} to npm (dist-tag: ${distTag})...`);
+  $.verbose = true;
+  await $`npm publish ./dist --tag ${distTag}`;
+  $.verbose = false;
+  console.log(`✅ Published ${tag} to npm.`);
+}
+
+// ---------------------------------------------------------------------------
+// Workflow polling
+// ---------------------------------------------------------------------------
+
+async function waitForWorkflow(
+  octokit,
+  name,
+  owner,
+  repo,
+  headSha,
+  spinner,
+  { timeoutMs = 3_600_000, pollMs = 15_000, autoDispatch = true, branch = 'main' } = {},
+) {
+  // Resolve the workflow ID by name.
+  const workflowsResp = await octokit.actions.listRepoWorkflows({ owner, repo, per_page: 100 });
+  const workflow = workflowsResp.data.workflows.find((w) => w.name === name);
+  if (!workflow) {
+    spinner.fail(`${name}: workflow not found in ${owner}/${repo}`);
+    throw new Error(`[${name}] workflow not found in ${owner}/${repo}`);
+  }
+
+  const deadline = Date.now() + timeoutMs;
+  let triggered = false;
+  // Track cancelled run IDs so we skip them on subsequent polls and don't
+  // mistake them for the new run that was re-dispatched.
+  const cancelledRunIds = new Set();
+
+  while (Date.now() < deadline) {
+    const runsResp = await octokit.actions.listWorkflowRuns({
+      owner,
+      repo,
+      workflow_id: workflow.id,
+      ...(branch ? { branch } : {}),
+      head_sha: headSha,
+      per_page: 10,
+    });
+
+    // Find the latest run that isn't one we already marked as cancelled.
+    const run = runsResp.data.workflow_runs.find((r) => !cancelledRunIds.has(r.id));
+
+    if (!run) {
+      if (autoDispatch && !triggered) {
+        spinner.text = `${name}: no run found — triggering workflow_dispatch...`;
+        await octokit.actions.createWorkflowDispatch({ owner, repo, workflow_id: workflow.id, ref: 'main' });
+        triggered = true;
+        spinner.text = `${name}: waiting for run to appear...`;
+      } else {
+        spinner.text = `${name}: waiting for run to appear...`;
+      }
+    } else if (run.status !== 'completed') {
+      const elapsed = Math.round((Date.now() - new Date(run.created_at).getTime()) / 1000);
+      spinner.text = `${name}: ${run.status} (${elapsed}s elapsed)`;
+    } else if (run.conclusion === 'success') {
+      spinner.succeed(`${name}: passed`);
+      return;
+    } else if (run.conclusion === 'cancelled') {
+      // Cancelled runs are often caused by a concurrent push racing with CI startup.
+      // Record this run so we skip it on future polls, then re-dispatch.
+      cancelledRunIds.add(run.id);
+      spinner.text = `${name}: run was cancelled — re-dispatching...`;
+      triggered = false;
+    } else {
+      spinner.fail(`${name}: ${run.conclusion}`);
+      throw new Error(`[${name}] conclusion=${run.conclusion}\n   Run: ${run.html_url}`);
+    }
+
+    await sleep(pollMs);
+  }
+
+  spinner.fail(`${name}: timed out`);
+  throw new Error(`[${name}] timed out after ${timeoutMs / 1000}s`);
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+main().catch(async (err) => {
+  const msg = err?.message ?? String(err);
+  // ProcessOutput errors from zx already printed the command output; only
+  // print extra context for our own thrown errors.
+  if (!(err instanceof ProcessOutput)) {
+    console.error(`❌ ${msg}`);
+  }
+  await rollback();
+  process.exit(err?.exitCode ?? 1);
+});

package/scripts/write-dist-package.js

@@ -0,0 +1,53 @@
+import { copyFile, mkdir, readFile, writeFile } from 'fs/promises';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+async function main() {
+  const rootPkgPath = resolve(__dirname, '..', 'package.json');
+  const outDir = resolve(__dirname, '..', 'dist');
+  const raw = await readFile(rootPkgPath, 'utf8');
+  const {name, version, description, keywords, homepage, bugs, issues, repository, license, author} = JSON.parse(raw);
+
+  const distPkg = {
+    name,
+    version,
+    description,
+    keywords,
+    homepage,
+    bugs,
+    issues,
+    repository,
+    license,
+    author,
+    main: './index.cjs',
+    module: './index.js',
+    types: './index.d.ts',
+    files: ['./index.cjs', './index.js', './index.d.ts'],
+    bin: {
+      'beans-mcp': './beans-mcp-server.cjs'
+    },
+    exports: {
+      '.': {
+        import: './index.js',
+        require: './index.cjs'
+      }
+    }
+  };
+
+  await mkdir(outDir, { recursive: true });
+  await writeFile(resolve(outDir, 'package.json'), JSON.stringify(distPkg, null, 2) + '\n', 'utf8');
+  console.log('Wrote', resolve(outDir, 'package.json'));
+
+  const readmeSrc = resolve(__dirname, '..', 'README.md');
+  const readmeDest = resolve(outDir, 'README.md');
+  await copyFile(readmeSrc, readmeDest);
+  console.log('Copied', readmeSrc, 'to', readmeDest);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exitCode = 1;
+});

package/src/cli.ts

@@ -0,0 +1,14 @@
+/**
+ * CLI entry point for beans-mcp-server
+ *
+ * Usage:
+ *   beans-mcp-server [workspace-root] [options]
+ *   beans-mcp-server --help
+ */
+
+import { startBeansMcpServer } from './server/BeansMcpServer';
+
+startBeansMcpServer(process.argv.slice(2)).catch(error => {
+  console.error('[beans-mcp-server] fatal:', error);
+  process.exit(1);
+});

package/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Public API for beans-mcp-server
+ *
+ * Exports:
+ * - createBeansMcpServer: Create an MCP server instance
+ * - startBeansMcpServer: CLI entrypoint for launching as stdio server
+ * - parseCliArgs: Parse CLI arguments for configuration
+ * - isPathWithinRoot: Utility to validate file paths stay within root
+ * - sortBeans: Sort beans by specified mode
+ *
+ * Types:
+ * - BeanRecord, SortMode, GraphQLError
+ * - BackendInterface: Interface for custom backend implementations
+ */
+
+export { createBeansMcpServer, parseCliArgs, startBeansMcpServer } from './server/BeansMcpServer';
+export { BeansCliBackend, type BackendInterface } from './server/backend';
+export { sortBeans } from './internal/queryHelpers';
+export { isPathWithinRoot, makeTextAndStructured } from './utils';
+export type { BeanRecord, SortMode, GraphQLError } from './types';
+export { DEFAULT_MCP_PORT, MAX_ID_LENGTH, MAX_TITLE_LENGTH, MAX_METADATA_LENGTH } from './types';