@empirical-gauzza/cli 1.0.26 → 1.0.27

package/lib/installers/detect.js

@@ -1,47 +1,47 @@
-'use strict';
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { commandExists } = require('../fsUtils');
-const { installCodex } = require('./codex');
-const { installCopilot } = require('./copilot');
-const { installClaude } = require('./claude');
-
-function detectInstallTargets() {
-  const home = os.homedir();
-  const targets = [];
-
-  const codexDetected = commandExists('codex') || fs.existsSync(path.join(home, '.codex'));
-  if (codexDetected) {
-    targets.push({
-      id: 'codex',
-      label: 'Codex CLI',
-      install: installCodex
-    });
-  }
-
-  const copilotDetected = commandExists('copilot') || fs.existsSync(path.join(home, '.copilot'));
-  if (copilotDetected) {
-    targets.push({
-      id: 'copilot',
-      label: 'GitHub Copilot CLI',
-      install: installCopilot
-    });
-  }
-
-  const claudeDetected = commandExists('claude') || fs.existsSync(path.join(home, '.claude'));
-  if (claudeDetected) {
-    targets.push({
-      id: 'claude',
-      label: 'Claude CLI',
-      install: installClaude
-    });
-  }
-
-  return targets;
-}
-
-module.exports = {
-  detectInstallTargets
-};
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { commandExists } = require('../fsUtils');
+const { installCodex } = require('./codex');
+const { installCopilot } = require('./copilot');
+const { installClaude } = require('./claude');
+
+function detectInstallTargets() {
+  const home = os.homedir();
+  const targets = [];
+
+  const codexDetected = commandExists('codex') || fs.existsSync(path.join(home, '.codex'));
+  if (codexDetected) {
+    targets.push({
+      id: 'codex',
+      label: 'Codex CLI',
+      install: installCodex
+    });
+  }
+
+  const copilotDetected = commandExists('copilot') || fs.existsSync(path.join(home, '.copilot'));
+  if (copilotDetected) {
+    targets.push({
+      id: 'copilot',
+      label: 'GitHub Copilot CLI',
+      install: installCopilot
+    });
+  }
+
+  const claudeDetected = commandExists('claude') || fs.existsSync(path.join(home, '.claude'));
+  if (claudeDetected) {
+    targets.push({
+      id: 'claude',
+      label: 'Claude CLI',
+      install: installClaude
+    });
+  }
+
+  return targets;
+}
+
+module.exports = {
+  detectInstallTargets
+};

package/lib/installers/skill-variants/SKILL.both.md

@@ -123,6 +123,18 @@ Two rules that are not optional:
   codebase, stop: that is work-history or scar-tissue, and filing it here makes it indistinguishable
   from something the user actually said or lived. Downstream features read these as the user's life.
 
+  **Say which one it is: pass `authorType`.** Same distinction, made explicit in the data instead
+  of left to be guessed from which transport you happened to use. `authorType: "user"` when the
+  memory is about the user — something they said, decided, prefer, or are working toward.
+  `authorType: "agent"` when it is your own work. Do not set `"agent"` merely because you are the
+  one calling: an agent writing down a real fact about the user is recording a user-authored fact,
+  and that is the whole point of this tool. On the CLI it is `--author-type user|agent`. Omit it
+  when you genuinely cannot tell, and it stays unresolved rather than being invented.
+
+  This is read back at retrieval time to keep an agent's session notes out of answers about the
+  user's own life and work, so a wrong value does not show up as a warning, it shows up as the
+  wrong memories coming back.
+
 - Append a correction or follow-up to an existing memory with `add_note_by_query` / `empirical memory note`.
 - Patch an existing memory with `update_memory_by_query` / `empirical memory update`.
 - Delete only when the user explicitly asks; use the delete tool with confirmation, or `empirical memory delete --match "<memory>" --confirm`.

package/lib/installers/skill-variants/SKILL.cli.md

@@ -115,6 +115,18 @@ Two rules that are not optional:
   codebase, stop: that is work-history or scar-tissue, and filing it here makes it indistinguishable
   from something the user actually said or lived. Downstream features read these as the user's life.
 
+  **Say which one it is: pass `authorType`.** Same distinction, made explicit in the data instead
+  of left to be guessed from which transport you happened to use. `authorType: "user"` when the
+  memory is about the user — something they said, decided, prefer, or are working toward.
+  `authorType: "agent"` when it is your own work. Do not set `"agent"` merely because you are the
+  one calling: an agent writing down a real fact about the user is recording a user-authored fact,
+  and that is the whole point of this tool. On the CLI it is `--author-type user|agent`. Omit it
+  when you genuinely cannot tell, and it stays unresolved rather than being invented.
+
+  This is read back at retrieval time to keep an agent's session notes out of answers about the
+  user's own life and work, so a wrong value does not show up as a warning, it shows up as the
+  wrong memories coming back.
+
 - Append a correction or follow-up to an existing memory with `empirical memory note`.
 - Patch an existing memory with `empirical memory update`.
 - Delete only when the user explicitly asks: `empirical memory delete --match "<memory>" --confirm`.

package/lib/installers/skill-variants/SKILL.mcp.md

@@ -92,6 +92,18 @@ Two rules that are not optional:
   codebase, stop: that is work-history or scar-tissue, and filing it here makes it indistinguishable
   from something the user actually said or lived. Downstream features read these as the user's life.
 
+  **Say which one it is: pass `authorType`.** Same distinction, made explicit in the data instead
+  of left to be guessed from which transport you happened to use. `authorType: "user"` when the
+  memory is about the user — something they said, decided, prefer, or are working toward.
+  `authorType: "agent"` when it is your own work. Do not set `"agent"` merely because you are the
+  one calling: an agent writing down a real fact about the user is recording a user-authored fact,
+  and that is the whole point of this tool. On the CLI it is `--author-type user|agent`. Omit it
+  when you genuinely cannot tell, and it stays unresolved rather than being invented.
+
+  This is read back at retrieval time to keep an agent's session notes out of answers about the
+  user's own life and work, so a wrong value does not show up as a warning, it shows up as the
+  wrong memories coming back.
+
 - Append a correction or follow-up to an existing memory with `add_note_by_query`.
 - Patch an existing memory with `update_memory_by_query`.
 - Delete only when the user explicitly asks; use `delete_memory_by_query` with confirmation.

package/lib/memoryCommands.js

@@ -47,7 +47,7 @@ const MEMORY_SUBCOMMAND_USAGE = {
   query: 'Usage: empirical memory query --match <query> [--top-k 3] [--category <cat>] [--tags <t1,t2>] [--tags-all <t1,t2>] [--status <s1,s2>] [--pretty] [--format table]',
   get: 'Usage: empirical memory get --memory-id <id> [--pretty]',
   list: 'Usage: empirical memory list [--category <cat>] [--tags <t1,t2>] [--start-date <ISO>] [--end-date <ISO>] [--limit 20] [--cursor <cursor>] [--oldest] [--pretty] [--format table]',
-  record: 'Usage: empirical memory record --category <cat> (--summary <text> | --summary - | --summary-file <path>) [--tags t1,t2] [--node-type observation] [--json-file <path>] [--no-dedupe] [--no-auto-link]',
+  record: 'Usage: empirical memory record --category <cat> (--summary <text> | --summary - | --summary-file <path>) [--tags t1,t2] [--node-type observation] [--json-file <path>] [--no-dedupe] [--no-auto-link] [--author-type user|agent]',
   note: 'Usage: empirical memory note --text <note> (--match <query> | --memory-id <id>) [--min-score 0.35]',
   update: 'Usage: empirical memory update (--match <query> | --memory-id <id>) (--patch-json <json> | --json-file <path>) [--min-score 0.35]',
   delete: 'Usage: empirical memory delete (--match <query> | --memory-id <id>) [--confirm] [--min-score 0.35]\nUsage: empirical memory delete (--tag <t> | --category <c> | --all) --confirm',
@@ -351,7 +351,7 @@ async function runMemoryRecord(args) {
     }
 
     if (!category || !summary) {
-      warn('Usage: empirical memory record --category <cat> (--summary <text> | --summary - | --summary-file <path>) [--tags t1,t2] [--node-type observation] [--json-file <path>] [--no-dedupe] [--no-auto-link]');
+      warn('Usage: empirical memory record --category <cat> (--summary <text> | --summary - | --summary-file <path>) [--tags t1,t2] [--node-type observation] [--json-file <path>] [--no-dedupe] [--no-auto-link] [--author-type user|agent]');
       warn('Valid categories: ' + MEMORY_CATEGORIES.join(', '));
       process.exit(1);
     }
@@ -395,6 +395,29 @@ async function runMemoryRecord(args) {
     payload.autoLink = false;
   }
 
+  // Authorship (2026-09-09). `source` is observable truth: this is the CLI, so say so.
+  // Until now the CLI sent nothing, the server fell back to the transport it saw ('api'),
+  // and api maps to authorType 'user' because that mapping was written for the web portal.
+  // Every agent write through this command was therefore stored as authored by the user.
+  // 'cli' resolves to authorType 'unknown', which is the honest answer when nobody says.
+  if (payload.source === undefined) payload.source = 'cli';
+
+  // --author-type lets the caller state what the transport cannot know. An agent recording
+  // its own session notes should pass 'agent'; an agent recording something the user said
+  // or decided should pass 'user'. Omitted, it stays 'unknown' rather than being guessed.
+  const authorType = parseOption(args, '--author-type', '');
+  if (authorType) {
+    if (!['user', 'agent', 'system'].includes(authorType)) {
+      warn(JSON.stringify({
+        error: true,
+        code: 'invalid_author_type',
+        message: `Invalid --author-type "${authorType}". Valid: user, agent, system`
+      }));
+      process.exit(1);
+    }
+    payload.authorType = authorType;
+  }
+
   const accessToken = requireAccessToken();
   const baseUrl = resolveApiBaseUrl();
   const recordUrl = new URL('/api/v1/memories', baseUrl).toString();

package/lib/oauthClient.js

@@ -1,222 +1,222 @@
-'use strict';
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { readJsonIfExists, writeFile, ensureDir } = require('./fsUtils');
-const { getEnv } = require('./env');
-const { runResolvedCommand } = require('./fsUtils');
-
-function getLocalOAuthClientPath() {
-  return path.join(os.homedir(), '.empirical', 'oauth-client.json');
-}
-
-function readStoredOAuthClient() {
-  const stored = readJsonIfExists(getLocalOAuthClientPath());
-  if (!stored || typeof stored !== 'object') return null;
-  const clientId = String(stored.clientId || '').trim();
-  if (!clientId) return null;
-  return {
-    clientId,
-    clientSecret: String(stored.clientSecret || '')
-  };
-}
-
-function writeStoredOAuthClient(clientId, clientSecret) {
-  const payload = {
-    clientId: String(clientId || '').trim(),
-    clientSecret: String(clientSecret || '').trim(),
-    updatedAt: new Date().toISOString()
-  };
-  writeFile(getLocalOAuthClientPath(), `${JSON.stringify(payload, null, 2)}\n`);
-}
-
-function clearStoredOAuthClient() {
-  const storePath = getLocalOAuthClientPath();
-  if (fs.existsSync(storePath)) {
-    fs.unlinkSync(storePath);
-  }
-}
-
-function maskSecret(value) {
-  const raw = String(value || '');
-  if (!raw) return '(not set)';
-  if (raw.length <= 8) return '*'.repeat(raw.length);
-  return `${raw.slice(0, 4)}...${raw.slice(-4)}`;
-}
-
-function generateRandomString(length = 32) {
-  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~';
-  let result = '';
-  for (let i = 0; i < length; i += 1) {
-    result += chars.charAt(Math.floor(Math.random() * chars.length));
-  }
-  return result;
-}
-
-function base64url(buf) {
-  return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
-}
-
-function generatePKCE() {
-  const crypto = require('crypto');
-  const codeVerifier = generateRandomString(128);
-  const codeChallenge = base64url(crypto.createHash('sha256').update(codeVerifier).digest());
-  return { codeVerifier, codeChallenge };
-}
-
-function decodeJwtPayload(token) {
-  try {
-    const parts = String(token).split('.');
-    if (parts.length !== 3) return null;
-    return JSON.parse(Buffer.from(parts[1], 'base64url').toString());
-  } catch (_error) {
-    return null;
-  }
-}
-
-function isJwtToken(token) {
-  return typeof token === 'string' && token.split('.').length === 3;
-}
-
-function isJwtExpired(token, skewSeconds = 30) {
-  const payload = decodeJwtPayload(token);
-  if (!payload || typeof payload.exp !== 'number') return true;
-  return payload.exp < Math.floor(Date.now() / 1000) + skewSeconds;
-}
-
-function getHeadlessTokenPath() {
-  return path.resolve(getEnv('EMPIRICAL_TOKEN_OUTPUT', '.empirical/headless-token.json'));
-}
-
-function getOAuthSessionPath() {
-  return path.join(os.homedir(), '.empirical', 'oauth-session.json');
-}
-
-function readOAuthSession() {
-  const session = readJsonIfExists(getOAuthSessionPath());
-  if (!session || typeof session !== 'object') return null;
-  return session;
-}
-
-function writeOAuthSession(session) {
-  if (!session?.accessToken) return;
-  writeFile(getOAuthSessionPath(), `${JSON.stringify(session, null, 2)}\n`);
-}
-
-function clearOAuthSession() {
-  const sessionPath = getOAuthSessionPath();
-  if (fs.existsSync(sessionPath)) fs.unlinkSync(sessionPath);
-}
-
-function readHeadlessToken() {
-  const tokenPath = getHeadlessTokenPath();
-  if (!fs.existsSync(tokenPath)) return null;
-  try {
-    const parsed = JSON.parse(fs.readFileSync(tokenPath, 'utf8'));
-    if (!parsed || typeof parsed !== 'object') {
-      return null;
-    }
-
-    const normalized = { ...parsed };
-    if (!normalized.clientId && normalized.authClientId) {
-      normalized.clientId = normalized.authClientId;
-    }
-    if (!normalized.clientSecret && normalized.authClientSecret) {
-      normalized.clientSecret = normalized.authClientSecret;
-    }
-    if (!normalized.apiKey) {
-      normalized.apiKey = normalized.clientSecret || normalized.authClientSecret || null;
-    }
-    return normalized;
-  } catch (_error) {
-    return null;
-  }
-}
-
-function getAccessTokenExpiryMs(token) {
-  if (!token || !token.accessToken) return 0;
-  const obtainedAtMs = Date.parse(String(token.obtainedAt || ''));
-  const expiresInSeconds = Number(token.expiresIn || 0);
-  if (!Number.isFinite(obtainedAtMs) || !Number.isFinite(expiresInSeconds) || expiresInSeconds <= 0) {
-    return 0;
-  }
-  return obtainedAtMs + (expiresInSeconds * 1000);
-}
-
-function hasFreshAccessToken(token, skewSeconds = 120) {
-  const expiryMs = getAccessTokenExpiryMs(token);
-  if (!expiryMs) return false;
-  return expiryMs > (Date.now() + (skewSeconds * 1000));
-}
-
-function persistAccessToken(accessToken) {
-  if (!accessToken) return;
-  process.env.EMPIRICAL_ACCESS_TOKEN = accessToken;
-  if (process.platform !== 'win32') {
-    return;
-  }
-  // `setx` writes permanently into the user's Windows environment, surviving
-  // every future shell/process. Only do that for a genuinely permanent
-  // credential (a plain apiKey) — a short-lived session JWT written here
-  // would silently outlive its own expiry and shadow a valid apiKey in the
-  // token file for good, forcing a manual env-var reset roughly every hour.
-  if (isJwtToken(accessToken)) {
-    return;
-  }
-  const escaped = String(accessToken).replace(/\"/g, '""');
-  runResolvedCommand('setx', ['EMPIRICAL_ACCESS_TOKEN', escaped], { stdio: 'ignore' });
-}
-
-function toEnvSafe(value) {
-  return String(value ?? '')
-    .replace(/\\/g, '\\\\')
-    .replace(/\n/g, '\\n')
-    .replace(/\r/g, '\\r')
-    .replace(/"/g, '\\"');
-}
-
-function writeHeadlessEnvFile(result, outputPath) {
-  ensureDir(path.dirname(path.resolve(outputPath)));
-  // Prefer the API key as the access token — it never expires and works as a
-  // permanent Bearer credential with the MCP endpoint.
-  const permanentToken = result.apiKey || result.accessToken;
-  const lines = [
-    '# Generated by empirical cli',
-    `EMPIRICAL_BASE_URL="${toEnvSafe(result.baseUrl)}"`,
-    `EMPIRICAL_ACCESS_TOKEN="${toEnvSafe(permanentToken)}"`,
-    `EMPIRICAL_API_KEY="${toEnvSafe(result.apiKey || '')}"`,
-    `EMPIRICAL_REFRESH_TOKEN="${toEnvSafe(result.refreshToken || '')}"`,
-    `EMPIRICAL_CLIENT_ID="${toEnvSafe(result.clientId || '')}"`,
-    `EMPIRICAL_CLIENT_SECRET="${toEnvSafe(result.clientSecret || '')}"`,
-    `EMPIRICAL_TOKEN_TYPE="${toEnvSafe(result.tokenType || 'Bearer')}"`,
-    `EMPIRICAL_TOKEN_OBTAINED_AT="${toEnvSafe(result.obtainedAt || '')}"`,
-    `EMPIRICAL_TOKEN_EXPIRES_IN="${toEnvSafe(result.expiresIn || '')}"`
-  ];
-  fs.writeFileSync(path.resolve(outputPath), `${lines.join('\n')}\n`, 'utf8');
-}
-
-module.exports = {
-  getLocalOAuthClientPath,
-  readStoredOAuthClient,
-  writeStoredOAuthClient,
-  clearStoredOAuthClient,
-  maskSecret,
-  generateRandomString,
-  base64url,
-  generatePKCE,
-  decodeJwtPayload,
-  isJwtToken,
-  isJwtExpired,
-  getHeadlessTokenPath,
-  getOAuthSessionPath,
-  readOAuthSession,
-  writeOAuthSession,
-  clearOAuthSession,
-  readHeadlessToken,
-  getAccessTokenExpiryMs,
-  hasFreshAccessToken,
-  persistAccessToken,
-  toEnvSafe,
-  writeHeadlessEnvFile
-};
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { readJsonIfExists, writeFile, ensureDir } = require('./fsUtils');
+const { getEnv } = require('./env');
+const { runResolvedCommand } = require('./fsUtils');
+
+function getLocalOAuthClientPath() {
+  return path.join(os.homedir(), '.empirical', 'oauth-client.json');
+}
+
+function readStoredOAuthClient() {
+  const stored = readJsonIfExists(getLocalOAuthClientPath());
+  if (!stored || typeof stored !== 'object') return null;
+  const clientId = String(stored.clientId || '').trim();
+  if (!clientId) return null;
+  return {
+    clientId,
+    clientSecret: String(stored.clientSecret || '')
+  };
+}
+
+function writeStoredOAuthClient(clientId, clientSecret) {
+  const payload = {
+    clientId: String(clientId || '').trim(),
+    clientSecret: String(clientSecret || '').trim(),
+    updatedAt: new Date().toISOString()
+  };
+  writeFile(getLocalOAuthClientPath(), `${JSON.stringify(payload, null, 2)}\n`);
+}
+
+function clearStoredOAuthClient() {
+  const storePath = getLocalOAuthClientPath();
+  if (fs.existsSync(storePath)) {
+    fs.unlinkSync(storePath);
+  }
+}
+
+function maskSecret(value) {
+  const raw = String(value || '');
+  if (!raw) return '(not set)';
+  if (raw.length <= 8) return '*'.repeat(raw.length);
+  return `${raw.slice(0, 4)}...${raw.slice(-4)}`;
+}
+
+function generateRandomString(length = 32) {
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~';
+  let result = '';
+  for (let i = 0; i < length; i += 1) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return result;
+}
+
+function base64url(buf) {
+  return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+}
+
+function generatePKCE() {
+  const crypto = require('crypto');
+  const codeVerifier = generateRandomString(128);
+  const codeChallenge = base64url(crypto.createHash('sha256').update(codeVerifier).digest());
+  return { codeVerifier, codeChallenge };
+}
+
+function decodeJwtPayload(token) {
+  try {
+    const parts = String(token).split('.');
+    if (parts.length !== 3) return null;
+    return JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+  } catch (_error) {
+    return null;
+  }
+}
+
+function isJwtToken(token) {
+  return typeof token === 'string' && token.split('.').length === 3;
+}
+
+function isJwtExpired(token, skewSeconds = 30) {
+  const payload = decodeJwtPayload(token);
+  if (!payload || typeof payload.exp !== 'number') return true;
+  return payload.exp < Math.floor(Date.now() / 1000) + skewSeconds;
+}
+
+function getHeadlessTokenPath() {
+  return path.resolve(getEnv('EMPIRICAL_TOKEN_OUTPUT', '.empirical/headless-token.json'));
+}
+
+function getOAuthSessionPath() {
+  return path.join(os.homedir(), '.empirical', 'oauth-session.json');
+}
+
+function readOAuthSession() {
+  const session = readJsonIfExists(getOAuthSessionPath());
+  if (!session || typeof session !== 'object') return null;
+  return session;
+}
+
+function writeOAuthSession(session) {
+  if (!session?.accessToken) return;
+  writeFile(getOAuthSessionPath(), `${JSON.stringify(session, null, 2)}\n`);
+}
+
+function clearOAuthSession() {
+  const sessionPath = getOAuthSessionPath();
+  if (fs.existsSync(sessionPath)) fs.unlinkSync(sessionPath);
+}
+
+function readHeadlessToken() {
+  const tokenPath = getHeadlessTokenPath();
+  if (!fs.existsSync(tokenPath)) return null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(tokenPath, 'utf8'));
+    if (!parsed || typeof parsed !== 'object') {
+      return null;
+    }
+
+    const normalized = { ...parsed };
+    if (!normalized.clientId && normalized.authClientId) {
+      normalized.clientId = normalized.authClientId;
+    }
+    if (!normalized.clientSecret && normalized.authClientSecret) {
+      normalized.clientSecret = normalized.authClientSecret;
+    }
+    if (!normalized.apiKey) {
+      normalized.apiKey = normalized.clientSecret || normalized.authClientSecret || null;
+    }
+    return normalized;
+  } catch (_error) {
+    return null;
+  }
+}
+
+function getAccessTokenExpiryMs(token) {
+  if (!token || !token.accessToken) return 0;
+  const obtainedAtMs = Date.parse(String(token.obtainedAt || ''));
+  const expiresInSeconds = Number(token.expiresIn || 0);
+  if (!Number.isFinite(obtainedAtMs) || !Number.isFinite(expiresInSeconds) || expiresInSeconds <= 0) {
+    return 0;
+  }
+  return obtainedAtMs + (expiresInSeconds * 1000);
+}
+
+function hasFreshAccessToken(token, skewSeconds = 120) {
+  const expiryMs = getAccessTokenExpiryMs(token);
+  if (!expiryMs) return false;
+  return expiryMs > (Date.now() + (skewSeconds * 1000));
+}
+
+function persistAccessToken(accessToken) {
+  if (!accessToken) return;
+  process.env.EMPIRICAL_ACCESS_TOKEN = accessToken;
+  if (process.platform !== 'win32') {
+    return;
+  }
+  // `setx` writes permanently into the user's Windows environment, surviving
+  // every future shell/process. Only do that for a genuinely permanent
+  // credential (a plain apiKey) — a short-lived session JWT written here
+  // would silently outlive its own expiry and shadow a valid apiKey in the
+  // token file for good, forcing a manual env-var reset roughly every hour.
+  if (isJwtToken(accessToken)) {
+    return;
+  }
+  const escaped = String(accessToken).replace(/\"/g, '""');
+  runResolvedCommand('setx', ['EMPIRICAL_ACCESS_TOKEN', escaped], { stdio: 'ignore' });
+}
+
+function toEnvSafe(value) {
+  return String(value ?? '')
+    .replace(/\\/g, '\\\\')
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r')
+    .replace(/"/g, '\\"');
+}
+
+function writeHeadlessEnvFile(result, outputPath) {
+  ensureDir(path.dirname(path.resolve(outputPath)));
+  // Prefer the API key as the access token — it never expires and works as a
+  // permanent Bearer credential with the MCP endpoint.
+  const permanentToken = result.apiKey || result.accessToken;
+  const lines = [
+    '# Generated by empirical cli',
+    `EMPIRICAL_BASE_URL="${toEnvSafe(result.baseUrl)}"`,
+    `EMPIRICAL_ACCESS_TOKEN="${toEnvSafe(permanentToken)}"`,
+    `EMPIRICAL_API_KEY="${toEnvSafe(result.apiKey || '')}"`,
+    `EMPIRICAL_REFRESH_TOKEN="${toEnvSafe(result.refreshToken || '')}"`,
+    `EMPIRICAL_CLIENT_ID="${toEnvSafe(result.clientId || '')}"`,
+    `EMPIRICAL_CLIENT_SECRET="${toEnvSafe(result.clientSecret || '')}"`,
+    `EMPIRICAL_TOKEN_TYPE="${toEnvSafe(result.tokenType || 'Bearer')}"`,
+    `EMPIRICAL_TOKEN_OBTAINED_AT="${toEnvSafe(result.obtainedAt || '')}"`,
+    `EMPIRICAL_TOKEN_EXPIRES_IN="${toEnvSafe(result.expiresIn || '')}"`
+  ];
+  fs.writeFileSync(path.resolve(outputPath), `${lines.join('\n')}\n`, 'utf8');
+}
+
+module.exports = {
+  getLocalOAuthClientPath,
+  readStoredOAuthClient,
+  writeStoredOAuthClient,
+  clearStoredOAuthClient,
+  maskSecret,
+  generateRandomString,
+  base64url,
+  generatePKCE,
+  decodeJwtPayload,
+  isJwtToken,
+  isJwtExpired,
+  getHeadlessTokenPath,
+  getOAuthSessionPath,
+  readOAuthSession,
+  writeOAuthSession,
+  clearOAuthSession,
+  readHeadlessToken,
+  getAccessTokenExpiryMs,
+  hasFreshAccessToken,
+  persistAccessToken,
+  toEnvSafe,
+  writeHeadlessEnvFile
+};