@empirical-gauzza/cli 1.0.36 → 1.0.38

package/bin/empirical.js

@@ -25,6 +25,7 @@ const { showVersion } = require('../lib/help');
 const { isPluginCommand, runPluginCommand } = require('../lib/pluginCommands');
 const { runPolicyCommand } = require('../lib/policyCommands');
 const { runSetupCommand } = require('../lib/setupCommands');
+const { runUsageCommand } = require('../lib/usageCommands');
 const { runBlueprintCommand } = require('../lib/blueprintCommands');
 const { checkNativePluginUpdates } = require('../lib/pluginUpdateCheck');
 
@@ -112,6 +113,11 @@ async function main() {
     return;
   }
 
+  if (args[0] === 'usage') {
+    await runUsageCommand(args.slice(1));
+    return;
+  }
+
   if (args[0] === 'setup') {
     await runSetupCommand(args.slice(1));
     return;

package/lib/attachmentCommands.js

@@ -0,0 +1,388 @@
+'use strict';
+
+// `empirical memory attachment <list|add|get|delete|restore>` over the four REST routes in
+// packages/server/src/routes/memories.ts (POST/GET/DELETE /:id/attachments[/:attachmentId] and
+// the restore POST). Attachments shipped REST-only; this is the first non-REST door.
+//
+// Two things here are not style choices:
+//  1. `get` writes BYTES. It never goes through httpJson, which decodes utf8 and would corrupt
+//     every non-text file, and it never prints the body to stdout unless asked (--out -), so a
+//     stray download cannot dump a binary into a terminal or a piped JSON stream.
+//  2. The per-file cap is checked locally BEFORE the upload. The server refuses an oversized
+//     body at ingress, but only after the client has pushed 25MB+ up the wire for nothing.
+
+const fs = require('fs');
+const path = require('path');
+const { log, warn } = require('./ui');
+const { httpJson, httpMultipart, httpDownload, printApiError } = require('./http');
+const { parseOption, parseFlag } = require('./env');
+const { requireAccessToken, resolveApiBaseUrl, buildApiAuthHeaders } = require('./auth');
+const { resolveMemoryByQuery, parseMatchFilters, printMemoryResolveError } = require('./memoryResolve');
+
+// Mirrors MAX_ATTACHMENT_BYTES / MAX_ATTACHMENTS_PER_MEMORY in packages/shared/src/
+// subscriptionPlans.ts. The CLI is published as its own npm package and cannot depend on the
+// workspace, so these are copied; they are used for a friendlier local error only, never to
+// decide anything the server does not re-check.
+const MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024;
+
+// Enough to label the common cases. The server sniffs magic bytes and overrides anything
+// renderable or executable, so a wrong guess here is corrected, never trusted.
+const MIME_BY_EXTENSION = {
+  '.txt': 'text/plain',
+  '.md': 'text/markdown',
+  '.json': 'application/json',
+  '.csv': 'text/csv',
+  '.pdf': 'application/pdf',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.svg': 'image/svg+xml',
+  '.zip': 'application/zip',
+  '.mp3': 'audio/mpeg',
+  '.m4a': 'audio/mp4',
+  '.wav': 'audio/wav',
+  '.mp4': 'video/mp4'
+};
+
+const ATTACHMENT_SUBCOMMAND_USAGE = {
+  list: 'Usage: empirical memory attachment list (--memory-id <id> | --match <query>) [--include-deleted] [--format table] [--pretty]',
+  add: 'Usage: empirical memory attachment add (--memory-id <id> | --match <query>) --file <path> [--author-type user|agent] [--min-score 0.35]',
+  get: 'Usage: empirical memory attachment get (--memory-id <id> | --match <query>) --attachment-id <id> [--out <path>] [--force]\n  --out - writes the bytes to stdout.',
+  delete: 'Usage: empirical memory attachment delete (--memory-id <id> | --match <query>) --attachment-id <id> [--confirm]\n  Soft delete: the file is restorable for 30 days, then purged.',
+  restore: 'Usage: empirical memory attachment restore (--memory-id <id> | --match <query>) --attachment-id <id>'
+};
+
+function printAttachmentHelp(sub) {
+  if (sub && ATTACHMENT_SUBCOMMAND_USAGE[sub]) {
+    log(ATTACHMENT_SUBCOMMAND_USAGE[sub]);
+    return;
+  }
+  log('Files attached to a memory. Up to 20 per memory, 25MB each; a delete is reversible for 30 days.');
+  log('');
+  for (const usage of Object.values(ATTACHMENT_SUBCOMMAND_USAGE)) log(usage);
+  log('');
+  log('Shorthands: `memory attach` = `memory attachment add`, `memory attachments` = `memory attachment list`.');
+}
+
+function guessContentType(filename) {
+  return MIME_BY_EXTENSION[path.extname(String(filename || '')).toLowerCase()] || 'application/octet-stream';
+}
+
+function fail(code, message, extra = {}) {
+  warn(JSON.stringify({ error: true, code, message, ...extra }));
+  process.exit(1);
+}
+
+// Every subcommand takes the same target: an explicit id, or a --match query resolved the same
+// way `memory note` and `memory delete` resolve theirs.
+async function resolveTargetMemoryId(args, accessToken, baseUrl, usage) {
+  const memoryId = parseOption(args, '--memory-id', '');
+  if (memoryId) return memoryId;
+
+  const match = parseOption(args, '--match', '');
+  if (!match) {
+    warn(usage);
+    process.exit(1);
+  }
+
+  const minScore = Number(parseOption(args, '--min-score', '0.35'));
+  const result = await resolveMemoryByQuery(match, minScore, accessToken, baseUrl, parseMatchFilters(args));
+  if (!result.found) {
+    printMemoryResolveError(result);
+    process.exit(1);
+  }
+  return result.memory.id;
+}
+
+function attachmentsUrl(baseUrl, memoryId, suffix = '') {
+  return new URL(`/api/v1/memories/${encodeURIComponent(memoryId)}/attachments${suffix}`, baseUrl).toString();
+}
+
+function renderAttachmentsTable(rows) {
+  const header = ['ID', 'FILENAME', 'BYTES', 'TYPE', 'STATE'];
+  const body = rows.map((row) => [
+    String(row.id || ''),
+    String(row.filename || ''),
+    String(row.bytes != null ? row.bytes : ''),
+    String(row.mimeType || ''),
+    row.deletedAt ? `deleted, purges ${String(row.purgeAfter || '').slice(0, 10)}` : 'live'
+  ]);
+  const widths = header.map((_h, i) => Math.max(header[i].length, ...body.map((r) => r[i].length), 1));
+  const line = (cells) => cells.map((c, i) => c.padEnd(widths[i])).join('  ').trimEnd();
+  log(line(header));
+  log(widths.map((w) => '-'.repeat(w)).join('  '));
+  for (const row of body) log(line(row));
+}
+
+async function runAttachmentList(args) {
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const memoryId = await resolveTargetMemoryId(args, accessToken, baseUrl, ATTACHMENT_SUBCOMMAND_USAGE.list);
+
+  const url = attachmentsUrl(baseUrl, memoryId) + (parseFlag(args, '--include-deleted') ? '?includeDeleted=true' : '');
+
+  let response;
+  try {
+    response = await httpJson(url, 'GET', undefined, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  // This route answers with `attachments` at the TOP level, not under `data` like most of the
+  // memory routes; reading response.data here would silently print nothing.
+  const attachments = Array.isArray(response && response.attachments) ? response.attachments : [];
+
+  if (parseOption(args, '--format', '') === 'table') {
+    if (!attachments.length) {
+      log('No attachments on this memory.');
+      return;
+    }
+    renderAttachmentsTable(attachments);
+    return;
+  }
+
+  const payload = {
+    memoryId: response.memoryId || memoryId,
+    attachmentsCount: response.attachmentsCount != null ? response.attachmentsCount : attachments.length,
+    attachments
+  };
+  log(parseFlag(args, '--pretty') ? JSON.stringify(payload, null, 2) : JSON.stringify(payload));
+}
+
+async function runAttachmentAdd(args) {
+  const filePath = parseOption(args, '--file', '');
+  if (!filePath) {
+    warn(ATTACHMENT_SUBCOMMAND_USAGE.add);
+    process.exit(1);
+  }
+
+  const resolved = path.resolve(filePath);
+  let stat;
+  try {
+    stat = fs.statSync(resolved);
+  } catch (_error) {
+    fail('file_not_found', `No such file: ${resolved}`);
+  }
+  if (!stat.isFile()) {
+    fail('not_a_file', `Not a file: ${resolved}`);
+  }
+  if (stat.size === 0) {
+    fail('empty_file', `File is empty: ${resolved}`);
+  }
+  // Local pre-check, see note 2 at the top of this file.
+  if (stat.size > MAX_ATTACHMENT_BYTES) {
+    fail('attachment_too_large', `File is ${stat.size} bytes; the per-file limit is ${MAX_ATTACHMENT_BYTES} bytes (25MB).`, {
+      bytes: stat.size,
+      maxBytes: MAX_ATTACHMENT_BYTES
+    });
+  }
+
+  const authorType = parseOption(args, '--author-type', '');
+  if (authorType && !['user', 'agent', 'system'].includes(authorType)) {
+    fail('invalid_author_type', `Invalid --author-type "${authorType}". Valid: user, agent, system`);
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const memoryId = await resolveTargetMemoryId(args, accessToken, baseUrl, ATTACHMENT_SUBCOMMAND_USAGE.add);
+
+  const filename = path.basename(resolved);
+  let response;
+  try {
+    response = await httpMultipart(
+      attachmentsUrl(baseUrl, memoryId),
+      'POST',
+      {
+        // Same authorship contract as `memory record`: `source` is observable truth, authorType
+        // is only declared when the caller says so, never guessed.
+        fields: { source: 'cli', ...(authorType ? { authorType } : {}) },
+        file: { field: 'file', filename, contentType: guessContentType(filename), buffer: fs.readFileSync(resolved) }
+      },
+      buildApiAuthHeaders(accessToken)
+    );
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const data = (response && response.data) ? response.data : response;
+  log(JSON.stringify({ attached: true, ...data, ...(response.warnings ? { warnings: response.warnings } : {}) }));
+}
+
+// Content-Disposition from the download route is always the RFC 5987 form
+// (filename*=UTF-8''<pct-encoded>), so that is what is parsed; the plain filename="..." form is
+// accepted too in case a proxy rewrites it.
+function filenameFromContentDisposition(header) {
+  const value = String(header || '');
+  const extended = value.match(/filename\*=UTF-8''([^;]+)/i);
+  if (extended) {
+    try {
+      return decodeURIComponent(extended[1]);
+    } catch (_error) {
+      // Fall through to the plain form below.
+    }
+  }
+  const plain = value.match(/filename="([^"]+)"/i);
+  return plain ? plain[1] : '';
+}
+
+async function runAttachmentGet(args) {
+  const attachmentId = parseOption(args, '--attachment-id', '');
+  if (!attachmentId) {
+    warn(ATTACHMENT_SUBCOMMAND_USAGE.get);
+    process.exit(1);
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const memoryId = await resolveTargetMemoryId(args, accessToken, baseUrl, ATTACHMENT_SUBCOMMAND_USAGE.get);
+
+  let result;
+  try {
+    result = await httpDownload(
+      attachmentsUrl(baseUrl, memoryId, `/${encodeURIComponent(attachmentId)}`),
+      buildApiAuthHeaders(accessToken)
+    );
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const out = parseOption(args, '--out', '');
+  if (out === '-') {
+    process.stdout.write(result.buffer);
+    return;
+  }
+
+  // The server's filename is only ever used as a BASENAME. It is attacker-supplied as far as
+  // this process is concerned, and joining a path that carries .. or a drive letter straight
+  // onto cwd would let a download write outside the directory the user chose.
+  const suggested = path.basename(filenameFromContentDisposition(result.headers['content-disposition']) || '') || 'attachment';
+  let target = out ? path.resolve(out) : path.resolve(process.cwd(), suggested);
+  if (out) {
+    try {
+      if (fs.statSync(target).isDirectory()) target = path.join(target, suggested);
+    } catch (_error) {
+      // --out names a file that does not exist yet, which is the normal case.
+    }
+  }
+
+  if (fs.existsSync(target) && !parseFlag(args, '--force')) {
+    fail('file_exists', `${target} already exists. Pass --force to overwrite, or --out <path> to write elsewhere.`, { path: target });
+  }
+
+  try {
+    fs.writeFileSync(target, result.buffer);
+  } catch (error) {
+    fail('write_failed', `Could not write ${target}: ${error.message}`);
+  }
+
+  log(JSON.stringify({ downloaded: true, memoryId, attachmentId, path: target, bytes: result.buffer.length }));
+}
+
+async function runAttachmentDelete(args) {
+  const attachmentId = parseOption(args, '--attachment-id', '');
+  if (!attachmentId) {
+    warn(ATTACHMENT_SUBCOMMAND_USAGE.delete);
+    process.exit(1);
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const memoryId = await resolveTargetMemoryId(args, accessToken, baseUrl, ATTACHMENT_SUBCOMMAND_USAGE.delete);
+
+  // Same gate as `memory delete`: without --confirm this only reports what it would do.
+  if (!parseFlag(args, '--confirm')) {
+    log(JSON.stringify({ dryRun: true, wouldDelete: true, memoryId, attachmentId, note: 'Re-run with --confirm. The file stays restorable for 30 days.' }));
+    return;
+  }
+
+  let response;
+  try {
+    response = await httpJson(
+      attachmentsUrl(baseUrl, memoryId, `/${encodeURIComponent(attachmentId)}`),
+      'DELETE',
+      null,
+      buildApiAuthHeaders(accessToken)
+    );
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const data = (response && response.data) ? response.data : response;
+  log(JSON.stringify({ deleted: true, ...data }));
+}
+
+async function runAttachmentRestore(args) {
+  const attachmentId = parseOption(args, '--attachment-id', '');
+  if (!attachmentId) {
+    warn(ATTACHMENT_SUBCOMMAND_USAGE.restore);
+    process.exit(1);
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const memoryId = await resolveTargetMemoryId(args, accessToken, baseUrl, ATTACHMENT_SUBCOMMAND_USAGE.restore);
+
+  let response;
+  try {
+    response = await httpJson(
+      attachmentsUrl(baseUrl, memoryId, `/${encodeURIComponent(attachmentId)}/restore`),
+      'POST',
+      {},
+      buildApiAuthHeaders(accessToken)
+    );
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const data = (response && response.data) ? response.data : response;
+  log(JSON.stringify({ restored: true, ...data }));
+}
+
+const ATTACHMENT_SUBCOMMANDS = {
+  list: runAttachmentList,
+  ls: runAttachmentList,
+  add: runAttachmentAdd,
+  upload: runAttachmentAdd,
+  get: runAttachmentGet,
+  download: runAttachmentGet,
+  delete: runAttachmentDelete,
+  rm: runAttachmentDelete,
+  remove: runAttachmentDelete,
+  restore: runAttachmentRestore
+};
+
+async function runAttachmentCommand(subArgs) {
+  const sub = subArgs[0] && !subArgs[0].startsWith('-') ? subArgs[0] : undefined;
+  if (!sub || subArgs.includes('--help') || subArgs.includes('-h')) {
+    printAttachmentHelp(sub);
+    return undefined;
+  }
+
+  const handler = ATTACHMENT_SUBCOMMANDS[sub];
+  if (!handler) {
+    warn('Unknown attachment subcommand: ' + sub);
+    printAttachmentHelp();
+    process.exit(1);
+  }
+
+  return handler(subArgs.slice(1));
+}
+
+module.exports = {
+  ATTACHMENT_SUBCOMMAND_USAGE,
+  guessContentType,
+  filenameFromContentDisposition,
+  runAttachmentList,
+  runAttachmentAdd,
+  runAttachmentGet,
+  runAttachmentDelete,
+  runAttachmentRestore,
+  runAttachmentCommand
+};

package/lib/auth.js

@@ -361,7 +361,7 @@ function inspectToken(token) {
 // 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() {
+async function gatherAuthStatus({ includeEmpiricalTokens = false } = {}) {
   const token = resolveAccessToken();
   const tokenInfo = inspectToken(token);
 
@@ -398,6 +398,18 @@ async function gatherAuthStatus() {
     cliWorkspace = null;
   }
 
+  // `whoami` / `auth status` add one Empirical Tokens line while they are enforced (spec 8.4).
+  // Best effort with a short timeout; doctor does not ask for it.
+  let empiricalTokens = null;
+  if (includeEmpiricalTokens && token && !error) {
+    try {
+      const { fetchBillingMe, empiricalTokensLine } = require('./usageCommands');
+      empiricalTokens = empiricalTokensLine((await fetchBillingMe(3000)).empiricalTokenUsage);
+    } catch (_error) {
+      empiricalTokens = null;
+    }
+  }
+
   return {
     authenticated: Boolean(token) && !error && tokenInfo.expired !== true,
     tokenPresent: tokenInfo.present,
@@ -407,6 +419,8 @@ async function gatherAuthStatus() {
     user,
     workspaceId,
     cliWorkspace,
+    // Present only while enforced for this account: a dark account's JSON has no such key.
+    ...(empiricalTokens ? { empiricalTokens } : {}),
     error
   };
 }
@@ -422,7 +436,7 @@ async function runAuthCommand(args) {
   }
 
   if (action === 'status' || action === 'whoami') {
-    const status = await gatherAuthStatus();
+    const status = await gatherAuthStatus({ includeEmpiricalTokens: true });
     log(JSON.stringify(status));
     if (!status.authenticated) {
       process.exitCode = 1;

package/lib/blueprintCommands.js

@@ -3,7 +3,9 @@
 const { httpJson, printApiError } = require('./http');
 const { parseOption } = require('./env');
 const { requireAccessToken, resolveApiBaseUrl, buildApiAuthHeaders } = require('./auth');
-const { warn, log } = require('./ui');
+const { warn, log, createPrompter } = require('./ui');
+const { sanitizeForTerminal } = require('./setupCommands');
+const { confirmCostOrExit, isCostPreview, isInteractiveTerminal } = require('./empiricalTokensFormat');
 
 function apiUrl(pathSuffix) {
   return new URL(`/api/v1/blueprints${pathSuffix}`, resolveApiBaseUrl()).toString();
@@ -61,17 +63,35 @@ async function runClaim(args) {
 async function runInstall(args) {
   const blueprintId = args[0] && !args[0].startsWith('--') ? args[0] : '';
   if (!blueprintId) {
-    warn('Usage: empirical blueprint install <blueprintId> [--version <v>]');
+    warn('Usage: empirical blueprint install <blueprintId> [--version <v>] [--accept-cost]');
     process.exit(1);
   }
   const version = parseOption(args, '--version', '');
+  const acceptCost = args.includes('--accept-cost');
 
   const detail = await callApi('GET', `/${blueprintId}`, undefined);
   if (!detail.owned && detail.priceModel === 'free') {
     await callApi('POST', `/${blueprintId}/claim`, {});
   }
 
-  const installResult = await callApi('POST', `/${blueprintId}/install`, version ? { version } : {});
+  const installBody = { ...(version ? { version } : {}), ...(acceptCost ? { acceptEmpiricalTokenCost: true } : {}) };
+  let installResult = await callApi('POST', `/${blueprintId}/install`, installBody);
+  if (isCostPreview(installResult)) {
+    // A priced blueprint in enforce answers 200 with the cost and starts nothing (no installId yet).
+    // Acceptance is sent only from --accept-cost or an explicit y at a real terminal, never for the person.
+    const prompter = isInteractiveTerminal() ? createPrompter(process.stderr) : null;
+    try {
+      await confirmCostOrExit(installResult, { prompter, warn, sanitize: sanitizeForTerminal });
+    } finally {
+      if (prompter) prompter.close();
+    }
+    installResult = await callApi('POST', `/${blueprintId}/install`, { ...installBody, acceptEmpiricalTokenCost: true });
+  }
+  if (!installResult || !installResult.installId) {
+    // Never poll /installs/undefined: a reply with no install id is not a started install.
+    log(JSON.stringify(installResult, null, 2));
+    return;
+  }
   const finalStatus = await waitForInstall(installResult.installId);
   log(JSON.stringify(finalStatus, null, 2));
 }