@empirical-gauzza/cli 1.0.9

package/lib/constants.js

@@ -0,0 +1,491 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const EMPIRICAL_MCP_NAME = 'empirical';
+const EMPIRICAL_MCP_LEGACY_NAMES = ['empirical-live'];
+const EMPIRICAL_MCP_URL = process.env.EMPIRICAL_MCP_URL || 'https://empirical.gauzza.com/mcp';
+const COPILOT_OAUTH_CLIENT_ID = process.env.EMPIRICAL_COPILOT_OAUTH_CLIENT_ID || 'copilot-cli-empirical';
+
+const MEMORY_CATEGORIES = [
+  'health', 'fitness', 'food', 'supplement', 'mood', 'idea', 'business',
+  'build', 'growth', 'learning', 'leadership', 'operations', 'workflow',
+  'lead', 'project', 'recipe', 'preference', 'reflection', 'relationship', 'heartbeat'
+];
+
+const DOC_TOPICS = {
+  memory: `# Empirical Memory Commands
+
+Use the \`empirical memory\` subcommands to query and manage memories via the REST API.
+All commands require a valid access token (see \`empirical doc auth\`).
+Errors are written to stderr as JSON. Successful output is written to stdout as JSON.
+
+## Subcommands
+
+### query
+Search memories by natural language.
+
+    empirical memory query --match "coding style preferences" [--top-k 3] [--category build] [--tags ts,node] [--pretty]
+
+Flags:
+- \`--match\` (required): natural language search string
+- \`--top-k\`: number of results, 1–100, default 3
+- \`--category\`: filter by category
+- \`--tags\`: comma-separated tags filter
+- \`--pretty\`: pretty-print JSON output
+
+### get
+Retrieve one memory by exact ID.
+
+    empirical memory get --memory-id <id> [--pretty]
+
+### list
+Browse memories deterministically. Use \`--cursor\` from the previous response while \`pagination.hasMore\` is true.
+
+    empirical memory list [--category project] [--tags canonical,launch] [--start-date <ISO>] [--end-date <ISO>] [--limit 20] [--cursor <cursor>] [--oldest] [--pretty]
+
+Flags:
+- \`--category\`, \`--tags\`: optional filters
+- \`--start-date\`, \`--end-date\`: createdAt bounds
+- \`--limit\`: page size, 1–100, default 20
+- \`--cursor\`: continuation cursor from a previous page
+- \`--oldest\`: sort oldest first; default is newest first
+- \`--pretty\`: pretty-print JSON output
+
+### record
+Save a new memory.
+
+    empirical memory record --category build --summary "Use ESM modules for all new packages" [--tags ts,node] [--node-type observation]
+
+Flags:
+- \`--category\` (required unless --json-file): memory category
+- \`--summary\` (required unless --json-file): memory summary text
+- \`--tags\`: comma-separated tags
+- \`--node-type\`: node type, default \`observation\`
+- \`--json-file\`: path to JSON file with full memory payload
+
+### note
+Add a note to an existing memory.
+
+    empirical memory note --match "ESM modules" --text "confirmed in monorepo migration" [--min-score 0.35]
+
+Flags:
+- \`--match\` (required unless --memory-id): search string to find the memory
+- \`--text\` (required): note text to append
+- \`--memory-id\`: use exact memory ID (skips fuzzy search)
+- \`--min-score\`: minimum similarity score, default 0.35
+
+### update
+Update an existing memory.
+
+    empirical memory update --match "ESM modules" --patch-json '{"summary":"Updated summary"}' [--min-score 0.35]
+
+Flags:
+- \`--match\` (required unless --memory-id): search string
+- \`--patch-json\`: JSON string with fields to update
+- \`--json-file\`: path to JSON patch file
+- \`--memory-id\`: use exact memory ID
+- \`--min-score\`: minimum similarity score, default 0.35
+
+### delete
+Delete a memory. Without --confirm, runs a dry-run and prints what would be deleted.
+
+    empirical memory delete --match "old preference" --confirm [--min-score 0.35]
+
+Flags:
+- \`--match\` (required unless --memory-id): search string
+- \`--confirm\`: actually delete (without this, dry-run only)
+- \`--memory-id\`: use exact memory ID
+- \`--min-score\`: minimum similarity score, default 0.35
+
+## Error output contract
+- Errors → stderr as JSON: \`{ "error": true, "code": "...", "message": "..." }\`
+- Success → stdout as JSON (compact by default)
+`,
+
+  install: `# Empirical Install
+
+    empirical install
+
+Runs the interactive installer to connect Empirical memory to your AI coding CLI(s).
+
+## What it does
+1. Detects installed CLIs: Codex, GitHub Copilot, Claude Code
+2. Prompts for CLI target selection
+3. Asks how agents should interact with Empirical:
+   - Mode 1: Via MCP tool (recommended) — registers Empirical as an MCP server
+   - Mode 2: Via CLI commands — writes CLI-direct instruction block, no MCP registration
+   - Mode 3: Both — MCP primary with CLI fallback
+4. Stores the personalized behavior policy for the native Empirical Memory Skill; global
+   instruction files are left unchanged
+5. Offers optional browser OAuth login for CLI use, optional headless/API-key bootstrap for
+   automation, containers, and external runtimes, and optional work-history/scar-tissue guidance
+6. For Claude, installs a \`SessionStart\` hook in \`~/.claude/settings.json\` that calls the
+   \`empirical\` CLI directly once per session — deterministic baseline context that doesn't
+   depend on the model deciding to call a tool. Codex/Copilot have no equivalent hook mechanism.
+7. Installs the native \`empirical-memory\` plugin for each selected client. The plugin owns
+   the Empirical MCP connection and all agent-facing Skills; the CLI does not generate duplicate
+   \`SKILL.md\` or \`EMPIRICAL_SKILL.md\` files.
+
+## Native plugin only
+
+    empirical plugin install <codex|copilot|claude|all> [--all-optional]
+
+    empirical plugin check [--force]
+
+Installs or refreshes only the native marketplace plugin. It does not run the MCP/auth questionnaire
+or modify global instruction files. With no target, the command installs for detected CLIs.
+
+The CLI performs a best-effort native plugin version check during interactive use (at most once per
+day). It is silent for noninteractive/headless commands. Use \`empirical plugin check --force\` to
+check immediately.
+
+Use \`empirical policy show\` to inspect the current native-skill behavior policy and
+\`empirical policy set --json '{"allowDiscretionaryUse":false}'\` to change it without rerunning
+the installer. The policy is cached locally and refreshed when stale.
+`,
+
+  workspace: `# Empirical Workspace Commands
+
+Manage disposable team workspaces and which Empirical workspace is active for this OAuth client.
+
+## Commands
+
+### List workspaces
+
+    empirical workspace list
+
+Shows all available workspaces and which one is currently selected.
+
+### Show current workspace
+
+    empirical workspace current
+
+Prints the currently selected workspace name.
+
+### Select a workspace
+
+    empirical workspace select [<number|name>]
+
+Interactive workspace selector (prompts if no argument given).
+Pass a number (from \`list\`) or an exact workspace name.
+
+    empirical workspace select 2
+    empirical workspace select "My Workspace"
+
+Note: workspace selection may be admin-locked for some OAuth clients.
+
+### Create a demo workspace
+
+    empirical workspace create "Demo Workspace" --description "Temporary shared context"
+
+Creates a team workspace using your existing plan quota and prints its workspace ID.
+
+### Use a workspace
+
+    empirical workspace use <number|name|id>
+
+Friendly alias for \`workspace select\`. It accepts the list number, exact case-insensitive name, or workspace ID.
+
+### Share an active workspace
+
+    empirical workspace invite create --role writer --expires-in-days 7 --max-uses 3
+    empirical workspace invite list
+    empirical workspace invite revoke <token>
+
+Invite commands operate on the active team workspace. Create prints a shareable URL.
+
+### Soft-delete a demo workspace
+
+    empirical workspace delete <number|name|id>
+    empirical workspace delete <number|name|id> --confirm
+
+Deletion dry-runs by default. \`--confirm\` calls the existing soft-delete endpoint; the Default Brain cannot be deleted. If the active workspace is deleted, the CLI selects the Default Brain.
+`,
+
+  doctor: `# Empirical Doctor
+
+    empirical doctor [--output json]
+
+Checks the health of your Empirical CLI setup. Useful for diagnosing auth and connectivity issues.
+
+## Checks performed (in order)
+
+1. **Token presence** — verifies a token exists via EMPIRICAL_ACCESS_TOKEN env, apiKey field,
+   or accessToken field in the token file
+2. **Token type** — detects API key (long alphanumeric, no dots) vs JWT (3 dot-separated parts)
+3. **Token expiry** — if JWT, decodes the payload and checks the \`exp\` field; warns if no \`exp\`
+4. **API connectivity** — calls GET /api/users/me; 200 = OK, anything else = FAIL
+5. **Workspace** — reads workspaceId from the /api/users/me response; warns if null
+
+## Output format
+
+Default: human-readable lines prefixed with [OK], [WARN], or [FAIL].
+
+    empirical doctor --output json
+
+JSON output: \`{ "checks": [{ "name", "status", "message" }], "overall": "ok"|"warn"|"fail" }\`
+Useful for agent/automation use.
+
+## Exit codes
+- 0: all checks passed (ok or warn)
+- 1: one or more checks failed
+`,
+
+  agents: `# Empirical Agent Integration
+
+Empirical memory integrates with three AI coding CLIs.
+
+## Supported agents
+
+| Agent       | Config dir          | Instruction file              | MCP config                          |
+|-------------|---------------------|-------------------------------|-------------------------------------|
+| Claude Code | ~/.claude/          | CLAUDE.md                     | ~/.claude.json (mcpServers)         |
+| Codex CLI   | ~/.codex/           | AGENTS.md                     | codex mcp add                       |
+| Copilot CLI | ~/.copilot/         | copilot-instructions.md       | ~/.copilot/mcp-config.json          |
+
+## Integration modes
+
+**Mode 1: MCP tool (recommended)**
+Empirical is registered as an MCP server. Agents call memory tools (query_memories,
+record_graph_memory, etc.) directly via the MCP protocol. Best for interactive sessions.
+
+**Mode 2: CLI commands**
+Agents run \`empirical memory <subcommand>\` shell commands. No MCP registration required.
+Suitable for headless/scripted environments or when MCP is unavailable.
+
+**Mode 3: Both**
+MCP is primary; CLI commands are available as fallback. Maximizes reliability.
+
+## Inventory commands
+
+    empirical skill list
+    empirical device list
+    empirical device show <deviceId>
+
+Use these to inspect Skills across Kits and the effective Skills installed for a device.
+
+The native \`empirical-memory\` plugin owns its Skills and MCP connection. Run
+\`empirical install\` to install it and configure detected agents.
+`,
+
+  kit: `# Empirical Skills Kits
+
+Kits are named collections of agent Skills. A Kit can contain Skills authored in Empirical
+or discovered from a git repository, then sync the resolved set to your local agents.
+
+## Commands
+
+### Create and list Kits
+
+    empirical kit create "My Team Kit"
+    empirical kit list
+
+### Add or remove a git source
+
+    empirical kit add-source "My Team Kit" https://github.com/example/skills.git
+    empirical kit add-source "My Team Kit" https://github.com/example/skills.git --ref main --path skills
+    empirical kit remove-source "My Team Kit" <source-id>
+
+Each source is scanned for valid \`SKILL.md\` files. A Skill file must begin with YAML
+frontmatter containing both \`name\` and \`description\`, for example:
+
+    ---
+    name: my-skill
+    description: Explain when this skill should be used.
+    ---
+
+### Activate and sync
+
+    empirical kit use "My Team Kit"
+    empirical kit sync
+    empirical kit sync --dry-run
+
+\`kit use\` activates a Kit on this device and syncs its Skills into detected agent
+directories. \`kit sync\` refreshes the active Kit. Use \`--quiet\` for unattended syncs
+and \`--force\` only when you intentionally want to bypass the local-edit guard.
+
+### Inventory
+
+    empirical skill list
+    empirical kit list
+    empirical kit devices "My Team Kit"
+    empirical device list
+    empirical device show <deviceId>
+
+\`skill list\` shows Skills resolved from owned Kits. \`device list\` shows registered devices and
+their active Kits; \`device show\` shows the effective resolved Skills for one device.
+
+### Manage devices and autosync
+
+    empirical kit autosync "My Team Kit" on
+    empirical kit devices "My Team Kit"
+    empirical kit deactivate "My Team Kit" <device-id>
+
+Autosync keeps a registered device current. Interactive syncs review new or changed external
+Skills; unattended syncs apply them and leave a review marker for the next interactive sync.
+`,
+
+  skill: `# Empirical Skills
+
+Skills are agent-facing \`SKILL.md\` instruction files. Authored Skills can be pushed into a
+Kit so they follow you across machines and projects.
+
+## Push an authored Skill
+
+    empirical skill list
+
+    empirical skill push path/to/SKILL.md
+    empirical skill push path/to/SKILL.md --kit "My Team Kit"
+
+The file must contain YAML frontmatter at the top with both required fields:
+
+    ---
+    name: my-skill
+    description: Explain when this skill should be used.
+    ---
+
+The remainder of the file is the Skill body. The CLI validates the frontmatter before upload.
+After pushing, activate or sync the target Kit with \`empirical kit use\` or \`empirical kit sync\`.
+
+## Review and rollback
+
+    empirical skill history <authored-skill-id>
+    empirical skill rollback <authored-skill-id> --to-version 2
+
+Use history to inspect versions and rollback to a known-good version when a Skill needs to be
+reverted. External git-sourced Skills are reviewed during Kit sync and are not authored with
+this command.
+`,
+
+  auth: `# Empirical Auth
+
+## Token types
+
+**API key**: Long alphanumeric string, no dots. Never expires. Preferred for automation.
+**JWT**: Three dot-separated base64 parts. Has an expiry (\`exp\` claim). Used for browser OAuth flows.
+
+## Browser OAuth login
+
+    empirical auth login
+
+Opens the browser, completes OAuth with the Empirical account, and saves a CLI session at
+\`~/.empirical/oauth-session.json\`. Use this for normal interactive CLI use when you do not
+want to provision a permanent API key.
+
+## Bootstrap command (headless / non-interactive)
+
+    empirical oauth bootstrap headless --write-env
+
+Exchanges account credentials (client ID + secret, i.e. your userId + API key) for an access
+token via \`grant_type=client_credentials\` — this is NOT a dynamically-registered OAuth client;
+the server treats client_id/client_secret as userId/apiKey directly.
+Writes token to \`.empirical/headless-token.json\` and \`.empirical/headless.env\`.
+
+No portal visit or manual copy/paste needed: if no client ID/secret is found via
+\`EMPIRICAL_CLIENT_ID\`/\`EMPIRICAL_CLIENT_SECRET\` env vars or \`~/.empirical/oauth-client.json\`
+(set via \`empirical oauth client set\`), the CLI self-provisions your account's API key via
+\`POST /api/v1/users/me/credentials\`, authenticated with whatever bearer token it already has
+(existing token file, or — only if nothing exists yet — one browser login). If you already have
+an API key on the account, the CLI will never silently rotate it (that would break other
+integrations using it); it asks for explicit confirmation in a TTY, or gives up quietly in
+non-interactive contexts. If a stored client is rejected by the server ("Invalid client
+credentials"), the CLI discards it and re-provisions automatically on the same run — unless
+\`--client-id\`/\`--client-secret\` was passed explicitly, in which case the error is surfaced
+as-is.
+
+## Refresh command
+
+    empirical oauth refresh headless
+
+Exchanges a stored refresh token for a new access token. Token file must exist.
+
+## Token resolution priority (resolveAccessToken)
+
+1. \`EMPIRICAL_ACCESS_TOKEN\` environment variable (skipped if it's an expired JWT, so a
+   stale session token can never permanently shadow a valid credential below it)
+2. \`apiKey\` field in token file
+3. \`accessToken\` field in token file
+4. \`~/.empirical/oauth-session.json\` browser OAuth session
+5. \`EMPIRICAL_API_KEY\` or \`EMPIRICAL_CLIENT_SECRET\` environment variable, used directly
+   as a permanent Bearer credential — lets a stateless agent environment authenticate from
+   client_id/secret alone with no token file and no bootstrap step
+
+Token file lookup order:
+1. Path in \`EMPIRICAL_TOKEN_OUTPUT\` env var
+2. \`.empirical/headless-token.json\` (current working directory)
+3. \`~/.empirical/headless-token.json\` (home directory)
+
+The browser OAuth session is stored separately at \`~/.empirical/oauth-session.json\`.
+
+## Verify auth status
+
+    empirical doctor
+
+Checks token presence, type, expiry, and API connectivity.
+`,
+
+  user: `# Empirical User Identity
+
+## Via MCP (when Empirical MCP server is connected)
+
+Use the \`get_user\` MCP tool. Returns: id, email, name, workspaceId, tier, and plan details.
+
+## Via CLI
+
+    empirical doctor --output json
+
+Returns a JSON object with a \`checks\` array. The connectivity check (name: "api")
+includes the user record from /api/users/me when successful.
+
+    empirical workspace current
+
+Prints the active workspace name.
+
+## Notes
+
+- \`get_user\` has no standalone CLI subcommand; use \`empirical doctor --output json\` to
+  inspect identity from the shell.
+- If MCP is unavailable, parse the \`api\` check from doctor JSON output for user context.
+`
+};
+
+let cachedCliVersion = null;
+
+function getCliVersion() {
+  if (cachedCliVersion) return cachedCliVersion;
+  try {
+    const cliPackagePath = path.join(__dirname, '..', 'package.json');
+    const parsed = JSON.parse(fs.readFileSync(cliPackagePath, 'utf8'));
+    if (parsed && typeof parsed.version === 'string' && parsed.version.trim()) {
+      cachedCliVersion = parsed.version.trim();
+      return cachedCliVersion;
+    }
+  } catch (_error) {
+    // ignore and use fallback
+  }
+  cachedCliVersion = 'unknown';
+  return cachedCliVersion;
+}
+
+function deriveBaseUrlFromMcpUrl() {
+  try {
+    const parsed = new URL(EMPIRICAL_MCP_URL);
+    parsed.pathname = parsed.pathname.replace(/\/mcp\/?$/, '');
+    return parsed.origin + parsed.pathname.replace(/\/$/, '');
+  } catch (_error) {
+    return '';
+  }
+}
+
+module.exports = {
+  EMPIRICAL_MCP_NAME,
+  EMPIRICAL_MCP_LEGACY_NAMES,
+  EMPIRICAL_MCP_URL,
+  COPILOT_OAUTH_CLIENT_ID,
+  MEMORY_CATEGORIES,
+  DOC_TOPICS,
+  getCliVersion,
+  deriveBaseUrlFromMcpUrl
+};

package/lib/deviceConfig.js

@@ -0,0 +1,94 @@
+'use strict';
+
+// US-011: local device config (~/.empirical/config.json) — deviceId bootstrap/persistence,
+// activeKit, and lastSyncedVersion. Follows the same `os.homedir()/.empirical/` convention
+// as the headless-token.json file in packages/cli/lib/auth.js.
+const crypto = require('crypto');
+const os = require('os');
+const path = require('path');
+const { readJsonIfExists, writeFile } = require('./fsUtils');
+
+function getEmpiricalDir() {
+  return path.join(os.homedir(), '.empirical');
+}
+
+function getDeviceConfigPath() {
+  return path.join(getEmpiricalDir(), 'config.json');
+}
+
+function readDeviceConfig() {
+  return readJsonIfExists(getDeviceConfigPath()) || {};
+}
+
+function writeDeviceConfig(config) {
+  writeFile(getDeviceConfigPath(), `${JSON.stringify(config, null, 2)}\n`);
+}
+
+function readPolicyCache() {
+  const config = readDeviceConfig();
+  return config.empiricalPolicy || null;
+}
+
+function writePolicyCache(policyCache) {
+  const config = readDeviceConfig();
+  config.empiricalPolicy = policyCache;
+  writeDeviceConfig(config);
+}
+
+// Ensures a deviceId exists in the local config, generating+persisting one on first use.
+// Reused across all future CLI invocations on this machine.
+function ensureDeviceId() {
+  const config = readDeviceConfig();
+  if (config.deviceId) {
+    return config.deviceId;
+  }
+  const deviceId = crypto.randomUUID();
+  config.deviceId = deviceId;
+  writeDeviceConfig(config);
+  return deviceId;
+}
+
+function getSyncManifestPath() {
+  return path.join(getEmpiricalDir(), 'sync-manifest.json');
+}
+
+function readSyncManifest() {
+  return readJsonIfExists(getSyncManifestPath()) || {};
+}
+
+function writeSyncManifest(manifest) {
+  writeFile(getSyncManifestPath(), `${JSON.stringify(manifest, null, 2)}\n`);
+}
+
+// US-016: local record of git_custom-sourced skills whose upstream content changed and was
+// applied unattended (during a `--quiet` sync) without a human reviewing it first. Shape:
+// { [skillName]: { from, firstDetectedAt, source, status } } — see skillSync.js for the gate
+// that populates/clears this. Same `os.homedir()/.empirical/` convention as config.json and
+// sync-manifest.json.
+function getPendingReviewPath() {
+  return path.join(getEmpiricalDir(), 'pending-review.json');
+}
+
+function readPendingReview() {
+  return readJsonIfExists(getPendingReviewPath()) || {};
+}
+
+function writePendingReview(pendingReview) {
+  writeFile(getPendingReviewPath(), `${JSON.stringify(pendingReview, null, 2)}\n`);
+}
+
+module.exports = {
+  getEmpiricalDir,
+  getDeviceConfigPath,
+  readDeviceConfig,
+  writeDeviceConfig,
+  readPolicyCache,
+  writePolicyCache,
+  ensureDeviceId,
+  getSyncManifestPath,
+  readSyncManifest,
+  writeSyncManifest,
+  getPendingReviewPath,
+  readPendingReview,
+  writePendingReview
+};

package/lib/doc.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const { log, warn, ANSI, colorize, supportsColor } = require('./ui');
+const { DOC_TOPICS } = require('./constants');
+
+function runDoc(args) {
+  const topic = (args[0] || '').trim().toLowerCase();
+
+  const descriptions = {
+    memory: 'Query, record, update, delete memories via CLI',
+    user: 'Get current user identity (MCP: get_user; CLI: doctor --output json)',
+    workspace: 'List, view, and switch workspaces',
+    doctor: 'Check token, connectivity, and workspace health',
+    agents: 'Supported agents, integration modes, and native plugin setup',
+    auth: 'Token types, bootstrap, refresh, resolution order',
+    install: 'Install Empirical for Codex / Copilot / Claude Code',
+    kit: 'Create, source, activate, and sync Skills Kits',
+    skill: 'Push, inspect, and roll back authored Skills'
+  };
+
+  if (!topic) {
+    log('Available documentation topics:');
+    log('');
+    for (const [key, desc] of Object.entries(descriptions)) {
+      const padded = key.padEnd(12);
+      if (supportsColor()) {
+        log(`  ${colorize(ANSI.cyan, padded)}  ${desc}`);
+      } else {
+        log(`  ${padded}  ${desc}`);
+      }
+    }
+    log('');
+    log('Run: empirical doc <topic>');
+    return;
+  }
+
+  if (!DOC_TOPICS[topic]) {
+    warn(`Unknown topic: "${topic}"`);
+    log('');
+    log('Available topics: ' + Object.keys(descriptions).join(', '));
+    process.exitCode = 1;
+    return;
+  }
+
+  log(DOC_TOPICS[topic]);
+}
+
+module.exports = {
+  runDoc
+};