@assuredloop/orca-bot-kit 0.1.0 → 0.3.0

package/src/hooks.js

@@ -0,0 +1,257 @@
+// The kit's own hook, in the bot's folder and nowhere else (ADR 0020).
+//
+// Both harnesses read a hooks file out of the folder a session starts in, and
+// every session starts at its bot home, so the bot folder is where the kit's
+// hook goes: versioned with the bot, and never in the user's own settings,
+// which other tools already fight over.
+//
+// The two files hold the same JSON shape and the kit asks each for the same
+// one event. Proved live on 2026-09-20 (Claude Code 2.1.278, Codex 0.155.1): a
+// hook in each file runs, is handed the session id on stdin, and can answer
+// with text the session then has (tech notes, sections 2 and 3).
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+
+import { leadsOutside } from './bot.js';
+import { ownCli, shellWord } from './launch.js';
+
+/** Where each harness reads a project's hooks, inside the bot home. */
+const HOOK_FILE = { claude: '.claude/settings.json', codex: '.codex/hooks.json' };
+
+/**
+ * The one thing the kit asks to be told: a session beginning. Both harnesses
+ * report it whenever a session starts, resumes or is begun again by the user —
+ * Claude Code's `/clear` and Codex's `/new` — and hand over the id it is
+ * running as, which is all the book needs.
+ */
+const EVENT = 'SessionStart';
+
+/** How long the harness gives the hook before it goes on without it. */
+const TIMEOUT = 10;
+
+/**
+ * What the hook runs: the CLI that wrote it, by its own path, so the session
+ * reports to the kit that set it up and not to whatever `obk` PATH finds in the
+ * harness's shell (#220). `|| true` and a quiet stderr because a hook must never
+ * disturb the session it fires in (ADR 0020): a kit that is not there, or a book
+ * that cannot be written, leaves the session alone and the health check finds
+ * the stale book later.
+ */
+export const hookCommand = (bots, bot, cli = ownCli()) =>
+  `${shellWord(cli)} session record --bots ${shellWord(bots)} --bot ${shellWord(bot)} 2>/dev/null || true`;
+
+/**
+ * Make sure the bot at `home` has the kit's SessionStart hook for `harness`.
+ * Returns the file it wrote, relative to the bot home, or undefined when the
+ * file already said this.
+ *
+ * The file is the user's as much as the kit's — it is where their own project
+ * settings for that harness live — so everything else in it is kept, and only
+ * the kit's own entry is written (PRD 6.3).
+ */
+export function installHook(home, harness, { bots, bot }) {
+  const file = path.join(home, HOOK_FILE[harness]);
+  const away = outside(home, file);
+  if (away !== undefined) throw new Error(away);
+  const settings = readSettings(file);
+
+  const mine = { type: 'command', command: hookCommand(bots, bot), timeout: TIMEOUT };
+  // The kit's own entry is put right where it already sits, and nothing else in
+  // the file is the kit's to move: a second run adds nothing, a changed bots
+  // path is corrected rather than doubled, an entry under an event the kit no
+  // longer asks about is taken out, and a hook of the user's beside the kit's
+  // stays where they put it.
+  const wanted = { ...settings, hooks: withKitHook(settings.hooks, file, mine) };
+
+  // Compared as documents, not as text: how the user laid their file out is
+  // theirs, and a run that changes nothing writes nothing.
+  if (isDeepStrictEqual(settings, wanted)) return undefined;
+
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(wanted, null, 2)}\n`);
+  return HOOK_FILE[harness];
+}
+
+/**
+ * Whether the kit's hook is in place for one harness, and what to say when it
+ * is not: `{ where, says }`, or nothing when the file already holds it.
+ *
+ * The same question `installHook` asks, without the writing. It matters more
+ * than it looks: the hook is the whole of how the book learns which
+ * conversation a session is running as (ADR 0012), and when it is not there
+ * nothing else says so — the book simply stops being true.
+ */
+export function hookTrouble(home, harness, { bots, bot }) {
+  const file = path.join(home, HOOK_FILE[harness]);
+  const stale = `Until it is there, nothing tells the book which conversation this bot's ${harness} sessions are running as, and the book goes stale.`;
+
+  const away = outside(home, file);
+  if (away !== undefined) return { where: file, says: `${away} ${stale}` };
+
+  let wanted;
+  let settings;
+  try {
+    settings = readSettings(file);
+    // The hook in the file is judged by what it runs, not by whether this is
+    // the install that wrote it. A bot made before the kit named itself by path
+    // runs the bare `obk`, and one another install wrote runs that install: both
+    // still reach a kit, and the next `obk up` writes this one's. So the line is
+    // checked against the program already in it, and only one that names a CLI
+    // that is not there any more is wrong — `|| true` would keep that quiet, and
+    // the book would stop being true with nothing to say why.
+    const running = kitProgramIn(settings);
+    if (running !== undefined && running !== BARE && !existsSync(running)) {
+      return {
+        where: file,
+        says: `${file} holds the kit's session hook, but it runs ${running}, which is not there any more. ${stale} obk up puts back one that runs the kit you have.`,
+      };
+    }
+    const program = running ?? ownCli();
+    wanted = { ...settings, hooks: withKitHook(settings.hooks, file, { type: 'command', command: hookCommand(bots, bot, program), timeout: TIMEOUT }) };
+  } catch (error) {
+    return { where: file, says: `${error.message} ${stale}` };
+  }
+
+  if (isDeepStrictEqual(settings, wanted)) return undefined;
+  return {
+    where: file,
+    says: `${file} does not hold the kit's session hook, and ${harness} reads this bot's hooks from it. ${stale} obk up puts it back.`,
+  };
+}
+
+/**
+ * What to say about a hooks file that a link takes out of the bot folder, or
+ * undefined when it stays in. The kit writes its hook in the bot folder and
+ * nowhere else (ADR 0020); through a link like that it would be writing the
+ * user's own settings, so it does not, and says why.
+ */
+function outside(home, file) {
+  const real = leadsOutside(home, file);
+  if (real === undefined) return undefined;
+  return `${file} leads outside the bot folder, to ${real}, through a link, and the kit writes its session hook only inside the bot folder. Replace the link with a file of the bot's own, then run the command again.`;
+}
+
+/**
+ * The file's hooks with the kit's own entry where it belongs and everything else
+ * as the user left it.
+ *
+ * The kit owns one entry, not the group it sits in. A group is the user's: it
+ * carries their other hooks and its own settings, and the kit's entry is only
+ * one of the things in it. So the kit's entry is written in place where one is
+ * already there, taken out where the kit no longer asks about that event, and
+ * added on its own only when the file has none. A group the kit empties goes,
+ * and an event left with no groups goes with it; a group that still has the
+ * user's hooks stays, whatever the kit took out of it.
+ *
+ * Anything under `hooks` that is not a mapping of events, or an event that is
+ * not a list of groups, is theirs and is left alone.
+ */
+function withKitHook(hooks, file, mine) {
+  if (hooks === undefined) return { [EVENT]: [{ hooks: [mine] }] };
+  if (hooks === null || typeof hooks !== 'object' || Array.isArray(hooks)) {
+    // Whatever this is, it is theirs, and writing the kit's hook here would
+    // write over it. Better to say so than to take it away.
+    throw new Error(`${file} has a hooks entry that is not a mapping of events, and the kit's session hook goes in there. Fix it or move it aside, then run the command again.`);
+  }
+
+  // One entry of the kit's, and only one: a file that somehow holds two keeps
+  // the first and loses the rest.
+  let placed = false;
+  const events = Object.fromEntries(Object.entries(hooks).flatMap(([event, groups]) => {
+    if (!Array.isArray(groups)) return [[event, groups]];
+
+    const kept = groups.flatMap((group) => {
+      if (!Array.isArray(group?.hooks)) return [group];
+
+      const entries = group.hooks.flatMap((hook) => {
+        if (!isKitHook(hook)) return [hook];
+        if (event !== EVENT || placed) return [];
+        placed = true;
+        return [mine];
+      });
+      return entries.length === 0 ? [] : [{ ...group, hooks: entries }];
+    });
+    return kept.length === 0 ? [] : [[event, kept]];
+  }));
+
+  if (placed) return events;
+  return { ...events, [EVENT]: [...(events[EVENT] ?? []), { hooks: [mine] }] };
+}
+
+/**
+ * The kit's own hook entry, wherever it sits and whatever sits beside it: a
+ * command of exactly the shape `hookCommand` writes, for any bots folder and
+ * bot, run by a kit — the bare `obk` a bot made before #220 still has, this
+ * install, or another — so an entry written before the folder moved or the kit
+ * changed is still the kit's, and is rewritten in place rather than joined by a
+ * second. A line of the user's that only mentions the command, or runs it with
+ * a program of their own, is theirs (PRD 6.5).
+ */
+const isKitHook = (hook) => kitProgramOf(hook?.command) !== undefined;
+
+/** One word as `shellWord` writes it: bare, or single-quoted with `'\''` inside. */
+const WORD = String.raw`(?:[A-Za-z0-9,._+:@%/=-]+|'(?:[^']|'\\'')*')`;
+const KIT_HOOK = new RegExp(String.raw`^(${WORD}) session record --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
+
+/** The program a bot made before the kit named itself by path runs. */
+const BARE = 'obk';
+
+/**
+ * Whether a program is a kit: the bare name, an install's `obk` wherever it
+ * lives, or a checkout's `src/cli.js` — the only two ways `ownCli` is reached.
+ */
+const isKitCli = (program) => path.basename(program) === BARE || program.endsWith('/src/cli.js');
+
+/** The program a hook command of the kit's runs, unquoted, or undefined for any other command. */
+function kitProgramOf(command) {
+  const found = typeof command === 'string' ? KIT_HOOK.exec(command) : null;
+  if (found === null) return undefined;
+  const program = unquoted(found[1]);
+  return isKitCli(program) ? program : undefined;
+}
+
+/**
+ * What the kit's hook in these settings runs, as a path or the bare name, or
+ * undefined when there is none. Read back out of its shell quoting, so it can be
+ * looked for on disk.
+ */
+function kitProgramIn(settings) {
+  for (const groups of Object.values(settings.hooks ?? {})) {
+    if (!Array.isArray(groups)) continue;
+    for (const group of groups) {
+      for (const hook of Array.isArray(group?.hooks) ? group.hooks : []) {
+        const program = kitProgramOf(hook?.command);
+        if (program !== undefined) return program;
+      }
+    }
+  }
+  return undefined;
+}
+
+/** A word as `shellWord` wrote it, read back to what it stands for. */
+const unquoted = (word) => (word.startsWith("'") ? word.slice(1, -1).replaceAll(`'\\''`, "'") : word);
+
+/**
+ * What the file says, or nothing when there is no file yet. A file the kit
+ * cannot read as JSON is the user's, and guessing at it would lose what they
+ * wrote, so the command says so and writes nothing.
+ */
+function readSettings(file) {
+  if (!existsSync(file)) return {};
+
+  const parsed = parse(readFileSync(file, 'utf8'));
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${file} is not readable as JSON, and the kit's session hook goes in it. Fix it or move it aside, then run the command again.`);
+  }
+  return parsed;
+}
+
+function parse(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}

package/src/init.js

@@ -0,0 +1,314 @@
+// Creates the user's bots folder: their own git repo, seeded with the files the
+// kit reads, and Bot Father. The kit puts none of its own code in here — kit
+// skills are linked from the installed package (ADR 0014).
+//
+// Seeding only ever adds what is missing. The user edits these files, by hand
+// or through Bot Father, so a re-run must never write over them.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { parseDocument } from 'yaml';
+
+import { BOT_GITIGNORE, changesExactly, YAML_OUT } from './bot.js';
+import { RECORD, SKILL_DIRS } from './skills.js';
+
+/**
+ * What the kit makes on this machine, and what the repo therefore does not
+ * carry (ADR 0014, PRD 6.3).
+ *
+ * A bot's skills are symlinks into wherever the kit and the user's skill
+ * sources are installed on the machine that made them, so a clone somewhere
+ * else holds links to nothing until something relinks. They are not the repo's
+ * to carry: every one of them is made again, at this machine's paths, by
+ * `obk up` and `obk skills build`.
+ *
+ * The entries are ignored rather than the directories holding them, because
+ * git cannot take a file back into a directory it has been told to ignore, and
+ * what the user keeps in there beside the kit's links is theirs.
+ *
+ * Written once, when the folder is made, and the user's from then on like
+ * everything else `init` seeds.
+ */
+const GITIGNORE = `# What obk links on this machine, rather than what this repo carries.
+#
+# A bot's skills are symlinks into wherever the kit and your skill sources are
+# installed here, so they say nothing true on another machine. obk up and obk
+# skills build make them again wherever this repo is checked out, and
+# ${RECORD} is the kit's own record of the ones it made.
+#
+# Anything of your own in a bot's skills directories is still yours: git add
+# --force takes one in, or name it below after a !.
+
+${Object.values(SKILL_DIRS).map((dir) => `bots/*/${dir.split(path.sep).join('/')}/*\n`).join('')}bots/*/${RECORD}
+`;
+
+const DEFAULTS_YAML = `# Rules and skills every bot gets, on top of its own.
+#
+# rules:  rule units built into every bot's AGENTS.md, on top of the kit's own
+#         defaults, which every bot carries already. A bare name is a file in
+#         rules/ beside this one; kit:<name> is one of the kit's.
+# skills: skills every bot gets, linked into both harnesses. kit:<name> is one
+#         of the kit's; <source>:<name> is one from an online source you listed
+#         in skills.yaml; a bare name is a directory in skills/ beside this one;
+#         anything with a / in it is a path to a skill directory on disk.
+
+rules: []
+skills: []
+`;
+
+const SKILLS_YAML = `# Online skill sources. The kit clones each one beside this folder, in
+# <bots>.skill-sources/, at the ref you pin here, and records the sha it got.
+#
+# sources:
+#   - name: someones-skills
+#     repo: https://github.com/someone/skills
+#     path: skills        # subfolder inside the repo, optional
+#     ref: v1.2.0         # branch, tag or sha
+
+sources: []
+`;
+
+/**
+ * Where a problem with the kit itself is reported: the one address, as the
+ * package gives it, so Bot Father is told the same place npm and the README are.
+ */
+const ISSUES = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).bugs.url;
+
+const botFatherYaml = (harness) => `# Bot Father runs the fleet. Ask it for changes rather than editing this file.
+
+name: bot-father
+harness: ${harness}
+charter: |
+  Bot Father owns the fleet. It creates, changes, pauses and retires bots and
+  their sessions, and keeps each bot's rules and skills in order.
+
+  Good looks like: every bot has a charter its owner recognises, the skills it
+  needs and no more, and sessions that come back after a restart.
+
+  Ask first before: retiring a bot or a session, restarting anything, or
+  changing a bot's rules in a way its owner did not ask for.
+
+  When the kit itself goes wrong (an obk command fails in a way its own message
+  does not explain, or does something other than what it says), tell your owner
+  plainly, and with their go-ahead report it as an issue at ${ISSUES}. The
+  report is public, so ask before filing and take out anything private first:
+  names in paths, tokens, what a charter says. Put in the command that was run
+  and its whole output, what you expected instead, and what these print:
+  obk --version, obk health --bots <folder> --json, node --version, the Orca
+  version, and claude --version or codex --version; and the operating system.
+  One problem per issue. If you cannot file it yourself, give your owner the
+  text to paste.
+rules: []
+skills:
+${MANAGEMENT_SKILLS.map((name) => `  - kit:${name}\n`).join('')}sessions:
+  # The management session: the tab you talk to Bot Father in.
+  - name: ${DAILY_SESSION}
+`;
+
+/**
+ * The kit's own skills for the job Bot Father has: writing a bot, looking over
+ * the fleet that exists, the daily pass over it, and what the work costs. The
+ * last two are here because the grooming run is told to use them by name, and a
+ * session woken to do a job with a skill it cannot load improvises instead,
+ * which is the thing the skill was written to stop. They go on its list when the kit writes its
+ * `bot.yaml`, because a fleet manager with no way to manage the fleet is not
+ * something the user can ask it to fix — asking it is the thing that does not
+ * work yet.
+ *
+ * Only then. A `bot.yaml` that is already there keeps whatever list it has: an
+ * older kit that never wrote these and an owner who took one off leave exactly
+ * the same file behind, and of the two readings, putting back what somebody
+ * removed is the worse one to be wrong about.
+ */
+const MANAGEMENT_SKILLS = ['obk-bot-building', 'obk-finops', 'obk-fleet-review', 'obk-grooming'];
+
+const BOT_FATHER_YAML = 'bots/bot-father/bot.yaml';
+
+/** The management session every Bot Father has: the tab you talk to it in. */
+export const DAILY_SESSION = 'daily';
+
+const seeds = (harness) => [
+  ['.gitignore', GITIGNORE],
+  ['defaults.yaml', DEFAULTS_YAML],
+  ['skills.yaml', SKILLS_YAML],
+  ['rules/.gitkeep', ''],
+  ['skills/.gitkeep', ''],
+  [BOT_FATHER_YAML, botFatherYaml(harness)],
+  // Bot Father's work folder stays out of the repo like every bot's.
+  ['bots/bot-father/.gitignore', BOT_GITIGNORE],
+];
+
+// The directories the layout implies, parents before children, taken from the
+// seed list so the two cannot drift apart.
+const LAYOUT_DIRS = (() => {
+  const dirs = new Set();
+  for (const [entry] of seeds('claude')) {
+    const parts = entry.split('/').slice(0, -1);
+    for (let depth = 1; depth <= parts.length; depth += 1) {
+      dirs.add(parts.slice(0, depth).join('/'));
+    }
+  }
+  return [...dirs];
+})();
+
+/**
+ * Create or complete the bots folder at `target`.
+ * Returns { bots, created } — `created` lists what was missing, in order.
+ *
+ * Everything is checked before anything is written, so a folder `init` cannot
+ * make usable is left exactly as it was found rather than half seeded.
+ */
+export function initBots(target, harness) {
+  const bots = path.resolve(target);
+  const SEEDS = seeds(harness);
+
+  // The bots path is held to the same rule as everything inside it, so a link
+  // to a folder on another volume is the folder it points at.
+  checkKind(bots, 'folder');
+
+  const created = [];
+  mkdirSync(bots, { recursive: true });
+
+  for (const dir of LAYOUT_DIRS) checkKind(path.join(bots, dir), 'folder');
+  for (const [entry] of SEEDS) checkKind(path.join(bots, entry), 'file');
+  checkBotFather(path.join(bots, BOT_FATHER_YAML), harness);
+
+  if (!existsSync(path.join(bots, '.git'))) {
+    gitInit(bots);
+    created.push('.git');
+  }
+  checkRepo(bots);
+
+  for (const [entry, contents] of SEEDS) {
+    const file = path.join(bots, entry);
+    if (existsSync(file)) continue;
+    mkdirSync(path.dirname(file), { recursive: true });
+    // 'wx' so a file that appeared between the check and the write is kept.
+    writeFileSync(file, contents, { flag: 'wx' });
+    created.push(entry);
+  }
+
+  // A bot.yaml from an earlier version of the kit is missing what this one
+  // needs. It is the user's file by now, so what is missing is filled in and
+  // nothing else is touched.
+  const completed = created.includes(BOT_FATHER_YAML) ? [] : completeBotFather(path.join(bots, BOT_FATHER_YAML), harness);
+
+  return { bots, created, completed };
+}
+
+// What is already at `target` must be the kind of thing `init` needs there, or
+// `init` refuses: it never moves the user's data aside to make room.
+// A symlink counts by what it points at.
+function checkKind(target, kind) {
+  if (!follow(target, () => lstatSync(target, { throwIfNoEntry: false }))) return;
+
+  const resolved = follow(target, () => statSync(target, { throwIfNoEntry: false }));
+  if (!resolved) {
+    throw new Error(`${target} is a symlink that points nowhere. Remove it, then run init again.`);
+  }
+  if (kind === 'folder' ? !resolved.isDirectory() : !resolved.isFile()) {
+    throw new Error(`${target} is in the way: init needs a ${kind} there. Move it aside, then run init again.`);
+  }
+}
+
+// Look at `target`, and say plainly when the look cannot be made at all because
+// the links there run in a circle. Node reports that as ELOOP and the name of a
+// call the user never made; what they need is which path is the loop and that
+// nobody but them can undo it.
+function follow(target, look) {
+  try {
+    return look();
+  } catch (error) {
+    if (error.code !== 'ELOOP') throw error;
+    throw new Error(`${target} is a symlink loop: following it comes back to where it started. Fix the links, then run init again.`);
+  }
+}
+
+// An existing `.git` is not proof of a repository, and a repository found by
+// walking up to a parent is not this folder's own.
+function checkRepo(bots) {
+  const top = spawnSync('git', ['-C', bots, 'rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+  // Only git's record terminator comes off: trailing whitespace may be part of the folder's name.
+  const toplevel = (top.stdout ?? '').replace(/\n$/, '');
+  if (top.status !== 0 || toplevel === '' || realpathSync(toplevel) !== realpathSync(bots)) {
+    throw new Error(`${bots} has a .git entry but is not a git repository of its own. Remove or repair it, then run init again.`);
+  }
+}
+
+// git's own output is captured, not inherited: the CLI decides what the user reads.
+function gitInit(bots) {
+  const result = spawnSync('git', ['init', '--quiet', bots], { encoding: 'utf8' });
+  if (result.error) throw new Error(`could not run git: ${result.error.message}`);
+  if (result.status !== 0) {
+    throw new Error(`git init failed in ${bots}: ${(result.stderr || '').trim()}`);
+  }
+}
+
+// A bot.yaml that is already there has to be one `init` can finish. What it
+// cannot finish, it refuses before anything is written, rather than guess at
+// what the user meant.
+function checkBotFather(file, harness) {
+  if (!existsSync(file)) return;
+
+  const doc = parseDocument(readFileSync(file, 'utf8'));
+  const bot = doc.errors.length > 0 ? undefined : doc.toJS();
+  if (bot === null || typeof bot !== 'object' || Array.isArray(bot)) {
+    throw new Error(`${file} is not a bot: it should be a YAML mapping with a name, a harness and a list of sessions. Fix it or move it aside, then run init again.`);
+  }
+
+  // The harness is the user's, written once and never rewritten: a second init
+  // naming the other one is a mistake worth stopping, not a quiet change.
+  if (bot.harness !== undefined && bot.harness !== harness) {
+    throw new Error(`you asked for --harness ${harness}, but Bot Father is already on ${bot.harness}, and init does not change it. Run init again with --harness ${bot.harness}, or ask Bot Father to move it.`);
+  }
+  if (bot.sessions !== undefined && bot.sessions !== null && !Array.isArray(bot.sessions)) {
+    throw new Error(`${file} has a sessions entry that is not a list, so init cannot add Bot Father's daily session to it. Fix it, then run init again.`);
+  }
+}
+
+/**
+ * Fill in what an older `bot.yaml` is missing, and nothing else. Returns what
+ * was completed, for the report.
+ *
+ * The file is edited through the YAML library, which keeps the user's comments
+ * and their own values; what it reformats on the way is its business. What is
+ * checked here is the thing that matters: that the file says what it said
+ * before, plus the harness and the session this fills in.
+ *
+ * Sessions the user already has are left alone, whatever they are called. They
+ * are theirs, and `up` brings up what it finds.
+ */
+function completeBotFather(file, harness) {
+  const source = readFileSync(file, 'utf8');
+  const doc = parseDocument(source);
+
+  // What is missing is settled from the document, not from the text it is
+  // written back as: a file that needs nothing is not rewritten, however the
+  // library would have laid it out.
+  const sessions = doc.get('sessions', true);
+  const needsSession = sessions?.items === undefined || sessions.items.length === 0;
+  const needsHarness = doc.get('harness') === undefined;
+  if (!needsSession && !needsHarness) return [];
+
+  if (sessions?.items === undefined) {
+    doc.set('sessions', [{ name: DAILY_SESSION }]);
+  } else if (needsSession) {
+    sessions.flow = false;
+    doc.addIn(['sessions'], { name: DAILY_SESSION });
+  }
+  if (needsHarness) doc.set('harness', harness);
+
+  const text = doc.toString(YAML_OUT);
+
+  if (!changesExactly(source, text, (was) => ({
+    ...was,
+    harness: was.harness ?? harness,
+    sessions: was.sessions?.length > 0 ? was.sessions : [{ name: DAILY_SESSION }],
+  }))) {
+    throw new Error(`${file} cannot be completed without changing something else in it, so nothing was written. Give it a harness and a session by hand, then run init again.`);
+  }
+
+  writeFileSync(file, text);
+  return [BOT_FATHER_YAML];
+}