@ccmsg/cli 0.2.13 → 0.3.1

package/src/plugin/codex.ts

@@ -0,0 +1,332 @@
+/** The plugin ccmsg hands to Codex, as its files.
+ *
+ * Nothing here goes through Codex's own plugin system. A Codex plugin can
+ * carry skills but not hooks — `plugin_hooks` is a removed feature of
+ * codex-cli 0.153.4 — and hooks are the whole point: they are how a session
+ * says hello and goodbye. So what is laid down is what Codex reads out of its
+ * config home directly: `hooks.json` beside its settings, and one skill under
+ * `skills/`.
+ *
+ * That makes the install different in kind from Claude Code's. There is no
+ * agent command to run and nothing to register: the files are the install, and
+ * uninstall is taking back exactly the files that were put there — which is
+ * why `hooks.json` is merged rather than written over, and unmerged rather than
+ * deleted. */
+
+import { readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { HARNESS, HARNESSES } from "../harness/index.ts";
+import type { InstancePaths } from "../instance/index.ts";
+import {
+  type InstallReport,
+  place,
+  readReceipt,
+  type Receipt,
+  receiptFile,
+  rootFor,
+  type Run,
+  type StatusReport,
+  type UninstallReport,
+  writeReceipt,
+} from "./receipt.ts";
+import { SKILL } from "./skill.ts";
+
+/** How Codex's own CLI is run, for the one question this asks it. */
+export const runCodex: Run = async (args) => {
+  let spawned: Bun.Subprocess<"ignore", "pipe", "pipe">;
+  try {
+    spawned = Bun.spawn({ cmd: ["codex", ...args], stdout: "pipe", stderr: "pipe" });
+  } catch {
+    return { code: 127, stdout: "", stderr: "codex が PATH にありません" };
+  }
+  const [stdout, stderr] = await Promise.all([
+    new Response(spawned.stdout).text(),
+    new Response(spawned.stderr).text(),
+  ]);
+  return { code: await spawned.exited, stdout, stderr };
+};
+
+/** The two events a session's life is read from, and the file each hook is.
+ *
+ * `SessionStart` and `SessionEnd` are what Codex fires around a thread, and
+ * both hand the hook the thread's id and its rollout path on standard input
+ * (codex-cli 0.153.4) — which is what `ccmsg hello --hook` and
+ * `ccmsg stopping --hook` already read. The legacy `notify` command is not
+ * used: it reports a finished turn, which is not a session's life. */
+const EVENTS = [
+  ["SessionStart", "session-start", "hello"],
+  ["SessionEnd", "session-end", "stopping"],
+] as const;
+
+/** How long a greeting or a departure may take before Codex stops waiting on
+ * it. Both are one connection to a socket on this same host, and both give up
+ * on their own when there is no instance behind it. */
+const HOOK_TIMEOUT_S = 5;
+
+/** What Codex still asks of the person before the hooks fire.
+ *
+ * Both are Codex's own questions, asked in its interface: a hook runs once it
+ * has been reviewed there, and a directory Codex has not been told to trust
+ * does not load project-local hooks at all. Said rather than answered — what
+ * may run on somebody's machine is theirs to decide. */
+const TRUST =
+  "hooks の trust が要ります (codex の hooks 画面で ccmsg の 2 つを trust。作業ディレクトリの信頼確認にも一度答えておく)";
+
+export const HOOKS_FILE = "hooks.json";
+const SKILL_FILE = join("skills", "ccmsg", "SKILL.md");
+
+/** One hook, as a program of its own rather than as a command line.
+ *
+ * Codex states a hook as one `command` string, and whether it reaches a shell
+ * is not something a config file says. A script settles it: the path is what
+ * Codex runs, and everything that needs a shell — finding `ccmsg`, naming the
+ * config home — happens inside it where a shell is certain.
+ *
+ * The config home is named, and every other harness's is dropped. A session
+ * started against the default home has no variable saying so, and a Codex
+ * session started from inside a Claude Code session inherits that session's
+ * `CLAUDE_CONFIG_DIR` and session id — so a hook that only added its own would
+ * still greet the other instance, as the other session (§3.8, measured). What
+ * is dropped is named here rather than left to the shell: the hook has to
+ * speak for the session it fired for.
+ *
+ * `env` is spelled absolutely because `PATH` is what the hook is about to
+ * search and not something it can lean on before it has. `ccmsg` itself is
+ * reached through `PATH`:
+ * the binary belongs to whoever installed ccmsg, and a plugin carrying its own
+ * copy would be a second version of it to keep current. A session whose `PATH`
+ * has no `ccmsg` leaves without saying anything, because a person who has not
+ * installed ccmsg has not asked to hear about it at every session start. */
+function hookScript(configHome: string, command: string): string {
+  const dropped = HARNESSES.filter((harness) => harness !== "codex").flatMap((harness) => [
+    HARNESS[harness].homeEnv,
+    ...HARNESS[harness].sessionEnv,
+  ]);
+  return `#!/bin/sh
+command -v ccmsg >/dev/null 2>&1 || exit 0
+exec /usr/bin/env ${dropped.map((name) => `-u ${name}`).join(" ")} CODEX_HOME=${shellQuoted(configHome)} ccmsg ${command} --hook
+`;
+}
+
+/** One value as a POSIX shell reads it literally: single quotes, and the one
+ * escape those admit for a single quote of their own. A config home is a path
+ * a person chose, so it is quoted rather than assumed to hold nothing. */
+function shellQuoted(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+/** Every file the plugin is made of, by its path under the plugin's root. */
+export function codexPluginFiles(configHome: string): Map<string, string> {
+  return new Map(
+    EVENTS.map(([, file, command]) => [join("hooks", file), hookScript(configHome, command)]),
+  );
+}
+
+/** What ccmsg adds to the config home's `hooks.json`. */
+function hookEntries(root: string): Record<string, unknown[]> {
+  const entries: Record<string, unknown[]> = {};
+  for (const [event, file] of EVENTS) {
+    entries[event] = [
+      {
+        hooks: [
+          { type: "command", command: join(root, "hooks", file), timeoutSec: HOOK_TIMEOUT_S },
+        ],
+      },
+    ];
+  }
+  return entries;
+}
+
+/** Lay the files down, add the hooks to the config home's own file, and write
+ * down what was done.
+ *
+ * Repeating it is laying the same files down again and replacing the same
+ * hooks: what an earlier install of ccmsg put in `hooks.json` is taken out
+ * before ours goes in, so an install run twice leaves one of each rather than
+ * two. */
+export async function install(
+  paths: InstancePaths,
+  version: string,
+  run: Run = runCodex,
+): Promise<InstallReport> {
+  const root = rootFor(paths, "codex");
+  const files = codexPluginFiles(paths.configHome);
+  // Executable, because Codex runs the path rather than passing it to a shell.
+  await place(root, files, 0o755);
+  await place(paths.configHome, new Map([[SKILL_FILE, SKILL]]));
+
+  const hooksFile = join(paths.configHome, HOOKS_FILE);
+  const held = await readHooks(hooksFile);
+  await writeFile(hooksFile, `${JSON.stringify(withHooks(held, root), null, 2)}\n`);
+
+  const receipt: Receipt = {
+    agent: "codex",
+    version,
+    installed_at: new Date().toISOString(),
+    config_home: paths.configHome,
+    root,
+    files: [...files.keys()],
+    placed: [join(paths.configHome, SKILL_FILE), hooksFile],
+    commands: [],
+  };
+  await writeReceipt(paths, receipt);
+
+  // Codex will not run a command hook it has not been shown: the person has to
+  // trust it once, in the session picker's hooks view. Said rather than worked
+  // around — trust is Codex asking whether this program may run, and answering
+  // it on their behalf is not an install's business.
+  const enabled = await hooksEnabled(run);
+  return {
+    agent: "codex",
+    ok: true,
+    version,
+    config_home: paths.configHome,
+    root,
+    files: receipt.files,
+    placed: receipt.placed,
+    commands: [],
+    needs:
+      enabled === false
+        ? `codex の features.hooks が off です (codex features enable hooks で入れてから、${TRUST})`
+        : `codex 側で ${TRUST}`,
+  };
+}
+
+/** What the receipt says was done, beside what is actually there now. */
+export async function status(paths: InstancePaths, run: Run = runCodex): Promise<StatusReport> {
+  const receipt = await readReceipt(paths, "codex");
+  const enabled = await hooksEnabled(run);
+  const hooks = enabled === undefined ? {} : { hooks_enabled: enabled };
+  if (receipt === undefined) return { agent: "codex", ok: true, ...hooks };
+  const missing: string[] = [];
+  for (const path of receipt.files) {
+    if (!(await Bun.file(join(receipt.root, path)).exists())) missing.push(path);
+  }
+  for (const path of receipt.placed ?? []) {
+    if (!(await Bun.file(path).exists())) missing.push(path);
+  }
+  const declared = await readHooks(join(receipt.config_home, HOOKS_FILE));
+  return {
+    agent: "codex",
+    ok: true,
+    receipt: receiptFile(paths, "codex"),
+    installed_at: receipt.installed_at,
+    version: receipt.version,
+    config_home: receipt.config_home,
+    root: receipt.root,
+    files: {
+      expected: receipt.files.length + (receipt.placed?.length ?? 0),
+      present: receipt.files.length + (receipt.placed?.length ?? 0) - missing.length,
+      missing,
+    },
+    ...hooks,
+    ...(hooksOf(declared, receipt.root).length === EVENTS.length
+      ? {}
+      : {
+          needs: `${HOOKS_FILE} に ccmsg の hook がありません (plugin install codex で入れ直せます)`,
+        }),
+  };
+}
+
+/** Undo what the receipt says was done, and nothing else.
+ *
+ * `hooks.json` is the config home's own file and may hold hooks that are
+ * nobody's business but the person's, so what is taken out of it is the
+ * entries pointing at the scripts this receipt names — and the file goes only
+ * when nothing is left in it. */
+export async function uninstall(paths: InstancePaths): Promise<UninstallReport> {
+  const receipt = await readReceipt(paths, "codex");
+  if (receipt === undefined) return { agent: "codex", ok: true, removed: {} };
+  const file = receiptFile(paths, "codex");
+  const hooksFile = join(receipt.config_home, HOOKS_FILE);
+  const left = withoutHooks(await readHooks(hooksFile), receipt.root);
+  if (Object.keys(left).length === 0) await rm(hooksFile, { force: true });
+  else await writeFile(hooksFile, `${JSON.stringify({ hooks: left }, null, 2)}\n`);
+
+  const placed = (receipt.placed ?? []).filter((path) => path !== hooksFile);
+  for (const path of placed) await rm(path, { force: true });
+  // The skill's own directory, which held nothing else.
+  await rm(join(receipt.config_home, "skills", "ccmsg"), { recursive: true, force: true });
+  await rm(receipt.root, { recursive: true, force: true });
+  await rm(file, { force: true });
+  return {
+    agent: "codex",
+    ok: true,
+    receipt: file,
+    removed: { root: receipt.root, placed: [...placed, hooksFile] },
+  };
+}
+
+/** Whether Codex has hooks switched on at all, or nothing when it could not be
+ * asked. Its own answer rather than a reading of `config.toml`, because the
+ * effective state is the feature's stage and the config together. */
+async function hooksEnabled(run: Run): Promise<boolean | undefined> {
+  const ran = await run(["features", "list"]);
+  if (ran.code !== 0) return undefined;
+  for (const line of ran.stdout.split("\n")) {
+    const fields = line.trim().split(/\s+/);
+    if (fields[0] !== "hooks") continue;
+    return fields[fields.length - 1] === "true";
+  }
+  return undefined;
+}
+
+/** The `hooks` object of a config home's file, or nothing where there is no
+ * file or it says something else. A file that cannot be read is treated as
+ * holding nothing, which is what makes the merge below additive. */
+async function readHooks(file: string): Promise<Record<string, unknown[]>> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(await readFile(file, "utf8"));
+  } catch {
+    return {};
+  }
+  const hooks = (parsed as { hooks?: unknown } | null)?.hooks;
+  if (typeof hooks !== "object" || hooks === null) return {};
+  const held: Record<string, unknown[]> = {};
+  for (const [event, entries] of Object.entries(hooks as Record<string, unknown>)) {
+    if (Array.isArray(entries)) held[event] = entries;
+  }
+  return held;
+}
+
+function withHooks(held: Record<string, unknown[]>, root: string): { hooks: object } {
+  const ours = hookEntries(root);
+  const merged = withoutHooks(held, root);
+  for (const [event, entries] of Object.entries(ours)) {
+    merged[event] = [...(merged[event] ?? []), ...entries];
+  }
+  return { hooks: merged };
+}
+
+/** The file's hooks with every entry that runs one of ours taken out, and
+ * every event left empty by that taken out with it. */
+function withoutHooks(held: Record<string, unknown[]>, root: string): Record<string, unknown[]> {
+  const left: Record<string, unknown[]> = {};
+  for (const [event, entries] of Object.entries(held)) {
+    const kept = entries.filter((entry) => !runsOurs(entry, root));
+    if (kept.length > 0) left[event] = kept;
+  }
+  return left;
+}
+
+/** Whether one entry of a file's hooks runs a script of this install's. */
+function runsOurs(entry: unknown, root: string): boolean {
+  return hooksIn(entry).some((command) => command.startsWith(join(root, "hooks")));
+}
+
+/** Which of ccmsg's own hook scripts a file's hooks name. */
+function hooksOf(held: Record<string, unknown[]>, root: string): string[] {
+  return Object.values(held)
+    .flat()
+    .flatMap((entry) => hooksIn(entry))
+    .filter((command) => command.startsWith(join(root, "hooks")));
+}
+
+function hooksIn(entry: unknown): string[] {
+  const hooks = (entry as { hooks?: unknown } | null)?.hooks;
+  if (!Array.isArray(hooks)) return [];
+  return hooks
+    .map((hook) => (hook as { command?: unknown } | null)?.command)
+    .filter((command): command is string => typeof command === "string");
+}

package/src/plugin/index.ts

@@ -1,13 +1,15 @@
 export { claudePluginFiles, MARKETPLACE_NAME, PLUGIN_ID, PLUGIN_NAME } from "./claude.ts";
+export { codexPluginFiles, HOOKS_FILE, runCodex } from "./codex.ts";
+export { install, runClaude, status, uninstall } from "./install.ts";
 export {
   type Agent,
   AGENTS,
-  install,
+  type InstallReport,
   type Outcome,
   type Ran,
   type Receipt,
   type Run,
-  runClaude,
-  status,
-  uninstall,
-} from "./install.ts";
+  type StatusReport,
+  type UninstallReport,
+} from "./receipt.ts";
+export { DESCRIPTION, SKILL } from "./skill.ts";

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);
 }