@ccmsg/cli 0.13.0 → 0.14.0

package/src/files/files.ts

@@ -1,16 +1,14 @@
 import {
-  closeSync,
-  lstatSync,
-  mkdirSync,
-  openSync,
-  readdirSync,
-  readFileSync,
-  readSync,
-  renameSync,
-  statSync,
-  unlinkSync,
-  writeFileSync,
-} from "node:fs";
+  lstat,
+  mkdir,
+  open,
+  readdir,
+  readFile,
+  rename,
+  stat,
+  unlink,
+  writeFile,
+} from "node:fs/promises";
 import type { Dirent } from "node:fs";
 import { basename, dirname, join, relative } from "node:path";
 import type {
@@ -62,27 +60,34 @@ const FIND_VISITS = 20_000;
  * caller — the role dispatch states for a `scope: "role"` op, and the session
  * the connection speaks for — is handed over unread. */
 export function fileHandlers(paths: Containment) {
-  const viewer = (input: HandlerInput): Viewer => ({ role: input.role, sid: input.identity?.sid });
+  const viewer = (input: HandlerInput): Viewer => ({
+    role: input.role,
+    sid: input.identity?.sid,
+  });
 
   return {
-    "dir.list": (input: HandlerInput): DirListResult => {
+    "dir.list": async (input: HandlerInput): Promise<DirListResult> => {
       const args = input.args as unknown as DirListArgs;
-      const at = paths.root(args, viewer(input));
-      const stat = existing(at);
+      const at = await paths.root(args, viewer(input));
+      const stat = await existing(at);
       if (!stat.isDirectory()) throw new OpError("not_found", `${args.path ?? ""} is not a folder`);
-      return { sid: args.sid, path: at.path, entries: entriesOf(at.real) };
+      return {
+        sid: args.sid,
+        path: at.path,
+        entries: await entriesOf(at.real),
+      };
     },
 
-    "file.read": (input: HandlerInput): FileReadResult => {
+    "file.read": async (input: HandlerInput): Promise<FileReadResult> => {
       const args = input.args as unknown as FileReadArgs;
-      const at = paths.locate(args, viewer(input));
-      const stat = existing(at);
+      const at = await paths.locate(args, viewer(input));
+      const stat = await existing(at);
       if (!stat.isFile()) throw new OpError("not_found", `${args.path} is not a file`);
       // As much as the answer may carry and no more: a file larger than the
       // limit is answered from its head, so reading it whole would cost the
       // instance the whole of a file whose size is what the limit exists to
       // refuse.
-      const head = bytesOf(at.real, READ_LIMIT);
+      const head = await bytesOf(at.real, READ_LIMIT);
       const binary = isBinary(head);
       return {
         sid: args.sid,
@@ -95,115 +100,126 @@ export function fileHandlers(paths: Containment) {
       };
     },
 
-    "file.write": (input: HandlerInput): FileWriteResult => {
+    "file.write": async (input: HandlerInput): Promise<FileWriteResult> => {
       const args = input.args as unknown as FileWriteArgs;
-      const at = paths.inbox(args.sid, args.path, viewer(input));
+      const at = await paths.inbox(args.sid, args.path, viewer(input));
       // The inbox takes new notes, so an existing name is refused rather than
       // replaced; the folder itself is made, since a repository that has never
       // had one is exactly where the first note goes (DR-0019 §2.1).
-      mkdirSync(dirname(at.real), { recursive: true });
-      create(at.real, args.content);
+      await mkdir(dirname(at.real), { recursive: true });
+      await create(at.real, args.content);
       return { sid: args.sid, path: at.path };
     },
 
-    "file.create": (input: HandlerInput): FileCreateResult => {
+    "file.create": async (input: HandlerInput): Promise<FileCreateResult> => {
       const args = input.args as unknown as FileCreateArgs;
-      const at = paths.locate(args, viewer(input));
+      const at = await paths.locate(args, viewer(input));
       const parent = dirname(at.real);
-      if (!isDirectory(parent)) {
+      if (!(await isDirectory(parent))) {
         throw new OpError("not_found", `${args.path} has no folder to be created in`);
       }
-      create(at.real, args.content);
+      await create(at.real, args.content);
       return { sid: args.sid, path: at.path };
     },
 
-    "file.edit": (input: HandlerInput): FileEditResult => {
+    "file.edit": async (input: HandlerInput): Promise<FileEditResult> => {
       const args = input.args as unknown as FileEditArgs;
-      const at = paths.locate(args, viewer(input));
-      const stat = existing(at);
-      if (!stat.isFile()) throw new OpError("not_found", `${args.path} is not a file`);
-      if (isBinary(bytesOf(at.real, SNIFF))) {
+      const at = await paths.locate(args, viewer(input));
+      const before = await existing(at);
+      if (!before.isFile()) throw new OpError("not_found", `${args.path} is not a file`);
+      if (isBinary(await bytesOf(at.real, SNIFF))) {
         throw new OpError("not_a_text_file", `${args.path} holds binary content`);
       }
-      if (mtimeOf(stat) !== args.expected_mtime_at || stat.size !== args.expected_size) {
+      if (mtimeOf(before) !== args.expected_mtime_at || before.size !== args.expected_size) {
         throw new OpError("file_conflict", `${args.path} changed since it was read`);
       }
-      replace(at.real, args.content);
-      const after = statSync(at.real);
-      return { sid: args.sid, path: at.path, size: after.size, mtime_at: mtimeOf(after) };
+      await replace(at.real, args.content);
+      const after = await stat(at.real);
+      return {
+        sid: args.sid,
+        path: at.path,
+        size: after.size,
+        mtime_at: mtimeOf(after),
+      };
     },
 
-    "file.delete": (input: HandlerInput): FileDeleteResult => {
+    "file.delete": async (input: HandlerInput): Promise<FileDeleteResult> => {
       const args = input.args as unknown as FileDeleteArgs;
-      const at = paths.locate(args, viewer(input));
+      const at = await paths.locate(args, viewer(input));
       // What is unlinked is what is named, so this reads the name itself rather
       // than what it resolves to: a symlink is refused as the wrong kind of
       // thing instead of taking its target's answer. The resolved path is the
       // one containment admitted and would answer for the target, which is the
       // file a link inside the root could otherwise be pointed at.
-      const stat = lstatOf(at.named);
+      const stat = await lstatOf(at.named);
       if (stat === undefined) throw new OpError("not_found", `${args.path} is not there`);
       if (!stat.isFile()) {
         throw new OpError("path_forbidden", `${args.path} is not a plain file`);
       }
-      unlinkSync(at.named);
+      await unlink(at.named);
       return { sid: args.sid, path: at.path };
     },
 
-    "file.find": (input: HandlerInput): FileFindResult => {
+    "file.find": async (input: HandlerInput): Promise<FileFindResult> => {
       const args = input.args as unknown as FileFindArgs;
-      const at = paths.root(
-        { sid: args.sid, kind: args.kind, ...(args.root === undefined ? {} : { path: args.root }) },
+      const at = await paths.root(
+        {
+          sid: args.sid,
+          kind: args.kind,
+          ...(args.root === undefined ? {} : { path: args.root }),
+        },
         viewer(input),
       );
       const terms = parseQuery(args.query);
       // A query with nothing to include matches nothing rather than the whole
       // tree, so a cleared search box costs no walk at all.
       if (terms.include.length === 0) return { sid: args.sid, hits: [], truncated: false };
-      const walk = find(at, terms, args.respect_gitignore ?? true);
+      const walk = await find(at, terms, args.respect_gitignore ?? true);
       return { sid: args.sid, hits: walk.hits, truncated: walk.truncated };
     },
 
-    "file.stat": (input: HandlerInput): FileStatResult => {
+    "file.stat": async (input: HandlerInput): Promise<FileStatResult> => {
       const args = input.args as unknown as FileStatArgs;
-      const results = args.paths.map((path): FileStatEntry | null => {
-        const at = paths.identify(args.sid, path, viewer(input));
-        if (at === undefined || !isFile(at.real)) return null;
-        return { kind: at.kind, path: at.path };
-      });
+      const results = await Promise.all(
+        args.paths.map(async (path): Promise<FileStatEntry | null> => {
+          const at = await paths.identify(args.sid, path, viewer(input));
+          if (at === undefined || !(await isFile(at.real))) return null;
+          return { kind: at.kind, path: at.path };
+        }),
+      );
       return { results };
     },
   };
 }
 
 /** The file a located path names, or the contract's word for "not there". */
-function existing(at: Located) {
+async function existing(at: Located) {
   try {
-    return statSync(at.real);
+    return await stat(at.real);
   } catch {
     throw new OpError("not_found", `${at.path} is not there`);
   }
 }
 
-function lstatOf(path: string) {
+async function lstatOf(path: string) {
   try {
-    return lstatSync(path);
+    return await lstat(path);
   } catch {
     return undefined;
   }
 }
 
-function isFile(path: string): boolean {
+async function isFile(path: string): Promise<boolean> {
   try {
-    return statSync(path).isFile();
+    return (await stat(path)).isFile();
   } catch {
     return false;
   }
 }
 
-function isDirectory(path: string): boolean {
+async function isDirectory(path: string): Promise<boolean> {
   try {
-    return statSync(path).isDirectory();
+    return (await stat(path)).isDirectory();
   } catch {
     return false;
   }
@@ -216,14 +232,14 @@ function mtimeOf(stat: { mtimeMs: number }): Timestamp {
 }
 
 /** A file's leading bytes, at most `limit` of them. */
-function bytesOf(path: string, limit: number): Buffer {
-  const fd = openSync(path, "r");
+async function bytesOf(path: string, limit: number): Promise<Buffer> {
+  const handle = await open(path, "r");
   try {
     const buffer = Buffer.alloc(limit);
-    const read = readSync(fd, buffer, 0, limit, 0);
-    return buffer.subarray(0, read);
+    const { bytesRead } = await handle.read(buffer, 0, limit, 0);
+    return buffer.subarray(0, bytesRead);
   } finally {
-    closeSync(fd);
+    await handle.close();
   }
 }
 
@@ -233,9 +249,9 @@ function isBinary(bytes: Buffer): boolean {
 
 /** Write a file that must not be there yet. The exclusive open is what decides
  * it: a check followed by a write would answer about the moment before. */
-function create(path: string, content: string): void {
+async function create(path: string, content: string): Promise<void> {
   try {
-    writeFileSync(path, content, { flag: "wx" });
+    await writeFile(path, content, { flag: "wx" });
   } catch (cause) {
     if ((cause as NodeJS.ErrnoException).code === "EEXIST") {
       throw new OpError("file_exists", `${basename(path)} is already there`);
@@ -247,39 +263,42 @@ function create(path: string, content: string): void {
 /** Replace a file's content whole. The write lands beside it and is renamed
  * over it, so a reader sees either the old file or the new one and never a
  * half-written one. */
-function replace(path: string, content: string): void {
+async function replace(path: string, content: string): Promise<void> {
   const temporary = `${path}.ccmsg-${process.pid}-${Date.now()}`;
-  writeFileSync(temporary, content);
+  await writeFile(temporary, content);
   try {
-    renameSync(temporary, path);
+    await rename(temporary, path);
   } catch (cause) {
-    unlinkSync(temporary);
+    await unlink(temporary);
     throw cause;
   }
 }
 
-function entriesOf(dir: string): DirEntry[] {
-  return readdirSync(dir, { withFileTypes: true })
-    .map((entry): DirEntry => {
-      const type = entry.isSymbolicLink()
-        ? "symlink"
-        : entry.isDirectory()
-          ? "dir"
-          : entry.isFile()
-            ? "file"
-            : "other";
-      // A symlink is reported as itself, so what is stated about it is the link
-      // and never what it points at — including one pointing out of the root,
-      // which is listed here and refuses to resolve everywhere else.
-      const stat = type === "symlink" ? undefined : lstatOf(join(dir, entry.name));
-      return {
-        name: entry.name,
-        type,
-        ...(stat?.isFile() === true ? { size: stat.size } : {}),
-        ...(stat === undefined ? {} : { mtime_at: mtimeOf(stat) }),
-      };
-    })
-    .sort((a, b) => a.name.localeCompare(b.name));
+async function entriesOf(dir: string): Promise<DirEntry[]> {
+  const entries = await readdir(dir, { withFileTypes: true });
+  return (
+    await Promise.all(
+      entries.map(async (entry): Promise<DirEntry> => {
+        const type = entry.isSymbolicLink()
+          ? "symlink"
+          : entry.isDirectory()
+            ? "dir"
+            : entry.isFile()
+              ? "file"
+              : "other";
+        // A symlink is reported as itself, so what is stated about it is the link
+        // and never what it points at — including one pointing out of the root,
+        // which is listed here and refuses to resolve everywhere else.
+        const info = type === "symlink" ? undefined : await lstatOf(join(dir, entry.name));
+        return {
+          name: entry.name,
+          type,
+          ...(info?.isFile() === true ? { size: info.size } : {}),
+          ...(info === undefined ? {} : { mtime_at: mtimeOf(info) }),
+        };
+      }),
+    )
+  ).sort((a, b) => a.name.localeCompare(b.name));
 }
 
 interface Terms {
@@ -312,17 +331,17 @@ function matches(path: string, terms: Terms): boolean {
  * Both caps are reported the same way: the hits are the ones found, and
  * `truncated` says they are not the whole match set. Saying so is better than
  * implying these are all. */
-function find(at: Located, terms: Terms, respectGitignore: boolean) {
+async function find(at: Located, terms: Terms, respectGitignore: boolean) {
   const hits: FileFindHit[] = [];
   let visits = 0;
   let truncated = false;
 
-  const walk = (dir: string, ignored: Ignores): void => {
+  const walk = async (dir: string, ignored: Ignores): Promise<void> => {
     if (truncated) return;
-    const here = respectGitignore ? ignored.descend(dir) : ignored;
+    const here = respectGitignore ? await ignored.descend(dir) : ignored;
     let entries: Dirent[];
     try {
-      entries = readdirSync(dir, { withFileTypes: true });
+      entries = await readdir(dir, { withFileTypes: true });
     } catch {
       // A folder that cannot be read contributes nothing, and a walk that
       // stopped at one would answer less than it can.
@@ -349,13 +368,13 @@ function find(at: Located, terms: Terms, respectGitignore: boolean) {
       // Only real directories are descended: a symlink is answered as itself,
       // and following one would walk out of the root the walk is bounded by.
       if (isDir && !entry.isSymbolicLink()) {
-        walk(full, here);
+        await walk(full, here);
         if (truncated) return;
       }
     }
   };
 
-  walk(at.real, EMPTY_IGNORES);
+  await walk(at.real, EMPTY_IGNORES);
   return { hits, truncated };
 }
 
@@ -372,7 +391,7 @@ function find(at: Located, terms: Terms, respectGitignore: boolean) {
  * hiding one. */
 interface Ignores {
   hides(name: string, isDir: boolean): boolean;
-  descend(dir: string): Ignores;
+  descend(dir: string): Promise<Ignores>;
 }
 
 const ALWAYS_HIDDEN = new Set([".git"]);
@@ -385,17 +404,17 @@ function makeIgnores(patterns: readonly RegExp[]): Ignores {
       if (ALWAYS_HIDDEN.has(name)) return true;
       return patterns.some((pattern) => pattern.test(name));
     },
-    descend(dir) {
-      const own = readIgnoreFile(join(dir, ".gitignore"));
+    async descend(dir) {
+      const own = await readIgnoreFile(join(dir, ".gitignore"));
       return own.length === 0 ? makeIgnores(patterns) : makeIgnores([...patterns, ...own]);
     },
   };
 }
 
-function readIgnoreFile(file: string): RegExp[] {
+async function readIgnoreFile(file: string): Promise<RegExp[]> {
   let text: string;
   try {
-    text = readFileSync(file, "utf8");
+    text = await readFile(file, "utf8");
   } catch {
     return [];
   }

package/src/instance/instance.ts

@@ -363,6 +363,11 @@ export class Instance {
   readonly #direct: DirectRoute;
   readonly #notify: Notify;
   readonly #translate: Translate | undefined;
+  /** Everything that writes to the state directory as it changes rather than
+   * at exit (DESIGN §2.5). A stop waits for what they have asked for before it
+   * lets go of the config home, so a successor reads what this instance last
+   * said (DESIGN §8.5 step 4). */
+  readonly #persisted: { flush(): Promise<void> }[] = [];
   /** The person's authentication: who may open a connection, and the records
    * that say so (DR-0001). */
   readonly #auth: Auth;
@@ -438,7 +443,19 @@ export class Instance {
       // what this instance writes travels as its own (DR-0001 §2.6).
       element: (_topic, _instance, data) => {
         const stated = (data as { records?: AuthRecord[] } | undefined)?.records;
-        if (Array.isArray(stated)) this.#auth.merge(stated);
+        // Folded in as it arrives: the element callback is not what the peer
+        // waits on, and the set is written down before the removals in it are
+        // acted on (DR-0015). A set that could not be written is said here and
+        // nowhere else — there is no caller to answer, and the records come
+        // back from the peers that also hold them.
+        if (Array.isArray(stated)) {
+          void this.#auth.merge(stated).catch((cause: unknown) => {
+            this.log.write("auth records merge failed", {
+              instance: this.self,
+              cause: String(cause),
+            });
+          });
+        }
       },
       // The mesh view is this instance's own, so the topic that carries it is
       // restated when that view moves (DESIGN §7.5).
@@ -549,6 +566,7 @@ export class Instance {
 
     const inbox = new Inbox(inboxPath(paths.stateDir));
     inbox.load();
+    this.#persisted.push(inbox);
     // Route (a) is the harness's own way in (DESIGN §6.5): Claude Code's messaging
     // socket, Codex's thread queue. Which one an instance speaks follows the
     // config home it answers for (DESIGN §4.1), and the flag turns the route off for
@@ -602,6 +620,7 @@ export class Instance {
     const kv = new KvStore(join(paths.stateDir, KV_DIR), this.self, (topic, data) => {
       this.#topics.publish(topic, data);
     });
+    this.#persisted.push(kv);
     this.#topics.attach("kv", kv);
 
     // The credentials, tokens and removals the mesh shares (DR-0001 §2.6).
@@ -615,6 +634,7 @@ export class Instance {
         this.#topics.publish("auth.records", { records: written });
       },
     });
+    this.#persisted.push(records);
     this.#auth = new Auth({
       self: this.self,
       records,
@@ -714,11 +734,9 @@ export class Instance {
         handle: (frame, conn) => {
           const admin = adminRequestOf(frame);
           if (admin !== undefined) {
-            return Promise.resolve(
-              handleAdmin(
-                { auth: this.#auth, ...(this.#mesh === undefined ? {} : { mesh: this.#mesh }) },
-                admin,
-              ),
+            return handleAdmin(
+              { auth: this.#auth, ...(this.#mesh === undefined ? {} : { mesh: this.#mesh }) },
+              admin,
             );
           }
           return this.handle(frame, conn);
@@ -997,10 +1015,16 @@ export class Instance {
     // 3. tell the connections, while they can still be told
     const restarting: RestartingEvent = { ev: "restarting", instance: this.self };
     for (const conn of this.#conns) conn.send(restarting);
-    // 4. settle what is persisted. `last_live` and the inbox are written as
-    // they change rather than at exit, so there is nothing held back to flush;
-    // the log's writer is synchronous for the same reason (DESIGN §2.5).
+    // 4. settle what is persisted. `last_live`, the inbox, the store and the
+    // records are written as they change rather than at exit (DESIGN §2.5), so
+    // what is held back is only what has been asked for and has not landed —
+    // and it has to land before the lock goes, since a successor reads these
+    // files as it starts.
     this.log.write("stopping", { instance: this.self });
+    await Promise.allSettled([
+      this.#sessions.flush(),
+      ...this.#persisted.map((held) => held.flush()),
+    ]);
     // 5. let the resources go, the unix socket last. Closing takes the path
     // this process bound, and only that one: the stable address is a symlink
     // nothing here touches, because a successor may have already pointed it at
@@ -1016,8 +1040,11 @@ export class Instance {
     } finally {
       // The pid and lock are the observable proof that this process is still
       // leaving. Released only after every listener has finished closing, so a
-      // client cannot mistake an unreachable socket for a completed stop.
+      // client cannot mistake an unreachable socket for a completed stop — and
+      // after the log's own last lines, this one included, are on disk: what a
+      // reader wants from the log of a stopped instance is how it ended.
       remove(this.paths.pidFile);
+      await this.log.flush();
       this.lock.release();
     }
   }

package/src/instance/log.ts

@@ -1,15 +1,24 @@
-import { appendFileSync, mkdirSync } from "node:fs";
+import { mkdirSync } from "node:fs";
+import { appendFile } from "node:fs/promises";
 import { dirname } from "node:path";
 
-/** The instance's log: one writer, and every line on disk before the call
- * returns (DESIGN §2.5).
+/** The instance's log: one writer, and the file in the order the calls were
+ * made (DESIGN §2.5).
  *
- * The reason to read a log is to find out why a process stopped, so the line
- * that matters most is the last one written before it did. A buffered writer
- * is the one that loses exactly that line, so this one appends synchronously
- * and holds nothing — the cost is a write per line, on a file that takes a
- * line per lifecycle event rather than per request. */
+ * A line is written where anything at all is happening — a lifecycle step, a
+ * mesh callback, a session appearing — so the write cannot be the one thing
+ * that stops the instance while it lands (DR-0015). Each append is chained onto
+ * the one before it, which is what keeps the order the calls stated; what a
+ * kill can cost is the last line or two that had not reached the file yet, and
+ * for a log that is a cheaper loss than holding the process still for every
+ * line.
+ *
+ * `flush` is for the one moment that loss is avoidable: a stop that is being
+ * waited on can wait for its own last line. */
 export class Log {
+  /** The appends already asked for, as one chain. */
+  #written: Promise<void> = Promise.resolve();
+
   constructor(
     private readonly file: string,
     /** Mirrored to stderr so a foreground run shows what it is doing. */
@@ -21,10 +30,17 @@ export class Log {
   write(message: string, fields: Record<string, unknown> = {}): void {
     const line = JSON.stringify({ at: new Date().toISOString(), message, ...fields });
     if (this.echo) process.stderr.write(`${line}\n`);
-    try {
-      appendFileSync(this.file, `${line}\n`);
-    } catch {
-      // A log that cannot be written is not a reason to stop serving.
-    }
+    this.#written = this.#written.then(async () => {
+      try {
+        await appendFile(this.file, `${line}\n`);
+      } catch {
+        // A log that cannot be written is not a reason to stop serving.
+      }
+    });
+  }
+
+  /** Settle once every line asked for so far is on disk. */
+  async flush(): Promise<void> {
+    await this.#written;
   }
 }