@ccmsg/cli 0.3.4 → 0.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/cli",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "The ccmsg daemon, CLI and agent plugins for one instance (= one config home)",
   "license": "MIT",
   "author": "kawaz",

package/src/cli.ts

@@ -34,11 +34,22 @@ const SESSION_ENV = HARNESSES.flatMap((harness) => [...HARNESS[harness].sessionE
 import { hookEvent, type StatedMeta, statedMeta } from "./greeting/index.ts";
 import {
   isRunning,
+  MERGE_RULES,
   resolveConfigHome,
   resolvePaths,
   resolvePathsFor,
   start,
 } from "./instance/index.ts";
+
+/** The merge rules as the help prints them: one line per field path, in the
+ * order the schema declares them, so the table a person reads is the table the
+ * merge runs on. */
+const MERGE_DOCS: readonly Doc[] = Object.entries(MERGE_RULES).map(([path, rule]) => [
+  path,
+  rule === "merge"
+    ? "instances[] 側にある field だけを defaults に重ねる"
+    : "instances[] 側にあれば丸ごと置換する (追加・和にはならない)",
+]);
 import {
   type Agent,
   AGENTS,
@@ -98,6 +109,10 @@ interface Command {
   readonly usage?: string;
   readonly options?: readonly Doc[];
   readonly env?: readonly Doc[];
+  /** Anything else this level has to state as a list of names, under a title of
+   * its own. Options and environment are the two every level shares; this is
+   * for what only one of them has. */
+  readonly notes?: readonly { readonly title: string; readonly docs: readonly Doc[] }[];
   readonly children?: readonly Command[];
   readonly run?: (args: readonly string[]) => Promise<unknown>;
   /** Whether running it with nothing after it is a command rather than a
@@ -148,6 +163,13 @@ const ROOT: Command = {
               `config home が動かすもの: ${HARNESSES.join(" | ")} (既定 ${DEFAULT_HARNESS})`,
             ],
           ],
+          notes: [
+            {
+              title:
+                "共通 config で instances[] の値が defaults に重なる規則 (掲載の無いパスは丸ごと置換):",
+              docs: MERGE_DOCS,
+            },
+          ],
           run: (args) => added(args),
         },
         {
@@ -488,6 +510,7 @@ function help(path: readonly Command[]): string {
     }
     lines.push("");
   }
+  for (const note of at.notes ?? []) section(lines, note.title, note.docs);
   section(lines, "このレベルのオプション:", at.options);
   section(lines, "グローバルオプション:", GLOBAL_OPTIONS);
   section(lines, "環境変数:", [...(at.env ?? []), ...GLOBAL_ENV]);

package/src/daemon/registry.ts

@@ -3,7 +3,9 @@ import { basename, isAbsolute, join, resolve } from "node:path";
 import type { Endpoint, InstanceId, InstancePingResult } from "@ccmsg/protocol";
 import { DEFAULT_HARNESS, type Harness, HARNESS, isHarness } from "../harness/index.ts";
 import {
+  type InstanceConfig,
   type InstanceEntry,
+  loadConfig,
   loadShared,
   saveShared,
   settingsFor,
@@ -61,6 +63,14 @@ export interface InstanceRow {
 /** 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 {
+  /** What this config home's instance is configured with, after the shared
+   * file's defaults and its own entry are merged (§8.2).
+   *
+   * Answered whether or not anything is running, and read from the file rather
+   * than asked of the instance: this is what a restart would apply, which is
+   * the question an operator who just edited the file has. It carries no
+   * secret — the gateway's token is named by the path it is kept at. */
+  readonly config: InstanceConfig;
   readonly version?: string;
   readonly network?: InstancePingResult["network"];
   /** The other instances this one names, each with where it is dialled: the id
@@ -155,7 +165,7 @@ export function list(env: Env): InstanceRow[] {
 /** 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 row = { ...rowFor(target), config: loadConfig(target.paths.configFile, target.dir) };
   const conn = await connect(target.paths.socket);
   if (conn === undefined) return row;
   try {

package/src/instance/config.ts

@@ -230,13 +230,68 @@ export function saveShared(file: string, shared: SharedConfig): void {
   writeFileSync(file, `${JSON.stringify({ defaults: shared.defaults, instances }, null, 2)}\n`);
 }
 
+/** How one field of the shared file combines an instance's entry with the
+ * defaults.
+ *
+ * `merge` takes the two field by field, so an instance states only what it
+ * differs in; `replace` takes the instance's value whole. */
+export type MergeRule = "merge" | "replace";
+
+/** The rule for every field path that holds an object or an array, which are
+ * the only ones where "combine" could mean more than one thing.
+ *
+ * Declared beside the parsers rather than derived from the values, because
+ * whether a list is a sequence or a set is a fact about what the field means
+ * and every list looks the same without it. A path not named here replaces:
+ * that is what a scalar can do, and it is what an array does until some field
+ * is a set and says so. */
+export const MERGE_RULES: Readonly<Record<string, MergeRule>> = {
+  // The same finished list goes to every instance (§7.1), so an instance that
+  // writes its own means to run with that one and no other.
+  peers: "replace",
+  entry: "merge",
+  "entry.source_ips": "replace",
+  "entry.trusted_proxies": "replace",
+  upstream: "merge",
+  "upstream.launcher": "merge",
+  "upstream.launcher.root_dirs": "replace",
+  "upstream.launcher.templates": "replace",
+  "upstream.launcher.clean_env": "replace",
+  "upstream.launcher.keep_env": "replace",
+};
+
+function ruleFor(path: string): MergeRule {
+  return MERGE_RULES[path] ?? "replace";
+}
+
+function plainObject(raw: unknown): raw is Record<string, unknown> {
+  return typeof raw === "object" && raw !== null && !Array.isArray(raw);
+}
+
+function merged(
+  base: Record<string, unknown>,
+  over: Record<string, unknown>,
+  at: string,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...base };
+  for (const [name, value] of Object.entries(over)) {
+    const path = at === "" ? name : `${at}.${name}`;
+    const under = out[name];
+    out[name] =
+      ruleFor(path) === "merge" && plainObject(under) && plainObject(value)
+        ? merged(under, value, path)
+        : value;
+  }
+  return out;
+}
+
 /** What one config home's instance is configured with: its own entry over the
- * shared defaults, key by key. A config home the file does not list still
- * resolves — `daemon run` on an unregistered directory is the defaults plus
- * the built-ins. */
+ * shared defaults, by the rule each field path declares. A config home the file
+ * does not list still resolves — `daemon run` on an unregistered directory is
+ * the defaults plus the built-ins. */
 export function settingsFor(shared: SharedConfig, dir: string): Record<string, unknown> {
   const entry = shared.instances.find((one) => one.dir === dir);
-  return { ...shared.defaults, ...entry?.settings };
+  return merged(shared.defaults, entry?.settings ?? {}, "");
 }
 
 /** One instance's settings, read at the shape the instance uses them. */