@empirical-gauzza/cli 1.0.37 → 1.0.38

package/bin/empirical.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 'use strict';
 

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/constants.js

@@ -183,6 +183,46 @@ Bulk delete by tag, category, or everything (exactly one selector):
 Without \`--confirm\`, always a dry-run that prints the count that would be deleted; no writes
 happen. Re-run with \`--confirm\` to actually delete.
 
+### tree
+One item and everything nested under it, as a readable document. The server assembles it in
+one query, so there is no walking the graph level by level.
+
+    empirical memory tree (--memory-id <id> | --match <q>) [--depth 10] [--max-nodes 500] [--no-notes] [--format markdown|json] [--out <path>]
+
+Flags:
+- \`--depth\`: how many levels below the starting item to include, default 10. 0 is the item alone
+- \`--max-nodes\`: cap on items in the document, default 500. When it bites, stderr carries a
+  truncated warning and the document itself stays clean for redirection
+- \`--no-notes\`: leave each item's notes out, for a bare outline
+- \`--format json\`: print the nodes and metadata instead of the document (markdown is the default
+  here, unlike other memory subcommands, because the point of this one is something to read)
+- \`--out <path>\`: write the document to a file instead of stdout
+
+Items nest only in a workspace that has a shape. For an ordinary memory this returns that one
+memory as a one-section document.
+
+### attachment
+Files attached to a memory. Up to 20 files per memory, 25MB each. Every subcommand takes the
+target memory as \`--memory-id <id>\` or \`--match <query>\`, the same way \`note\` and \`update\` do.
+
+    empirical memory attachment list    (--memory-id <id> | --match <q>) [--include-deleted] [--format table] [--pretty]
+    empirical memory attachment add     (--memory-id <id> | --match <q>) --file <path> [--author-type user|agent]
+    empirical memory attachment get     (--memory-id <id> | --match <q>) --attachment-id <id> [--out <path>] [--force]
+    empirical memory attachment delete  (--memory-id <id> | --match <q>) --attachment-id <id> [--confirm]
+    empirical memory attachment restore (--memory-id <id> | --match <q>) --attachment-id <id>
+
+\`empirical memory attach\` is shorthand for \`attachment add\`, and \`empirical memory attachments\`
+for \`attachment list\`.
+
+Notes:
+- \`delete\` is a soft delete: the file stays restorable for 30 days, then the purge worker
+  removes the bytes. Without \`--confirm\` it is a dry run, like \`memory delete\`.
+- \`list --include-deleted\` shows deleted rows with the date their bytes get purged.
+- \`get\` writes bytes to a file, not to stdout: \`--out <path>\` chooses where (a directory is
+  allowed), and without it the server's filename is used in the current directory. An existing
+  file is never overwritten without \`--force\`. \`--out -\` writes the bytes to stdout for piping.
+- Attachments need a paid plan; the free tier's attachment pool is 0 bytes.
+
 ### export / import
 Export memories to a versioned, round-trippable JSON document and re-import them later.
 
@@ -297,6 +337,16 @@ Note: workspace selection may be admin-locked for some OAuth clients.
 
 Creates a team workspace using your existing plan quota and prints its workspace ID.
 
+### Set up or re-shape a workspace by interview
+
+    empirical workspace create --interview
+    empirical workspace shape --workspace-id <id>
+    empirical setup abandon <sessionId>
+
+The interview asks what the workspace is for, offers kinds of item, statuses, fields and rules to pick from, shows a draft, and creates the workspace (or saves the new shape) and emails any invites only after you confirm. At the first review type next to choose who to invite (a bare yes is not a choice there), or confirm to finish with nobody invited, or type a change. On a new workspace a change can be its name (for example: change the name to Wellness on Balance); the name of an existing workspace is changed in its settings, not here. After the invitations, a yes confirms. In a re-shape the workspace's current kinds of item, statuses, fields and rules are listed first as Now in use: say keep, or only add things after a bar, to start from them as they are. Adding works; taking something away is not possible yet. In a script, the draft answer may be a list sent in order, for example for a new workspace {"draft": ["change the name to Leads", "next"], "invites": "ana@example.com writer", "confirm": "confirm"}. \`create --interview\` always makes a new workspace and takes no name. \`shape\` re-shapes an existing team workspace you manage: pass \`--workspace-id\`. Without it, at a terminal only, the command names the workspace this directory is bound to and asks you to confirm it; in a script (\`--answers\`), with \`--accept-cost\`, or with no terminal it refuses and needs \`--workspace-id\`. \`--answers <file.json>\` runs it from a map of question key to answer, and \`--accept-cost\` agrees to the Empirical Tokens cost in a script (a person at a terminal is asked instead).
+
+A new interview is charged. \`setup abandon\` stops one but does not return what it cost. When the interview is not switched on for your account, the start answers that nothing was started or charged.
+
 ### Use a workspace
 
     empirical workspace use <number|name|id>

package/lib/empiricalTokensFormat.js

@@ -33,11 +33,13 @@ function resetLabel(resetsAt, timeZone) {
 }
 
 // A charge is offered only to a real terminal; piped input never accepts one. EMPIRICAL_TEST_ASSUME_TTY=1
-// exists only so tests can drive the prompt through a pipe. It is not documented in --help on purpose,
-// it must be exactly '1', and nothing in the product sets it; setting it only lets a person who typed
-// 'y' at the prompt through a pipe, it never accepts a cost by itself.
+// exists only so tests can drive the prompt through a pipe, and it applies ONLY when NODE_ENV is 'test':
+// a stray copy of it in a real shell cannot switch off the non-interactive refusals (a paid re-shape from
+// a binding, a cost accepted with no one at the keyboard). It is not documented in --help on purpose and
+// nothing in the product sets it.
 function isInteractiveTerminal() {
-  return Boolean(process.stdin.isTTY) || process.env.EMPIRICAL_TEST_ASSUME_TTY === '1';
+  if (process.stdin.isTTY) return true;
+  return process.env.NODE_ENV === 'test' && process.env.EMPIRICAL_TEST_ASSUME_TTY === '1';
 }
 
 // A priced start answered 200 with status 'cost_confirmation_required' and started nothing. This

package/lib/help.js

@@ -46,6 +46,13 @@ function showHelp() {
   log('  empirical workspace unbind                   Remove this project\'s workspace binding');
   log('  empirical workspace create <name> [--description <text>]');
   log('                                                Create a new shared team workspace');
+  log('  empirical workspace create --interview [--answers <file.json>] [--accept-cost]');
+  log('                                                Set up a new shared workspace by interview: it offers options, shows a');
+  log('                                                draft, and creates the workspace and invites only when you say yes');
+  log('  empirical workspace shape [--workspace-id <id>] [--answers <file.json>] [--accept-cost]');
+  log('                                                Re-shape a team workspace you manage by interview. Without --workspace-id it');
+  log('                                                confirms the workspace bound to this directory with you, at a terminal only;');
+  log('                                                in a script or with --accept-cost it needs --workspace-id. A new interview is charged');
   log('  empirical workspace invite create [--role reader|writer|manager] [--expires-in-days <n>] [--max-uses <n>]');
   log('                                                Create a shareable invite link for the active team workspace');
   log('  empirical workspace invite list              List active invites for the active team workspace');
@@ -61,6 +68,7 @@ function showHelp() {
   log('  empirical setup answer <sessionId> <key> <v>  Answer a question');
   log('  empirical setup confirm <sessionId> <hash>    Confirm and install a reviewed draft');
   log('  empirical setup finish <sessionId>            Finish a scripted setup early');
+  log('  empirical setup abandon <sessionId>           Stop a workspace interview (what it cost is not returned)');
   log('');
   log('Options:');
   log('  install                        Interactive installer for Codex/Copilot/Claude CLI integration');
@@ -89,6 +97,10 @@ function showHelp() {
   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 attach          Attach a file to a memory [--file <path>]');
+  log('  empirical memory attachments     List the files on a memory [--include-deleted] [--format table]');
+  log('  empirical memory attachment      Full file commands: list, add, get, delete, restore');
+  log('  empirical memory tree            One item plus everything nested under it, as a document');
   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>]');