@yegor256/jinka 0.0.0-stage → 0.0.1

package/LICENSE.txt

@@ -0,0 +1,21 @@
+(The MIT License)
+
+Copyright (c) 2026 Yegor Bugayenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the 'Software'), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# Simple Command Line Orchestrator of Agents
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![test](https://github.com/yegor256/jinka/actions/workflows/test.yml/badge.svg)](https://github.com/yegor256/jinka/actions/workflows/test.yml)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/yegor256/jinka/blob/master/LICENSE.txt)
+
+First, you create a directory with your wishes, one per Markdown file.
+You can start with a single wish:
+
+```text
+my-wishes/
+  make-me-happy.md
+```
+
+In the `make-me-happy.md` file you say something like this:
+
+```text
+I wish my GitHub repositories were in good shape: `foo/bar` and `foo/bar2`.
+```
+
+Then, you install `jinka`:
+
+```bash
+npm install -g @yegor256/jinka
+```
+
+Finally, you run it, giving it the path to your directory with wishes:
+
+```bash
+jinka my-wishes/
+```
+
+That's it.
+Your wish will come true.

package/bin/jinka.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+// SPDX-License-Identifier: MIT
+
+import { parseArgs } from 'node:util';
+import { readFile } from 'node:fs/promises';
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Jinka } from '../src/jinka.js';
+import { Wishes } from '../src/wishes.js';
+import { Claude } from '../src/claude.js';
+import { Tty } from '../src/tty.js';
+import { Log } from '../src/log.js';
+import { Status } from '../src/status.js';
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    threads: { type: 'string', default: '8' },
+    archive: { type: 'string', default: '' },
+    agent: { type: 'string', default: 'claude' },
+    interval: { type: 'string', default: '5000' },
+    model: { type: 'string', default: '' }
+  }
+});
+if (positionals.length !== 1) {
+  console.error('Usage: jinka [--threads 8] [--archive DIR] [--agent claude] [--interval 5000] [--model MODEL] WISHES');
+  process.exit(1);
+}
+const threads = Number(values.threads);
+const interval = Number(values.interval);
+if (!Number.isInteger(threads) || threads < 1 || !Number.isInteger(interval) || interval < 1) {
+  console.error(`The --threads and --interval options must be positive integers, but got "${values.threads}" and "${values.interval}"`);
+  process.exit(1);
+}
+const dir = resolve(positionals[0]);
+const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+const screen = process.stdout.isTTY
+  ? new Tty(process.stdout, threads, new Status(JSON.parse(await readFile(join(root, 'package.json'), 'utf8')).version, Date.now()))
+  : new Log(process.stdout);
+process.on('exit', () => screen.close());
+const controller = new AbortController();
+process.on('SIGINT', () => {
+  if (controller.signal.aborted) {
+    process.exit(130);
+  }
+  controller.abort();
+});
+try {
+  await new Jinka(
+    new Wishes(dir, interval, values.archive === '' ? '' : resolve(values.archive)),
+    new Claude(values.agent, join(root, 'plugin'), dir, values.model),
+    screen,
+    threads
+  ).run(controller.signal);
+  process.exit(130);
+} catch (e) {
+  screen.close();
+  console.error(e.message);
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,34 @@
 {
+  "author": "Yegor Bugayenko",
+  "bin": {
+    "jinka": "bin/jinka.js"
+  },
+  "description": "Simple command line orchestrator of coding agents",
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "c8": "^12.0.0",
+    "eslint": "^10.13.0",
+    "globals": "^17.13.0",
+    "hamjest": "^4.1.1",
+    "mocha": "^12.0.3"
+  },
+  "engines": {
+    "node": ">=20.12"
+  },
+  "files": [
+    "bin",
+    "src",
+    "plugin"
+  ],
+  "license": "MIT",
   "name": "@yegor256/jinka",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yegor256/jinka.git"
+  },
+  "scripts": {
+    "test": "c8 --check-coverage --lines 80 mocha"
+  },
+  "type": "module",
+  "version": "0.0.1"
+}

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "author": {
+    "name": "Yegor Bugayenko"
+  },
+  "description": "Skills that jinka gives to every agent working on a wish",
+  "name": "jinka",
+  "version": "0.0.0"
+}

package/plugin/skills/accept-pull-request/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: accept-pull-request
+description: Use this skill when a wish asks to review and accept one GitHub pull request.
+---
+
+# Accept a Pull Request
+
+<!--
+@todo #2:60min Design the accept-pull-request skill properly.
+ This draft only lists the basic steps, but it should explain how deep
+ the review must be, what to do with failing checks, and which merge
+ method to use.
+-->
+
+Read the pull request with `gh pr view` and its diff with `gh pr diff`.
+Check that all its CI checks are green with `gh pr checks`.
+If the change is correct and the checks pass, merge it with `gh pr merge`.
+Otherwise, explain in a review comment what has to change.

package/plugin/skills/clean-up-backlog/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: clean-up-backlog
+description: Use this skill when a wish asks to keep the backlog of a GitHub repository in good shape.
+---
+
+# Clean Up the Backlog
+
+<!--
+@todo #2:60min Design the clean-up-backlog skill properly.
+ This draft picks any issue or pull request, but it should prefer the
+ oldest ones, skip those already covered by an existing wish, and
+ limit how many new wishes it writes at once.
+-->
+
+List open issues with `gh issue list` and pull requests with `gh pr list`.
+Pick one of them that nobody has touched for a while.
+Write a new Markdown file into the wishes directory given in the prompt.
+In that file, ask to triage the issue or to accept the pull request,
+  naming the repository and the number.
+Name the file after them, for example `foo-bar-pr-42.md`.

package/plugin/skills/triage-an-issue/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: triage-an-issue
+description: Use this skill when a wish asks to triage one GitHub issue.
+---
+
+# Triage an Issue
+
+<!--
+@todo #2:60min Design the triage-an-issue skill properly.
+ This draft only lists the basic steps, but it should explain how to
+ judge whether an issue is clear, which labels to use, and when to
+ close it as a duplicate.
+-->
+
+Read the issue with `gh issue view`, including all its comments.
+Decide whether it describes a real problem or a clear request.
+If it does, label it and say in a comment what should be done next.
+If it does not, ask its author one precise question in a comment.

package/src/archived.js

@@ -0,0 +1,42 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+// SPDX-License-Identifier: MIT
+
+import { copyFile, mkdir, access } from 'node:fs/promises';
+import { join, dirname, extname } from 'node:path';
+
+/**
+ * A wish that goes into the archive directory instead of disappearing.
+ * The archived copy keeps the subdirectory of the wish, and gets a
+ * timestamp in its name when a file with the same name is already there.
+ */
+export class Archived {
+  constructor(origin, dir, archive) {
+    this.origin = origin;
+    this.dir = dir;
+    this.archive = archive;
+  }
+  name() {
+    return this.origin.name();
+  }
+  async text() {
+    return this.origin.text();
+  }
+  fate() {
+    return this.origin.fate();
+  }
+  async close() {
+    await copyFile(join(this.dir, this.origin.name()), await this.#target());
+    await this.origin.close();
+  }
+  free() {
+    this.origin.free();
+  }
+  async #target() {
+    const target = join(this.archive, this.origin.name());
+    await mkdir(dirname(target), { recursive: true });
+    return access(target).then(
+      () => `${target.slice(0, target.length - extname(target).length)}-${Date.now()}${extname(target)}`,
+      () => target
+    );
+  }
+}

package/src/claude.js

@@ -0,0 +1,60 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+// SPDX-License-Identifier: MIT
+
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { join } from 'node:path';
+import { Event } from './event.js';
+
+/**
+ * The coding agent that makes one wish come true.
+ * It starts the agent process in headless mode, writes the prompt
+ * to its standard input, and reports every event of its stream-json
+ * output to a screen row. The model, when not empty, is passed
+ * to the agent verbatim. The process gets SIGTERM when the signal
+ * aborts.
+ */
+export class Claude {
+  constructor(command, plugin, dir, model) {
+    this.command = command;
+    this.plugin = plugin;
+    this.dir = dir;
+    this.model = model;
+  }
+  async run(wish, row, signal) {
+    const prompt = [
+      'Make this wish come true, working on your own without asking any questions:',
+      '',
+      await wish.text(),
+      '',
+      `The wish is written in the file ${join(this.dir, wish.name())}, ${wish.fate()}.`,
+      `All wishes live in the directory ${this.dir}, and you may add new wishes there as Markdown files.`
+    ].join('\n');
+    const agent = spawn(
+      this.command,
+      [
+        '-p', '--output-format', 'stream-json', '--verbose',
+        '--plugin-dir', this.plugin, '--add-dir', this.dir,
+        '--dangerously-skip-permissions',
+        ...(this.model === '' ? [] : ['--model', this.model])
+      ],
+      { signal, stdio: ['pipe', 'pipe', 'ignore'] }
+    );
+    agent.stdin.on('error', () => {});
+    agent.stdin.end(prompt);
+    createInterface({ input: agent.stdout }).on('line', (line) => {
+      const text = new Event(line).text();
+      if (text !== '') {
+        row.show(text);
+      }
+    });
+    return new Promise((resolve, reject) => {
+      agent.on('error', (e) => {
+        if (!signal.aborted) {
+          reject(new Error(`Cannot start the agent "${this.command}": ${e.message}`));
+        }
+      });
+      agent.on('close', (code) => resolve(code ?? 1));
+    });
+  }
+}

package/src/duration.js

@@ -0,0 +1,21 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+// SPDX-License-Identifier: MIT
+
+/**
+ * A span of time, printed the way a clock prints it.
+ * It drops the milliseconds and pads every part with zeros, either as
+ * minutes and seconds, or as hours, minutes and seconds.
+ */
+export class Duration {
+  constructor(millis) {
+    this.millis = millis;
+  }
+  minutes() {
+    const seconds = Math.floor(this.millis / 1000);
+    return [Math.floor(seconds / 60), seconds % 60].map((p) => String(p).padStart(2, '0')).join(':');
+  }
+  hours() {
+    const seconds = Math.floor(this.millis / 1000);
+    return [Math.floor(seconds / 3600), Math.floor(seconds / 60) % 60, seconds % 60].map((p) => String(p).padStart(2, '0')).join(':');
+  }
+}

package/src/event.js

@@ -0,0 +1,47 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+// SPDX-License-Identifier: MIT
+
+/**
+ * One line of the stream-json output of the agent.
+ * It turns the line into a short phrase that fits into one screen line,
+ * such as the name of a tool with its main argument, or the first line
+ * of what the agent said. Lines that carry nothing worth showing
+ * become an empty phrase.
+ */
+export class Event {
+  constructor(line) {
+    this.line = line;
+  }
+  text() {
+    try {
+      return this.#phrase(JSON.parse(this.line));
+    } catch {
+      return this.line.trim();
+    }
+  }
+  #phrase(json) {
+    if (json.type === 'assistant') {
+      return (json.message?.content ?? []).map((part) => this.#part(part)).filter((p) => p !== '').join(' ');
+    }
+    if (json.type === 'result') {
+      return this.#first(String(json.result ?? json.subtype ?? ''));
+    }
+    return '';
+  }
+  #part(part) {
+    if (part.type === 'text') {
+      return this.#first(part.text);
+    }
+    if (part.type === 'tool_use') {
+      const input = part.input ?? {};
+      return [part.name, input.command ?? input.file_path ?? input.pattern ?? input.url ?? input.query ?? input.skill ?? input.description]
+        .filter((p) => p !== undefined)
+        .map((p) => this.#first(String(p)))
+        .join(': ');
+    }
+    return '';
+  }
+  #first(text) {
+    return text.split('\n').map((l) => l.trim()).find((l) => l !== '') ?? '';
+  }
+}

package/src/jinka.js

@@ -0,0 +1,23 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+// SPDX-License-Identifier: MIT
+
+import { Wand } from './wand.js';
+
+/**
+ * The application, which keeps several wands busy with wishes.
+ * Each wand gets its own screen row and protocol, and all of them share one
+ * directory of wishes and one agent, until the signal aborts.
+ */
+export class Jinka {
+  constructor(wishes, agent, screen, threads) {
+    this.wishes = wishes;
+    this.agent = agent;
+    this.screen = screen;
+    this.threads = threads;
+  }
+  async run(signal) {
+    await Promise.all(
+      Array.from({ length: this.threads }, (_, i) => new Wand(this.wishes, this.agent, this.screen.row(i), this.screen.protocol(i)).run(signal))
+    );
+  }
+}

package/src/log.js

@@ -0,0 +1,25 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+// SPDX-License-Identifier: MIT
+
+import { Row } from './row.js';
+
+/**
+ * The screen for anything that is not a terminal, such as CI or a pipe.
+ * It prints every change of every row and every protocol line
+ * as a new plain line, without any cursor movement.
+ */
+export class Log {
+  constructor(stream) {
+    this.stream = stream;
+  }
+  row(index) {
+    return new Row({ push: ([i, text]) => this.stream.write(`[${i + 1}] ${text.replace('\t', '  ')}\n`) }, index);
+  }
+  protocol(index) {
+    return new Row(
+      { push: ([i, text]) => this.stream.write(`${new Date().toTimeString().slice(0, 8)} [${i + 1}] ${text.replace('\t', '  ')}\n`) },
+      index
+    );
+  }
+  close() {}
+}

package/src/permanent.js

@@ -0,0 +1,33 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+// SPDX-License-Identifier: MIT
+
+/**
+ * A wish that was already in the directory when jinka started.
+ * It describes ongoing work, so its file is never deleted: closing it
+ * only gives its claim back, sending it to the end of the queue.
+ * @todo #10:45min A permanent wish goes back to the queue right after
+ *  a successful run, so a directory with a single permanent wish makes
+ *  the agent work on it without any pause, burning the subscription.
+ *  Let us decide whether a permanent wish must wait some time after
+ *  a success before it is tried again, and implement that delay.
+ */
+export class Permanent {
+  constructor(origin) {
+    this.origin = origin;
+  }
+  name() {
+    return this.origin.name();
+  }
+  async text() {
+    return this.origin.text();
+  }
+  fate() {
+    return 'which stays there after you exit, so you must not delete it';
+  }
+  async close() {
+    this.origin.free();
+  }
+  free() {
+    this.origin.free();
+  }
+}

package/src/row.js

@@ -0,0 +1,17 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+// SPDX-License-Identifier: MIT
+
+/**
+ * One line of the screen, owned by one wand.
+ * Every text it receives goes to the screen together with the index
+ * of the line, so the screen knows which line to change.
+ */
+export class Row {
+  constructor(lines, index) {
+    this.lines = lines;
+    this.index = index;
+  }
+  show(text) {
+    this.lines.push([this.index, text]);
+  }
+}

package/src/status.js

@@ -0,0 +1,19 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+// SPDX-License-Identifier: MIT
+
+import { Duration } from './duration.js';
+
+/**
+ * The top line of the terminal screen.
+ * It tells which version of jinka is running and how long it has been
+ * alive since the moment it started.
+ */
+export class Status {
+  constructor(version, start) {
+    this.version = version;
+    this.start = start;
+  }
+  text() {
+    return `jinka ${this.version}, up ${new Duration(Date.now() - this.start).hours()}`;
+  }
+}

package/src/tty.js

@@ -0,0 +1,75 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+// SPDX-License-Identifier: MIT
+
+import { Row } from './row.js';
+import { Duration } from './duration.js';
+
+/**
+ * The screen for terminals, which takes over the whole terminal like top.
+ * It switches to the alternate buffer and draws a fixed layout from the
+ * top left corner: the status line, one line per wand with the time it
+ * has been busy with its current wish, a separator, and the newest
+ * protocol lines that fit below it. The layout is redrawn on every change,
+ * every second, and on every resize, until the screen is closed and the
+ * normal buffer comes back.
+ */
+export class Tty {
+  constructor(stream, threads, status) {
+    this.stream = stream;
+    this.status = status;
+    this.lines = Array.from({ length: threads }, () => ({ head: '', tail: '', start: Date.now() }));
+    this.notes = [];
+    this.clock = [];
+  }
+  row(index) {
+    return new Row({ push: ([i, text]) => this.#update(i, text) }, index);
+  }
+  protocol(index) {
+    return new Row({ push: ([i, text]) => this.#note(i, text) }, index);
+  }
+  close() {
+    this.clock.splice(0).forEach((c) => {
+      clearInterval(c);
+      this.stream.write('\x1b[?25h\x1b[?1049l');
+    });
+  }
+  #update(index, text) {
+    const [head, tail = ''] = text.split('\t');
+    this.lines[index] = {
+      head,
+      tail,
+      start: head === this.lines[index].head ? this.lines[index].start : Date.now()
+    };
+    this.#paint();
+  }
+  #note(index, text) {
+    this.notes.push(`${new Date().toTimeString().slice(0, 8)} [${index + 1}] ${text.replace('\t', '  ')}`);
+    this.#paint();
+  }
+  #paint() {
+    if (this.clock.length === 0) {
+      this.stream.write('\x1b[?1049h\x1b[?25l');
+      this.clock.push(setInterval(() => this.#draw(), 1000).unref());
+      this.stream.on('resize', () => {
+        if (this.clock.length > 0) {
+          this.#draw();
+        }
+      });
+    }
+    this.#draw();
+  }
+  #draw() {
+    this.notes.splice(0, Math.max(0, this.notes.length - Math.max(0, (this.stream.rows || 24) - this.lines.length - 2)));
+    const width = Math.max(...this.lines.map((l) => l.head.length));
+    this.stream.write(
+      `\x1b[H${
+        [
+          this.status.text(),
+          ...this.lines.map((l, i) => `[${i + 1}] ${l.head.padEnd(width)}  ${new Duration(Date.now() - l.start).minutes()}  ${l.tail}`),
+          '-'.repeat(10),
+          ...this.notes
+        ].map((l) => `\x1b[2K${l.slice(0, this.stream.columns || 80)}`).join('\n')
+      }\x1b[J`
+    );
+  }
+}

package/src/wand.js

@@ -0,0 +1,45 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+// SPDX-License-Identifier: MIT
+
+import { Duration } from './duration.js';
+
+/**
+ * One loop that keeps making wishes come true until the signal aborts.
+ * It takes the next free wish, shows it on its own screen row, runs the
+ * agent on it, and closes the wish when the agent succeeds or frees it
+ * for a later retry when the agent fails. Either way, it reports the
+ * outcome and the time it took to the protocol of the screen.
+ */
+export class Wand {
+  constructor(wishes, agent, row, protocol) {
+    this.wishes = wishes;
+    this.agent = agent;
+    this.row = row;
+    this.protocol = protocol;
+  }
+  async run(signal) {
+    try {
+      while (!signal.aborted) {
+        await this.#once(signal);
+      }
+    } catch (e) {
+      if (!signal.aborted) {
+        throw e;
+      }
+    }
+  }
+  async #once(signal) {
+    this.row.show('idle\twaiting for wishes');
+    const wish = await this.wishes.next(signal);
+    this.row.show(`${wish.name()}\tstarting the agent`);
+    const start = Date.now();
+    const code = await this.agent.run(wish, { show: (text) => this.row.show(`${wish.name()}\t${text}`) }, signal);
+    if (code === 0) {
+      await wish.close();
+      this.protocol.show(`${wish.name()}\tdone in ${new Duration(Date.now() - start).minutes()}`);
+    } else {
+      wish.free();
+      this.protocol.show(`${wish.name()}\tfailed with exit code ${code} after ${new Duration(Date.now() - start).minutes()}`);
+    }
+  }
+}

package/src/wish.js

@@ -0,0 +1,34 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+// SPDX-License-Identifier: MIT
+
+import { readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * One wish, a Markdown file inside the wishes directory.
+ * The wish shares the map of claims with the wishes directory,
+ * so it can give its claim back when a wand is done with it.
+ */
+export class Wish {
+  constructor(dir, path, claims) {
+    this.dir = dir;
+    this.path = path;
+    this.claims = claims;
+  }
+  name() {
+    return this.path;
+  }
+  async text() {
+    return readFile(join(this.dir, this.path), 'utf8');
+  }
+  fate() {
+    return 'which will be deleted once you exit with code zero';
+  }
+  async close() {
+    await rm(join(this.dir, this.path));
+    this.claims.delete(this.path);
+  }
+  free() {
+    this.claims.set(this.path, false);
+  }
+}

package/src/wishes.js

@@ -0,0 +1,51 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+// SPDX-License-Identifier: MIT
+
+import { readdir } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { setTimeout } from 'node:timers/promises';
+import { Wish } from './wish.js';
+import { Archived } from './archived.js';
+import { Permanent } from './permanent.js';
+
+/**
+ * The directory with wishes, shared by all wands.
+ * It is the only object with mutable state: a map of claims, where the
+ * order of entries tells how recently each wish was tried and the value
+ * tells whether a wand holds it now. A wish is claimed synchronously
+ * right after the scan, so two wands never get the same file.
+ * The wishes found by the first scan are permanent and stay in the
+ * directory forever, while the ones that appear later are one-time.
+ */
+export class Wishes {
+  constructor(dir, interval, archive = '') {
+    this.dir = dir;
+    this.interval = interval;
+    this.archive = archive;
+    this.claims = new Map();
+    this.startup = [];
+  }
+  async next(signal) {
+    signal.throwIfAborted();
+    const files = (await readdir(this.dir, { recursive: true, withFileTypes: true }))
+      .filter((f) => f.isFile() && f.name.endsWith('.md'))
+      .map((f) => join(relative(this.dir, f.parentPath), f.name))
+      .sort();
+    if (this.startup.length === 0) {
+      this.startup.push(new Set(files));
+    }
+    const path = files.find((f) => !this.claims.has(f))
+      ?? [...this.claims.keys()].find((c) => !this.claims.get(c) && files.includes(c));
+    if (path === undefined) {
+      await setTimeout(this.interval, undefined, { signal });
+      return this.next(signal);
+    }
+    this.claims.delete(path);
+    this.claims.set(path, true);
+    const wish = new Wish(this.dir, path, this.claims);
+    if (this.startup[0].has(path)) {
+      return new Permanent(wish);
+    }
+    return this.archive === '' ? wish : new Archived(wish, this.dir, this.archive);
+  }
+}