@empirical-gauzza/cli 1.0.36 → 1.0.37

package/lib/empiricalTokensFormat.js

@@ -0,0 +1,66 @@
+'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. 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.
+function isInteractiveTerminal() {
+  return Boolean(process.stdin.isTTY) || 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>]');
@@ -52,6 +53,15 @@ 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('');
   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');

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) {
@@ -186,6 +193,7 @@ function httpForm(urlString, method, params, headers = {}) {
 module.exports = {
   httpGet,
   httpErrorFromResponse,
+  formatApiError,
   printApiError,
   httpJson,
   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) {

package/lib/installers/nativePlugin.js

@@ -17,7 +17,7 @@ const { skillFilePath } = require('../skillPaths');
 
 const EMPIRICAL_PLUGIN_SOURCE = process.env.EMPIRICAL_PLUGIN_SOURCE || 'mattgauzza/empirical-memory-plugin';
 const CORE_PLUGIN_NAME = 'empirical-memory';
-const OPTIONAL_PLUGIN_NAMES = ['empirical-work-history', 'empirical-scar-tissue', 'empirical-todo'];
+const OPTIONAL_PLUGIN_NAMES = ['empirical-work-history', 'empirical-scar-tissue', 'empirical-todo', 'empirical-voice'];
 
 function runPluginCommand(command, args, options = {}) {
   return runResolvedCommand(command, args, { stdio: 'inherit', ...options });

package/lib/installers/promptBlocks.js

@@ -23,6 +23,7 @@ const INSTALL_PROMPT_OPTIONS_DEFAULTS = Object.freeze({
   recordWorkHistory: true,
   recordScarTissue: true,
   recordTodos: false,
+  installVoicePlugin: false,
   storeInstructionArtifacts: false,
   checkMemoryBeforeAskingContext: true,
   durableWritesOnly: true
@@ -75,6 +76,8 @@ function normalizeInstallPromptOptions(options = {}) {
       options.recordScarTissue !== false,
     recordTodos:
       options.recordTodos === true,
+    installVoicePlugin:
+      options.installVoicePlugin === true,
     storeInstructionArtifacts:
       options.storeInstructionArtifacts === true,
     checkMemoryBeforeAskingContext:
@@ -228,6 +231,7 @@ function formatPromptOptionSummary(promptOptions) {
     ['Record timestamped work history', promptOptions.recordWorkHistory],
     ['Record scar-tissue guidance', promptOptions.recordScarTissue],
     ['Enable project-based Todo skill', promptOptions.recordTodos],
+    ['Install the writing voice skill', promptOptions.installVoicePlugin],
     ['Store/recall instruction artifacts', promptOptions.storeInstructionArtifacts],
     ['Check memory before asking for context', promptOptions.checkMemoryBeforeAskingContext],
     ['Store durable context only', promptOptions.durableWritesOnly]
@@ -313,6 +317,10 @@ async function collectInstallerPromptOptions() {
     'Install the project-based Todo skill for actionable follow-ups?',
     false
   );
+  const installVoicePlugin = await askYesNo(
+    'Install the writing voice skill so agents write as you once you have saved a voice?',
+    false
+  );
   const storeInstructionArtifacts = await askYesNo(
     'Store and recall instruction artifacts (AGENTS.md/CLAUDE.md/skills-style rules) in Empirical?',
     false
@@ -337,6 +345,7 @@ async function collectInstallerPromptOptions() {
     recordWorkHistory,
     recordScarTissue,
     recordTodos,
+    installVoicePlugin,
     storeInstructionArtifacts,
     checkMemoryBeforeAskingContext,
     durableWritesOnly

package/lib/memoryCommands.js

@@ -33,7 +33,9 @@ function renderMemoryResultsTable(items) {
   const rows = (Array.isArray(items) ? items : []).map((m) => ({
     id: m.id || m._id || '',
     category: m.category || '',
-    summary: truncateForTable(m.summary, 60),
+    // A row marked usage 'style_preference_only' (a writing voice memory) says so, so a person
+    // reading the table sees what an agent reading the JSON sees.
+    summary: truncateForTable(m.summary, 60) + (m.usage === 'style_preference_only' ? ' [style]' : ''),
     // The recall front door emits `score` (toQueryRow plus score in mcp/tools/memory.ts); the
     // older /query route emitted rankScore/similarityScore. Read all three so the column is not
     // blank against a real /recall row. On the list pathways score is deliberately absent, and

package/lib/pluginCommands.js

@@ -4,7 +4,7 @@ const { log, warn, uiHeader, uiSuccess } = require('./ui');
 const { detectInstallTargets } = require('./installers/detect');
 const {
   installNativePlugin,
-  OPTIONAL_PLUGIN_NAMES = ['empirical-work-history', 'empirical-scar-tissue', 'empirical-todo']
+  OPTIONAL_PLUGIN_NAMES = ['empirical-work-history', 'empirical-scar-tissue', 'empirical-todo', 'empirical-voice']
 } = require('./installers/nativePlugin');
 const { checkNativePluginUpdates } = require('./pluginUpdateCheck');
 const { addInstalledHosts } = require('./deviceConfig');
@@ -35,6 +35,7 @@ function resolvePluginNames(args = []) {
   if (args.includes('--all-optional') || args.includes('--work-history')) names.push('empirical-work-history');
   if (args.includes('--all-optional') || args.includes('--scar-tissue')) names.push('empirical-scar-tissue');
   if (args.includes('--all-optional') || args.includes('--todo')) names.push('empirical-todo');
+  if (args.includes('--all-optional') || args.includes('--voice')) names.push('empirical-voice');
   return names.filter((name) => name === 'empirical-memory' || OPTIONAL_PLUGIN_NAMES.includes(name));
 }
 
@@ -82,7 +83,7 @@ async function runPluginCommand(args = []) {
   }
   log('');
   log('Native plugin installation does not configure MCP or credentials.');
-  log('Optional packages: --work-history, --scar-tissue, --todo, or --all-optional.');
+  log('Optional packages: --work-history, --scar-tissue, --todo, --voice, or --all-optional.');
   log('Use `empirical auth login` for normal CLI OAuth, or the full `empirical install` flow for MCP setup.');
 }