@contextful-com/contextful-mcp 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# Contextful
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Connect Claude Code or Codex to your Contextful Hub. The installer sets up the
+local MCP server, hooks, and skills, and guides you through account connection.
+Your Hub runs separately in the cloud or on your own infrastructure.
+
+## Install
+
+Run this from your project, using the Hub URL provided by your dashboard:
+
+```sh
+npx @contextful-com/contextful-mcp@latest install --hub https://YOUR-HUB
+```
+
+Follow the browser sign-in and choose your agent when prompted. The installer
+discovers the Hub endpoints and your organizations. It reuses a saved or sole
+organization; otherwise, choose an organization by name. It asks before uploading
+committed repository history. Private prompt history and usage are opt-in.
+It then asks whether to upload new commits on your default branch automatically
+and, when your Hub offers it, whether to share the lessons your agent writes down.
+
+To choose an agent explicitly, add `--client codex` or `--client claude`.
+
+## Ask your agent to install
+
+Copy this prompt and replace the Hub URL:
+
+> Install Contextful for this project using https://YOUR-HUB and the official
+> @contextful-com/contextful-mcp npm package. Use the current agent, or ask whether
+> I want Codex or Claude Code. Guide me through browser sign-in and complete the
+> MCP, hooks, and skills installation. Ask before uploading repository history,
+> turning on automatic updates, or sharing lessons.
+
+Instructions for the installing agent:
+
+- Run the package's `install --hub <URL>` command from the project and supply
+  `--client codex` or `--client claude`. Use `--scope repo --project .` for this
+  project, and `--json --no-open --no-wait --no-history` to handle progress and
+  keep private history local. If no project is available, ask which folder to use.
+- `npx -y` accepts npm's package download prompt. The install command's `--yes`
+  separately approves committed-history upload; use it only after user approval.
+- `--yes` answers no other question. Ask whether to upload new commits on the
+  default branch automatically and whether to share the lessons the agent writes
+  down; add `--auto-refresh` and `--share-lessons` or `--no-share-lessons` only
+  after the user answers. Without them, automatic updates stay off.
+- Show `authorization_required`'s link and code immediately, and keep the process
+  running while the user signs in. Do not request passwords or read stored tokens.
+- On `organization_required`, ask the user to choose from the returned names;
+  supply the selected ID internally when resuming. On `consent_required`, obtain
+  approval for the stated Hub and upload, then resume with the returned arguments.
+  Prefix returned `contextful-mcp` commands with this npm package when needed.
+- After `complete`, report the installed agent and required activation actions.
+  Hub training may still be running. Do not report pending training as ready, or
+  bypass the agent's hook trust. Rerun the same install command to resume failures.
+
+## Requirements
+
+- Node.js 24 or newer and npm to run the npm launcher.
+- A supported Claude Code or Codex installation. The installer checks its version.
+- macOS ARM64/x64, Linux ARM64/x64 with glibc, or Windows x64.
+
+npm installs the matching prebuilt binary. No compiler or Bun installation is
+needed. Installed plugins keep their own executable, so they continue working
+independently of npm's cache and without Node or Bun on their runtime path.
+
+## Update or uninstall
+
+Rerun the install command with `@latest` to update your integration. To select a
+specific release, replace `latest` with its version.
+
+```sh
+npx @contextful-com/contextful-mcp@latest uninstall
+```
+
+For a persistent command on your PATH:
+
+```sh
+npm install -g @contextful-com/contextful-mcp
+contextful-mcp install --hub https://YOUR-HUB
+```
+
+Removing the global npm package removes the launcher. Use `contextful-mcp uninstall`
+to remove the installed agent integration.

package/bin/contextful-mcp.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// Public npm bootstrap. The application runs in the selected standalone binary.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { Buffer } from 'node:buffer';
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { spawn } from 'node:child_process';
+import { constants } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+export function selectTarget(platform, arch, glibc) {
+  const target = `${platform}-${arch}`;
+  if (!['darwin-arm64', 'darwin-x64', 'linux-arm64', 'linux-x64', 'win32-x64'].includes(target)) {
+    throw new Error(`Unsupported platform: ${target}. Contextful supports macOS ARM64/x64, Linux ARM64/x64 (glibc), and Windows x64.`);
+  }
+  if (platform === 'linux' && !glibc) throw new Error('Contextful requires glibc on Linux. musl/Alpine is not supported by this release.');
+  return target;
+}
+
+function checksum(file) {
+  const hash = createHash('sha256');
+  const buffer = Buffer.alloc(1024 * 1024);
+  const fd = fs.openSync(file, 'r');
+  try {
+    let bytes;
+    while ((bytes = fs.readSync(fd, buffer, 0, buffer.length, null))) hash.update(buffer.subarray(0, bytes));
+    return hash.digest('hex');
+  } finally { fs.closeSync(fd); }
+}
+
+export function resolveBinary(packageRoot) {
+  const target = selectTarget(process.platform, process.arch,
+    process.platform === 'linux' ? process.report.getReport().header.glibcVersionRuntime : undefined);
+  const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+  const manifest = JSON.parse(fs.readFileSync(path.join(packageRoot, 'native-manifest.json'), 'utf8'));
+  const record = manifest.targets?.[target];
+  if (manifest.schemaVersion !== 1 || manifest.version !== pkg.version || !record
+      || pkg.optionalDependencies?.[record.package] !== pkg.version) {
+    throw new Error('The npm launcher and binary manifest have different versions. Reinstall Contextful.');
+  }
+  let dependency;
+  try { dependency = createRequire(path.join(packageRoot, 'package.json')).resolve(`${record.package}/package.json`); }
+  catch { throw new Error(`Missing ${record.package}. Reinstall Contextful with optional dependencies enabled (remove --omit=optional).`); }
+  const installed = JSON.parse(fs.readFileSync(dependency, 'utf8'));
+  if (installed.name !== record.package || installed.version !== pkg.version) {
+    throw new Error(`The ${record.package} version does not match the launcher (${pkg.version}). Reinstall Contextful.`);
+  }
+  const expectedPath = `bin/contextful-mcp${process.platform === 'win32' ? '.exe' : ''}`;
+  if (record.executable !== expectedPath || !/^[a-f0-9]{64}$/.test(record.sha256)) {
+    throw new Error('Invalid Contextful binary manifest. Reinstall Contextful.');
+  }
+  const executable = path.join(path.dirname(dependency), expectedPath);
+  const info = fs.lstatSync(executable);
+  if (!info.isFile() || info.size !== record.size || checksum(executable) !== record.sha256) {
+    throw new Error(`Binary checksum verification failed for ${record.package}. Reinstall Contextful.`);
+  }
+  return executable;
+}
+
+function main() {
+  let executable;
+  try { executable = resolveBinary(path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')); }
+  catch (error) {
+    process.stderr.write(`Contextful could not start: ${error.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  const child = spawn(executable, process.argv.slice(2), { stdio: 'inherit', shell: false });
+  const handlers = new Map(['SIGINT', 'SIGTERM', 'SIGHUP'].map(signal => [signal, () => { child.kill(signal); }]));
+  for (const [signal, handler] of handlers) process.on(signal, handler);
+  const cleanup = () => { for (const [signal, handler] of handlers) process.off(signal, handler); };
+  child.once('error', error => {
+    cleanup();
+    process.stderr.write(`Contextful could not start its binary: ${error.message}\n`);
+    process.exitCode = 1;
+  });
+  child.once('exit', (code, signal) => {
+    cleanup();
+    if (signal && process.platform !== 'win32') process.kill(process.pid, signal);
+    else process.exitCode = code ?? (signal ? 128 + (constants.signals[signal] ?? 1) : 1);
+  });
+}
+
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) main();

package/native-manifest.json

@@ -0,0 +1,36 @@
+{
+  "schemaVersion": 1,
+  "version": "0.2.0",
+  "targets": {
+    "darwin-arm64": {
+      "package": "@contextful-com/contextful-mcp-darwin-arm64",
+      "executable": "bin/contextful-mcp",
+      "sha256": "d9ab0e49d4439290df575d5a00fa1090a92ecfa335290c038c015d312e269f7c",
+      "size": 65991666
+    },
+    "darwin-x64": {
+      "package": "@contextful-com/contextful-mcp-darwin-x64",
+      "executable": "bin/contextful-mcp",
+      "sha256": "148cb3f6dd6a01e3de04eb10f2d5647683b2a59da7d0cbafdf2efbcaa39b9a63",
+      "size": 73068816
+    },
+    "linux-arm64": {
+      "package": "@contextful-com/contextful-mcp-linux-arm64",
+      "executable": "bin/contextful-mcp",
+      "sha256": "2567f022f54df6f62a60ca422bb95547ef781415faf566130bbdb703082c243e",
+      "size": 85051688
+    },
+    "linux-x64": {
+      "package": "@contextful-com/contextful-mcp-linux-x64",
+      "executable": "bin/contextful-mcp",
+      "sha256": "beccfc11eba4f6f080e6ddf5d14667f237a0e4407385ae07eccee83f30faf044",
+      "size": 85050848
+    },
+    "win32-x64": {
+      "package": "@contextful-com/contextful-mcp-win32-x64",
+      "executable": "bin/contextful-mcp.exe",
+      "sha256": "81d71b9a147c43b1b149a7b9de7f6986ae26a15823a7d45cd7122c7aebd6ba15",
+      "size": 89822720
+    }
+  }
+}

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@contextful-com/contextful-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "description": "Install Contextful MCP, hooks and skills for Claude Code and Codex",
+  "type": "module",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "bin": {
+    "contextful-mcp": "bin/contextful-mcp.mjs"
+  },
+  "files": [
+    "bin",
+    "native-manifest.json"
+  ],
+  "optionalDependencies": {
+    "@contextful-com/contextful-mcp-darwin-arm64": "0.2.0",
+    "@contextful-com/contextful-mcp-darwin-x64": "0.2.0",
+    "@contextful-com/contextful-mcp-linux-arm64": "0.2.0",
+    "@contextful-com/contextful-mcp-linux-x64": "0.2.0",
+    "@contextful-com/contextful-mcp-win32-x64": "0.2.0"
+  }
+}