@ajaykumarnpm/talea 0.1.0

package/src/github.js

@@ -0,0 +1,208 @@
+// Talking to GitHub.
+//
+// Two calls and no SDK: list the repos an account can see, and read/write a
+// gist. `fetch` is in Node 20, which is the floor this package already sets, so
+// the dependency count stays at zero.
+//
+// The token is whatever the machine already has. `gh auth token` first, because
+// anyone who clones private repos over SSH almost certainly has the GitHub CLI
+// logged in and that saves inventing a second credential to keep in sync.
+
+import { spawnSync } from 'node:child_process';
+
+const API = 'https://api.github.com';
+
+/**
+ * A token, and where it came from.
+ *
+ * No token is a usable state, not an error: the public repos of a named user
+ * are enough to build a catalogue with, and saying "public only" is better than
+ * demanding a credential for a read anyone can do.
+ */
+export function token() {
+  if (process.env.GITHUB_TOKEN) return { token: process.env.GITHUB_TOKEN, from: 'GITHUB_TOKEN' };
+  if (process.env.GH_TOKEN) return { token: process.env.GH_TOKEN, from: 'GH_TOKEN' };
+
+  const res = spawnSync('gh', ['auth', 'token'], { encoding: 'utf8', shell: false });
+  const out = res.stdout?.trim();
+  if (res.status === 0 && out) return { token: out, from: 'gh auth token' };
+
+  return { token: null, from: null };
+}
+
+/**
+ * Is the `gh` CLI on this machine?
+ *
+ * Worth knowing beyond the token: `gh` is a Go binary that trusts the system
+ * certificate store, and Node's `fetch` trusts a CA list compiled into Node.
+ * On any machine behind TLS interception — a corporate proxy, a VPN, a
+ * security agent — `curl` and `gh` work and `fetch` fails with
+ * UNABLE_TO_GET_ISSUER_CERT_LOCALLY. Preferring `gh` when it is there means
+ * that machine works with no configuration at all.
+ */
+let ghPresent = null;
+export function haveGh() {
+  if (ghPresent === null) {
+    ghPresent = spawnSync('gh', ['--version'], { encoding: 'utf8', shell: false }).status === 0;
+  }
+  return ghPresent;
+}
+
+function viaGh(pathname, { method = 'GET', body, paginate } = {}) {
+  const args = ['api', pathname.replace(`${API}`, ''), '-X', method];
+  // --slurp because without it `--paginate` prints each page as its own JSON
+  // document, and stitching those back together by string surgery would break
+  // on a repo whose description happens to contain "] [".
+  if (paginate) args.push('--paginate', '--slurp');
+  if (body) args.push('--input', '-');
+
+  const res = spawnSync('gh', args, {
+    encoding: 'utf8',
+    shell: false,
+    input: body ? JSON.stringify(body) : undefined,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+
+  if (res.status !== 0) {
+    const detail = (res.stderr ?? '').trim().split('\n')[0] ?? `gh api exited ${res.status}`;
+    throw new Error(`GitHub — ${detail}`);
+  }
+
+  const json = JSON.parse(res.stdout);
+  // --slurp wraps the pages in an outer array: [[page1…], [page2…]].
+  return paginate ? json.flat() : json;
+}
+
+async function call(pathname, { token: tok, method = 'GET', body } = {}) {
+  if (haveGh()) return { json: viaGh(pathname, { method, body }), link: null };
+
+  const res = await fetch(pathname.startsWith('http') ? pathname : `${API}${pathname}`, {
+    method,
+    headers: {
+      accept: 'application/vnd.github+json',
+      'user-agent': 'talea',
+      ...(tok ? { authorization: `Bearer ${tok}` } : {}),
+      ...(body ? { 'content-type': 'application/json' } : {}),
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    let detail = '';
+    try {
+      detail = JSON.parse(text).message ?? '';
+    } catch {
+      detail = text.slice(0, 200);
+    }
+    throw new Error(`GitHub ${res.status} on ${pathname}${detail ? ` — ${detail}` : ''}`);
+  }
+
+  return { json: await res.json(), link: res.headers.get('link') };
+}
+
+/**
+ * Follow `Link: <…>; rel="next"` until it stops.
+ *
+ * The page count is not knowable in advance and `?page=N` past the end returns
+ * an empty array rather than an error, so walking the header is both the
+ * cheapest and the only correct way to know when to stop.
+ */
+async function paginate(pathname, opts) {
+  if (haveGh()) return viaGh(pathname, { paginate: true });
+
+  const all = [];
+  let next = pathname;
+  while (next) {
+    const { json, link } = await call(next, opts);
+    all.push(...json);
+    next = /<([^>]+)>;\s*rel="next"/.exec(link ?? '')?.[1] ?? null;
+  }
+  return all;
+}
+
+/**
+ * Every repo this account can see: its own, and every org it belongs to.
+ *
+ * `affiliation` is what makes one call do the job of four — without it you
+ * would list the user's repos, then list each org, and miss anything shared
+ * with the account directly.
+ */
+export async function listRepos({ token: tok, user }) {
+  if (tok) {
+    return paginate('/user/repos?per_page=100&sort=pushed&affiliation=owner,organization_member,collaborator', {
+      token: tok,
+    });
+  }
+  if (!user) {
+    throw new Error(
+      'No GitHub token, and no --user to fall back on.\n' +
+        '  Run `gh auth login`, or set GITHUB_TOKEN, or pass --user <login> for public repos.',
+    );
+  }
+  return paginate(`/users/${encodeURIComponent(user)}/repos?per_page=100&sort=pushed`, {});
+}
+
+export async function whoami(tok) {
+  const { json } = await call('/user', { token: tok });
+  return json.login;
+}
+
+/** The catalogue entry for one API repo. Shape lives here, in one place. */
+export function toEntry(api, { activeSince } = {}) {
+  return {
+    name: api.name,
+    owner: api.owner?.login,
+    defaultBranch: api.default_branch ?? null,
+    private: Boolean(api.private),
+    fork: Boolean(api.fork),
+    // A fork with no upstream recorded is a fork whose parent was deleted, so
+    // the field is honestly null rather than absent.
+    upstream: api.parent?.full_name ?? null,
+    pushedAt: api.pushed_at ?? null,
+    // Archived means "not touched lately", not GitHub's archived flag — a repo
+    // that has gone quiet is still listed, just off by default, so nothing is
+    // ever lost by narrowing the window.
+    archived: Boolean(api.archived) || (activeSince ? (api.pushed_at ?? '') < activeSince : false),
+    description: api.description ?? '',
+  };
+}
+
+// ── gists ────────────────────────────────────────────────────────
+// The whole cross-machine story. A private gist is a file with a URL and an
+// edit history, reachable with the token the machine already has — no server to
+// run, no repo to create, nothing to remember to commit.
+
+export async function createGist({ token: tok, filename, content, description }) {
+  const { json } = await call('/gists', {
+    token: tok,
+    method: 'POST',
+    body: { description, public: false, files: { [filename]: { content } } },
+  });
+  return json.id;
+}
+
+export async function updateGist({ token: tok, id, filename, content }) {
+  const { json } = await call(`/gists/${id}`, {
+    token: tok,
+    method: 'PATCH',
+    body: { files: { [filename]: { content } } },
+  });
+  return json.id;
+}
+
+export async function readGist({ token: tok, id, filename }) {
+  const { json } = await call(`/gists/${id}`, { token: tok });
+  const file = json.files?.[filename] ?? Object.values(json.files ?? {})[0];
+  if (!file) throw new Error(`Gist ${id} has no files.`);
+
+  // GitHub truncates a file inline past ~1MB and hands back a raw_url instead.
+  // A catalogue can reach that size, and silently syncing half of one would be
+  // worse than any error this can throw.
+  if (file.truncated) {
+    const res = await fetch(file.raw_url, { headers: { 'user-agent': 'talea' } });
+    if (!res.ok) throw new Error(`Could not read the full gist (${res.status}).`);
+    return res.text();
+  }
+  return file.content;
+}

package/src/live.js

@@ -0,0 +1,197 @@
+// The live block: rows redrawn in place while `pooled()` works.
+//
+// Bulk commands used to print a line per repo as each one landed, which under
+// `-j 6` meant the order was whichever clone the network finished first. The
+// board fixes the order (catalogue order, grouped by folder) and shows what is
+// queued, in flight and done while it happens.
+//
+// There are two renderings and ONE formatter. On a terminal the rows are
+// redrawn in place; on a pipe, in CI, or when the board would not fit the
+// window, each row prints once as it settles — exactly what this tool printed
+// before. Both go through `statusLine()` in log.js, so the animated and the
+// plain rendering of a finished repo cannot drift apart.
+
+import {
+  ansi,
+  glyph,
+  groupHeader,
+  padEndVisible,
+  paint,
+  spinner,
+  statusLine,
+  visibleWidth,
+} from './log.js';
+
+const FRAME_MS = 80;
+const SETTLED = new Set(['ok', 'skip', 'fail', 'warn']);
+const LABEL_MAX = 46;
+
+const out = (s) => process.stdout.write(s);
+
+/**
+ * Start a board over `items` — `{ id, group, label }`, already in the order
+ * they should appear.
+ *
+ * `set(id, status, note)` moves a row; `note(id, text)` attaches detail that
+ * belongs under the block rather than in the row (a git error, say); `stop()`
+ * freezes the block and prints the detail.
+ */
+export function board(items, { live = process.stdout.isTTY } = {}) {
+  const rows = items.map((it) => ({ ...it, status: 'pending', note: null }));
+  const byId = new Map(rows.map((r) => [r.id, r]));
+  const notes = [];
+
+  const width = Math.min(Math.max(0, ...rows.map((r) => visibleWidth(r.label))), LABEL_MAX);
+
+  // Group headers, rows, a blank line and the counter. When that does not fit
+  // the window, `ansi.up()` would address a region that has already scrolled
+  // and tear the screen — so settled rows scroll away above a small footer
+  // instead of everything being redrawn.
+  const groups = [...new Set(rows.map((r) => r.group))];
+  const fits = () =>
+    live && groups.length + rows.length + 3 <= (process.stdout.rows || 24) - 1;
+  let full = fits();
+
+  let frame = 0;
+  let drawn = 0;
+  let timer = null;
+
+  const counter = () => {
+    const done = rows.filter((r) => SETTLED.has(r.status)).length;
+    return done < rows.length
+      ? `${paint.dim('working …')}  ${paint.ok(String(done))}${paint.dim(`/${rows.length}`)}`
+      : `${paint.ok(glyph.arrow)} ${paint.bold(`${done} of ${rows.length} done`)}`;
+  };
+
+  const rowLine = (r) => {
+    if (r.status !== 'busy') return '  ' + statusLine(r.status, r.label, r.note, width);
+    const f = paint.warn(spinner[frame % spinner.length]);
+    return `  ${f} ${paint.dim(padEndVisible(r.label, width))}  ${paint.dim(r.note ?? 'working …')}`;
+  };
+
+  const lines = () => {
+    const body = [];
+    if (full) {
+      for (const g of groups) {
+        const mine = rows.filter((r) => r.group === g);
+        body.push(groupHeader(g, mine.length));
+        for (const r of mine) body.push(rowLine(r));
+      }
+    } else {
+      // Only what is still moving, so the footer stays a fixed handful of lines
+      // however many repos are queued behind it.
+      for (const r of rows.filter((r) => r.status === 'busy')) body.push(rowLine(r));
+    }
+    body.push('');
+    body.push(counter());
+    return body;
+  };
+
+  const erase = () => {
+    if (!drawn) return;
+    let s = ansi.up(drawn) + ansi.cr;
+    s += (ansi.clearLine + '\n').repeat(drawn);
+    out(s + ansi.up(drawn));
+    drawn = 0;
+  };
+
+  const draw = () => {
+    const body = lines();
+    let s = (drawn ? ansi.up(drawn) : '') + ansi.cr;
+    for (const l of body) s += ansi.clearLine + l + '\n';
+    // The previous block may have been taller — clear what is left of it, then
+    // put the cursor back under the new one.
+    const extra = Math.max(0, drawn - body.length);
+    s += (ansi.clearLine + '\n').repeat(extra) + ansi.up(extra);
+    out(s);
+    drawn = body.length;
+  };
+
+  /** Print above the live block without tearing it. */
+  const emit = (text) => {
+    erase();
+    console.log(text);
+    draw();
+  };
+
+  // A window the board once fitted can stop fitting mid-run. Redrawing a block
+  // taller than the window makes `ansi.up()` address rows that have already
+  // scrolled off, which tears the screen — exactly what `full` exists to avoid —
+  // so re-decide on resize and forget the frame that is no longer up there.
+  const onResize = () => {
+    full = fits();
+    drawn = 0;
+  };
+
+  if (live) {
+    out(ansi.hideCursor);
+    process.on('exit', restoreCursor);
+    process.on('SIGINT', onSigint);
+    process.stdout.on('resize', onResize);
+    draw();
+    timer = setInterval(() => {
+      frame++;
+      draw();
+    }, FRAME_MS);
+    timer.unref?.();
+  }
+
+  return {
+    /** Move a row. `status` is pending | busy | ok | skip | fail | warn. */
+    set(id, status, note = null) {
+      const r = byId.get(id);
+      if (!r) return;
+      r.status = status;
+      r.note = note;
+
+      if (live) {
+        // In the rolling footer a finished row leaves the block, so print it on
+        // the way out — otherwise the run would keep no record of it at all.
+        if (!full && SETTLED.has(status)) emit('  ' + statusLine(status, r.label, note, width));
+        return;
+      }
+
+      // Piped: one line per row, as it settles. Failures keep going to stderr,
+      // which is where every script and CI job already looks for them.
+      if (!SETTLED.has(status)) return;
+      const line = statusLine(status, r.label, note, width);
+      if (status === 'fail') console.error(line);
+      else console.log(line);
+    },
+
+    /** Detail that belongs under the block rather than in the row. */
+    note(id, text) {
+      if (text) notes.push([id, text]);
+    },
+
+    /** Freeze the block, then print whatever detail was collected. */
+    stop() {
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+      if (live) {
+        draw();
+        restoreCursor();
+        process.off('exit', restoreCursor);
+        process.off('SIGINT', onSigint);
+        process.stdout.off('resize', onResize);
+      }
+      for (const [id, text] of notes) {
+        const label = byId.get(id)?.label ?? id;
+        const detail = `  ${paint.dim(label)}\n    ${paint.dim(text)}`;
+        if (live) console.log(detail);
+        else console.error(detail);
+      }
+    },
+  };
+}
+
+const restoreCursor = () => out(ansi.showCursor);
+
+// A hidden cursor outlives the process, so Ctrl-C has to put it back. Node runs
+// no exit handlers for a default SIGINT, which is why this is its own listener.
+function onSigint() {
+  restoreCursor();
+  process.exit(130);
+}

package/src/log.js

@@ -0,0 +1,190 @@
+// Terminal output. Every colour, glyph and width comes from `theme.js` — this
+// module only composes them into the shapes commands actually print, so
+// re-skinning the whole CLI is a change to one file and nothing else.
+//
+// `log.js` also owns the process exit code: `summary()` is what makes a partial
+// failure visible to a script, so every bulk command must end with it.
+
+import {
+  ansi,
+  bold,
+  box,
+  centerVisible,
+  columns,
+  dim,
+  glyph,
+  paint,
+  padEndVisible,
+  spinner,
+  stripAnsi,
+  useColor,
+  visibleWidth,
+} from './theme.js';
+
+export { ansi, glyph, padEndVisible, paint, spinner, useColor, visibleWidth };
+
+/**
+ * Named colours, kept because every command's `help` string and most inline
+ * detail text is written against them. They are roles in the phosphor palette
+ * now rather than raw ANSI, so re-skinning `theme.js` moves them all at once.
+ */
+export const c = {
+  bold,
+  dim,
+  red: paint.fail,
+  green: paint.ok,
+  yellow: paint.warn,
+  blue: paint.aged,
+  cyan: paint.aged,
+  grey: paint.faint,
+};
+
+export const icon = {
+  ok: paint.ok(glyph.ok),
+  skip: paint.warn(glyph.skip),
+  fail: paint.fail(glyph.fail),
+  warn: paint.warn(glyph.warn),
+  arrow: paint.aged(glyph.arrow),
+};
+
+export const plain = (s = '') => console.log(s);
+export const heading = (s) => console.log(`\n${bold(s)}`);
+export const info = (s) => console.log(`${paint.aged(glyph.prompt)} ${s}`);
+export const ok = (s) => console.log(`${icon.ok} ${s}`);
+export const skip = (s) => console.log(`${icon.skip} ${dim(s)}`);
+export const warn = (s) => console.log(`${icon.warn} ${s}`);
+export const fail = (s) => console.error(`${icon.fail} ${s}`);
+
+/**
+ * A group header: the name, a rule filling the line, and a count on the right.
+ * Used by the live block and anywhere else output is bucketed by folder group.
+ */
+export function groupHeader(name, count, noun = 'repo') {
+  const left = `${glyph.groupMark} ${name} `;
+  const right = ` ${count} ${noun}${count === 1 ? '' : 's'}`;
+  const width = Math.min(columns() - 2, 58);
+  const fill = Math.max(2, width - visibleWidth(left) - visibleWidth(right));
+  return paint.aged(left) + paint.faint(glyph.rule.repeat(fill)) + dim(right);
+}
+
+export const group = (name, count, noun) => console.log(groupHeader(name, count, noun));
+
+/**
+ * The context strip under a heading — where the command is working, on which
+ * environment, how wide. `parts` is a list of [label, value] pairs.
+ */
+export function context(parts) {
+  const bits = parts
+    .filter(Boolean)
+    .map(([k, v]) => `${dim(k)} ${v}`)
+    .join(dim('   '));
+  console.log(`${paint.ok(glyph.ok)} ${bits}`);
+}
+
+/** Strip ANSI so padding math stays correct on coloured cells. */
+const visibleLength = (s) => stripAnsi(s).length;
+
+/**
+ * Render an aligned table. `rows` is an array of arrays; `head` is optional.
+ * Columns are left-aligned and padded to the widest visible cell.
+ */
+export function table(rows, head) {
+  const all = head ? [head, ...rows] : rows;
+  if (all.length === 0) return;
+  const widths = [];
+  for (const row of all) {
+    row.forEach((cell, i) => {
+      widths[i] = Math.max(widths[i] ?? 0, visibleLength(cell));
+    });
+  }
+  const render = (row) =>
+    row
+      .map((cell, i) =>
+        i === row.length - 1
+          ? String(cell)
+          : String(cell) + ' '.repeat(widths[i] - visibleLength(cell)),
+      )
+      .join('  ')
+      .trimEnd();
+
+  if (head) console.log(dim(render(head)));
+  for (const row of rows) console.log(render(row));
+}
+
+/**
+ * One settled row: a glyph, an aligned name, and a note.
+ *
+ * Both output paths go through this one formatter — the live block freezes its
+ * rows with it, and the piped path prints them with it — so the animated and
+ * the plain rendering of a finished repo can never drift apart.
+ */
+export function statusLine(status, label, note, width = 0) {
+  const name = padEndVisible(label, width);
+  switch (status) {
+    case 'ok':
+      return `${paint.ok(glyph.ok)} ${paint.ok(name)}  ${note ?? ''}`.trimEnd();
+    case 'skip':
+      return `${paint.warn(glyph.skip)} ${paint.warn(name)}  ${dim(note ?? 'skipped')}`;
+    case 'fail':
+      return `${paint.fail(glyph.fail)} ${paint.fail(name)}  ${dim(note ?? 'failed')}`;
+    case 'warn':
+      return `${paint.warn(glyph.warn)} ${bold(name)}  ${dim(note ?? '')}`.trimEnd();
+    default:
+      return `${dim(glyph.pending)} ${dim(name)}  ${dim(note ?? 'queued')}`;
+  }
+}
+
+// ── The results box ────────────────────────────────────────────
+
+const BOX_INNER = 46;
+
+const boxRow = (content) =>
+  paint.aged(box.v) + centerVisible(content, BOX_INNER) + paint.aged(box.v);
+
+/**
+ * The closing counters, e.g. "12 cloned, 3 skipped, 1 failed", in a box.
+ *
+ * Also sets a non-zero exit code when anything failed. Bulk commands print
+ * per-repo errors and keep going, so without this a script or pipeline would
+ * read a partial failure as complete success.
+ */
+export function summary(counts) {
+  const parts = [];
+  if (counts.ok) parts.push(paint.ok(`${glyph.ok} ${counts.ok} ${counts.okLabel}`));
+  if (counts.skipped) parts.push(paint.warn(`${glyph.skip} ${counts.skipped} skipped`));
+  if (counts.failed) parts.push(paint.fail(`${glyph.fail} ${counts.failed} failed`));
+
+  console.log('');
+  if (parts.length === 0) {
+    console.log(dim('nothing to do'));
+    return;
+  }
+
+  console.log(paint.aged(box.tl + box.h.repeat(BOX_INNER) + box.tr));
+  console.log(boxRow(bold('R E S U L T S')));
+  console.log(boxRow(parts.join('   ')));
+  console.log(paint.aged(box.bl + box.h.repeat(BOX_INNER) + box.br));
+
+  if (counts.failed) process.exitCode = 1;
+}
+
+/**
+ * The closing line under the box: what the run means, in one sentence.
+ *
+ * Three states, not two. `clear` is an absolute claim — "every repo is level
+ * with origin" — and anything skipped falsifies it, so a run with skips gets
+ * `partial` instead. Reporting an all-skipped run as ALL CLEAR is the kind of
+ * lie that only shows up when somebody trusts it.
+ */
+export function verdict(counts, { clear, partial, trouble }) {
+  console.log('');
+  if (counts.failed) {
+    console.log(`${paint.warn(glyph.fail)} ${bold(paint.warn(trouble))}`);
+    return;
+  }
+  if (counts.skipped && partial) {
+    console.log(`${paint.warn(glyph.skip)} ${bold(paint.warn(partial))}`);
+    return;
+  }
+  console.log(`${paint.ok(glyph.ok)} ${bold(paint.ok(clear))}`);
+}