@remodex/rmx 1.0.2

package/src/cli/config-command.ts

@@ -0,0 +1,183 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { clearCodexAccountPin } from "../codex/account-priority";
+import { getConfigPath, readConfigDiagnostics, saveConfig, validateConfigCandidate } from "../config";
+import { VISION_REASONING_EFFORTS, isVisionReasoningEffort } from "../reasoning-effort";
+import type { OcxConfig } from "../types";
+import { normalizeVisionReasoningForModel } from "../vision/reasoning";
+import { CliUsageError, printData, rejectArgs, runCliAction, takeFlag } from "./runtime-api";
+
+const USAGE = `Usage:
+  rmx config [show] [--json] [--source]
+  rmx config get <dot.path> [--json]
+  rmx config set <dot.path> <json-or-string> [--json]
+  rmx config unset <dot.path> [--json]
+  rmx config validate [path|-] [--json]
+  rmx config export <path|->
+  rmx config import <path|-> --yes [--json]`;
+
+const SECRET_KEYS = /^(apiKey|key|accessToken|refreshToken|idToken|token|password|clientSecret)$/i;
+const BLOCKED_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
+
+function redact(value: unknown, key = ""): unknown {
+  if (SECRET_KEYS.test(key) && typeof value === "string") return value ? "********" : value;
+  if (Array.isArray(value)) return value.map(item => redact(item));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([childKey, child]) => [childKey, redact(child, childKey)]));
+  }
+  return value;
+}
+
+function pathSegments(path: string): string[] {
+  const segments = path.split(".").map(part => part.trim()).filter(Boolean);
+  if (segments.length === 0 || segments.some(part => BLOCKED_SEGMENTS.has(part))) throw new CliUsageError("invalid config path", USAGE);
+  return segments;
+}
+
+function getPath(root: unknown, path: string): unknown {
+  let current = root;
+  for (const segment of pathSegments(path)) {
+    if (!current || typeof current !== "object" || !Object.hasOwn(current, segment)) throw new CliUsageError(`config path not found: ${path}`);
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current;
+}
+
+function setPath(root: Record<string, unknown>, path: string, value: unknown, remove = false): void {
+  const segments = pathSegments(path);
+  let current = root;
+  for (const segment of segments.slice(0, -1)) {
+    const next = current[segment];
+    if (!next || typeof next !== "object" || Array.isArray(next)) throw new CliUsageError(`config parent path not found: ${segment}`, USAGE);
+    current = next as Record<string, unknown>;
+  }
+  const leaf = segments.at(-1)!;
+  if (remove && !Object.hasOwn(current, leaf)) throw new CliUsageError(`config path not found: ${path}`);
+  if (remove) delete current[leaf];
+  else current[leaf] = value;
+}
+
+function parseValue(raw: string): unknown {
+  try { return JSON.parse(raw); }
+  catch { return raw; }
+}
+
+function loadInput(path: string): unknown {
+  const raw = path === "-" ? readFileSync(0, "utf8") : readFileSync(path, "utf8");
+  try { return JSON.parse(raw); }
+  catch { throw new CliUsageError(`invalid JSON in ${path}`); }
+}
+
+function visionReasoningError(value: unknown): string | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const vision = (value as Record<string, unknown>).visionSidecar;
+  if (!vision || typeof vision !== "object" || Array.isArray(vision)) return null;
+  const reasoning = (vision as Record<string, unknown>).reasoning;
+  if (reasoning === undefined || isVisionReasoningEffort(reasoning)) return null;
+  return `schema_invalid: visionSidecar.reasoning: must be one of ${VISION_REASONING_EFFORTS.join(", ")}`;
+}
+
+function validateCandidate(value: unknown): ReturnType<typeof validateConfigCandidate> {
+  const error = visionReasoningError(value);
+  return error ? { ok: false, error } : validateConfigCandidate(value);
+}
+
+function normalizeVisionConfig(config: OcxConfig): OcxConfig {
+  const vision = config.visionSidecar;
+  if (!vision || vision.reasoning === undefined) return config;
+  // Keep CLI import/set semantics aligned with the execution path: an omitted or blank model means
+  // the bounded OpenAI vision default, gpt-5.4-mini, not the Dashboard's web-search default.
+  const model = vision.model || "gpt-5.4-mini";
+  const normalized = normalizeVisionReasoningForModel(model, vision.reasoning);
+  if (normalized === undefined) delete vision.reasoning;
+  else vision.reasoning = normalized;
+  return config;
+}
+
+function validate(value: unknown): OcxConfig {
+  const result = validateCandidate(value);
+  if (!result.ok) throw new CliUsageError(result.error);
+  return normalizeVisionConfig(result.config);
+}
+
+export async function handleConfigCommand(argv: string[]): Promise<number> {
+  return runCliAction(async () => {
+    const args = [...argv];
+    const action = (args.shift() ?? "show").toLowerCase();
+    const wantsJson = takeFlag(args, "--json");
+    if (action === "show") {
+      const source = takeFlag(args, "--source");
+      rejectArgs(args, USAGE);
+      const diagnostics = readConfigDiagnostics();
+      const config = redact(diagnostics.config);
+      const result = source ? { config, source: diagnostics.source, error: diagnostics.error, warnings: diagnostics.warnings ?? [] } : config;
+      printData(result, true);
+      return;
+    }
+    if (action === "get") {
+      const path = args.shift();
+      if (!path) throw new CliUsageError("config path is required", USAGE);
+      rejectArgs(args, USAGE);
+      const value = redact(getPath(readConfigDiagnostics().config, path), path.split(".").at(-1));
+      if (wantsJson || typeof value === "object") console.log(JSON.stringify(value, null, 2));
+      else console.log(String(value));
+      return;
+    }
+    if (action === "set" || action === "unset") {
+      const path = args.shift();
+      const raw = action === "set" ? args.shift() : undefined;
+      if (!path || (action === "set" && raw === undefined)) throw new CliUsageError("config path and value are required", USAGE);
+      rejectArgs(args, USAGE);
+      const candidate = structuredClone(readConfigDiagnostics().config) as unknown as Record<string, unknown>;
+      setPath(candidate, path, raw === undefined ? undefined : parseValue(raw), action === "unset");
+      const config = validate(candidate);
+      const savedValue = action === "unset" ? null : getPath(config, path);
+      // Setting the order here is the operator restating it, exactly as through
+      // `rmx account priority` or the management route, so it releases the manual pin
+      // for the same reason those do: a pin made before any order existed would
+      // otherwise outrank every order set afterwards, capping the pool at the pinned
+      // account's tier with nothing on any surface explaining why. `import` is
+      // deliberately not covered — that file supplies its own pin, so there is no
+      // stale one to release.
+      if (pathSegments(path)[0] === "codexAccountPriorities") clearCodexAccountPin(config);
+      saveConfig(config);
+      printData({ ok: true, path, value: redact(savedValue, path.split(".").at(-1)) }, wantsJson,
+        [`${action === "unset" ? "Unset" : "Set"} ${path}.`]);
+      return;
+    }
+    if (action === "validate") {
+      const path = args.shift();
+      rejectArgs(args, USAGE);
+      const result = path ? validateCandidate(loadInput(path)) : (() => {
+        const diagnostics = readConfigDiagnostics();
+        if (diagnostics.error) return { ok: false as const, error: diagnostics.error };
+        return validateCandidate(diagnostics.config);
+      })();
+      printData(result.ok ? { ok: true, source: path ?? getConfigPath() } : result, wantsJson,
+        [result.ok ? "Config is valid." : `Config is invalid: ${result.error}`]);
+      if (!result.ok) process.exitCode = 1;
+      return;
+    }
+    if (action === "export") {
+      const path = args.shift();
+      if (!path) throw new CliUsageError("export path is required", USAGE);
+      rejectArgs(args, USAGE);
+      const content = `${JSON.stringify(readConfigDiagnostics().config, null, 2)}\n`;
+      if (path === "-") process.stdout.write(content);
+      else { writeFileSync(path, content, { encoding: "utf8", mode: 0o600 }); console.log(`Exported config to ${path}.`); }
+      return;
+    }
+    if (action === "import") {
+      const path = args.shift();
+      const yes = takeFlag(args, "--yes");
+      if (!path) throw new CliUsageError("import path is required", USAGE);
+      if (!yes) throw new CliUsageError("import requires --yes", USAGE);
+      rejectArgs(args, USAGE);
+      saveConfig(validate(loadInput(path)));
+      printData({ ok: true, source: path }, wantsJson, [`Imported config from ${path}. Restart or run rmx sync if needed.`]);
+      return;
+    }
+    throw new CliUsageError(`unknown config command ${action}`, USAGE);
+  });
+}
+
+export const CONFIG_USAGE = USAGE;

package/src/cli/debug.ts

@@ -0,0 +1,228 @@
+import { findLiveProxy, probeHostname } from "../server/proxy-liveness";
+import { DEBUG_ENV, type DebugSettingsView } from "../lib/debug-settings";
+import { runningProxyUpdateHeaders } from "../oauth/login-cli";
+
+type DebugScope = "provider" | "usage" | "injection" | "claude";
+
+async function requireLiveProxy() {
+  const live = await findLiveProxy();
+  if (!live) {
+    console.error("Proxy is not running. Start it with: rmx start");
+    process.exit(1);
+  }
+  return live;
+}
+
+async function fetchDebugSettings(): Promise<DebugSettingsView> {
+  const live = await requireLiveProxy();
+  try {
+    const res = await fetch(`http://${probeHostname(live.hostname)}:${live.port}/api/debug`, {
+      headers: runningProxyUpdateHeaders(),
+    });
+    if (!res.ok) {
+      console.error(`Failed to read debug settings (${res.status})`);
+      process.exit(1);
+    }
+    return await res.json() as DebugSettingsView;
+  } catch (err) {
+    console.error(`Proxy is running but /api/debug is unreachable: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}
+
+async function putDebugSettings(body: Record<string, unknown>): Promise<DebugSettingsView> {
+  const live = await requireLiveProxy();
+  const res = await fetch(`http://${probeHostname(live.hostname)}:${live.port}/api/debug`, {
+    method: "PUT",
+    headers: runningProxyUpdateHeaders(),
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    console.error(`Failed to update debug settings (${res.status})${text ? `: ${text.slice(0, 200)}` : ""}`);
+    process.exit(1);
+  }
+  return await res.json() as DebugSettingsView;
+}
+
+function printScopeStatus(scope: DebugScope, view: DebugSettingsView): void {
+  if (scope === "provider") {
+    console.log(`Provider debug: ${view.enabled ? "ON" : "off"}`);
+    console.log(`  env=${view.env.debug ? "on" : "off"}, runtime=${view.runtimeOverride.debug === undefined ? "env/default" : view.runtimeOverride.debug ? "on" : "off"}`);
+    console.log("  Tail: rmx debug provider logs [-f]");
+  } else if (scope === "usage") {
+    console.log(`Usage debug: ${view.usage ? "ON" : "off"}`);
+    console.log(`  env=${view.env.usage ? "on" : "off"}, runtime=${view.runtimeOverride.usage === undefined ? "env/default" : view.runtimeOverride.usage ? "on" : "off"}`);
+    console.log("  Tail: rmx debug usage logs [-f] (via running proxy API)");
+  } else if (scope === "injection") {
+    console.log(`Injection debug: ${view.injection ? "ON" : "off"}`);
+    console.log(`  env=${view.env.injection ? "on" : "off"}, runtime=${view.runtimeOverride.injection === undefined ? "env/default" : view.runtimeOverride.injection ? "on" : "off"}`);
+    console.log("  Lines appear on the proxy console when multi-agent guidance is injected.");
+  } else {
+    console.log(`Claude inbound debug: ${view.claude ? "ON" : "off"}`);
+    console.log(`  env=${view.env.claude ? "on" : "off"}, runtime=${view.runtimeOverride.claude === undefined ? "env/default" : view.runtimeOverride.claude ? "on" : "off"}`);
+    console.log("  View: rmx observe claude-inbound");
+  }
+}
+
+function envDebugEnabled(): boolean {
+  return process.env.OCX_DEBUG === "1"
+    || process.env.OCX_DEBUG_FRAMES === "1";
+}
+
+async function printProviderLogs(follow: boolean): Promise<void> {
+  const live = await requireLiveProxy();
+  const base = `http://${probeHostname(live.hostname)}:${live.port}/api/debug/logs`;
+
+  let after = 0;
+  try {
+    const res = await fetch(`${base}?limit=500`, { headers: runningProxyUpdateHeaders() });
+    if (!res.ok) {
+      console.error(`Failed to read debug logs (${res.status})`);
+      process.exit(1);
+    }
+    const entries = await res.json() as { seq: number; line: string }[];
+    for (const entry of entries) console.log(entry.line);
+    if (entries.length > 0) after = entries[entries.length - 1]!.seq;
+  } catch (err) {
+    console.error(`Failed to read debug logs: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+
+  if (!follow) return;
+
+  while (true) {
+    await new Promise(resolve => setTimeout(resolve, 1000));
+    try {
+      const res = await fetch(`${base}?after=${after}&limit=500`, { headers: runningProxyUpdateHeaders() });
+      if (!res.ok) continue;
+      const entries = await res.json() as { seq: number; line: string }[];
+      for (const entry of entries) console.log(entry.line);
+      if (entries.length > 0) after = entries[entries.length - 1]!.seq;
+    } catch {
+      /* keep following */
+    }
+  }
+}
+
+async function printUsageLogs(follow: boolean): Promise<void> {
+  const live = await requireLiveProxy();
+  const base = `http://${probeHostname(live.hostname)}:${live.port}/api/debug/usage-logs`;
+
+  let after = 0;
+  try {
+    const res = await fetch(`${base}?limit=500`, { headers: runningProxyUpdateHeaders() });
+    if (!res.ok) {
+      console.error(`Failed to read usage debug logs (${res.status})`);
+      process.exit(1);
+    }
+    const entries = await res.json() as { seq: number; line: string }[];
+    for (const entry of entries) console.log(entry.line);
+    if (entries.length === 0) console.log("(empty — enable with: rmx debug usage on)");
+    if (entries.length > 0) after = entries[entries.length - 1]!.seq;
+  } catch (err) {
+    console.error(`Failed to read usage debug logs: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+
+  if (!follow) return;
+
+  while (true) {
+    await new Promise(resolve => setTimeout(resolve, 1000));
+    try {
+      const res = await fetch(`${base}?after=${after}&limit=500`, { headers: runningProxyUpdateHeaders() });
+      if (!res.ok) continue;
+      const entries = await res.json() as { seq: number; line: string }[];
+      for (const entry of entries) console.log(entry.line);
+      if (entries.length > 0) after = entries[entries.length - 1]!.seq;
+    } catch {
+      /* keep following */
+    }
+  }
+}
+
+async function handleScopeCommand(scope: DebugScope, actionArgv: string[]): Promise<void> {
+  const action = (actionArgv[0] ?? "status").trim().toLowerCase();
+
+  if (action === "on" || action === "off") {
+    const enabled = action === "on";
+    const body = scope === "provider" ? { debug: enabled }
+      : scope === "usage" ? { usage: enabled }
+        : scope === "injection" ? { injection: enabled }
+          : { claude: enabled };
+    printScopeStatus(scope, await putDebugSettings(body));
+    console.log(`\n${scope} debug is now ${enabled ? "enabled" : "disabled"}.`);
+    return;
+  }
+
+  if (action === "status") {
+    printScopeStatus(scope, await fetchDebugSettings());
+    return;
+  }
+
+  if (action === "reset") {
+    const resetKey = scope === "provider" ? "provider" : scope;
+    printScopeStatus(scope, await putDebugSettings({ reset: resetKey }));
+    console.log(`\nRuntime override cleared for ${scope}; effective value follows env again.`);
+    return;
+  }
+
+  if (action === "logs") {
+    if (scope === "injection" || scope === "claude") {
+      console.error(scope === "claude"
+        ? "Use: rmx observe claude-inbound"
+        : "Injection debug has no buffered log stream; use: rmx observe injection");
+      process.exit(1);
+    }
+    const follow = actionArgv.slice(1).some(arg => arg === "-f" || arg === "--follow");
+    if (scope === "provider") await printProviderLogs(follow);
+    else await printUsageLogs(follow);
+    return;
+  }
+
+  console.error(scope === "injection" || scope === "claude"
+    ? `Usage: rmx debug ${scope} on|off|status|reset`
+    : `Usage: rmx debug ${scope} on|off|status|reset|logs [-f]`);
+  process.exit(1);
+}
+
+function printTopLevelHelp(): void {
+  console.log("Debug commands (proxy must be running):");
+  console.log("");
+  console.log("  rmx debug provider on|off|status|reset|logs [-f]");
+  console.log("  rmx debug usage on|off|status|reset|logs [-f]");
+  console.log("  rmx debug injection on|off|status|reset");
+  console.log("  rmx debug claude on|off|status|reset");
+  console.log("");
+  console.log("Env defaults on start:");
+  console.log("  provider → OCX_DEBUG=1 (legacy OCX_DEBUG_FRAMES still works)");
+  console.log(`  usage    → ${DEBUG_ENV.usage}=1`);
+  console.log(`  injection→ ${DEBUG_ENV.injection}=1`);
+  console.log(`  claude   → ${DEBUG_ENV.claude}=1`);
+}
+
+export async function handleDebugCommand(argv: string[]): Promise<void> {
+  const sub = (argv[0] ?? "").trim().toLowerCase();
+
+  if (sub === "provider" || sub === "usage" || sub === "injection" || sub === "claude") {
+    await handleScopeCommand(sub, argv.slice(1));
+    return;
+  }
+
+  if (sub === "" || sub === "help" || sub === "--help" || sub === "-h") {
+    const live = await findLiveProxy();
+    if (!live) {
+      console.log("Proxy is not running — env defaults for the next start:");
+      console.log(`  provider → OCX_DEBUG = ${envDebugEnabled() ? "on" : "off"}`);
+      console.log(`  usage    → ${DEBUG_ENV.usage} = ${process.env[DEBUG_ENV.usage] === "1" ? "on" : "off"}`);
+      console.log(`  injection→ ${DEBUG_ENV.injection} = ${process.env[DEBUG_ENV.injection] === "1" ? "on" : "off"}`);
+      console.log(`  claude   → ${DEBUG_ENV.claude} = ${process.env[DEBUG_ENV.claude] === "1" ? "on" : "off"}`);
+      console.log("");
+    }
+    printTopLevelHelp();
+    return;
+  }
+
+  printTopLevelHelp();
+  process.exit(1);
+}

package/src/cli/desktop-first-run.ts

@@ -0,0 +1,25 @@
+import {
+  ensureConfigFile,
+  type ConfigBootstrapResult,
+} from "../config";
+
+export type DesktopConfigBootstrapOutcome =
+  | { ran: false }
+  | { ran: true; result: ConfigBootstrapResult };
+
+/**
+ * Persist Remodex's own safe defaults for a genuinely fresh desktop home.
+ *
+ * Generic CLI reads remain side-effect free. The desktop shell, however, is an
+ * installed application and must have one persisted authority snapshot before
+ * unattended first-launch Codex convergence can be admitted. `ensureConfigFile`
+ * is no-replace: existing, malformed, or concurrently-created files survive
+ * byte-for-byte, including an explicit `clientIntegrations.codex = false`.
+ */
+export function bootstrapDesktopConfigIfNeeded(
+  env: Record<string, string | undefined> = process.env as Record<string, string | undefined>,
+  bootstrap: () => ConfigBootstrapResult = ensureConfigFile,
+): DesktopConfigBootstrapOutcome {
+  if (env.OCX_DESKTOP !== "1") return { ran: false };
+  return { ran: true, result: bootstrap() };
+}