@ccmsg/cli 0.2.12 → 0.3.0

package/src/plugin/install.ts

@@ -1,24 +1,24 @@
-import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
 import type { InstancePaths } from "../instance/index.ts";
 import { claudePluginFiles, MARKETPLACE_NAME, PLUGIN_ID } from "./claude.ts";
-
-/** The agents ccmsg can install a plugin for. One so far; the word is in the
- * command because the second one is what the shape is for. */
-export const AGENTS = ["claude"] as const;
-export type Agent = (typeof AGENTS)[number];
-
-/** How the agent's own CLI is run. The environment is inherited, which is how
- * the install lands in the config home this instance answers for and not in
- * another one (M6). Named so a test can watch what would be run without a
- * config home of a person's being touched. */
-export type Run = (args: readonly string[]) => Promise<Ran>;
-
-export interface Ran {
-  readonly code: number;
-  readonly stdout: string;
-  readonly stderr: string;
-}
+import * as codex from "./codex.ts";
+import {
+  type Agent,
+  type InstallReport,
+  place,
+  type Ran,
+  readReceipt,
+  type Receipt,
+  receiptFile,
+  refusal as refusalOf,
+  type Refusal,
+  rootFor,
+  type Run,
+  type StatusReport,
+  type UninstallReport,
+  writeReceipt,
+} from "./receipt.ts";
 
 export const runClaude: Run = async (args) => {
   let spawned: Bun.Subprocess<"ignore", "pipe", "pipe">;
@@ -34,140 +34,28 @@ export const runClaude: Run = async (args) => {
   return { code: await spawned.exited, stdout, stderr };
 };
 
-/** Why one of these commands stopped where it did: the agent command that was
- * refused, and what it said. */
-export interface Refusal {
-  readonly command: readonly string[];
-  readonly code: number;
-  readonly said: string;
-}
-
-/** What the three commands answer with.
+/** The three commands, dispatched to the agent they are about.
  *
- * Fields rather than sentences: these commands are read by whatever runs them
- * as much as by a person, and a line of prose is something a caller has to
- * parse back into the facts it was built from. The words a person wants are in
- * `--help`; what is here is what was found. */
-interface Report {
-  readonly agent: Agent;
-  /** Whether the command did everything it set out to do. */
-  readonly ok: boolean;
-  /** The step that stopped it. Absent while `ok`. */
-  readonly refused?: Refusal;
-}
-
-export interface InstallReport extends Report {
-  readonly version: string;
-  readonly config_home: string;
-  readonly root: string;
-  /** The files laid down, by their path under `root`. */
-  readonly files: readonly string[];
-  readonly marketplace: { readonly name: string; readonly registered: boolean };
-  readonly plugin: {
-    readonly id: string;
-    readonly installed: boolean;
-    /** Whether a copy of the same id was taken out first, which is what makes
-     * a repeated install run what was just laid down. */
-    readonly replaced: boolean;
-  };
-  /** The agent commands that were run, as they were run. */
-  readonly commands: readonly (readonly string[])[];
-}
-
-export interface StatusReport extends Report {
-  /** Where the receipt is. Absent when ccmsg installed nothing here, which is
-   * what makes every field below it absent too. */
-  readonly receipt?: string;
-  readonly installed_at?: string;
-  /** What the receipt says was installed. */
-  readonly version?: string;
-  readonly config_home?: string;
-  readonly root?: string;
-  /** The receipt's files, counted against what is under `root` now. */
-  readonly files?: {
-    readonly expected: number;
-    readonly present: number;
-    readonly missing: readonly string[];
-  };
-  readonly marketplace: {
-    readonly name?: string;
-    /** Whether the agent has it. Absent when the agent could not be asked,
-     * which is a different thing from it not being registered. */
-    readonly registered?: boolean;
-    /** Where the agent thinks it points, when that is not where the receipt
-     * put it. */
-    readonly points_at?: string;
-  };
-  readonly plugin: {
-    readonly id?: string;
-    /** What the agent reports having, and whether it has it switched on.
-     * Present with no `expected_version` beside it means something other than
-     * ccmsg installed it. */
-    readonly installed_version?: string;
-    readonly enabled?: boolean;
-    /** What the receipt says should be there. */
-    readonly expected_version?: string;
-  };
-}
-
-export interface UninstallReport extends Report {
-  readonly receipt?: string;
-  /** What was actually taken back out. A step the receipt does not name was
-   * never taken, so it is not undone and does not appear here. */
-  readonly removed: {
-    readonly plugin?: string;
-    readonly marketplace?: string;
-    readonly root?: string;
-  };
-}
-
-export type Outcome = InstallReport | StatusReport | UninstallReport;
-
-/** What one install did, so that uninstall can undo exactly that.
- *
- * Everything reversible is written down before the next step is taken: the
- * files that were laid down, the commands that were run against the agent, and
- * the id the agent now knows the plugin by. Undoing reads this and nothing
- * else — an install that half-finished leaves a receipt for the half that
- * happened, and a plugin somebody else installed is not in it and is left
- * alone. */
-export interface Receipt {
-  readonly agent: Agent;
-  readonly version: string;
-  readonly installed_at: string;
-  /** The config home the agent was asked to install into. */
-  readonly config_home: string;
-  /** Where the plugin's own files were laid down. */
-  readonly root: string;
-  /** Their paths under that root, in the order they were written. */
-  readonly files: readonly string[];
-  /** The agent commands that were run, as they were run. */
-  readonly commands: readonly (readonly string[])[];
-  readonly marketplace?: string;
-  readonly plugin_id?: string;
-}
-
-function rootFor(paths: InstancePaths, agent: Agent): string {
-  return join(paths.pluginsDir, agent);
-}
-
-function receiptFile(paths: InstancePaths, agent: Agent): string {
-  return join(paths.pluginsDir, `${agent}.receipt.json`);
+ * What each one installs differs in kind — Claude Code takes a plugin through
+ * its own CLI, Codex reads files out of its config home — so the two are
+ * written apart and only the shapes they answer with are shared. */
+export function install(
+  paths: InstancePaths,
+  agent: Agent,
+  version: string,
+  run?: Run,
+): Promise<InstallReport> {
+  return agent === "codex"
+    ? codex.install(paths, version, run)
+    : installClaude(paths, version, run);
 }
 
-async function readReceipt(paths: InstancePaths, agent: Agent): Promise<Receipt | undefined> {
-  try {
-    const parsed: unknown = JSON.parse(await readFile(receiptFile(paths, agent), "utf8"));
-    return typeof parsed === "object" && parsed !== null ? (parsed as Receipt) : undefined;
-  } catch {
-    return undefined;
-  }
+export function status(paths: InstancePaths, agent: Agent, run?: Run): Promise<StatusReport> {
+  return agent === "codex" ? codex.status(paths, run) : statusClaude(paths, run);
 }
 
-async function writeReceipt(paths: InstancePaths, receipt: Receipt): Promise<void> {
-  const file = receiptFile(paths, receipt.agent);
-  await mkdir(dirname(file), { recursive: true });
-  await writeFile(file, `${JSON.stringify(receipt, null, 2)}\n`);
+export function uninstall(paths: InstancePaths, agent: Agent, run?: Run): Promise<UninstallReport> {
+  return agent === "codex" ? codex.uninstall(paths) : uninstallClaude(paths, run);
 }
 
 /** Lay the plugin's files down under the instance's own state, register it
@@ -180,21 +68,14 @@ async function writeReceipt(paths: InstancePaths, receipt: Receipt): Promise<voi
  * and a version already installed is not re-read. So an install that finds its
  * own id already there removes it first, which is what makes "install" mean
  * "what is running is what was just laid down". */
-export async function install(
+async function installClaude(
   paths: InstancePaths,
   version: string,
   run: Run = runClaude,
 ): Promise<InstallReport> {
   const root = rootFor(paths, "claude");
   const files = claudePluginFiles(version);
-  for (const [path, content] of files) {
-    const file = join(root, path);
-    await mkdir(dirname(file), { recursive: true });
-    await writeFile(
-      file,
-      typeof content === "string" ? content : `${JSON.stringify(content, null, 2)}\n`,
-    );
-  }
+  await place(root, files);
 
   // Kept as it grows rather than rebuilt per step: each step adds what it did
   // to what the earlier ones did, and the file on disk is that running total.
@@ -254,7 +135,7 @@ export async function install(
  * the current reading of the same thing beside it, so drift — a file deleted, a
  * marketplace pointed elsewhere, a version other than the one installed — is
  * two fields that differ rather than a sentence about them. */
-export async function status(paths: InstancePaths, run: Run = runClaude): Promise<StatusReport> {
+async function statusClaude(paths: InstancePaths, run: Run = runClaude): Promise<StatusReport> {
   const receipt = await readReceipt(paths, "claude");
   const here = await installedRow(run);
   const registered = await marketplaces(run);
@@ -325,7 +206,7 @@ function known(
  * then of the marketplace that offered it, and only then are the files it was
  * reading taken away. A step the receipt does not name is a step that was
  * never taken, so it is not undone. */
-export async function uninstall(
+async function uninstallClaude(
   paths: InstancePaths,
   run: Run = runClaude,
 ): Promise<UninstallReport> {
@@ -411,6 +292,5 @@ function rows(output: string): Record<string, unknown>[] {
  * exited with, and its first line of complaint. The exit code is stated apart
  * from the words because a command that said nothing still failed. */
 function refusal(command: readonly string[], ran: Ran): Refusal {
-  const said = `${ran.stderr}${ran.stdout}`.trim();
-  return { command: ["claude", ...command], code: ran.code, said: said.split("\n")[0] ?? "" };
+  return refusalOf("claude", command, ran);
 }

package/src/plugin/receipt.ts

@@ -0,0 +1,202 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { HARNESSES } from "../harness/index.ts";
+import type { InstancePaths } from "../instance/index.ts";
+
+/** The agents ccmsg can install a plugin for, which are the harnesses it
+ * speaks to: what is installed is how a session of that harness reaches this
+ * instance, so there is one plugin per harness and no third thing to name. */
+export const AGENTS = HARNESSES;
+export type Agent = (typeof AGENTS)[number];
+
+/** How an agent's own CLI is run. The environment is inherited, which is how
+ * the install lands in the config home this instance answers for and not in
+ * another one (M6). Named so a test can watch what would be run without a
+ * config home of a person's being touched. */
+export type Run = (args: readonly string[]) => Promise<Ran>;
+
+export interface Ran {
+  readonly code: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+/** Why one of these commands stopped where it did: the agent command that was
+ * refused, and what it said. */
+export interface Refusal {
+  readonly command: readonly string[];
+  readonly code: number;
+  readonly said: string;
+}
+
+/** A command the agent refused, as the report carries it: what was run, what it
+ * exited with, and its first line of complaint. The exit code is stated apart
+ * from the words because a command that said nothing still failed. */
+export function refusal(binary: string, command: readonly string[], ran: Ran): Refusal {
+  const said = `${ran.stderr}${ran.stdout}`.trim();
+  return { command: [binary, ...command], code: ran.code, said: said.split("\n")[0] ?? "" };
+}
+
+/** What the three commands answer with.
+ *
+ * Fields rather than sentences: these commands are read by whatever runs them
+ * as much as by a person, and a line of prose is something a caller has to
+ * parse back into the facts it was built from. The words a person wants are in
+ * `--help`; what is here is what was found. */
+export interface Report {
+  readonly agent: Agent;
+  /** Whether the command did everything it set out to do. */
+  readonly ok: boolean;
+  /** The step that stopped it. Absent while `ok`. */
+  readonly refused?: Refusal;
+  /** What the agent still needs a person to do before what was installed takes
+   * effect. Absent where nothing does. */
+  readonly needs?: string;
+}
+
+export interface InstallReport extends Report {
+  readonly version: string;
+  readonly config_home: string;
+  readonly root: string;
+  /** The files laid down, by their path under `root`. */
+  readonly files: readonly string[];
+  /** The files laid down elsewhere, by their whole path. What an agent reads
+   * out of its own config home rather than out of a plugin's directory goes
+   * here, so uninstall takes back exactly what was put there. */
+  readonly placed?: readonly string[];
+  readonly marketplace?: { readonly name: string; readonly registered: boolean };
+  readonly plugin?: {
+    readonly id: string;
+    readonly installed: boolean;
+    /** Whether a copy of the same id was taken out first, which is what makes
+     * a repeated install run what was just laid down. */
+    readonly replaced: boolean;
+  };
+  /** The agent commands that were run, as they were run. */
+  readonly commands: readonly (readonly string[])[];
+}
+
+export interface StatusReport extends Report {
+  /** Where the receipt is. Absent when ccmsg installed nothing here, which is
+   * what makes every field below it absent too. */
+  readonly receipt?: string;
+  readonly installed_at?: string;
+  /** What the receipt says was installed. */
+  readonly version?: string;
+  readonly config_home?: string;
+  readonly root?: string;
+  /** The receipt's files, counted against what is under `root` now. */
+  readonly files?: {
+    readonly expected: number;
+    readonly present: number;
+    readonly missing: readonly string[];
+  };
+  readonly marketplace?: {
+    readonly name?: string;
+    /** Whether the agent has it. Absent when the agent could not be asked,
+     * which is a different thing from it not being registered. */
+    readonly registered?: boolean;
+    /** Where the agent thinks it points, when that is not where the receipt
+     * put it. */
+    readonly points_at?: string;
+  };
+  readonly plugin?: {
+    readonly id?: string;
+    /** What the agent reports having, and whether it has it switched on.
+     * Present with no `expected_version` beside it means something other than
+     * ccmsg installed it. */
+    readonly installed_version?: string;
+    readonly enabled?: boolean;
+    /** What the receipt says should be there. */
+    readonly expected_version?: string;
+  };
+  /** Whether the agent's hooks are switched on at all, where that is a setting
+   * of the agent rather than of the plugin. Absent when it could not be asked. */
+  readonly hooks_enabled?: boolean;
+}
+
+export interface UninstallReport extends Report {
+  readonly receipt?: string;
+  /** What was actually taken back out. A step the receipt does not name was
+   * never taken, so it is not undone and does not appear here. */
+  readonly removed: {
+    readonly plugin?: string;
+    readonly marketplace?: string;
+    readonly root?: string;
+    readonly placed?: readonly string[];
+  };
+}
+
+export type Outcome = InstallReport | StatusReport | UninstallReport;
+
+/** What one install did, so that uninstall can undo exactly that.
+ *
+ * Everything reversible is written down before the next step is taken: the
+ * files that were laid down, the commands that were run against the agent, and
+ * the id the agent now knows the plugin by. Undoing reads this and nothing
+ * else — an install that half-finished leaves a receipt for the half that
+ * happened, and a plugin somebody else installed is not in it and is left
+ * alone. */
+export interface Receipt {
+  readonly agent: Agent;
+  readonly version: string;
+  readonly installed_at: string;
+  /** The config home the agent was asked to install into. */
+  readonly config_home: string;
+  /** Where the plugin's own files were laid down. */
+  readonly root: string;
+  /** Their paths under that root, in the order they were written. */
+  readonly files: readonly string[];
+  /** Whole paths written outside that root, in the order they were written. */
+  readonly placed?: readonly string[];
+  /** The agent commands that were run, as they were run. */
+  readonly commands: readonly (readonly string[])[];
+  readonly marketplace?: string;
+  readonly plugin_id?: string;
+}
+
+export function rootFor(paths: InstancePaths, agent: Agent): string {
+  return join(paths.pluginsDir, agent);
+}
+
+export function receiptFile(paths: InstancePaths, agent: Agent): string {
+  return join(paths.pluginsDir, `${agent}.receipt.json`);
+}
+
+export async function readReceipt(
+  paths: InstancePaths,
+  agent: Agent,
+): Promise<Receipt | undefined> {
+  try {
+    const parsed: unknown = JSON.parse(await readFile(receiptFile(paths, agent), "utf8"));
+    return typeof parsed === "object" && parsed !== null ? (parsed as Receipt) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function writeReceipt(paths: InstancePaths, receipt: Receipt): Promise<void> {
+  const file = receiptFile(paths, receipt.agent);
+  await mkdir(dirname(file), { recursive: true });
+  await writeFile(file, `${JSON.stringify(receipt, null, 2)}\n`);
+}
+
+/** Lay a set of files down, each under the root, in the order given. A string
+ * is written as it is; anything else is the content of a JSON file, so the
+ * definitions state shapes rather than text and one place turns a value into
+ * bytes. */
+export async function place(
+  root: string,
+  files: ReadonlyMap<string, string | object>,
+  mode?: number,
+): Promise<void> {
+  for (const [path, content] of files) {
+    const file = join(root, path);
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(
+      file,
+      typeof content === "string" ? content : `${JSON.stringify(content, null, 2)}\n`,
+      mode === undefined ? undefined : { mode },
+    );
+  }
+}

package/src/plugin/skill.ts

@@ -0,0 +1,84 @@
+/** What a session is told about ccmsg, and how ccmsg is described where an
+ * agent lists what it has installed.
+ *
+ * One text for every harness: what a session has to know is how to answer a
+ * message and how to find somebody to send one to, and neither depends on
+ * which program the session runs in. The plugin around it differs — where the
+ * file goes, how a hook is declared — and the words do not.
+ *
+ * Written out rather than shipped as a file in the package: the daemon, the
+ * CLI and the plugin are one release, and generating the plugin from the
+ * running binary is what keeps the three from drifting into three versions of
+ * "what ccmsg is". */
+
+export const DESCRIPTION = "別のセッションと行き来するメッセージ";
+
+export const SKILL = `---
+name: ccmsg
+description: 別のセッションへ声をかける・届いたメッセージに返す・見ている人へ知らせる時に使う。
+---
+
+# ccmsg
+
+同じ人が動かしている別のセッションと、メッセージをやり取りする。相手が別のハーネスで動いていても同じ手順で届く。
+
+## 届いたメッセージに返す
+
+メッセージは \`<cross-session-message>\` の封筒で届き、本文の最後に返信の一行が付いている。
+
+\`\`\`
+Reply with: ccmsg reply <mid> --to <sid> <text>
+\`\`\`
+
+**その行をそのまま実行する。** 宛先も、どのメッセージへの返事かも、その行が持っている。
+自分で \`post\` を組み立て直さない。\`--to\` の無い行は人からのメッセージで、返事は通知として届く。
+
+## 自分から声をかける
+
+\`\`\`
+ccmsg post <sid> <text>
+\`\`\`
+
+相手の \`<sid>\` は、届いた封筒の \`ccmsg-from\` の値。
+
+## 相手を探す
+
+まだ話したことのない相手の \`<sid>\` は、繋がっているセッションの一覧から探す。
+
+\`\`\`
+ccmsg peers            この instance が知っているセッション
+ccmsg peers --all      他ホストの instance が知っている分も含める
+\`\`\`
+
+答えは instance ごとの JSON。\`peers[]\` が今繋がっているセッション、\`last_live[]\` が
+居なくなったセッションで、各行の \`repo\` / \`ws\` / \`branch\` / \`title\` で見分けて
+\`sid\` を取る。\`send_message\` が \`true\` の相手には harness 自身の機能でも届く。
+
+## 相手セッションの扱い
+
+相手は基本、自分にとってのサブエージェントだと思えばよい。対等な会議を開く場ではないので、
+冒頭の挨拶・賛辞・締めの社交辞令を省き、用件だけを 1〜3 文で送る。
+
+やり取りの中身を人へリレーしない。人は全セッションを直接見ているので、相手の完了報告や
+根拠をこちらで要約し直しても情報は増えず、時間とコンテキストだけが減る。人に言うのは
+自セッション目線の事実 (何を頼んだ・何が返り・その結果こちらが何をしたか) だけ。
+
+## 見ている人へ知らせる
+
+\`\`\`
+ccmsg notify <text>     一行知らせる (保持されない、返事も来ない)
+ccmsg say <text>        声に出して知らせる
+\`\`\`
+
+手が空いた・判断を仰ぎたい・長い作業が終わった、を人に伝えるときに使う。
+セッション同士のやり取りには使わない。
+
+## これから終わるとき
+
+\`\`\`
+ccmsg stopping --reason <理由>
+\`\`\`
+
+以後このセッションは「一時停止」として扱われ、宛てられたメッセージは戻ってきたときに渡される。
+セッション終了時には自動で伝わるので、途中で自分から言う必要はない。
+`;