moshcode 0.67.0 → 0.69.0

package/README.md

@@ -14,28 +14,6 @@ curl -fsSL https://moshcoding.com/install.sh | sh
 Zero-dependency ESM — all it needs is Node.js 18+. Later: `… | sh -s -- update`
 to upgrade, `… | sh -s -- remove` to uninstall.
 
-## What is in this repo
-
-The CLI is the root package — `bin/`, `src/`, `plugins/` — and that is what
-`npm publish` and the installer above ship. Two apps live alongside it:
-
-| path | what it is | deployed as |
-|---|---|---|
-| `apps/pwa` | the Moshpit registry and account app | pit.moshcode.sh, app.moshcode.sh |
-| `apps/qryptchat-web` | QryptChat, the post-quantum messenger | qrypt.chat |
-
-One repo, but **not one dependency tree**. Each app installs itself, with its
-own lockfile, and the root `pnpm install` does not reach into either. That is
-deliberate on both counts and `pnpm-workspace.yaml` says why. The practical
-rule: run `pnpm install` in the directory you are working in, not at the root
-and not the other way round.
-
-The two apps share a feature rather than code — a person can sign in to
-QryptChat by proving they hold a Moshpit name, which `moshcode name link`
-produces the proof for. The shared half of that is still duplicated in both
-trees; see `pnpm-workspace.yaml` for what has to be fixed before it can be
-lifted into `packages/`.
-
 ## Commands
 
 `moshcode help <command>` drills into any of these — flags, examples and all.
@@ -74,6 +52,7 @@ or miss one that does. A test fails the build when it drifts.
 | `moshcode doh` | hosting | run the DNS-over-HTTPS resolver |
 | `moshcode site` <br>`serve` | hosting | install web-server config for a Moshpit name |
 | `moshcode template` <br>`templates` | hosting | scaffold a stack for a Moshpit-hosted service |
+| `moshcode shorten` <br>`short` `link` | hosting | mint a short link on the pit — /f/<code> follows to your url |
 | `moshcode games` <br>`game` `arcade` | arcade | the moshcode arcade — twenty-two games, no menus |
 | `moshcode pwd` <br>`where` | system | show the current directory and git context |
 | `moshcode engines` | engines | list engines and installation status |
@@ -722,6 +701,35 @@ engines, `mcpjam` tells you whether that server is healthy first — health
 checks, OAuth conformance, tool-surface diffing, and structured triage from the
 terminal or CI. Re-running `moshcode install mcpjam` is also its upgrade path.
 
+### ElevenLabs — Eleven Agents, voices, and speech
+
+```sh
+moshcode install elevenlabs       # npm i -g @elevenlabs/cli
+
+moshcode elevenlabs auth login    # PKCE OAuth, stored in the system keyring
+moshcode elevenlabs agents list
+moshcode elevenlabs agents push   # upload local agent configs to the platform
+moshcode elevenlabs text-to-speech convert …
+```
+
+[ElevenLabs](https://elevenlabs.io/docs/eleven-agents/operate/cli)' CLI manages
+**Eleven Agents** — conversational voice agents you define in files and
+`push`/`pull` against their platform, alongside the knowledge bases, tools,
+tests and phone numbers those agents use. The same binary reaches the rest of
+the API: voices, text-to-speech, dubbing, transcription, music, and workspace
+usage.
+
+They are agents in a different sense than the ones under `/agents`: you deploy
+them and callers talk to them, rather than handing your terminal to one. That is
+why it sits here with the workflow CLIs — every subcommand runs one request and
+exits, so it pipes like the rest of the roster. `--format json` (the default
+when stdout is not a TTY) and `--query` (JMESPath) are what a script wants.
+
+The npm package is a small shim over a native binary shipped as an optional
+dependency, so install it without `--omit=optional` or the `elevenlabs` on your
+PATH will refuse to run. Re-running `moshcode install elevenlabs` is its upgrade
+path.
+
 ### Alchemy — onchain data, wallets, and x402
 
 ```sh
@@ -1271,6 +1279,41 @@ Full walkthrough, including the layer-by-layer way to debug it and the limits
 worth knowing before you build:
 **[docs/hosting-a-moshpit-name.md](docs/hosting-a-moshpit-name.md)**.
 
+### Filtering what resolves
+
+With `dns enable` on, the bridge already sees every lookup this machine makes.
+`dns filter` is the other thing a resolver in that position can do: refuse the
+names that exist only to advertise, track, mine or phish, before a connection is
+ever opened. Nothing is filtered until you ask for it.
+
+```sh
+moshcode dns filter on             # ads, malware, phishing, mining
+moshcode dns filter update         # fetch the lists — nothing downloads on its own
+moshcode dns filter                # what is on, and what it has blocked
+moshcode dns filter test ads.example.com   # would this be blocked, and by which rule
+moshcode dns filter allow news.example     # never block it, whatever any list says
+```
+
+| list | what it blocks |
+|---|---|
+| `ads` | ads and trackers — StevenBlack unified, on by default |
+| `malware` | hosts serving malware — URLhaus, on by default |
+| `phishing` | Phishing Army, on by default |
+| `mining` | in-browser cryptominers, on by default |
+| `adult` `gambling` `social` `fakenews` | opt in by name with `filter add <list>` |
+
+Three things worth knowing. Blocking a name blocks everything under it, and an
+`allow` rule always wins — that is the escape hatch for the day a list someone
+else maintains takes down something you need. Changes reach a running bridge
+within about five seconds, so nothing has to be restarted. And a blocked name is
+answered `NXDOMAIN` by default; `--mode zero` answers `0.0.0.0` instead, and
+`--mode refuse` says `REFUSED`, which is the one a client can tell apart from a
+real absence while you work out whether the filter is what broke something.
+
+`dns filter` never turns DNS routing on — it writes a config and nothing else,
+so on a machine whose resolver has never heard of the bridge it changes nothing.
+Its status says so rather than reporting `on` and leaving you to find out.
+
 ## Shell completion
 
 MoshCode can print context-aware completion scripts for its commands, engines,
@@ -1460,6 +1503,7 @@ chmod +x deploy.mosh
 | `mcpjam(args…)` | drive the MCPJam CLI (test, debug, and validate MCP servers) |
 | `spinifex(args…)` | drive the Spinifex CLI (`spx` — AWS-compatible cloud on your own hardware) |
 | `alchemy(args…)` | drive the Alchemy CLI (onchain data, apps, wallets, x402) |
+| `elevenlabs(args…)` | drive the ElevenLabs CLI (Eleven Agents, voices, TTS, dubbing) |
 | `trade(args…)` | look up tickers, inspect markets, preview/place Alpaca orders |
 | `stocks(args…)` | research tickers via advis0r (`stocksRead` returns the data) |
 | `crypto(args…)` | research crypto pairs via advis0r (`cryptoRead` returns the data) |

package/bin/moshcode.mjs

@@ -36,6 +36,7 @@ import { dnsCommand } from "../src/dns.mjs";
 import { nameCommand } from "../src/name-link.mjs";
 import { templateCommand } from "../src/templates.mjs";
 import { serveCommand } from "../src/serve.mjs";
+import { shortenCommand } from "../src/shorten.mjs";
 import { createDohServer, nginxDohSite, parseDohPort, parseGuardArgs, DEFAULT_DOH_PORT, DOH_PATH } from "../src/doh-server.mjs";
 import { completionScript } from "../src/completion.mjs";
 import { CORE_CLI_COMMAND_NAMES } from "../src/cli-schema.mjs";
@@ -587,6 +588,10 @@ async function main() {
     process.exitCode = (await templateCommand(rest)) || 0;
     return;
   }
+  if (cmd === "shorten" || cmd === "short" || cmd === "link") {
+    process.exitCode = (await shortenCommand(rest, { prefix: `moshcode ${cmd}` })) || 0;
+    return;
+  }
 
   if (cmd === "pwd" || cmd === "where") {
     const location = locate();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moshcode",
-  "version": "0.67.0",
+  "version": "0.69.0",
   "type": "module",
   "description": "moshcode — a metal wrapper for coding engines and native UGig/CoinPay workflow CLIs, with OpenPRD and moshscript",
   "repository": {
@@ -18,7 +18,7 @@
   "scripts": {
     "start": "node bin/moshcode.mjs",
     "demo": "node bin/moshcode.mjs run examples/alive.mosh",
-    "test": "node --test \"test/**/*.test.mjs\" \"tests/**/*.test.mjs\" \"apps/pwa/test/**/*.test.mjs\""
+    "test": "node --test"
   },
   "files": [
     "bin",

package/src/cli-schema.mjs

@@ -455,6 +455,30 @@ export const CORE_CLI_COMMANDS = [
     seeAlso: ["site"],
   },
   { name: "templates", aliasOf: "template", description: "alias for template" },
+  {
+    name: "shorten",
+    group: "hosting",
+    description: "mint a short link on the pit — /f/<code> follows to your url",
+    synopsis: [
+      ["moshcode shorten <url>", "mint one and print it"],
+      ["moshcode shorten <url> --name <name>", "file it under a Moshpit name you hold"],
+      ["moshcode shorten list", "every link you have minted, newest first"],
+      ["moshcode shorten rm <code>", "take one down"],
+    ],
+    flags: [
+      ["--name <name>", "file the link under a Moshpit name you hold", "none"],
+      ["--json", "print the link (or the list) as machine-readable JSON", ""],
+    ],
+    examples: [
+      ["moshcode shorten https://pit.moshcode.sh/n/blue.eggs", "→ pit.moshcode.sh/f/k7mq2xd"],
+      ["moshcode shorten list --json", "pipe your links into a script"],
+      ["moshcode shorten rm k7mq2xd", "the code stops resolving"],
+    ],
+    seeAlso: ["login", "name", "site"],
+    note: "needs an account — run `moshcode login` first. Shortening the same url twice returns the same code.",
+  },
+  { name: "short", aliasOf: "shorten", description: "alias for shorten" },
+  { name: "link", aliasOf: "shorten", description: "alias for shorten" },
   {
     name: "games",
     group: "arcade",
@@ -815,6 +839,17 @@ export const DNS_VERBS = [
   { name: "tlds", description: "list the endings claimed in the Pit" },
   { name: "resolve", description: "what a name resolves to, and why" },
   { name: "trust", description: "trust one name's certificate, after checking it against the registry pin" },
+  {
+    name: "filter",
+    description: "block ads, trackers, malware and phishing at the resolver",
+    synopsis: [
+      ["moshcode dns filter", "what is on, and what it has blocked"],
+      ["moshcode dns filter on [--mode nxdomain|zero|refuse] [--lists a,b]", ""],
+      ["moshcode dns filter update", "fetch the lists — nothing downloads on its own"],
+      ["moshcode dns filter allow <name>", "never block it, whatever any list says"],
+      ["moshcode dns filter test <name>", "would this be blocked, and by which rule"],
+    ],
+  },
 ];
 
 /**
@@ -1166,6 +1201,8 @@ export const PIT_COMMANDS = [
     description: "install moshcode's slash commands into Claude Code" },
   { name: "games", aliases: ["game", "arcade", "play"], args: "[game]", cli: "games",
     description: "the arcade — tetris, invaders, pac-man, frogger, kong, outrun, chess and more" },
+  { name: "shorten", aliases: ["short", "link"], args: "<url> | list | rm <code>", cli: "shorten",
+    description: "mint a short link on the pit — /f/<code> follows to your url" },
   { name: "socials", aliases: ["social"], pitOnly: true,
     description: "list social networks available for posting" },
   { name: "post", args: '<social> "message"', pitOnly: true,

package/src/commands.mjs

@@ -683,6 +683,7 @@ const COMMANDS = [
   cliVerb("mcpjam", "drive the MCPJam CLI (test, debug, and validate MCP servers)"),
   cliVerb("spinifex", "drive the Spinifex CLI (spx — AWS-compatible cloud on your own hardware)"),
   cliVerb("alchemy", "drive the Alchemy CLI (onchain data, apps, wallets, x402)"),
+  cliVerb("elevenlabs", "drive the ElevenLabs CLI (Eleven Agents, voices, TTS, dubbing)"),
   cliVerb("trade", "look up tickers, inspect markets, and preview/place Alpaca orders"),
   cliVerb("pwd", "print the current repo/location"),
 

package/src/completion.mjs

@@ -336,7 +336,7 @@ _moshcode_completion() {
         ;;
       dns)
         if (( COMP_CWORD == 2 )); then
-          choices="enable disable status tlds resolve start install trust"
+          choices="enable disable status tlds resolve start install trust filter"
         elif [[ "$nested" == "resolve" && "$cur" == -* ]]; then
           choices="--json --open --registry"
         fi
@@ -485,7 +485,7 @@ _moshcode() {
       ;;
     dns)
       if (( CURRENT == 3 )); then
-        _values "dns command" enable disable status tlds resolve start install trust
+        _values "dns command" enable disable status tlds resolve start install trust filter
       elif [[ "\${words[3]}" == "resolve" && "$PREFIX" == -* ]]; then
         _values "dns resolve option" --json --open --registry
       else
@@ -566,7 +566,7 @@ complete -c moshcode -n '${atSecondToken("console")}' -a '--url' -d 'print a gat
 complete -c moshcode -n '__moshcode_nested_is console serve' -l port -r -d 'local HTTP port'
 complete -c moshcode -n '__moshcode_nested_is console serve' -l ttyd -r -d 'ttyd host and port'
 complete -c moshcode -n '__moshcode_nested_is console serve' -l bind -r -d 'bind address'
-complete -c moshcode -n '${atSecondToken("dns")}' -a 'enable disable status tlds resolve start install trust' -d 'dns command'
+complete -c moshcode -n '${atSecondToken("dns")}' -a 'enable disable status tlds resolve start install trust filter' -d 'dns command'
 complete -c moshcode -n '__moshcode_nested_is dns resolve' -l json -d 'print JSON'
 complete -c moshcode -n '__moshcode_nested_is dns resolve' -l open -d 'open a parked name in the Pit'
 complete -c moshcode -n '__moshcode_nested_is dns resolve' -l registry -r -d 'registry base URL'

package/src/dns-filter-cli.mjs

@@ -0,0 +1,407 @@
+/**
+ * `moshcode dns filter` — the verb over the policy in `dns-filter.mjs`.
+ *
+ * Kept out of `dns.mjs` for the same reason the policy is: that file is vendored
+ * from `@moshcoder/moshpit-dns` and is ported by hand, so it gets the hook and
+ * nothing else.
+ *
+ * The thing this command has to be honest about, in every subcommand that could
+ * mislead, is that a filter only filters what passes through the bridge. Writing
+ * `enabled: true` into a file on a machine whose resolver has never heard of the
+ * bridge changes nothing at all, and a status line that says `on` without saying
+ * that is the same lie as `bridge started` being printed by a run that never
+ * wrote the routing.
+ */
+
+import {
+  BLOCK_MODES,
+  CATALOG_BY_ID,
+  DEFAULT_CATEGORIES,
+  DEFAULT_MODE,
+  FILTER_CATALOG,
+  configPath,
+  filterDir,
+  listPath,
+  listStatus,
+  matchSuffix,
+  normaliseName,
+  readCachedList,
+  readConfig,
+  readStats,
+  updateList,
+  writeConfig,
+} from "./dns-filter.mjs";
+import { DEFAULT_HOST, DEFAULT_PORT, bridgePresence, describeBridge, parseDnsPort } from "./dns.mjs";
+import { daemonStatus } from "./dns-system.mjs";
+
+const USAGE = `moshcode dns filter — block names before they are ever looked up
+
+  moshcode dns filter                  what is on, what it has blocked
+  moshcode dns filter on               start filtering (${DEFAULT_CATEGORIES.join(", ")})
+  moshcode dns filter off              stop filtering; keeps the lists and the rules
+  moshcode dns filter lists            the catalogue, and what is cached here
+  moshcode dns filter add <list>...    turn a category on
+  moshcode dns filter remove <list>... turn one off
+  moshcode dns filter update [<list>]  fetch the lists — nothing downloads on its own
+  moshcode dns filter block <name>...  always block this name and everything under it
+  moshcode dns filter allow <name>...  never block it, whatever any list says
+  moshcode dns filter unblock <name>...
+  moshcode dns filter unallow <name>...
+  moshcode dns filter test <name>      would this be blocked, and by which rule
+
+  --mode nxdomain|zero|refuse   how a blocked name is answered (default ${DEFAULT_MODE})
+  --lists a,b                   with \`on\`: the categories to run, instead of the default
+  --json                        with status, lists or test: one document for scripts
+
+Filtering happens in the bridge, so it applies to exactly the queries the bridge
+sees: with \`dns enable\` on, that is every lookup this machine makes. Changes are
+picked up by a running bridge within about five seconds — no restart, no reload.
+This command never turns DNS routing on.`;
+
+const flagValue = (args, name) => {
+  const index = args.indexOf(name);
+  if (index >= 0 && args[index + 1]) return args[index + 1];
+  const inline = args.find((a) => a.startsWith(`${name}=`));
+  return inline ? inline.slice(name.length + 1) : null;
+};
+
+const positional = (args) => {
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--mode" || arg === "--lists" || arg === "--port") { i += 1; continue; }
+    if (arg.startsWith("-")) continue;
+    out.push(arg);
+  }
+  return out;
+};
+
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+
+/**
+ * Is there a bridge that could be applying this policy?
+ *
+ * Probed rather than read from the pidfile. A bridge started by systemd, by
+ * hand, or by an escalated `dns enable` leaves no pidfile this process can see,
+ * and reporting "no bridge" for a machine that is filtering every lookup would
+ * send someone to fix the wrong thing.
+ */
+async function bridgeLine({ host, port, presence = bridgePresence, recorded = daemonStatus }) {
+  try {
+    const found = await presence({ host, port, recorded: await recorded().catch(() => undefined) });
+    return { found, text: describeBridge(found, { host, port }) };
+  } catch {
+    return { found: { kind: "unknown", answering: false }, text: "could not be determined" };
+  }
+}
+
+export async function filterCommand(args = [], out = console.log, deps = {}) {
+  const {
+    dir = filterDir(),
+    fetchImpl = fetch,
+    presence = bridgePresence,
+    recorded = daemonStatus,
+    now = () => new Date(),
+  } = deps;
+
+  const sub = positional(args)[0] || "status";
+  const rest = positional(args).slice(1);
+  const json = args.includes("--json");
+  const host = DEFAULT_HOST;
+  const port = parseDnsPort(flagValue(args, "--port")) || DEFAULT_PORT;
+
+  if (sub === "help" || args.includes("--help") || args.includes("-h")) {
+    out(USAGE);
+    return 0;
+  }
+
+  let config;
+  try {
+    config = await readConfig(dir);
+  } catch (err) {
+    out(`! ${err.message}`);
+    out(`  fix or remove ${configPath(dir)} — filtering is off until it parses`);
+    return 1;
+  }
+
+  /* ------------------------------------------------------------------ lists */
+
+  if (sub === "lists") {
+    const rows = [];
+    for (const entry of FILTER_CATALOG) {
+      const cached = await listStatus(dir, entry.id);
+      rows.push({ ...entry, ...cached, on: config.categories.includes(entry.id) });
+    }
+    if (json) {
+      out(JSON.stringify({ dir, categories: config.categories, lists: rows }, null, 2));
+      return 0;
+    }
+    for (const row of rows) {
+      const state = row.on ? "on " : "off";
+      const cache = row.cached
+        ? `cached ${row.bytes < 1024 ? "<1" : Math.round(row.bytes / 1024)}k, ${row.at.slice(0, 10)}`
+        : "not fetched";
+      out(`  ${state}  ${row.id.padEnd(9)} ${row.title.padEnd(22)} ${cache}`);
+      out(`       ${row.note}`);
+    }
+    out("");
+    out("fetch what is on with: moshcode dns filter update");
+    return 0;
+  }
+
+  /* ------------------------------------------------------------------- test */
+
+  if (sub === "test") {
+    const name = rest[0];
+    if (!name) {
+      out("usage: moshcode dns filter test <name>");
+      return 1;
+    }
+    const clean = normaliseName(name);
+    if (!clean) {
+      out(`! ${name} is not a name this can match`);
+      return 1;
+    }
+    // Read straight from the cache rather than through a filter handle: this
+    // has to answer for a category that is cached but switched off, so that
+    // "why is this not blocked" has an answer other than silence.
+    const allowed = matchSuffix(clean, new Set(config.allow));
+    const blockedBy = matchSuffix(clean, new Set(config.block));
+    const hits = [];
+    if (blockedBy) hits.push({ list: "custom", rule: blockedBy, on: true });
+    for (const entry of FILTER_CATALOG) {
+      const set = await readCachedList(dir, entry.id);
+      if (!set) continue;
+      const rule = matchSuffix(clean, set);
+      if (rule) hits.push({ list: entry.id, rule, on: config.categories.includes(entry.id) });
+    }
+    const live = hits.filter((h) => h.on);
+    const blocked = config.enabled && !allowed && live.length > 0;
+
+    if (json) {
+      out(JSON.stringify({ name: clean, blocked, mode: config.mode, allowed, hits }, null, 2));
+      return 0;
+    }
+    if (!config.enabled) out("filtering is off — this is what would happen with it on");
+    if (allowed) {
+      out(`${clean} — allowed by your rule \`${allowed}\``);
+      if (hits.length) out(`  (${plural(hits.length, "list")} would otherwise block it: ${hits.map((h) => h.list).join(", ")})`);
+      return 0;
+    }
+    if (!live.length) {
+      out(`${clean} — not blocked`);
+      const dormant = hits.filter((h) => !h.on);
+      if (dormant.length) {
+        out(`  it is in ${dormant.map((h) => h.list).join(", ")}, which ${dormant.length === 1 ? "is" : "are"} not switched on`);
+        out(`  turn one on with: moshcode dns filter add ${dormant[0].list}`);
+      }
+      return 0;
+    }
+    out(`${clean} — blocked by ${live[0].list} (rule \`${live[0].rule}\`), answered as ${config.mode}`);
+    if (live.length > 1) out(`  also in: ${live.slice(1).map((h) => h.list).join(", ")}`);
+    out(`  keep it working with: moshcode dns filter allow ${clean}`);
+    return 0;
+  }
+
+  /* ----------------------------------------------------------------- update */
+
+  if (sub === "update") {
+    const wanted = rest.length ? rest : config.categories;
+    if (!wanted.length) {
+      out("no categories are on — nothing to fetch");
+      out(`  turn one on with: moshcode dns filter add ${DEFAULT_CATEGORIES[0]}`);
+      return 1;
+    }
+    const unknown = wanted.filter((id) => !CATALOG_BY_ID.has(id));
+    if (unknown.length) {
+      out(`! no such list: ${unknown.join(", ")}`);
+      out(`  the catalogue is: ${FILTER_CATALOG.map((e) => e.id).join(", ")}`);
+      return 1;
+    }
+    let failed = 0;
+    for (const id of wanted) {
+      try {
+        const result = await updateList(dir, id, { fetchImpl });
+        out(`ok ${id.padEnd(9)} ${result.count.toLocaleString()} names`);
+      } catch (err) {
+        failed += 1;
+        // Named and survived rather than thrown: one dead source should not
+        // stop the other seven from refreshing.
+        out(`!  ${id.padEnd(9)} ${err?.message || err}`);
+      }
+    }
+    await writeConfig(dir, { ...config, updatedAt: now().toISOString() });
+    if (failed) out(`\n${plural(failed, "list")} did not refresh — the cached copy is still in use`);
+    if (config.enabled) out("\na running bridge picks these up within about five seconds");
+    else out("\nfiltering is off — turn it on with: moshcode dns filter on");
+    return failed === wanted.length ? 1 : 0;
+  }
+
+  /* --------------------------------------------------------------- on / off */
+
+  if (sub === "on" || sub === "off") {
+    const mode = flagValue(args, "--mode");
+    if (mode && !BLOCK_MODES.includes(mode)) {
+      out(`! --mode must be one of: ${BLOCK_MODES.join(", ")}`);
+      return 1;
+    }
+    const chosen = flagValue(args, "--lists");
+    const categories = chosen
+      ? chosen.split(",").map((s) => s.trim()).filter(Boolean)
+      : (config.categories.length ? config.categories : DEFAULT_CATEGORIES.slice());
+    const unknown = categories.filter((id) => !CATALOG_BY_ID.has(id));
+    if (unknown.length) {
+      out(`! no such list: ${unknown.join(", ")}`);
+      out(`  the catalogue is: ${FILTER_CATALOG.map((e) => e.id).join(", ")}`);
+      return 1;
+    }
+    const next = await writeConfig(dir, {
+      ...config,
+      enabled: sub === "on",
+      mode: mode || config.mode,
+      categories,
+    });
+    if (sub === "off") {
+      out("filtering off — lists and rules kept, nothing is being blocked");
+      return 0;
+    }
+
+    const missing = [];
+    for (const id of next.categories) {
+      if (!(await listStatus(dir, id)).cached) missing.push(id);
+    }
+    out(`filtering on — ${next.categories.join(", ")}, blocked names answered as ${next.mode}`);
+    if (missing.length) {
+      // The state that would otherwise read as success and block nothing.
+      out(`! ${plural(missing.length, "list")} ${missing.length === 1 ? "has" : "have"} never been fetched: ${missing.join(", ")}`);
+      out("  nothing is blocked from them until you run: moshcode dns filter update");
+    }
+    const bridge = await bridgeLine({ host, port, presence, recorded });
+    if (!bridge.found.answering) {
+      out(`! no bridge is answering on ${host}:${port} — ${bridge.text}`);
+      out("  the filter runs inside the bridge, so nothing is filtered until one does.");
+      out("  turn DNS on deliberately with: sudo moshcode dns enable");
+    } else if (bridge.found.forwards === false) {
+      out(`! the bridge on ${host}:${port} answers Moshpit names but does not forward clearnet ones`);
+      out("  it is not in the path of ordinary lookups, so only Moshpit names are filtered");
+    }
+    return 0;
+  }
+
+  /* ------------------------------------------------------ categories, rules */
+
+  const listVerbs = { add: true, remove: true };
+  if (listVerbs[sub]) {
+    if (!rest.length) {
+      out(`usage: moshcode dns filter ${sub} <list>...`);
+      return 1;
+    }
+    const unknown = rest.filter((id) => !CATALOG_BY_ID.has(id));
+    if (unknown.length) {
+      out(`! no such list: ${unknown.join(", ")}`);
+      out(`  the catalogue is: ${FILTER_CATALOG.map((e) => e.id).join(", ")}`);
+      return 1;
+    }
+    const set = new Set(config.categories);
+    for (const id of rest) (sub === "add" ? set.add(id) : set.delete(id));
+    const next = await writeConfig(dir, { ...config, categories: Array.from(set) });
+    out(next.categories.length ? `lists: ${next.categories.join(", ")}` : "lists: none");
+    if (sub === "add") {
+      const missing = [];
+      for (const id of rest) if (!(await listStatus(dir, id)).cached) missing.push(id);
+      if (missing.length) out(`  fetch ${missing.join(", ")} with: moshcode dns filter update ${missing.join(" ")}`);
+    }
+    return 0;
+  }
+
+  const ruleVerbs = {
+    block: { field: "block", add: true, said: "blocked" },
+    allow: { field: "allow", add: true, said: "allowed" },
+    unblock: { field: "block", add: false, said: "no longer blocked by rule" },
+    unallow: { field: "allow", add: false, said: "no longer allowed by rule" },
+  };
+  if (ruleVerbs[sub]) {
+    const { field, add, said } = ruleVerbs[sub];
+    if (!rest.length) {
+      out(`usage: moshcode dns filter ${sub} <name>...`);
+      return 1;
+    }
+    const names = [];
+    for (const raw of rest) {
+      const clean = normaliseName(raw);
+      if (!clean) {
+        out(`! ${raw} is not a name`);
+        return 1;
+      }
+      names.push(clean);
+    }
+    const set = new Set(config[field]);
+    for (const name of names) (add ? set.add(name) : set.delete(name));
+    const next = await writeConfig(dir, { ...config, [field]: Array.from(set) });
+    out(`${names.join(", ")} — ${said}${add ? ", along with everything under it" : ""}`);
+    out(`  ${plural(next[field].length, "rule")} in your ${field} list`);
+    if (!next.enabled) out("  filtering is off, so this takes effect when you turn it on");
+    return 0;
+  }
+
+  /* ----------------------------------------------------------------- status */
+
+  if (sub !== "status") {
+    out(`unknown: moshcode dns filter ${sub}`);
+    out(USAGE);
+    return 1;
+  }
+
+  const stats = await readStats(dir);
+  const cached = [];
+  for (const id of config.categories) cached.push(await listStatus(dir, id));
+  const bridge = await bridgeLine({ host, port, presence, recorded });
+
+  if (json) {
+    out(JSON.stringify({
+      dir,
+      enabled: config.enabled,
+      mode: config.mode,
+      categories: config.categories,
+      block: config.block,
+      allow: config.allow,
+      lists: cached,
+      bridge: { kind: bridge.found.kind, answering: Boolean(bridge.found.answering), forwards: Boolean(bridge.found.forwards) },
+      stats,
+    }, null, 2));
+    return 0;
+  }
+
+  out(`filter    ${config.enabled ? `on — answering blocked names as ${config.mode}` : "off"}`);
+  out(`bridge    ${bridge.text}`);
+  out(`lists     ${config.categories.length ? config.categories.join(", ") : "none"}`);
+  const never = cached.filter((c) => !c.cached);
+  if (never.length) out(`          ! never fetched: ${never.map((c) => c.id).join(", ")} — run \`moshcode dns filter update\``);
+  if (config.block.length || config.allow.length) {
+    out(`rules     ${plural(config.block.length, "block")}, ${plural(config.allow.length, "allow")}`);
+  }
+  if (stats) {
+    const share = stats.queries ? `${((stats.blocked / stats.queries) * 100).toFixed(1)}%` : "0%";
+    out(`blocked   ${stats.blocked.toLocaleString()} of ${stats.queries.toLocaleString()} queries (${share}) as of ${String(stats.at).slice(0, 19).replace("T", " ")}`);
+    for (const [id, count] of Object.entries(stats.byList || {}).sort((a, b) => b[1] - a[1])) {
+      out(`          ${String(count).padStart(7)}  ${id}`);
+    }
+    if (stats.recent?.length) {
+      out("recent    " + stats.recent.slice(0, 5).map((r) => r.name).join(", "));
+    }
+  } else if (config.enabled) {
+    // The counters are written by the bridge, so their absence is a fact about
+    // the bridge rather than about the filter.
+    out("blocked   no counts yet — the bridge writes them once it is answering");
+  }
+
+  if (config.enabled && !bridge.found.answering) {
+    out("");
+    out(`! nothing is being filtered: the filter runs inside the bridge and none is answering on ${host}:${port}`);
+    out("  turn DNS on deliberately with: sudo moshcode dns enable");
+  }
+  out("");
+  out(`config    ${configPath(dir)}`);
+  out(`lists at  ${listPath(dir, "<list>")}`);
+  return 0;
+}