cli-tools autoupdate: keep the checkout current on a timer

`cli-tools autoupdate --install` writes a systemd user timer that runs
`cli-tools update --auto` daily. `--hours N` changes the interval,
`--remove` takes it away, bare `autoupdate` shows when it last ran.

Almost all of `update --auto` is about deciding not to act, and that is
the point. The install is symlinks into a working tree, so updating
moves somebody's real checkout — an unattended pull that discards work
is far worse than a command being a day out of date. It proceeds only
when the tree is clean, HEAD is the default branch, nothing is unpushed,
and it is genuinely behind. Every refusal names the specific blocker,
because the failure mode this guards against is concluding auto-update
is broken while it is working exactly as designed.

Two things that would have made this silently useless:

- The unit bakes today's PATH in. A user unit starts with roughly
  /usr/bin:/bin, while every command here runs through a `npx --yes tsx`
  shebang whose node is a version manager's shim under $HOME. Without
  it the timer fires on schedule, fails to find node, and nothing looks
  wrong anywhere.
- Status is read from `--porcelain=v2`, not the human-readable "Your
  branch is behind by N commits" line, which is localised — on a
  non-English machine that check would never fire.

The stamp is written before the work rather than after, so a fetch that
fails does not mean a retry on every invocation while the network is
down. A stamp in the future reads as due, since a moved clock could
otherwise stall updates for days.

Also refreshes the /tools:install command doc, whose table had gone
three commands stale, and the key list in `cli-tools --help`, which
still named only openai and anthropic.

Suite is 274 tests.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: ralyodio

README.md

@@ -50,8 +50,38 @@ cli-tools list                 # * runs from here, ! is shadowed by another copy
 cli-tools aliases --install    # /blog /free /merge /prs /whois
 cli-tools config               # API keys: what is set, and where it came from
 cli-tools update               # git pull, reinstall, relink
+cli-tools autoupdate --install # …or have a timer do that daily
 ```
 
+### Keeping it current
+
+`cli-tools autoupdate --install` writes a systemd **user** timer that runs
+`cli-tools update --auto` once a day — `--hours N` to change the interval,
+`--remove` to take it away, bare `autoupdate` to see when it last ran.
+
+`update --auto` is mostly a set of reasons not to act, and deliberately so. The
+install is symlinks into a working tree, so updating moves your actual checkout;
+an unattended pull that discards work is much worse than a command being a day
+old. It proceeds only on a clean tree, on the default branch, with nothing
+unpushed, and only when genuinely behind — and names the blocker otherwise, on
+stderr, which is the journal when a timer runs it:
+
+```sh
+cli-tools update --auto --force        # ignore the once-a-day stamp
+journalctl --user -u cli-tools-update  # what it decided, and why
+```
+
+A checkout parked on a feature branch is therefore left alone. That is the
+design rather than a failure.
+
+The unit **carries your current `PATH`**, because a user unit otherwise starts
+with roughly `/usr/bin:/bin` while every command here runs through a `npx --yes
+tsx` shebang whose node is usually a version manager's shim under `$HOME`. Get
+that wrong and the timer fires perfectly on schedule, fails to find node, and
+nothing anywhere looks broken. Note also that **user timers stop at logout**
+unless lingering is on (`loginctl enable-linger`, which needs root);
+`Persistent=true` means it catches up at the next login instead.
+
 <details>
 <summary>From a clone, for development</summary>
 

bin/cli-tools.ts

@@ -16,10 +16,21 @@
  */
 
 import { spawnSync } from 'node:child_process';
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 
-import { parseArgs, UsageError } from '../src/args.ts';
+import { integer, parseArgs, UsageError } from '../src/args.ts';
+import {
+  SERVICE_NAME,
+  TIMER_NAME,
+  decide,
+  formatInterval,
+  isDue,
+  parseStatus,
+  renderService,
+  renderTimer,
+} from '../src/selfupdate.ts';
 import {
   credentialsPath,
   keyStates,
@@ -42,7 +53,8 @@ import {
 
 const USAGE = `Usage:
   cli-tools list
-  cli-tools update
+  cli-tools update [--auto]
+  cli-tools autoupdate [--install [--hours N] | --remove]
   cli-tools link [--force]
   cli-tools unlink
   cli-tools aliases [--install]
@@ -52,6 +64,9 @@ const USAGE = `Usage:
 Commands:
   list      Every command here, and whether it is on PATH
   update    git pull, reinstall dependencies, relink
+            "--auto" is the unattended form: at most once a day, and only on a
+            clean checkout of the default branch with nothing unpushed
+  autoupdate  A systemd user timer that runs "update --auto" for you
   link      Symlink the commands into ~/.local/bin
   unlink    Remove the symlinks we own
   aliases   Print the moshcode pit aliases, or write them with --install
@@ -62,17 +77,24 @@ Commands:
 Keys (config set <key>):
   openai      OPENAI_API_KEY      generate-names
   anthropic   ANTHROPIC_API_KEY   generate-names
+  perplexity  PERPLEXITY_API_KEY  ask-web
+  elevenlabs  ELEVENLABS_API_KEY  tts
 
 Options:
   --force   link: take over a symlink owned by another checkout
+            update --auto: check now, ignoring the once-a-day stamp
   --install aliases: merge them into ~/.moshcode/aliases.json
+            autoupdate: write and enable the systemd user timer
+  --remove  autoupdate: disable it and delete the units
+  --hours N autoupdate --install: how often to check (default: 24)
+  --auto    update: the unattended form, safe to run from a timer
   --json    list/aliases/config: machine-readable (config never prints a key)
   -h, --help
 `;
 
 const SPEC = {
-  boolean: ['--force', '--install', '--json', '-h', '--help'],
-  string: [],
+  boolean: ['--force', '--install', '--json', '--auto', '--remove', '-h', '--help'],
+  string: ['--hours'],
 } as const;
 
 function runLinks(root: string, args: readonly string[]): number {
@@ -105,6 +127,147 @@ function update(root: string): number {
   return runLinks(root, []);
 }
 
+/** Where the last automatic check is remembered. */
+function stampPath(env: NodeJS.ProcessEnv = process.env): string {
+  const state = env.XDG_STATE_HOME || join(env.HOME ?? homedir(), '.local', 'state');
+  return join(state, 'cli-tools', 'update-stamp');
+}
+
+function readStamp(): number | null {
+  try {
+    return Number(readFileSync(stampPath(), 'utf8').trim());
+  } catch {
+    return null;
+  }
+}
+
+function writeStamp(now: number): void {
+  const path = stampPath();
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${now}\n`);
+}
+
+/** `origin/HEAD` when the remote publishes it, else master. */
+function defaultBranch(root: string): string {
+  const result = spawnSync('git', ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], {
+    cwd: root,
+    encoding: 'utf8',
+  });
+  if (result.status !== 0) return 'master';
+  const name = (result.stdout ?? '').trim().split('/').pop();
+  return name || 'master';
+}
+
+/**
+ * The unattended path: check rarely, move only when it is unambiguously safe.
+ *
+ * Every refusal is printed rather than swallowed. This normally runs from a
+ * timer, where stderr lands in the journal, and "why is my checkout not
+ * updating" is otherwise unanswerable without reproducing the decision by hand.
+ */
+function autoUpdate(root: string, force: boolean): number {
+  const now = Date.now();
+  if (!force && !isDue(readStamp(), now)) return 0;
+
+  // Stamped before the work, not after: a fetch that fails should not mean a
+  // retry on every single invocation for as long as the network is down.
+  writeStamp(now);
+
+  const fetched = spawnSync('git', ['fetch', '--quiet'], { cwd: root, encoding: 'utf8' });
+  if (fetched.status !== 0) {
+    process.stderr.write(`update --auto: git fetch failed — ${(fetched.stderr ?? '').trim()}\n`);
+    return 0;
+  }
+
+  const status = spawnSync('git', ['status', '--porcelain=v2', '--branch'], {
+    cwd: root,
+    encoding: 'utf8',
+  });
+  if (status.status !== 0) {
+    process.stderr.write('update --auto: could not read git status\n');
+    return 0;
+  }
+
+  const decision = decide(parseStatus(status.stdout ?? ''), {
+    defaultBranch: defaultBranch(root),
+  });
+  if (decision.action === 'skip') {
+    process.stderr.write(`update --auto: skipped — ${decision.reason}\n`);
+    return 0;
+  }
+
+  process.stderr.write(`update --auto: ${decision.reason}\n`);
+  return update(root);
+}
+
+function unitDir(env: NodeJS.ProcessEnv = process.env): string {
+  return join(env.XDG_CONFIG_HOME || join(env.HOME ?? homedir(), '.config'), 'systemd', 'user');
+}
+
+function systemctl(args: readonly string[]): number {
+  const result = spawnSync('systemctl', ['--user', ...args], { stdio: 'inherit' });
+  if (result.error) {
+    process.stderr.write('autoupdate: systemctl --user is not available on this machine.\n');
+    return 1;
+  }
+  return result.status ?? 1;
+}
+
+/**
+ * Install, remove or report the timer.
+ *
+ * systemd rather than cron because the units are declarative, `Persistent=true`
+ * catches up a machine that was asleep, and the output of a failed run is in
+ * the journal instead of an email nobody configured.
+ */
+function autoupdate(root: string, flags: Set<string>, hours: number): number {
+  const dir = unitDir();
+  const service = join(dir, SERVICE_NAME);
+  const timer = join(dir, TIMER_NAME);
+
+  if (flags.has('--remove')) {
+    systemctl(['disable', '--now', TIMER_NAME]);
+    for (const path of [service, timer]) {
+      try {
+        rmSync(path);
+      } catch {
+        // Already gone is the outcome we wanted.
+      }
+    }
+    systemctl(['daemon-reload']);
+    process.stdout.write('autoupdate: removed\n');
+    return 0;
+  }
+
+  if (flags.has('--install')) {
+    // The installed symlink is preferred over this checkout's path: it is the
+    // name the operator actually uses, and it keeps working if the checkout
+    // moves and is re-linked.
+    const linked = join(process.env.HOME ?? homedir(), '.local', 'bin', 'cli-tools');
+    const exec = existsSync(linked) ? linked : join(root, 'bin', 'cli-tools.ts');
+
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(service, renderService(exec, process.env.PATH));
+    writeFileSync(timer, renderTimer(hours * 3600));
+
+    if (systemctl(['daemon-reload']) !== 0) return 1;
+    if (systemctl(['enable', '--now', TIMER_NAME]) !== 0) return 1;
+
+    process.stdout.write(`autoupdate: enabled, every ${formatInterval(hours * 3600)}\n${timer}\n`);
+    process.stdout.write(
+      'Note: user timers stop when you log out unless lingering is on\n' +
+        '      (`loginctl enable-linger` — needs root).\n',
+    );
+    return 0;
+  }
+
+  if (!existsSync(timer)) {
+    process.stdout.write('autoupdate: not installed — `cli-tools autoupdate --install`\n');
+    return 0;
+  }
+  return systemctl(['list-timers', '--all', TIMER_NAME]);
+}
+
 function writeAliases(): number {
   const path = aliasesPath();
   let existing: Record<string, string> = {};
@@ -382,7 +545,9 @@ export async function run(argv: readonly string[]): Promise<number> {
   // Anything that is not one of ours is one of the commands: pass it straight
   // through, arguments and streams untouched, so `cli-tools gh-prs --orgs x`
   // behaves exactly as `gh-prs --orgs x` does.
-  const known = new Set(['list', 'update', 'link', 'unlink', 'aliases', 'config', 'where']);
+  const known = new Set([
+    'list', 'update', 'autoupdate', 'link', 'unlink', 'aliases', 'config', 'where',
+  ]);
   if (!known.has(command)) {
     const match = commands(root).find((entry) => entry.name === command);
     if (!match) {
@@ -465,7 +630,16 @@ export async function run(argv: readonly string[]): Promise<number> {
     }
 
     case 'update':
-      return update(root);
+      return options.flags.has('--auto')
+        ? autoUpdate(root, options.flags.has('--force'))
+        : update(root);
+
+    case 'autoupdate':
+      return autoupdate(
+        root,
+        options.flags,
+        integer(options.values, '--hours', 24, { min: 1, max: 24 * 30 }),
+      );
 
     case 'link':
       return runLinks(root, options.flags.has('--force') ? ['--force'] : []);

plugins/tools/commands/install.md

@@ -34,14 +34,22 @@ The installer clones to `~/.local/share/cli-tools` (override with
 
 | Command | What it does |
 | --- | --- |
+| `affiliate` | Work through a list of programs you mean to sign up for |
+| `ask-web` | Answer a question from the live web, with its sources |
 | `blog-post` | Publish to a plain-HTML blog without breaking the feed |
 | `cli-tools` | This dispatcher |
 | `domainfree` | Which of these domains you can actually register |
 | `domainjson` | whois-style, JSON-first name lookup |
+| `generate-names` | Turn a sentence about a product into candidate names |
 | `gh-prs` | Every open PR across the owners you name |
 | `gh-prs-fix-all` | Repair the open scan PRs that are broken because of us |
 | `gh-prs-merge` | Squash-merge the PRs that are genuinely ready |
 | `tcfeed` | Find repositories worth scanning, scan them, print a shortlist |
+| `tts` | Read text aloud and keep the audio |
+
+Rather than listing them by hand, `cli-tools list` reads `bin/` — a new command
+is a new file there and nothing else has to be edited, so that output is right
+when this table has gone stale.
 
 Check what took:
 
@@ -109,12 +117,42 @@ been sourced first. The aliases only buy you a shorter word.
 ## Keeping it current
 
 ```bash
-cli-tools update        # git pull, reinstall dependencies, relink
+cli-tools autoupdate --install     # a systemd user timer; check daily from now on
+cli-tools update                   # or do it now, by hand
 ```
 
 `update` refuses to move a dirty or diverged checkout rather than discarding
 work. If it stops, sort the checkout out at `cli-tools where` and retry.
 
+### Auto-update
+
+`cli-tools autoupdate --install` writes a systemd **user** timer that runs
+`cli-tools update --auto` once a day (`--hours N` to change it, `--remove` to
+take it away, and bare `autoupdate` to see when it last ran).
+
+`update --auto` is the unattended form, and almost all of it is about deciding
+*not* to act. The install is symlinks into a working tree, so updating means
+moving somebody's real checkout — an unattended pull that discards work is far
+worse than a command being a day out of date. It proceeds only when all of
+these hold, and names the one in the way otherwise:
+
+- the tree is clean,
+- HEAD is the default branch (`origin/HEAD`, else `master`),
+- nothing is unpushed,
+- and it is genuinely behind.
+
+So on a checkout parked on a feature branch it does nothing and says so. That is
+the design, not a failure — the refusals go to stderr, which is the journal when
+the timer runs it (`journalctl --user -u cli-tools-update`).
+
+Two things worth knowing. The unit **bakes today's `PATH` in**, because a user
+unit otherwise starts with roughly `/usr/bin:/bin` while these commands run
+through a `npx --yes tsx` shebang whose node is usually a version manager's shim
+under `$HOME` — without it the timer fires on schedule, fails to find node, and
+nothing looks wrong. And **user timers stop when you log out** unless lingering
+is enabled (`loginctl enable-linger`, which needs root); on a laptop that is
+fine, since `Persistent=true` makes it catch up on the next login.
+
 Note that the installed command runs **whatever branch the checkout is on** —
 these are symlinks into a working tree, not a copied build. A checkout parked on
 an old branch silently runs old code, so `cli-tools where` and a `git branch