@celilo/core 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/core",
-  "version": "0.1.0",
+  "version": "0.2.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

@@ -402,6 +402,94 @@ export const COMMANDS: CommandDef[] = [
       },
     ],
   },
+  {
+    name: 'registry',
+    description: 'Administer the module registry (append-safe publish-token management)',
+    subcommands: [
+      {
+        name: 'token',
+        description: 'Manage the celilo-registry publish_tokens list (append-safe)',
+        subcommands: [
+          {
+            name: 'add',
+            description: 'Append a publish token without clobbering existing holders',
+            args: [{ name: 'token', description: 'Publish token to append' }],
+          },
+          {
+            name: 'rm',
+            description: 'Remove one publish token, leaving the rest intact',
+            args: [{ name: 'token', description: 'Publish token to remove' }],
+          },
+        ],
+      },
+      {
+        name: 'owner',
+        description: 'Administer the module-owner table (who may publish which module names)',
+        subcommands: [
+          {
+            name: 'list',
+            description: 'List the whole module-owner table',
+            flags: [{ name: 'registry', description: 'Registry URL', takesValue: true }],
+          },
+          {
+            name: 'show',
+            description: 'Show the owner of one module name',
+            args: [{ name: 'module', description: 'Module name to look up' }],
+            flags: [{ name: 'registry', description: 'Registry URL', takesValue: true }],
+          },
+          {
+            name: 'set',
+            description: 'Reassign a module name to a new owner (admin)',
+            args: [
+              { name: 'module', description: 'Module name to reassign' },
+              { name: 'owner-sub', description: 'New owner subject (idp sub)' },
+            ],
+            flags: [{ name: 'registry', description: 'Registry URL', takesValue: true }],
+          },
+        ],
+      },
+    ],
+  },
+  {
+    name: 'token',
+    description: 'Manage contributor identity tokens (idp-issued per-user publish tokens)',
+    subcommands: [
+      {
+        name: 'obtain',
+        description: 'Mint (or return) a per-user API token bound to an idp identity',
+        args: [{ name: 'username', description: 'The idp user the token is bound to' }],
+        flags: [
+          { name: 'user', description: 'The idp user the token is bound to', takesValue: true },
+          {
+            name: 'identifier',
+            description: 'Token identifier (default: celilo-publish-<user>)',
+            takesValue: true,
+          },
+          {
+            name: 'description',
+            description: 'Human-readable description shown in the idp',
+            takesValue: true,
+          },
+        ],
+      },
+      {
+        name: 'list',
+        description: "List a user's API tokens (metadata only, never the secret)",
+        args: [{ name: 'username', description: 'The idp user whose tokens to list' }],
+        flags: [
+          { name: 'user', description: 'The idp user whose tokens to list', takesValue: true },
+        ],
+      },
+      {
+        name: 'revoke',
+        description: 'Revoke a token by identifier; the next publish with it is denied',
+        args: [{ name: 'identifier', description: 'Token identifier to revoke' }],
+        flags: [
+          { name: 'identifier', description: 'Token identifier to revoke', takesValue: true },
+        ],
+      },
+    ],
+  },
   {
     name: 'module',
     description: 'Manage modules (import, generate, configure)',
@@ -493,7 +581,7 @@ export const COMMANDS: CommandDef[] = [
       {
         name: 'upgrade',
         description:
-          'Upgrade a module to its latest registry version: update → backup (posture-gated) → deploy → verify. No id = the CD poll: upgrade every auto_upgrade module with a newer version.',
+          'Upgrade a module to its latest registry version: update → backup (posture-gated) → deploy → verify. No id (or --poll) = the CD poll: upgrade every auto_upgrade module with a newer version.',
         args: [
           {
             name: 'id',
@@ -502,6 +590,12 @@ export const COMMANDS: CommandDef[] = [
           },
         ],
         flags: [
+          {
+            name: 'poll',
+            description:
+              'Run the CD poll regardless of positional args — required when wired as an event-bus handler (the dispatcher appends the event id)',
+            takesValue: false,
+          },
           {
             name: 'registry',
             description: 'Registry URL (defaults to configured registry)',
@@ -627,6 +721,44 @@ export const COMMANDS: CommandDef[] = [
         description: 'Show detailed module status',
         args: [{ name: 'id', description: 'Module ID', completion: 'module_ids' }],
       },
+      {
+        name: 'where',
+        description: 'Show which host(s) serve a module (host discovery)',
+        args: [{ name: 'id', description: 'Module ID', completion: 'module_ids' }],
+        flags: [
+          {
+            name: 'json',
+            description: 'Output host discovery as stable JSON',
+            takesValue: false,
+          },
+        ],
+      },
+      {
+        name: 'operations',
+        description: 'Show or release in-flight module operations (the backup/restore lock)',
+        args: [{ name: 'action', description: 'list (default) or clear' }],
+        flags: [
+          {
+            name: 'all',
+            description: 'With clear: also release operations that still look alive',
+            takesValue: false,
+          },
+        ],
+        subcommands: [
+          { name: 'list', description: 'Show operations currently holding the lock' },
+          {
+            name: 'clear',
+            description: 'Release abandoned operations so backups can run again',
+            flags: [
+              {
+                name: 'all',
+                description: 'Also release operations that still look alive',
+                takesValue: false,
+              },
+            ],
+          },
+        ],
+      },
       {
         name: 'logs',
         description: 'Show deploy logs for a module',
@@ -1303,6 +1435,176 @@ export const COMMANDS: CommandDef[] = [
       },
     ],
   },
+  {
+    name: 'person',
+    description: 'Manage people celilo can reach',
+    subcommands: [
+      { name: 'list', description: 'List configured people' },
+      {
+        name: 'add',
+        description: 'Add a person',
+        args: [{ name: 'name', description: 'Human-readable name, kebab-case' }],
+        flags: [
+          {
+            name: 'timezone',
+            description: 'IANA timezone, e.g. America/Los_Angeles',
+            takesValue: true,
+          },
+          { name: 'quiet-hours', description: 'Local window, e.g. 22:00-07:00', takesValue: true },
+        ],
+      },
+      {
+        name: 'remove',
+        description: 'Remove a person and their routes',
+        args: [{ name: 'name', description: 'Person name' }],
+      },
+    ],
+  },
+  {
+    name: 'route',
+    description: 'Manage how each person is reached (transport + address)',
+    subcommands: [
+      { name: 'list', description: 'List configured routes' },
+      {
+        name: 'add',
+        description: 'Reach a person over a transport',
+        args: [
+          { name: 'person', description: 'Person name' },
+          { name: 'transport', description: 'Module providing the notification capability' },
+        ],
+        flags: [
+          { name: 'address', description: 'Transport-specific address', takesValue: true },
+          { name: 'severity-floor', description: 'warning | critical', takesValue: true },
+          {
+            name: 'can-ack',
+            description: 'Replies can arrive over this transport',
+            takesValue: false,
+          },
+        ],
+      },
+      {
+        name: 'remove',
+        description: 'Remove a route',
+        args: [
+          { name: 'person', description: 'Person name' },
+          { name: 'transport', description: 'Transport module id' },
+        ],
+      },
+    ],
+  },
+  {
+    name: 'escalation-policy',
+    description: 'Manage who gets paged, and in what order',
+    subcommands: [
+      { name: 'list', description: 'List policies and their steps' },
+      {
+        name: 'add',
+        description: 'Create a named policy',
+        args: [{ name: 'name', description: 'Policy name' }],
+      },
+      {
+        name: 'step',
+        description: 'Append a step to a policy',
+        args: [
+          { name: 'policy', description: 'Policy name' },
+          { name: 'person', description: 'Person name' },
+          { name: 'transport', description: 'Transport module id' },
+        ],
+        flags: [
+          {
+            name: 'after',
+            description: 'Delay in minutes from escalation start',
+            takesValue: true,
+          },
+        ],
+      },
+      {
+        name: 'assign',
+        description: 'Use a policy for a monitor',
+        args: [
+          { name: 'policy', description: 'Policy name' },
+          { name: 'monitor', description: 'Monitor target' },
+        ],
+      },
+      {
+        name: 'remove',
+        description: 'Remove a policy',
+        args: [{ name: 'name', description: 'Policy name' }],
+      },
+    ],
+  },
+  {
+    name: 'monitor',
+    description: 'Manage what celilo watches (health checks on a schedule)',
+    subcommands: [
+      { name: 'list', description: 'List configured monitors' },
+      {
+        name: 'add',
+        description: 'Watch a module or built-in check',
+        args: [{ name: 'target', description: 'Module id or built-in check name' }],
+        flags: [{ name: 'interval', description: 'Cadence, e.g. 15m, 1h, 1d', takesValue: true }],
+      },
+      {
+        name: 'run',
+        description: 'Run a monitor now',
+        args: [{ name: 'target', description: 'Module id or built-in check name' }],
+      },
+      {
+        name: 'enable',
+        description: 'Enable a monitor',
+        args: [{ name: 'target', description: 'Module id or built-in check name' }],
+      },
+      {
+        name: 'disable',
+        description: 'Disable a monitor and resolve its alerts',
+        args: [{ name: 'target', description: 'Module id or built-in check name' }],
+      },
+    ],
+  },
+  {
+    name: 'alerts',
+    description: 'View and manage alerts raised by monitors',
+    subcommands: [
+      {
+        name: 'list',
+        description: 'List current alerts',
+        flags: [{ name: 'json', description: 'Machine-readable output', takesValue: false }],
+      },
+      {
+        name: 'ack',
+        description: 'Acknowledge an alert — stops escalation, does not resolve it',
+        args: [{ name: 'key', description: 'Alert key from `celilo alerts list`' }],
+        flags: [{ name: 'as', description: 'Person acknowledging', takesValue: true }],
+      },
+      {
+        name: 'silence',
+        description: 'Silence an alert for a while — deliberate and expiring',
+        args: [{ name: 'key', description: 'Alert key' }],
+        flags: [{ name: 'for', description: 'Duration, e.g. 2h, 30m, 1d', takesValue: true }],
+      },
+      {
+        name: 'resolve',
+        description: 'Manually resolve an alert (it re-fires if the check still fails)',
+        args: [{ name: 'key', description: 'Alert key' }],
+      },
+      {
+        name: 'sweep',
+        description: 'Run one alerting pass (invoked by the dispatcher on timer.tick.5m)',
+      },
+      {
+        name: 'poll',
+        description: 'Read replies off every bidirectional transport once',
+        flags: [
+          {
+            name: 'ask-after',
+            description:
+              'Seconds a deploy question must go unanswered before it is sent to a phone (default 90). A responder attached to the deploy answers in seconds; this grace stops the two racing.',
+            takesValue: true,
+          },
+        ],
+      },
+    ],
+  },
   {
     name: 'storage',
     description: 'Manage backup storage destinations',
@@ -1393,6 +1695,11 @@ export const COMMANDS: CommandDef[] = [
           },
         ],
       },
+      {
+        name: 'sweep',
+        description:
+          'Back up every module whose declared schedule is due (run by the event bus on timer.tick.1h)',
+      },
       {
         name: 'list',
         description: 'List available backups',

package/src/protocol.ts

@@ -3,7 +3,7 @@
  *
  * A versioned, Zod-validated tagged union carried as NDJSON. This is the
  * transport-neutral message layer for driving the CLI over the wire — see
- * `v2/API_COMMUNICATION.md`. Slice 1 covers non-interactive command execution
+ * `openspec/changes/replace-ssh-cli-api/proposal.md`. Slice 1 covers non-interactive command execution
  * + streamed output; `interview` / `answer` / `cancel` arrive in Slice 3.
  *
  * The command crosses the wire as a *structured, validated* `argv` array —