@rfany/rf 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 spoj
+
+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

@@ -1,3 +1,8 @@
-# Temporary Holding Version
+# @rfany/rf
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+People's command line for [rollforward](https://github.com/spoj/rollforward): what its page does, from a shell or a desktop agent, as you.
+
+    npm i -g @rfany/rf
+    rf login https://rollforward.example.com TOKEN
+
+Make the token on the page, under Tokens. `rf` alone lists the commands.

package/package.json

@@ -1,6 +1,13 @@
 {
   "name": "@rfany/rf",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "rollforward's command line for people: what its page does, from a shell or a desktop agent, as you",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/spoj/rollforward.git", "directory": "cli" },
+  "type": "module",
+  "bin": { "rf": "rf.mjs" },
+  "files": ["rf.mjs"],
+  "engines": { "node": ">=22" },
+  "scripts": { "prepack": "node --no-warnings build.mjs" },
+  "publishConfig": { "access": "public" }
+}

package/rf.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+// rf for people: what the page does, from a shell or a desktop agent, as you, with a personal token made on the page (Tokens).
+// Published to npm as @rfany/rf, from cli/. PATH is workspace/series/label, as `rf ls` prints it.
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+
+const USAGE = `rf login URL TOKEN
+rf ls
+rf pull DIR                       a read-only mirror of what you can see, in the layout agents see
+rf comment PATH TEXT [--item ID] [--ref REF] [--thread T] [--wait]   a new thread, or a reply in T, as to an agent's ask
+rf upload PATH FILE [--onto ITEM] [--output]
+rf wake PATH AT REASON [--label LABEL]   AT now, +<n>m|h|d or a date; PATH an open instance, or a series with LABEL
+rf agents [WORKSPACE] [--set FILE|-]     the company's AGENTS.md, or a workspace's; setting the company's is for admins
+rf skills
+rf websites
+
+Publishers and admins:
+rf skill push DIR                 DIR/SKILL.md and the rest become the newest version of the skill named DIR's name, live at once
+rf skill versions ID
+rf skill rollback ID N            pushes version N again, as the newest
+
+Admins:
+rf users
+rf user add EMAIL [admin|publisher] | role EMAIL admin|publisher|user | disable EMAIL | enable EMAIL | signout EMAIL | remove EMAIL
+rf website set ID URL [--name NAME] [--hosts HOST,...]   a website people sign in to at URL, and the other hosts its pages need,
+                                  such as sso.example.com or *.example.com; a run's browser on it reaches only those
+rf website remove ID`;
+
+const config = join(homedir(), '.config', 'rollforward.json');
+const [cmd, ...argv] = process.argv.slice(2);
+const flags                                = {}, args           = [];
+for (let i = 0; i < argv.length; i++) {
+  const flag = argv[i].match(/^--(.+)$/)?.[1];
+  if (!flag) args.push(argv[i]);
+  else flags[flag] = flag === 'wait' || flag === 'output' ? true : argv[++i];
+}
+if (cmd !== 'login' && !existsSync(config)) {
+  console.error(`Sign in first, with a token made on the page under Tokens: rf login URL TOKEN\n\n${USAGE}`);
+  process.exit(2);
+}
+const { url, token } = cmd === 'login' ? { url: args[0], token: args[1] } : JSON.parse(readFileSync(config, 'utf8'));
+
+async function api(path        , init              = {}) {
+  const r = await fetch(url + path, { ...init, headers: { authorization: `Bearer ${token}` } });
+  if (!r.ok) throw new Error(`${init.method ?? 'GET'} ${path}: ${r.status} ${await r.text()}`);
+  return r;
+}
+const get = async (path        ) => (await api(path)).json();
+const post = (path        , body         , method = 'POST') => api(path, { method, body: JSON.stringify(body) });
+
+async function find(path        ) {
+  const [w, s, l] = path.split('/'), series = (await get('/api')).find(x => x.name === w)?.series.find(x => x.name === s);
+  const inst = l === undefined ? undefined : series?.instances.find(i => i.label === l);
+  if (!series || (l !== undefined && !inst)) throw new Error(`nothing you can see at ${path}`);
+  return { series, inst, at: inst ? `/api/instances/${inst.id}` : '' };
+}
+
+function write(path        , data                     ) {
+  mkdirSync(dirname(path), { recursive: true });
+  rmSync(path, { force: true });
+  writeFileSync(path, data);
+  chmodSync(path, 0o444);
+}
+
+// A path the server named, under `base`, or undefined: on Windows a file's name may hold \ and lead out of it.
+const under = (base        , rel        ) => resolve(base, rel).startsWith(resolve(base) + sep) ? resolve(base, rel) : undefined;
+
+// Pulls what changed since the last pull, by each instance's files' sizes and times, and removes what moved or went. A file that fails
+// is said and fetched again next time.
+async function pull(dir        ) {
+  const manifest = join(dir, '.rf-pull.json'), had = existsSync(manifest) ? JSON.parse(readFileSync(manifest, 'utf8')) : {};
+  const now                                                                  = {}, tree = await get('/api');
+  write(join(dir, 'AGENTS.md'), (await get('/agents')).text);
+  for (const w of tree) {
+    write(join(dir, w.name, 'AGENTS.md'), w.agents);
+    for (const s of w.series) for (const i of s.instances) now[i.id] = { path: join(w.name, s.name, i.label), files: {} };
+  }
+  for (const [id, old] of Object.entries                  (had)) if (now[id]?.path !== old.path) rmSync(join(dir, old.path), { recursive: true, force: true });
+  let fetched = 0;
+  for (const [id, mine] of Object.entries(now)) {
+    const at = `/api/instances/${id}`, d = await get(at), was = had[id]?.path === mine.path ? had[id].files : {};
+    write(join(dir, mine.path, 'screen.json'), JSON.stringify(d.doc, null, 1));
+    write(join(dir, mine.path, 'log.jsonl'), d.log.map(e => JSON.stringify(e)).join('\n') + '\n');
+    write(join(dir, mine.path, 'trace.json'), JSON.stringify(await get(`${at}/trace`), null, 1));
+    for (const f of await get(`${at}/files`)) {
+      const path = under(join(dir, mine.path), f.path);
+      if (!path) {
+        console.error(`skipped ${mine.path}/${f.path}: it leads out of its folder`);
+        continue;
+      }
+      mine.files[f.path] = `${f.size} ${f.mtime}`;
+      if (was[f.path] === mine.files[f.path]) continue;
+      try {
+        write(path, new Uint8Array(await (await api(`/files/${id}/${f.path.split('/').map(encodeURIComponent).join('/')}`)).arrayBuffer()));
+        fetched++;
+      } catch (e) {
+        mine.files[f.path] = '';
+        console.error(`${mine.path}/${f.path}: ${(e         ).message}`);
+      }
+    }
+    for (const gone of Object.keys(was).filter(p => !(p in mine.files))) {
+      const path = under(join(dir, mine.path), gone);
+      if (path) rmSync(path, { force: true });
+    }
+  }
+  writeFileSync(manifest, JSON.stringify(now));
+  console.log(`${Object.keys(now).length} instances, ${fetched} files fetched, into ${dir}`);
+}
+
+if (cmd === 'login' && url && token) {
+  const me = await get('/me');
+  mkdirSync(dirname(config), { recursive: true });
+  writeFileSync(config, JSON.stringify({ url, token }), { mode: 0o600 });
+  console.log(`signed in as ${me.email}`);
+} else if (cmd === 'ls') {
+  for (const w of await get('/api')) for (const s of w.series) {
+    console.log(`${w.name}/${s.name}${s.wake ? `  wakes ${s.wake.at} to start ${s.wake.label}: ${s.wake.reason}` : ''}${s.requests.length ? `  ${s.requests.length} asking to start` : ''}`);
+    for (const i of s.instances) console.log(`${w.name}/${s.name}/${i.label}  ${i.status}${i.running ? ', running' : ''}${i.asks.length ? `, ${i.asks.length} asks waiting` : ''}${i.wake ? `, wakes ${i.wake}` : ''}, runner ${i.runner}`);
+  }
+} else if (cmd === 'pull' && args[0]) await pull(args[0]);
+else if (cmd === 'comment' && args.length === 2) {
+  const { at } = await find(args[0]);
+  await post(`${at}/comment`, { text: args[1], item: flags.item, ref: flags.ref, thread: flags.thread });
+  const seq = (await get(at)).log.at(-1).seq;
+  if (!flags.wait) console.log(`commented, seq ${seq}`);
+  else for (;;) {
+    // The run that saw the comment, and what it said from then on: a run ending as it came may not have.
+    await new Promise(r => setTimeout(r, 5000));
+    const log = (await get(at)).log, done = log.find(e => e.op === 'done' && e.seen >= seq);
+    if (!done) continue;
+    const from = Math.max(seq, log.find(e => e.op === 'run' && e.run === done.run).seq);
+    for (const e of log.filter(e => e.seq > from && e.seq < done.seq && ((e.op === 'comment' && e.by === 'agent') || e.op === 'report'))) console.log(`${e.op === 'report' ? 'Report' : `${e.ask ? 'Asks' : 'Says'} in ${e.thread}`}:\n${e.text}\n`);
+    if (done.error) console.log(`The run failed: ${done.error}`);
+    break;
+  }
+} else if (cmd === 'upload' && args.length === 2) {
+  const q = new URLSearchParams({ name: basename(args[1]), pane: flags.output ? 'out' : 'in', ...(typeof flags.onto === 'string' && { onto: flags.onto }) });
+  await api(`${(await find(args[0])).at}/upload?${q}`, { method: 'POST', body: readFileSync(args[1]) });
+  console.log('uploaded');
+} else if (cmd === 'wake' && args.length >= 3) {
+  const { series, inst } = await find(args[0]);
+  const at = args[1] === 'now' ? Date.now() : args[1].startsWith('+') ? Date.now() + Number(args[1].slice(1, -1)) * { m: 60e3, h: 3600e3, d: 86400e3 }[args[1].at(-1) ]  : Date.parse(args[1]);
+  const w = await (await post(`/api/wakes/${inst?.id ?? series.id}`, { at: new Date(at).toISOString(), reason: args.slice(2).join(' '), label: flags.label }, 'PUT')).json();
+  console.log(`wakes at ${w.at}`);
+} else if (cmd === 'agents' && args.length <= 1) {
+  const ws = args[0] === undefined ? undefined : (await get('/api')).find(w => w.name === args[0]);
+  if (args[0] !== undefined && !ws) throw new Error(`no workspace ${args[0]}`);
+  if (typeof flags.set !== 'string') console.log(ws ? ws.agents : (await get('/agents')).text);
+  else {
+    const text = readFileSync(flags.set === '-' ? 0 : flags.set, 'utf8');
+    await (ws ? post(`/api/workspaces/${ws.id}`, { agents: text }, 'PUT') : api('/agents', { method: 'PUT', body: text }));
+    console.log('saved');
+  }
+} else if (cmd === 'skill' && args[0] === 'push' && args[1]) {
+  const files = Object.fromEntries(readdirSync(args[1], { recursive: true, withFileTypes: true }).filter(d => d.isFile())
+    .map(d => [relative(args[1], join(d.parentPath, d.name)).split(sep).join('/'), readFileSync(join(d.parentPath, d.name)).toString('base64')]));
+  console.log(await (await post(`/skills/${encodeURIComponent(basename(resolve(args[1])))}/versions`, { files })).text());
+} else if (cmd === 'skill' && args[0] === 'versions' && args[1]) {
+  for (const v of await get(`/skills/${encodeURIComponent(args[1])}/versions`)) console.log(`${v.version}  ${v.at}  ${v.by}`);
+} else if (cmd === 'skill' && args[0] === 'rollback' && args.length === 3) {
+  console.log(await (await post(`/skills/${encodeURIComponent(args[1])}/versions`, { from: Number(args[2]) })).text());
+} else if (cmd === 'skills') {
+  for (const s of await get('/skills')) console.log(`${s.id}  v${s.pushed.version} by ${s.pushed.by} ${s.pushed.at}  ${s.description}`);
+} else if (cmd === 'websites') {
+  for (const w of await get('/websites')) console.log(`${w.id}  ${w.url}  ${w.hosts.join(' ') || '-'}  ${w.name}`);
+} else if (cmd === 'website' && args[0] === 'set' && args.length === 3) {
+  await post(`/websites/${encodeURIComponent(args[1])}`, { url: args[2], name: flags.name, hosts: typeof flags.hosts === 'string' ? flags.hosts.split(',') : [] }, 'PUT');
+  console.log('saved');
+} else if (cmd === 'website' && args[0] === 'remove' && args[1]) {
+  await api(`/websites/${encodeURIComponent(args[1])}`, { method: 'DELETE' });
+  console.log('removed');
+} else if (cmd === 'users') {
+  for (const u of await get('/users')) console.log([u.email, u.role, u.disabled ? 'disabled' : '', u.last_login ? `last in ${u.last_login}` : 'never in', u.workspaces.join(', ')].filter(Boolean).join('\t'));
+} else if (cmd === 'user' && args.length >= 2) {
+  const [what, email, role] = args, at = `/users/${encodeURIComponent(email)}`;
+  if (what === 'add') await post('/users', { email, role: role ?? 'user' });
+  else if (what === 'role' && role) await post(at, { role }, 'PUT');
+  else if (what === 'disable' || what === 'enable') await post(at, { disabled: what === 'disable' }, 'PUT');
+  else if (what === 'signout') await post(at, { signout: true }, 'PUT');
+  else if (what === 'remove') await api(at, { method: 'DELETE' });
+  else throw new Error(USAGE);
+  console.log('done');
+} else {
+  console.error(USAGE);
+  process.exitCode = 2;
+}