@empirical-gauzza/cli 1.0.36 → 1.0.38

package/lib/empiricalTokensFormat.js

@@ -0,0 +1,68 @@
+'use strict';
+
+// Empirical Tokens wording and the cost gate shared by every CLI command that can start a priced
+// action (`setup run`, `blueprint install`) or print a reset date (`usage`, `whoami`, error hints).
+
+// '<Month> <D> at <h:mm AM/PM> <TZ>' in this machine's time zone, e.g. 'October 31 at 8:00 PM EDT'.
+// The reset instant is 00:00 UTC on the 1st, so the local date can be the day before: date AND time
+// are always shown. This is a standalone copy of formatResetInstant in packages/shared (the CLI is
+// published on its own and does not import shared); both are pinned to the same fixtures in tests.
+// timeZone defaults to the machine's own; an invalid or empty one reads as UTC and says so. Returns
+// null for a missing or unreadable date so callers can fall back to neutral wording.
+function resetLabel(resetsAt, timeZone) {
+  if (resetsAt === undefined || resetsAt === null || resetsAt === '') return null;
+  const date = new Date(resetsAt);
+  if (Number.isNaN(date.getTime())) return null;
+  const machineZone = (() => {
+    try { return Intl.DateTimeFormat().resolvedOptions().timeZone; } catch (_error) { return null; }
+  })();
+  const requested = timeZone === undefined ? machineZone : timeZone;
+  const zones = [typeof requested === 'string' && requested.trim() ? requested.trim() : null, 'UTC'].filter(Boolean);
+  for (const zone of zones) {
+    try {
+      const parts = new Intl.DateTimeFormat('en-US', {
+        timeZone: zone, month: 'long', day: 'numeric', hour: 'numeric', minute: '2-digit', timeZoneName: 'short'
+      }).formatToParts(date);
+      const get = (type) => (parts.find((p) => p.type === type) || {}).value || '';
+      return `${get('month')} ${get('day')} at ${get('hour')}:${get('minute')} ${get('dayPeriod')} ${get('timeZoneName')}`;
+    } catch (_error) {
+      // Invalid time zone: try UTC.
+    }
+  }
+  return null;
+}
+
+// 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, 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() {
+  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
+// resolves only when a person at a terminal typed y or yes; every other path (no prompter, no terminal,
+// any other reply) prints why nothing started and exits 1. The cost is never accepted on the person's
+// behalf: acceptance reaches the server only from --accept-cost or from this prompt.
+//   preview   the server's preview payload (message, empiricalTokenCost)
+//   prompter  createPrompter(...) result, or null for a non-interactive run
+//   warn      the CLI's stderr printer
+//   sanitize  terminal sanitiser for server text
+async function confirmCostOrExit(preview, { prompter, warn, sanitize = String }) {
+  warn(sanitize(preview.message || `This uses ${preview.empiricalTokenCost} Empirical Tokens.`));
+  if (!prompter || !isInteractiveTerminal()) {
+    warn('Nothing was started. Re-run with --accept-cost to start.');
+    process.exit(1);
+  }
+  const reply = (await prompter.askText('Start? (y/N)')).trim();
+  if (!/^(y|yes)$/i.test(reply)) {
+    warn('Nothing was started.');
+    process.exit(1);
+  }
+}
+
+const isCostPreview = (value) => Boolean(value) && value.status === 'cost_confirmation_required';
+
+module.exports = { resetLabel, isInteractiveTerminal, confirmCostOrExit, isCostPreview };

package/lib/help.js

@@ -13,7 +13,7 @@ function showHelp() {
   log('');
   log('Usage:');
   log('  empirical install');
-  log('  empirical plugin install <codex|copilot|claude|all> [--all-optional]');
+  log('  empirical plugin install <codex|copilot|claude|all> [--all-optional|--voice]');
   log('  empirical plugin check [--force]');
   log('  empirical policy show [--refresh]');
   log('  empirical policy set --json <policy>');
@@ -25,6 +25,7 @@ function showHelp() {
   log('                                               Mint a new API key (--replace-all wipes the existing ones)');
   log('  empirical auth revoke-key (--key-id <id> | --all)');
   log('                                               Revoke one API key, or every key on the account');
+  log('  empirical usage [--json]                     Memory, installs and Empirical Tokens this month');
   log('  empirical oauth bootstrap headless [--print-access-token]');
   log('                                                First-time token setup for CI/headless/API-key use');
   log('  empirical oauth bootstrap headless --write-env [--env-output <path>]');
@@ -45,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');
@@ -52,6 +60,16 @@ function showHelp() {
   log('  empirical workspace delete <number|name|id> [--confirm]');
   log('                                                Soft-delete a team workspace (dry-run without --confirm)');
   log('');
+  log('Guided setups:');
+  log('  empirical setup list                          List guided setups');
+  log('  empirical setup run <setupId> [--accept-cost] Run one interactively');
+  log('  empirical setup run <setupId> --answers <f>   Run from a JSON file of answers');
+  log('  empirical setup resume <sessionId>            Show the current question');
+  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');
   log('  plugin install <target>        Install core plugin; add --all-optional or capability flags');
@@ -79,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>]');

package/lib/http.js

@@ -52,8 +52,10 @@ function httpErrorFromResponse(method, urlString, statusCode, data) {
 
   const error = new Error(parts.join(' '));
   error.statusCode = statusCode;
+  error.serverMessage = baseMsg;
   error.code = data.code || null;
   error.upgradeUrl = upgradeUrl;
+  error.details = data.details && typeof data.details === 'object' ? data.details : null;
   error.retryAfterSeconds = retryAfterSeconds;
   return error;
 }
@@ -61,14 +63,19 @@ function httpErrorFromResponse(method, urlString, statusCode, data) {
 // 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({
+// JSON.stringify escapes C0 controls but not C1 (0x80 to 0x9f), which some terminals act on.
+function formatApiError(error) {
+  return JSON.stringify({
     error: true,
     code: error.code || 'api_error',
     message: error.message,
     ...(error.retryAfterSeconds != null && { retryAfterSeconds: error.retryAfterSeconds }),
     ...(error.upgradeUrl && { upgradeUrl: error.upgradeUrl })
-  }));
+  }).replace(/[\x80-\x9f]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+
+function printApiError(error) {
+  warn(formatApiError(error));
 }
 
 function httpJson(urlString, method, payload, headers = {}, timeoutMs = 0) {
@@ -131,6 +138,163 @@ function httpJson(urlString, method, payload, headers = {}, timeoutMs = 0) {
   });
 }
 
+// A filename travels to the server inside a Content-Disposition header we build by hand. Local
+// filenames are arbitrary bytes: a quote ends the parameter early and a CR/LF splits the part
+// header, so either one lets a filename forge headers or a whole extra part. multer/busboy also
+// has no portable unescaping here, so these characters are replaced rather than escaped.
+function sanitizeMultipartFilename(value) {
+  const cleaned = String(value || '')
+    .replace(/[\r\n"\\]/g, '_')
+    // C0 controls would be sent verbatim into a header line.
+    .replace(/[\x00-\x1f\x7f]/g, '_')
+    .trim();
+  return cleaned || 'attachment';
+}
+
+function buildMultipartBody(boundary, fields, file) {
+  const parts = [];
+  for (const [name, value] of Object.entries(fields || {})) {
+    if (value === undefined || value === null || value === '') continue;
+    parts.push(Buffer.from(
+      `--${boundary}\r\nContent-Disposition: form-data; name="${sanitizeMultipartFilename(name)}"\r\n\r\n${String(value)}\r\n`,
+      'utf8'
+    ));
+  }
+  parts.push(Buffer.from(
+    `--${boundary}\r\n`
+    + `Content-Disposition: form-data; name="${sanitizeMultipartFilename(file.field || 'file')}";`
+    + ` filename="${sanitizeMultipartFilename(file.filename)}"\r\n`
+    + `Content-Type: ${sanitizeMultipartFilename(file.contentType || 'application/octet-stream')}\r\n\r\n`,
+    'utf8'
+  ));
+  parts.push(file.buffer);
+  parts.push(Buffer.from(`\r\n--${boundary}--\r\n`, 'utf8'));
+  return Buffer.concat(parts);
+}
+
+/**
+ * multipart/form-data with exactly one file part, for attachment uploads. The CLI ships with one
+ * dependency and no form-data library, and the body is already fully buffered (the per-file cap
+ * is 25MB), so the body is assembled here rather than streamed.
+ *
+ * Resolves/rejects on the same contract as httpJson, so callers can use printApiError unchanged.
+ */
+function httpMultipart(urlString, method, { fields = {}, file }, headers = {}, timeoutMs = 0) {
+  return new Promise((resolve, reject) => {
+    if (!file || !Buffer.isBuffer(file.buffer)) {
+      reject(new Error('httpMultipart requires file.buffer'));
+      return;
+    }
+    const parsed = new URL(urlString);
+    const lib = parsed.protocol === 'https:' ? https : http;
+    const boundary = `----empiricalcli${Date.now().toString(16)}${Math.random().toString(16).slice(2)}`;
+    const body = buildMultipartBody(boundary, fields, file);
+
+    const req = lib.request(
+      parsed,
+      {
+        method,
+        headers: {
+          Accept: 'application/json',
+          // The server infers source 'cli' from this (see @empirical/core memoryAuthorship).
+          'User-Agent': 'empirical-cli/1.0',
+          'Content-Type': `multipart/form-data; boundary=${boundary}`,
+          'Content-Length': body.length,
+          ...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`));
+      });
+    }
+    req.write(body);
+    req.end();
+  });
+}
+
+/**
+ * GET that keeps the response as BYTES. httpJson would decode the body as utf8 and corrupt any
+ * binary, so downloads cannot reuse it. A non-2xx body is still JSON here (the attachment
+ * download route answers 404/410 as JSON), so failures are parsed and rejected on the same
+ * contract as httpJson.
+ *
+ * @returns {Promise<{ statusCode: number, headers: object, buffer: Buffer }>}
+ */
+function httpDownload(urlString, headers = {}, timeoutMs = 0) {
+  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',
+          ...headers
+        }
+      },
+      (res) => {
+        const chunks = [];
+        res.on('data', (chunk) => chunks.push(chunk));
+        res.on('end', () => {
+          const buffer = Buffer.concat(chunks);
+          const statusCode = res.statusCode || 0;
+          if (statusCode < 200 || statusCode >= 300) {
+            let data = {};
+            try {
+              data = JSON.parse(buffer.toString('utf8'));
+            } catch (_error) {
+              data = { raw: buffer.toString('utf8').slice(0, 500) };
+            }
+            reject(httpErrorFromResponse('GET', urlString, statusCode, data));
+            return;
+          }
+          resolve({ statusCode, headers: res.headers || {}, buffer });
+        });
+      }
+    );
+
+    req.on('error', reject);
+    if (Number.isFinite(timeoutMs) && timeoutMs > 0) {
+      req.setTimeout(timeoutMs, () => {
+        req.destroy(new Error(`request timeout after ${timeoutMs}ms`));
+      });
+    }
+    req.end();
+  });
+}
+
 function httpForm(urlString, method, params, headers = {}) {
   return new Promise((resolve, reject) => {
     const parsed = new URL(urlString);
@@ -186,7 +350,11 @@ function httpForm(urlString, method, params, headers = {}) {
 module.exports = {
   httpGet,
   httpErrorFromResponse,
+  formatApiError,
   printApiError,
   httpJson,
+  httpMultipart,
+  httpDownload,
+  sanitizeMultipartFilename,
   httpForm
 };

package/lib/installWizard.js

@@ -32,6 +32,7 @@ function pluginNamesForInstallerOptions(options = {}) {
   if (options.recordWorkHistory !== false) names.push('empirical-work-history');
   if (options.recordScarTissue !== false) names.push('empirical-scar-tissue');
   if (options.recordTodos === true) names.push('empirical-todo');
+  if (options.installVoicePlugin === true) names.push('empirical-voice');
   return names.filter((name) => name === 'empirical-memory' || OPTIONAL_PLUGIN_NAMES.includes(name));
 }
 
@@ -405,5 +406,6 @@ async function runInstallFlow() {
 }
 
 module.exports = {
-  runInstallFlow
+  runInstallFlow,
+  pluginNamesForInstallerOptions
 };

package/lib/installers/coreMemoryBlock.js

@@ -23,7 +23,8 @@ const PLUGIN_DESCRIPTIONS = {
   [CORE_PLUGIN_NAME]: 'query and save durable project/user context - the core memory skill',
   'empirical-work-history': 'record concise summaries of completed work for future agents',
   'empirical-scar-tissue': 'record recurring failure patterns and prevention guidance',
-  'empirical-todo': 'track actionable follow-ups by project'
+  'empirical-todo': 'track actionable follow-ups by project',
+  'empirical-voice': "write in the person's saved voice whenever you write as them"
 };
 
 function describePlugin(name) {