@empirical-gauzza/cli 1.0.9

package/lib/doctor.js

@@ -0,0 +1,116 @@
+'use strict';
+
+const { log, warn, ANSI, colorize, supportsColor } = require('./ui');
+const { httpJson } = require('./http');
+const { parseOption } = require('./env');
+const { resolveAccessToken, resolveApiBaseUrl, buildApiAuthHeaders } = require('./auth');
+const { withCliAnalyticsContext } = require('./memoryCommands');
+
+async function runDoctor(args) {
+  return withCliAnalyticsContext({ command: 'doctor' }, async () => {
+    const outputJson = parseOption(args, '--output', '') === 'json';
+    const checks = [];
+    let overallFail = false;
+    let overallWarn = false;
+
+    function addCheck(name, status, message) {
+      checks.push({ name, status, message });
+      if (status === 'fail') overallFail = true;
+      if (status === 'warn') overallWarn = true;
+    }
+
+    const token = resolveAccessToken();
+    if (!token) {
+      addCheck('token_presence', 'fail', 'No access token found. Run: empirical auth login, or configure headless credentials with empirical oauth bootstrap headless.');
+    } else {
+      addCheck('token_presence', 'ok', 'Access token found.');
+    }
+
+    let tokenType = null;
+    if (token) {
+      const parts = token.split('.');
+      if (parts.length === 3) {
+        tokenType = 'jwt';
+        addCheck('token_type', 'ok', 'Token is a JWT (3-part).');
+      } else {
+        tokenType = 'apikey';
+        addCheck('token_type', 'ok', 'Token is an API key (long alphanumeric).');
+      }
+    } else {
+      addCheck('token_type', 'fail', 'Cannot determine token type — no token found.');
+    }
+
+    if (token && tokenType === 'jwt') {
+      const parts = token.split('.');
+      try {
+        const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+        if (payload && typeof payload.exp === 'number') {
+          const nowSec = Math.floor(Date.now() / 1000);
+          if (payload.exp < nowSec) {
+            addCheck('token_expiry', 'fail', `Token expired at ${new Date(payload.exp * 1000).toISOString()}.`);
+          } else {
+            const remaining = payload.exp - nowSec;
+            addCheck('token_expiry', 'ok', `Token expires in ${remaining}s (at ${new Date(payload.exp * 1000).toISOString()}).`);
+          }
+        } else {
+          addCheck('token_expiry', 'warn', 'JWT has no `exp` claim — expiry unknown.');
+        }
+      } catch (_error) {
+        addCheck('token_expiry', 'warn', 'Could not decode JWT payload — expiry unknown.');
+      }
+    } else if (token && tokenType === 'apikey') {
+      addCheck('token_expiry', 'ok', 'API key — no expiry.');
+    }
+
+    let userData = null;
+    if (token) {
+      const baseUrl = resolveApiBaseUrl();
+      const meUrl = new URL('/api/v1/users/me', baseUrl).toString();
+      try {
+        const response = await httpJson(meUrl, 'GET', null, buildApiAuthHeaders(token));
+        userData = (response && response.data) ? response.data : response;
+        addCheck('api_connectivity', 'ok', `Connected. User: ${userData.email || userData.userId || 'unknown'}.`);
+      } catch (error) {
+        addCheck('api_connectivity', 'fail', `API request failed: ${error.message}`);
+      }
+    } else {
+      addCheck('api_connectivity', 'fail', 'Skipped — no token available.');
+    }
+
+    if (userData) {
+      const wsId = userData.workspaceId || userData.workspaceName || null;
+      if (wsId) {
+        addCheck('workspace', 'ok', `Workspace ID: ${wsId}.`);
+      } else {
+        addCheck('workspace', 'warn', 'No active workspace — using default brain.');
+      }
+    } else {
+      addCheck('workspace', 'fail', 'Skipped — API connectivity check failed.');
+    }
+
+    const overall = overallFail ? 'fail' : (overallWarn ? 'warn' : 'ok');
+
+    if (outputJson) {
+      log(JSON.stringify({ checks, overall }));
+    } else {
+      const statusLabel = (status) => {
+        if (status === 'ok') return colorize(ANSI.green, '[OK]  ');
+        if (status === 'warn') return colorize(ANSI.yellow, '[WARN]');
+        return colorize(ANSI.red, '[FAIL]');
+      };
+      for (const check of checks) {
+        log(`${statusLabel(check.status)} ${check.name.padEnd(20)} ${check.message}`);
+      }
+      log('');
+      log(`Overall: ${overall.toUpperCase()}`);
+    }
+
+    if (overallFail) {
+      process.exitCode = 1;
+    }
+  });
+}
+
+module.exports = {
+  runDoctor
+};

package/lib/env.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const { ask } = require('./ui');
+
+function getEnv(name, fallback = '') {
+  return String(process.env[name] ?? fallback).trim();
+}
+
+function requireEnv(name) {
+  const value = getEnv(name);
+  if (!value) {
+    throw new Error(`Missing required env var: ${name}`);
+  }
+  return value;
+}
+
+async function resolveRequiredValueFromEnvOrPrompt(envName, promptLabel) {
+  const value = getEnv(envName);
+  if (value) return value;
+
+  if (!process.stdin.isTTY) {
+    throw new Error(`Missing required env var: ${envName}`);
+  }
+
+  const answer = (await ask(`${promptLabel}: `)).trim();
+  if (!answer) {
+    throw new Error(`${promptLabel} is required`);
+  }
+
+  return answer;
+}
+
+function parseFlag(args, flagName) {
+  return args.includes(flagName);
+}
+
+function parseOption(args, optionName, fallback = '') {
+  const index = args.indexOf(optionName);
+  if (index === -1) return fallback;
+  return String(args[index + 1] || '').trim() || fallback;
+}
+
+module.exports = {
+  getEnv,
+  requireEnv,
+  resolveRequiredValueFromEnvOrPrompt,
+  parseFlag,
+  parseOption
+};

package/lib/fsUtils.js

@@ -0,0 +1,90 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function commandExists(cmd) {
+  if (process.platform === 'win32') {
+    const escaped = cmd.replace(/'/g, "''");
+    const script = `if (Get-Command '${escaped}' -ErrorAction SilentlyContinue) { exit 0 } else { exit 1 }`;
+    const result = spawnSync('pwsh', ['-NoProfile', '-Command', script], { stdio: 'ignore' });
+    return result.status === 0;
+  }
+  const result = spawnSync('which', [cmd], { stdio: 'ignore' });
+  return result.status === 0;
+}
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function readUtf8IfExists(filePath) {
+  if (!fs.existsSync(filePath)) return '';
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+function readJsonIfExists(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (_error) {
+    return null;
+  }
+}
+
+function writeFile(filePath, content) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, content, 'utf8');
+}
+
+function quotePowerShellArg(value) {
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
+
+function runResolvedCommand(command, args, options = {}) {
+  // `input`, when given, is piped to the child's stdin (e.g. `crontab -` on Linux, which reads
+  // the new crontab body from stdin) — spawnSync ignores `stdio` in that case and manages stdin
+  // itself, so we only pass the `stdio` option through when there's no `input` to feed.
+  const { input } = options;
+  const stdio = options.stdio || 'inherit';
+
+  if (process.platform !== 'win32') {
+    return spawnSync(command, args, {
+      encoding: 'utf8',
+      ...(input !== undefined ? { input } : { stdio })
+    });
+  }
+
+  const script = `& ${quotePowerShellArg(command)} ${args.map(quotePowerShellArg).join(' ')}`;
+  return spawnSync('pwsh', ['-NoProfile', '-Command', script], {
+    encoding: 'utf8',
+    ...(input !== undefined ? { input } : { stdio })
+  });
+}
+
+function summarizeProcessOutput(result) {
+  if (result.error) {
+    return String(result.error.message || result.error);
+  }
+  const stdout = (result.stdout || '').trim();
+  const stderr = (result.stderr || '').trim();
+  const lines = [stderr, stdout]
+    .filter(Boolean)
+    .join('\n')
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .slice(0, 8);
+  return lines.join(' | ');
+}
+
+module.exports = {
+  commandExists,
+  ensureDir,
+  readUtf8IfExists,
+  readJsonIfExists,
+  writeFile,
+  quotePowerShellArg,
+  runResolvedCommand,
+  summarizeProcessOutput
+};

package/lib/help.js

@@ -0,0 +1,113 @@
+'use strict';
+
+const { log } = require('./ui');
+const { version } = require('../package.json');
+
+function showVersion() {
+  log(version);
+}
+
+function showHelp() {
+  log('Empirical CLI');
+  log(`Version: ${version}`);
+  log('');
+  log('Usage:');
+  log('  empirical install');
+  log('  empirical -install');
+  log('  empirical --install');
+  log('  empirical plugin install <codex|copilot|claude|all> [--all-optional]');
+  log('  empirical plugin check [--force]');
+  log('  empirical policy show [--refresh]');
+  log('  empirical policy set --json <policy>');
+  log('  empirical auth login');
+  log('  empirical auth logout');
+  log('  empirical oauth bootstrap headless [--print-access-token]');
+  log('  empirical oauth bootstrap headless --write-env [--env-output <path>]');
+  log('  empirical oauth refresh headless [--print-access-token]');
+  log('  empirical oauth refresh headless --write-env [--env-output <path>]');
+  log('  empirical oauth bootstrap docker [--print-access-token]');
+  log('  empirical oauth refresh docker [--print-access-token]');
+  log('  empirical oauth client set [--client-id <id>] [--client-secret <secret>]');
+  log('  empirical oauth client show');
+  log('  empirical oauth client clear');
+  log('  empirical workspace list');
+  log('  empirical workspace current');
+  log('  empirical workspace select [<number|name>]');
+  log('  empirical workspace use <number|name|id>');
+  log('  empirical workspace create <name> [--description <text>]');
+  log('  empirical workspace invite create [--role reader|writer|manager] [--expires-in-days <n>] [--max-uses <n>]');
+  log('  empirical workspace invite list');
+  log('  empirical workspace invite revoke <token>');
+  log('  empirical workspace delete <number|name|id> [--confirm]');
+  log('  empirical oauth bootstrap openclaw [--print-access-token]   (legacy alias)');
+  log('  empirical oauth refresh openclaw [--print-access-token]     (legacy alias)');
+  log('  empirical --oauth-bootstrap-headless [--print-access-token]');
+  log('  empirical --oauth-refresh-headless [--print-access-token]');
+  log('  empirical --oauth-bootstrap-openclaw [--print-access-token] (legacy alias)');
+  log('  empirical --oauth-refresh-openclaw [--print-access-token]   (legacy alias)');
+  log('');
+  log('Options:');
+  log('  install, -install, --install   Interactive installer for Codex/Copilot/Claude CLI integration');
+  log('  plugin install <target>        Install core plugin; add --all-optional or capability flags');
+  log('  plugin check [--force]         Check for native plugin updates');
+  log('  policy show/set                Inspect or update native Empirical behavior policy');
+  log('                       Step 1 checks/provisions OAuth client credentials locally');
+  log('  --oauth-bootstrap-headless, --oauth-bootstrap-openclaw');
+  log('                       Headless OAuth bootstrap using client_credentials (client ID + client secret)');
+  log('  --oauth-refresh-headless, --oauth-refresh-openclaw');
+  log('                       Refresh headless token from stored refresh token file (if available)');
+  log('  --client-id <id>      Client ID override for headless bootstrap');
+  log('  --client-secret <sec> Client secret override for headless bootstrap');
+  log('  --print-access-token Print only access token (for scripting)');
+  log('  --write-env          Write a dotenv file for container startup');
+  log('  --env-output <path>  Env output path (default: .empirical/headless.env)');
+  log('  oauth client set     Persist OAuth client credentials at ~/.empirical/oauth-client.json');
+  log('  oauth client show    Show the currently saved OAuth client id/secret mask');
+  log('  oauth client clear   Remove saved OAuth client credentials');
+  log('  -h, --help            Show help');
+  log('  -v, --version         Show CLI version');
+  log('');
+  log('Docs & Agent Skills:');
+  log('  empirical doc                    List available documentation topics');
+  log('  empirical doc <topic>            Print agent-readable instructions for a topic');
+  log('  empirical doctor                 Check token, API connectivity, and workspace status');
+  log('  empirical memory query           Search memories by natural language');
+  log('  empirical memory get             Retrieve one memory by exact ID');
+  log('  empirical memory list            Browse memories with filters and pagination');
+  log('  empirical memory record          Save a new memory');
+  log('  empirical memory note            Add a note to an existing memory');
+  log('  empirical memory update          Update an existing memory');
+  log('  empirical memory delete          Delete an existing memory');
+  log('  empirical memory duplicates      List duplicate candidates for a memory');
+  log('  empirical memory merge           Merge a duplicate memory into a canonical one');
+  log('  empirical memory export          Export memories as portable JSON [--scope <personal|workspace>] [--out <path>]');
+  log('  empirical kit create <name>      Create a new Kit [--workspace <workspaceId>]');
+  log('  empirical kit add-source <kit> <git-url>');
+  log('                                   Add a git Source to a Kit [--ref <ref>] [--path <subpath>]');
+  log('  empirical kit remove-source <kit> <source-id>');
+  log('                                   Remove a Source (and its Skills) from a Kit');
+  log('  empirical kit list               List Kits owned by the current user');
+  log('  empirical kit autosync <kit> on|off');
+  log('                                   Enable/disable auto-sync for a Kit');
+  log('  empirical kit devices <kit>      List devices registered to a Kit');
+  log('  empirical kit deactivate <kit> <deviceId>');
+  log('                                   Deactivate a device on a Kit');
+  log('  empirical kit use <kit>          Activate a named Kit on this device and sync [--dry-run] [--quiet] [--force]');
+  log('  empirical kit sync               Sync the active Kit\'s Skills into detected agents [--dry-run] [--quiet] [--force]');
+  log('  empirical skill list              List Skills across owned Kits');
+  log('  empirical skill push <path/to/SKILL.md>');
+  log('                                   Push a local SKILL.md as an authored Skill [--kit <kitId>]');
+  log('                                   Wrote or edited a SKILL.md? Push it so it follows you');
+  log('                                   across machines/projects instead of staying local.');
+  log('  empirical skill history <authoredSkillId>');
+  log('                                   Show version history for an authored Skill');
+  log('  empirical skill rollback <authoredSkillId> --to-version <n>');
+  log('                                   Roll an authored Skill back to a prior version');
+  log('  empirical device list             List registered devices and active Kits');
+  log('  empirical device show <deviceId>  Show effective Skills for a device');
+}
+
+module.exports = {
+  showHelp,
+  showVersion
+};

package/lib/http.js

@@ -0,0 +1,179 @@
+'use strict';
+
+const http = require('http');
+const https = require('https');
+const { warn } = require('./ui');
+
+function httpGet(urlString, timeoutMs = 8000) {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(urlString);
+    const lib = parsed.protocol === 'https:' ? https : http;
+    const req = lib.request(
+      parsed,
+      {
+        method: 'GET',
+        headers: {
+          'User-Agent': 'empirical-installer/1.0'
+        }
+      },
+      (res) => {
+        let body = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => {
+          body += chunk;
+        });
+        res.on('end', () => {
+          resolve({
+            statusCode: res.statusCode || 0,
+            headers: res.headers || {},
+            body
+          });
+        });
+      }
+    );
+
+    req.setTimeout(timeoutMs, () => {
+      req.destroy(new Error('request timeout'));
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+function httpErrorFromResponse(method, urlString, statusCode, data) {
+  const baseMsg = data.error_description || data.message || data.error || `HTTP ${statusCode}`;
+  const upgradeUrl = data.upgrade_url || data.details?.upgradeUrl || null;
+  const retryAfterSeconds = data.retry_after_seconds ?? null;
+
+  const parts = [`${method} ${urlString} failed: ${baseMsg}`];
+  if (retryAfterSeconds != null) parts.push(`Retry after ${retryAfterSeconds}s.`);
+  if (upgradeUrl) parts.push(`Upgrade: ${upgradeUrl}`);
+
+  const error = new Error(parts.join(' '));
+  error.statusCode = statusCode;
+  error.code = data.code || null;
+  error.upgradeUrl = upgradeUrl;
+  error.retryAfterSeconds = retryAfterSeconds;
+  return error;
+}
+
+// Prints a structured JSON error line to stderr so scripts/agents parsing CLI
+// output can branch on `code` (e.g. RATE_LIMITED, PLAN_LIMIT_MEMORY_REACHED)
+// and act on `upgradeUrl`/`retryAfterSeconds` without string-parsing `message`.
+function printApiError(error) {
+  warn(JSON.stringify({
+    error: true,
+    code: error.code || 'api_error',
+    message: error.message,
+    ...(error.retryAfterSeconds != null && { retryAfterSeconds: error.retryAfterSeconds }),
+    ...(error.upgradeUrl && { upgradeUrl: error.upgradeUrl })
+  }));
+}
+
+function httpJson(urlString, method, payload, headers = {}, timeoutMs = 0) {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(urlString);
+    const lib = parsed.protocol === 'https:' ? https : http;
+    const body = payload ? JSON.stringify(payload) : null;
+
+    const req = lib.request(
+      parsed,
+      {
+        method,
+        headers: {
+          Accept: 'application/json',
+          ...(body ? { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) } : {}),
+          ...headers
+        }
+      },
+      (res) => {
+        let raw = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => {
+          raw += chunk;
+        });
+        res.on('end', () => {
+          let data = {};
+          try {
+            data = raw ? JSON.parse(raw) : {};
+          } catch (_error) {
+            data = { raw };
+          }
+
+          const statusCode = res.statusCode || 0;
+          if (statusCode < 200 || statusCode >= 300) {
+            reject(httpErrorFromResponse(method, urlString, statusCode, data));
+            return;
+          }
+
+          resolve(data);
+        });
+      }
+    );
+
+    req.on('error', reject);
+    if (Number.isFinite(timeoutMs) && timeoutMs > 0) {
+      req.setTimeout(timeoutMs, () => {
+        req.destroy(new Error(`request timeout after ${timeoutMs}ms`));
+      });
+    }
+    if (body) req.write(body);
+    req.end();
+  });
+}
+
+function httpForm(urlString, method, params, headers = {}) {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(urlString);
+    const lib = parsed.protocol === 'https:' ? https : http;
+    const body = new URLSearchParams(params).toString();
+
+    const req = lib.request(
+      parsed,
+      {
+        method,
+        headers: {
+          Accept: 'application/json',
+          'Content-Type': 'application/x-www-form-urlencoded',
+          'Content-Length': Buffer.byteLength(body),
+          ...headers
+        }
+      },
+      (res) => {
+        let raw = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => {
+          raw += chunk;
+        });
+        res.on('end', () => {
+          let data = {};
+          try {
+            data = raw ? JSON.parse(raw) : {};
+          } catch (_error) {
+            data = { raw };
+          }
+
+          const statusCode = res.statusCode || 0;
+          if (statusCode < 200 || statusCode >= 300) {
+            reject(httpErrorFromResponse(method, urlString, statusCode, data));
+            return;
+          }
+
+          resolve(data);
+        });
+      }
+    );
+
+    req.on('error', reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+module.exports = {
+  httpGet,
+  httpErrorFromResponse,
+  printApiError,
+  httpJson,
+  httpForm
+};