@empirical-gauzza/cli 1.0.19 → 1.0.21

package/lib/pluginCommands.js

@@ -1,81 +1,84 @@
-'use strict';
-
-const { log, warn, uiHeader, uiSuccess } = require('./ui');
-const { detectInstallTargets } = require('./installers/detect');
-const {
-  installNativePlugin,
-  OPTIONAL_PLUGIN_NAMES = ['empirical-work-history', 'empirical-scar-tissue', 'empirical-todo']
-} = require('./installers/nativePlugin');
-const { checkNativePluginUpdates } = require('./pluginUpdateCheck');
-
-const SUPPORTED_TARGETS = ['codex', 'copilot', 'claude'];
-
-function isPluginCommand(args = []) {
-  return args[0] === 'plugin';
-}
-
-function resolveTargets(targetArg) {
-  if (targetArg === 'all') return SUPPORTED_TARGETS;
-  if (targetArg && SUPPORTED_TARGETS.includes(targetArg)) return [targetArg];
-  if (targetArg) {
-    throw new Error(`Unsupported plugin target "${targetArg}". Use codex, copilot, claude, or all.`);
-  }
-
-  const detected = detectInstallTargets().map((target) => target.id);
-  if (detected.length === 0) {
-    throw new Error('No supported CLI detected. Specify a target explicitly: codex, copilot, claude, or all.');
-  }
-  return detected;
-}
-
-function resolvePluginNames(args = []) {
-  const names = ['empirical-memory'];
-  if (args.includes('--all-optional') || args.includes('--work-history')) names.push('empirical-work-history');
-  if (args.includes('--all-optional') || args.includes('--scar-tissue')) names.push('empirical-scar-tissue');
-  if (args.includes('--all-optional') || args.includes('--todo')) names.push('empirical-todo');
-  return names.filter((name) => name === 'empirical-memory' || OPTIONAL_PLUGIN_NAMES.includes(name));
-}
-
-async function runPluginCommand(args = []) {
-  const action = args[0];
-  if (action === 'check') {
-    const result = await checkNativePluginUpdates({
-      force: args.includes('--force'),
-      interactive: Boolean(process.stdin.isTTY)
-    });
-    if (result.skipped && result.reason === 'rate_limited') {
-      log('Native plugin update check was recently completed.');
-    } else if (result.outdated?.length) {
-      log(uiSuccess('Native plugin update check complete.'));
-    } else if (!result.skipped) {
-      log('Native plugins are up to date.');
-    }
-    return;
-  }
-  if (action !== 'install') {
-    throw new Error('Usage: empirical plugin install <codex|copilot|claude|all> or empirical plugin check [--force]');
-  }
-
-  const targets = resolveTargets(args[1]);
-  const pluginNames = resolvePluginNames(args.slice(2));
-  log(uiHeader('Empirical native plugin installer'));
-  log('');
-  for (const target of targets) {
-    log(`Installing empirical-memory for ${target}...`);
-    if (pluginNames.length === 1) installNativePlugin(target);
-    else installNativePlugin(target, pluginNames);
-    log(uiSuccess(`${target} plugins installed through its marketplace: ${pluginNames.join(', ')}.`));
-  }
-  log('');
-  log('Native plugin installation does not configure MCP or credentials.');
-  log('Optional packages: --work-history, --scar-tissue, --todo, or --all-optional.');
-  log('Use `empirical auth login` for normal CLI OAuth, or the full `empirical install` flow for MCP setup.');
-}
-
-module.exports = {
-  SUPPORTED_TARGETS,
-  isPluginCommand,
-  resolveTargets,
-  resolvePluginNames,
-  runPluginCommand
-};
+'use strict';
+
+const { log, warn, uiHeader, uiSuccess } = require('./ui');
+const { detectInstallTargets } = require('./installers/detect');
+const {
+  installNativePlugin,
+  OPTIONAL_PLUGIN_NAMES = ['empirical-work-history', 'empirical-scar-tissue', 'empirical-todo']
+} = require('./installers/nativePlugin');
+const { checkNativePluginUpdates } = require('./pluginUpdateCheck');
+
+const SUPPORTED_TARGETS = ['codex', 'copilot', 'claude'];
+
+function isPluginCommand(args = []) {
+  return args[0] === 'plugin';
+}
+
+function resolveTargets(targetArg) {
+  if (targetArg === 'all') return SUPPORTED_TARGETS;
+  if (targetArg && SUPPORTED_TARGETS.includes(targetArg)) return [targetArg];
+  if (targetArg) {
+    throw new Error(`Unsupported plugin target "${targetArg}". Use codex, copilot, claude, or all.`);
+  }
+
+  const detected = detectInstallTargets().map((target) => target.id);
+  if (detected.length === 0) {
+    throw new Error('No supported CLI detected. Specify a target explicitly: codex, copilot, claude, or all.');
+  }
+  return detected;
+}
+
+function resolvePluginNames(args = []) {
+  const names = ['empirical-memory'];
+  if (args.includes('--all-optional') || args.includes('--work-history')) names.push('empirical-work-history');
+  if (args.includes('--all-optional') || args.includes('--scar-tissue')) names.push('empirical-scar-tissue');
+  if (args.includes('--all-optional') || args.includes('--todo')) names.push('empirical-todo');
+  return names.filter((name) => name === 'empirical-memory' || OPTIONAL_PLUGIN_NAMES.includes(name));
+}
+
+async function runPluginCommand(args = []) {
+  const action = args[0];
+  if (action === 'check') {
+    const result = await checkNativePluginUpdates({
+      force: args.includes('--force'),
+      interactive: Boolean(process.stdin.isTTY)
+    });
+    if (result.skipped && result.reason === 'rate_limited') {
+      log('Native plugin update check was recently completed.');
+    } else if (result.outdated?.length) {
+      log(uiSuccess('Native plugin update check complete.'));
+    } else if (!result.skipped) {
+      log('Native plugins are up to date.');
+    }
+    if (result.notInstalled?.length) {
+      for (const target of result.notInstalled) log(`${target}: not installed`);
+    }
+    return;
+  }
+  if (action !== 'install') {
+    throw new Error('Usage: empirical plugin install <codex|copilot|claude|all> or empirical plugin check [--force]');
+  }
+
+  const targets = resolveTargets(args[1]);
+  const pluginNames = resolvePluginNames(args.slice(2));
+  log(uiHeader('Empirical native plugin installer'));
+  log('');
+  for (const target of targets) {
+    log(`Installing empirical-memory for ${target}...`);
+    if (pluginNames.length === 1) installNativePlugin(target);
+    else installNativePlugin(target, pluginNames);
+    log(uiSuccess(`${target} plugins installed through its marketplace: ${pluginNames.join(', ')}.`));
+  }
+  log('');
+  log('Native plugin installation does not configure MCP or credentials.');
+  log('Optional packages: --work-history, --scar-tissue, --todo, or --all-optional.');
+  log('Use `empirical auth login` for normal CLI OAuth, or the full `empirical install` flow for MCP setup.');
+}
+
+module.exports = {
+  SUPPORTED_TARGETS,
+  isPluginCommand,
+  resolveTargets,
+  resolvePluginNames,
+  runPluginCommand
+};

package/lib/pluginUpdateCheck.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { askYesNo, ask, log, warn, uiHeader, parseSelection } = require('./ui');
+const { askYesNo, ask, warn, uiHeader, parseSelection } = require('./ui');
 const { runResolvedCommand, commandExists, summarizeProcessOutput } = require('./fsUtils');
 const { readDeviceConfig, writeDeviceConfig } = require('./deviceConfig');
 const { installNativePlugin } = require('./installers/nativePlugin');
@@ -34,12 +34,35 @@ function extractVersion(output, pluginName = 'empirical-memory') {
       const match = rows.find((row) => row && (row.name === pluginName || row.plugin === pluginName));
       if (match?.version) return String(match.version);
     } catch (_error) {
-      // Native CLIs may print a table instead of JSON.
+      // Native CLIs may print a table or a human-readable list instead of JSON.
     }
   }
-  const line = text.split(/\r?\n/).find((value) => value.toLowerCase().includes(pluginName.toLowerCase()));
-  const match = line && line.match(new RegExp(`${pluginName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[^\\d]*(\\d+\\.\\d+\\.\\d+)`, 'i'));
-  return match ? match[1] : null;
+
+  // Neither native CLI emits JSON for `plugin list`. Codex prints a table row per plugin
+  // ("empirical-memory@empirical-memory   installed, enabled  1.1.1   <path>"); Claude prints a
+  // bulleted list with the version on its OWN line two lines below the name ("❯ empirical-
+  // memory@empirical-memory" / "  Version: 1.1.2"). A naive "first line containing pluginName"
+  // search (the previous approach) false-matched marketplace-header/path lines that mention the
+  // plugin name but carry no version at all (e.g. "Marketplace `empirical-memory`"), and for
+  // Claude's format could never find a version regardless since name and version never share a
+  // line. Anchoring on "<name>@<marketplace>" is what both real formats share and headers/paths
+  // don't, so that's the marker used to find the actual entry line before looking for a version
+  // on it or just below it.
+  const escapedName = pluginName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const entryLinePattern = new RegExp(`${escapedName}@[\\w.-]+`, 'i');
+  const lines = text.split(/\r?\n/);
+  const entryIndex = lines.findIndex((line) => entryLinePattern.test(line));
+  if (entryIndex === -1) return null;
+
+  const sameLineMatch = lines[entryIndex].match(/(\d+\.\d+\.\d+[\w.+-]*)/);
+  if (sameLineMatch) return sameLineMatch[1];
+
+  for (let i = entryIndex + 1; i < Math.min(lines.length, entryIndex + 5); i += 1) {
+    const versionMatch = lines[i].match(/Version:\s*(\S+)/i);
+    if (versionMatch) return versionMatch[1] === 'unknown' ? null : versionMatch[1];
+    if (entryLinePattern.test(lines[i])) break;
+  }
+  return null;
 }
 
 function readInstalledVersions(target, pluginNames) {
@@ -91,32 +114,42 @@ async function checkNativePluginUpdates({ force = false, interactive = process.s
   config.pluginUpdates = { checkedAt: Date.now(), latestVersions: latestVersion, installed };
   writeDeviceConfig(config);
 
-  const outdated = SUPPORTED_TARGETS.flatMap((target) => pluginNames
+  // `installed[target]` is null when that target's CLI is not on PATH (or its `plugin list`
+  // call failed) -- readInstalledVersions() returns null in that case, and it is not "no
+  // outdated plugins", it is "we could not check this target at all". Skip those targets
+  // instead of crashing on `installed[target][name]`.
+  const outdated = SUPPORTED_TARGETS.filter((target) => installed[target]).flatMap((target) => pluginNames
     .filter((name) => compareVersions(latestVersion[name], installed[target][name]) === 1)
     .map((name) => ({ target, name, installed: installed[target][name], latest: latestVersion[name] })));
+  const notInstalled = SUPPORTED_TARGETS.filter((target) => !installed[target]);
   const latestSignature = JSON.stringify(latestVersion);
   if (outdated.length === 0 || cache.offeredVersion === latestSignature) {
-    return { latestVersion, installed, outdated };
+    return { latestVersion, installed, outdated, notInstalled };
   }
 
   if (!interactive) {
-    return { latestVersion, installed, outdated, promptSuppressed: true };
+    return { latestVersion, installed, outdated, notInstalled, promptSuppressed: true };
   }
 
+  // All output below is advisory/interactive (header + prompts), and this check runs
+  // automatically ahead of most commands (see bin/empirical.js), so it must never land on
+  // stdout: any command whose stdout contract is machine-parsed (e.g. `memory query`) would
+  // otherwise get this header and prompt text as preamble ahead of its JSON. Route it through
+  // stderr instead -- ask()/askYesNo() already accept an output-stream parameter for this.
   // latestVersion is a map of pluginName -> version (e.g. {'empirical-memory': '1.1.2', ...}),
   // not a single scalar -- interpolating it directly stringified to "[object Object]". Prefer
   // the core plugin's version since that's the one most users recognize; the per-target
   // breakdown line right below already lists every outdated plugin/version precisely.
   const headlineVersion = latestVersion['empirical-memory'] || Object.values(latestVersion)[0] || 'update available';
-  log(uiHeader(`A newer empirical-memory plugin is available (${headlineVersion}).`));
-  log(`Installed versions: ${outdated.map((item) => `${item.target} ${item.name} ${item.installed} -> ${item.latest}`).join(', ')}`);
-  const update = await askYesNo('Update the native plugin now?', true);
+  warn(uiHeader(`A newer empirical-memory plugin is available (${headlineVersion}).`));
+  warn(`Installed versions: ${outdated.map((item) => `${item.target} ${item.name} ${item.installed} -> ${item.latest}`).join(', ')}`);
+  const update = await askYesNo('Update the native plugin now?', true, process.stderr);
   if (!update) {
     config.pluginUpdates = { ...config.pluginUpdates, offeredVersion: latestSignature, outcome: 'declined' };
     writeDeviceConfig(config);
-    return { latestVersion, installed, outdated, declined: true };
+    return { latestVersion, installed, outdated, notInstalled, declined: true };
   }
-  const selection = (await ask('Which agents should be updated? (all, or numbers 1-' + outdated.length + ') ')).trim().toLowerCase();
+  const selection = (await ask('Which agents should be updated? (all, or numbers 1-' + outdated.length + ') ', process.stderr)).trim().toLowerCase();
   const outdatedTargets = [...new Set(outdated.map((item) => item.target))];
   const selectedTargets = selection === 'all' || !selection
     ? outdatedTargets
@@ -133,7 +166,7 @@ async function checkNativePluginUpdates({ force = false, interactive = process.s
   }
   config.pluginUpdates = { ...config.pluginUpdates, offeredVersion: latestSignature, outcome: results };
   writeDeviceConfig(config);
-  return { latestVersion, installed, outdated, results };
+  return { latestVersion, installed, outdated, notInstalled, results };
 }
 
 module.exports = {
@@ -142,6 +175,7 @@ module.exports = {
   parseVersion,
   compareVersions,
   extractVersion,
+  readInstalledVersions,
   shouldCheck,
   fetchLatestVersions,
   checkNativePluginUpdates

package/lib/skillPaths.js

@@ -0,0 +1,25 @@
+'use strict';
+
+// Per-agent skill file path conventions, mirrored exactly from the hardcoded paths already used
+// by installers/claude.js, installers/codex.js, installers/copilot.js (for the single
+// empirical-memory skill) — parameterized by skill name instead of hardcoded to it.
+//
+// Split out of skillSync.js into its own dependency-free module so both skillSync.js and
+// installers/nativePlugin.js (C-001's mode-aware Skill overwrite) can use the same path
+// convention without creating a require cycle: skillSync.js -> installers/detect.js ->
+// installers/claude.js|codex.js|copilot.js -> installers/nativePlugin.js would loop straight
+// back into skillSync.js if nativePlugin.js required it directly.
+const os = require('os');
+const path = require('path');
+
+function skillFilePath(targetId, skillName) {
+  const home = os.homedir();
+  if (targetId === 'claude') return path.join(home, '.claude', 'skills', skillName, 'SKILL.md');
+  if (targetId === 'codex') return path.join(home, '.agents', 'skills', skillName, 'SKILL.md');
+  if (targetId === 'copilot') return path.join(home, '.copilot', 'skills', skillName, 'SKILL.md');
+  return null;
+}
+
+module.exports = {
+  skillFilePath
+};

package/lib/skillSync.js

@@ -7,11 +7,10 @@
 const crypto = require('crypto');
 const fs = require('fs');
 const matter = require('gray-matter');
-const os = require('os');
 const path = require('path');
 const { httpJson } = require('./http');
 const { log, warn, createPrompter } = require('./ui');
-const { detectInstallTargets } = require('./installers/detect');
+const { detectInstallTargets } = require('./installers/detect');
 const {
   readDeviceConfig,
   writeDeviceConfig,
@@ -20,47 +19,40 @@ const {
   writeSyncManifest,
   readPendingReview,
   writePendingReview
-} = require('./deviceConfig');
-
-const SYNC_READ_MAX_ATTEMPTS = 2;
-const SYNC_READ_RETRY_DELAY_MS = 250;
-
-function isRetryableSyncReadError(error) {
-  if (error?.statusCode) return false;
-  return /socket hang up|ECONNRESET|ECONNREFUSED|ETIMEDOUT|EPIPE|ENOTFOUND|network/i.test(error?.message || '');
-}
-
-async function fetchSyncRead(url, headers, label) {
-  let lastError;
-  for (let attempt = 1; attempt <= SYNC_READ_MAX_ATTEMPTS; attempt += 1) {
-    try {
-      return await httpJson(url, 'GET', undefined, headers);
-    } catch (error) {
-      lastError = error;
-      if (attempt >= SYNC_READ_MAX_ATTEMPTS || !isRetryableSyncReadError(error)) break;
-      await new Promise((resolve) => setTimeout(resolve, SYNC_READ_RETRY_DELAY_MS));
-    }
-  }
-
-  const detail = lastError?.message || 'unknown request error';
-  const wrapped = new Error(`${label} request failed: ${detail}`);
-  if (lastError?.code) wrapped.code = lastError.code;
-  if (lastError?.statusCode) wrapped.statusCode = lastError.statusCode;
-  wrapped.cause = lastError;
-  throw wrapped;
-}
-
-// Per-agent skill file path conventions, mirrored exactly from the hardcoded paths already
-// used by installers/claude.js, installers/codex.js, installers/copilot.js (for the single
-// empirical-memory skill) — just parameterized by skill name instead of hardcoded to it.
-function skillFilePath(targetId, skillName) {
-  const home = os.homedir();
-  if (targetId === 'claude') return path.join(home, '.claude', 'skills', skillName, 'SKILL.md');
-  if (targetId === 'codex') return path.join(home, '.agents', 'skills', skillName, 'SKILL.md');
-  if (targetId === 'copilot') return path.join(home, '.copilot', 'skills', skillName, 'SKILL.md');
-  return null;
+} = require('./deviceConfig');
+
+const SYNC_READ_MAX_ATTEMPTS = 2;
+const SYNC_READ_RETRY_DELAY_MS = 250;
+
+function isRetryableSyncReadError(error) {
+  if (error?.statusCode) return false;
+  return /socket hang up|ECONNRESET|ECONNREFUSED|ETIMEDOUT|EPIPE|ENOTFOUND|network/i.test(error?.message || '');
+}
+
+async function fetchSyncRead(url, headers, label) {
+  let lastError;
+  for (let attempt = 1; attempt <= SYNC_READ_MAX_ATTEMPTS; attempt += 1) {
+    try {
+      return await httpJson(url, 'GET', undefined, headers);
+    } catch (error) {
+      lastError = error;
+      if (attempt >= SYNC_READ_MAX_ATTEMPTS || !isRetryableSyncReadError(error)) break;
+      await new Promise((resolve) => setTimeout(resolve, SYNC_READ_RETRY_DELAY_MS));
+    }
+  }
+
+  const detail = lastError?.message || 'unknown request error';
+  const wrapped = new Error(`${label} request failed: ${detail}`);
+  if (lastError?.code) wrapped.code = lastError.code;
+  if (lastError?.statusCode) wrapped.statusCode = lastError.statusCode;
+  wrapped.cause = lastError;
+  throw wrapped;
 }
 
+// skillFilePath moved to ./skillPaths.js (see that file for why) — re-exported below for
+// existing callers of skillSync.js that import it from here.
+const { skillFilePath } = require('./skillPaths');
+
 function hashContent(content) {
   return crypto.createHash('sha256').update(content, 'utf8').digest('hex');
 }
@@ -102,14 +94,14 @@ function buildSkillFileContent(skill) {
 // ────────────────────────────────────────────────────────────────────────────────────────
 // CRITICAL TRAP TO AVOID (see PRD US-011): the server's resolveBuiltin() (see
 // packages/server/src/services/sourceResolver.service.ts) currently returns ONE hardcoded
-// PLACEHOLDER Skill named `empirical-memory`, whose bodyMarkdown is literally
-// "Placeholder body — real content wiring is a later story." — it is NOT the native
-// empirical-memory plugin content. The plugin repository owns the real Skill, and native
-// agent plugin installers are responsible for installing it.
+// PLACEHOLDER Skill named `empirical-memory`, whose bodyMarkdown is literally
+// "Placeholder body — real content wiring is a later story." — it is NOT the native
+// empirical-memory plugin content. The plugin repository owns the real Skill, and native
+// agent plugin installers are responsible for installing it.
 //
-// If this generalized writer were allowed to write a resolved Skill named `empirical-memory`,
-// it would silently overwrite that real plugin file with the server's placeholder stub text on
-// every sync — a real regression for every existing user. So: any
+// If this generalized writer were allowed to write a resolved Skill named `empirical-memory`,
+// it would silently overwrite that real plugin file with the server's placeholder stub text on
+// every sync — a real regression for every existing user. So: any
 // resolved Skill named exactly `empirical-memory` is filtered out here, unconditionally,
 // before any writing/tracking/removal-consideration happens. A future story that finally
 // wires up real builtin content server-side (not this one) needs to revisit this filter.
@@ -352,10 +344,10 @@ async function performSync({ accessToken, baseUrl, dryRun = false, force = false
     }
 
     const versionUrl = new URL(`/api/v1/devices/${encodeURIComponent(deviceId)}/version`, baseUrl).toString();
-    const versionResponse = await fetchSyncRead(versionUrl, {
-      Authorization: `Bearer ${accessToken}`,
-      'x-empirical-surface': 'cli'
-    }, 'Kit version');
+    const versionResponse = await fetchSyncRead(versionUrl, {
+      Authorization: `Bearer ${accessToken}`,
+      'x-empirical-surface': 'cli'
+    }, 'Kit version');
     const versionData = (versionResponse && versionResponse.data) ? versionResponse.data : versionResponse;
     const version = versionData.version;
 
@@ -364,10 +356,10 @@ async function performSync({ accessToken, baseUrl, dryRun = false, force = false
     }
 
     const resolvedUrl = new URL(`/api/v1/devices/${encodeURIComponent(deviceId)}/resolved`, baseUrl).toString();
-    const resolvedResponse = await fetchSyncRead(resolvedUrl, {
-      Authorization: `Bearer ${accessToken}`,
-      'x-empirical-surface': 'cli'
-    }, 'Resolved Kit skills');
+    const resolvedResponse = await fetchSyncRead(resolvedUrl, {
+      Authorization: `Bearer ${accessToken}`,
+      'x-empirical-surface': 'cli'
+    }, 'Resolved Kit skills');
     const resolvedData = (resolvedResponse && resolvedResponse.data) ? resolvedResponse.data : resolvedResponse;
     const skills = filterOutEmpiricalMemory(resolvedData.skills);
     const tierSkipped = resolvedData.skipped || [];

package/package.json

@@ -1,7 +1,20 @@
 {
   "name": "@empirical-gauzza/cli",
-  "version": "1.0.19",
-  "description": "Empirical CLI installer and local MCP wiring helper",
+  "version": "1.0.21",
+  "description": "Persistent cross-tool memory for AI agents. Give Claude Code, Codex, Copilot, Cursor, and ChatGPT one shared memory: save project context once, recall it everywhere via CLI or MCP.",
+  "keywords": [
+    "memory",
+    "mcp",
+    "agent memory",
+    "ai memory",
+    "claude",
+    "chatgpt",
+    "model context protocol",
+    "persistent memory",
+    "claude-code",
+    "codex",
+    "knowledge base"
+  ],
   "type": "commonjs",
   "license": "MIT",
   "homepage": "https://empirical.gauzza.com/docs/cli-details",