@empirical-gauzza/cli 1.0.19 → 1.0.20

package/bin/empirical.js

@@ -32,7 +32,12 @@ async function main() {
     return;
   }
 
-  if (args.includes('-h') || args.includes('--help')) {
+  // `-h`/`--help` short-circuits to the global help wall UNLESS a subcommand that knows how to
+  // print its own scoped usage was named first (currently just `memory`, per C-005 item 5) --
+  // otherwise `empirical memory --help` / `empirical memory query --help` printed the 90-line
+  // global wall instead of anything about `memory`.
+  const scopedHelpCommands = new Set(['memory']);
+  if ((args.includes('-h') || args.includes('--help')) && !scopedHelpCommands.has(args[0])) {
     showHelp();
     return;
   }
@@ -42,8 +47,11 @@ async function main() {
     return;
   }
 
-  const updateCheckExcluded = new Set(['install', 'plugin', 'auth', 'oauth', 'policy', 'doctor']);
-  if (process.stdin.isTTY && !updateCheckExcluded.has(args[0])) {
+  const updateCheckExcluded = new Set(['install', 'plugin', 'auth', 'oauth', 'policy', 'doctor', 'whoami']);
+  // Both stdin and stdout must be a real TTY: stdin.isTTY alone let this run ahead of e.g.
+  // `empirical memory query --match x | jq`, where stdin stays a TTY but stdout is a pipe --
+  // the header/prompt then leaked into the piped stream ahead of the JSON payload.
+  if (process.stdin.isTTY && process.stdout.isTTY && !updateCheckExcluded.has(args[0])) {
     try {
       await checkNativePluginUpdates({ interactive: true });
     } catch (_error) {

package/lib/auth.js

@@ -18,12 +18,12 @@ const {
   generateRandomString,
   generatePKCE,
   isJwtToken,
-  isJwtExpired,
-  readHeadlessToken,
-  readOAuthSession,
-  writeOAuthSession,
-  clearOAuthSession,
-  hasFreshAccessToken,
+  isJwtExpired,
+  readHeadlessToken,
+  readOAuthSession,
+  writeOAuthSession,
+  clearOAuthSession,
+  hasFreshAccessToken,
   writeHeadlessEnvFile
 } = require('./oauthClient');
 const { deriveBaseUrlFromMcpUrl } = require('./constants');
@@ -124,11 +124,11 @@ async function runMcpOAuthFlow(baseUrl) {
 
         if (!resolved) {
           resolved = true;
-          resolveOAuthCode(code, codeVerifier, baseUrl)
-            .then((token) => {
-              writeOAuthSession(token);
-              resolve(token);
-            })
+          resolveOAuthCode(code, codeVerifier, baseUrl)
+            .then((token) => {
+              writeOAuthSession(token);
+              resolve(token);
+            })
             .catch(reject);
         }
       } else {
@@ -191,9 +191,9 @@ async function resolveOAuthCode(code, codeVerifier, baseUrl) {
     throw new Error('Token exchange succeeded but no access_token was returned.');
   }
 
-  return {
-    baseUrl,
-    accessToken: token.access_token,
+  return {
+    baseUrl,
+    accessToken: token.access_token,
     refreshToken: token.refresh_token || null,
     expiresIn: token.expires_in || null,
     tokenType: token.token_type || 'Bearer',
@@ -240,7 +240,7 @@ function resolveAccessToken() {
     path.join(os.homedir(), '.empirical', 'headless-token.json')
   ].filter(Boolean);
 
-  for (const candidate of tokenFileCandidates) {
+  for (const candidate of tokenFileCandidates) {
     if (!fs.existsSync(candidate)) continue;
     try {
       const parsed = JSON.parse(fs.readFileSync(candidate, 'utf8'));
@@ -253,12 +253,12 @@ function resolveAccessToken() {
     } catch (_error) {
       // ignore parse errors and try next
     }
-  }
-
-  const session = readOAuthSession();
-  if (session?.accessToken && !(isJwtToken(session.accessToken) && isJwtExpired(session.accessToken))) {
-    return session.accessToken;
-  }
+  }
+
+  const session = readOAuthSession();
+  if (session?.accessToken && !(isJwtToken(session.accessToken) && isJwtExpired(session.accessToken))) {
+    return session.accessToken;
+  }
 
   // Priority 4: EMPIRICAL_API_KEY / EMPIRICAL_CLIENT_SECRET env vars, used
   // directly as a permanent Bearer credential. In a client_credentials setup
@@ -305,30 +305,111 @@ function resolveApiBaseUrl() {
   return 'https://empirical.gauzza.com';
 }
 
-function requireAccessToken() {
+function requireAccessToken() {
   const token = resolveAccessToken();
   if (!token) {
-    warn('No access token found. Run: empirical auth login, or configure headless credentials with empirical oauth bootstrap headless.');
+    warn('No access token found. Run: empirical auth login, or configure headless credentials with empirical oauth bootstrap headless.');
     process.exit(1);
   }
   return token;
-}
-
-function isAuthCommand(args) {
-  return args[0] === 'auth' && ['login', 'logout'].includes(args[1]);
-}
-
-async function runAuthCommand(args) {
-  const action = args[1];
-  if (action === 'login') {
-    const baseUrl = getEnv('EMPIRICAL_BASE_URL', 'https://empirical.gauzza.com');
-    await runMcpOAuthFlow(baseUrl);
-    log('Empirical OAuth login complete. CLI session saved.');
-    return;
-  }
-  clearOAuthSession();
-  log('Empirical OAuth session cleared.');
-}
+}
+
+function isAuthCommand(args) {
+  if (args[0] === 'whoami') return true;
+  return args[0] === 'auth' && ['login', 'logout', 'status', 'whoami'].includes(args[1]);
+}
+
+// Shared token introspection, used by both `auth status`/`whoami` here and by `doctor`
+// (doctor.js's token_type/token_expiry checks call this instead of decoding the JWT payload
+// a second time) so the two commands can never silently drift on what "expired" means.
+function inspectToken(token) {
+  if (!token) {
+    return { present: false, tokenType: null, expiresAt: null, expired: null };
+  }
+  const parts = token.split('.');
+  if (parts.length !== 3) {
+    return { present: true, tokenType: 'apikey', expiresAt: null, expired: false };
+  }
+  try {
+    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+    if (payload && typeof payload.exp === 'number') {
+      const expiresAt = new Date(payload.exp * 1000).toISOString();
+      const expired = payload.exp < Math.floor(Date.now() / 1000);
+      return { present: true, tokenType: 'jwt', expiresAt, expired };
+    }
+    return { present: true, tokenType: 'jwt', expiresAt: null, expired: null };
+  } catch (_error) {
+    return { present: true, tokenType: 'jwt', expiresAt: null, expired: null };
+  }
+}
+
+// Gathers the same identity/workspace facts `doctor` reports (token presence/type/expiry, plus
+// user + workspace from /api/v1/users/me), formatted for `auth status` / `whoami` as a single
+// JSON object instead of doctor's multi-check report.
+async function gatherAuthStatus() {
+  const token = resolveAccessToken();
+  const tokenInfo = inspectToken(token);
+
+  let user = null;
+  let workspaceId = null;
+  let error = null;
+
+  if (token) {
+    try {
+      const baseUrl = resolveApiBaseUrl();
+      const meUrl = new URL('/api/v1/users/me', baseUrl).toString();
+      const response = await httpJson(meUrl, 'GET', null, buildApiAuthHeaders(token));
+      const userData = (response && response.data) ? response.data : response;
+      user = {
+        id: userData.userId || userData.id || null,
+        email: userData.email || null
+      };
+      workspaceId = userData.workspaceId || userData.workspaceName || null;
+    } catch (apiError) {
+      error = apiError.message;
+    }
+  }
+
+  return {
+    authenticated: Boolean(token) && !error && tokenInfo.expired !== true,
+    tokenPresent: tokenInfo.present,
+    tokenType: tokenInfo.tokenType,
+    tokenExpiresAt: tokenInfo.expiresAt,
+    tokenExpired: tokenInfo.expired,
+    user,
+    workspaceId,
+    error
+  };
+}
+
+async function runAuthCommand(args) {
+  const action = args[0] === 'whoami' ? 'status' : args[1];
+
+  if (action === 'login') {
+    const baseUrl = getEnv('EMPIRICAL_BASE_URL', 'https://empirical.gauzza.com');
+    await runMcpOAuthFlow(baseUrl);
+    log('Empirical OAuth login complete. CLI session saved.');
+    return;
+  }
+
+  if (action === 'status' || action === 'whoami') {
+    const status = await gatherAuthStatus();
+    log(JSON.stringify(status));
+    if (!status.authenticated) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (action === 'logout') {
+    clearOAuthSession();
+    log('Empirical OAuth session cleared.');
+    return;
+  }
+
+  warn('Usage: empirical auth <login|logout|status> (or: empirical whoami)');
+  process.exitCode = 1;
+}
 
 function buildApiAuthHeaders(token) {
   const context = globalThis.__empiricalCliAnalyticsContext || {};
@@ -780,9 +861,11 @@ async function runHeadlessRefresh(args) {
 module.exports = {
   oauthPreflight,
   openBrowser,
-  runMcpOAuthFlow,
-  isAuthCommand,
-  runAuthCommand,
+  runMcpOAuthFlow,
+  isAuthCommand,
+  runAuthCommand,
+  inspectToken,
+  gatherAuthStatus,
   resolveOAuthCode,
   updateClaudeMcpServerAuth,
   resolveAccessToken,

package/lib/constants.js

@@ -26,7 +26,7 @@ Errors are written to stderr as JSON. Successful output is written to stdout as
 ### query
 Search memories by natural language.
 
-    empirical memory query --match "coding style preferences" [--top-k 3] [--category build] [--tags ts,node] [--pretty]
+    empirical memory query --match "coding style preferences" [--top-k 3] [--category build] [--tags ts,node] [--pretty] [--format table]
 
 Flags:
 - \`--match\` (required): natural language search string
@@ -34,6 +34,7 @@ Flags:
 - \`--category\`: filter by category
 - \`--tags\`: comma-separated tags filter
 - \`--pretty\`: pretty-print JSON output
+- \`--format table\`: render results as a table instead of JSON (JSON stays the default)
 
 ### get
 Retrieve one memory by exact ID.
@@ -43,7 +44,7 @@ Retrieve one memory by exact ID.
 ### list
 Browse memories deterministically. Use \`--cursor\` from the previous response while \`pagination.hasMore\` is true.
 
-    empirical memory list [--category project] [--tags canonical,launch] [--start-date <ISO>] [--end-date <ISO>] [--limit 20] [--cursor <cursor>] [--oldest] [--pretty]
+    empirical memory list [--category project] [--tags canonical,launch] [--start-date <ISO>] [--end-date <ISO>] [--limit 20] [--cursor <cursor>] [--oldest] [--pretty] [--format table]
 
 Flags:
 - \`--category\`, \`--tags\`: optional filters
@@ -52,6 +53,7 @@ Flags:
 - \`--cursor\`: continuation cursor from a previous page
 - \`--oldest\`: sort oldest first; default is newest first
 - \`--pretty\`: pretty-print JSON output
+- \`--format table\`: render results as a table instead of JSON (JSON stays the default)
 
 ### record
 Save a new memory.
@@ -99,6 +101,43 @@ Flags:
 - \`--memory-id\`: use exact memory ID
 - \`--min-score\`: minimum similarity score, default 0.35
 
+Bulk delete by tag, category, or everything (exactly one selector):
+
+    empirical memory delete --tag old-preference --confirm
+    empirical memory delete --category recipe --confirm
+    empirical memory delete --all --confirm
+
+Without \`--confirm\`, always a dry-run that prints the count that would be deleted; no writes
+happen. Re-run with \`--confirm\` to actually delete.
+
+### export / import
+Export memories to a versioned, round-trippable JSON document and re-import them later.
+
+    empirical memory export --scope <personal|workspace> [--out <path>] [--workspace-id <id>]
+    empirical memory import <file> [--dry-run]
+
+Export writes \`{ schemaVersion: 1, exportedAt, memories: [...] }\`. Import reads that same
+shape and POSTs each row through the normal create endpoint, so imported memories get the same
+dedupe and auto-link treatment as any other write. \`--dry-run\` on import prints the count that
+would be imported without writing anything.
+
+### stats
+Aggregated counts, scoped to the caller.
+
+    empirical memory stats [--format table]
+
+Returns total count, counts by category, counts by tag, and oldest/newest memory timestamps.
+
+### compact
+On-demand near-duplicate scan (the same logic the nightly compaction job runs), scoped to the
+caller only. Dry-run by default, matching a terraform plan/apply model.
+
+    empirical memory compact [--category <cat>]
+    empirical memory compact --apply [--category <cat>]
+
+Without \`--apply\`, reports proposed merge/link candidate pairs and counts with no writes.
+With \`--apply\`, executes the merges and links for real and reports what was applied.
+
 ## Error output contract
 - Errors → stderr as JSON: \`{ "error": true, "code": "...", "message": "..." }\`
 - Success → stdout as JSON (compact by default)
@@ -207,18 +246,35 @@ Deletion dry-runs by default. \`--confirm\` calls the existing soft-delete endpo
 
   doctor: `# Empirical Doctor
 
-    empirical doctor [--output json]
+    empirical doctor [--output json] [--deep]
 
-Checks the health of your Empirical CLI setup. Useful for diagnosing auth and connectivity issues.
+Checks the health of your Empirical CLI setup, including why MCP tools might not be showing up
+in a host CLI (the most common failure report).
 
-## Checks performed (in order)
+## Checks performed
 
 1. **Token presence** — verifies a token exists via EMPIRICAL_ACCESS_TOKEN env, apiKey field,
    or accessToken field in the token file
 2. **Token type** — detects API key (long alphanumeric, no dots) vs JWT (3 dot-separated parts)
 3. **Token expiry** — if JWT, decodes the payload and checks the \`exp\` field; warns if no \`exp\`
-4. **API connectivity** — calls GET /api/users/me; 200 = OK, anything else = FAIL
-5. **Workspace** — reads workspaceId from the /api/users/me response; warns if null
+4. **API connectivity** — calls GET /api/v1/users/me; 200 = OK, anything else = FAIL
+5. **Workspace** — reads workspaceId from the /api/v1/users/me response; warns if null
+6. **MCP hosts detected** — which of codex/claude/copilot were found on this machine
+7. **MCP config registration (per detected host)** — reads that host's own config file
+   (\`~/.claude.json\`, \`<CODEX_HOME>/config.toml\`, \`~/.copilot/mcp-config.json\`) and confirms
+   the Empirical MCP server is actually registered there with the current URL
+8. **MCP reachability** — POSTs a real MCP \`initialize\` request to the MCP endpoint with the
+   resolved access token and confirms a valid JSON-RPC response comes back
+9. **Native plugin presence/version (per detected host)** — runs \`<host> plugin list\` and
+   reports the installed empirical-memory (and optional) plugin versions
+10. **Hooks presence (per detected host)** — confirms the SessionStart/UserPromptSubmit/Stop
+    hook scripts exist on disk and are registered in that host's hook manifest
+
+## --deep
+
+Adds a live write/query/delete round trip: records a \`doctor-probe-<timestamp>\` memory, queries
+it back, deletes it, and reports elapsed time for each leg. Requires a valid token; writes and
+deletes exactly one throwaway memory tagged \`doctor-probe\`.
 
 ## Output format
 
@@ -422,9 +478,17 @@ The browser OAuth session is stored separately at \`~/.empirical/oauth-session.j
 
 ## Verify auth status
 
+    empirical auth status
+    empirical whoami
+
+Prints a single JSON object: \`{ authenticated, tokenPresent, tokenType, tokenExpiresAt,
+tokenExpired, user: { id, email } | null, workspaceId, error }\`. \`whoami\` is an alias for
+\`auth status\`. Exits 1 if not authenticated.
+
     empirical doctor
 
-Checks token presence, type, expiry, and API connectivity.
+Checks token presence, type, expiry, and API connectivity across a broader set of checks
+(host MCP config registration, hooks, plugin versions).
 `,
 
   user: `# Empirical User Identity

package/lib/deviceConfig.js

@@ -20,20 +20,37 @@ function readDeviceConfig() {
   return readJsonIfExists(getDeviceConfigPath()) || {};
 }
 
-function writeDeviceConfig(config) {
-  writeFile(getDeviceConfigPath(), `${JSON.stringify(config, null, 2)}\n`);
-}
-
-function readPolicyCache() {
-  const config = readDeviceConfig();
-  return config.empiricalPolicy || null;
-}
-
-function writePolicyCache(policyCache) {
-  const config = readDeviceConfig();
-  config.empiricalPolicy = policyCache;
-  writeDeviceConfig(config);
-}
+function writeDeviceConfig(config) {
+  writeFile(getDeviceConfigPath(), `${JSON.stringify(config, null, 2)}\n`);
+}
+
+// C-001: the installer's chosen integration mode (1 = MCP, 2 = CLI-direct, 3 = both), persisted
+// so later, unattended refreshes of the empirical-memory Skill -- a plugin auto-update
+// (pluginUpdateCheck.js) or a `kit sync`/`kit use` run (skillSync.js) that happens long after the
+// interactive installer finished -- still pick the mode the user actually chose, not a hardcoded
+// default.
+function readIntegrationMode() {
+  const config = readDeviceConfig();
+  const mode = config.integrationMode;
+  return mode === 2 || mode === 3 ? mode : 1;
+}
+
+function writeIntegrationMode(integrationMode) {
+  const config = readDeviceConfig();
+  config.integrationMode = integrationMode === 2 || integrationMode === 3 ? integrationMode : 1;
+  writeDeviceConfig(config);
+}
+
+function readPolicyCache() {
+  const config = readDeviceConfig();
+  return config.empiricalPolicy || null;
+}
+
+function writePolicyCache(policyCache) {
+  const config = readDeviceConfig();
+  config.empiricalPolicy = policyCache;
+  writeDeviceConfig(config);
+}
 
 // Ensures a deviceId exists in the local config, generating+persisting one on first use.
 // Reused across all future CLI invocations on this machine.
@@ -80,10 +97,12 @@ function writePendingReview(pendingReview) {
 module.exports = {
   getEmpiricalDir,
   getDeviceConfigPath,
-  readDeviceConfig,
-  writeDeviceConfig,
-  readPolicyCache,
-  writePolicyCache,
+  readDeviceConfig,
+  writeDeviceConfig,
+  readIntegrationMode,
+  writeIntegrationMode,
+  readPolicyCache,
+  writePolicyCache,
   ensureDeviceId,
   getSyncManifestPath,
   readSyncManifest,