@empirical-gauzza/cli 1.0.9

package/lib/oauthClient.js

@@ -0,0 +1,222 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { readJsonIfExists, writeFile, ensureDir } = require('./fsUtils');
+const { getEnv } = require('./env');
+const { runResolvedCommand } = require('./fsUtils');
+
+function getLocalOAuthClientPath() {
+  return path.join(os.homedir(), '.empirical', 'oauth-client.json');
+}
+
+function readStoredOAuthClient() {
+  const stored = readJsonIfExists(getLocalOAuthClientPath());
+  if (!stored || typeof stored !== 'object') return null;
+  const clientId = String(stored.clientId || '').trim();
+  if (!clientId) return null;
+  return {
+    clientId,
+    clientSecret: String(stored.clientSecret || '')
+  };
+}
+
+function writeStoredOAuthClient(clientId, clientSecret) {
+  const payload = {
+    clientId: String(clientId || '').trim(),
+    clientSecret: String(clientSecret || '').trim(),
+    updatedAt: new Date().toISOString()
+  };
+  writeFile(getLocalOAuthClientPath(), `${JSON.stringify(payload, null, 2)}\n`);
+}
+
+function clearStoredOAuthClient() {
+  const storePath = getLocalOAuthClientPath();
+  if (fs.existsSync(storePath)) {
+    fs.unlinkSync(storePath);
+  }
+}
+
+function maskSecret(value) {
+  const raw = String(value || '');
+  if (!raw) return '(not set)';
+  if (raw.length <= 8) return '*'.repeat(raw.length);
+  return `${raw.slice(0, 4)}...${raw.slice(-4)}`;
+}
+
+function generateRandomString(length = 32) {
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~';
+  let result = '';
+  for (let i = 0; i < length; i += 1) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return result;
+}
+
+function base64url(buf) {
+  return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+}
+
+function generatePKCE() {
+  const crypto = require('crypto');
+  const codeVerifier = generateRandomString(128);
+  const codeChallenge = base64url(crypto.createHash('sha256').update(codeVerifier).digest());
+  return { codeVerifier, codeChallenge };
+}
+
+function decodeJwtPayload(token) {
+  try {
+    const parts = String(token).split('.');
+    if (parts.length !== 3) return null;
+    return JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+  } catch (_error) {
+    return null;
+  }
+}
+
+function isJwtToken(token) {
+  return typeof token === 'string' && token.split('.').length === 3;
+}
+
+function isJwtExpired(token, skewSeconds = 30) {
+  const payload = decodeJwtPayload(token);
+  if (!payload || typeof payload.exp !== 'number') return true;
+  return payload.exp < Math.floor(Date.now() / 1000) + skewSeconds;
+}
+
+function getHeadlessTokenPath() {
+  return path.resolve(getEnv('EMPIRICAL_TOKEN_OUTPUT', '.empirical/headless-token.json'));
+}
+
+function getOAuthSessionPath() {
+  return path.join(os.homedir(), '.empirical', 'oauth-session.json');
+}
+
+function readOAuthSession() {
+  const session = readJsonIfExists(getOAuthSessionPath());
+  if (!session || typeof session !== 'object') return null;
+  return session;
+}
+
+function writeOAuthSession(session) {
+  if (!session?.accessToken) return;
+  writeFile(getOAuthSessionPath(), `${JSON.stringify(session, null, 2)}\n`);
+}
+
+function clearOAuthSession() {
+  const sessionPath = getOAuthSessionPath();
+  if (fs.existsSync(sessionPath)) fs.unlinkSync(sessionPath);
+}
+
+function readHeadlessToken() {
+  const tokenPath = getHeadlessTokenPath();
+  if (!fs.existsSync(tokenPath)) return null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(tokenPath, 'utf8'));
+    if (!parsed || typeof parsed !== 'object') {
+      return null;
+    }
+
+    const normalized = { ...parsed };
+    if (!normalized.clientId && normalized.authClientId) {
+      normalized.clientId = normalized.authClientId;
+    }
+    if (!normalized.clientSecret && normalized.authClientSecret) {
+      normalized.clientSecret = normalized.authClientSecret;
+    }
+    if (!normalized.apiKey) {
+      normalized.apiKey = normalized.clientSecret || normalized.authClientSecret || null;
+    }
+    return normalized;
+  } catch (_error) {
+    return null;
+  }
+}
+
+function getAccessTokenExpiryMs(token) {
+  if (!token || !token.accessToken) return 0;
+  const obtainedAtMs = Date.parse(String(token.obtainedAt || ''));
+  const expiresInSeconds = Number(token.expiresIn || 0);
+  if (!Number.isFinite(obtainedAtMs) || !Number.isFinite(expiresInSeconds) || expiresInSeconds <= 0) {
+    return 0;
+  }
+  return obtainedAtMs + (expiresInSeconds * 1000);
+}
+
+function hasFreshAccessToken(token, skewSeconds = 120) {
+  const expiryMs = getAccessTokenExpiryMs(token);
+  if (!expiryMs) return false;
+  return expiryMs > (Date.now() + (skewSeconds * 1000));
+}
+
+function persistAccessToken(accessToken) {
+  if (!accessToken) return;
+  process.env.EMPIRICAL_ACCESS_TOKEN = accessToken;
+  if (process.platform !== 'win32') {
+    return;
+  }
+  // `setx` writes permanently into the user's Windows environment, surviving
+  // every future shell/process. Only do that for a genuinely permanent
+  // credential (a plain apiKey) — a short-lived session JWT written here
+  // would silently outlive its own expiry and shadow a valid apiKey in the
+  // token file for good, forcing a manual env-var reset roughly every hour.
+  if (isJwtToken(accessToken)) {
+    return;
+  }
+  const escaped = String(accessToken).replace(/\"/g, '""');
+  runResolvedCommand('setx', ['EMPIRICAL_ACCESS_TOKEN', escaped], { stdio: 'ignore' });
+}
+
+function toEnvSafe(value) {
+  return String(value ?? '')
+    .replace(/\\/g, '\\\\')
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r')
+    .replace(/"/g, '\\"');
+}
+
+function writeHeadlessEnvFile(result, outputPath) {
+  ensureDir(path.dirname(path.resolve(outputPath)));
+  // Prefer the API key as the access token — it never expires and works as a
+  // permanent Bearer credential with the MCP endpoint.
+  const permanentToken = result.apiKey || result.accessToken;
+  const lines = [
+    '# Generated by empirical cli',
+    `EMPIRICAL_BASE_URL="${toEnvSafe(result.baseUrl)}"`,
+    `EMPIRICAL_ACCESS_TOKEN="${toEnvSafe(permanentToken)}"`,
+    `EMPIRICAL_API_KEY="${toEnvSafe(result.apiKey || '')}"`,
+    `EMPIRICAL_REFRESH_TOKEN="${toEnvSafe(result.refreshToken || '')}"`,
+    `EMPIRICAL_CLIENT_ID="${toEnvSafe(result.clientId || '')}"`,
+    `EMPIRICAL_CLIENT_SECRET="${toEnvSafe(result.clientSecret || '')}"`,
+    `EMPIRICAL_TOKEN_TYPE="${toEnvSafe(result.tokenType || 'Bearer')}"`,
+    `EMPIRICAL_TOKEN_OBTAINED_AT="${toEnvSafe(result.obtainedAt || '')}"`,
+    `EMPIRICAL_TOKEN_EXPIRES_IN="${toEnvSafe(result.expiresIn || '')}"`
+  ];
+  fs.writeFileSync(path.resolve(outputPath), `${lines.join('\n')}\n`, 'utf8');
+}
+
+module.exports = {
+  getLocalOAuthClientPath,
+  readStoredOAuthClient,
+  writeStoredOAuthClient,
+  clearStoredOAuthClient,
+  maskSecret,
+  generateRandomString,
+  base64url,
+  generatePKCE,
+  decodeJwtPayload,
+  isJwtToken,
+  isJwtExpired,
+  getHeadlessTokenPath,
+  getOAuthSessionPath,
+  readOAuthSession,
+  writeOAuthSession,
+  clearOAuthSession,
+  readHeadlessToken,
+  getAccessTokenExpiryMs,
+  hasFreshAccessToken,
+  persistAccessToken,
+  toEnvSafe,
+  writeHeadlessEnvFile
+};

package/lib/pluginCommands.js

@@ -0,0 +1,81 @@
+'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
+};

package/lib/pluginUpdateCheck.js

@@ -0,0 +1,143 @@
+'use strict';
+
+const { askYesNo, ask, log, warn, uiHeader, parseSelection } = require('./ui');
+const { runResolvedCommand, commandExists, summarizeProcessOutput } = require('./fsUtils');
+const { readDeviceConfig, writeDeviceConfig } = require('./deviceConfig');
+const { installNativePlugin } = require('./installers/nativePlugin');
+
+const PLUGIN_METADATA_URL = 'https://raw.githubusercontent.com/mattgauzza/empirical-memory-plugin/main/.claude-plugin/marketplace.json';
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const SUPPORTED_TARGETS = ['codex', 'claude', 'copilot'];
+
+function parseVersion(value) {
+  const match = String(value || '').trim().match(/^v?(\d+)\.(\d+)\.(\d+)/i);
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function compareVersions(left, right) {
+  const a = parseVersion(left);
+  const b = parseVersion(right);
+  if (!a || !b) return null;
+  for (let i = 0; i < 3; i += 1) {
+    if (a[i] !== b[i]) return a[i] > b[i] ? 1 : -1;
+  }
+  return 0;
+}
+
+function extractVersion(output, pluginName = 'empirical-memory') {
+  const text = String(output || '');
+  const jsonCandidates = [text, ...text.split(/\r?\n/).map((line) => line.trim())];
+  for (const candidate of jsonCandidates) {
+    try {
+      const value = JSON.parse(candidate);
+      const rows = Array.isArray(value) ? value : [value, ...(Array.isArray(value?.plugins) ? value.plugins : [])];
+      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.
+    }
+  }
+  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;
+}
+
+function readInstalledVersions(target, pluginNames) {
+  const commands = {
+    codex: ['codex', ['plugin', 'list']],
+    claude: ['claude', ['plugin', 'list']],
+    copilot: ['copilot', ['plugin', 'list']]
+  };
+  const [command, args] = commands[target];
+  if (!commandExists(command)) return null;
+  const result = runResolvedCommand(command, args, { stdio: 'pipe' });
+  if (!result || result.status !== 0) return null;
+  const output = `${result.stdout || ''}\n${result.stderr || ''}`;
+  return Object.fromEntries(pluginNames.map((name) => [name, extractVersion(output, name)]));
+}
+
+async function fetchLatestVersions(fetchImpl = globalThis.fetch) {
+  if (typeof fetchImpl !== 'function') return null;
+  const response = await fetchImpl(PLUGIN_METADATA_URL, { signal: AbortSignal.timeout(5000) });
+  if (!response.ok) throw new Error(`marketplace metadata returned HTTP ${response.status}`);
+  const data = await response.json();
+  if (Array.isArray(data?.plugins)) {
+    return Object.fromEntries(data.plugins.map((plugin) => [plugin.name, plugin.version]).filter(([, version]) => version));
+  }
+  return data?.version ? { 'empirical-memory': data.version } : {};
+}
+
+function shouldCheck(cache, now = Date.now(), force = false) {
+  return force || !cache?.checkedAt || now - Number(cache.checkedAt) >= CHECK_INTERVAL_MS;
+}
+
+async function checkNativePluginUpdates({ force = false, interactive = process.stdin.isTTY, fetchImpl } = {}) {
+  if (!interactive && !force) return { skipped: true, reason: 'noninteractive' };
+  const config = readDeviceConfig();
+  const cache = config.pluginUpdates || {};
+  if (!shouldCheck(cache, Date.now(), force)) return { skipped: true, reason: 'rate_limited' };
+
+  let latestVersion;
+  try {
+    latestVersion = await fetchLatestVersions(fetchImpl);
+  } catch (error) {
+    config.pluginUpdates = { ...cache, checkedAt: Date.now(), lastError: error.message };
+    writeDeviceConfig(config);
+    return { skipped: true, reason: 'marketplace_unavailable' };
+  }
+  const pluginNames = Object.keys(latestVersion);
+  const installed = {};
+  for (const target of SUPPORTED_TARGETS) installed[target] = readInstalledVersions(target, pluginNames);
+  config.pluginUpdates = { checkedAt: Date.now(), latestVersions: latestVersion, installed };
+  writeDeviceConfig(config);
+
+  const outdated = SUPPORTED_TARGETS.flatMap((target) => pluginNames
+    .filter((name) => compareVersions(latestVersion[name], installed[target][name]) === 1)
+    .map((name) => ({ target, name, installed: installed[target][name], latest: latestVersion[name] })));
+  const latestSignature = JSON.stringify(latestVersion);
+  if (outdated.length === 0 || cache.offeredVersion === latestSignature) {
+    return { latestVersion, installed, outdated };
+  }
+
+  if (!interactive) {
+    return { latestVersion, installed, outdated, promptSuppressed: true };
+  }
+
+  log(uiHeader(`A newer empirical-memory plugin is available (${latestVersion}).`));
+  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);
+  if (!update) {
+    config.pluginUpdates = { ...config.pluginUpdates, offeredVersion: latestSignature, outcome: 'declined' };
+    writeDeviceConfig(config);
+    return { latestVersion, installed, outdated, declined: true };
+  }
+  const selection = (await ask('Which agents should be updated? (all, or numbers 1-' + outdated.length + ') ')).trim().toLowerCase();
+  const outdatedTargets = [...new Set(outdated.map((item) => item.target))];
+  const selectedTargets = selection === 'all' || !selection
+    ? outdatedTargets
+    : parseSelection(selection, outdatedTargets.length).map((index) => outdatedTargets[index]);
+  const results = {};
+  for (const target of selectedTargets) {
+    try {
+      installNativePlugin(target, [...new Set(outdated.filter((item) => item.target === target).map((item) => item.name))]);
+      results[target] = 'updated';
+    } catch (error) {
+      results[target] = `failed: ${summarizeProcessOutput({ stderr: error.message })}`;
+      warn(`Could not update ${target}: ${error.message}`);
+    }
+  }
+  config.pluginUpdates = { ...config.pluginUpdates, offeredVersion: latestSignature, outcome: results };
+  writeDeviceConfig(config);
+  return { latestVersion, installed, outdated, results };
+}
+
+module.exports = {
+  CHECK_INTERVAL_MS,
+  SUPPORTED_TARGETS,
+  parseVersion,
+  compareVersions,
+  extractVersion,
+  shouldCheck,
+  fetchLatestVersions,
+  checkNativePluginUpdates
+};

package/lib/policyCommands.js

@@ -0,0 +1,144 @@
+'use strict';
+
+const { log, warn } = require('./ui');
+const { httpJson, printApiError } = require('./http');
+const { parseOption } = require('./env');
+const { requireAccessToken, resolveApiBaseUrl, buildApiAuthHeaders } = require('./auth');
+const { readPolicyCache, writePolicyCache } = require('./deviceConfig');
+
+const POLICY_CACHE_TTL_MS = 15 * 60 * 1000;
+
+function policyUrl(baseUrl) {
+  return new URL('/api/v1/users/me/empirical-policy', baseUrl).toString();
+}
+
+function isPolicyCacheFresh(cache, now = Date.now()) {
+  return Boolean(
+    cache &&
+    cache.policy &&
+    cache.updatedAt &&
+    now - new Date(cache.cachedAt || 0).getTime() < POLICY_CACHE_TTL_MS
+  );
+}
+
+async function fetchPolicy({ force = false } = {}) {
+  const cached = readPolicyCache();
+  if (!force && isPolicyCacheFresh(cached)) return { ...cached, source: 'cache' };
+
+  const accessToken = requireAccessToken();
+  const response = await httpJson(
+    policyUrl(resolveApiBaseUrl()),
+    'GET',
+    null,
+    buildApiAuthHeaders(accessToken)
+  );
+  const data = response?.data || response;
+  const next = {
+    policy: data.policy || {},
+    policyVersion: data.policyVersion || 1,
+    updatedAt: data.updatedAt || null,
+    cachedAt: new Date().toISOString()
+  };
+  writePolicyCache(next);
+  return { ...next, source: 'remote' };
+}
+
+function policyFromInstallerOptions(options = {}) {
+  return {
+    memoryFirstWorkflows: options.requireMemoryInWorkflows === false
+      ? []
+      : (options.requiredWorkflows || []),
+    allowDiscretionaryUse: options.allowDiscretionaryMemoryUsage !== false,
+    stopOnMemoryFailure: options.stopOnMemoryToolFailure !== false,
+    rememberCodingStyle: options.rememberCodingStyle !== false,
+    rememberArchitectureDecisions: options.rememberArchitectureDecisions !== false,
+    recordWorkHistory: options.recordWorkHistory !== false,
+    recordScarTissue: options.recordScarTissue !== false,
+    recordTodos: options.recordTodos === true,
+    storeInstructionArtifacts: options.storeInstructionArtifacts === true,
+    checkMemoryBeforeAskingContext: options.checkMemoryBeforeAskingContext !== false,
+    durableWritesOnly: options.durableWritesOnly !== false
+  };
+}
+
+async function savePolicy(policy, accessTokenOverride = null) {
+  const accessToken = accessTokenOverride || requireAccessToken();
+  const response = await httpJson(
+    policyUrl(resolveApiBaseUrl()),
+    'PATCH',
+    { policy },
+    buildApiAuthHeaders(accessToken)
+  );
+  const data = response?.data || response;
+  writePolicyCache({
+    policy: data.policy || {},
+    policyVersion: data.policyVersion || 1,
+    updatedAt: data.updatedAt || null,
+    cachedAt: new Date().toISOString()
+  });
+  return data;
+}
+
+async function runPolicyCommand(args = []) {
+  const subcommand = args[0] || 'show';
+  if (subcommand === 'show') {
+    try {
+      const result = await fetchPolicy({ force: args.includes('--refresh') });
+      log(JSON.stringify(result, null, 2));
+    } catch (error) {
+      printApiError(error);
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (subcommand === 'set') {
+    const raw = parseOption(args, '--json', '');
+    if (!raw) {
+      warn('Usage: empirical policy set --json \'{"allowDiscretionaryUse":false}\'');
+      process.exitCode = 1;
+      return;
+    }
+    let policy;
+    try {
+      policy = JSON.parse(raw);
+    } catch (error) {
+      warn(`Invalid policy JSON: ${error.message}`);
+      process.exitCode = 1;
+      return;
+    }
+    try {
+      const accessToken = requireAccessToken();
+      const response = await httpJson(
+        policyUrl(resolveApiBaseUrl()),
+        'PATCH',
+        { policy },
+        buildApiAuthHeaders(accessToken)
+      );
+      const data = response?.data || response;
+      writePolicyCache({
+        policy: data.policy || {},
+        policyVersion: data.policyVersion || 1,
+        updatedAt: data.updatedAt || null,
+        cachedAt: new Date().toISOString()
+      });
+      log(JSON.stringify(data, null, 2));
+    } catch (error) {
+      printApiError(error);
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  warn('Usage: empirical policy <show [--refresh]|set --json <policy>>');
+  process.exitCode = 1;
+}
+
+module.exports = {
+  POLICY_CACHE_TTL_MS,
+  isPolicyCacheFresh,
+  policyFromInstallerOptions,
+  fetchPolicy,
+  savePolicy,
+  runPolicyCommand
+};