ziprin-context-optimizer 8.0.0

package/README.md

@@ -0,0 +1,48 @@
+# Ziprin Context Optimizer 8.0.0
+
+Standalone MCP + Context Inspector — **not part of ziprin-monorepo**.
+
+| Registry | URL |
+|----------|-----|
+| GitLab | https://185.226.118.181/ah.lotfali/ziprin-context-optimizer |
+| npm | `ziprin-context-optimizer@8.0.0` (after `npm publish`) |
+
+## Install (local dev → ~/.ziprin)
+
+```bash
+cd ~/Desktop/ziprin-context-optimizer
+npm run install:local
+# or with monorepo path:
+node scripts/install.mjs --workspace ~/Desktop/ziprin-monorepo
+```
+
+## Update from GitLab (sync monorepo ref)
+
+```bash
+npm run update:local
+# or:
+node scripts/update.mjs --workspace ~/Desktop/ziprin-monorepo
+```
+
+## Publish GitLab + npm
+
+```bash
+git push -u origin main --tags
+npm login
+npm run publish:all
+```
+
+GitLab CI (`.gitlab-ci.yml`) runs tests on push and `npm publish` on tags.
+
+## Monorepo integration
+
+Monorepo keeps only:
+- `.cursor/ziprin-context-mcp.mjs` — thin launcher (~60 lines)
+- `.cursor/ziprin-context-ref.json` — version pointer
+- `.cursor/mcp.json` — points to launcher
+
+Runtime: `~/.ziprin/ziprin-context-optimizer`
+
+## MCP tools (8)
+
+`ziprin_optimize_context` · `ziprin_analyze_task` · `ziprin_rank_context` · `ziprin_find_symbol` · `ziprin_unfold_symbol` · `ziprin_validate_context` · `ziprin_context_memory` · `ziprin_health`

package/bin/ziprin-context-mcp.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+'use strict';
+
+/** npm bin entry — stdio MCP for Cursor / CLI */
+const path = require('path');
+const { spawn } = require('child_process');
+
+const entry = path.join(__dirname, '..', 'src', 'mcp-server.js');
+const workspace = process.env.ZIPRIN_WORKSPACE
+  ? path.resolve(process.env.ZIPRIN_WORKSPACE)
+  : process.cwd();
+
+const child = spawn(process.execPath, [entry, '--project', workspace], {
+  stdio: 'inherit',
+  env: { ...process.env, ZIPRIN_WORKSPACE: workspace },
+  windowsHide: true,
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    try {
+      process.kill(process.pid, signal);
+    } catch {
+      process.exit(1);
+    }
+    return;
+  }
+  process.exit(code ?? 1);
+});
+
+child.on('error', (err) => {
+  console.error('[ziprin-context-mcp]', err.message);
+  process.exit(1);
+});

package/bin/ziprin-context-setup.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+'use strict';
+
+/** One-command install: MCP runtime + VSIX + workspace mcp.json */
+const { spawnSync } = require('child_process');
+const path = require('path');
+
+const script = path.join(__dirname, '..', 'scripts', 'install.mjs');
+const r = spawnSync(process.execPath, [script, ...process.argv.slice(2)], { stdio: 'inherit' });
+process.exit(r.status ?? 1);

package/install-source.json

@@ -0,0 +1,5 @@
+{
+  "version": "8.0.0",
+  "git": "https://185.226.118.181/ah.lotfali/ziprin-context-optimizer.git#v8.0.0",
+  "npm": "@ziprin/context-optimizer@8.0.0"
+}

package/media/context-activity.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">
+  <rect x="3" y="4" width="8" height="6" rx="1.5"/>
+  <rect x="13" y="4" width="8" height="6" rx="1.5"/>
+  <rect x="3" y="14" width="8" height="6" rx="1.5"/>
+  <path d="M13 17h8"/>
+  <path d="M17 14v6"/>
+</svg>

package/package.json

@@ -0,0 +1,154 @@
+{
+  "name": "ziprin-context-optimizer",
+  "displayName": "Ziprin Context Inspector",
+  "description": "Live observability dashboard for Ziprin Context MCP — history, health, token analytics. Intelligence runs only via MCP in native Cursor Chat.",
+  "version": "8.0.0",
+  "publisher": "ziprin",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://185.226.118.181/ah.lotfali/ziprin-context-optimizer.git"
+  },
+  "bugs": {
+    "url": "https://185.226.118.181/ah.lotfali/ziprin-context-optimizer/-/issues"
+  },
+  "homepage": "https://185.226.118.181/ah.lotfali/ziprin-context-optimizer",
+  "keywords": [
+    "ziprin",
+    "mcp",
+    "cursor",
+    "context",
+    "model-context-protocol"
+  ],
+  "files": [
+    "bin/",
+    "src/",
+    "media/",
+    "scripts/",
+    "templates/",
+    "releases/",
+    "install-source.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "ziprin-context-mcp": "./bin/ziprin-context-mcp.js",
+    "ziprin-context-setup": "./bin/ziprin-context-setup.js"
+  },
+  "engines": {
+    "vscode": "^1.85.0"
+  },
+  "categories": [
+    "Other",
+    "Machine Learning"
+  ],
+  "activationEvents": [
+    "onStartupFinished",
+    "onView:ziprinContext.inspector"
+  ],
+  "main": "./src/extension.js",
+  "contributes": {
+    "viewsContainers": {
+      "activitybar": [
+        {
+          "id": "ziprinContext",
+          "title": "Context Inspector",
+          "icon": "media/context-activity.svg"
+        }
+      ]
+    },
+    "views": {
+      "ziprinContext": [
+        {
+          "type": "webview",
+          "id": "ziprinContext.inspector",
+          "name": "Context Dashboard"
+        }
+      ]
+    },
+    "commands": [
+      {
+        "command": "ziprinContext.openInspector",
+        "title": "Ziprin Context: Open Inspector Dashboard"
+      },
+      {
+        "command": "ziprinContext.refreshDashboard",
+        "title": "Ziprin Context: Reload Observer State"
+      },
+      {
+        "command": "ziprinContext.diagnoseMcp",
+        "title": "Ziprin Context: Diagnose MCP Health"
+      },
+      {
+        "command": "ziprinContext.installTokenBudget",
+        "title": "Ziprin Context: Install Token Budget (stub + strip mdc)"
+      }
+    ],
+    "configuration": {
+      "title": "Ziprin Context Inspector",
+      "properties": {
+        "ziprinContext.profile": {
+          "type": "string",
+          "enum": [
+            "frontend",
+            "backend",
+            "architecture",
+            "standard",
+            "minimal",
+            "strict"
+          ],
+          "default": "standard",
+          "description": "Default context profile label in the dashboard (MCP may pass profileId explicitly)"
+        },
+        "ziprinContext.charsPerToken": {
+          "type": "number",
+          "default": 4,
+          "description": "Heuristic bytes per token"
+        },
+        "ziprinContext.stripOtherMdc": {
+          "type": "boolean",
+          "default": true,
+          "description": "When installing token budget, delete non-stub .mdc rules"
+        },
+        "ziprinContext.liveRefresh": {
+          "type": "boolean",
+          "default": true,
+          "description": "Auto-update dashboard when MCP event/session files change"
+        },
+        "ziprinContext.refreshDebounceMs": {
+          "type": "number",
+          "default": 500,
+          "minimum": 120,
+          "description": "Debounce for live dashboard updates"
+        },
+        "ziprinContext.autoRevealPanel": {
+          "type": "boolean",
+          "default": true,
+          "description": "Reveal the Context Inspector Activity Bar panel on activate"
+        },
+        "ziprinContext.maxSessions": {
+          "type": "number",
+          "default": 80,
+          "minimum": 10,
+          "description": "Maximum recorded MCP sessions per workspace"
+        }
+      }
+    }
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.js",
+    "test:mcp": "node --test tests/mcp-gateway.test.js tests/v6-mandatory.test.js tests/mcp-lifecycle.test.js tests/mcp-event-stream.test.js",
+    "mcp": "node src/mcp-server.js",
+    "mcp:health": "node src/mcp-health-cli.js",
+    "package": "node scripts/package-vsix.mjs",
+    "install:local": "node scripts/install.mjs",
+    "setup": "node bin/ziprin-context-setup.js",
+    "update:local": "node scripts/update.mjs",
+    "publish:all": "node scripts/publish.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0"
+  }
+}

package/scripts/install.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+/**
+ * Install to ~/.ziprin + VSIX + patch monorepo mcp.json
+ *
+ *   node scripts/install.mjs
+ *   node scripts/install.mjs --workspace C:/path/to/ziprin-monorepo
+ *   node scripts/install.mjs --from bundle.zip
+ */
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  defaultInstallRoot,
+  isPluginRoot,
+  writeManifest,
+  ziprinHome,
+} from "./paths.mjs";
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const SOURCE_CFG = path.join(PKG_ROOT, "install-source.json");
+const INSTALL_ROOT = defaultInstallRoot();
+const LOG = "[ziprin-context-install]";
+
+function log(...a) {
+  console.error(LOG, ...a);
+}
+
+function fail(msg, code = 1) {
+  console.error(LOG, "FATAL:", msg);
+  process.exit(code);
+}
+
+function parseArgs(argv) {
+  const out = { from: null, npm: null, git: null, workspace: null, skipVsix: false, force: false };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--from" && argv[i + 1]) out.from = path.resolve(argv[++i]);
+    else if (a === "--npm" && argv[i + 1]) out.npm = argv[++i];
+    else if (a === "--git" && argv[i + 1]) out.git = argv[++i];
+    else if (a === "--workspace" && argv[i + 1]) out.workspace = path.resolve(argv[++i]);
+    else if (a === "--skip-vsix") out.skipVsix = true;
+    else if (a === "--force") out.force = true;
+  }
+  if (!out.workspace) {
+    const guess = path.join(os.homedir(), "Desktop", "ziprin-monorepo");
+    if (fs.existsSync(path.join(guess, ".cursor"))) out.workspace = guess;
+  }
+  return out;
+}
+
+function loadDefaults() {
+  if (!fs.existsSync(SOURCE_CFG)) return { version: "8.0.0", git: null, npm: null };
+  return JSON.parse(fs.readFileSync(SOURCE_CFG, "utf8"));
+}
+
+function run(cmd, args, opts = {}) {
+  const r = spawnSync(cmd, args, {
+    stdio: "inherit",
+    cwd: opts.cwd,
+    shell: opts.shell ?? false,
+    env: process.env,
+  });
+  if (r.status !== 0) throw new Error(`${cmd} failed`);
+}
+
+function npmInstall(cwd) {
+  const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+  run(npm, ["install", "--omit=dev"], { cwd, shell: process.platform === "win32" });
+}
+
+function installFromGit(spec) {
+  const hash = spec.lastIndexOf("#");
+  const url = hash === -1 ? spec : spec.slice(0, hash);
+  const ref = hash === -1 ? null : spec.slice(hash + 1);
+  if (fs.existsSync(INSTALL_ROOT)) fs.rmSync(INSTALL_ROOT, { recursive: true, force: true });
+  const args = ["clone", "--depth", "1"];
+  if (ref) args.push("--branch", ref);
+  args.push(url, INSTALL_ROOT);
+  run("git", args);
+  if (!isPluginRoot(INSTALL_ROOT)) fail("git clone missing src/mcp-server.js");
+  npmInstall(INSTALL_ROOT);
+  return INSTALL_ROOT;
+}
+
+function installFromNpm(spec) {
+  if (fs.existsSync(INSTALL_ROOT)) fs.rmSync(INSTALL_ROOT, { recursive: true, force: true });
+  fs.mkdirSync(INSTALL_ROOT, { recursive: true });
+  fs.writeFileSync(
+    path.join(INSTALL_ROOT, "package.json"),
+    JSON.stringify({ name: "ziprin-context-host", private: true }, null, 2),
+  );
+  const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+  run(npm, ["install", spec, "--omit=dev"], { cwd: INSTALL_ROOT, shell: process.platform === "win32" });
+  const nested = path.join(INSTALL_ROOT, "node_modules", "@ziprin", "context-optimizer");
+  if (!isPluginRoot(nested)) fail("npm install missing plugin");
+  return nested;
+}
+
+function installLocalDev() {
+  log("dev install from Desktop repo →", INSTALL_ROOT);
+  if (fs.existsSync(INSTALL_ROOT)) fs.rmSync(INSTALL_ROOT, { recursive: true, force: true });
+  fs.cpSync(PKG_ROOT, INSTALL_ROOT, { recursive: true, filter: (src) => !src.includes("node_modules") });
+  npmInstall(INSTALL_ROOT);
+  return INSTALL_ROOT;
+}
+
+function patchMonorepo(workspace, version, ref) {
+  if (!workspace) return;
+  const mcpJson = path.join(workspace, ".cursor", "mcp.json");
+  const refJson = path.join(workspace, ".cursor", "ziprin-context-ref.json");
+  const launcher = path.join(workspace, ".cursor", "ziprin-context-mcp.mjs");
+  const template = path.join(PKG_ROOT, "templates", "ziprin-context-mcp.mjs");
+  if (fs.existsSync(template)) {
+    fs.mkdirSync(path.dirname(launcher), { recursive: true });
+    fs.copyFileSync(template, launcher);
+    log("installed launcher", launcher);
+  }
+  if (fs.existsSync(mcpJson)) {
+    const cfg = JSON.parse(fs.readFileSync(mcpJson, "utf8"));
+    cfg.mcpServers = cfg.mcpServers || {};
+    cfg.mcpServers["ziprin-context"] = {
+      command: "node",
+      args: ["${workspaceFolder}/.cursor/ziprin-context-mcp.mjs"],
+      env: { ZIPRIN_WORKSPACE: "${workspaceFolder}" },
+    };
+    fs.writeFileSync(mcpJson, `${JSON.stringify(cfg, null, 2)}\n`);
+    log("patched", mcpJson);
+  }
+  if (fs.existsSync(refJson)) {
+    const refCfg = JSON.parse(fs.readFileSync(refJson, "utf8"));
+    refCfg.ref = ref || refCfg.ref;
+    refCfg.npm = `@ziprin/context-optimizer@${version}`;
+    fs.writeFileSync(refJson, `${JSON.stringify(refCfg, null, 2)}\n`);
+    log("patched", refJson);
+  }
+}
+
+function installVsix() {
+  const version = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, "package.json"), "utf8")).version;
+  const vsix = path.join(PKG_ROOT, "releases", `ziprin-context-optimizer-${version}.vsix`);
+  if (!fs.existsSync(vsix)) {
+    log("WARN: no VSIX in releases/ — run npm run package");
+    return;
+  }
+  for (const cli of ["cursor", "code"]) {
+    const r = spawnSync(process.platform === "win32" ? "where" : "which", [cli], {
+      encoding: "utf8",
+      shell: true,
+    });
+    if (r.status === 0 && r.stdout.trim()) {
+      run(cli, ["--install-extension", vsix, "--force"], { shell: true });
+      return;
+    }
+  }
+  log("WARN: install VSIX manually:", vsix);
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const defs = loadDefaults();
+  fs.mkdirSync(ziprinHome(), { recursive: true });
+
+  let pluginRoot;
+  if (args.from) {
+    fail("--from not implemented in Desktop install yet; use local dev copy");
+  } else if (args.git) {
+    try {
+      pluginRoot = installFromGit(args.git);
+    } catch (err) {
+      log("git install failed, falling back to Desktop repo copy:", err.message);
+      pluginRoot = installLocalDev();
+    }
+  } else if (args.npm) {
+    pluginRoot = installFromNpm(args.npm);
+  } else if (isPluginRoot(INSTALL_ROOT) && !args.force) {
+    pluginRoot = INSTALL_ROOT;
+    npmInstall(pluginRoot);
+  } else {
+    pluginRoot = installLocalDev();
+  }
+
+  const version = JSON.parse(fs.readFileSync(path.join(pluginRoot, "package.json"), "utf8")).version;
+  const ref = args.git?.split("#")[1] || defs.git?.split("#")[1] || `v${version}`;
+
+  writeManifest({
+    version,
+    pluginRoot,
+    installedAt: new Date().toISOString(),
+    source: args.npm ? "npm" : args.git ? "git" : "local",
+  });
+
+  patchMonorepo(args.workspace, version, ref);
+  if (!args.skipVsix) installVsix();
+
+  console.log(`\n✓ Ziprin Context v${version}`);
+  console.log(`  Plugin:    ${pluginRoot}`);
+  console.log(`  Monorepo:  ${args.workspace || "(not found)"}`);
+  console.log("  Next: Developer → Reload Window in Cursor\n");
+}
+
+main();

package/scripts/package-vsix.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+/**
+ * VSCE rejects scoped npm names (@scope/pkg). Build VSIX with extension-safe name.
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const pkgFile = path.join(PKG_ROOT, 'package.json');
+const backup = path.join(PKG_ROOT, 'package.json.vsce-backup');
+const releases = path.join(PKG_ROOT, 'releases');
+
+const original = JSON.parse(fs.readFileSync(pkgFile, 'utf8'));
+const version = original.version;
+const vsixName = `ziprin-context-optimizer-${version}.vsix`;
+
+fs.mkdirSync(releases, { recursive: true });
+fs.writeFileSync(backup, JSON.stringify(original, null, 2));
+
+const vscePkg = { ...original, name: 'ziprin-context-optimizer' };
+delete vscePkg.files;
+delete vscePkg.publishConfig;
+fs.writeFileSync(pkgFile, `${JSON.stringify(vscePkg, null, 2)}\n`);
+
+try {
+  const r = spawnSync(
+    process.platform === 'win32' ? 'npx.cmd' : 'npx',
+    ['--yes', '@vscode/vsce', 'package', '--no-dependencies', '--out', path.join('releases', vsixName)],
+    { cwd: PKG_ROOT, stdio: 'inherit', shell: process.platform === 'win32' },
+  );
+  if (r.status !== 0) process.exit(r.status ?? 1);
+  console.error(`\n✓ VSIX: releases/${vsixName}\n`);
+} finally {
+  fs.writeFileSync(pkgFile, `${JSON.stringify(original, null, 2)}\n`);
+  fs.rmSync(backup, { force: true });
+}

package/scripts/paths.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const MANIFEST_REL = ".ziprin/ziprin-context-install.json";
+
+export function ziprinHome() {
+  return path.join(os.homedir(), ".ziprin");
+}
+
+export function defaultInstallRoot() {
+  return path.join(ziprinHome(), "ziprin-context-optimizer");
+}
+
+export function manifestPath() {
+  return path.join(os.homedir(), MANIFEST_REL);
+}
+
+export function isPluginRoot(dir) {
+  if (!dir) return false;
+  return fs.existsSync(path.join(dir, "src", "mcp-server.js"));
+}
+
+export function readManifest() {
+  const file = manifestPath();
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function writeManifest(data) {
+  const file = manifestPath();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+}

package/scripts/publish.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * Publish ziprin-context-optimizer to GitLab + npm (run from package root).
+ *
+ *   node scripts/publish.mjs
+ *
+ * Prerequisites:
+ *   - GitLab project: https://185.226.118.181/ah.lotfali/ziprin-context-optimizer (create empty)
+ *   - npm login (npm login) with access to publish ziprin-context-optimizer
+ *   - VPN/network to 185.226.118.181 if self-hosted GitLab is internal
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+const tag = `v${pkg.version}`;
+
+function run(cmd, args, opts = {}) {
+  console.error(`> ${cmd} ${args.join(' ')}`);
+  const r = spawnSync(cmd, args, { stdio: 'inherit', cwd: ROOT, shell: opts.shell ?? false });
+  if (r.status !== 0) process.exit(r.status ?? 1);
+}
+
+console.error(`[publish] ${pkg.name}@${pkg.version}`);
+
+run('git', ['push', '-u', 'origin', 'main', '--tags']);
+run('npm', ['publish', '--access', 'public'], { shell: process.platform === 'win32' });
+
+console.log('');
+console.log(`✓ Published ${pkg.name}@${pkg.version}`);
+console.log(`  GitLab: ${pkg.repository?.url || 'see package.json'}`);
+console.log(`  npm:    https://www.npmjs.com/package/${pkg.name}`);
+console.log(`  Tag:    ${tag}`);

package/scripts/update.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * Pull latest from GitLab/npm, refresh ~/.ziprin, sync monorepo ref.
+ *
+ *   node scripts/update.mjs
+ *   node scripts/update.mjs --workspace C:/path/to/ziprin-monorepo
+ */
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { defaultInstallRoot, isPluginRoot, readManifest, writeManifest } from "./paths.mjs";
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const SOURCE_CFG = path.join(PKG_ROOT, "install-source.json");
+const INSTALL_ROOT = defaultInstallRoot();
+const LOG = "[ziprin-context-update]";
+
+function log(...a) {
+  console.error(LOG, ...a);
+}
+
+function parseArgs(argv) {
+  const out = { workspace: null };
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === "--workspace" && argv[i + 1]) out.workspace = path.resolve(argv[++i]);
+  }
+  if (!out.workspace) {
+    const guess = path.join(os.homedir(), "Desktop", "ziprin-monorepo");
+    if (fs.existsSync(path.join(guess, ".cursor"))) out.workspace = guess;
+  }
+  return out;
+}
+
+function run(cmd, args, opts = {}) {
+  const r = spawnSync(cmd, args, { stdio: "inherit", cwd: opts.cwd, shell: opts.shell ?? false });
+  if (r.status !== 0) process.exit(r.status ?? 1);
+}
+
+function loadDefaults() {
+  return JSON.parse(fs.readFileSync(SOURCE_CFG, "utf8"));
+}
+
+function syncMonorepoRef(workspace, version, ref) {
+  if (!workspace) return;
+  const refJson = path.join(workspace, ".cursor", "ziprin-context-ref.json");
+  if (!fs.existsSync(refJson)) return;
+  const cfg = JSON.parse(fs.readFileSync(refJson, "utf8"));
+  cfg.ref = ref;
+  cfg.npm = `ziprin-context-optimizer@${version}`;
+  fs.writeFileSync(refJson, `${JSON.stringify(cfg, null, 2)}\n`);
+  log("synced", refJson, "→", ref);
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const defs = loadDefaults();
+  const manifest = readManifest();
+
+  if (fs.existsSync(path.join(INSTALL_ROOT, ".git"))) {
+    log("git pull in", INSTALL_ROOT);
+    run("git", ["pull", "--ff-only"], { cwd: INSTALL_ROOT });
+  } else if (defs.git) {
+    log("re-install from git", defs.git);
+    run(process.execPath, [path.join(PKG_ROOT, "scripts", "install.mjs"), "--git", defs.git, "--force"], {
+      shell: true,
+    });
+    return;
+  } else if (defs.npm) {
+    log("re-install from npm", defs.npm);
+    run(process.execPath, [path.join(PKG_ROOT, "scripts", "install.mjs"), "--npm", defs.npm, "--force"], {
+      shell: true,
+    });
+    return;
+  }
+
+  if (isPluginRoot(INSTALL_ROOT)) {
+    const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+    run(npm, ["install", "--omit=dev"], { cwd: INSTALL_ROOT, shell: process.platform === "win32" });
+  }
+
+  const version = JSON.parse(fs.readFileSync(path.join(INSTALL_ROOT, "package.json"), "utf8")).version;
+  const ref = defs.git?.split("#")[1] || `v${version}`;
+
+  writeManifest({
+    ...(manifest || {}),
+    version,
+    pluginRoot: INSTALL_ROOT,
+    updatedAt: new Date().toISOString(),
+  });
+
+  syncMonorepoRef(args.workspace, version, ref);
+
+  run(process.execPath, [path.join(PKG_ROOT, "scripts", "install.mjs"), "--skip-vsix"], { shell: true });
+
+  console.log(`\n✓ Updated to v${version}. Reload Cursor window.\n`);
+}
+
+main();