@ccmsg/cli 0.1.0

package/src/daemon/control.ts

@@ -0,0 +1,88 @@
+import { PROTOCOL_VERSION } from "@ccmsg/protocol";
+
+/** One short exchange over an instance's unix socket.
+ *
+ * The CLI asks one thing at a time, so a `request_id` is a counter and the
+ * answer is the next frame: nothing here needs correlation, and the connection
+ * lives no longer than the command that opened it. */
+export interface Conn {
+  ask(request: Record<string, unknown>): Promise<Record<string, unknown>>;
+  /** The next frame the instance sends without having been asked for one: a
+   * topic frame, or an event about the connection itself. Every frame arrives
+   * on the one stream `ask` reads its reply from, so a caller that subscribes
+   * reads on with this instead of asking again. */
+  next(): Promise<Record<string, unknown>>;
+  close(): void;
+}
+
+/** The instance behind a socket path, or nothing when there is none. */
+export async function connect(path: string): Promise<Conn | undefined> {
+  const replies = new Replies();
+  let socket: Bun.Socket<undefined>;
+  try {
+    socket = await Bun.connect({
+      unix: path,
+      socket: {
+        data(_socket, chunk) {
+          replies.push(chunk);
+        },
+      },
+    });
+  } catch {
+    return undefined;
+  }
+  let counter = 0;
+  return {
+    ask(request) {
+      counter += 1;
+      socket.write(`${JSON.stringify({ request_id: `${counter}`, ...request })}\n`);
+      return replies.next();
+    },
+    next() {
+      return replies.next();
+    },
+    close() {
+      socket.end();
+    },
+  };
+}
+
+/** Greet as the person running the command.
+ *
+ * `role: "user"` because that is what the caller is: the lifecycle ops belong
+ * to whoever operates the host, not to a session speaking from inside a turn. */
+export function greetAsUser(conn: Conn): Promise<Record<string, unknown>> {
+  return conn.ask({ op: "hello", role: "user", protocol_version: PROTOCOL_VERSION });
+}
+
+/** Reassemble the replies of one exchange, by arrival order. */
+class Replies {
+  readonly #ready: Record<string, unknown>[] = [];
+  #waiting: ((frame: Record<string, unknown>) => void) | undefined;
+  #buffer = "";
+
+  push(chunk: Uint8Array): void {
+    this.#buffer += new TextDecoder().decode(chunk);
+    let at: number;
+    while ((at = this.#buffer.indexOf("\n")) >= 0) {
+      const line = this.#buffer.slice(0, at);
+      this.#buffer = this.#buffer.slice(at + 1);
+      if (line.trim() === "") continue;
+      const frame = JSON.parse(line) as Record<string, unknown>;
+      const waiting = this.#waiting;
+      if (waiting === undefined) this.#ready.push(frame);
+      else {
+        this.#waiting = undefined;
+        waiting(frame);
+      }
+    }
+  }
+
+  next(): Promise<Record<string, unknown>> {
+    const first = this.#ready.shift();
+    if (first !== undefined) return Promise.resolve(first);
+    return new Promise((resolve) => {
+      this.#waiting = resolve;
+    });
+  }
+}

package/src/daemon/index.ts

@@ -0,0 +1,6 @@
+export * from "./control.ts";
+export * from "./link.ts";
+export * from "./log.ts";
+export * from "./registry.ts";
+export * from "./snapshot.ts";
+export * from "./supervise.ts";

package/src/daemon/link.ts

@@ -0,0 +1,93 @@
+import type { ErrorCode } from "@ccmsg/protocol";
+import { type Env, resolveSupervisorSocket } from "../instance/paths.ts";
+import { connect } from "./control.ts";
+
+/** What a command asks the supervisor for.
+ *
+ * Its own protocol, not the contract's: these are requests about processes on
+ * this host, spoken over a socket no client outside it reaches, and nothing
+ * here is something a web UI or a mesh peer may ask. The `supervise_` prefix is
+ * what keeps the two from being read as one — an op name here is not an op
+ * name there, and no attribute table covers these. */
+export const SUPERVISE_OPS = [
+  "supervise_start",
+  "supervise_stop",
+  "supervise_restart",
+  "supervise_status",
+  "supervise_add",
+  "supervise_remove",
+] as const;
+
+export type SuperviseOp = (typeof SUPERVISE_OPS)[number];
+
+export interface SuperviseRequest {
+  readonly op: SuperviseOp;
+  /** The config home the request is about. Absent with `all`. */
+  readonly dir?: string;
+  /** Every config home the supervisor looks after. */
+  readonly all?: boolean;
+}
+
+/** Why a command could not be carried out.
+ *
+ * The contract's codes wherever one fits, because a person reading a ccmsg
+ * error should not have to learn a second vocabulary for the same thing. The
+ * one addition is the failure the contract has no word for: there is no
+ * supervisor, which is not an op being refused but nobody being there to
+ * refuse it. */
+export type CliErrorCode = ErrorCode | "supervisor_not_running";
+
+/** The one command that answers without a supervisor is `daemon log`: a log is
+ * read after something died, and requiring the supervisor to be up would make
+ * the record unreadable exactly when it is wanted. */
+export const NO_SUPERVISOR: CliErrorCode = "supervisor_not_running";
+
+export class CommandError extends Error {
+  constructor(
+    readonly code: CliErrorCode,
+    msg: string,
+    /** What the command found before it stopped, for a failure that has more
+     * to say than a line: the same report the command would have answered
+     * with. Printed beside the error so a caller reads one shape whether the
+     * command worked or not. */
+    readonly detail?: unknown,
+  ) {
+    super(msg);
+    this.name = "CommandError";
+  }
+}
+
+export function noSupervisor(): CommandError {
+  return new CommandError(
+    NO_SUPERVISOR,
+    "監督者が動いていません (`ccmsg service start` か `ccmsg daemon supervise` で起動してください)",
+  );
+}
+
+/** Put one request to the supervisor, and answer with what it said.
+ *
+ * A connection per command: these are one exchange each, and a socket that
+ * outlived the command would be a client the supervisor has to keep track of
+ * for nothing. */
+export async function ask(request: SuperviseRequest, env: Env = process.env): Promise<unknown> {
+  const conn = await connect(resolveSupervisorSocket(env));
+  if (conn === undefined) throw noSupervisor();
+  try {
+    const answer = await conn.ask({ ...request });
+    if (answer["ok"] === true) return answer["result"];
+    const error = answer["error"] as { code?: CliErrorCode; msg?: string } | undefined;
+    throw new CommandError(error?.code ?? "internal_error", error?.msg ?? JSON.stringify(answer));
+  } finally {
+    conn.close();
+  }
+}
+
+/** Whether a supervisor is there at all, for the two commands that carry on
+ * without one rather than failing: writing the config is worth doing whether or
+ * not anybody is listening for the news. */
+export async function reachable(env: Env = process.env): Promise<boolean> {
+  const conn = await connect(resolveSupervisorSocket(env));
+  if (conn === undefined) return false;
+  conn.close();
+  return true;
+}

package/src/daemon/log.ts

@@ -0,0 +1,116 @@
+import { type FSWatcher, existsSync, statSync, watch } from "node:fs";
+import { open } from "node:fs/promises";
+import { dirname } from "node:path";
+
+/** How much of a log is shown when one is opened.
+ *
+ * The reason to read a log is to find out what just happened, so what is wanted
+ * is its recent end rather than its history — and a bound is what keeps
+ * `daemon log --all` on a long-running host from being a whole day of lines
+ * before the first new one arrives. */
+export const LOG_TAIL_BYTES = 256 * 1024;
+
+/** Where reading a log left off, so following it starts where showing it ended
+ * and no line is shown twice. */
+export interface Read {
+  readonly lines: readonly string[];
+  readonly end: number;
+}
+
+/** The bytes of `[from, to)`, cut back to the last complete line.
+ *
+ * A line still being written is left for the next read: the log's writer
+ * appends whole lines (`Log`), so half a line on disk is one being written
+ * right now rather than one that will stay half. */
+async function readRange(file: string, from: number, to: number): Promise<Read> {
+  if (to <= from) return { lines: [], end: from };
+  const handle = await open(file, "r");
+  try {
+    const buffer = Buffer.alloc(to - from);
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, from);
+    const text = buffer.subarray(0, bytesRead).toString("utf8");
+    const complete = text.slice(0, text.lastIndexOf("\n") + 1);
+    return {
+      lines: complete.split("\n").filter((line) => line !== ""),
+      end: from + Buffer.byteLength(complete),
+    };
+  } finally {
+    await handle.close();
+  }
+}
+
+/** The end of a log, and where it ends.
+ *
+ * The window starts at a byte rather than at a line, so the first line it lands
+ * inside is dropped: a fragment of a record is not a record. */
+export async function tailOf(file: string, bytes = LOG_TAIL_BYTES): Promise<Read> {
+  if (!existsSync(file)) return { lines: [], end: 0 };
+  const size = statSync(file).size;
+  const from = Math.max(0, size - bytes);
+  const read = await readRange(file, from, size);
+  return from === 0 ? read : { lines: read.lines.slice(1), end: read.end };
+}
+
+/** Follow a file, on its own change notifications rather than on a clock.
+ *
+ * The watch is on the directory as well as on the file, because a log that does
+ * not exist yet is one a watch cannot attach to and the instance writing it may
+ * not have started.
+ *
+ * A file that shrank is one that was rotated or replaced, so reading continues
+ * from its start: what was there before is gone, and holding the old offset
+ * would skip everything written since. */
+export function follow(
+  file: string,
+  from: number,
+  onLines: (lines: readonly string[]) => void,
+): { close(): void } {
+  let offset = from;
+  let reading: Promise<void> = Promise.resolve();
+  const watchers: FSWatcher[] = [];
+  const pull = (): void => {
+    reading = reading.then(async () => {
+      if (!existsSync(file)) return;
+      const size = statSync(file).size;
+      if (size < offset) offset = 0;
+      const read = await readRange(file, offset, size);
+      if (read.lines.length > 0) onLines(read.lines);
+      offset = read.end;
+    });
+  };
+  for (const at of new Set([file, dirname(file)])) {
+    try {
+      watchers.push(watch(at, pull));
+    } catch {
+      // Not there yet. The directory watch is what catches the file appearing;
+      // when neither attaches there is nothing to follow and nothing to report.
+    }
+  }
+  pull();
+  return {
+    close(): void {
+      for (const watcher of watchers) watcher.close();
+    },
+  };
+}
+
+/** One log line as it is shown, which is the line itself when it is JSON and a
+ * record carrying it when it is not.
+ *
+ * The instance writes JSON per line, so `--all` can add which instance a line
+ * came from by putting the fields beside it. A line from anywhere else — a
+ * crash the runtime printed, an init system's own words — is not JSON and is
+ * shown as text under `line`, because dropping it would hide exactly the
+ * failure somebody opened the log for. */
+export function labelled(line: string, fields: Record<string, unknown>): string {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return JSON.stringify({ ...fields, line });
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return JSON.stringify({ ...fields, line });
+  }
+  return JSON.stringify({ ...fields, ...(parsed as Record<string, unknown>) });
+}

package/src/daemon/registry.ts

@@ -0,0 +1,285 @@
+import { existsSync, mkdirSync, watch } from "node:fs";
+import { basename, isAbsolute, join, resolve } from "node:path";
+import type { Endpoint, InstanceId, InstancePingResult } from "@ccmsg/protocol";
+import {
+  type InstanceEntry,
+  loadShared,
+  saveShared,
+  type SharedConfig,
+} from "../instance/config.ts";
+import { instanceIdentity } from "../instance/identity.ts";
+import { alive, lockHolder } from "../instance/lock.ts";
+import { type Env, type InstancePaths, resolvePaths } from "../instance/paths.ts";
+import { prepareSocketDir } from "../instance/socket.ts";
+import { connect, greetAsUser } from "./control.ts";
+import { CommandError } from "./link.ts";
+
+/** What a config home has to be for an instance to answer for it.
+ *
+ * `settings.json` is the harness's own file, so its presence is what says the
+ * directory is a config home rather than any directory somebody typed. Checked
+ * where a directory is named — `add` and `run` — rather than at every use, so
+ * the mistake is caught when it is made. */
+export function configHome(dir: string): string {
+  const path = isAbsolute(dir) ? dir : resolve(dir);
+  if (!existsSync(join(path, "settings.json"))) {
+    throw new CommandError(
+      "not_found",
+      `${path} は Claude Code の config home ではありません (settings.json がありません)`,
+    );
+  }
+  return path;
+}
+
+/** One row of `daemon list`: which config home, and whether anything answers
+ * for it right now. */
+export interface InstanceRow {
+  readonly id: InstanceId;
+  readonly dir: string;
+  readonly running: boolean;
+  readonly pid?: number;
+}
+
+/** One row of `daemon status`: the list's row, plus what the instance itself
+ * says when there is one to ask. */
+export interface StatusRow extends InstanceRow {
+  readonly version?: string;
+  readonly network?: InstancePingResult["network"];
+  /** The other instances this one names, each with where it is dialled: the id
+   * says which instance and the endpoint says how to reach it, and neither
+   * follows from the other (DR-0001 §2.1). */
+  readonly peers?: readonly { readonly id: InstanceId; readonly endpoint: Endpoint }[];
+}
+
+/** Everything one command needs to reach one config home. */
+export interface Target {
+  readonly dir: string;
+  readonly paths: InstancePaths;
+}
+
+export function targetFor(env: Env, dir: string): Target {
+  return { dir, paths: resolvePaths({ ...env, CLAUDE_CONFIG_DIR: dir }) };
+}
+
+/** The config homes the shared file lists, in the order it lists them. */
+export function registered(env: Env): Target[] {
+  const paths = resolvePaths(env);
+  return loadShared(paths.configFile).instances.map((entry) => targetFor(env, entry.dir));
+}
+
+/** Add a config home to the shared file. The settings it will run with are the
+ * defaults until somebody edits its entry, so the entry starts empty. */
+export function add(env: Env, dir: string): InstanceRow {
+  const home = configHome(dir);
+  const file = resolvePaths(env).configFile;
+  const shared = loadShared(file);
+  if (shared.instances.some((entry) => entry.dir === home)) {
+    throw new CommandError("file_exists", `${home} は既に登録されています`);
+  }
+  const entry: InstanceEntry = { dir: home, settings: {} };
+  saveShared(file, { ...shared, instances: [...shared.instances, entry] });
+  const target = targetFor(env, home);
+  // The id is made here rather than at the first start, so that what `add`
+  // prints is what the instance will answer to and so that a person can write
+  // the id into a peer's config before anything has run (DR-0001 §2.1).
+  instanceIdentity(target.paths.instanceIdFile);
+  return rowFor(target);
+}
+
+/** Take a config home off the list.
+ *
+ * The instance it names is left alone: what this changes is what the supervisor
+ * starts and what `--all` reaches, and an instance already serving a session is
+ * not something a list edit should take away from it. `daemon stop` is how one
+ * is stopped, and saying so is the point of keeping the two apart. */
+export function remove(env: Env, dir: string): { dir: string; removed: boolean } {
+  const home = isAbsolute(dir) ? dir : resolve(dir);
+  const file = resolvePaths(env).configFile;
+  const shared: SharedConfig = loadShared(file);
+  const kept = shared.instances.filter((entry) => entry.dir !== home);
+  if (kept.length === shared.instances.length) {
+    throw new CommandError("not_found", `${home} は登録されていません`);
+  }
+  saveShared(file, { ...shared, instances: kept });
+  return { dir: home, removed: true };
+}
+
+/** What an instance is called, whether or not it is running.
+ *
+ * Read from the state directory rather than asked, so a stopped instance still
+ * has the name the running one answers to — and written there if it is not
+ * there yet, which is what makes this total for a config home that has been
+ * registered but never started (DR-0001 §2.1). */
+export function idOf(target: Target): InstanceId {
+  return instanceIdentity(target.paths.instanceIdFile);
+}
+
+export function rowFor(target: Target): InstanceRow {
+  const pid = lockHolder(target.paths.lockFile);
+  const running = pid !== undefined && alive(pid);
+  return {
+    id: idOf(target),
+    dir: target.dir,
+    running,
+    ...(running ? { pid } : {}),
+  };
+}
+
+export function list(env: Env): InstanceRow[] {
+  return registered(env).map((target) => rowFor(target));
+}
+
+/** Ask one instance how it is. A config home with nothing behind it answers the
+ * list's row and nothing more: not running is a state, not a failure. */
+export async function status(target: Target): Promise<StatusRow> {
+  const row = rowFor(target);
+  const conn = await connect(target.paths.socket);
+  if (conn === undefined) return row;
+  try {
+    const greeting = await greetAsUser(conn);
+    if (greeting["ok"] !== true) return row;
+    const peers =
+      (greeting["instances"] as { id: InstanceId; endpoint: Endpoint }[] | undefined) ?? [];
+    const answer = await conn.ask({ op: "instance_ping" });
+    if (answer["ok"] !== true) return row;
+    const ping = answer as unknown as InstancePingResult;
+    return {
+      ...row,
+      id: ping.instance,
+      running: true,
+      pid: ping.pid,
+      version: ping.version,
+      network: ping.network,
+      peers: peers
+        .filter((one) => one.id !== ping.instance)
+        .map((one) => ({ id: one.id, endpoint: one.endpoint })),
+    };
+  } finally {
+    conn.close();
+  }
+}
+
+/** Ask one instance to stop, over its own socket.
+ *
+ * The contract's op rather than a signal, so the request goes through the same
+ * authorization every other op does and the caller is told it was accepted
+ * before the process goes down (§8.5). */
+export async function stop(target: Target): Promise<{ dir: string; stopped: boolean }> {
+  const conn = await connect(target.paths.socket);
+  if (conn === undefined) {
+    throw new CommandError("instance_unreachable", `${target.dir} の instance は動いていません`);
+  }
+  try {
+    const greeting = await greetAsUser(conn);
+    if (greeting["ok"] !== true) {
+      throw new CommandError("forbidden", `hello が拒否されました: ${JSON.stringify(greeting)}`);
+    }
+    const answer = await conn.ask({ op: "instance_shutdown" });
+    if (answer["ok"] !== true) {
+      throw new CommandError("internal_error", `停止を拒否されました: ${JSON.stringify(answer)}`);
+    }
+    return { dir: target.dir, stopped: true };
+  } finally {
+    conn.close();
+  }
+}
+
+/** How this process was started, so a child can be started the same way.
+ *
+ * The interpreter and the entry script rather than a name on `PATH`: a
+ * supervisor that resolved `ccmsg` again could start a different build from the
+ * one that spawned it, and which build is running is exactly what a person
+ * chasing a stale instance is trying to find out. */
+export const ENTRY = new URL("../cli.ts", import.meta.url).pathname;
+
+export interface Child {
+  readonly pid: number;
+  readonly exited: Promise<number>;
+  kill(signal?: NodeJS.Signals): void;
+}
+
+/** How a child instance is started. Injected so a test drives the supervisor
+ * without spawning one. */
+export type SpawnInstance = (dir: string, env: Env) => Child;
+
+export const spawnInstance: SpawnInstance = (dir, env) => {
+  const proc = Bun.spawn([process.execPath, ENTRY, "daemon", "run", dir], {
+    stdio: ["ignore", "ignore", "ignore"],
+    env: { ...env, CLAUDE_CONFIG_DIR: dir } as Record<string, string>,
+  });
+  return {
+    pid: proc.pid,
+    exited: proc.exited,
+    kill: (signal) => {
+      proc.kill(signal ?? "SIGTERM");
+    },
+  };
+};
+
+/** How long a start waits for the instance it spawned to be reachable before
+ * reporting what it saw.
+ *
+ * A deadline rather than an interval: what is waited on is the socket appearing
+ * or the child exiting, both of which are events, and this only bounds how long
+ * a start that does neither may hold the caller. */
+export const START_TIMEOUT_MS = 10_000;
+
+/** The directories an instance will fill, made before the child that fills
+ * them: a watch cannot report a change in a directory that does not exist. */
+export function prepareFor(target: Target): void {
+  mkdirSync(target.paths.stateDir, { recursive: true });
+  prepareSocketDir(target.paths);
+}
+
+/** Wait for the stable socket to appear, on the directory's own change
+ * notifications rather than on a clock.
+ *
+ * The check comes first and again after the watch is up, because the socket may
+ * be published in the window between the two and a watch reports only what
+ * happens after it starts. */
+export function awaitSocket(paths: InstancePaths, timeoutMs: number): Promise<void> {
+  return awaitEntry(paths, timeoutMs, () => existsSync(paths.socket));
+}
+
+/** Wait for the lock to be released, which is the last thing a departing
+ * instance does (§8.5). */
+export function awaitGone(paths: InstancePaths, timeoutMs: number): Promise<void> {
+  return awaitEntry(paths, timeoutMs, () => {
+    const pid = lockHolder(paths.lockFile);
+    return pid === undefined || !alive(pid);
+  });
+}
+
+function awaitEntry(paths: InstancePaths, timeoutMs: number, ready: () => boolean): Promise<void> {
+  if (ready()) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const watchers: { close(): void }[] = [];
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const done = (cause?: Error): void => {
+      clearTimeout(timer);
+      for (const watcher of watchers) watcher.close();
+      if (cause === undefined) resolve();
+      else reject(cause);
+    };
+    const look = (): void => {
+      if (ready()) done();
+    };
+    for (const dir of new Set([paths.socketDir, paths.stateDir])) {
+      try {
+        watchers.push(watch(dir, look));
+      } catch {
+        // The directory is not there yet; the other watch, or the deadline,
+        // is what this run has.
+      }
+    }
+    timer = setTimeout(() => {
+      done(
+        new CommandError(
+          "internal_error",
+          `${basename(paths.configHome)} の instance を ${String(timeoutMs)}ms 待ちましたが応答がありません`,
+        ),
+      );
+    }, timeoutMs);
+    look();
+  });
+}