@empirical-gauzza/cli 1.0.27 → 1.0.28

package/bin/empirical.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 'use strict';
 
@@ -17,6 +17,7 @@ const {
 } = require('../lib/auth');
 const { isWorkspaceCommand, runWorkspaceCommand } = require('../lib/workspaceCommands');
 const { runMemoryCommand } = require('../lib/memoryCommands');
+const { runAlertCommand } = require('../lib/alertCommands');
 const { runKitCommand, runSkillCommand, runDeviceCommand } = require('../lib/kitCommands');
 const { runDoctor } = require('../lib/doctor');
 const { runDoc } = require('../lib/doc');
@@ -91,6 +92,11 @@ async function main() {
     return;
   }
 
+  if (args[0] === 'alert') {
+    await runAlertCommand(args.slice(1));
+    return;
+  }
+
   if (args[0] === 'kit') {
     await runKitCommand(args.slice(1));
     return;

package/lib/alertBanner.js

@@ -0,0 +1,44 @@
+'use strict';
+
+// Plain-text rendering for a human reading stderr directly — deliberately NOT the MCP wording
+// (renderAlertNotice's "NOTICE FOR THE USER - relay this verbatim"), which instructs a host
+// MODEL to relay text to a person who can't see stderr at all. Here the person IS the reader.
+const ANSI = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m'
+};
+
+function supportsColorStderr() {
+  return Boolean(process.stderr && process.stderr.isTTY) && !process.env.NO_COLOR;
+}
+
+const TONE_PREFIX = { info: 'i', success: '✓', warning: '!', error: '✗' };
+const TONE_COLOR = { info: ANSI.cyan, success: ANSI.cyan, warning: ANSI.yellow, error: ANSI.red };
+
+function colorize(code, text) {
+  if (!supportsColorStderr()) return text;
+  return `${code}${text}${ANSI.reset}`;
+}
+
+function renderOneAlert(alert) {
+  const prefix = TONE_PREFIX[alert.tone] || TONE_PREFIX.info;
+  const color = TONE_COLOR[alert.tone] || TONE_COLOR.info;
+  const lines = [];
+  lines.push(colorize(`${ANSI.bold}${color}`, `${prefix} ${alert.title}`));
+  lines.push(`  ${alert.body}`);
+  for (const action of alert.actions || []) {
+    lines.push(`  → ${action.label}: ${action.href}`);
+  }
+  lines.push(`  (dismiss: empirical alert dismiss --alert-id ${alert.id})`);
+  return lines.join('\n');
+}
+
+function renderCliAlertBanner(alerts) {
+  if (!Array.isArray(alerts) || !alerts.length) return '';
+  return alerts.map(renderOneAlert).join('\n\n') + '\n';
+}
+
+module.exports = { renderCliAlertBanner };

package/lib/alertCommands.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const { requireAccessToken, resolveApiBaseUrl, buildApiAuthHeaders } = require('./auth');
+const { httpJson, printApiError } = require('./http');
+const { log, warn } = require('./ui');
+
+function parseOption(args, name, fallback) {
+  const idx = args.indexOf(name);
+  if (idx === -1 || idx === args.length - 1) return fallback;
+  return args[idx + 1];
+}
+
+async function runAlertList(_args) {
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const url = new URL('/api/v1/alerts', baseUrl).toString();
+  let response;
+  try {
+    response = await httpJson(url, 'GET', undefined, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+    return;
+  }
+  const data = response && response.data ? response.data : response;
+  log(JSON.stringify(data.alerts !== undefined ? data.alerts : data));
+}
+
+async function runAlertDismiss(args) {
+  const alertId = parseOption(args, '--alert-id', '');
+  if (!alertId) {
+    warn('Usage: empirical alert dismiss --alert-id <id>');
+    process.exit(1);
+    return;
+  }
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const url = new URL(`/api/v1/alerts/${encodeURIComponent(alertId)}/dismiss`, baseUrl).toString();
+  let response;
+  try {
+    response = await httpJson(url, 'POST', undefined, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+    return;
+  }
+  const data = response && response.data ? response.data : response;
+  log(JSON.stringify(data));
+}
+
+async function runAlertCommand(subArgs) {
+  const sub = subArgs[0] && !subArgs[0].startsWith('-') ? subArgs[0] : undefined;
+  const rest = subArgs.slice(1);
+
+  if (sub === 'list') return runAlertList(rest);
+  if (sub === 'dismiss') return runAlertDismiss(rest);
+
+  warn('Usage: empirical alert <list|dismiss> [options]');
+  process.exit(1);
+}
+
+module.exports = { runAlertCommand };

package/lib/constants.js

@@ -8,12 +8,21 @@ const EMPIRICAL_MCP_LEGACY_NAMES = ['empirical-live'];
 const EMPIRICAL_MCP_URL = process.env.EMPIRICAL_MCP_URL || 'https://empirical.gauzza.com/mcp';
 const COPILOT_OAUTH_CLIENT_ID = process.env.EMPIRICAL_COPILOT_OAUTH_CLIENT_ID || 'copilot-cli-empirical';
 
+// These two lists mirror the schema-level enums in packages/shared/src/memoryGraph.ts.
+// They are duplicated rather than imported on purpose: this CLI publishes to npm as
+// @empirical-gauzza/cli, and @empirical/shared is a private workspace package, so depending
+// on it would break `npm install` for end users. tests/unit/cliMemoryEnumParity.test.js
+// fails CI if the copies ever diverge.
 const MEMORY_CATEGORIES = [
   'health', 'fitness', 'food', 'supplement', 'mood', 'idea', 'business',
   'build', 'growth', 'learning', 'leadership', 'operations', 'workflow',
   'lead', 'project', 'recipe', 'preference', 'reflection', 'relationship', 'heartbeat'
 ];
 
+const NODE_TYPES = [
+  'event', 'entity', 'observation', 'reflection', 'goal', 'concept'
+];
+
 const DOC_TOPICS = {
   memory: `# Empirical Memory Commands
 
@@ -33,9 +42,26 @@ Flags:
 - \`--top-k\`: number of results, 1–100, default 3
 - \`--category\`: filter by category
 - \`--tags\`: comma-separated tags filter
+- \`--tags-all\`: comma-separated tags that must ALL be present (AND match)
+- \`--status\`: comma-separated status values to keep (for example open,in_progress)
+- \`--path\`: pin one retrieval pathway (see below)
+- \`--hops\`: 1 or 2, graph depth; only valid with \`--path graph\` or \`--path hebbian\`
 - \`--pretty\`: pretty-print JSON output
 - \`--format table\`: render results as a table instead of JSON (JSON stays the default)
 
+#### Retrieval pathways
+
+- \`--path semantic\`: ranked meaning match. Runs the embedding search and scores candidates.
+  Use it when you are asking a question and want the closest few answers.
+- \`--path list\`: filtered browse. Skips ranking and returns the matching set in order, with
+  paging. Use it when you want everything carrying a tag, status, or category, not a top few.
+- \`--path graph\`: relationship walk from the best entry points, out \`--hops\` steps. Use it
+  when what you want is connected to what you can name rather than worded like it.
+- \`--path hebbian\`: co-recall walk, following the links that repeated retrieval strengthened.
+  Use it when you want what usually comes up alongside this, not what merely resembles it.
+
+Omitting \`--path\` keeps the default, where the classifier decides which pathway answers.
+
 ### get
 Retrieve one memory by exact ID.
 
@@ -85,6 +111,18 @@ Flags:
 - \`--node-type\`: node type, default \`observation\`
 - \`--json-file\`: path to JSON file with full memory payload
 
+Both \`--category\` and \`--node-type\` are closed sets. Do not guess a value: anything outside
+these lists is rejected and the write does not happen.
+
+Valid categories (20): health, fitness, food, supplement, mood, idea, business, build, growth,
+learning, leadership, operations, workflow, lead, project, recipe, preference, reflection,
+relationship, heartbeat.
+
+Valid node types (6): event, entity, observation, reflection, goal, concept.
+
+There is no \`product\` category and no \`decision\` node type. Record a decision as
+\`--category project --node-type event\`.
+
 ### note
 Add a note to an existing memory.
 
@@ -595,6 +633,7 @@ module.exports = {
   EMPIRICAL_MCP_URL,
   COPILOT_OAUTH_CLIENT_ID,
   MEMORY_CATEGORIES,
+  NODE_TYPES,
   DOC_TOPICS,
   getCliVersion,
   deriveBaseUrlFromMcpUrl

package/lib/http.js

@@ -1,187 +1,192 @@
-'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-cli/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',
-          // Identifies the client so the server can tell a CLI write from a portal write
-          // (services/memoryAuthorship.ts). Writes also send source: 'cli' in the body,
-          // which is authoritative; this covers every other endpoint.
-          'User-Agent': 'empirical-cli/1.0',
-          ...(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',
-          // Identifies the client so the server can tell a CLI write from a portal write
-          // (services/memoryAuthorship.ts). Writes also send source: 'cli' in the body,
-          // which is authoritative; this covers every other endpoint.
-          'User-Agent': 'empirical-cli/1.0',
-          '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
-};
+'use strict';
+
+const http = require('http');
+const https = require('https');
+const { warn } = require('./ui');
+const { renderCliAlertBanner } = require('./alertBanner');
+
+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-cli/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',
+          // Identifies the client so the server can tell a CLI write from a portal write
+          // (services/memoryAuthorship.ts). Writes also send source: 'cli' in the body,
+          // which is authoritative; this covers every other endpoint.
+          'User-Agent': 'empirical-cli/1.0',
+          ...(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 };
+          }
+
+          if (data && Array.isArray(data.alerts) && data.alerts.length) {
+            process.stderr.write(renderCliAlertBanner(data.alerts));
+          }
+
+          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',
+          // Identifies the client so the server can tell a CLI write from a portal write
+          // (services/memoryAuthorship.ts). Writes also send source: 'cli' in the body,
+          // which is authoritative; this covers every other endpoint.
+          'User-Agent': 'empirical-cli/1.0',
+          '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
+};