@ajaykumarnpm/talea 0.1.0

package/src/commands/discover.js

@@ -0,0 +1,194 @@
+import { findWorkspace, loadManifest, saveManifest } from '../config.js';
+import { listRepos, toEntry, token, whoami } from '../github.js';
+import { c, context, fail, heading, info, ok, plain, skip, table, warn } from '../log.js';
+
+export const help = `
+${c.bold('talea discover')} — build the catalogue from your GitHub account
+
+  ${c.dim('talea discover')}                    every repo you can see
+  ${c.dim('talea discover --since 6mo')}        anything older is kept, but marked archived
+  ${c.dim('talea discover --user someone')}     public repos of an account, no token needed
+  ${c.dim('talea discover --apply')}            write the catalogue (default is a dry run)
+
+Lists your own repos and every org you belong to, then writes each one's owner,
+default branch and last push into the catalogue. This is what makes the
+catalogue current instead of hand-maintained.
+
+Options
+      --since <window>   6mo | 90d | 2y | an ISO date. Older repos are kept in
+                         the catalogue and marked archived, never dropped.
+      --user <login>     read a specific account's public repos instead
+      --apply            write the file (default prints what would change)
+
+${c.bold('What is preserved')} — a repo already in the catalogue keeps its ${c.dim('default')},
+${c.dim('group')} and ${c.dim('dir')}. Discovery refreshes the facts GitHub owns; the choices are
+yours and are never overwritten.
+
+Auth comes from ${c.dim('gh auth token')}, then ${c.dim('GITHUB_TOKEN')}, then nothing — and nothing is
+a working state, it just means public repos only.
+
+The first run writes ${c.dim('~/.talea/talea.repos.json')}. Share it with
+${c.dim('talea manifest push')}.
+`;
+
+/**
+ * Turn `6mo` / `90d` / `2y` / `2026-01-01` into an ISO timestamp.
+ *
+ * Returns null for "no window", which means nothing gets marked archived by
+ * age. A window that cannot be parsed is an error rather than a silent null:
+ * `--since 6m` quietly meaning "everything is active" is the kind of typo that
+ * makes a command look like it worked.
+ */
+export function parseSince(spec, now = new Date()) {
+  if (!spec) return null;
+  const m = /^(\d+)\s*(d|w|mo|m|y)$/i.exec(String(spec).trim());
+  if (m) {
+    const n = Number(m[1]);
+    const d = new Date(now);
+    const unit = m[2].toLowerCase();
+    if (unit === 'd') d.setDate(d.getDate() - n);
+    else if (unit === 'w') d.setDate(d.getDate() - n * 7);
+    else if (unit === 'y') d.setFullYear(d.getFullYear() - n);
+    else d.setMonth(d.getMonth() - n); // 'mo' and bare 'm' both mean months
+    return d.toISOString();
+  }
+  const date = new Date(spec);
+  if (Number.isNaN(date.getTime())) {
+    throw new Error(`Cannot read --since "${spec}". Try 6mo, 90d, 2y, or 2026-01-01.`);
+  }
+  return date.toISOString();
+}
+
+/**
+ * Merge what GitHub says into what the catalogue already holds.
+ *
+ * The split that matters: GitHub owns the *facts* (owner, default branch, fork,
+ * last push) and refreshing them is the whole point. You own the *choices*
+ * (`default`, `group`, `dir`, `url`), and a discovery run that reset those
+ * would undo your curation every time the tool got run.
+ */
+export function merge(existing, found) {
+  const byKey = new Map(existing.map((r) => [`${r.owner}/${r.name}`.toLowerCase(), r]));
+  const seen = new Set();
+  const repos = [];
+  const added = [];
+
+  for (const entry of found) {
+    const key = `${entry.owner}/${entry.name}`.toLowerCase();
+    seen.add(key);
+    const prior = byKey.get(key);
+    if (!prior) added.push(entry);
+    repos.push({
+      ...entry,
+      // Choices win over discovery, every time.
+      ...(prior?.default !== undefined ? { default: prior.default } : {}),
+      ...(prior?.group !== undefined ? { group: prior.group } : {}),
+      ...(prior?.dir !== undefined ? { dir: prior.dir } : {}),
+      ...(prior?.url !== undefined ? { url: prior.url } : {}),
+    });
+  }
+
+  // A repo the API did not return is not a repo that stopped existing — a token
+  // with narrower scopes, a revoked org grant or a rate limit all look the same
+  // from here. Keep it, mark it, and let the human decide.
+  const vanished = existing.filter((r) => !seen.has(`${r.owner}/${r.name}`.toLowerCase()));
+  for (const r of vanished) repos.push({ ...r, missing: true });
+
+  return { repos, added, vanished };
+}
+
+export async function run(opts) {
+  const { token: tok, from } = token();
+  const since = parseSince(opts.since);
+
+  heading('Discovering repositories');
+  context([
+    ['auth', tok ? c.green(from) : c.yellow('none — public repos only')],
+    opts.user ? ['user', c.bold(opts.user)] : null,
+    since ? ['active since', c.cyan(since.slice(0, 10))] : null,
+    ['mode', opts.apply ? c.bold('apply') : c.dim('dry run')],
+  ]);
+
+  let login = opts.user ?? null;
+  if (tok && !login) {
+    try {
+      login = await whoami(tok);
+      info(`signed in as ${c.bold(login)}`);
+    } catch (err) {
+      warn(`Could not read the account behind that token — ${err.message}`);
+    }
+  }
+
+  let api;
+  try {
+    api = await listRepos({ token: opts.user ? null : tok, user: login });
+  } catch (err) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  const found = api.map((r) => toEntry(r, { activeSince: since }));
+  const root = findWorkspace();
+  const manifest = loadManifest(root);
+  const { repos, added, vanished } = merge(manifest.repos, found);
+
+  const active = repos.filter((r) => !r.archived && !r.missing);
+  const owners = new Set(repos.map((r) => r.owner));
+
+  plain('');
+  table(
+    [
+      ['found', `${found.length}`],
+      ['active', `${active.length}`],
+      ['archived / quiet', `${repos.length - active.length - vanished.length}`],
+      ['new to the catalogue', `${added.length}`],
+      ['owners', [...owners].join(', ')],
+    ],
+    ['', ''],
+  );
+
+  if (added.length) {
+    heading('New');
+    for (const r of added.slice(0, 40)) {
+      plain(`  ${c.green('+')} ${c.bold(`${r.owner}/${r.name}`)} ${c.dim(r.pushedAt?.slice(0, 10) ?? '')}`);
+    }
+    if (added.length > 40) plain(c.dim(`  … and ${added.length - 40} more`));
+  }
+
+  if (vanished.length) {
+    heading('In the catalogue, not returned by GitHub');
+    for (const r of vanished) {
+      plain(`  ${c.yellow('?')} ${c.bold(`${r.owner}/${r.name}`)}`);
+    }
+    plain(
+      c.dim(
+        '  Kept and marked. Renamed, made private, or your token cannot see it —\n' +
+          '  none of which is a reason for this tool to forget it.',
+      ),
+    );
+  }
+
+  if (!opts.apply) {
+    plain(`\n${c.dim('Re-run with --apply to write the catalogue.')}`);
+    return;
+  }
+
+  // First discovery decides what "default" means: everything still active. It
+  // is only a starting point — the catalogue is yours to edit, and `talea add`
+  // and the picker both write to it.
+  const seeding = !manifest.repos.length;
+  if (seeding) {
+    for (const r of repos) r.default = !r.archived && !r.fork;
+  }
+
+  const groups = { ...manifest.groups };
+  for (const owner of owners) groups[owner] ??= { dir: owner, title: `${owner} on GitHub` };
+
+  const file = saveManifest({ ...manifest, groups, repos });
+  plain('');
+  ok(`catalogue written ${c.dim(`→ ${file}`)}`);
+  if (seeding) {
+    const on = repos.filter((r) => r.default).length;
+    skip(`${on} repos marked default — edit the file, or run \`talea sync --pick\` to choose`);
+  }
+}

package/src/commands/doctor.js

@@ -0,0 +1,142 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+
+import { findWorkspace, loadManifest, loadState } from '../config.js';
+import { git, gitVersion } from '../git.js';
+import { token, whoami } from '../github.js';
+import { c, heading, icon, plain, verdict } from '../log.js';
+import { padEndVisible } from '../theme.js';
+import { hasChosen, machineRepos } from '../workspace.js';
+
+export const help = `
+${c.bold('talea doctor')} — check that this machine can actually do the work
+
+  ${c.dim('talea doctor')}
+
+Verifies Node, git, SSH access to GitHub, the API token, and the workspace it
+found. Run this first when a clone fails.
+`;
+
+const PASS = icon.ok;
+const FAIL = icon.fail;
+const WARN = icon.warn;
+
+/**
+ * `ssh -T git@github.com` exits non-zero even when it works — GitHub
+ * authenticates you and then refuses the shell. So the signal is the text, not
+ * the exit code.
+ */
+function sshProbe(host) {
+  return new Promise((resolve) => {
+    const child = spawn(
+      'ssh',
+      ['-T', '-o', 'StrictHostKeyChecking=accept-new', '-o', 'ConnectTimeout=10', host],
+      { stdio: ['ignore', 'pipe', 'pipe'], shell: false },
+    );
+    let out = '';
+    child.stdout.on('data', (d) => (out += d));
+    child.stderr.on('data', (d) => (out += d));
+    child.on('error', (e) => resolve({ ok: false, message: e.message }));
+    child.on('close', () => {
+      const text = out.trim();
+      const authed = /successfully authenticated|shell access|You've successfully|Welcome/i.test(text);
+      const denied = /permission denied|publickey/i.test(text);
+      resolve({ ok: authed && !denied, message: text.split('\n')[0] ?? 'no response' });
+    });
+    setTimeout(() => child.kill(), 15000);
+  });
+}
+
+export async function run() {
+  heading('talea doctor');
+
+  const checks = [];
+
+  const nodeMajor = Number(process.versions.node.split('.')[0]);
+  checks.push([
+    nodeMajor >= 20 ? PASS : FAIL,
+    'Node.js',
+    `v${process.versions.node}${nodeMajor >= 20 ? '' : c.red('  (need >= 20)')}`,
+  ]);
+
+  const gv = await gitVersion();
+  checks.push([gv ? PASS : FAIL, 'git', gv ?? c.red('not found on PATH')]);
+
+  const user = await git(['config', '--get', 'user.email']);
+  checks.push([
+    user.stdout ? PASS : WARN,
+    'git user.email',
+    user.stdout || c.yellow('not set — commits will be attributed oddly'),
+  ]);
+
+  const gh = await sshProbe('git@github.com');
+  checks.push([
+    gh.ok ? PASS : FAIL,
+    `SSH ${icon.arrow} GitHub`,
+    gh.ok ? c.dim(gh.message) : c.red(gh.message),
+  ]);
+
+  // The token is for reading the catalogue, not for cloning — so no token is a
+  // warning, never a failure. SSH is what clones private repos.
+  const { token: tok, from } = token();
+  let login = null;
+  if (tok) {
+    try {
+      login = await whoami(tok);
+    } catch (err) {
+      login = c.red(err.message);
+    }
+  }
+  checks.push([
+    tok ? PASS : WARN,
+    'GitHub API token',
+    tok
+      ? `${c.dim(from)}${login ? ` ${icon.arrow} ${c.bold(login)}` : ''}`
+      : c.yellow('none — `talea discover` will see public repos only'),
+  ]);
+
+  const root = findWorkspace();
+  const manifest = loadManifest(root);
+  checks.push([root ? PASS : WARN, 'workspace', root ?? c.yellow('none found — run `talea init`')]);
+  checks.push([
+    manifest.repos.length ? PASS : WARN,
+    'catalogue',
+    manifest.repos.length
+      ? `${manifest.repos.length} repos  ${c.dim(manifest.__source)}`
+      : c.yellow('empty — run `talea discover`'),
+  ]);
+
+  if (root) {
+    const state = loadState(root);
+    checks.push([
+      PASS,
+      'this machine keeps',
+      hasChosen(state)
+        ? `${machineRepos(manifest, state).length} repos`
+        : c.dim(`${machineRepos(manifest, state).length} by default — not chosen yet`),
+    ]);
+  }
+
+  plain('');
+  for (const [mark, label, detail] of checks) {
+    plain(`  ${mark}  ${padEndVisible(label, 22)} ${detail}`);
+  }
+
+  const broken = checks.filter(([m]) => m === FAIL).length;
+  verdict(
+    { failed: broken },
+    {
+      clear: 'ALL CLEAR · this machine can do the work',
+      trouble: `${broken} problem(s) to fix before cloning`,
+    },
+  );
+
+  if (!gh.ok) {
+    plain(
+      c.dim(
+        '\nGitHub SSH: add your public key at https://github.com/settings/keys,\n' +
+          '  or run `talea sync --protocol https` to clone over HTTPS instead.',
+      ),
+    );
+  }
+}

package/src/commands/exec.js

@@ -0,0 +1,78 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+
+import { c, fail, heading, info, ok, plain, summary } from '../log.js';
+import { clonedOnly, machineRepos, requireWorkspace, selectRepos, withPaths } from '../workspace.js';
+
+export const help = `
+${c.bold('talea exec')} — run one command in every repo
+
+  ${c.dim('talea exec -- git log --oneline -1')}
+  ${c.dim('talea exec -g nonstopio -- npm install')}
+  ${c.dim('talea exec -- git branch --show-current')}
+
+Everything after ${c.bold('--')} is the command. It runs once per repo with the
+repo as the working directory.
+
+Options
+  -g, --group <names>   comma-separated groups
+  -r, --repo <names>    comma-separated repo names
+      --all             every repo in the catalogue, not just what this machine keeps
+
+Repos are processed one at a time so the output stays readable and attributable.
+`;
+
+function runOne(command, args, cwd) {
+  return new Promise((resolve) => {
+    // shell:true so developers can write `talea exec -- yarn build && yarn test`
+    // and get the shell semantics they expect on their own platform.
+    const child = spawn([command, ...args].join(' '), {
+      cwd,
+      shell: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let out = '';
+    child.stdout.on('data', (d) => (out += d));
+    child.stderr.on('data', (d) => (out += d));
+    child.on('error', (e) => resolve({ code: -1, out: e.message }));
+    child.on('close', (code) => resolve({ code, out: out.trimEnd() }));
+  });
+}
+
+export async function run(opts, positionals) {
+  const [command, ...args] = positionals;
+  if (!command) {
+    fail('Nothing to run. Put the command after `--`, e.g. `talea exec -- git status`.');
+    process.exit(1);
+  }
+
+  const { root, manifest, state } = requireWorkspace();
+  const pool = opts.all ? manifest.repos : machineRepos(manifest, state);
+  const entries = clonedOnly(withPaths(manifest, root, selectRepos(manifest, opts, pool)));
+
+  heading(`${c.bold([command, ...args].join(' '))} ${c.dim(`in ${entries.length} repos`)}`);
+
+  const counts = { ok: 0, skipped: 0, failed: 0, okLabel: 'ok' };
+
+  for (const { repo, dir } of entries) {
+    const res = await runOne(command, args, dir);
+    const label = `${c.bold(repo.name)} ${c.dim(path.relative(root, dir))}`;
+    if (res.code === 0) {
+      counts.ok++;
+      ok(label);
+    } else {
+      counts.failed++;
+      fail(`${label} ${c.dim(`(exit ${res.code})`)}`);
+    }
+    if (res.out) {
+      plain(
+        res.out
+          .split('\n')
+          .map((l) => '    ' + c.dim(l))
+          .join('\n'),
+      );
+    }
+  }
+
+  summary(counts);
+}

package/src/commands/init.js

@@ -0,0 +1,106 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+
+import {
+  STATE_FILE,
+  expandHome,
+  groupDir,
+  loadManifest,
+  loadState,
+  repoGroup,
+  saveState,
+} from '../config.js';
+import { machineRepos } from '../workspace.js';
+import { c, context, heading, info, ok, plain, skip, warn } from '../log.js';
+import { run as discover } from './discover.js';
+import { run as sync } from './sync.js';
+
+export const help = `
+${c.bold('talea init')} — set this machine up
+
+  ${c.dim('talea init')}                      use the current folder as the workspace
+  ${c.dim('talea init ~/Workspace')}          use that folder instead
+  ${c.dim('talea init --no-clone')}           write the config, clone later
+
+Creates the workspace, records this machine's preferences in ${STATE_FILE}, asks
+what this machine should keep, and fills it.
+
+If the catalogue is empty, ${c.dim('talea discover')} runs first — so on your very first
+machine this one command goes from nothing to a folder tree.
+
+Options
+      --protocol <p>    ssh (default) or https
+      --no-clone        create the workspace without cloning
+      --pick            go straight to the checklist, skipping the defaults offer
+  -g, --group <names>   restrict to these groups
+  -j, --jobs <n>        parallel clones
+
+${c.bold('On your second machine')}, pull the catalogue first:
+
+  ${c.dim('talea manifest pull <gist-id>')}
+  ${c.dim('talea init ~/Workspace')}
+`;
+
+export async function run(opts, positionals = []) {
+  const target = path.resolve(expandHome(positionals[0] ?? process.cwd()));
+  const stateFile = path.join(target, STATE_FILE);
+  const fresh = !existsSync(stateFile);
+
+  heading(fresh ? `Creating a workspace at ${target}` : `Workspace already at ${target}`);
+
+  mkdirSync(target, { recursive: true });
+
+  if (fresh) {
+    // Written before anything else: every other command finds the workspace by
+    // walking up to this file, so until it exists `talea sync` run from inside
+    // the folder we just made would not know it is in one.
+    saveState(target, { protocol: opts.protocol ?? 'ssh', createdAt: new Date().toISOString() });
+    ok(`${STATE_FILE} ${c.dim('— this machine’s own state, never shared')}`);
+  } else {
+    skip(`${STATE_FILE} already here, leaving it alone`);
+  }
+
+  let manifest = loadManifest(target);
+
+  if (!manifest.repos.length) {
+    info('The catalogue is empty — discovering your repos from GitHub.');
+    plain('');
+    await discover({ ...opts, apply: true });
+    manifest = loadManifest(target);
+    if (!manifest.repos.length) {
+      warn('Still nothing in the catalogue. Nothing to clone.');
+      return;
+    }
+  }
+
+  const groups = [...new Set(manifest.repos.map((r) => repoGroup(r)))];
+  context([
+    ['catalogue', c.dim(manifest.__source)],
+    ['repos', `${manifest.repos.length}`],
+    ['groups', `${groups.length}`],
+  ]);
+
+  // The group folders for the repos this machine will actually hold — not one
+  // per owner in the catalogue. A collaborator repo you never clone should not
+  // leave an empty folder in the tree forever.
+  const mine = machineRepos(manifest, loadState(target));
+  for (const g of new Set(mine.map((r) => repoGroup(r)))) {
+    mkdirSync(path.join(target, groupDir(manifest, g)), { recursive: true });
+  }
+
+  if (opts.clone === false) {
+    plain(`\n${c.dim('Workspace ready. Run `talea sync` when you want the repos.')}`);
+    return;
+  }
+
+  // `sync` finds the workspace by walking up from cwd, and cwd is wherever the
+  // developer typed the command — which is not necessarily inside the folder
+  // they just named.
+  const back = process.cwd();
+  try {
+    process.chdir(target);
+    await sync(opts);
+  } finally {
+    process.chdir(back);
+  }
+}

package/src/commands/list.js

@@ -0,0 +1,100 @@
+import { findWorkspace, groupDir, loadManifest, loadState, repoGroup } from '../config.js';
+import { c, glyph, group, heading, plain, table } from '../log.js';
+import { machineRepos, selectRepos } from '../workspace.js';
+
+export const help = `
+${c.bold('talea list')} — show the catalogue
+
+  ${c.dim('talea list')}                      every repo, grouped by folder
+  ${c.dim('talea list -g nonstopio')}         one owner
+  ${c.dim('talea list --groups')}             just the group summary
+  ${c.dim('talea list --json')}               machine-readable output
+
+The ${c.bold('KEEP')} column is this machine: ${glyph.ok} kept, blank not. The ${c.bold('DEFAULT')} column is
+the catalogue's opinion — what a brand new machine would start with.
+
+Options
+  -g, --group <names>   comma-separated groups
+  -r, --repo <names>    comma-separated repo names
+      --all             include archived and quiet repos (default: hidden)
+      --groups          show groups only
+      --json            emit JSON
+`;
+
+export function run(opts) {
+  // Readable from anywhere. Listing the catalogue is not a workspace operation
+  // — on a fresh machine it is the thing you run *before* `talea init`, to see
+  // what you are about to be offered.
+  const root = findWorkspace();
+  const manifest = loadManifest(root);
+  const state = root ? loadState(root) : {};
+  const kept = new Set(machineRepos(manifest, state).map((r) => r.name));
+
+  let repos = selectRepos(manifest, opts, manifest.repos);
+  if (!opts.all) repos = repos.filter((r) => !r.archived || kept.has(r.name));
+
+  if (opts.json) {
+    // Data, so stdout and nothing else — this is what a script reads.
+    process.stdout.write(
+      JSON.stringify(
+        repos.map((r) => ({ ...r, group: repoGroup(r), kept: kept.has(r.name) })),
+        null,
+        2,
+      ) + '\n',
+    );
+    return;
+  }
+
+  const byGroup = new Map();
+  for (const r of repos) {
+    const g = repoGroup(r);
+    if (!byGroup.has(g)) byGroup.set(g, []);
+    byGroup.get(g).push(r);
+  }
+
+  if (opts.groups) {
+    heading('Groups');
+    table(
+      [...byGroup.entries()].map(([g, members]) => [
+        c.bold(`${groupDir(manifest, g)}/`),
+        `${members.length}`,
+        c.dim(`${members.filter((r) => kept.has(r.name)).length} kept here`),
+      ]),
+      ['GROUP', 'REPOS', ''],
+    );
+    return;
+  }
+
+  heading(`Catalogue ${c.dim(manifest.__source)}`);
+
+  for (const [g, members] of byGroup) {
+    plain('');
+    group(`${groupDir(manifest, g)}/`, members.length);
+    table(
+      members.map((r) => [
+        '  ' + (kept.has(r.name) ? c.bold(r.name) : c.dim(r.name)),
+        kept.has(r.name) ? c.green(glyph.ok) : c.dim(''),
+        r.default ? c.dim('default') : c.dim(''),
+        c.dim(r.defaultBranch ?? '?'),
+        [
+          r.private ? c.dim('private') : '',
+          r.fork ? c.dim('fork') : '',
+          r.archived ? c.yellow('quiet') : '',
+          r.missing ? c.yellow('not on github') : '',
+        ]
+          .filter(Boolean)
+          .join(' '),
+      ]),
+      ['  REPO', 'KEEP', 'DEFAULT', 'BRANCH', ''],
+    );
+  }
+
+  const hidden = manifest.repos.length - repos.length;
+  plain('');
+  plain(
+    c.dim(
+      `${repos.length} shown, ${kept.size} kept on this machine` +
+        (hidden > 0 ? `, ${hidden} quiet (--all to show)` : ''),
+    ),
+  );
+}