@diffin/cli 0.0.0-stage → 0.1.0

package/lib/machine.mjs

@@ -0,0 +1,45 @@
+// The computer this CLI runs on, as a hash the server can compare and nothing more.
+//
+// Many Google accounts are cheap; one computer is not. The server links the accounts that run from one machine and
+// lets them spend as one person, and refuses a third account on the same machine (`COMPUTER_ACCOUNTS`). What is sent is
+// the salted HMAC of the platform id the OS already keeps for the machine — macOS IOPlatformUUID, Linux machine-id,
+// Windows MachineGuid — never the id itself, no MAC address, no host name. It names the computer to the server about
+// as much as a random token would, except that reinstalling the CLI does not change it.
+//
+// This is a value the machine's owner can change (a VM, an edited CLI): it raises the price of a sign-in farm, it does
+// not make one impossible. A CLI that cannot read one sends none, and the server gives such a run its lowest budget.
+// The random device id (`state.mjs` deviceId) keeps its own roles — a backfill once per source per device.
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { createHmac } from 'node:crypto';
+
+const SALT = 'diffin-machine-v1';
+let memo;
+
+function platformId() {
+  try {
+    if (process.platform === 'darwin') {
+      const out = execFileSync('ioreg', ['-rd1', '-c', 'IOPlatformExpertDevice'], { encoding: 'utf8', timeout: 3000, stdio: ['ignore', 'pipe', 'ignore'] });
+      const m = out.match(/"IOPlatformUUID"\s*=\s*"([0-9A-Fa-f-]{36})"/);
+      return m ? m[1].toUpperCase() : null;
+    }
+    if (process.platform === 'linux') {
+      for (const f of ['/etc/machine-id', '/var/lib/dbus/machine-id']) { try { const v = readFileSync(f, 'utf8').trim(); if (/^[0-9a-f]{32}$/.test(v)) return v; } catch { /* next */ } }
+      return null;
+    }
+    if (process.platform === 'win32') {
+      const out = execFileSync('reg', ['query', 'HKLM\\SOFTWARE\\Microsoft\\Cryptography', '/v', 'MachineGuid'], { encoding: 'utf8', timeout: 3000, stdio: ['ignore', 'pipe', 'ignore'] });
+      const m = out.match(/MachineGuid\s+REG_SZ\s+([0-9A-Fa-f-]{36})/);
+      return m ? m[1].toLowerCase() : null;
+    }
+  } catch { /* no id to read */ }
+  return null;
+}
+
+/** the computer's hash — 64 hex characters — or null when this machine's id cannot be read */
+export function machineHash() {
+  if (memo !== undefined) return memo;
+  const id = platformId();
+  memo = id ? createHmac('sha256', SALT).update(`${process.platform}:${id}`).digest('hex') : null;
+  return memo;
+}

package/lib/net.mjs

@@ -0,0 +1,87 @@
+// HTTP helpers shared by every command. The transient-error set is the predecessor's,
+// learned the hard way: a large upload leaves the socket idle while the body is
+// prepared, and it gets reset — the same batch failed with write EPIPE one run and
+// succeeded the next. Retrying is safe because the server is idempotent per session.
+import { dim, fail, serverMessage, warn } from './ui.mjs';
+
+const TRANSIENT = new Set([
+  'EPIPE', 'ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'EAI_AGAIN',
+  'UND_ERR_SOCKET', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT',
+]);
+
+// the production API (decided 2026-10-11, docs/deploy.md); DIFFIN_SERVER points a machine elsewhere — the local stack
+// is `DIFFIN_SERVER=http://localhost:3000`
+export const SERVER = serverUrl(process.env.DIFFIN_SERVER ?? 'https://api.diffin.work');
+
+// Every request carries the person's credential in a header, so the transport must
+// be TLS everywhere except this machine. A mistyped http://api… would otherwise send
+// a token that never expires in the clear and keep working, which is the worst kind of failure.
+export function serverUrl(raw) {
+  let u;
+  try { u = new URL(raw); } catch { throw new Error(`DIFFIN_SERVER 가 URL 이 아닙니다: ${raw}`); }
+  const local = u.hostname === 'localhost' || u.hostname === '127.0.0.1' || u.hostname === '::1';
+  if (u.protocol !== 'https:' && !local) {
+    throw new Error(`DIFFIN_SERVER 는 https 여야 합니다 (localhost 제외): ${raw}`);
+  }
+  return u.origin;
+}
+
+// A run's files sit on ONE server machine's disk, and only that machine's worker reads
+// them. The server names the machine when it opens (or resumes) a run; every request that
+// belongs to the run — each file, `complete`, a discard — carries it, and the platform's
+// proxy delivers the request to exactly that machine (`fly-force-instance-id`). Creating a
+// run is NOT pinned: any machine may answer, and the one that does becomes the run's.
+// A local server calls itself `local`, and nothing is sent.
+let runMachine = null;
+export function pinRun(machine) {
+  const m = String(machine ?? '');
+  runMachine = m !== 'local' && /^[A-Za-z0-9_-]{4,64}$/.test(m) ? m : null;
+}
+export const runAuth = (token, extra = {}) => ({ authorization: `Bearer ${token}`, ...(runMachine ? { 'fly-force-instance-id': runMachine } : {}), ...extra });
+
+/**
+ * makeInit is a function so a retry builds a fresh body (a consumed stream can't replay).
+ *
+ * A 429 is WAITED OUT, not reported. The server says how long in `Retry-After`, and a rate limit is transient by
+ * definition — it exists to slow a client down, not to refuse its work. Measured 2026-09-23 on a real backfill: one
+ * of the three sessions in the window held 95 files (its own transcript and 94 subagents), so the upload burst spent
+ * the minute's budget, the first 429 ended that session, and the run was left incomplete with "요청이 너무 잦습니다"
+ * on screen. The same lesson the model client already carries — "retries live at the HTTP client, where 429 and 5xx
+ * are retryable and retry-after is honoured" — had never reached the CLI's.
+ *
+ * `Retry-After` is trusted but bounded: a header is someone else's number, and a person waiting at a terminal should
+ * not be held for a minute by a typo.
+ *
+ * Only a 429 that CARRIES the header is waited out. The server's rate limiter always sends one; its decisions — five
+ * hours between captures, a day's count, a day's spend — are 429s too and send none, because waiting does not change
+ * them. Retried, a refused capture printed "서버가 잠시 기다려 달라고 합니다" twice and held the agent's turn for three
+ * seconds before saying what the first answer had already said — and with five hours between captures that refusal
+ * is the common reply, not the rare one.
+ */
+const RETRY_AFTER_MAX_SEC = 30;
+
+export async function fetchRetry(url, makeInit, tries = 3) {
+  for (let attempt = 1; ; attempt++) {
+    let res;
+    try {
+      res = await fetch(url, makeInit());
+    } catch (e) {
+      const code = e?.cause?.code ?? e?.code ?? '';
+      if (attempt >= tries || !TRANSIENT.has(code)) throw e;
+      warn(`연결이 끊겨 다시 시도합니다 (${attempt}/${tries - 1}) ${dim(code)}`);
+      await new Promise((r) => setTimeout(r, 500 * attempt));
+      continue;
+    }
+    if (res.status !== 429 || attempt >= tries) return res;
+    const asked = Number(res.headers.get('retry-after'));
+    if (!(Number.isFinite(asked) && asked > 0)) return res; // a decision, not a rate limit: the caller says so
+    const waitSec = Math.min(asked, RETRY_AFTER_MAX_SEC);
+    warn(`서버가 잠시 기다려 달라고 합니다 — ${waitSec}초 뒤 다시 시도합니다 (${attempt}/${tries - 1})`);
+    await new Promise((r) => setTimeout(r, waitSec * 1000));
+  }
+}
+
+export function reportFail(status, body, ctx) {
+  const text = typeof body === 'string' ? body : JSON.stringify(body ?? {});
+  fail(`${ctx} 실패 — ${serverMessage(status, text)}`, process.env.DIFFIN_DEBUG ? `${status} ${text.slice(0, 300)}` : undefined);
+}

package/lib/onboard.mjs

@@ -0,0 +1,74 @@
+// `npx @diffin/cli onboard <setup-token>` — the one line the web page shows. Login, the `diffin` command on PATH, install
+// the skill, run the first backfill, and stay until the server has a result. Each step
+// is one line as it finishes; the card at the end is the result and what happens next.
+// A failure stops there and names the single command to run again: this one. The setup token is single-use, so a
+// second run on a machine that is already signed in goes on without one, and the backfill picks up the run it left
+// open (the server hands it back). There is no separate backfill command any more (2026-10-07): a person met it only
+// in a failure message, as a second command to learn at the worst moment.
+import { login } from './login.mjs';
+import { init } from './init.mjs';
+import { backfill } from './backfill.mjs';
+import { readCreds } from './creds.mjs';
+import { agentById } from './agents.mjs';
+import { version } from './status.mjs';
+import { ensureCommand, PACKAGE } from './command.mjs';
+import { accent, banner, card, dim, fail, out, stepDone, stepFail, stepWarn } from './ui.mjs';
+
+const n = (x) => Number(x ?? 0).toLocaleString('ko-KR');
+
+export async function onboard(argv = []) {
+  const rest = argv.filter((a) => a.startsWith('--') || ['--project', '--exclude'].includes(argv[argv.indexOf(a) - 1]));
+  banner(version());
+  const given = argv.filter((a) => !rest.includes(a));
+  const signedIn = !given.length && readCreds()?.token;
+  const who = signedIn ? { email: readCreds()?.email ?? '' } : await login(given, { quiet: true });
+  if (!who) return;
+  stepDone('로그인', who.email, signedIn ? dim('이미 연결돼 있습니다') : '');
+
+  // the command the agent will run: npx left nothing on PATH (command.mjs)
+  const cmd = ensureCommand(version());
+  if (cmd.state === 'failed') stepWarn('diffin 명령', '설치하지 못했습니다', dim(`터미널에서 npm install -g ${PACKAGE()} 를 실행하세요 · ${cmd.error}`));
+  else stepDone('diffin 명령', cmd.version, dim(cmd.state === 'installed' ? '설치했습니다 · 에이전트가 기록할 때 씁니다' : '이미 있습니다'));
+
+  const installed = init([], { quiet: true });
+  if (process.exitCode) { stepFail('에이전트 연결', '기록할 수 있는 에이전트가 이 기기에 없습니다'); return; }
+  // the agents whose sessions can be recorded are the ones connected; one that only received the skill is named apart
+  const names = (ok) => [...new Set(installed.map((r) => agentById(r.agent)).filter((a) => a && Boolean(a.capture) === ok).map((a) => a.name))];
+  const later = names(false);
+  stepDone('에이전트 연결', names(true).join(' · ') || '없음', later.length ? dim(`${later.join(' · ')} 는 아직 지원하지 않습니다`) : '');
+
+  // The window is the SERVER's: it comes from the account's entitlement and this
+  // command never previews — every source's line prints the range the server gave.
+  const runs = await backfill(rest);
+  out();
+  // the journey has already said it stopped, and how to go on
+  if (process.exitCode) { if (!runs?.journey) fail('지난 작업을 다 올리지 못했습니다.', 'npx @diffin/cli onboard 를 다시 실행하면 이어서 올립니다.'); return; }
+
+  // The app's address comes from the server (`FRONT_URL`, returned on connect) and nowhere else. A default here was
+  // `https://diffin.work/app`, which is the string the CLI's own rule names: it is wrong on every local run, and it
+  // is printed exactly when the server did NOT say — which is when it is least likely to be right.
+  const app = readCreds()?.appUrl ?? null;
+  const done = (runs ?? []).filter((r) => r.outcome === 'done');
+  const waiting = (runs ?? []).some((r) => r.outcome === 'waiting' || r.outcome === 'handed');
+  // a number is printed only where the server said it
+  const atoms = done.reduce((t, r) => t + Number(r.view?.progress?.atoms ?? 0), 0);
+  const goals = done.reduce((t, r) => t + Number(r.view?.progress?.goals ?? 0), 0);
+  const result = waiting ? '서버가 기록을 마저 정리하고 있습니다. 몇 분 뒤 앱에서 볼 수 있습니다.'
+    : atoms ? `기록 ${n(atoms)}개가 작업 ${n(goals)}개로 정리됐습니다.`
+    : '새로 올릴 작업은 없었습니다.';
+  card([
+    '연결됐습니다',
+    '',
+    // the journey's last frame already says what came of the run
+    ...(runs?.journey ? [] : [result]),
+    ...(app ? [`${accent('→')} ${app}`] : []),
+    '',
+    '이제부터 에이전트가 작업을 diffin 에 자동으로 기록합니다.',
+    '따로 할 일은 없습니다. 하루에 몇 번, 일이 일단락되면 올라갑니다.',
+    dim('에이전트의 다음 세션부터 적용됩니다.'),
+    '',
+    `기록 멈추기   diffin pause`,
+    `폴더 제외     diffin exclude <폴더>`,
+    `상태 보기     diffin status`,
+  ]);
+}