@hasna/events 0.1.6 → 0.1.8

package/README.md

@@ -219,6 +219,16 @@ events events replay --type ticket.created
 events events replay --dry-run
 ```
 
+Machine-readable status:
+
+```bash
+events status --json
+```
+
+The status contract reports event, channel, delivery, file, and transport counts
+only. It does not include event payloads, webhook signing secrets, command
+environment values, or channel targets.
+
 Use `--json` for script-friendly output and `--dir <path>` for isolated data.
 
 ## App Integration Pattern

package/dist/cli/index.js

@@ -62,6 +62,13 @@ var HASNA_EVENTS_HOME_ENV = "HASNA_EVENTS_HOME";
 function getEventsDataDir(override) {
   return override || process.env[HASNA_EVENTS_DIR_ENV] || process.env[HASNA_EVENTS_HOME_ENV] || join(homedir(), ".hasna", "events");
 }
+function getActiveEventsDirEnv() {
+  if (process.env[HASNA_EVENTS_DIR_ENV])
+    return HASNA_EVENTS_DIR_ENV;
+  if (process.env[HASNA_EVENTS_HOME_ENV])
+    return HASNA_EVENTS_HOME_ENV;
+  return null;
+}
 
 class JsonEventsStore {
   dataDir;
@@ -174,6 +181,52 @@ class JsonEventsStore {
     });
   }
 }
+async function getEventsStatus(dataDir) {
+  const store = new JsonEventsStore(dataDir);
+  await store.init();
+  const [channels, events, deliveries] = await Promise.all([
+    store.listChannels(),
+    store.listEvents(),
+    store.listDeliveries()
+  ]);
+  const transports = channels.reduce((counts, channel) => {
+    counts[channel.transport] = (counts[channel.transport] ?? 0) + 1;
+    return counts;
+  }, {});
+  return {
+    service: "events",
+    schemaVersion: "1.0",
+    dataDir: store.dataDir,
+    env: {
+      primary: HASNA_EVENTS_DIR_ENV,
+      fallback: HASNA_EVENTS_HOME_ENV,
+      active: getActiveEventsDirEnv()
+    },
+    files: {
+      channels: statusFile(store.dataDir, "channels.json", channels.length),
+      events: statusFile(store.dataDir, "events.json", events.length),
+      deliveries: statusFile(store.dataDir, "deliveries.json", deliveries.length)
+    },
+    counts: {
+      channels: channels.length,
+      enabledChannels: channels.filter((channel) => channel.enabled).length,
+      disabledChannels: channels.filter((channel) => !channel.enabled).length,
+      events: events.length,
+      deliveries: deliveries.length
+    },
+    transports,
+    safety: {
+      includesEventPayloads: false,
+      includesWebhookSecrets: false,
+      listOutputsRedactSecrets: true,
+      statusOutputIsMetadataOnly: true
+    }
+  };
+}
+function statusFile(dataDir, fileName, records) {
+  const path = join(dataDir, fileName);
+  return { path, exists: existsSync(path), records };
+}
 
 // src/transports.ts
 import { randomUUID } from "crypto";
@@ -564,10 +617,19 @@ function parseGlobalArgs(argv) {
   return { json, dir, rest };
 }
 function takeOption(args, name) {
+  const equalsPrefix = `${name}=`;
+  const equalsIndex = args.findIndex((arg) => arg.startsWith(equalsPrefix));
+  if (equalsIndex !== -1) {
+    const value2 = args[equalsIndex]?.slice(equalsPrefix.length);
+    args.splice(equalsIndex, 1);
+    return value2;
+  }
   const index = args.indexOf(name);
   if (index === -1)
     return;
   const value = args[index + 1];
+  if (value === undefined)
+    throw new Error(`${name} requires a value`);
   args.splice(index, 2);
   return value;
 }
@@ -580,7 +642,7 @@ function takeFlag(args, name) {
 }
 function takeMany(args, name) {
   const values = [];
-  while (args.includes(name)) {
+  while (args.includes(name) || args.some((arg) => arg.startsWith(`${name}=`))) {
     const value = takeOption(args, name);
     if (value !== undefined)
       values.push(value);
@@ -643,6 +705,7 @@ Usage:
   ${name} [--dir <path>] [--json] webhooks list
   ${name} [--dir <path>] [--json] webhooks remove <id>
   ${name} [--dir <path>] [--json] webhooks test <id>
+  ${name} [--dir <path>] [--json] status
   ${name} [--dir <path>] [--json] events emit <type>${options.source ? "" : " --source <source>"} [options]
   ${name} [--dir <path>] [--json] events list [--limit <n>]
   ${name} [--dir <path>] [--json] events replay [--id <event-id>] [--dry-run]
@@ -703,6 +766,14 @@ async function runEventsCli(argv = process.argv.slice(2), options = {}) {
     console.log(version());
     return;
   }
+  if (group === "status") {
+    const status = await getEventsStatus(parsed.dir);
+    output(parsed, status, () => {
+      console.log(`events ${status.counts.events} event(s), ${status.counts.channels} channel(s), ${status.counts.deliveries} delivery record(s)`);
+      console.log(`dataDir: ${status.dataDir}`);
+    });
+    return;
+  }
   const store = new JsonEventsStore(parsed.dir);
   const client = new EventsClient({ store });
   if (group === "webhooks") {
@@ -710,6 +781,10 @@ async function runEventsCli(argv = process.argv.slice(2), options = {}) {
       printWebhooksHelp(options);
       return;
     }
+    if (tail.includes("--help") || tail.includes("-h")) {
+      printWebhooksHelp(options);
+      return;
+    }
     await handleWebhooks(client, command, tail, parsed, options);
     return;
   }
@@ -718,6 +793,10 @@ async function runEventsCli(argv = process.argv.slice(2), options = {}) {
       printEventsHelp(options);
       return;
     }
+    if (tail.includes("--help") || tail.includes("-h")) {
+      printEventsHelp(options);
+      return;
+    }
     await handleEvents(client, command, tail, parsed, options);
     return;
   }
@@ -735,6 +814,7 @@ async function handleWebhooks(client, command, tail, parsed, options) {
     const retryBackoffMs = numberOption(takeOption(args, "--retry-backoff-ms"));
     const disabled = takeFlag(args, "--disabled");
     const headerValues = takeMany(args, "--header");
+    const commandArgs = takeMany(args, "--arg");
     const redactions = takeMany(args, "--redact");
     const filters = parseFilter(args);
     const target = args[0];
@@ -755,7 +835,7 @@ async function handleWebhooks(client, command, tail, parsed, options) {
     if (transport === "webhook") {
       channel.webhook = { url: target, secret, headers: parseHeaders(headerValues), timeoutMs };
     } else if (transport === "command") {
-      channel.command = { command: target, args: args.slice(1), timeoutMs };
+      channel.command = { command: target, args: [...args.slice(1), ...commandArgs], timeoutMs };
     } else {
       throw new Error(`Transport ${transport} is reserved for future use and cannot be added yet`);
     }

package/dist/commander.js

@@ -52,6 +52,13 @@ var HASNA_EVENTS_HOME_ENV = "HASNA_EVENTS_HOME";
 function getEventsDataDir(override) {
   return override || process.env[HASNA_EVENTS_DIR_ENV] || process.env[HASNA_EVENTS_HOME_ENV] || join(homedir(), ".hasna", "events");
 }
+function getActiveEventsDirEnv() {
+  if (process.env[HASNA_EVENTS_DIR_ENV])
+    return HASNA_EVENTS_DIR_ENV;
+  if (process.env[HASNA_EVENTS_HOME_ENV])
+    return HASNA_EVENTS_HOME_ENV;
+  return null;
+}
 
 class JsonEventsStore {
   dataDir;
@@ -164,6 +171,52 @@ class JsonEventsStore {
     });
   }
 }
+async function getEventsStatus(dataDir) {
+  const store = new JsonEventsStore(dataDir);
+  await store.init();
+  const [channels, events, deliveries] = await Promise.all([
+    store.listChannels(),
+    store.listEvents(),
+    store.listDeliveries()
+  ]);
+  const transports = channels.reduce((counts, channel) => {
+    counts[channel.transport] = (counts[channel.transport] ?? 0) + 1;
+    return counts;
+  }, {});
+  return {
+    service: "events",
+    schemaVersion: "1.0",
+    dataDir: store.dataDir,
+    env: {
+      primary: HASNA_EVENTS_DIR_ENV,
+      fallback: HASNA_EVENTS_HOME_ENV,
+      active: getActiveEventsDirEnv()
+    },
+    files: {
+      channels: statusFile(store.dataDir, "channels.json", channels.length),
+      events: statusFile(store.dataDir, "events.json", events.length),
+      deliveries: statusFile(store.dataDir, "deliveries.json", deliveries.length)
+    },
+    counts: {
+      channels: channels.length,
+      enabledChannels: channels.filter((channel) => channel.enabled).length,
+      disabledChannels: channels.filter((channel) => !channel.enabled).length,
+      events: events.length,
+      deliveries: deliveries.length
+    },
+    transports,
+    safety: {
+      includesEventPayloads: false,
+      includesWebhookSecrets: false,
+      listOutputsRedactSecrets: true,
+      statusOutputIsMetadataOnly: true
+    }
+  };
+}
+function statusFile(dataDir, fileName, records) {
+  const path = join(dataDir, fileName);
+  return { path, exists: existsSync(path), records };
+}
 
 // src/signing.ts
 import { createHmac, timingSafeEqual } from "crypto";

package/dist/index.js

@@ -52,6 +52,13 @@ var HASNA_EVENTS_HOME_ENV = "HASNA_EVENTS_HOME";
 function getEventsDataDir(override) {
   return override || process.env[HASNA_EVENTS_DIR_ENV] || process.env[HASNA_EVENTS_HOME_ENV] || join(homedir(), ".hasna", "events");
 }
+function getActiveEventsDirEnv() {
+  if (process.env[HASNA_EVENTS_DIR_ENV])
+    return HASNA_EVENTS_DIR_ENV;
+  if (process.env[HASNA_EVENTS_HOME_ENV])
+    return HASNA_EVENTS_HOME_ENV;
+  return null;
+}
 
 class JsonEventsStore {
   dataDir;
@@ -164,6 +171,52 @@ class JsonEventsStore {
     });
   }
 }
+async function getEventsStatus(dataDir) {
+  const store = new JsonEventsStore(dataDir);
+  await store.init();
+  const [channels, events, deliveries] = await Promise.all([
+    store.listChannels(),
+    store.listEvents(),
+    store.listDeliveries()
+  ]);
+  const transports = channels.reduce((counts, channel) => {
+    counts[channel.transport] = (counts[channel.transport] ?? 0) + 1;
+    return counts;
+  }, {});
+  return {
+    service: "events",
+    schemaVersion: "1.0",
+    dataDir: store.dataDir,
+    env: {
+      primary: HASNA_EVENTS_DIR_ENV,
+      fallback: HASNA_EVENTS_HOME_ENV,
+      active: getActiveEventsDirEnv()
+    },
+    files: {
+      channels: statusFile(store.dataDir, "channels.json", channels.length),
+      events: statusFile(store.dataDir, "events.json", events.length),
+      deliveries: statusFile(store.dataDir, "deliveries.json", deliveries.length)
+    },
+    counts: {
+      channels: channels.length,
+      enabledChannels: channels.filter((channel) => channel.enabled).length,
+      disabledChannels: channels.filter((channel) => !channel.enabled).length,
+      events: events.length,
+      deliveries: deliveries.length
+    },
+    transports,
+    safety: {
+      includesEventPayloads: false,
+      includesWebhookSecrets: false,
+      listOutputsRedactSecrets: true,
+      statusOutputIsMetadataOnly: true
+    }
+  };
+}
+function statusFile(dataDir, fileName, records) {
+  const path = join(dataDir, fileName);
+  return { path, exists: existsSync(path), records };
+}
 
 // src/signing.ts
 import { createHmac, timingSafeEqual } from "crypto";
@@ -558,7 +611,9 @@ export {
   redactPaths,
   matchString,
   isTimestampWithinTolerance,
+  getEventsStatus,
   getEventsDataDir,
+  getActiveEventsDirEnv,
   eventMatchesFilter,
   dispatchWebhook,
   dispatchCommand,

package/dist/storage.d.ts

@@ -1,7 +1,8 @@
-import type { ChannelConfig, DeliveryResult, EventEnvelope, StoredEventsData } from "./types.js";
+import type { ChannelConfig, DeliveryResult, EventEnvelope, EventsStatus, StoredEventsData } from "./types.js";
 export declare const HASNA_EVENTS_DIR_ENV = "HASNA_EVENTS_DIR";
 export declare const HASNA_EVENTS_HOME_ENV = "HASNA_EVENTS_HOME";
 export declare function getEventsDataDir(override?: string): string;
+export declare function getActiveEventsDirEnv(): EventsStatus["env"]["active"];
 export interface EventsStore {
     dataDir: string;
     init(): Promise<void>;
@@ -42,3 +43,4 @@ export declare class JsonEventsStore implements EventsStore {
     private readJson;
     private writeJson;
 }
+export declare function getEventsStatus(dataDir?: string): Promise<EventsStatus>;

package/dist/storage.js

@@ -9,6 +9,13 @@ var HASNA_EVENTS_HOME_ENV = "HASNA_EVENTS_HOME";
 function getEventsDataDir(override) {
   return override || process.env[HASNA_EVENTS_DIR_ENV] || process.env[HASNA_EVENTS_HOME_ENV] || join(homedir(), ".hasna", "events");
 }
+function getActiveEventsDirEnv() {
+  if (process.env[HASNA_EVENTS_DIR_ENV])
+    return HASNA_EVENTS_DIR_ENV;
+  if (process.env[HASNA_EVENTS_HOME_ENV])
+    return HASNA_EVENTS_HOME_ENV;
+  return null;
+}
 
 class JsonEventsStore {
   dataDir;
@@ -121,8 +128,56 @@ class JsonEventsStore {
     });
   }
 }
+async function getEventsStatus(dataDir) {
+  const store = new JsonEventsStore(dataDir);
+  await store.init();
+  const [channels, events, deliveries] = await Promise.all([
+    store.listChannels(),
+    store.listEvents(),
+    store.listDeliveries()
+  ]);
+  const transports = channels.reduce((counts, channel) => {
+    counts[channel.transport] = (counts[channel.transport] ?? 0) + 1;
+    return counts;
+  }, {});
+  return {
+    service: "events",
+    schemaVersion: "1.0",
+    dataDir: store.dataDir,
+    env: {
+      primary: HASNA_EVENTS_DIR_ENV,
+      fallback: HASNA_EVENTS_HOME_ENV,
+      active: getActiveEventsDirEnv()
+    },
+    files: {
+      channels: statusFile(store.dataDir, "channels.json", channels.length),
+      events: statusFile(store.dataDir, "events.json", events.length),
+      deliveries: statusFile(store.dataDir, "deliveries.json", deliveries.length)
+    },
+    counts: {
+      channels: channels.length,
+      enabledChannels: channels.filter((channel) => channel.enabled).length,
+      disabledChannels: channels.filter((channel) => !channel.enabled).length,
+      events: events.length,
+      deliveries: deliveries.length
+    },
+    transports,
+    safety: {
+      includesEventPayloads: false,
+      includesWebhookSecrets: false,
+      listOutputsRedactSecrets: true,
+      statusOutputIsMetadataOnly: true
+    }
+  };
+}
+function statusFile(dataDir, fileName, records) {
+  const path = join(dataDir, fileName);
+  return { path, exists: existsSync(path), records };
+}
 export {
+  getEventsStatus,
   getEventsDataDir,
+  getActiveEventsDirEnv,
   JsonEventsStore,
   HASNA_EVENTS_HOME_ENV,
   HASNA_EVENTS_DIR_ENV

package/dist/types.d.ts

@@ -117,3 +117,44 @@ export interface EmitResult<TData extends EventData = EventData> {
     deliveries: DeliveryResult[];
     deduped: boolean;
 }
+export interface EventsStatus {
+    service: "events";
+    schemaVersion: "1.0";
+    dataDir: string;
+    env: {
+        primary: "HASNA_EVENTS_DIR";
+        fallback: "HASNA_EVENTS_HOME";
+        active: "HASNA_EVENTS_DIR" | "HASNA_EVENTS_HOME" | null;
+    };
+    files: {
+        channels: {
+            path: string;
+            exists: boolean;
+            records: number;
+        };
+        events: {
+            path: string;
+            exists: boolean;
+            records: number;
+        };
+        deliveries: {
+            path: string;
+            exists: boolean;
+            records: number;
+        };
+    };
+    counts: {
+        channels: number;
+        enabledChannels: number;
+        disabledChannels: number;
+        events: number;
+        deliveries: number;
+    };
+    transports: Record<string, number>;
+    safety: {
+        includesEventPayloads: false;
+        includesWebhookSecrets: false;
+        listOutputsRedactSecrets: true;
+        statusOutputIsMetadataOnly: true;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/events",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Shared event envelopes, local subscriptions, and webhook delivery for Hasna open-source apps",
   "type": "module",
   "main": "./dist/index.js",