@ajaykumarnpm/talea 0.1.0

package/src/commands/manifest.js

@@ -0,0 +1,190 @@
+// The catalogue's trip between machines.
+//
+// A private gist, and nothing else: no server to run, no account to create, no
+// extra repo to remember to commit. It is reachable with the token the machine
+// already has for `discover`, it has a URL you can paste into the next laptop,
+// and it keeps a revision history for free.
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+
+import {
+  MANIFEST_NAME,
+  USER_MANIFEST,
+  findWorkspace,
+  loadManifest,
+  readUserState,
+  writeUserState,
+} from '../config.js';
+import { createGist, readGist, token, updateGist } from '../github.js';
+import { c, context, fail, heading, info, ok, plain, warn } from '../log.js';
+
+export const help = `
+${c.bold('talea manifest')} — move the catalogue between machines
+
+  ${c.dim('talea manifest push')}              publish it to a private gist
+  ${c.dim('talea manifest pull')}              fetch the one this machine is linked to
+  ${c.dim('talea manifest pull <gist-id>')}    link this machine to a gist and fetch it
+  ${c.dim('talea manifest where')}             which file is in use, and which gist
+
+The catalogue is the only thing that travels. What each machine *keeps* stays
+in that machine's ${c.dim('.talea.json')} and is never published — so pulling on a new
+laptop gives you the full list to choose from, not the last machine's choices.
+
+The gist is ${c.bold('private')}. It still holds the names of your private repositories,
+so treat the id like a bookmark you would not paste into a public channel.
+
+The id is remembered in ${c.dim('~/.talea/state.json')}, so after the first ${c.dim('pull <id>')}
+every later ${c.dim('push')} and ${c.dim('pull')} needs no argument.
+
+Options
+      --gist <id>       use this gist for one command without remembering it
+`;
+
+const GIST_FILE = MANIFEST_NAME;
+
+function requireToken() {
+  const { token: tok, from } = token();
+  if (!tok) {
+    fail('A GitHub token is needed to read or write a gist.');
+    console.error('\n  Run `gh auth login`, or set GITHUB_TOKEN.');
+    process.exit(1);
+  }
+  return { tok, from };
+}
+
+/** The catalogue file this machine would load, and where it came from. */
+function currentFile() {
+  const root = findWorkspace();
+  const manifest = loadManifest(root);
+  return { root, manifest, file: manifest.__source };
+}
+
+async function push(opts) {
+  const { tok, from } = requireToken();
+  const { manifest, file } = currentFile();
+
+  if (!manifest.repos.length) {
+    fail('The catalogue is empty — there is nothing to publish.');
+    console.error('\n  Run `talea discover --apply` first.');
+    process.exit(1);
+  }
+
+  const state = readUserState();
+  const id = opts.gist ?? state.gist ?? null;
+
+  // Published from the file on disk, byte for byte, rather than from the parsed
+  // object — a round trip through JSON.parse would drop comments-by-convention,
+  // key order and anything a future version of the format adds that this
+  // version does not know to keep.
+  const content = readFileSync(file, 'utf8');
+
+  heading(id ? 'Updating the catalogue gist' : 'Publishing the catalogue');
+  context([
+    ['auth', c.dim(from)],
+    ['from', c.dim(file)],
+    ['repos', `${manifest.repos.length}`],
+  ]);
+
+  const gistId = id
+    ? await updateGist({ token: tok, id, filename: GIST_FILE, content })
+    : await createGist({
+        token: tok,
+        filename: GIST_FILE,
+        content,
+        description: 'talea catalogue — the repos I keep, and where they go',
+      });
+
+  writeUserState({ ...state, gist: gistId });
+
+  plain('');
+  ok(`gist ${c.bold(gistId)}`);
+  plain(c.dim(`  https://gist.github.com/${gistId}`));
+  plain('');
+  info(`On another machine: ${c.bold(`talea manifest pull ${gistId}`)}`);
+}
+
+async function pull(opts, positionals) {
+  const { tok, from } = requireToken();
+  const state = readUserState();
+  const id = positionals[0] ?? opts.gist ?? state.gist ?? null;
+
+  if (!id) {
+    fail('No gist to pull from.');
+    console.error('\n  Pass the id once — `talea manifest pull <gist-id>` — and it is remembered.');
+    process.exit(1);
+  }
+
+  heading('Pulling the catalogue');
+  context([
+    ['auth', c.dim(from)],
+    ['gist', c.bold(id)],
+  ]);
+
+  const content = await readGist({ token: tok, id, filename: GIST_FILE });
+
+  // Parsed before it is written, never after: a truncated download or somebody
+  // else's gist would otherwise land on top of a working catalogue and only
+  // fail on the next command, with the good copy already gone.
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch (err) {
+    fail(`That gist is not a catalogue — ${err.message}`);
+    process.exit(1);
+  }
+  if (!Array.isArray(parsed.repos)) {
+    fail('That gist has no `repos` array, so it is not a talea catalogue.');
+    process.exit(1);
+  }
+
+  mkdirSync(path.dirname(USER_MANIFEST), { recursive: true });
+  writeFileSync(USER_MANIFEST, content.endsWith('\n') ? content : content + '\n');
+  writeUserState({ ...state, gist: id });
+
+  plain('');
+  ok(`${parsed.repos.length} repos ${c.dim(`→ ${USER_MANIFEST}`)}`);
+
+  const { file } = currentFile();
+  if (file !== USER_MANIFEST) {
+    warn(`A nearer catalogue is still winning: ${c.bold(file)}`);
+    plain(c.dim('  Delete or rename it if you meant to use the one you just pulled.'));
+    return;
+  }
+
+  plain('');
+  info(`Next: ${c.bold('talea init ~/Workspace')} — or ${c.bold('talea sync --pick')} if you already have one.`);
+}
+
+function where() {
+  const { root, manifest, file } = currentFile();
+  const { gist } = readUserState();
+
+  heading('Catalogue');
+  context([
+    ['in use', c.bold(file)],
+    ['repos', `${manifest.repos.length}`],
+  ]);
+  plain('');
+  plain(`  ${c.dim('workspace')}  ${root ?? c.dim('none found')}`);
+  plain(`  ${c.dim('gist')}       ${gist ? `${gist}  ${c.dim(`https://gist.github.com/${gist}`)}` : c.dim('not linked')}`);
+  plain(`  ${c.dim('user copy')}  ${USER_MANIFEST}`);
+}
+
+export async function run(opts, positionals = []) {
+  const [verb, ...rest] = positionals;
+
+  switch (verb) {
+    case 'push':
+      return push(opts);
+    case 'pull':
+      return pull(opts, rest);
+    case 'where':
+    case undefined:
+      return where();
+    default:
+      fail(`Unknown: talea manifest ${verb}`);
+      console.error('\n  Try: push, pull, where');
+      process.exit(1);
+  }
+}

package/src/commands/status.js

@@ -0,0 +1,114 @@
+import path from 'node:path';
+
+import { defaultBranch, groupDir, repoGroup } from '../config.js';
+import { aheadBehind, currentBranch, defaultJobs, isDirty, pooled } from '../git.js';
+import { c, context, glyph, group, heading, plain, table } from '../log.js';
+import { machineRepos, requireWorkspace, selectRepos, withPaths } from '../workspace.js';
+
+export const help = `
+${c.bold('talea status')} — one table showing where every repo stands
+
+  ${c.dim('talea status')}                    every repo this machine keeps
+  ${c.dim('talea status -g nonstopio')}       only that owner
+  ${c.dim('talea status --drift')}            only repos not on their default branch
+  ${c.dim('talea status --missing')}          only repos not cloned yet
+  ${c.dim('talea status --all')}              the whole catalogue, not just this machine
+
+Columns
+  REPO      repository name
+  BRANCH    the branch checked out right now
+  DEFAULT   the repo's default branch (blank when you are on it)
+  STATE     clean / dirty, and commits ahead or behind origin
+
+Options
+  -g, --group <names>   comma-separated groups
+  -r, --repo <names>    comma-separated repo names
+      --drift           only repos on some other branch
+      --missing         only repos not cloned yet
+      --all             ignore this machine's selection
+`;
+
+export async function run(opts) {
+  const { root, manifest, state } = requireWorkspace();
+  const pool = opts.all ? manifest.repos : machineRepos(manifest, state);
+  const entries = withPaths(manifest, root, selectRepos(manifest, opts, pool));
+
+  const rows = await pooled(entries, defaultJobs(), async ({ repo, dir, cloned }) => {
+    const home = defaultBranch(repo);
+    if (!cloned) {
+      return {
+        repo,
+        missing: true,
+        cells: [c.dim(repo.name), c.dim(glyph.rule), c.dim(home ?? glyph.rule), c.yellow('not cloned')],
+      };
+    }
+
+    const [branch, dirty, delta] = await Promise.all([
+      currentBranch(dir),
+      isDirty(dir),
+      aheadBehind(dir),
+    ]);
+
+    // Drift here means "somewhere other than the default branch", which is a
+    // fact worth showing and not a problem to fix — most of the time it is
+    // exactly where the work is. `--drift` is a filter, never a warning.
+    const drift = home != null && branch !== home;
+    const bits = [dirty ? c.yellow('dirty') : c.dim('clean')];
+    if (delta?.ahead) bits.push(c.cyan(`${glyph.up}${delta.ahead}`));
+    if (delta?.behind) bits.push(c.yellow(`${glyph.down}${delta.behind}`));
+
+    return {
+      repo,
+      drift,
+      missing: false,
+      cells: [
+        c.bold(repo.name),
+        drift ? c.cyan(branch ?? '?') : (branch ?? '?'),
+        drift ? c.dim(home) : c.dim(''),
+        bits.join(' '),
+      ],
+    };
+  });
+
+  let shown = rows;
+  if (opts.drift) shown = rows.filter((r) => r.drift && !r.missing);
+  if (opts.missing) shown = rows.filter((r) => r.missing);
+
+  heading('Workspace');
+  context([
+    ['root', c.bold(root)],
+    ['repos', `${rows.length}`],
+    ['catalogue', c.dim(path.basename(manifest.__source))],
+  ]);
+  plain('');
+
+  if (shown.length === 0) {
+    plain(c.dim('Nothing to show.'));
+    return;
+  }
+
+  // Grouped by folder, so the table reads like the tree on disk.
+  const byGroup = new Map();
+  for (const row of shown) {
+    const g = repoGroup(row.repo);
+    if (!byGroup.has(g)) byGroup.set(g, []);
+    byGroup.get(g).push(row);
+  }
+
+  for (const [name, groupRows] of byGroup) {
+    group(`${groupDir(manifest, name)}/`, groupRows.length);
+    table(
+      groupRows.map((r) => ['  ' + r.cells[0], ...r.cells.slice(1)]),
+      ['  REPO', 'BRANCH', 'DEFAULT', 'STATE'],
+    );
+    plain();
+  }
+
+  const missing = rows.filter((r) => r.missing).length;
+  const working = rows.filter((r) => r.drift && !r.missing).length;
+  const parts = [`${rows.length - missing} cloned`];
+  if (missing) parts.push(c.yellow(`${missing} missing`));
+  if (working) parts.push(c.cyan(`${working} on another branch`));
+  plain(parts.join(c.dim(', ')));
+  if (missing) plain(c.dim('Run `talea sync` to get the missing repos.'));
+}

package/src/commands/sync.js

@@ -0,0 +1,203 @@
+import path from 'node:path';
+
+import { defaultBranch, groupDir, repoGroup } from '../config.js';
+import {
+  aheadBehind,
+  currentBranch,
+  defaultJobs,
+  fetch,
+  ffMerge,
+  hasUpstream,
+  isDirty,
+  isMissingRemote,
+  pooled,
+} from '../git.js';
+import { board } from '../live.js';
+import { c, context, glyph, heading, plain, summary, verdict, warn } from '../log.js';
+import { chooseRepos } from '../select.js';
+import { requireCatalogue, requireWorkspace, selectRepos, withPaths } from '../workspace.js';
+import { adoptInPlace, cloneMissing, writeDocs } from './clone.js';
+
+export const help = `
+${c.bold('talea sync')} — make this machine match the list
+
+  ${c.dim('talea sync')}                      clone what is missing, fast-forward the rest
+  ${c.dim('talea sync --pick')}               change what this machine keeps, then sync
+  ${c.dim('talea sync -g nonstopio')}         only that owner
+  ${c.dim('talea sync --no-clone')}           fast-forward only, clone nothing
+
+The first time you run this on a machine you are asked what it should keep:
+your default set, or a checklist of everything in the catalogue with those
+defaults already ticked. The answer is remembered in ${c.dim('.talea.json')}, so every run
+after that is a bare ${c.dim('talea sync')}.
+
+Options
+  -g, --group <names>   comma-separated groups
+  -r, --repo <names>    comma-separated repo names
+      --pick            re-open the checklist before syncing
+      --no-clone        do not clone anything new
+      --no-adopt        do not look for checkouts to move into place
+      --protocol <p>    ssh (default) or https
+  -j, --jobs <n>        parallel operations (default: one per core, 6-12)
+
+${c.bold('What it will not do')}
+
+Fast-forwards only. A repo that has diverged is reported, never merged
+automatically. A repo with uncommitted changes is fetched and left exactly as
+you left it. A branch with no upstream is fetched and left alone.
+
+It never switches branches. If you are on a feature branch, that is where you
+are working, and a tool that moves you off it mid-task is no better than one
+that clobbers your changes — so it fast-forwards the branch you are on, or
+leaves it alone, and says which.
+`;
+
+export async function run(opts) {
+  const { root, manifest, state } = requireWorkspace();
+  requireCatalogue(manifest);
+
+  const protocol = opts.protocol ?? state.protocol ?? 'ssh';
+  const jobs = Number(opts.jobs ?? defaultJobs());
+
+  const { repos: chosen } = await chooseRepos({ manifest, root, state, opts });
+  const repos = selectRepos(manifest, opts, chosen);
+
+  if (!repos.length) {
+    warn('Nothing selected for this machine. Run `talea sync --pick` to choose.');
+    return;
+  }
+
+  // Adopt before cloning, never after: a repo already on disk must be moved
+  // into place, not cloned a second time beside the work in it.
+  const adoption =
+    opts.adopt === false || opts.clone === false
+      ? { skip: new Map() }
+      : await adoptInPlace({ manifest, root, state, repos, opts });
+
+  // Before the network work, not after: the group doc explains what is about to
+  // land in the folder, and it must also appear on a re-run where nothing is
+  // cloned at all — that is how an existing workspace picks up a new template.
+  writeDocs(manifest, root, repos);
+
+  const entries = withPaths(manifest, root, repos);
+  const missing = entries.filter((e) => !e.cloned && !adoption.skip.has(e.repo.name));
+  const present = entries.filter((e) => e.cloned);
+
+  heading(`Syncing ${root}`);
+  context([
+    ['repos', `${entries.length}`],
+    ['to clone', `${opts.clone === false ? 0 : missing.length}`],
+    ['on disk', `${present.length}`],
+    ['jobs', `${jobs}`],
+  ]);
+
+  const counts = { ok: 0, skipped: adoption.skip.size, failed: 0, okLabel: 'synced' };
+
+  if (missing.length && opts.clone !== false) {
+    plain('');
+    const cloneCounts = { ok: 0, skipped: 0, failed: 0, okLabel: 'cloned' };
+    await cloneMissing({ manifest, root, entries: missing, protocol, jobs, counts: cloneCounts });
+    counts.ok += cloneCounts.ok;
+    counts.skipped += cloneCounts.skipped;
+    counts.failed += cloneCounts.failed;
+  } else if (missing.length) {
+    counts.skipped += missing.length;
+  }
+
+  if (present.length) {
+    plain('');
+    await fastForward({ manifest, root, entries: present, jobs, counts });
+  }
+
+  summary(counts);
+  verdict(counts, {
+    clear: 'ALL CLEAR · every repo is on disk and level with origin',
+    partial: `${counts.skipped} repo(s) were fetched only or left alone — see above`,
+    trouble: `${counts.failed} repo(s) need attention — review above`,
+  });
+}
+
+/**
+ * Fetch each repo once, then fast-forward the branch it is on.
+ *
+ * One fetch, not two: `git pull` fetches again on top of the fetch we already
+ * did, and `ffMerge` merges the ref that fetch just updated. Over twenty repos
+ * on a slow link that is half the wall clock.
+ */
+async function fastForward({ manifest, root, entries, jobs, counts }) {
+  const view = board(
+    entries.map(({ repo }) => ({
+      id: repo.name,
+      group: groupDir(manifest, repoGroup(repo)),
+      label: repo.name,
+    })),
+  );
+
+  await pooled(entries, jobs, async ({ repo, dir }) => {
+    view.set(repo.name, 'busy', 'fetching …');
+    const fetched = await fetch(dir);
+
+    if (fetched.code !== 0) {
+      // A repo the catalogue lists but this account cannot reach is not a
+      // broken checkout — nothing here or in a retry fixes it, so say so and
+      // let the rest of the run stand.
+      if (isMissingRemote(fetched.stderr)) {
+        counts.skipped++;
+        view.set(repo.name, 'skip', 'origin is gone or not granted to you, left as it is');
+        return;
+      }
+      counts.failed++;
+      view.set(repo.name, 'fail', 'fetch failed');
+      view.note(repo.name, fetched.stderr.split('\n')[0] ?? 'fetch failed');
+      return;
+    }
+
+    // Independent reads of the same checkout — no reason to wait for one before
+    // starting the other, and every repo pays for all three.
+    const [branch, dirty, tracked] = await Promise.all([
+      currentBranch(dir),
+      isDirty(dir),
+      hasUpstream(dir),
+    ]);
+
+    // `currentBranch` is `rev-parse --abbrev-ref HEAD`, which reports the
+    // literal string "HEAD" when nothing is checked out. Printing that as if it
+    // were a branch name is how "HEAD tracks no remote branch" happens.
+    const where = branch === 'HEAD' ? 'a detached HEAD' : branch;
+    const home = defaultBranch(repo);
+    const away = home && branch !== home && branch !== 'HEAD' ? c.dim(` (not ${home})`) : '';
+
+    if (dirty) {
+      counts.skipped++;
+      view.set(repo.name, 'warn', `uncommitted changes on ${where}, fetched only`);
+      return;
+    }
+
+    if (!tracked) {
+      // A local-only branch has nothing to fast-forward onto. Saying so beats
+      // the "no upstream configured" git spits out of a bare merge.
+      counts.skipped++;
+      view.set(repo.name, 'skip', `${where} tracks no remote branch, fetched only`);
+      return;
+    }
+
+    const res = await ffMerge(dir);
+    if (res.code !== 0) {
+      counts.failed++;
+      const reason = /diverge|non-fast-forward|not possible to fast-forward/i.test(res.stderr)
+        ? 'diverged from origin — needs a manual merge or rebase'
+        : (res.stderr.split('\n')[0] ?? 'fast-forward failed');
+      view.set(repo.name, 'fail', `${branch} — ${reason}`);
+      return;
+    }
+
+    counts.ok++;
+    const delta = await aheadBehind(dir);
+    const note = res.stdout.includes('Already up to date') ? c.dim('up to date') : c.green('updated');
+    const ahead = delta?.ahead ? c.yellow(` ${glyph.up}${delta.ahead}`) : '';
+    view.set(repo.name, 'ok', `${c.cyan(branch)}${away} ${note}${ahead}`);
+  });
+
+  view.stop();
+  return counts;
+}

package/src/commands/tree.js

@@ -0,0 +1,103 @@
+// The folder tree as it is on disk, with a CLAUDE.md marker on every level.
+//
+// `status` answers "what branch is this on"; `tree` answers "where does this
+// live, and is there a doc there". The group folders are not repos, so nothing
+// else in the tool ever shows them as folders — and they are exactly the levels
+// whose CLAUDE.md is easy to lose, being outside every git repo. See src/docs.js.
+
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+import { groupDir, repoGroup } from '../config.js';
+import { c, context, glyph, heading, icon, plain, table } from '../log.js';
+import { machineRepos, requireWorkspace, selectRepos, withPaths } from '../workspace.js';
+
+export const help = `
+${c.bold('talea tree')} — the workspace folder tree, and who has a CLAUDE.md
+
+  ${c.dim('talea tree')}                     the whole workspace
+  ${c.dim('talea tree -g nonstopio')}        one owner
+
+Every folder from the workspace root down to each repo is listed, with a marker
+saying whether a ${c.bold('CLAUDE.md')} sits in it. The group folders are not git repos, so
+their docs come from the CLI — run \`talea sync\` to drop in any that are new.
+
+Options
+  -g, --group <names>   comma-separated groups
+  -r, --repo <names>    comma-separated repo names
+      --all             the whole catalogue, not just what this machine keeps
+`;
+
+const hasDoc = (dir) => existsSync(path.join(dir, 'CLAUDE.md'));
+
+export function run(opts) {
+  const { root, manifest, state } = requireWorkspace();
+  const pool = opts.all ? manifest.repos : machineRepos(manifest, state);
+  const entries = withPaths(manifest, root, selectRepos(manifest, opts, pool));
+
+  // A node per folder, keyed by path segment, so work/api and work/web share
+  // the one work node instead of printing it twice.
+  const make = (dir) => ({ dir, children: new Map() });
+  const tree = make(root);
+
+  for (const { repo, dir, cloned } of entries) {
+    let node = tree;
+    for (const seg of groupDir(manifest, repoGroup(repo)).split('/')) {
+      if (!node.children.has(seg)) node.children.set(seg, make(path.join(node.dir, seg)));
+      node = node.children.get(seg);
+    }
+    node.children.set(path.basename(dir), { ...make(dir), repo, cloned });
+  }
+
+  const rows = [];
+  const walk = (node, prefix) => {
+    // Sorted, because this claims to show the folders on disk and `ls` does
+    // not print them in catalogue order.
+    const kids = [...node.children.entries()].sort(([a], [b]) =>
+      a.localeCompare(b, 'en', { sensitivity: 'base' }),
+    );
+    kids.forEach(([name, kid], i) => {
+      const last = i === kids.length - 1;
+      const branch = c.dim(last ? '└─ ' : '├─ ');
+      const label = kid.repo
+        ? kid.cloned
+          ? c.bold(name)
+          : c.dim(name)
+        : c.bold(`${name}/`);
+      rows.push({
+        folder: !kid.repo,
+        missing: !hasDoc(kid.dir),
+        cells: [
+          prefix + branch + label,
+          hasDoc(kid.dir) ? `${icon.ok} CLAUDE.md` : c.dim(`${glyph.pending} no CLAUDE.md`),
+          kid.repo && !kid.cloned ? c.yellow('not cloned') : '',
+        ],
+      });
+      walk(kid, prefix + c.dim(last ? '   ' : '│  '));
+    });
+  };
+  walk(tree, '');
+
+  heading('Workspace');
+  context([
+    ['root', c.bold(root)],
+    ['repos', `${entries.length}`],
+  ]);
+  plain('');
+  table(
+    [
+      [c.bold(`${path.basename(root)}/`), hasDoc(root) ? `${icon.ok} CLAUDE.md` : c.dim(`${glyph.pending} no CLAUDE.md`), ''],
+      ...rows.map((r) => r.cells),
+    ],
+  );
+
+  // Only the group folders are counted: a repo's own CLAUDE.md is whoever
+  // wrote it's business, but a missing group one is a file `sync` can drop in.
+  const gaps = rows.filter((r) => r.folder && r.missing).length + (hasDoc(root) ? 0 : 1);
+  plain();
+  plain(
+    gaps
+      ? c.dim(`${gaps} folder${gaps === 1 ? '' : 's'} without a CLAUDE.md — \`talea sync\` writes the ones that ship with the CLI`)
+      : c.dim('every folder has a CLAUDE.md'),
+  );
+}

package/src/commands/upgrade.js

@@ -0,0 +1,84 @@
+import { readUserState, writeUserState } from '../config.js';
+import { c, fail, heading, icon, info, ok, plain, skip, warn } from '../log.js';
+import { installKind, installLatest, isNewer, lookupLatestRelease, pkgJson } from '../update.js';
+
+export const help = `
+${c.bold('talea upgrade')} — update the CLI itself
+
+  ${c.dim('talea upgrade')}                    reinstall from npm at the latest version
+  ${c.dim('talea upgrade --check')}            only report whether one is available
+  ${c.dim('talea upgrade --on')}               turn the daily update notice on
+  ${c.dim('talea upgrade --off')}              turn the daily update notice off
+
+By default the CLI checks for a new version at most once a day and prints a
+one-line notice. It never updates itself silently — this tool moves checkouts
+around, so it should not change behaviour underneath you mid-session.
+
+Set ${c.dim('TALEA_NO_UPDATE_CHECK=1')} to disable the check for a single shell.
+
+Options
+      --check   report only, change nothing
+      --on      enable the daily update notice
+      --off     disable the daily update notice
+`;
+
+export async function run(opts) {
+  const state = readUserState();
+
+  if (opts.on || opts.off) {
+    writeUserState({ ...state, updateCheck: Boolean(opts.on) });
+    ok(`daily update notice ${opts.on ? c.green('on') : c.dim('off')}`);
+    return;
+  }
+
+  const { name, version } = pkgJson();
+  heading('talea upgrade');
+
+  const latest = await lookupLatestRelease(name);
+  if (!latest.version) {
+    const why = {
+      timeout: 'the registry did not answer in time',
+      unpublished: `${name} is not on the registry yet`,
+      unreachable: 'could not reach the registry',
+      untagged: 'the registry has no version for it',
+    };
+    warn(`No version to compare against — ${why[latest.reason] ?? latest.reason}.`);
+    plain(c.dim(`  Installed: ${version}`));
+    return;
+  }
+
+  // Cached for the passive notice, whatever happens next. A `--check` that
+  // silently refreshed nothing would make the daily notice go stale for a day.
+  writeUserState({ ...state, lastCheck: Date.now(), latestSeen: latest.version });
+
+  if (!isNewer(version, latest.version)) {
+    ok(`already on the latest version ${c.dim(version)}`);
+    return;
+  }
+
+  info(`${c.dim(version)} ${icon.arrow} ${c.green(latest.version)}`);
+
+  if (opts.check) {
+    plain(c.dim('\n  Run `talea upgrade` to install it.'));
+    return;
+  }
+
+  // A git checkout is somebody's working copy of this project. Reinstalling
+  // over it from the registry would replace their branch with a release, which
+  // is not an upgrade, it is a data loss with a friendly name.
+  if (installKind() === 'local') {
+    skip('this copy is a git checkout, not an npm install — `git pull` instead');
+    return;
+  }
+
+  plain('');
+  const code = await installLatest(name);
+  plain('');
+  if (code !== 0) {
+    fail(`npm install exited ${code}.`);
+    plain(c.dim(`  Try it yourself: npm install -g ${name}@latest`));
+    process.exitCode = code;
+    return;
+  }
+  ok(`upgraded to ${c.green(latest.version)}`);
+}