@celilo/core 0.12.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/core",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Lightweight shared core for Celilo CLI tools — command registry, NDJSON API protocol, and remote SSH client. No Ink/React/drizzle/aws-sdk transitive deps, so an MCP server can reach the transport without installing the full CLI.",
   "type": "module",
   "main": "./src/index.ts",

package/src/command-registry.ts

@@ -98,7 +98,7 @@ export const COMMANDS: CommandDef[] = [
     subcommands: [
       {
         name: 'grant',
-        description: 'Grant or replace API access for a principal',
+        description: 'Grant, amend, or replace API access for a principal',
         args: [{ name: 'principal', description: 'Principal name (kebab-case)' }],
         flags: [
           {
@@ -109,9 +109,24 @@ export const COMMANDS: CommandDef[] = [
           },
           {
             name: 'can',
-            description: 'Comma-separated grants (e.g. module:deploy,service:*)',
+            description: 'Comma-separated grants, REPLACING the set (e.g. module:deploy,service:*)',
             takesValue: true,
           },
+          {
+            name: 'add',
+            description: 'Comma-separated grants to add to the existing set',
+            takesValue: true,
+          },
+          {
+            name: 'remove',
+            description: 'Comma-separated grants to remove from the existing set',
+            takesValue: true,
+          },
+          {
+            name: 'force',
+            description: 'Allow a --can replacement that drops existing grants',
+            takesValue: false,
+          },
         ],
       },
       { name: 'list', description: 'List API principals and their grants' },
@@ -1315,6 +1330,25 @@ export const COMMANDS: CommandDef[] = [
         ],
         flags: [{ name: 'clear', description: 'Clear the earmark', takesValue: false }],
       },
+      {
+        name: 'reclassify',
+        description:
+          "Re-classify a machine's stored interface zone labels against the current zone model",
+        args: [
+          {
+            name: 'hostname',
+            description: 'Machine hostname or IP',
+            completion: 'machine_hostnames',
+          },
+        ],
+        flags: [
+          {
+            name: 'apply',
+            description: 'Write the new labels (default: dry run)',
+            takesValue: false,
+          },
+        ],
+      },
     ],
   },
   {
@@ -1469,6 +1503,25 @@ export const COMMANDS: CommandDef[] = [
           },
         ],
       },
+      {
+        name: 'reboot',
+        description:
+          'Reboot the management server. Refuses while a module operation is in flight, names it, and records the boot id so the return can be verified',
+        flags: [
+          {
+            name: 'allow-reboot',
+            description:
+              'Approve the reboot without an interview question (the downtime takes the dispatcher, MCP server and remote API with it)',
+            takesValue: false,
+          },
+          {
+            name: 'verify',
+            description:
+              'Confirm a requested reboot came back: the boot id changed, the dispatcher is live and the CLI answers. Reports which is missing when it has not',
+            takesValue: false,
+          },
+        ],
+      },
       {
         name: 'migrate',
         description: 'Apply pending database migrations (idempotent; safe to re-run)',
@@ -1751,6 +1804,45 @@ export const COMMANDS: CommandDef[] = [
         description:
           'Per-subscriber delivery history (success rate, last delivery, recent failures)',
       },
+      {
+        name: 'install-daemon',
+        description: 'Write a supervisor unit (systemd/launchd) for the build-bus webhook receiver',
+        flags: [
+          {
+            name: 'system',
+            description: 'System-scope unit (/etc/systemd/system or LaunchDaemons)',
+            takesValue: false,
+          },
+          {
+            name: 'secret',
+            description:
+              'Shared HMAC secret incoming webhooks sign with (or CELILO_BUS_SECRET env)',
+            takesValue: true,
+          },
+          { name: 'port', description: 'TCP port to listen on (default 8123)', takesValue: true },
+          {
+            name: 'dispatch',
+            description:
+              'Render a combined unit (receiver + hook dispatcher) for boxes with no events daemon',
+            takesValue: false,
+          },
+          {
+            name: 'print',
+            description: 'Render the unit to stdout without writing (Ansible seam)',
+            takesValue: false,
+          },
+          {
+            name: 'celilo-path',
+            description: 'Explicit celilo binary path for ExecStart',
+            takesValue: true,
+          },
+        ],
+      },
+      {
+        name: 'uninstall-daemon',
+        description: 'Remove the build-bus receiver supervisor unit',
+        flags: [{ name: 'system', description: 'System-scope unit', takesValue: false }],
+      },
     ],
   },
   {

package/src/protocol.ts

@@ -100,6 +100,14 @@ export type ProgressMessage = z.infer<typeof ProgressMessageSchema>;
 export const LogMessageSchema = z.object({
   type: z.literal('log'),
   message: z.string(),
+  /**
+   * Which child stream the line came from. The server merges nothing —
+   * each stream is pumped separately — but the message schema is the only
+   * place the distinction can survive the trip, so it is recorded here
+   * (celilo#1362). Optional so an older client parses a newer server
+   * unchanged; unmarked lines are stdout.
+   */
+  stream: z.enum(['stdout', 'stderr']).optional(),
 });
 export type LogMessage = z.infer<typeof LogMessageSchema>;
 

package/src/read-only-classifier.test.ts

@@ -99,10 +99,35 @@ describe('readOnlyGrants', () => {
   });
 
   test('a mixed-verb op is classified as a write', () => {
-    // `module config` covers get AND set. Its token is `config`, which is not a
-    // read verb, so the whole op is a write. Collapsing it would hand a
-    // read-only principal the ability to set configuration.
+    // `module config` covers get AND set. One mutating leaf disqualifies the
+    // whole op, because a grant cannot be finer than the op. Collapsing it would
+    // hand a read-only principal the ability to set configuration.
     expect(isReadOnlyPath(['module', 'config'])).toBe(false);
     expect(readOnlyGrants(COMMANDS)).not.toContain('module:config');
   });
 });
+
+describe('op-level classification (celilo#1404)', () => {
+  test('a sole-leaf read op nested 3 deep is a read, not a write', () => {
+    // `proxmox node list` is `proxmox:node`, whose only leaf is a read. Keying
+    // on the middle segment (`node`) called it a write, so the read-only
+    // principal was not granted it and the read tool that routes RO could not
+    // run — a silent exit 126.
+    expect(isReadOnlyPath(['proxmox', 'node', 'list'])).toBe(true);
+    expect(readOnlyGrants(COMMANDS)).toContain('proxmox:node');
+  });
+
+  test('one mutating leaf disqualifies its whole op', () => {
+    // `proxmox vm` covers list AND resize. The grant cannot be finer than the
+    // op, so the read `vm list` rides the RW key rather than widening RO.
+    expect(isReadOnlyPath(['proxmox', 'vm', 'list'])).toBe(false);
+    expect(readOnlyGrants(COMMANDS)).not.toContain('proxmox:vm');
+  });
+
+  test('module journal and module where are reachable', () => {
+    // The two the live server was missing.
+    const granted = new Set(readOnlyGrants(COMMANDS));
+    expect(granted).toContain('module:journal');
+    expect(granted).toContain('module:where');
+  });
+});

package/src/read-only-classifier.ts

@@ -14,7 +14,7 @@
  * automatically and a new write verb is not.
  */
 
-import type { ArgDef, CommandDef, FlagDef } from './command-registry';
+import { type ArgDef, COMMANDS, type CommandDef, type FlagDef } from './command-registry';
 
 /** A runnable leaf command flattened from the registry tree. */
 export interface Leaf {
@@ -26,18 +26,44 @@ export interface Leaf {
 }
 
 /**
- * Read-only verbs. The server's authz is 2-level (`command:subcommand`), so the
- * read/write split is too: a leaf is read-only iff its *op token* — the
- * subcommand (or, for a top-level leaf, the command) — is a read verb. This
- * guarantees a read tool's op is exactly what the RO principal is granted, and
- * never routes a mutating op onto the RO key. A mixed op like `module:config`
- * (get + set) has a non-read token (`config`) → classified write → RW.
+ * Read-only LEAF verbs — the last path segment of a runnable command.
+ *
+ * Classification is two steps, because the server's authz is 2-level
+ * (`command:subcommand`) while the registry is up to 3 deep. A LEAF is a read
+ * iff its own verb is here; an OP is a read iff EVERY leaf under it is. That
+ * second step is what keeps a mixed op like `module config` (get + set) a write,
+ * and it is what stopped `proxmox node list` from being one: keying on the
+ * middle segment (`node`) classified a sole-leaf read op as a write, so the
+ * read-only principal could not run it (celilo#1404).
+ *
+ * DELIBERATELY NOT read verbs, though they look like ones:
+ *   health, verify — run hooks ON the target host; reads in intent, side effects
+ *                    in mechanism.
+ *   doctor, poll   — poll writes alert state; doctor can repair.
+ *   search         — reaches the registry over the network.
+ *   authorized-keys — renders every principal's full public key and forced-command
+ *                    line. `api list` (granted) shows key type and comment only.
  */
 export const READ_VERBS: ReadonlySet<string> = new Set([
   'list',
   'status',
   'where',
   'get',
+  'show',
+  'show-config',
+  'show-zone',
+  'show-daemon',
+  'info',
+  'logs',
+  'tail',
+  'registrations',
+  'list-allocations',
+  'list-reservations',
+  'list-exclusions',
+  'list-subscribers',
+  'list-pending',
+  'list-failed',
+  'list-unanswered',
   // Reads a deployed module's daemon journal. Read-only by construction —
   // the only remote command it can emit is `journalctl` (services/module-journal.ts).
   'journal',
@@ -50,14 +76,14 @@ export function opOf(path: string[]): string {
   return path.length >= 2 ? `${path[0]}:${path[1]}` : path[0];
 }
 
-/** Token that decides read vs write: the subcommand, or the bare command. */
-function opToken(path: string[]): string {
-  return path.length >= 2 ? path[1] : path[0];
+/** The leaf's own verb — the token that decides read vs write. */
+function leafVerb(path: string[]): string {
+  return path[path.length - 1];
 }
 
-/** Is this leaf read-only (→ RO principal)? See `READ_VERBS`. */
-export function isReadOnlyPath(path: string[]): boolean {
-  return READ_VERBS.has(opToken(path));
+/** Is this single leaf a read? (Not the same question as its OP — see below.) */
+export function isReadOnlyLeaf(path: string[]): boolean {
+  return READ_VERBS.has(leafVerb(path));
 }
 
 /** Flatten the registry tree into its runnable leaves (nodes with no subcommands). */
@@ -82,15 +108,44 @@ export function flattenLeaves(commands: CommandDef[], prefix: string[] = []): Le
 /**
  * Every authz op a read-only principal needs, derived from a command registry.
  *
+ * An op is granted iff EVERY leaf it can run is a read. One mutating leaf under
+ * an op disqualifies the whole op, because the grant cannot be finer than the op.
+ *
  * Sorted and de-duplicated so the result is stable enough to compare in a test
  * and to print in a grant line.
  */
 export function readOnlyGrants(commands: CommandDef[]): string[] {
-  return [
-    ...new Set(
-      flattenLeaves(commands)
-        .filter((l) => isReadOnlyPath(l.path))
-        .map((l) => opOf(l.path)),
-    ),
-  ].sort();
+  return [...readOnlyOps(commands)].sort();
+}
+
+function readOnlyOps(commands: CommandDef[]): Set<string> {
+  const leavesByOp = new Map<string, string[][]>();
+  for (const leaf of flattenLeaves(commands)) {
+    const op = opOf(leaf.path);
+    const group = leavesByOp.get(op);
+    if (group) group.push(leaf.path);
+    else leavesByOp.set(op, [leaf.path]);
+  }
+  const ops = new Set<string>();
+  for (const [op, paths] of leavesByOp) {
+    if (paths.every(isReadOnlyLeaf)) ops.add(op);
+  }
+  return ops;
+}
+
+/** Every authz op the registry can run, read and write alike. Sorted, de-duped. */
+export function allOps(commands: CommandDef[]): string[] {
+  return [...new Set(flattenLeaves(commands).map((l) => opOf(l.path)))].sort();
+}
+
+let liveReadOnlyOps: Set<string> | null = null;
+
+/**
+ * Is this path routed to the read-only principal? Answered at OP level against
+ * the live registry, so a leaf's routing and the RO principal's grants can never
+ * disagree — a read tool routes RO iff RO is granted its op.
+ */
+export function isReadOnlyPath(path: string[]): boolean {
+  liveReadOnlyOps ??= readOnlyOps(COMMANDS);
+  return liveReadOnlyOps.has(opOf(path));
 }

package/src/remote-client.test.ts

@@ -177,3 +177,40 @@ describe('stdin carrying JSON-RPC survives a raised interview', () => {
     expect(out).toContain(`SURVIVED:${rpc}`);
   }, 30_000);
 });
+
+describe("a denial's text survives to a capturing caller (celilo#1404)", () => {
+  test('the outcome carries the server error, which never reaches `out`', async () => {
+    // The server DOES say why: `permission denied: "<principal>" is not granted
+    // "<op>"`. But it says it as a protocol `error` message, not as command
+    // output, so a caller that captures `out` (the MCP server) saw exit 126 with
+    // an empty body and read it as the command failing on the target host.
+    const denial = 'permission denied: "celilo-mcp-ro" is not granted "module:journal"';
+    const transport = fakeTransport([
+      JSON.stringify({ type: 'error', error: denial }),
+      JSON.stringify({ type: 'result', success: false, exitCode: 126 }),
+    ]);
+    const captured: string[] = [];
+
+    const outcome = await runRemoteClient('host', ['module', 'journal', 'caddy'], {
+      openTransport: () => transport,
+      out: { write: (s: string) => void captured.push(s), isTTY: false },
+      onBlocked: 'return',
+    });
+
+    expect(outcome).toEqual({ status: 'result', exitCode: 126, error: denial });
+    // Still not command output — a caller must not mistake it for one.
+    expect(captured.join('')).toBe('');
+  });
+
+  test('a clean run carries no error', async () => {
+    const transport = fakeTransport([
+      JSON.stringify({ type: 'result', success: true, exitCode: 0 }),
+    ]);
+    const outcome = await runRemoteClient('host', ['module', 'list'], {
+      openTransport: () => transport,
+      out: { write() {}, isTTY: false },
+      onBlocked: 'return',
+    });
+    expect(outcome).toEqual({ status: 'result', exitCode: 0 });
+  });
+});

package/src/remote-client.ts

@@ -190,16 +190,19 @@ function applyMessage(
       // Nest under the active step so the footer isn't corrupted; otherwise print.
       if (display.hasPending) {
         display.subEvent(msg.message);
+      } else if (msg.stream === 'stderr') {
+        // The server names each log line's origin stream; keep stderr on
+        // stderr locally so diagnostics never masquerade as command output
+        // (celilo#1362). Unmarked lines are stdout from an older server.
+        process.stderr.write(`${msg.message}\n`);
       } else {
         out.write(`${msg.message}\n`);
       }
       return null;
     case 'error':
-      process.stderr.write(`${msg.error}\n`);
-      return null;
     case 'interview':
     case 'blocked':
-      // Handled by the caller (needs the transport to reply) — never reached here.
+      // Handled by consumeStream (needs to retain the text / reply) — never here.
       return null;
     case 'result':
       return msg.exitCode;
@@ -212,7 +215,14 @@ function applyMessage(
  * is still alive under `sessionId`.
  */
 export type RemoteOutcome =
-  | { status: 'result'; exitCode: number }
+  /**
+   * `error` is the server's in-band `error` text, retained so a CAPTURING
+   * caller can report it. It is written to stderr as well, for a terminal one.
+   * Without it an authz denial reached the MCP as exit 126 with empty output —
+   * a silent denial the caller reads as the command failing on the host
+   * (celilo#1404).
+   */
+  | { status: 'result'; exitCode: number; error?: string }
   | { status: 'blocked'; sessionId: string; eventId: string; question: string; key?: string };
 
 /** Exit code a caller reports when a command parked rather than finishing. */
@@ -237,6 +247,7 @@ async function consumeStream(
 ): Promise<RemoteOutcome | null> {
   const { out, display, renderInterview } = opts;
   const decoder = new TextDecoder();
+  const errors: string[] = [];
   let buffer = '';
 
   for await (const chunk of transport.stdout) {
@@ -276,6 +287,12 @@ async function consumeStream(
         continue;
       }
 
+      if (msg.type === 'error') {
+        errors.push(msg.error);
+        process.stderr.write(`${msg.error}\n`);
+        continue;
+      }
+
       if (msg.type === 'blocked') {
         if (opts.onBlocked === 'wait') {
           out.write(
@@ -293,7 +310,9 @@ async function consumeStream(
       }
 
       const exit = applyMessage(msg, display, out);
-      if (exit !== null) return { status: 'result', exitCode: exit };
+      if (exit !== null) {
+        return { status: 'result', exitCode: exit, error: errors.join('\n') || undefined };
+      }
     }
   }
   return null;