@shardworks/nexus 0.1.270 → 0.1.272

package/README.md

@@ -119,6 +119,21 @@ Framework commands are defined in the CLI package itself (`src/commands/`). They
 | `nsg plugin remove <name>` | Remove a plugin |
 | `nsg plugin upgrade <name>` | Upgrade a plugin to a newer version *(stub)* |
 
+### Event Emission
+
+| Command | Description |
+|---|---|
+| `nsg signal <name> [--payload '<json>']` | Emit a custom event into the Clockworks events book with `emitter='operator'` |
+
+`nsg signal` is hand-written rather than auto-generated from the
+clockworks `signal` tool — the auto-builder cannot JSON-parse a
+record-shaped `--payload` flag, and the operator emitter default
+differs from the tool's `'anima'` default. The event name must be
+declared under `clockworks.events` in `guild.json`; reserved framework
+namespaces (`anima.`, `commission.`, `migration.`, `guild.`,
+`standing-order.`, `session.`) and writ-lifecycle patterns
+(`<type>.{ready,completed,stuck,failed}`) are rejected.
+
 #### `nsg init`
 
 Writes the minimum viable guild. Does not run `git init`, create the database, or instantiate animas — those are separate steps.
@@ -248,7 +263,6 @@ The following commands are planned but not yet implemented. No plugin currently
 | `nsg anima update` | — | *(Planned)* Update anima configuration |
 | `nsg anima remove` | — | *(Planned)* Retire an anima |
 | `nsg anima manifest` | — | *(Planned)* Preview the manifest for an anima |
-| `nsg signal` | — | *(Planned)* Signal a custom event |
 | `nsg event list` | — | *(Planned)* List recent events |
 | `nsg event show` | — | *(Planned)* Show event detail |
 | `nsg dispatch list` | — | *(Planned)* List recent dispatches |

package/dist/commands/clock.d.ts

@@ -0,0 +1,225 @@
+/**
+ * nsg clock — operator-facing Clockworks CLI.
+ *
+ * Three subcommands under `nsg clock` that compose on top of
+ * `ClockworksApi.processEvents` and a direct read of the
+ * `clockworks/events` book:
+ *
+ *   - `nsg clock list` — print pending events (or, with
+ *     `--include-processed`, every event), one event per two-line
+ *     block (or a single line when payload is null), in id-ascending
+ *     order. `--limit N` caps output at N entries.
+ *   - `nsg clock tick [id]` — process a single event. Without `id`,
+ *     the next pending event in id order; with `id`, exactly that
+ *     event after a CLI-side pre-check that it exists and is still
+ *     pending. Prints per-dispatch summary lines via the
+ *     `processEvents({ onDispatch })` observer.
+ *   - `nsg clock run` — loop `processEvents()` until the dispatcher
+ *     reports zero processed events for an iteration. No sleep, no
+ *     daemon — finite drain. Mid-sweep arrivals are picked up on the
+ *     next iteration.
+ *
+ * The CLI package deliberately does not depend on the clockworks or
+ * stacks plugin packages — apparatus interfaces are declared inline
+ * and resolved at runtime via `guild().apparatus<T>(name)`. This
+ * mirrors the discipline practiced by `signal` and `start`.
+ *
+ * Hand-written rather than auto-built because:
+ *   - `tick [id]` is an optional positional, which the auto-builder
+ *     cannot express.
+ *   - `--include-processed` and `--limit <N>` need locally-validated
+ *     parsing.
+ *   - Exit-code semantics are nontrivial: nonzero only when at least
+ *     one dispatch recorded `status: error`, plus the
+ *     missing-event-id and already-processed-event branches.
+ *
+ * See commission c-mody57g7 decisions D1–D20.
+ */
+import { Command } from 'commander';
+import { type ClockStatus } from '@shardworks/clockworks-apparatus';
+interface DispatchObservationLike {
+    eventId: string;
+    eventName: string;
+    handlerName: string;
+    /**
+     * Mirrors `DispatchObservation.status` from the clockworks
+     * apparatus. The `'skipped'` variant covers loop-guard
+     * suppression — the relay was not invoked, no SOF was emitted, and
+     * `error` carries the loop-guard reason. Skipped rows must not
+     * count toward operator error metrics or the CLI exit code.
+     */
+    status: 'success' | 'error' | 'skipped';
+    durationMs: number;
+    error: string | null;
+}
+interface EventDocLike {
+    id: string;
+    name: string;
+    payload: unknown;
+    emitter: string;
+    firedAt: string;
+    processed: boolean;
+}
+/**
+ * Render the payload preview for `list`. Returns null when the
+ * payload is exactly null (D19 — payload line omitted entirely);
+ * otherwise returns a truncated JSON string.
+ */
+export declare function renderPayloadPreview(payload: unknown): string | null;
+/**
+ * Format a single event for `nsg clock list`. Two lines when payload
+ * is non-null; single line otherwise.
+ */
+export declare function formatEventBlock(event: EventDocLike): string;
+/**
+ * Format a single dispatch observation for the per-dispatch summary
+ * line emitted by `tick` and `run`. Per D10:
+ *   `[<handlerName>] <status> <durationMs>ms`
+ * With `: <error>` appended on the same line when `status` is error.
+ *
+ * Loop-guard `'skipped'` rows render as
+ *   `[<handlerName>] skipped: <loop-guard reason>`
+ * — the same colon-then-message convention as the error arm so output
+ * stays parseable. Skipped lines do NOT include a duration (the
+ * dispatcher never invoked the relay; surfacing `0ms` would only
+ * mislead operators).
+ */
+export declare function formatDispatchLine(obs: DispatchObservationLike): string;
+export interface ListInput {
+    /** Include processed events in addition to pending ones. */
+    includeProcessed?: boolean;
+    /** Cap output at this many entries; no default — undefined prints all. */
+    limit?: number;
+}
+export interface ListOutput {
+    /** Lines to print (already formatted). */
+    lines: string[];
+    /** Number of events rendered (after the limit cap, after the filter). */
+    count: number;
+    /** Whether the queue (matching the filter) was empty. */
+    empty: boolean;
+}
+/**
+ * Read events for `nsg clock list` and render them.
+ *
+ * The book read uses `find` with a `where` filter when only pending
+ * events are wanted (the common case); otherwise `list` with no
+ * filter (the `--include-processed` path).
+ */
+export declare function runList(input: ListInput): Promise<ListOutput>;
+export interface TickInput {
+    /** Optional event id to process. When omitted, the next pending event. */
+    eventId?: string;
+}
+export interface TickOutput {
+    /** Lines to print (in order). */
+    lines: string[];
+    /** Whether at least one dispatch row recorded `status: error`. */
+    hadError: boolean;
+    /** Whether the targeted/queue lookup found nothing to do. */
+    empty: boolean;
+    /** Set when an explicit eventId was supplied but does not exist. */
+    notFound: boolean;
+    /** Set when an explicit eventId was supplied but is already processed. */
+    alreadyProcessed: boolean;
+    /**
+     * Warning lines to write to stderr before the main output. Currently
+     * carries the daemon-coexistence warning when `nsg clock start` is
+     * already running.
+     */
+    warnings: string[];
+}
+/**
+ * Process a single event via `processEvents({ eventId })` or
+ * `processEvents({ max: 1 })` and capture the per-dispatch summary
+ * lines via the observer.
+ *
+ * The `events.get(id)` pre-check happens here per D4: missing-id and
+ * already-processed cases never reach the dispatcher.
+ */
+export declare function runTick(input: TickInput): Promise<TickOutput>;
+export interface RunOutput {
+    /** Lines to print (in dispatch order, plus the final count). */
+    lines: string[];
+    /** Whether at least one dispatch row across every iteration was an error. */
+    hadError: boolean;
+    /** Total events processed across all iterations. */
+    totalProcessed: number;
+    /** Whether the very first iteration found an empty queue. */
+    empty: boolean;
+    /**
+     * Warning lines to write to stderr before the main output. Currently
+     * carries the daemon-coexistence warning when `nsg clock start` is
+     * already running.
+     */
+    warnings: string[];
+}
+/**
+ * Drain the queue. Loop `processEvents()` until it reports zero
+ * processed events for an iteration. No sleep, no daemon. Per-dispatch
+ * summary lines emit as they happen via the observer; the final
+ * `processed N events` line goes out at the end.
+ */
+export declare function runRun(): Promise<RunOutput>;
+export interface StartInput {
+    /** Polling interval in milliseconds. Forwarded to `clockStart`. */
+    interval?: number;
+    /**
+     * When `true`, run the inline foreground daemon body instead of
+     * spawning a detached child. The detached `clock start` re-execs
+     * itself with this flag.
+     */
+    foreground?: boolean;
+}
+export interface StartOutput {
+    /** Lines to print. */
+    lines: string[];
+}
+/**
+ * Handle `nsg clock start`. Without `--foreground`, calls
+ * `clockStart(home)`, which spawns a detached child and blocks until
+ * the daemon is verified running. With `--foreground`, calls
+ * `runForegroundDaemonFromGuild` — the inline daemon body that the
+ * detached spawn re-execs into. The function returns only when the
+ * daemon shuts down (under SIGTERM or SIGINT).
+ */
+export declare function runStart(input: StartInput): Promise<StartOutput>;
+export interface StopOutput {
+    /** Lines to print. */
+    lines: string[];
+}
+/**
+ * Handle `nsg clock stop`. Thin wrapper around `clockStop`.
+ *
+ * Per spec: missing-pidfile and stale-pidfile cases exit zero with a
+ * message — they are not errors. The success-path message comes from
+ * the core API result so the three branches (`'signaled'`,
+ * `'no-pidfile'`, `'stale'`) stay aligned across CLI / programmatic
+ * consumers.
+ */
+export declare function runStop(): Promise<StopOutput>;
+export interface StatusInput {
+    /** Emit JSON instead of multi-line plain text. */
+    json?: boolean;
+}
+export interface StatusOutput {
+    /** Lines to print. */
+    lines: string[];
+    /** The structured status, included unconditionally so tests can assert it. */
+    status: ClockStatus;
+}
+/**
+ * Handle `nsg clock status`. Defaults to multi-line plain text;
+ * `--json` emits the structured shape verbatim. The output mirrors
+ * the `clock-status` MCP tool's payload so the surfaces stay aligned.
+ */
+export declare function runStatus(input: StatusInput): StatusOutput;
+/**
+ * Build the `nsg clock` Commander Command — the parent group plus the
+ * three subcommands. Each subcommand's action wrapper translates the
+ * structured handler output to printed lines and `process.exit(N)` per
+ * commission decision D8.
+ */
+export declare function buildClockCommand(): Command;
+export {};
+//# sourceMappingURL=clock.d.ts.map

package/dist/commands/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../../src/commands/clock.ts"],"names":[],"mappings":"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"}