@empirical-gauzza/cli 1.0.9

package/lib/ui.js

@@ -0,0 +1,280 @@
+'use strict';
+
+const readline = require('readline');
+
+function log(msg) {
+  process.stdout.write(`${msg}\n`);
+}
+
+function warn(msg) {
+  process.stderr.write(`${msg}\n`);
+}
+
+const ANSI = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  underline: '\x1b[4m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m'
+};
+
+function supportsColor() {
+  return process.stdout.isTTY && !process.env.NO_COLOR;
+}
+
+function colorize(code, text) {
+  if (!supportsColor()) return String(text);
+  return `${code}${text}${ANSI.reset}`;
+}
+
+function uiHeader(text) {
+  return colorize(`${ANSI.bold}${ANSI.blue}`, text);
+}
+
+function uiQuestion(text) {
+  return `${colorize(ANSI.cyan, '?')} ${text}`;
+}
+
+function uiSuccess(text) {
+  return `${colorize(ANSI.green, '✓')} ${text}`;
+}
+
+function uiWarn(text) {
+  return `${colorize(ANSI.yellow, '!')} ${text}`;
+}
+
+function uiDim(text) {
+  return colorize(ANSI.dim, text);
+}
+
+function uiLink(text) {
+  return colorize(`${ANSI.bold}${ANSI.underline}${ANSI.cyan}`, text);
+}
+
+function formatHeadlessErrorHint(message = '') {
+  const raw = String(message || '').toLowerCase();
+  if (raw.includes('user not found') || raw.includes('inactive') || raw.includes('access_denied')) {
+    return 'Verify Settings client credentials (client ID + client secret) and account status.';
+  }
+  if (raw.includes('invalid_client')) {
+    return 'Client credentials are invalid. Use Settings -> API Tool Credentials and retry.';
+  }
+  if (raw.includes('invalid_grant') || raw.includes('invalid token')) {
+    return 'Auth grant/token was rejected. Re-enter credentials and retry.';
+  }
+  return '';
+}
+
+function parseSelection(input, max) {
+  const raw = (input || '').trim();
+  if (!raw) {
+    return Array.from({ length: max }, (_v, i) => i);
+  }
+
+  const indexes = raw
+    .split(',')
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .map((part) => Number(part) - 1)
+    .filter((idx) => Number.isInteger(idx) && idx >= 0 && idx < max);
+
+  return Array.from(new Set(indexes));
+}
+
+// `output` defaults to stdout (the original behavior, unchanged for every existing caller).
+// skillSync.js's review-gate prompts pass `process.stderr` instead — `kit sync`/`kit use`'s
+// stdout contract is a single machine-parsed JSON summary line, so prompt text (and any human-
+// readable pre-answer output) must never land there.
+async function ask(question, output = process.stdout) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output
+  });
+
+  const answer = await new Promise((resolve) => {
+    rl.question(question, resolve);
+  });
+
+  rl.close();
+  return answer;
+}
+
+async function askYesNo(question, defaultYes = true, output = process.stdout) {
+  const suffix = defaultYes ? 'Y/n' : 'y/N';
+  const answer = (await ask(uiQuestion(`${question} ${uiDim(`(${suffix})`)} `), output)).trim().toLowerCase();
+  if (!answer) return defaultYes;
+  if (['y', 'yes'].includes(answer)) return true;
+  if (['n', 'no'].includes(answer)) return false;
+  return defaultYes;
+}
+
+// A prompter for asking MULTIPLE sequential y/n questions in one process run (e.g.
+// skillSync.js's US-016 review gate, which may need to ask about several skills in one
+// `kit sync` invocation). Deliberately does NOT use readline: readline.createInterface()
+// auto-closes itself as soon as its underlying input stream fires 'end' — and against a piped,
+// non-TTY stdin (as in CLI-subprocess tests, or any script feeding all answers up front and
+// then closing stdin) that 'end' can arrive well before every question has been asked, even
+// with a single shared interface. Once closed, any further rl.question() call throws
+// ERR_USE_AFTER_CLOSE instead of resolving. Reading stdin manually and buffering it ourselves
+// sidesteps this: all piped lines are captured as they arrive (or immediately, if already
+// buffered before we start reading), regardless of how many questions we've asked so far.
+function createPrompter(output = process.stdout) {
+  let buffer = '';
+  let ended = false;
+  const waiters = [];
+
+  function flush() {
+    while (waiters.length > 0) {
+      const newlineIndex = buffer.indexOf('\n');
+      if (newlineIndex === -1) {
+        if (!ended) break;
+        const resolve = waiters.shift();
+        const rest = buffer;
+        buffer = '';
+        resolve(rest);
+        continue;
+      }
+      const line = buffer.slice(0, newlineIndex).replace(/\r$/, '');
+      buffer = buffer.slice(newlineIndex + 1);
+      waiters.shift()(line);
+    }
+  }
+
+  function onData(chunk) {
+    buffer += chunk;
+    flush();
+  }
+  function onEnd() {
+    ended = true;
+    flush();
+  }
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', onData);
+  process.stdin.on('end', onEnd);
+
+  function readLine() {
+    return new Promise((resolve) => {
+      waiters.push(resolve);
+      flush();
+    });
+  }
+
+  async function promptYesNo(question, defaultYes = true) {
+    const suffix = defaultYes ? 'Y/n' : 'y/N';
+    output.write(uiQuestion(`${question} ${uiDim(`(${suffix})`)} `) + '\n');
+    const answer = (await readLine()).trim().toLowerCase();
+    if (!answer) return defaultYes;
+    if (['y', 'yes'].includes(answer)) return true;
+    if (['n', 'no'].includes(answer)) return false;
+    return defaultYes;
+  }
+
+  function close() {
+    process.stdin.removeListener('data', onData);
+    process.stdin.removeListener('end', onEnd);
+    // Removing the 'data' listener alone isn't enough to let the process exit: once a stream
+    // has been put into flowing mode it keeps its underlying handle referenced/active until
+    // explicitly paused, which would otherwise hang every interactive `kit sync` run forever
+    // (even ones where zero skills actually triggered a prompt).
+    process.stdin.pause();
+  }
+
+  return { askYesNo: promptYesNo, close };
+}
+
+function parseSelectionList(answer, max) {
+  const selected = new Set();
+  const parts = String(answer || '')
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+
+  for (const part of parts) {
+    const rangeMatch = part.match(/^(\d+)\s*-\s*(\d+)$/);
+    if (rangeMatch) {
+      const start = Number(rangeMatch[1]);
+      const end = Number(rangeMatch[2]);
+      if (
+        Number.isInteger(start) &&
+        Number.isInteger(end) &&
+        start >= 1 &&
+        end >= start &&
+        end <= max
+      ) {
+        for (let i = start; i <= end; i += 1) selected.add(i);
+      }
+      continue;
+    }
+    const value = Number(part);
+    if (Number.isInteger(value) && value >= 1 && value <= max) {
+      selected.add(value);
+    }
+  }
+
+  return selected;
+}
+
+async function askWorkflowMultiSelect(question, options, defaults) {
+  const optionCount = options.length;
+  const selected = new Set(defaults);
+
+  while (true) {
+    log(uiQuestion(question));
+    for (let index = 0; index < options.length; index += 1) {
+      const item = options[index];
+      const checked = selected.has(item.id) ? '[x]' : '[ ]';
+      log(`  ${index + 1}. ${checked} ${item.label}`);
+    }
+    const answer = (await ask(
+      uiDim('Press Enter to continue, or type numbers/ranges to toggle (example: 2,4-5): ')
+    )).trim();
+
+    if (!answer) {
+      if (!selected.size) {
+        warn(uiWarn('At least one workflow must remain selected.'));
+        log('');
+        continue;
+      }
+      return options.filter((item) => selected.has(item.id)).map((item) => item.id);
+    }
+
+    const indices = parseSelectionList(answer, optionCount);
+    if (!indices.size) {
+      warn(uiWarn('No valid selections were provided. Use numbers like 1,3 or ranges like 2-4.'));
+      log('');
+      continue;
+    }
+    for (const idx of indices) {
+      const id = options[idx - 1].id;
+      if (selected.has(id)) selected.delete(id);
+      else selected.add(id);
+    }
+    log('');
+  }
+}
+
+module.exports = {
+  log,
+  warn,
+  ANSI,
+  supportsColor,
+  colorize,
+  uiHeader,
+  uiQuestion,
+  uiSuccess,
+  uiWarn,
+  uiDim,
+  uiLink,
+  formatHeadlessErrorHint,
+  parseSelection,
+  ask,
+  askYesNo,
+  createPrompter,
+  parseSelectionList,
+  askWorkflowMultiSelect
+};

package/lib/workspaceCommands.js

@@ -0,0 +1,323 @@
+'use strict';
+
+const { log, ask, uiSuccess } = require('./ui');
+const { httpJson } = require('./http');
+const { getEnv, parseFlag, parseOption } = require('./env');
+const { ensureHeadlessToken, resolveAccessToken, buildApiAuthHeaders } = require('./auth');
+const { readStoredOAuthClient } = require('./oauthClient');
+const { deriveBaseUrlFromMcpUrl } = require('./constants');
+const { withCliAnalyticsContext } = require('./memoryCommands');
+const { readSelectedWorkspace, writeSelectedWorkspace, clearSelectedWorkspace } = require('./workspaceContext');
+
+function isWorkspaceCommand(args) {
+  if (args[0] !== 'workspace') return false;
+  if (['list', 'current', 'select', 'use', 'create', 'delete'].includes(args[1])) return true;
+  return args[1] === 'invite' && ['create', 'list', 'revoke'].includes(args[2]);
+}
+
+function workspaceOptions(payload) {
+  return [
+    ...(payload?.defaultOption ? [{ ...payload.defaultOption, isDefault: true }] : []),
+    ...((payload?.workspaces || []).map((workspace) => ({ ...workspace, isDefault: false })))
+  ];
+}
+
+function positionalArgs(args, startIndex) {
+  const valueOptions = new Set(['--description', '--role', '--expires-in-days', '--max-uses']);
+  const positional = [];
+  for (let index = startIndex; index < args.length; index += 1) {
+    if (valueOptions.has(args[index])) {
+      index += 1;
+    } else if (!args[index].startsWith('--')) {
+      positional.push(args[index]);
+    }
+  }
+  return positional;
+}
+
+function getTeamBrains(payload) {
+  return Array.isArray(payload?.teamBrains) ? payload.teamBrains : [];
+}
+
+function targetFromOption(option, teamBrain) {
+  return {
+    ...(option || {}),
+    key: option?.key || teamBrain?.workspaceId,
+    selectionKey: option?.key || teamBrain?.workspaceId || option?.workspaceId,
+    label: option?.label || teamBrain?.name,
+    isDefault: Boolean(option?.isDefault),
+    workspaceId: teamBrain?.workspaceId || option?.workspaceId || null,
+  };
+}
+
+function ambiguousWorkspaceTarget() {
+  return { ambiguous: true };
+}
+
+function resolveWorkspaceTarget(requested, selectablePayload, teamBrainsPayload) {
+  const value = String(requested || '').trim();
+  const options = workspaceOptions(selectablePayload);
+  const teamBrains = getTeamBrains(teamBrainsPayload);
+  if (!value) return null;
+
+  const byNumber = Number(value);
+  if (Number.isInteger(byNumber) && byNumber >= 1 && byNumber <= options.length) {
+    const option = options[byNumber - 1];
+    if (option.isDefault) return targetFromOption(option, null);
+    const teamMatches = teamBrains.filter((brain) => brain.workspaceId === option.workspaceId
+      || (!option.workspaceId && String(brain.name || '').toLowerCase() === String(option.label || '').toLowerCase()));
+    if (teamMatches.length > 1) return ambiguousWorkspaceTarget();
+    return targetFromOption(option, teamMatches[0]);
+  }
+
+  const lowerValue = value.toLowerCase();
+  const byId = teamBrains.filter((brain) => String(brain.workspaceId || '').toLowerCase() === lowerValue);
+  if (byId.length > 1) return ambiguousWorkspaceTarget();
+  if (byId.length === 1) {
+    const option = options.find((item) => item.workspaceId === byId[0].workspaceId
+      || String(item.label || '').toLowerCase() === String(byId[0].name || '').toLowerCase());
+    return targetFromOption(option, byId[0]);
+  }
+
+  const byKey = options.filter((item) => String(item.key || '').toLowerCase() === lowerValue);
+  if (byKey.length > 1) return ambiguousWorkspaceTarget();
+  if (byKey.length === 1) {
+    const teamMatches = teamBrains.filter((brain) => brain.workspaceId === byKey[0].workspaceId
+      || (!byKey[0].workspaceId && String(brain.name || '').toLowerCase() === String(byKey[0].label || '').toLowerCase()));
+    if (teamMatches.length > 1) return ambiguousWorkspaceTarget();
+    return targetFromOption(byKey[0], teamMatches[0]);
+  }
+
+  const byName = teamBrains.filter((brain) => String(brain.name || '').toLowerCase() === lowerValue);
+  if (byName.length > 1) return ambiguousWorkspaceTarget();
+  if (byName.length === 1) {
+    const option = options.find((item) => item.workspaceId === byName[0].workspaceId
+      || String(item.label || '').toLowerCase() === lowerValue);
+    return targetFromOption(option, byName[0]);
+  }
+
+  const byLabel = options.filter((item) => String(item.label || '').toLowerCase() === lowerValue);
+  if (byLabel.length > 1) return ambiguousWorkspaceTarget();
+  return byLabel.length === 1 ? targetFromOption(byLabel[0], null) : null;
+}
+
+function positiveIntegerOption(args, optionName) {
+  const raw = parseOption(args, optionName, '');
+  if (!raw) return undefined;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`${optionName} must be a positive integer.`);
+  }
+  return value;
+}
+
+async function getWorkspaceCommandAuth() {
+  const configuredAccessToken = resolveAccessToken();
+  const tokenPayload = configuredAccessToken ? null : await ensureHeadlessToken({ promptCredentials: true });
+  const accessToken = configuredAccessToken || tokenPayload?.apiKey || tokenPayload?.accessToken;
+  if (!accessToken) {
+    throw new Error('No access token available. Run `empirical oauth bootstrap headless --prompt-credentials` first.');
+  }
+  const clientId = tokenPayload?.clientId || getEnv('EMPIRICAL_CLIENT_ID') || readStoredOAuthClient()?.clientId;
+  if (!clientId) {
+    throw new Error('No OAuth client ID found. Run `empirical oauth client set --client-id <id>` first.');
+  }
+  const baseUrl = getEnv('EMPIRICAL_BASE_URL', deriveBaseUrlFromMcpUrl() || 'https://empirical.gauzza.com');
+  return { baseUrl, clientId, accessToken };
+}
+
+async function runWorkspaceCommand(args) {
+  return withCliAnalyticsContext(
+    { command: `workspace.${args[1] || 'unknown'}`, subcommand: args[1] || 'unknown' },
+    async () => {
+      const action = args[1];
+      const { baseUrl, clientId, accessToken } = await getWorkspaceCommandAuth();
+      const encodedClientId = encodeURIComponent(clientId);
+      const listUrl = new URL(`/oauth/clients/${encodedClientId}/workspaces`, baseUrl).toString();
+      const currentUrl = new URL(`/oauth/clients/${encodedClientId}/workspace-selection`, baseUrl).toString();
+      const teamBrainsUrl = new URL('/api/v1/team-brains', baseUrl).toString();
+      const authHeaders = buildApiAuthHeaders(accessToken);
+
+      if (action === 'list') {
+        const payload = await httpJson(listUrl, 'GET', null, authHeaders);
+        log('Selectable workspaces:');
+        log(`  1. ${payload.defaultOption.label}${payload.defaultOption.selected ? ' (current)' : ''}`);
+        (payload.workspaces || []).forEach((ws, index) => {
+          log(`  ${index + 2}. ${ws.label}${ws.selected ? ' (current)' : ''}`);
+        });
+        if (payload.locked) {
+          log('  (workspace selection is admin-locked for this client)');
+        }
+        return;
+      }
+
+      if (action === 'current') {
+        const locallySelected = readSelectedWorkspace();
+        if (locallySelected) {
+          log(`Current workspace: ${locallySelected.label || locallySelected.workspaceId}`);
+          return;
+        }
+        const payload = await httpJson(currentUrl, 'GET', null, authHeaders);
+        log(`Current workspace: ${payload?.current?.label || 'Default Brain'}`);
+        if (payload?.locked) {
+          log('This OAuth client is admin-locked to a workspace.');
+        }
+        return;
+      }
+
+      if (action === 'select' || action === 'use') {
+        const [payload, teamPayload] = await Promise.all([
+          httpJson(listUrl, 'GET', null, authHeaders),
+          httpJson(teamBrainsUrl, 'GET', null, authHeaders),
+        ]);
+        if (payload.locked) {
+          throw new Error('Workspace is admin-locked for this OAuth client and cannot be changed.');
+        }
+
+        const options = workspaceOptions(payload);
+
+        let requested = args.slice(2).join(' ').trim();
+        if (!requested && process.stdin.isTTY) {
+          log('Select workspace:');
+          options.forEach((item, idx) => log(`  ${idx + 1}. ${item.label}`));
+          const answer = (await ask('Enter number: ')).trim();
+          requested = answer;
+        }
+
+        if (!requested) {
+          throw new Error('Please provide a workspace selection, e.g. `empirical workspace use 1` or `empirical workspace use "Default Brain"`.');
+        }
+
+        const target = resolveWorkspaceTarget(requested, payload, teamPayload);
+        if (target?.ambiguous) throw new Error(`Ambiguous workspace: ${requested}. Use its list number or workspace ID.`);
+        if (!target?.selectionKey) throw new Error(`Workspace not found: ${requested}`);
+
+        const updateUrl = new URL(`/oauth/clients/${encodedClientId}/workspace-selection`, baseUrl).toString();
+        const updated = await httpJson(updateUrl, 'POST', { key: target.selectionKey }, authHeaders);
+        if (target.isDefault) {
+          clearSelectedWorkspace();
+        } else if (target.workspaceId) {
+          writeSelectedWorkspace({ workspaceId: target.workspaceId, key: target.key, label: target.label });
+        }
+        log(uiSuccess(`Workspace selected: ${updated?.current?.label || target.label || target.selectionKey}`));
+        return;
+      }
+
+      if (action === 'create') {
+        const name = positionalArgs(args, 2).join(' ').trim();
+        if (!name) throw new Error('Usage: empirical workspace create <name> [--description <text>]');
+        const description = parseOption(args, '--description', '');
+        const created = await httpJson(
+          teamBrainsUrl,
+          'POST',
+          { name, ...(description ? { description } : {}) },
+          authHeaders
+        );
+        const workspace = created?.teamBrain || created?.workspace || created;
+        log(uiSuccess(`Workspace created: ${workspace?.name || name} (${workspace?.workspaceId || workspace?.id || 'unknown'})`));
+        return;
+      }
+
+      if (action === 'delete') {
+        const requested = positionalArgs(args, 2).join(' ').trim();
+        if (!requested) throw new Error('Usage: empirical workspace delete <number|name|id> [--confirm]');
+        const [selectablePayload, teamPayload] = await Promise.all([
+          httpJson(listUrl, 'GET', null, authHeaders),
+          httpJson(teamBrainsUrl, 'GET', null, authHeaders),
+        ]);
+        const target = resolveWorkspaceTarget(requested, selectablePayload, teamPayload);
+        if (target?.ambiguous) throw new Error(`Ambiguous workspace: ${requested}. Use its list number or workspace ID.`);
+        if (!target) throw new Error(`Workspace not found: ${requested}`);
+        if (target.isDefault || target.key === 'default_brain') {
+          throw new Error('The Default Brain cannot be deleted.');
+        }
+        if (!target.workspaceId) throw new Error(`Workspace is not a deletable team brain: ${target.label}`);
+
+        const targetDescription = `${target.label} (${target.workspaceId})`;
+        if (!parseFlag(args, '--confirm')) {
+          log(`Dry run: would soft-delete workspace ${targetDescription}. This is recoverable by data retention but cannot be undone in the UI. Re-run with --confirm to proceed.`);
+          return;
+        }
+
+        log(`Soft-deleting workspace ${targetDescription}...`);
+        await httpJson(new URL(`/api/v1/team-brains/${encodeURIComponent(target.workspaceId)}`, baseUrl).toString(), 'DELETE', null, authHeaders);
+        if (target.selected) {
+          const updateUrl = new URL(`/oauth/clients/${encodedClientId}/workspace-selection`, baseUrl).toString();
+          const updated = await httpJson(updateUrl, 'POST', { key: 'default_brain' }, authHeaders);
+          log(uiSuccess(`Soft-deleted workspace ${targetDescription}. Active workspace reset to ${updated?.current?.label || 'Default Brain'}.`));
+          clearSelectedWorkspace();
+        } else {
+          log(uiSuccess(`Soft-deleted workspace ${targetDescription}.`));
+        }
+        return;
+      }
+
+      if (action === 'invite') {
+        const inviteAction = args[2];
+        const currentPayload = await httpJson(currentUrl, 'GET', null, authHeaders);
+        const current = currentPayload?.current;
+        if (!current?.key || current.key === 'default_brain') {
+          throw new Error('Workspace invites require an active team workspace. Use `empirical workspace use <workspace>` first.');
+        }
+        const teamPayload = await httpJson(teamBrainsUrl, 'GET', null, authHeaders);
+        const target = resolveWorkspaceTarget(
+          current.workspaceId || current.key,
+          { workspaces: [{ key: current.key, label: current.label, workspaceId: current.workspaceId }] },
+          teamPayload
+        );
+        if (!target?.workspaceId) {
+          throw new Error('The active workspace is not a team workspace available for invites.');
+        }
+        const inviteUrl = new URL(`/api/v1/team-brains/${encodeURIComponent(target.workspaceId)}/invites`, baseUrl).toString();
+
+        if (inviteAction === 'create') {
+          const role = parseOption(args, '--role', 'reader');
+          if (!['reader', 'writer', 'manager'].includes(role)) {
+            throw new Error('--role must be reader, writer, or manager.');
+          }
+          const expiresInDays = positiveIntegerOption(args, '--expires-in-days');
+          const maxUses = positiveIntegerOption(args, '--max-uses');
+          const payload = await httpJson(inviteUrl, 'POST', {
+            accessRole: role,
+            ...(expiresInDays !== undefined ? { expiresInDays } : {}),
+            ...(maxUses !== undefined ? { maxUses } : {}),
+          }, authHeaders);
+          const token = payload?.invite?.token || payload?.token;
+          if (!token) throw new Error('Invite creation did not return a token.');
+          log(uiSuccess(`Invite created: ${baseUrl.replace(/\/$/, '')}/invite/${token}`));
+          return;
+        }
+
+        if (inviteAction === 'list') {
+          const payload = await httpJson(inviteUrl, 'GET', null, authHeaders);
+          const invites = Array.isArray(payload?.invites) ? payload.invites : [];
+          if (!invites.length) {
+            log(`No active invites for ${target.label}.`);
+            return;
+          }
+          log(`Active invites for ${target.label}:`);
+          invites.forEach((invite) => {
+            log(`  ${invite.token} (${invite.accessRole || 'reader'}) ${baseUrl.replace(/\/$/, '')}/invite/${invite.token}`);
+          });
+          return;
+        }
+
+        const token = positionalArgs(args, 3).join(' ').trim();
+        if (!token) throw new Error('Usage: empirical workspace invite revoke <token>');
+        if (!parseFlag(args, '--confirm')) {
+          log(`Dry run: would revoke invite ${token} from ${target.label}. Re-run with --confirm to proceed.`);
+          return;
+        }
+        await httpJson(`${inviteUrl}/${encodeURIComponent(token)}`, 'DELETE', null, authHeaders);
+        log(uiSuccess(`Invite revoked: ${token}`));
+      }
+    }
+  );
+}
+
+module.exports = {
+  isWorkspaceCommand,
+  getWorkspaceCommandAuth,
+  resolveWorkspaceTarget,
+  runWorkspaceCommand
+};

package/lib/workspaceContext.js

@@ -0,0 +1,76 @@
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const { httpJson } = require('./http');
+const { getEnv } = require('./env');
+const { resolveAccessToken, resolveApiBaseUrl, buildApiAuthHeaders } = require('./auth');
+const { readStoredOAuthClient } = require('./oauthClient');
+const { readJsonIfExists, writeFile, ensureDir } = require('./fsUtils');
+
+const WORKSPACE_CONTEXT_TIMEOUT_MS = 2000;
+const SELECTED_WORKSPACE_PATH = path.join(os.homedir(), '.empirical', 'workspace-selection.json');
+
+function readSelectedWorkspace() {
+  const value = readJsonIfExists(SELECTED_WORKSPACE_PATH);
+  return value && typeof value.workspaceId === 'string' ? value : null;
+}
+
+function writeSelectedWorkspace(workspace) {
+  ensureDir(path.dirname(SELECTED_WORKSPACE_PATH));
+  writeFile(SELECTED_WORKSPACE_PATH, `${JSON.stringify(workspace, null, 2)}\n`);
+}
+
+function clearSelectedWorkspace() {
+  const fs = require('fs');
+  if (fs.existsSync(SELECTED_WORKSPACE_PATH)) fs.unlinkSync(SELECTED_WORKSPACE_PATH);
+}
+
+async function withSelectedWorkspaceContext(fn) {
+  const stored = readSelectedWorkspace();
+  if (stored?.workspaceId) {
+    const previousWorkspaceId = globalThis.__empiricalCliWorkspaceId || null;
+    globalThis.__empiricalCliWorkspaceId = stored.workspaceId;
+    try {
+      return await fn();
+    } finally {
+      globalThis.__empiricalCliWorkspaceId = previousWorkspaceId;
+    }
+  }
+
+  const accessToken = resolveAccessToken();
+  const clientId = getEnv('EMPIRICAL_CLIENT_ID') || readStoredOAuthClient()?.clientId;
+  if (!accessToken || !clientId) return fn();
+
+  const previousWorkspaceId = globalThis.__empiricalCliWorkspaceId || null;
+  globalThis.__empiricalCliWorkspaceId = null;
+  try {
+    const baseUrl = resolveApiBaseUrl();
+    const currentUrl = new URL(
+      `/oauth/clients/${encodeURIComponent(clientId)}/workspace-selection`,
+      baseUrl
+    ).toString();
+    try {
+      const payload = await httpJson(
+        currentUrl,
+        'GET',
+        null,
+        buildApiAuthHeaders(accessToken),
+        WORKSPACE_CONTEXT_TIMEOUT_MS
+      );
+      globalThis.__empiricalCliWorkspaceId = payload?.current?.workspaceId || null;
+    } catch (_error) {
+      globalThis.__empiricalCliWorkspaceId = null;
+    }
+    return await fn();
+  } finally {
+    globalThis.__empiricalCliWorkspaceId = previousWorkspaceId;
+  }
+}
+
+module.exports = {
+  withSelectedWorkspaceContext,
+  readSelectedWorkspace,
+  writeSelectedWorkspace,
+  clearSelectedWorkspace
+};