@rfany/rf 0.4.0 → 0.6.0

package/README.md

@@ -3,6 +3,7 @@
 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
+    rf login https://rollforward.example.com
 
-Make the token on the page, under Tokens. `rf` alone lists the commands; `rf help` is the guide for an agent, read before it first uses rf.
+rf opens the page, which asks you to allow it if it shows the same code as rf; or make a token on the page, under Tokens, and
+`rf login URL TOKEN`. `rf` alone lists the commands; `rf help` is the guide for an agent, read before it first uses rf.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rfany/rf",
-  "version": "0.4.0",
+  "version": "0.6.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" },

package/rf.mjs

@@ -2,10 +2,11 @@
 // 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, rmdirSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { spawn } from 'node:child_process';
+import { homedir, hostname } from 'node:os';
 import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 
-const USAGE = `rf login URL TOKEN
+const USAGE = `rf login URL [TOKEN]                without a TOKEN, through the browser: allow it on the page, where it shows rf's code
 rf ls
 rf pull PATH DIR [--delete] [-n|--dry-run] [--exclude PATTERN]...
                                   PATH's files into DIR as rsync copies them, whole, if their size or time differ: PATH/ fills DIR,
@@ -37,7 +38,10 @@ rf people [--set FILE|-] [-n] [--force]   everyone as lines of ROLE EMAIL, each
 rf user add EMAIL [admin|publisher] | role EMAIL admin|publisher|user [--force] | 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`;
+rf website remove ID
+rf brand [--text TEXT] [--logo FILE] [--clear]   the deployment's text and logo, a .png, .jpg, .gif, .webp or .svg, which top
+                                  the sidebar and are the page's title and icon; --clear goes back to the plain look, and with
+                                  no option it prints them`;
 
 const GUIDE = `rollforward runs a team's recurring work, such as a weekly borrowing base or a month-end reconciliation, with an agent
 that does each period's work and people who check it. rf does what its page does, as you.
@@ -46,19 +50,22 @@ What there is
 - A workspace holds series, and its people. A series is one recurring job; an instance is one period of it, labelled such as
   2026-08-23. A task is a one-off: a series of one instance, named by its label, until someone makes it a series. PATH is workspace/series/label, as rf ls prints it; for rf pull it may go deeper, into an instance's files.
 - An instance's screen is its items: inputs, steps and outputs, each pointing at a file, with what it's made from. People upload
-  files and comment; each comment or upload starts a run of the agent, which reads it and carries on. The runner is the person whose
-  logins the runs use, and who closes the instance once they stand by it.
+  files and comment. The runner is the person whose logins the runs use, and who closes the instance once they stand by it. Their
+  comments and uploads start a run of the agent, which reads them and carries on, as do everyone's where the runner shares the
+  series, and a reply from whom an ask names; anyone else's is a note, which the agent takes up once the runner does.
 - A comment starts a thread, on the instance or on an item, at a cell such as Base!C25, and others reply in it. An ask is the
   agent's comment that waits on someone, the one it names or else the runner, until they reply or resolve it. rf ls says how many
-  asks wait in each instance.
+  asks wait in each instance. A sign-off, an ask with signoff true, waits on the runner, who approves or rejects it on the page:
+  either commits the instance's folder to its history, .git in it, as closing does.
 
 What rf pull copies, the folders as the agent sees them
   AGENTS.md                  the company's conventions; <workspace>/AGENTS.md the workspace's
   <workspace>/<series>/<label>/
     workspace.json           the screen: {rev, status, items: [{id, name, kind, file, from, headline, source}]}
     log.jsonl                every event, by seq: by is a person's email, "server" or "agent"; op is upload, comment (thread, item,
-                             ref, text, ask, to), resolve, point and item (the screen changing), run, report (the agent's account of
-                             a run), done (its cost, summary or error), close, and the rest
+                             ref, text, ask, to, signoff), resolve, signoff (the runner's answer, with its commit), commit, point and
+                             item (the screen changing), run, report (the agent's account of a run), done (its cost, summary or
+                             error), close, and the rest
     upload/                  what people uploaded, their comments' attachments in upload/attachments/
     working/                 what the agent made, its scripts, and process.md, how it does this series
     session/                 the agent's own session: every message and tool call of every run
@@ -69,14 +76,15 @@ Usual work
 - What waits on me: rf ls, then the asks in that instance's log.jsonl, ask true, whose thread has nothing after them.
 - Answer an ask: rf comment PATH TEXT --thread T --wait, which prints what the agent says back.
 - Give an input or a corrected output: rf upload PATH FILE [--onto ITEM] [--output].
-- Start an instance: rf wake SERIES now REASON --label LABEL; take one up later: rf wake PATH +2h REASON.
+- Start an instance: rf wake SERIES now REASON --label LABEL, which starts it as whoever shares the series, else asks on the page for
+  someone to start it; take one you run up later: rf wake PATH +2h REASON.
 - Read what a run did: rf pull PATH/ DIR, then its report and done entries in log.jsonl, the files in working/, and session/ for
   every step.
 
 Watching over it, for admins and power users; each sees what the caller sees, and takes --json
 - What's stuck: rf status lists runs going, flagging those past --long MIN (30); queued runs, since when and why: their series is
   running, the RF_MAX_RUNS cap, or memory; what waits on whom since when: asks, notes for runners, expired logins and the instances
-  they hold, requests to start, and shared series with nothing open and no wake set; and open instances whose last run failed.
+  they hold, and requests to start; and open instances whose last run failed.
 - History: rf runs [PATH] [--since DATE] [--failed] [--running] [--long MIN] prints a line per run: its start, path, run number,
   outcome, time taken, cost, what started it and by whom, and its summary or error. rf costs [PATH] [--since DATE] [--by
   workspace|series|person|day] totals them, by the runner for person.
@@ -93,18 +101,22 @@ const flags                                = {}, excludes           = [], args
 for (let i = 0; i < argv.length; i++) {
   const flag = argv[i] === '-n' ? 'dry-run' : argv[i].match(/^--(.+)$/)?.[1];
   if (!flag) args.push(argv[i]);
-  else if (flag === 'exclude') excludes.push(argv[++i]);
-  else flags[flag] = ['wait', 'output', 'delete', 'dry-run', 'force', 'json', 'failed', 'running'].includes(flag) ? true : argv[++i];
+  else if (['wait', 'output', 'delete', 'dry-run', 'force', 'json', 'failed', 'running', 'clear'].includes(flag)) flags[flag] = true;
+  else if (argv[i + 1] === undefined) {
+    console.error(`--${flag} takes a value\n\n${USAGE}`);
+    process.exit(2);
+  } else if (flag === 'exclude') excludes.push(argv[++i]);
+  else flags[flag] = argv[++i];
 }
 if (cmd === 'help') {
   console.log(GUIDE);
   process.exit();
 }
 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}`);
+  console.error(`Sign in first: rf login URL\n\n${USAGE}`);
   process.exit(2);
 }
-const { url, token } = cmd === 'login' ? { url: args[0], token: args[1] } : JSON.parse(readFileSync(config, 'utf8'));
+let { url, token } = cmd === 'login' ? { url: args[0]?.replace(/\/$/, ''), token: args[1] } : JSON.parse(readFileSync(config, 'utf8'));
 
 async function api(path        , init              = {}) {
   const r = await fetch(url + path, { ...init, headers: { authorization: `Bearer ${token}` } });
@@ -136,8 +148,15 @@ function write(path        , data                     , mtime        ) {
   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;
+// A path the server named, under `base`, or undefined where a name in it can't be one here: on Windows a name may hold \ or :, which
+// would put the file elsewhere, even in another workspace's folder, or another file's stream; or name a device, such as CON; or end
+// in a dot or a space, which Windows drops.
+const under = (base        , rel        ) => {
+  const names = rel.split('/');
+  if (names.some(n => !n || n === '.' || n === '..' || basename(n) !== n
+    || (process.platform === 'win32' && (/[<>:"|?*\x00-\x1f]|[. ]$/.test(n) || /^(con|prn|aux|nul|com\d|lpt\d)(\.|$)/i.test(n))))) return undefined;
+  return join(base, ...names);
+};
 
 // rsync's --exclude, simply: a pattern without / matches any one name on the path, one with / the path from the pull's top; * and ?
 // stop at /, ** doesn't. A folder it matches takes what's in it along.
@@ -150,12 +169,13 @@ async function pull(path        , dir        ) {
   const at = path.replace(/^\/+/, ''), from = at.replace(/\/+$/, ''), dry = !!flags['dry-run'];
   const list                                                                               = await get(`/api/files?path=${encodeURIComponent(from)}`);
   if (!list.length) throw new Error(`nothing you can see at ${path}`);
-  const into = !from || at.endsWith('/') ? resolve(dir) : join(resolve(dir), basename(from)), rel = (f                  ) => f.path.slice(from ? from.length + 1 : 0);
+  const into = !from || at.endsWith('/') ? resolve(dir) : under(resolve(dir), from.slice(from.lastIndexOf('/') + 1)), rel = (f                  ) => f.path.slice(from ? from.length + 1 : 0);
+  if (!into) throw new Error(`${from} can't be a name here: pull ${from}/ into a folder of your choosing`);
   let fetched = 0, same = 0, deleted = 0, failed = 0;
   for (const f of list.filter(f => !excluded(rel(f)))) {
     const local = rel(f) ? under(into, rel(f)) : into, st = local && existsSync(local) ? statSync(local) : undefined;
     if (!local) {
-      console.error(`skipped ${f.path}: it leads out of ${into}`);
+      console.error(`skipped ${f.path}: it can't be a file's name here`);
       continue;
     }
     if (st && st.size === f.size && Math.floor(st.mtimeMs / 1000) === Math.floor(Date.parse(f.mtime) / 1000)) {
@@ -187,7 +207,22 @@ async function pull(path        , dir        ) {
   if (failed) process.exitCode = 1;
 }
 
-if (cmd === 'login' && url && token) {
+// The browser's sign-in: the server makes a request, the person allows it on the page, which shows its code, and rf collects the token.
+async function browserToken()                  {
+  const { id, code } = await (await fetch(`${url}/auth/cli`, { method: 'POST', body: JSON.stringify({ name: `rf on ${hostname()}` }) })).json();
+  const link = `${url}/cli?code=${code}`;
+  console.log(`Open ${link}\nand allow rf there if the page shows the code ${code}.`);
+  spawn(process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'explorer' : 'xdg-open', [link], { stdio: 'ignore', detached: true }).on('error', () => {}).unref();
+  for (;;) {
+    await new Promise(ok => setTimeout(ok, 2000));
+    const r = await fetch(`${url}/auth/cli/poll`, { method: 'POST', body: JSON.stringify({ id }) });
+    if (r.status === 200) return (await r.json()).token;
+    if (r.status !== 202) throw new Error(await r.text());
+  }
+}
+
+if (cmd === 'login' && url) {
+  token ??= await browserToken();
   const me = await get('/me');
   mkdirSync(dirname(config), { recursive: true });
   writeFileSync(config, JSON.stringify({ url, token }), { mode: 0o600 });
@@ -201,8 +236,9 @@ if (cmd === 'login' && url && token) {
 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}`);
+  const { log, runner } = await get(at), { seq, note } = log.at(-1);
+  if (note) console.log(`a note for the runner, ${runner.by}, seq ${seq}: it starts no run until they act`);
+  else 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));
@@ -257,10 +293,9 @@ else if (cmd === 'comment' && args.length === 2) {
       [`Running`, s.running.map(r => `${r.path}  run ${r.run}  for ${took((Date.now() - Date.parse(r.at)) / 1000)}  ${usd(r.cost)}${Date.now() - Date.parse(r.at) > long * 60e3 ? `  LONG, past ${long}m` : ''}`)],
       [`Queued`, s.queued.map(q => `${q.path}  since ${when(q.since)}: ${q.why}`)],
       [`Waiting`, [
-        ...s.asks.sort((a, b) => a.who.localeCompare(b.who) || a.since.localeCompare(b.since)).map(a => `${a.who}  ${a.note ? 'a note' : 'an ask'} in ${a.path} since ${when(a.since)}: ${a.text.split('\n')[0].slice(0, 80)}`),
+        ...s.asks.sort((a, b) => a.who.localeCompare(b.who) || a.since.localeCompare(b.since)).map(a => `${a.who}  ${a.signoff ? 'a sign-off' : a.note ? 'a note' : 'an ask'} in ${a.path} since ${when(a.since)}: ${a.text.split('\n')[0].slice(0, 80)}`),
         ...s.expired.map(e => `${e.who}  their ${e.login} login expired${e.holding.length ? `, holding ${e.holding.join(', ')}` : ''}`),
         ...s.requests.map(r => `${r.path}  ${r.from} asks to start ${r.label}, since ${when(r.at)}: ${r.reason}`),
-        ...s.broken.map(b => `${b.path}  shared by ${b.shared_by}, but nothing is open and no wake is set`),
       ]],
       [`Last run failed`, s.failed.map(f => `${f.path}  run ${f.run} at ${when(f.at)}: ${f.error}`)],
     ].filter(([, rows]) => rows.length);
@@ -309,6 +344,15 @@ else if (cmd === 'comment' && args.length === 2) {
       console.log('saved');
     }
   }
+} else if (cmd === 'brand' && !args.length) {
+  if (flags.clear || flags.text !== undefined || flags.logo !== undefined) {
+    const logo = typeof flags.logo === 'string' ? { name: basename(flags.logo), data: readFileSync(flags.logo).toString('base64') } : undefined;
+    await post('/brand', { clear: flags.clear, text: flags.text, logo }, 'PUT');
+    console.log('saved');
+  } else {
+    const { text, logo } = (await get('/me')).brand;
+    console.log(text || logo ? `${text ?? 'no text'}, ${logo ? 'with a logo' : 'no logo'}` : 'no brand: the plain look');
+  }
 } else if (cmd === 'user' && args.length >= 2) {
   const [what, email, role] = args, at = `/users/${encodeURIComponent(email)}`;
   if (what === 'add') await post('/users', { roles: { [email]: role ?? 'user' } }, 'PUT');