@remits/remits-cli 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Remits
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# remits-cli
+
+Local CLI for rapid Remits component testing without push/sync cycles.
+
+## Install
+
+```bash
+npm install -g @remits/remits-cli
+```
+
+## Commands
+
+```bash
+remits-cli auth --base-url https://your-remits-host --account-id 123
+remits-cli install --skills
+remits-cli tools
+remits-cli tool --name "My Tool" --input '{"foo":"bar"}'
+remits-cli components stage
+remits-cli test run --test 45
+remits-cli test run --test "My New Test" --names "test case 1,test case 2"
+remits-cli components commit --message "sync passing changes"
+remits-cli token --path page/my-embeddable
+```
+
+## Skill Install
+
+```bash
+remits-cli install --skills
+```
+
+Optional:
+
+```bash
+remits-cli install --skills --target codex
+remits-cli install --skills --target claude
+remits-cli install --skills --target gemini
+remits-cli install --skills --overwrite true
+```
+
+## Notes
+
+- `components stage`/`push` reads from the current account repo working directory.
+- `components commit`/`sync` performs local git commit + push, triggers server sync, then fetch/pull locally.
+- `account-info.json` is used to infer `accountId` when not supplied.
+- Branch defaults to current local git branch.
+- Test activity is streamed from websocket `TestSuite` events and status is polled from `/cli/test`.
+- All `/cli/*` calls are logged to `./.remits-cli/sessions/<current-session>.jsonl`.
+- Tool responses are stored in `./.remits-cli/tool-responses/<callId>.json`.
+- Available tools are cached in `./.remits-cli/tools/tools.json`.

package/index.js

@@ -0,0 +1,979 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const http = require('http');
+const crypto = require('crypto');
+const { execSync } = require('child_process');
+const axios = require('axios');
+const openModule = require('open');
+const { Client } = require('@stomp/stompjs');
+const WebSocket = require('ws');
+
+Object.assign(global, { WebSocket });
+const openBrowser = (openModule && typeof openModule === 'function')
+  ? openModule
+  : (openModule && typeof openModule.default === 'function' ? openModule.default : null);
+
+//const DEFAULT_BASE_URL = process.env.REMITS_BASE_URL || 'http://localhost:8080';
+const DEFAULT_BASE_URL = process.env.REMITS_BASE_URL || 'https://remits-529558023549.us-east5.run.app';
+const SESSION_DIR = path.join(os.homedir(), '.remits-cli');
+const SESSION_FILE = path.join(SESSION_DIR, 'session.json');
+const SKILL_SOURCE_FILE = path.join(__dirname, 'skills', 'remits-cli', 'SKILL.md');
+const DEFAULT_DATA_MODE = 'test';
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) {
+      out._.push(arg);
+      continue;
+    }
+    const key = arg.slice(2);
+    const next = argv[i + 1];
+    if (!next || next.startsWith('--')) {
+      out[key] = true;
+    } else {
+      out[key] = next;
+      i += 1;
+    }
+  }
+  return out;
+}
+
+function ensureSessionDir() {
+  if (!fs.existsSync(SESSION_DIR)) {
+    fs.mkdirSync(SESSION_DIR, { recursive: true });
+  }
+}
+
+function readSession() {
+  if (!fs.existsSync(SESSION_FILE)) {
+    return null;
+  }
+  return JSON.parse(fs.readFileSync(SESSION_FILE, 'utf8'));
+}
+
+function writeSession(data) {
+  ensureSessionDir();
+  fs.writeFileSync(SESSION_FILE, JSON.stringify(data, null, 2));
+}
+
+function normalizeDataMode(value) {
+  const mode = String(value || DEFAULT_DATA_MODE).trim().toLowerCase();
+  return mode === 'prod' ? 'prod' : 'test';
+}
+
+function resolveDataMode(flags, session) {
+  if (flags && Object.prototype.hasOwnProperty.call(flags, 'data-mode')) {
+    return normalizeDataMode(flags['data-mode']);
+  }
+  if (flags && Object.prototype.hasOwnProperty.call(flags, 'dataMode')) {
+    return normalizeDataMode(flags.dataMode);
+  }
+  if (session && session.dataMode) {
+    return normalizeDataMode(session.dataMode);
+  }
+  return DEFAULT_DATA_MODE;
+}
+
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+function localStatePaths(cwd) {
+  const base = path.join(cwd, '.remits-cli');
+  return {
+    base,
+    toolsDir: path.join(base, 'tools'),
+    sessionsDir: path.join(base, 'sessions'),
+    toolResponsesDir: path.join(base, 'tool-responses'),
+    currentSessionFile: path.join(base, 'current-session.txt')
+  };
+}
+
+function ensureLocalState(cwd) {
+  const paths = localStatePaths(cwd);
+  ensureDir(paths.base);
+  ensureDir(paths.toolsDir);
+  ensureDir(paths.sessionsDir);
+  ensureDir(paths.toolResponsesDir);
+  return paths;
+}
+
+function currentLocalSessionName(cwd) {
+  const paths = ensureLocalState(cwd);
+  if (fs.existsSync(paths.currentSessionFile)) {
+    const existing = fs.readFileSync(paths.currentSessionFile, 'utf8').trim();
+    if (existing) {
+      return existing;
+    }
+  }
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const sessionName = 'session-' + timestamp + '-' + crypto.randomUUID().slice(0, 8);
+  fs.writeFileSync(paths.currentSessionFile, sessionName + '\n');
+  return sessionName;
+}
+
+function sessionJsonlFile(cwd) {
+  const paths = ensureLocalState(cwd);
+  return path.join(paths.sessionsDir, currentLocalSessionName(cwd) + '.jsonl');
+}
+
+function sanitizeForLog(value) {
+  if (value === null || value === undefined) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(sanitizeForLog);
+  }
+  if (typeof value !== 'object') {
+    return value;
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (k.toLowerCase() === 'token') {
+      out[k] = '[redacted]';
+    } else {
+      out[k] = sanitizeForLog(v);
+    }
+  }
+  return out;
+}
+
+function appendSessionLog(cwd, entry) {
+  const file = sessionJsonlFile(cwd);
+  fs.appendFileSync(file, JSON.stringify(entry) + '\n');
+  return file;
+}
+
+function writeToolResponseFile(cwd, callId, responsePayload) {
+  const paths = ensureLocalState(cwd);
+  const file = path.join(paths.toolResponsesDir, callId + '.json');
+  fs.writeFileSync(file, JSON.stringify(responsePayload, null, 2));
+  return file;
+}
+
+function normalizeName(name) {
+  return name.replace(/([a-z])([A-Z])/g, '$1 $2').replace(/\s+/g, ' ').trim();
+}
+
+function stableStringify(obj) {
+  if (obj === null || typeof obj !== 'object') {
+    return JSON.stringify(obj);
+  }
+  if (Array.isArray(obj)) {
+    return '[' + obj.map(stableStringify).join(',') + ']';
+  }
+  const keys = Object.keys(obj).sort();
+  return '{' + keys.map((k) => JSON.stringify(k) + ':' + stableStringify(obj[k])).join(',') + '}';
+}
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function currentBranch(cwd) {
+  try {
+    return execSync('git rev-parse --abbrev-ref HEAD', { cwd, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+  } catch (err) {
+    return 'main';
+  }
+}
+
+function shellQuote(value) {
+  return '\'' + String(value).replace(/'/g, '\'\"\'\"\'' ) + '\'';
+}
+
+function runGit(cwd, command) {
+  try {
+    return execSync(command, { cwd, stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
+  } catch (err) {
+    const stderr = err && err.stderr ? err.stderr.toString().trim() : '';
+    const stdout = err && err.stdout ? err.stdout.toString().trim() : '';
+    const details = stderr || stdout || err.message;
+    throw new Error('Git command failed: ' + command + (details ? ' :: ' + details : ''));
+  }
+}
+
+function loadAccountId(cwd) {
+  const file = path.join(cwd, 'account-info.json');
+  if (!fs.existsSync(file)) {
+    throw new Error('account-info.json not found in current directory');
+  }
+  const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+  return Number(data.id || data.accountId || (data.account && data.account.id));
+}
+
+function resolvePreferredAccountId(cwd, flags, session) {
+  try {
+    const fromRepo = loadAccountId(cwd);
+    if (Number.isFinite(fromRepo) && fromRepo > 0) {
+      return fromRepo;
+    }
+  } catch (_) {
+    // Fall back to explicit flags/session when not in an account repo.
+  }
+
+  const fallback = Number(flags['account-id'] || (session && session.accountId));
+  if (Number.isFinite(fallback) && fallback > 0) {
+    return fallback;
+  }
+
+  throw new Error('Unable to resolve account id. Use an account repo with account-info.json or pass --account-id.');
+}
+
+function collectComponents(cwd) {
+  const mapping = {
+    schemas: 'schema',
+    readers: 'reader',
+    actions: 'action',
+    embeddables: 'embeddable',
+    rules: 'rule',
+    templates: 'htmltemplate',
+    agents: 'utility',
+    tools: 'tool',
+    prompts: 'prompt',
+    tests: 'test'
+  };
+
+  const byKey = new Map();
+  for (const dirName of Object.keys(mapping)) {
+    const type = mapping[dirName];
+    const dir = path.join(cwd, 'components', dirName);
+    if (!fs.existsSync(dir)) {
+      continue;
+    }
+
+    const entries = fs.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isFile());
+    for (const entry of entries) {
+      const fileName = entry.name;
+      const match = fileName.match(/^(.+?)_(.+)\.([^.]+)$/);
+      if (!match) {
+        continue;
+      }
+      const prefix = match[1];
+      const rawName = match[2];
+      const ext = match[3].toLowerCase();
+      const id = /^\d+$/.test(prefix) ? Number(prefix) : null;
+      const name = prefix.startsWith('new') || !id ? normalizeName(rawName) : normalizeName(rawName);
+      const key = type + ':' + (id ? 'id:' + id : 'name:' + name.toLowerCase());
+
+      if (!byKey.has(key)) {
+        byKey.set(key, { type, id, name });
+      }
+      const component = byKey.get(key);
+      const filePath = path.join(dir, fileName);
+      const content = fs.readFileSync(filePath, 'utf8');
+
+      if (ext === 'groovy' || ext === 'md') {
+        component.source = content;
+      } else if (type === 'embeddable' && ext === 'html') {
+        component.html = content;
+      } else if (type === 'embeddable' && ext === 'js') {
+        component.javascript = content;
+      } else if (type === 'htmltemplate' && ext === 'html') {
+        component.html = content;
+      } else if (type === 'htmltemplate' && ext === 'json') {
+        component.previewData = content;
+      } else if (type === 'tool' && ext === 'json') {
+        component.inputSchema = content;
+      } else if (type === 'schema' && ext === 'json') {
+        component.schema = content;
+      }
+    }
+  }
+
+  const components = [];
+  for (const component of byKey.values()) {
+    const fingerprint = {
+      type: component.type,
+      id: component.id || null,
+      name: component.name || null,
+      source: component.source || null,
+      html: component.html || null,
+      javascript: component.javascript || null,
+      previewData: component.previewData || null,
+      inputSchema: component.inputSchema || null,
+      schema: component.schema || null
+    };
+    component.hash = sha256(stableStringify(fingerprint));
+    components.push(component);
+  }
+
+  return components;
+}
+
+function buildAxios(baseUrl, token) {
+  const headers = token ? { Authorization: 'Bearer ' + token } : {};
+  return axios.create({ baseURL: baseUrl, timeout: 60000, headers });
+}
+
+function saveToolsSnapshot(cwd, data) {
+  const paths = ensureLocalState(cwd);
+  const file = path.join(paths.toolsDir, 'tools.json');
+  fs.writeFileSync(file, JSON.stringify(data, null, 2));
+  return file;
+}
+
+async function loggedPost(api, cwd, endpoint, payload, options = {}) {
+  const requestId = options.requestId || crypto.randomUUID();
+  const started = Date.now();
+  let responseData = null;
+  let error = null;
+  let responseFile = null;
+
+  try {
+    responseData = await api.post(endpoint, payload).then((r) => r.data);
+    if (options.toolResponseFile) {
+      const callId = options.toolCallId || (responseData && responseData.callId) || requestId;
+      responseFile = writeToolResponseFile(cwd, callId, responseData);
+    }
+    return { data: responseData, requestId, responseFile };
+  } catch (err) {
+    responseData = err && err.response ? err.response.data : null;
+    error = err;
+    throw err;
+  } finally {
+    const status = error ? 'error' : 'success';
+    const responseForLog = responseFile
+      ? { responseFile, note: 'Tool response stored externally' }
+      : sanitizeForLog(responseData);
+    appendSessionLog(cwd, {
+      ts: new Date().toISOString(),
+      requestId,
+      endpoint,
+      method: 'POST',
+      status,
+      durationMs: Date.now() - started,
+      request: sanitizeForLog(payload),
+      response: responseForLog,
+      error: error ? String(error.message || error) : null
+    });
+  }
+}
+
+async function loggedGet(api, cwd, endpoint, params = {}) {
+  const requestId = crypto.randomUUID();
+  const started = Date.now();
+  let responseData = null;
+  let error = null;
+  try {
+    responseData = await api.get(endpoint, { params }).then((r) => r.data);
+    return { data: responseData, requestId };
+  } catch (err) {
+    responseData = err && err.response ? err.response.data : null;
+    error = err;
+    throw err;
+  } finally {
+    appendSessionLog(cwd, {
+      ts: new Date().toISOString(),
+      requestId,
+      endpoint,
+      method: 'GET',
+      status: error ? 'error' : 'success',
+      durationMs: Date.now() - started,
+      request: sanitizeForLog(params),
+      response: sanitizeForLog(responseData),
+      error: error ? String(error.message || error) : null
+    });
+  }
+}
+
+function resolveSkillTargets(target) {
+  const value = String(target || 'all').toLowerCase();
+  const home = os.homedir();
+  const targets = {
+    codex: path.join(home, '.codex', 'skills', 'remits-cli', 'SKILL.md'),
+    claude: path.join(home, '.claude', 'skills', 'remits-cli', 'SKILL.md'),
+    gemini: path.join(home, '.gemini', 'skills', 'remits-cli.md')
+  };
+
+  if (value === 'all') {
+    return Object.entries(targets);
+  }
+  if (!targets[value]) {
+    throw new Error('Unknown --target value: ' + target + ' (expected codex|claude|gemini|all)');
+  }
+  return [[value, targets[value]]];
+}
+
+async function installSkillsCommand(flags) {
+  if (!flags.skills) {
+    throw new Error('Missing --skills flag. Usage: remits-cli install --skills');
+  }
+  if (!fs.existsSync(SKILL_SOURCE_FILE)) {
+    throw new Error('Skill source file not found: ' + SKILL_SOURCE_FILE);
+  }
+
+  const overwrite = flags.overwrite === true || flags.overwrite === 'true';
+  const targets = resolveSkillTargets(flags.target || 'all');
+  const sourceBody = fs.readFileSync(SKILL_SOURCE_FILE, 'utf8');
+  const installed = [];
+  const skipped = [];
+
+  for (const [agent, targetPath] of targets) {
+    ensureDir(path.dirname(targetPath));
+    if (fs.existsSync(targetPath) && !overwrite) {
+      skipped.push({ agent, path: targetPath, reason: 'already exists (use --overwrite true)' });
+      continue;
+    }
+    fs.writeFileSync(targetPath, sourceBody);
+    installed.push({ agent, path: targetPath });
+  }
+
+  console.log('Skill installation complete.');
+  if (installed.length) {
+    console.log('Installed:');
+    for (const item of installed) {
+      console.log(' -', item.agent + ':', item.path);
+    }
+  }
+  if (skipped.length) {
+    console.log('Skipped:');
+    for (const item of skipped) {
+      console.log(' -', item.agent + ':', item.path, '(' + item.reason + ')');
+    }
+  }
+}
+
+async function authCommand(flags) {
+  const cwd = process.cwd();
+  ensureLocalState(cwd);
+  const existingSession = readSession() || {};
+  const dataMode = resolveDataMode(flags, existingSession);
+  const baseUrl = flags['base-url'] || DEFAULT_BASE_URL;
+  const accountId = flags['account-id'] || resolvePreferredAccountId(cwd, flags, {});
+  const port = Number(flags.port || 8765);
+  const state = crypto.randomUUID();
+  const redirectUri = 'http://localhost:' + port + '/callback';
+
+  const callbackPromise = new Promise((resolve, reject) => {
+    const server = http.createServer((req, res) => {
+      const reqUrl = new URL(req.url, 'http://localhost:' + port);
+      if (reqUrl.pathname !== '/callback') {
+        res.statusCode = 404;
+        res.end('Not found');
+        return;
+      }
+
+      const payload = {
+        token: reqUrl.searchParams.get('token'),
+        state: reqUrl.searchParams.get('state'),
+        userId: reqUrl.searchParams.get('userId'),
+        userUuid: reqUrl.searchParams.get('userUuid')
+      };
+
+      res.statusCode = 200;
+      res.setHeader('Content-Type', 'text/html');
+      res.end('<html><body><h2>Remits CLI Auth Complete</h2><p>You can close this tab.</p></body></html>');
+      server.close();
+      resolve(payload);
+    });
+
+    server.on('error', reject);
+    server.listen(port, '127.0.0.1');
+  });
+
+  const params = new URLSearchParams();
+  params.set('redirect_uri', redirectUri);
+  params.set('state', state);
+  if (accountId) {
+    params.set('accountId', String(accountId));
+  }
+  params.set('dataMode', dataMode);
+
+  const loginUrl = baseUrl.replace(/\/$/, '') + '/cli/auth?' + params.toString();
+  console.log('Opening browser for auth:', loginUrl);
+  if (openBrowser) {
+    await openBrowser(loginUrl);
+  } else {
+    console.log('Browser auto-open is unavailable. Open this URL manually:', loginUrl);
+  }
+
+  const timeoutPromise = new Promise((_, reject) =>
+    setTimeout(() => reject(new Error('Auth callback timeout (120s)')), 120000)
+  );
+  const result = await Promise.race([callbackPromise, timeoutPromise]);
+
+  if (result.state !== state) {
+    throw new Error('Invalid auth callback state');
+  }
+
+  const api = buildAxios(baseUrl, result.token);
+  const me = await loggedGet(api, cwd, '/cli/auth', {
+    accountId: accountId || undefined,
+    dataMode
+  }).then((r) => r.data);
+
+  const session = {
+    ...existingSession,
+    baseUrl,
+    token: result.token,
+    accountId: me.account ? me.account.id : Number(accountId),
+    user: me.user,
+    websocketTopic: me.websocketTopic,
+    dataMode: normalizeDataMode(me.dataMode || dataMode),
+    updatedAt: new Date().toISOString()
+  };
+
+  writeSession(session);
+  console.log('Authenticated as user', session.user ? session.user.id : 'unknown', 'for account', session.accountId);
+  console.log('Data mode:', session.dataMode);
+
+  try {
+    const toolsData = await loggedPost(api, cwd, '/cli/tools', {
+      token: session.token,
+      accountId: session.accountId,
+      dataMode: session.dataMode
+    }).then((r) => r.data);
+    if (toolsData && toolsData.success) {
+      const toolsFile = saveToolsSnapshot(cwd, {
+        accountId: session.accountId,
+        dataMode: toolsData.dataMode || session.dataMode,
+        fetchedAt: new Date().toISOString(),
+        tools: toolsData.tools || []
+      });
+      console.log('Tools cached at:', toolsFile);
+    }
+  } catch (err) {
+    console.log('Warning: failed to refresh tools after auth:', err.message);
+  }
+}
+
+async function pushComponentsCommand(flags) {
+  const cwd = process.cwd();
+  ensureLocalState(cwd);
+  const session = readSession();
+  if (!session || !session.token) {
+    throw new Error('Not authenticated. Run: remits-cli auth');
+  }
+
+  const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const accountId = resolvePreferredAccountId(cwd, flags, session);
+  const branchName = flags.branch || currentBranch(cwd);
+  const dataMode = resolveDataMode(flags, session);
+  const mode = String(flags.mode || 'stage').toLowerCase();
+  const components = collectComponents(cwd);
+
+  const api = buildAxios(baseUrl, session.token);
+  const response = await loggedPost(api, cwd, '/cli/components', {
+    token: session.token,
+    accountId,
+    branchName,
+    dataMode,
+    mode,
+    components
+  }).then((r) => r.data);
+
+  console.log('Data mode:', response.dataMode || dataMode);
+  console.log('Mode:', response.mode || mode);
+  console.log('Components sync:', JSON.stringify(response, null, 2));
+}
+
+async function commitComponentsCommand(flags) {
+  const cwd = process.cwd();
+  ensureLocalState(cwd);
+  const session = readSession();
+  if (!session || !session.token) {
+    throw new Error('Not authenticated. Run: remits-cli auth');
+  }
+
+  const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const accountId = resolvePreferredAccountId(cwd, flags, session);
+  const branchName = flags.branch || currentBranch(cwd);
+  const dataMode = resolveDataMode(flags, session);
+  const commitMessage = String(flags.message || ('remits-cli commit sync ' + new Date().toISOString()));
+  const allowEmpty = flags['allow-empty'] === true || flags['allow-empty'] === 'true';
+  const skipGit = flags['skip-git'] === true || flags['skip-git'] === 'true';
+  const components = collectComponents(cwd);
+
+  if (!skipGit) {
+    const status = runGit(cwd, 'git status --porcelain');
+    if (status || allowEmpty) {
+      runGit(cwd, 'git add -A');
+      const commitCmd = 'git commit ' + (allowEmpty ? '--allow-empty ' : '') + '-m ' + shellQuote(commitMessage);
+      try {
+        runGit(cwd, commitCmd);
+      } catch (err) {
+        if (!allowEmpty && String(err.message || '').toLowerCase().includes('nothing to commit')) {
+          console.log('No staged changes to commit.');
+        } else {
+          throw err;
+        }
+      }
+    } else {
+      console.log('No local changes detected; skipping local git commit.');
+    }
+
+    try {
+      runGit(cwd, 'git push origin ' + shellQuote(branchName));
+    } catch (err) {
+      runGit(cwd, 'git push --set-upstream origin ' + shellQuote(branchName));
+    }
+  }
+
+  const api = buildAxios(baseUrl, session.token);
+  const response = await loggedPost(api, cwd, '/cli/components', {
+    token: session.token,
+    accountId,
+    branchName,
+    dataMode,
+    mode: 'commit',
+    components
+  }).then((r) => r.data);
+
+  if (!response.success) {
+    throw new Error(response.message || 'Commit sync failed');
+  }
+
+  if (!skipGit) {
+    runGit(cwd, 'git fetch origin ' + shellQuote(branchName));
+    runGit(cwd, 'git pull --ff-only origin ' + shellQuote(branchName));
+  }
+
+  console.log('Data mode:', response.dataMode || dataMode);
+  console.log('Mode:', response.mode || 'commit');
+  console.log('Components commit/sync:', JSON.stringify(response, null, 2));
+}
+
+function webSocketUrl(baseUrl) {
+  const u = new URL(baseUrl);
+  const wsProtocol = u.protocol === 'https:' ? 'wss:' : 'ws:';
+  return wsProtocol + '//' + u.host + '/stomp';
+}
+
+async function waitForStatus(api, cwd, accountId, branchName, taskId, token, dataMode) {
+  while (true) {
+    const status = await loggedPost(api, cwd, '/cli/test', {
+      token,
+      command: 'status',
+      accountId,
+      branchName,
+      taskId,
+      dataMode
+    }).then((r) => r.data);
+
+    if (status.status === 'completed' || status.status === 'failed') {
+      return status;
+    }
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+}
+
+function watchWebsocket(baseUrl, topicId, taskId) {
+  const client = new Client({
+    brokerURL: webSocketUrl(baseUrl),
+    reconnectDelay: 3000,
+    heartbeatIncoming: 10000,
+    heartbeatOutgoing: 10000,
+    debug: () => {}
+  });
+
+  client.onConnect = () => {
+    client.subscribe('/topic/messages/' + topicId, (msg) => {
+      try {
+        const data = JSON.parse(msg.body);
+        if (data.type === 'TestSuite') {
+          const payload = data.payload || {};
+          if (payload.tests || payload.name || payload.total != null) {
+            console.log('[ws][TestSuite]', JSON.stringify(payload));
+          }
+        }
+      } catch (err) {
+        console.error('[ws] parse error:', err.message);
+      }
+    });
+  };
+
+  client.activate();
+  return () => {
+    client.deactivate();
+  };
+}
+
+async function testCommand(flags) {
+  const cwd = process.cwd();
+  ensureLocalState(cwd);
+  const session = readSession();
+  if (!session || !session.token) {
+    throw new Error('Not authenticated. Run: remits-cli auth');
+  }
+
+  const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const accountId = resolvePreferredAccountId(cwd, flags, session);
+  const branchName = flags.branch || currentBranch(cwd);
+  const dataMode = resolveDataMode(flags, session);
+  const testRef = flags.test || flags['test-id'] || flags.name;
+
+  if (!testRef) {
+    throw new Error('Missing --test <id-or-name>');
+  }
+
+  const names = flags.names ? String(flags.names).split(',').map((s) => s.trim()).filter(Boolean) : [];
+
+  const api = buildAxios(baseUrl, session.token);
+  const start = await loggedPost(api, cwd, '/cli/test', {
+    token: session.token,
+    accountId,
+    branchName,
+    dataMode,
+    testId: /^\d+$/.test(String(testRef)) ? Number(testRef) : undefined,
+    testName: /^\d+$/.test(String(testRef)) ? undefined : String(testRef),
+    tests: names
+  }).then((r) => r.data);
+
+  if (!start.success) {
+    throw new Error('Failed to start test run');
+  }
+
+  console.log('Test run started:', start.taskId);
+
+  let stopWs = null;
+  if (flags.watch !== 'false') {
+    const topic = session.websocketTopic || start.websocketTopic || (session.user && String(session.user.uuid || '').replace(/-/g, ''));
+    if (topic) {
+      stopWs = watchWebsocket(baseUrl, topic, start.taskId);
+    }
+  }
+
+  const status = await waitForStatus(api, cwd, accountId, branchName, start.taskId, session.token, dataMode);
+  if (stopWs) {
+    stopWs();
+  }
+
+  console.log('Final status:', JSON.stringify(status, null, 2));
+  if (status.status !== 'completed') {
+    process.exitCode = 1;
+  }
+}
+
+async function tokenCommand(flags) {
+  const cwd = process.cwd();
+  ensureLocalState(cwd);
+  const session = readSession();
+  if (!session || !session.token) {
+    throw new Error('Not authenticated. Run: remits-cli auth');
+  }
+
+  const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const accountId = resolvePreferredAccountId(cwd, flags, session);
+  const branchName = flags.branch || currentBranch(cwd);
+  const dataMode = resolveDataMode(flags, session);
+
+  const api = buildAxios(baseUrl, session.token);
+  const data = await loggedPost(api, cwd, '/cli/token', {
+    token: session.token,
+    accountId,
+    branchName,
+    dataMode
+  }).then((r) => r.data);
+
+  if (!data.success) {
+    throw new Error('Failed to generate token key');
+  }
+
+  const base = baseUrl.replace(/\/$/, '');
+  const embeddablePath = flags.path || flags['embeddable-path'];
+  const embeddableUrl = embeddablePath
+    ? (base + '/s/' + data.tokenKey + '/' + String(embeddablePath).replace(/^\/+/, ''))
+    : null;
+
+  const output = {
+    success: true,
+    tokenKey: data.tokenKey,
+    accountId: data.accountId,
+    branchName: data.branchName,
+    dataMode: data.dataMode || dataMode,
+    shortBasePath: data.shortBasePath,
+    embeddableUrl
+  };
+
+  console.log(JSON.stringify(output, null, 2));
+}
+
+async function toolsCommand(flags) {
+  const cwd = process.cwd();
+  ensureLocalState(cwd);
+  const session = readSession();
+  if (!session || !session.token) {
+    throw new Error('Not authenticated. Run: remits-cli auth');
+  }
+
+  const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const accountId = resolvePreferredAccountId(cwd, flags, session);
+  const dataMode = resolveDataMode(flags, session);
+  const api = buildAxios(baseUrl, session.token);
+
+  const data = await loggedPost(api, cwd, '/cli/tools', {
+    token: session.token,
+    accountId,
+    dataMode
+  }).then((r) => r.data);
+
+  if (!data.success) {
+    throw new Error('Failed to fetch tools');
+  }
+
+  const toolsFile = saveToolsSnapshot(cwd, {
+    accountId,
+    dataMode: data.dataMode || dataMode,
+    fetchedAt: new Date().toISOString(),
+    tools: data.tools || []
+  });
+
+  console.log('Tools refreshed.');
+  console.log('Data mode:', data.dataMode || dataMode);
+  console.log('Tools file:', toolsFile);
+  console.log('Tool count:', (data.tools || []).length);
+}
+
+function parseToolInput(flags) {
+  if (flags['input-file']) {
+    const file = path.resolve(process.cwd(), String(flags['input-file']));
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  }
+  if (flags.input) {
+    return JSON.parse(String(flags.input));
+  }
+  return {};
+}
+
+async function toolCommand(flags) {
+  const cwd = process.cwd();
+  ensureLocalState(cwd);
+  const session = readSession();
+  if (!session || !session.token) {
+    throw new Error('Not authenticated. Run: remits-cli auth');
+  }
+
+  const toolName = flags.name || flags.tool;
+  if (!toolName) {
+    throw new Error('Missing --name <toolName>');
+  }
+
+  const input = parseToolInput(flags);
+  const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const accountId = resolvePreferredAccountId(cwd, flags, session);
+  const branchName = flags.branch || currentBranch(cwd);
+  const dataMode = resolveDataMode(flags, session);
+  const callId = crypto.randomUUID();
+  const api = buildAxios(baseUrl, session.token);
+
+  const response = await loggedPost(api, cwd, '/cli/tool', {
+    token: session.token,
+    accountId,
+    branchName,
+    dataMode,
+    name: String(toolName),
+    input,
+    callId
+  }, { toolResponseFile: true, toolCallId: callId });
+
+  const data = response.data;
+  if (!data.success) {
+    throw new Error(data.message || 'Tool execution failed');
+  }
+
+  console.log('Tool call succeeded.');
+  console.log('Call ID:', callId);
+  console.log('Data mode:', dataMode);
+  console.log('Session log:', sessionJsonlFile(cwd));
+  console.log('Tool response file:', response.responseFile);
+}
+
+async function dataModeCommand(flags, subcommand) {
+  const session = readSession() || {};
+  const nextMode = flags.mode || flags.value || flags._[2];
+  if (subcommand === 'set') {
+    if (!nextMode) {
+      throw new Error('Missing mode. Use: remits-cli data-mode set test|prod');
+    }
+    const dataMode = normalizeDataMode(nextMode);
+    writeSession({
+      ...session,
+      dataMode,
+      updatedAt: new Date().toISOString()
+    });
+    console.log('Data mode set to:', dataMode);
+    return;
+  }
+
+  const currentMode = resolveDataMode(flags, session);
+  console.log(JSON.stringify({ dataMode: currentMode }, null, 2));
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const [command, subcommand] = args._;
+
+  if (!command || command === 'help' || command === '--help') {
+    console.log('Usage: remits-cli <command>');
+    console.log('  remits-cli auth [--base-url URL] [--account-id ID] [--port 8765] [--data-mode test|prod]');
+    console.log('  remits-cli data-mode [set test|prod]');
+    console.log('  remits-cli install --skills [--target codex|claude|gemini|all] [--overwrite true]');
+    console.log('  remits-cli tools [--base-url URL] [--account-id ID] [--data-mode test|prod]');
+    console.log('  remits-cli tool --name <toolName> [--input \"{...}\"|--input-file file.json] [--data-mode test|prod]');
+    console.log('  remits-cli components push|stage [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod]');
+    console.log('  remits-cli components commit|sync [--message \"msg\"] [--allow-empty true|false] [--skip-git true|false] [--branch BRANCH] [--data-mode test|prod]');
+    console.log('  remits-cli test run --test <id|name> [--names name1,name2] [--watch true|false] [--data-mode test|prod]');
+    console.log('  remits-cli token [--branch BRANCH] [--path embeddable/path] [--data-mode test|prod]');
+    process.exit(0);
+  }
+
+  if (command === 'auth') {
+    await authCommand(args);
+    return;
+  }
+
+  if (command === 'components' && (subcommand === 'push' || subcommand === 'stage')) {
+    await pushComponentsCommand(args);
+    return;
+  }
+
+  if (command === 'components' && (subcommand === 'commit' || subcommand === 'sync')) {
+    await commitComponentsCommand(args);
+    return;
+  }
+
+  if (command === 'data-mode' || command === 'datamode' || command === 'data-model' || command === 'datamodel') {
+    await dataModeCommand(args, subcommand);
+    return;
+  }
+
+  if (command === 'install') {
+    await installSkillsCommand(args);
+    return;
+  }
+
+  if (command === 'test' && subcommand === 'run') {
+    await testCommand(args);
+    return;
+  }
+
+  if (command === 'token') {
+    await tokenCommand(args);
+    return;
+  }
+
+  if (command === 'tools') {
+    await toolsCommand(args);
+    return;
+  }
+
+  if (command === 'tool') {
+    await toolCommand(args);
+    return;
+  }
+
+  throw new Error('Unknown command: ' + args._.join(' '));
+}
+
+main().catch((err) => {
+  console.error('remits-cli error:', err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@remits/remits-cli",
+  "version": "0.1.1",
+  "description": "Local CLI for auth, component sync, and live test execution against Remits",
+  "license": "MIT",
+  "private": false,
+  "bin": {
+    "remits-cli": "./index.js"
+  },
+  "main": "index.js",
+  "type": "commonjs",
+  "files": [
+    "index.js",
+    "README.md",
+    "skills/remits-cli/SKILL.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "remits",
+    "cli",
+    "grails",
+    "testing",
+    "automation"
+  ],
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "@stomp/stompjs": "^7.2.0",
+    "axios": "^1.8.4",
+    "open": "^10.1.0",
+    "ws": "^8.18.1"
+  }
+}

package/skills/remits-cli/SKILL.md

@@ -0,0 +1,271 @@
+# remits-cli
+
+Use this skill when working in a local Remits account repository and you need server-backed validation for in-flight component changes without full git push/sync cycles.
+
+## What remits-cli Does
+
+`remits-cli` is the primary development and support tool for Remits account repositories. It enables two workflows:
+
+1. **Development workflow** (test mode) - Build and iterate on components with isolated test data. Stage local changes, run tests, and commit once passing.
+2. **Production support workflow** (prod mode) - Investigate production data, run tools against live data, and debug issues on real accounts.
+
+Every CLI command and every server response includes `dataMode` so you always know which data context you are operating in.
+
+## Preconditions
+
+- You are in a Remits account repo root that contains `account-info.json` and `components/`.
+- `remits-cli` is installed and available in PATH.
+- User has valid access to the Remits platform account.
+
+## Authentication
+
+Authenticate once per session. Opens a browser for OAuth, then stores the session token at `~/.remits-cli/session.json`.
+
+```bash
+remits-cli auth --base-url <REMITS_URL> --account-id <ACCOUNT_ID>
+```
+
+- `--base-url` defaults to remits platform endpoint. Exclude this unless instructed otherwise by the user.
+- `--account-id` is auto-resolved from `account-info.json` if present
+- Auth also caches available tools automatically
+
+If any command returns a 401 error, re-run `remits-cli auth` to get a fresh token.
+
+## Data Mode (test vs prod)
+
+Data mode controls whether operations use isolated test data or production data. **Default is `test`.**
+
+```bash
+remits-cli data-mode                  # Show current mode
+remits-cli data-mode set test         # Persist test mode
+remits-cli data-mode set prod         # Persist prod mode
+```
+
+One-off override on any command (does NOT change the persisted mode):
+
+```bash
+remits-cli test run --test 3 --data-mode test
+remits-cli tool --name "System Logs" --input '{}' --data-mode prod
+```
+
+**Rules:**
+- Use `test` mode for development: building components, running tests, staging changes.
+- Use `prod` mode for support: investigating production data, querying logs, viewing records.
+- Always check the `dataMode` field in command output to confirm which context you are in.
+
+## Development Fast Loop
+
+This is the core iteration cycle for building and modifying components:
+
+```bash
+# 1. Authenticate (once per session)
+remits-cli auth --base-url <REMITS_URL> --account-id <ACCOUNT_ID>
+
+# 2. Confirm data mode is test
+remits-cli data-mode
+
+# 3. Make local edits to component files under components/
+
+# 4. Stage local changes to the platform's in-flight cache
+remits-cli components stage
+
+# 5. Run tests against the staged snapshot
+remits-cli test run --test <TEST_ID_OR_NAME>
+
+# 6. If tests fail: fix code, re-stage, re-test (repeat 3-5)
+
+# 7. Once tests pass: commit and sync to platform
+remits-cli components commit --message "description of changes"
+```
+
+### Staging Components
+
+```bash
+remits-cli components stage
+remits-cli components push          # alias for stage
+```
+
+- Scans `components/` directory and uploads all component source to the platform's branch cache.
+- Uses SHA256 hash-based change detection: only modified components are re-uploaded on subsequent calls.
+- Response shows `updated` count (changed) and `unchanged` count (skipped).
+- **Always stage after local edits and before running tests.** Tests run against the staged snapshot, not the local filesystem.
+
+### Running Tests
+
+```bash
+remits-cli test run --test <ID_OR_NAME>
+remits-cli test run --test "Example Tests"
+remits-cli test run --test 3
+```
+
+Run specific test cases within a test suite:
+
+```bash
+remits-cli test run --test "Example Tests" --names "test case 1,test case 2"
+```
+
+**Output:**
+- Real-time WebSocket streaming of individual test results as they complete.
+- Final status JSON with `passed`, `failed`, `total` counts and per-test details.
+- Failed tests include the `error` message and assertion expression.
+- Exit code 1 if any test fails.
+
+Disable WebSocket streaming (polling only):
+
+```bash
+remits-cli test run --test 3 --watch false
+```
+
+### Committing to Platform
+
+```bash
+remits-cli components commit --message "feature complete"
+remits-cli components sync          # alias for commit
+```
+
+This performs three steps:
+1. **Git commit + push**: Stages all changes (`git add -A`), commits with the provided message, pushes to origin.
+2. **Platform sync**: Sends components to the platform with `mode: commit`, triggering a full sync.
+3. **Git pull**: Pulls back any platform-generated changes (e.g., updated `account-info.json`).
+
+Options:
+
+```bash
+--message "commit msg"         # Custom commit message (default: auto-generated with timestamp)
+--skip-git true                # Skip git operations, only sync to platform
+--allow-empty true             # Allow empty git commits
+--branch <name>                # Override branch (default: current git branch)
+```
+
+## Embeddable Testing with Playwright
+
+Generate a branch-scoped short token for accessing embeddables in the browser:
+
+```bash
+remits-cli token
+remits-cli token --path embeddable/index/41
+```
+
+The response includes:
+- `tokenKey` - Short token for URL construction
+- `embeddableUrl` - Full URL ready to open (when `--path` is provided)
+- `dataMode` - Confirms test or prod context
+
+**URL pattern:** `<REMITS_URL>/s/<tokenKey>/embeddable/index/<embeddableId>`
+
+### testMode Verification
+
+When using a CLI-generated token in test mode, the platform injects `testMode` metadata in two places:
+
+1. **In the HTML** - A hidden `remits-session-info` element:
+   ```
+   TestMode: { "cliUserId": 3, "accountId": 1, "branchName": "main", "dataMode": "test" }
+   ```
+
+2. **In embeddable action JSON responses** - A `testMode` field alongside `dataMode`:
+   ```json
+   { "testMode": "{...}", "dataMode": "test", ... }
+   ```
+
+Use Playwright to verify testMode is present when testing embeddables:
+
+```bash
+# Generate token
+remits-cli token --path embeddable/index/<ID>
+
+# Open in Playwright
+playwright-cli open --headed "<embeddableUrl from above>"
+
+# Check snapshot for testMode in remits-session-info element
+playwright-cli snapshot
+
+# Or extract programmatically
+playwright-cli eval "() => document.querySelector('.remits-session-info').textContent"
+```
+
+## Tool Calling
+
+Tools are server-side operations available for the current account.
+
+### Refresh and List Tools
+
+```bash
+remits-cli tools
+```
+
+Fetches available tools and caches them at `./.remits-cli/tools/tools.json`.
+
+### Execute a Tool
+
+```bash
+remits-cli tool --name "<Tool Name>" --input '{"key": "value"}'
+remits-cli tool --name "<Tool Name>" --input-file ./payload.json
+```
+
+- Response is saved to `./.remits-cli/tool-responses/<callId>.json`.
+- The response file path is printed after each call.
+- All calls are logged to the session JSONL file.
+
+### Tool Usage Guidance
+
+For production investigations, use explicit `--data-mode prod`:
+
+```bash
+remits-cli tool --name "system_logs" --input '{"node":"remitsAdmin-east5"}' --data-mode prod
+```
+
+Preferred tools for investigations:
+- `system_logs` - Server-side log correlation
+- `object_activity` - Document activity history
+- `record_view` - View document data
+
+Do not use account/component inspection tools for local repo context - component and account files are already in the working directory.
+
+## Local State Files
+
+The CLI maintains state in two locations:
+
+**Global session** (`~/.remits-cli/`):
+- `session.json` - Auth token, accountId, user, dataMode, websocketTopic
+
+**Per-repo state** (`./.remits-cli/` in the account repo):
+- `tools/tools.json` - Cached tool definitions with accountId, dataMode, tool list
+- `sessions/<session-name>.jsonl` - Request/response log (all `/cli/*` API calls, tokens redacted)
+- `tool-responses/<callId>.json` - Individual tool execution results
+- `current-session.txt` - Current session identifier
+
+## Command Reference
+
+```
+remits-cli auth [--base-url URL] [--account-id ID] [--port 8765] [--data-mode test|prod]
+remits-cli data-mode [set test|prod]
+remits-cli components stage|push [--branch <name>] [--data-mode test|prod]
+remits-cli components commit|sync [--message "msg"] [--allow-empty true|false] [--skip-git true|false] [--branch <name>] [--data-mode test|prod]
+remits-cli test run --test <id|name> [--names "a,b"] [--watch true|false] [--data-mode test|prod]
+remits-cli token [--branch <name>] [--path <embeddablePathOrId>] [--data-mode test|prod]
+remits-cli tools [--data-mode test|prod]
+remits-cli tool --name <toolName> [--input "{...}" | --input-file file.json] [--data-mode test|prod]
+remits-cli install --skills [--target codex|claude|gemini|all] [--overwrite true]
+```
+
+## Efficiency Rules
+
+- **Always stage before test.** `components stage` then `test run` after any local edit.
+- **Target specific tests.** Use `--names` to run individual test cases for faster feedback.
+- **Keep the same branch.** Stay on one branch to preserve a coherent staged snapshot.
+- **Commit only after tests pass.** `components commit` performs git + platform sync together.
+- **Re-auth on 401.** Session tokens expire on server restart or timeout.
+- **Refresh tools when they change.** Run `remits-cli tools` after tool definitions are updated.
+- **Check dataMode on every response.** Confirm you are in the intended data context before acting on results.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `Not authenticated` or 401 error | Run `remits-cli auth` |
+| `account-info.json not found` | Run from the account repo root directory |
+| Test not found | Verify `--test` value matches an ID or exact name from `account-info.json` TestSuites |
+| Wrong branch behavior | Pass `--branch <branch>` explicitly |
+| Stage shows 0 updated | No local changes detected since last stage (hash-based dedup) |
+| Tool response missing | Check `./.remits-cli/tool-responses/` for the callId file |
+| Need to see all API calls | Read `./.remits-cli/sessions/<session>.jsonl` |