@empirical-gauzza/cli 1.0.9

package/lib/kitCommands.js

@@ -0,0 +1,622 @@
+'use strict';
+
+// US-010: CLI commands for Kit management (create/add-source/remove-source/list/autosync/
+// devices/deactivate) and Skill authoring (push/history/rollback).
+//
+// `<kit>` arguments throughout this file accept either a kitId or a Kit's name — the server
+// resolves both (names are unique per owner), so the CLI just passes the raw argument through.
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const matter = require('gray-matter');
+const { log, warn } = require('./ui');
+const { httpJson, printApiError } = require('./http');
+const { parseOption, parseFlag } = require('./env');
+const { requireAccessToken, resolveApiBaseUrl, buildApiAuthHeaders } = require('./auth');
+const { withCliAnalyticsContext } = require('./memoryCommands');
+const { readDeviceConfig, writeDeviceConfig, ensureDeviceId, readPendingReview } = require('./deviceConfig');
+const { performSync, printSyncSummary } = require('./skillSync');
+const { registerScheduledSync, deregisterScheduledSync } = require('./scheduledSync');
+
+// US-016: nag banner surfaced at the START of every interactive (non-`--quiet`) `kit`
+// subcommand — informational only, never blocks the subcommand's own work. `kit sync` is the
+// only place pending-review entries actually get resolved (see skillSync.js's
+// reviewPendingEntries), so this banner just points the user there.
+function surfacePendingReviewBanner(quiet) {
+  if (quiet) return;
+  const pendingReview = readPendingReview();
+  const names = Object.keys(pendingReview);
+  if (names.length === 0) return;
+  warn(`${names.length} skill(s) updated since you last reviewed them: ${names.join(', ')}. Run 'empirical kit sync' to review.`);
+}
+
+// US-012: reconciles the local OS scheduled task to match a Kit's `autoSyncEnabled` flag.
+// Best-effort/non-fatal: a broken scheduler (e.g. `schtasks`/`launchctl`/`crontab` missing or
+// erroring) is logged to stderr and never blocks the calling `kit use`/`kit autosync` command,
+// consistent with this being a background drift-catch-up floor, not a hard requirement.
+// Tracks which kitId currently "owns" the local schedule via deviceConfig's `scheduledSyncKitId`
+// so `kit autosync <kit> off` can tell whether `<kit>` is the one actually registered locally.
+function reconcileScheduledSyncForKit(kitId, autoSyncEnabled, quiet) {
+  const config = readDeviceConfig();
+  try {
+    if (autoSyncEnabled) {
+      registerScheduledSync();
+      writeDeviceConfig({ ...config, scheduledSyncKitId: kitId });
+    } else {
+      deregisterScheduledSync();
+      writeDeviceConfig({ ...config, scheduledSyncKitId: null });
+    }
+  } catch (error) {
+    if (!quiet) {
+      warn(`Warning: failed to reconcile local scheduled sync task: ${error.message}`);
+    }
+  }
+}
+
+// ─── Kit subcommands ──────────────────────────────────────────────────────────
+
+async function runKitCreate(args) {
+  const name = args[0] && !args[0].startsWith('--') ? args[0] : '';
+  if (!name) {
+    warn('Usage: empirical kit create <name> [--workspace <workspaceId>]');
+    process.exit(1);
+  }
+
+  const workspaceId = parseOption(args, '--workspace', '');
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const url = new URL('/api/v1/kits', baseUrl).toString();
+
+  const body = { name };
+  if (workspaceId) body.workspaceId = workspaceId;
+
+  let response;
+  try {
+    response = await httpJson(url, 'POST', body, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const created = (response && response.data) ? response.data : response;
+  log(JSON.stringify(created));
+}
+
+async function runKitAddSource(args) {
+  const kitId = args[0] && !args[0].startsWith('--') ? args[0] : '';
+  const gitUrl = args[1] && !args[1].startsWith('--') ? args[1] : '';
+
+  if (!kitId || !gitUrl) {
+    warn('Usage: empirical kit add-source <kit> <git-url> [--ref <ref>] [--path <subpath>]');
+    process.exit(1);
+  }
+
+  const ref = parseOption(args, '--ref', '');
+  const subpath = parseOption(args, '--path', '');
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const url = new URL(`/api/v1/kits/${encodeURIComponent(kitId)}/sources`, baseUrl).toString();
+
+  const body = { sourceType: 'git_custom', repoUrl: gitUrl };
+  if (ref) body.ref = ref;
+  if (subpath) body.subpath = subpath;
+
+  let response;
+  try {
+    response = await httpJson(url, 'POST', body, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const created = (response && response.data) ? response.data : response;
+  log(JSON.stringify(created));
+}
+
+async function runKitRemoveSource(args) {
+  const kitId = args[0] && !args[0].startsWith('--') ? args[0] : '';
+  const sourceId = args[1] && !args[1].startsWith('--') ? args[1] : '';
+
+  if (!kitId || !sourceId) {
+    warn('Usage: empirical kit remove-source <kit> <source-id>');
+    process.exit(1);
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const url = new URL(
+    `/api/v1/kits/${encodeURIComponent(kitId)}/sources/${encodeURIComponent(sourceId)}`,
+    baseUrl
+  ).toString();
+
+  let response;
+  try {
+    response = await httpJson(url, 'DELETE', null, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const result = (response && response.data) ? response.data : response;
+  log(JSON.stringify(result));
+}
+
+async function runKitList(args) {
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const url = new URL('/api/v1/kits', baseUrl).toString();
+
+  let response;
+  try {
+    response = await httpJson(url, 'GET', undefined, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const result = (response && response.data) ? response.data : response;
+  log(JSON.stringify(result));
+}
+
+async function fetchInventoryJson(url, accessToken) {
+  try {
+    return await httpJson(url, 'GET', undefined, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+}
+
+async function listOwnedKits(baseUrl, accessToken) {
+  const response = await fetchInventoryJson(new URL('/api/v1/kits', baseUrl).toString(), accessToken);
+  return response?.data?.kits || response?.kits || [];
+}
+
+async function runSkillList(args) {
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const kitFilter = parseOption(args, '--kit', '');
+  const kits = await listOwnedKits(baseUrl, accessToken);
+  const selectedKits = kitFilter
+    ? kits.filter((kit) => kit.kitId === kitFilter || kit.name === kitFilter)
+    : kits;
+  const skills = [];
+
+  for (const kit of selectedKits) {
+    const response = await fetchInventoryJson(
+      new URL(`/api/v1/kits/${encodeURIComponent(kit.kitId)}/resolved`, baseUrl).toString(),
+      accessToken
+    );
+    const kitSkills = response?.data?.skills || response?.skills || [];
+    for (const skill of kitSkills) {
+      skills.push({
+        ...skill,
+        kitId: kit.kitId,
+        kitName: kit.name,
+        isDefault: Boolean(kit.isDefault)
+      });
+    }
+  }
+
+  log(JSON.stringify({ skills }));
+}
+
+async function runDeviceList() {
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const kits = await listOwnedKits(baseUrl, accessToken);
+  const devicesById = new Map();
+
+  for (const kit of kits.filter((candidate) => !candidate.isDefault)) {
+    const response = await fetchInventoryJson(
+      new URL(`/api/v1/kits/${encodeURIComponent(kit.kitId)}/devices`, baseUrl).toString(),
+      accessToken
+    );
+    const devices = response?.data?.devices || response?.devices || [];
+    for (const device of devices) {
+      const existing = devicesById.get(device.deviceId) || {
+        ...device,
+        kits: []
+      };
+      existing.kits.push({
+        kitId: kit.kitId,
+        kitName: kit.name,
+        active: Boolean(device.active)
+      });
+      devicesById.set(device.deviceId, existing);
+    }
+  }
+
+  log(JSON.stringify({ devices: [...devicesById.values()] }));
+}
+
+async function runDeviceShow(args) {
+  const deviceId = args[0] && !args[0].startsWith('--') ? args[0] : '';
+  if (!deviceId) {
+    warn('Usage: empirical device show <deviceId>');
+    process.exit(1);
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const response = await fetchInventoryJson(
+    new URL(`/api/v1/devices/${encodeURIComponent(deviceId)}/resolved`, baseUrl).toString(),
+    accessToken
+  );
+  const data = response?.data || response || {};
+  log(JSON.stringify({ deviceId, ...data }));
+}
+
+async function runDeviceCommand(subArgs) {
+  const sub = subArgs[0];
+  const rest = subArgs.slice(1);
+  return withCliAnalyticsContext(
+    { command: `device.${sub || 'unknown'}`, subcommand: sub || 'unknown' },
+    async () => {
+      if (sub === 'list') return runDeviceList(rest);
+      if (sub === 'show') return runDeviceShow(rest);
+      warn('Unknown device subcommand: ' + (sub || '(none)'));
+      warn('Usage: empirical device <list|show> [options]');
+      process.exit(1);
+    }
+  );
+}
+
+async function runKitAutosync(args) {
+  const kitId = args[0] && !args[0].startsWith('--') ? args[0] : '';
+  const mode = args[1] && !args[1].startsWith('--') ? args[1] : '';
+
+  if (!kitId || (mode !== 'on' && mode !== 'off')) {
+    warn('Usage: empirical kit autosync <kit> on|off');
+    process.exit(1);
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const url = new URL(`/api/v1/kits/${encodeURIComponent(kitId)}/autosync`, baseUrl).toString();
+
+  let response;
+  try {
+    response = await httpJson(url, 'POST', { enabled: mode === 'on' }, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const result = (response && response.data) ? response.data : response;
+  log(JSON.stringify(result));
+
+  // Only reconcile the local scheduled task when toggling autosync for the kit that's actually
+  // active on THIS device — toggling a non-active kit's server-side flag doesn't affect this
+  // machine's schedule (see US-012 AC).
+  const config = readDeviceConfig();
+  if (config.activeKit === kitId) {
+    reconcileScheduledSyncForKit(kitId, mode === 'on', false);
+  }
+}
+
+async function runKitDevices(args) {
+  const kitId = args[0] && !args[0].startsWith('--') ? args[0] : '';
+
+  if (!kitId) {
+    warn('Usage: empirical kit devices <kit>');
+    process.exit(1);
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const url = new URL(`/api/v1/kits/${encodeURIComponent(kitId)}/devices`, baseUrl).toString();
+
+  let response;
+  try {
+    response = await httpJson(url, 'GET', undefined, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const result = (response && response.data) ? response.data : response;
+  log(JSON.stringify(result));
+}
+
+async function runKitDeactivate(args) {
+  const kitId = args[0] && !args[0].startsWith('--') ? args[0] : '';
+  const deviceId = args[1] && !args[1].startsWith('--') ? args[1] : '';
+
+  if (!kitId || !deviceId) {
+    warn('Usage: empirical kit deactivate <kit> <deviceId>');
+    process.exit(1);
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const url = new URL(
+    `/api/v1/kits/${encodeURIComponent(kitId)}/devices/${encodeURIComponent(deviceId)}/deactivate`,
+    baseUrl
+  ).toString();
+
+  let response;
+  try {
+    response = await httpJson(url, 'POST', null, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const result = (response && response.data) ? response.data : response;
+  log(JSON.stringify(result));
+}
+
+// `empirical kit use <kit>` — <kit> is a kitId or Kit name (server resolves both). Sets
+// activeKit locally to whatever identifier the user passed, registers this device against
+// the named Kit server-side, then triggers a sync via the shared skillSync module (never by
+// shelling back out to `empirical kit sync`).
+async function runKitUse(args) {
+  const kitId = args[0] && !args[0].startsWith('--') ? args[0] : '';
+  if (!kitId) {
+    warn('Usage: empirical kit use <kit> [--dry-run] [--quiet] [--force]');
+    process.exit(1);
+  }
+
+  const dryRun = parseFlag(args, '--dry-run');
+  const quiet = parseFlag(args, '--quiet');
+  const force = parseFlag(args, '--force');
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const deviceId = ensureDeviceId();
+
+  const url = new URL(`/api/v1/kits/${encodeURIComponent(kitId)}/devices`, baseUrl).toString();
+  let response;
+  try {
+    response = await httpJson(
+      url,
+      'POST',
+      { deviceId, hostname: os.hostname() },
+      buildApiAuthHeaders(accessToken)
+    );
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const config = readDeviceConfig();
+  writeDeviceConfig({ ...config, activeKit: kitId });
+
+  const result = (response && response.data) ? response.data : response;
+  if (!quiet) {
+    log(JSON.stringify(result));
+  }
+
+  let syncResult;
+  try {
+    syncResult = await performSync({ accessToken, baseUrl, dryRun, force, quiet });
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+  printSyncSummary(syncResult, quiet);
+
+  // US-012: fetch this Kit's own autoSyncEnabled flag and reconcile the local scheduled task to
+  // match it. A failure here is fetched best-effort — it must never turn a successful `kit use`
+  // (device registered, sync applied) into a failing command.
+  const kitUrl = new URL(`/api/v1/kits/${encodeURIComponent(kitId)}`, baseUrl).toString();
+  try {
+    const kitResponse = await httpJson(kitUrl, 'GET', undefined, buildApiAuthHeaders(accessToken));
+    const kit = (kitResponse && kitResponse.data && kitResponse.data.kit) ? kitResponse.data.kit : null;
+    reconcileScheduledSyncForKit(kitId, !!(kit && kit.autoSyncEnabled), quiet);
+  } catch (error) {
+    if (!quiet) {
+      warn(`Warning: failed to fetch Kit autosync setting: ${error.message}`);
+    }
+  }
+}
+
+// `empirical kit sync [--dry-run] [--quiet] [--force]` — see skillSync.js for the actual
+// version-check/resolved-fetch/per-target-write/manifest logic; this just wires CLI flags,
+// auth, and stdout/stderr reporting around it.
+async function runKitSync(args) {
+  const dryRun = parseFlag(args, '--dry-run');
+  const quiet = parseFlag(args, '--quiet');
+  const force = parseFlag(args, '--force');
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+
+  let result;
+  try {
+    result = await performSync({ accessToken, baseUrl, dryRun, force, quiet });
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  printSyncSummary(result, quiet);
+}
+
+async function runKitCommand(subArgs) {
+  const sub = subArgs[0];
+  const rest = subArgs.slice(1);
+
+  return withCliAnalyticsContext(
+    { command: `kit.${sub || 'unknown'}`, subcommand: sub || 'unknown' },
+    async () => {
+      // US-016: single choke point — every interactive kit subcommand (sync included; it's
+      // where entries actually get cleared) surfaces the pending-review banner first, before
+      // doing its own work. `--quiet` may appear anywhere in `rest` (not every subcommand's own
+      // parser reads it), so check for it directly here rather than relying on each handler.
+      surfacePendingReviewBanner(parseFlag(rest, '--quiet'));
+
+      if (sub === 'create') return runKitCreate(rest);
+      if (sub === 'add-source') return runKitAddSource(rest);
+      if (sub === 'remove-source') return runKitRemoveSource(rest);
+      if (sub === 'list') return runKitList(rest);
+      if (sub === 'autosync') return runKitAutosync(rest);
+      if (sub === 'devices') return runKitDevices(rest);
+      if (sub === 'deactivate') return runKitDeactivate(rest);
+      if (sub === 'use') return runKitUse(rest);
+      if (sub === 'sync') return runKitSync(rest);
+
+      warn('Unknown kit subcommand: ' + (sub || '(none)'));
+      warn('Usage: empirical kit <create|add-source|remove-source|list|autosync|devices|deactivate|use|sync> [options]');
+      process.exit(1);
+    }
+  );
+}
+
+// ─── Skill subcommands ────────────────────────────────────────────────────────
+
+async function runSkillPush(args) {
+  const filePath = args[0] && !args[0].startsWith('--') ? args[0] : '';
+  if (!filePath) {
+    warn('Usage: empirical skill push <path/to/SKILL.md> [--kit <kitId>]');
+    warn('Wrote or edited a SKILL.md? Push it so it follows you across machines/projects. See `empirical --help`.');
+    process.exit(1);
+  }
+
+  const kitId = parseOption(args, '--kit', '');
+
+  let raw;
+  try {
+    raw = fs.readFileSync(path.resolve(filePath), 'utf8');
+  } catch (error) {
+    warn(JSON.stringify({ error: true, code: 'file_read_error', message: error.message }));
+    process.exit(1);
+  }
+
+  let parsed;
+  try {
+    parsed = matter(raw);
+  } catch (error) {
+    warn(JSON.stringify({ error: true, code: 'frontmatter_parse_error', message: error.message }));
+    process.exit(1);
+  }
+
+  const name = typeof parsed.data.name === 'string' ? parsed.data.name.trim() : '';
+  const description = typeof parsed.data.description === 'string' ? parsed.data.description.trim() : '';
+  const bodyMarkdown = parsed.content;
+
+  if (!name || !description) {
+    warn(JSON.stringify({
+      error: true,
+      code: 'invalid_frontmatter',
+      message: 'SKILL.md frontmatter must include both "name" and "description".'
+    }));
+    process.exit(1);
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const url = new URL('/api/v1/skills/push', baseUrl).toString();
+
+  const body = { name, description, bodyMarkdown };
+  if (kitId) body.kitId = kitId;
+
+  let response;
+  try {
+    response = await httpJson(url, 'POST', body, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const result = (response && response.data) ? response.data : response;
+  log(JSON.stringify(result));
+}
+
+async function runSkillHistory(args) {
+  const authoredSkillId = args[0] && !args[0].startsWith('--') ? args[0] : '';
+  if (!authoredSkillId) {
+    warn('Usage: empirical skill history <authoredSkillId>');
+    process.exit(1);
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const url = new URL(
+    `/api/v1/skills/${encodeURIComponent(authoredSkillId)}/history`,
+    baseUrl
+  ).toString();
+
+  let response;
+  try {
+    response = await httpJson(url, 'GET', undefined, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const result = (response && response.data) ? response.data : response;
+  log(JSON.stringify(result));
+}
+
+async function runSkillRollback(args) {
+  const authoredSkillId = args[0] && !args[0].startsWith('--') ? args[0] : '';
+  const toVersionRaw = parseOption(args, '--to-version', '');
+  const toVersion = Number(toVersionRaw);
+
+  if (!authoredSkillId || !toVersionRaw || !Number.isInteger(toVersion) || toVersion < 1) {
+    warn('Usage: empirical skill rollback <authoredSkillId> --to-version <n>');
+    process.exit(1);
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const url = new URL(
+    `/api/v1/skills/${encodeURIComponent(authoredSkillId)}/rollback`,
+    baseUrl
+  ).toString();
+
+  let response;
+  try {
+    response = await httpJson(url, 'POST', { toVersion }, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const result = (response && response.data) ? response.data : response;
+  log(JSON.stringify(result));
+}
+
+async function runSkillCommand(subArgs) {
+  const sub = subArgs[0];
+  const rest = subArgs.slice(1);
+
+  return withCliAnalyticsContext(
+    { command: `skill.${sub || 'unknown'}`, subcommand: sub || 'unknown' },
+    async () => {
+      if (sub === 'push') return runSkillPush(rest);
+      if (sub === 'list') return runSkillList(rest);
+      if (sub === 'history') return runSkillHistory(rest);
+      if (sub === 'rollback') return runSkillRollback(rest);
+
+      warn('Unknown skill subcommand: ' + (sub || '(none)'));
+      warn('Usage: empirical skill <list|push|history|rollback> [options]');
+      process.exit(1);
+    }
+  );
+}
+
+module.exports = {
+  runKitCreate,
+  runKitAddSource,
+  runKitRemoveSource,
+  runKitList,
+  runKitAutosync,
+  runKitDevices,
+  runKitDeactivate,
+  runKitUse,
+  runKitSync,
+  runSkillList,
+  runDeviceList,
+  runDeviceShow,
+  runDeviceCommand,
+  runKitCommand,
+  runSkillPush,
+  runSkillHistory,
+  runSkillRollback,
+  runSkillCommand
+};