@hasna/events 0.1.7 → 0.1.9

package/README.md

@@ -204,6 +204,37 @@ events webhooks test ops
 events webhooks remove ops
 ```
 
+Field filters can match nested `data` or `metadata` values. Plain
+`--data`/`--metadata` values are strings, which keeps ids and slugs such as
+`001` intact. Use `--data-json` or `--metadata-json` for typed JSON predicates.
+Dot paths access nested object keys; dots inside key names are not escaped yet,
+and array traversal is not special-cased. Wildcard behavior stays broad for
+legacy source/type/subject filters. For field paths ending in `_path` or `.path`,
+`*` matches one path segment and `**` matches recursively.
+
+```bash
+events webhooks add loops \
+  --id open-source-task-route \
+  --transport command \
+  --source todos \
+  --type task.created \
+  --metadata 'project_path=/home/hasna/workspace/hasna/opensource/*' \
+  --metadata-json 'route_enabled=true' \
+  --arg events \
+  --arg handle \
+  --arg todos-task
+
+events webhooks match open-source-task-route \
+  --source todos \
+  --type task.created \
+  --metadata '{"project_path":"/home/hasna/workspace/hasna/opensource/open-events","route_enabled":true}'
+
+events webhooks test open-source-task-route --honor-filters \
+  --source todos \
+  --type task.created \
+  --metadata '{"project_path":"/tmp/outside","route_enabled":true}'
+```
+
 Emit, list, and replay:
 
 ```bash
@@ -219,6 +250,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

@@ -18,17 +18,30 @@ function getPathValue(input, path) {
     return;
   }, input);
 }
-function wildcardToRegExp(pattern) {
-  const escaped = pattern.replace(/[|\\{}()[\]^$+?.]/g, "\\$&").replace(/\*/g, ".*");
-  return new RegExp(`^${escaped}$`);
+function wildcardToRegExp(pattern, options = {}) {
+  let body = "";
+  for (let index = 0;index < pattern.length; index += 1) {
+    const char = pattern[index];
+    if (char === "*") {
+      if (pattern[index + 1] === "*") {
+        body += ".*";
+        index += 1;
+      } else {
+        body += options.segmentSafe ? "[^/]*" : ".*";
+      }
+    } else {
+      body += char.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+    }
+  }
+  return new RegExp(`^${body}$`);
 }
-function matchString(value, matcher) {
+function matchString(value, matcher, options = {}) {
   if (matcher === undefined)
     return true;
   if (value === undefined)
     return false;
   const matchers = Array.isArray(matcher) ? matcher : [matcher];
-  return matchers.some((item) => wildcardToRegExp(item).test(value));
+  return matchers.some((item) => wildcardToRegExp(item, options).test(value));
 }
 function matchRecord(input, matcher) {
   if (!matcher)
@@ -36,7 +49,9 @@ function matchRecord(input, matcher) {
   return Object.entries(matcher).every(([path, expected]) => {
     const actual = getPathValue(input, path);
     if (typeof expected === "string" || Array.isArray(expected)) {
-      return matchString(actual === undefined ? undefined : String(actual), expected);
+      return matchString(actual === undefined ? undefined : String(actual), expected, {
+        segmentSafe: path.endsWith("_path") || path.endsWith(".path")
+      });
     }
     return actual === expected;
   });
@@ -62,6 +77,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 +196,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";
@@ -410,7 +478,7 @@ class EventsClient {
     }
     return deliveries;
   }
-  async testChannel(id, input = {}) {
+  async matchChannel(id, input = {}) {
     const channel = await this.store.getChannel(id);
     if (!channel)
       throw new Error(`Channel not found: ${id}`);
@@ -427,6 +495,34 @@ class EventsClient {
       time: input.time,
       id: input.id
     });
+    const matched = channelMatchesEvent(channel, event);
+    return {
+      channelId: channel.id,
+      matched,
+      event,
+      filters: channel.filters,
+      reason: matched ? undefined : channel.enabled ? "event did not match channel filters" : "channel is disabled"
+    };
+  }
+  async testChannel(id, input = {}, options = {}) {
+    const channel = await this.store.getChannel(id);
+    if (!channel)
+      throw new Error(`Channel not found: ${id}`);
+    const match = await this.matchChannel(id, input);
+    const event = match.event;
+    if (options.honorFilters && !match.matched) {
+      const timestamp = new Date().toISOString();
+      const result2 = createDeliveryResult(event, channel, [{
+        attempt: 1,
+        status: "skipped",
+        startedAt: timestamp,
+        completedAt: timestamp,
+        error: match.reason
+      }]);
+      result2.metadata = { reason: "filter_mismatch" };
+      await this.store.appendDelivery(result2);
+      return result2;
+    }
     const eventForChannel = await this.applyRedaction(event, channel);
     const result = await this.deliverWithRetry(eventForChannel, channel);
     await this.store.appendDelivery(result);
@@ -538,6 +634,61 @@ function normalizeRetryPolicy(policy) {
   };
 }
 
+// src/filter-options.ts
+function parseFieldMatchers(values, label, typed = false) {
+  if (!values?.length)
+    return;
+  const result = {};
+  for (const value of values) {
+    const separator = value.indexOf("=");
+    if (separator <= 0)
+      throw new Error(`Invalid ${label} filter, expected path=value: ${value}`);
+    const path = value.slice(0, separator);
+    if (path in result)
+      throw new Error(`Duplicate ${label} filter path: ${path}`);
+    result[path] = typed ? parseTypedMatcherValue(value.slice(separator + 1), label) : value.slice(separator + 1);
+  }
+  return result;
+}
+function parseFilterOptions(options) {
+  const filter2 = {};
+  if (options.source)
+    filter2.source = options.source;
+  if (options.type)
+    filter2.type = options.type;
+  if (options.subject)
+    filter2.subject = options.subject;
+  if (options.severity)
+    filter2.severity = options.severity;
+  const data = mergeMatchers(parseFieldMatchers(options.data, "data"), parseFieldMatchers(options.dataJson, "data-json", true));
+  const metadata = mergeMatchers(parseFieldMatchers(options.metadata, "metadata"), parseFieldMatchers(options.metadataJson, "metadata-json", true));
+  if (Object.keys(data).length > 0)
+    filter2.data = data;
+  if (Object.keys(metadata).length > 0)
+    filter2.metadata = metadata;
+  return Object.keys(filter2).length > 0 ? [filter2] : undefined;
+}
+function mergeMatchers(...records) {
+  const result = {};
+  for (const record of records) {
+    if (!record)
+      continue;
+    for (const [path, value] of Object.entries(record)) {
+      if (path in result)
+        throw new Error(`Duplicate filter path: ${path}`);
+      result[path] = value;
+    }
+  }
+  return result;
+}
+function parseTypedMatcherValue(value, label) {
+  const parsed = JSON.parse(value);
+  if (parsed === null || typeof parsed === "string" || typeof parsed === "number" || typeof parsed === "boolean" || Array.isArray(parsed) && parsed.every((item) => typeof item === "string")) {
+    return parsed;
+  }
+  throw new Error(`${label} filter JSON values must be string, string[], number, boolean, or null`);
+}
+
 // src/cli/index.ts
 function version() {
   try {
@@ -606,20 +757,16 @@ function parseJsonOption(value, fallback) {
   return parsed;
 }
 function parseFilter(args) {
-  const filter2 = {};
-  const type = takeOption(args, "--type") ?? takeOption(args, "--event-type");
-  const source = takeOption(args, "--source");
-  const subject = takeOption(args, "--subject");
-  const severity = takeOption(args, "--severity");
-  if (type)
-    filter2.type = type;
-  if (source)
-    filter2.source = source;
-  if (subject)
-    filter2.subject = subject;
-  if (severity)
-    filter2.severity = severity;
-  return Object.keys(filter2).length > 0 ? [filter2] : undefined;
+  return parseFilterOptions({
+    type: takeOption(args, "--type") ?? takeOption(args, "--event-type"),
+    source: takeOption(args, "--source"),
+    subject: takeOption(args, "--subject"),
+    severity: takeOption(args, "--severity"),
+    data: takeMany(args, "--data"),
+    metadata: takeMany(args, "--metadata"),
+    dataJson: takeMany(args, "--data-json"),
+    metadataJson: takeMany(args, "--metadata-json")
+  });
 }
 function parseHeaders(values) {
   if (values.length === 0)
@@ -652,6 +799,9 @@ 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] webhooks match <id>
+  ${name} [--dir <path>] [--json] webhooks status
+  ${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]
@@ -668,6 +818,8 @@ 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] webhooks match <id>
+  ${name} [--dir <path>] [--json] webhooks status
 
 Options:
   --id <id>                 Channel id for add
@@ -675,6 +827,11 @@ Options:
   --source <source>         Event source filter
   --subject <subject>       Event subject filter
   --severity <severity>     Event severity filter
+  --data <path=value>       Event data field filter, repeatable; string values, dot paths, * segment wildcard, ** recursive wildcard
+  --metadata <path=value>   Event metadata field filter, repeatable; string values, dot paths, * segment wildcard, ** recursive wildcard
+  --data-json <path=json>   Event data field filter with typed JSON value
+  --metadata-json <path=json> Event metadata field filter with typed JSON value
+  --honor-filters           On webhooks test, skip delivery when the sample event does not match filters
   --transport <kind>        webhook or command
   --secret <secret>         Webhook signing secret
   --header <name=value>     Webhook header, repeatable
@@ -712,6 +869,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") {
@@ -795,6 +960,14 @@ async function handleWebhooks(client, command, tail, parsed, options) {
     });
     return;
   }
+  if (command === "status") {
+    const status = await getEventsStatus(parsed.dir);
+    output(parsed, status, () => {
+      console.log(`events dataDir: ${status.dataDir}`);
+      console.log(`${status.counts.enabledChannels}/${status.counts.channels} channel(s) enabled`);
+    });
+    return;
+  }
   if (command === "remove") {
     const id = tail[0];
     if (!id)
@@ -808,15 +981,34 @@ async function handleWebhooks(client, command, tail, parsed, options) {
     const id = args.shift();
     if (!id)
       throw new Error("webhooks test requires a channel id");
+    const honorFilters = takeFlag(args, "--honor-filters");
     const result = await client.testChannel(id, {
       source: takeOption(args, "--source") ?? options.source ?? "hasna.events",
       type: takeOption(args, "--type") ?? "events.test",
       subject: takeOption(args, "--subject") ?? id,
-      data: parseJsonOption(takeOption(args, "--data"), { test: true })
-    });
+      message: takeOption(args, "--message") ?? "Hasna events test delivery",
+      data: parseJsonOption(takeOption(args, "--data"), { test: true }),
+      metadata: parseJsonOption(takeOption(args, "--metadata"), {})
+    }, { honorFilters });
     output(parsed, result, () => console.log(`${result.status}: ${result.channelId}`));
     return;
   }
+  if (command === "match") {
+    const args = [...tail];
+    const id = args.shift();
+    if (!id)
+      throw new Error("webhooks match requires a channel id");
+    const result = await client.matchChannel(id, {
+      source: takeOption(args, "--source") ?? options.source ?? "hasna.events",
+      type: takeOption(args, "--type") ?? "events.test",
+      subject: takeOption(args, "--subject") ?? id,
+      message: takeOption(args, "--message") ?? "Hasna events match preview",
+      data: parseJsonOption(takeOption(args, "--data"), { test: true }),
+      metadata: parseJsonOption(takeOption(args, "--metadata"), {})
+    });
+    output(parsed, result, () => console.log(`${result.matched ? "matched" : "skipped"}: ${result.channelId}`));
+    return;
+  }
   throw new Error(`Unknown webhooks command: ${command ?? ""}`);
 }
 async function handleEvents(client, command, tail, parsed, options) {

package/dist/commander.js

@@ -8,17 +8,30 @@ function getPathValue(input, path) {
     return;
   }, input);
 }
-function wildcardToRegExp(pattern) {
-  const escaped = pattern.replace(/[|\\{}()[\]^$+?.]/g, "\\$&").replace(/\*/g, ".*");
-  return new RegExp(`^${escaped}$`);
+function wildcardToRegExp(pattern, options = {}) {
+  let body = "";
+  for (let index = 0;index < pattern.length; index += 1) {
+    const char = pattern[index];
+    if (char === "*") {
+      if (pattern[index + 1] === "*") {
+        body += ".*";
+        index += 1;
+      } else {
+        body += options.segmentSafe ? "[^/]*" : ".*";
+      }
+    } else {
+      body += char.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+    }
+  }
+  return new RegExp(`^${body}$`);
 }
-function matchString(value, matcher) {
+function matchString(value, matcher, options = {}) {
   if (matcher === undefined)
     return true;
   if (value === undefined)
     return false;
   const matchers = Array.isArray(matcher) ? matcher : [matcher];
-  return matchers.some((item) => wildcardToRegExp(item).test(value));
+  return matchers.some((item) => wildcardToRegExp(item, options).test(value));
 }
 function matchRecord(input, matcher) {
   if (!matcher)
@@ -26,7 +39,9 @@ function matchRecord(input, matcher) {
   return Object.entries(matcher).every(([path, expected]) => {
     const actual = getPathValue(input, path);
     if (typeof expected === "string" || Array.isArray(expected)) {
-      return matchString(actual === undefined ? undefined : String(actual), expected);
+      return matchString(actual === undefined ? undefined : String(actual), expected, {
+        segmentSafe: path.endsWith("_path") || path.endsWith(".path")
+      });
     }
     return actual === expected;
   });
@@ -52,6 +67,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 +186,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";
@@ -421,7 +489,7 @@ class EventsClient {
     }
     return deliveries;
   }
-  async testChannel(id, input = {}) {
+  async matchChannel(id, input = {}) {
     const channel = await this.store.getChannel(id);
     if (!channel)
       throw new Error(`Channel not found: ${id}`);
@@ -438,6 +506,34 @@ class EventsClient {
       time: input.time,
       id: input.id
     });
+    const matched = channelMatchesEvent(channel, event);
+    return {
+      channelId: channel.id,
+      matched,
+      event,
+      filters: channel.filters,
+      reason: matched ? undefined : channel.enabled ? "event did not match channel filters" : "channel is disabled"
+    };
+  }
+  async testChannel(id, input = {}, options = {}) {
+    const channel = await this.store.getChannel(id);
+    if (!channel)
+      throw new Error(`Channel not found: ${id}`);
+    const match = await this.matchChannel(id, input);
+    const event = match.event;
+    if (options.honorFilters && !match.matched) {
+      const timestamp = new Date().toISOString();
+      const result2 = createDeliveryResult(event, channel, [{
+        attempt: 1,
+        status: "skipped",
+        startedAt: timestamp,
+        completedAt: timestamp,
+        error: match.reason
+      }]);
+      result2.metadata = { reason: "filter_mismatch" };
+      await this.store.appendDelivery(result2);
+      return result2;
+    }
     const eventForChannel = await this.applyRedaction(event, channel);
     const result = await this.deliverWithRetry(eventForChannel, channel);
     await this.store.appendDelivery(result);
@@ -549,6 +645,61 @@ function normalizeRetryPolicy(policy) {
   };
 }
 
+// src/filter-options.ts
+function parseFieldMatchers(values, label, typed = false) {
+  if (!values?.length)
+    return;
+  const result = {};
+  for (const value of values) {
+    const separator = value.indexOf("=");
+    if (separator <= 0)
+      throw new Error(`Invalid ${label} filter, expected path=value: ${value}`);
+    const path = value.slice(0, separator);
+    if (path in result)
+      throw new Error(`Duplicate ${label} filter path: ${path}`);
+    result[path] = typed ? parseTypedMatcherValue(value.slice(separator + 1), label) : value.slice(separator + 1);
+  }
+  return result;
+}
+function parseFilterOptions(options) {
+  const filter2 = {};
+  if (options.source)
+    filter2.source = options.source;
+  if (options.type)
+    filter2.type = options.type;
+  if (options.subject)
+    filter2.subject = options.subject;
+  if (options.severity)
+    filter2.severity = options.severity;
+  const data = mergeMatchers(parseFieldMatchers(options.data, "data"), parseFieldMatchers(options.dataJson, "data-json", true));
+  const metadata = mergeMatchers(parseFieldMatchers(options.metadata, "metadata"), parseFieldMatchers(options.metadataJson, "metadata-json", true));
+  if (Object.keys(data).length > 0)
+    filter2.data = data;
+  if (Object.keys(metadata).length > 0)
+    filter2.metadata = metadata;
+  return Object.keys(filter2).length > 0 ? [filter2] : undefined;
+}
+function mergeMatchers(...records) {
+  const result = {};
+  for (const record of records) {
+    if (!record)
+      continue;
+    for (const [path, value] of Object.entries(record)) {
+      if (path in result)
+        throw new Error(`Duplicate filter path: ${path}`);
+      result[path] = value;
+    }
+  }
+  return result;
+}
+function parseTypedMatcherValue(value, label) {
+  const parsed = JSON.parse(value);
+  if (parsed === null || typeof parsed === "string" || typeof parsed === "number" || typeof parsed === "boolean" || Array.isArray(parsed) && parsed.every((item) => typeof item === "string")) {
+    return parsed;
+  }
+  throw new Error(`${label} filter JSON values must be string, string[], number, boolean, or null`);
+}
+
 // src/commander.ts
 function parseJsonObject(value, fallback) {
   if (!value)
@@ -571,18 +722,6 @@ function parseHeaders(values) {
   }
   return headers;
 }
-function parseFilter(options) {
-  const filter2 = {};
-  if (options.source)
-    filter2.source = options.source;
-  if (options.type)
-    filter2.type = options.type;
-  if (options.subject)
-    filter2.subject = options.subject;
-  if (options.severity)
-    filter2.severity = options.severity;
-  return Object.keys(filter2).length > 0 ? [filter2] : undefined;
-}
 function createClient(options) {
   if (options.createClient)
     return options.createClient();
@@ -602,14 +741,14 @@ function wantsJson(actionOptions, command) {
 }
 function registerWebhookCommands(program, options) {
   const webhooks = program.command(options.webhooksCommandName ?? "webhooks").description("Manage Hasna event webhook subscriptions");
-  webhooks.command("add").description("Add or replace a webhook or command subscription").argument("<target>", "Webhook URL or command binary").requiredOption("--id <id>", "Subscription/channel identifier").option("--transport <kind>", "Transport kind: webhook or command", "webhook").option("--name <name>", "Display name").option("--type <pattern>", "Event type filter, e.g. todos.task.*").option("--source <pattern>", "Event source filter").option("--subject <pattern>", "Event subject filter").option("--severity <pattern>", "Event severity filter").option("--secret <secret>", "Webhook HMAC secret").option("--header <name=value...>", "Webhook header", collectValues, []).option("--arg <arg...>", "Command argument", collectValues, []).option("--timeout-ms <ms>", "Transport timeout in milliseconds", parseNumber).option("--retry-attempts <n>", "Maximum delivery attempts", parseNumber).option("--retry-backoff-ms <ms>", "Initial retry backoff in milliseconds", parseNumber).option("--redact <path...>", "Event field path to redact before delivery", collectValues, []).option("--disabled", "Create channel disabled", false).option("-j, --json", "Print JSON output", false).action(async (target, actionOptions, command) => {
+  webhooks.command("add").description("Add or replace a webhook or command subscription").argument("<target>", "Webhook URL or command binary").requiredOption("--id <id>", "Subscription/channel identifier").option("--transport <kind>", "Transport kind: webhook or command", "webhook").option("--name <name>", "Display name").option("--type <pattern>", "Event type filter, e.g. todos.task.*").option("--source <pattern>", "Event source filter").option("--subject <pattern>", "Event subject filter").option("--severity <pattern>", "Event severity filter").option("--data <path=value...>", "Event data field filter; string values, dot paths, * segment wildcard, ** recursive wildcard", collectValues, []).option("--metadata <path=value...>", "Event metadata field filter; string values, dot paths, * segment wildcard, ** recursive wildcard", collectValues, []).option("--data-json <path=json...>", "Event data field filter with typed JSON value", collectValues, []).option("--metadata-json <path=json...>", "Event metadata field filter with typed JSON value", collectValues, []).option("--secret <secret>", "Webhook HMAC secret").option("--header <name=value...>", "Webhook header", collectValues, []).option("--arg <arg...>", "Command argument", collectValues, []).option("--timeout-ms <ms>", "Transport timeout in milliseconds", parseNumber).option("--retry-attempts <n>", "Maximum delivery attempts", parseNumber).option("--retry-backoff-ms <ms>", "Initial retry backoff in milliseconds", parseNumber).option("--redact <path...>", "Event field path to redact before delivery", collectValues, []).option("--disabled", "Create channel disabled", false).option("-j, --json", "Print JSON output", false).action(async (target, actionOptions, command) => {
     const timestamp = new Date().toISOString();
     const channel = {
       id: actionOptions.id,
       name: actionOptions.name,
       enabled: !actionOptions.disabled,
       transport: actionOptions.transport,
-      filters: parseFilter(actionOptions),
+      filters: parseFilterOptions(actionOptions),
       retry: actionOptions.retryAttempts || actionOptions.retryBackoffMs ? { maxAttempts: actionOptions.retryAttempts, backoffMs: actionOptions.retryBackoffMs } : undefined,
       redact: actionOptions.redact?.length ? { paths: actionOptions.redact } : undefined,
       createdAt: timestamp,
@@ -639,20 +778,36 @@ function registerWebhookCommands(program, options) {
       console.log(`${channel.id}	${channel.enabled ? "enabled" : "disabled"}	${channel.transport}	${channel.webhook?.url ?? channel.command?.command ?? channel.transport}`);
     }
   });
+  webhooks.command("status").description("Show events webhook storage status").option("-j, --json", "Print JSON output", false).action(async (actionOptions, command) => {
+    const status = await getEventsStatus(options.dataDir);
+    print(status, wantsJson(actionOptions, command), `events dataDir: ${status.dataDir}`);
+  });
   webhooks.command("remove").description("Remove a subscription").argument("<id>", "Subscription/channel identifier").option("-j, --json", "Print JSON output", false).action(async (id, actionOptions, command) => {
     const removed = await createClient(options).removeChannel(id);
     print({ removed }, wantsJson(actionOptions, command), removed ? `Removed ${id}` : `Channel not found: ${id}`);
   });
-  webhooks.command("test").description("Send a test event to one subscription").argument("<id>", "Subscription/channel identifier").option("--type <type>", "Event type", "events.test").option("--subject <subject>", "Event subject").option("--message <message>", "Event message", "Hasna events test delivery").option("--data <json>", "Event data JSON object").option("-j, --json", "Print JSON output", false).action(async (id, actionOptions, command) => {
+  webhooks.command("test").description("Send a test event to one subscription").argument("<id>", "Subscription/channel identifier").option("--source <source>", "Event source override").option("--type <type>", "Event type", "events.test").option("--subject <subject>", "Event subject").option("--message <message>", "Event message", "Hasna events test delivery").option("--data <json>", "Event data JSON object").option("--metadata <json>", "Event metadata JSON object").option("--honor-filters", "Skip delivery when the sample event does not match channel filters", false).option("-j, --json", "Print JSON output", false).action(async (id, actionOptions, command) => {
     const result = await createClient(options).testChannel(id, {
-      source: options.source,
+      source: actionOptions.source ?? options.source,
       type: actionOptions.type,
       subject: actionOptions.subject ?? id,
       message: actionOptions.message,
-      data: parseJsonObject(actionOptions.data, { test: true })
-    });
+      data: parseJsonObject(actionOptions.data, { test: true }),
+      metadata: parseJsonObject(actionOptions.metadata, {})
+    }, { honorFilters: actionOptions.honorFilters });
     print(result, wantsJson(actionOptions, command), `${result.status}: ${result.channelId}`);
   });
+  webhooks.command("match").description("Check whether a sample event matches one subscription without delivering").argument("<id>", "Subscription/channel identifier").option("--source <source>", "Event source override").option("--type <type>", "Event type", "events.test").option("--subject <subject>", "Event subject").option("--message <message>", "Event message", "Hasna events match preview").option("--data <json>", "Event data JSON object").option("--metadata <json>", "Event metadata JSON object").option("-j, --json", "Print JSON output", false).action(async (id, actionOptions, command) => {
+    const result = await createClient(options).matchChannel(id, {
+      source: actionOptions.source ?? options.source,
+      type: actionOptions.type,
+      subject: actionOptions.subject ?? id,
+      message: actionOptions.message,
+      data: parseJsonObject(actionOptions.data, { test: true }),
+      metadata: parseJsonObject(actionOptions.metadata, {})
+    });
+    print(result, wantsJson(actionOptions, command), `${result.matched ? "matched" : "skipped"}: ${result.channelId}`);
+  });
   return webhooks;
 }
 function registerEventCommands(program, options) {

package/dist/filter-options.d.ts

@@ -0,0 +1,15 @@
+import type { EventFilter, StringMatcher } from "./types.js";
+type MatcherValue = StringMatcher | number | boolean | null;
+export interface FilterOptionInput {
+    source?: string;
+    type?: string;
+    subject?: string;
+    severity?: string;
+    data?: string[];
+    metadata?: string[];
+    dataJson?: string[];
+    metadataJson?: string[];
+}
+export declare function parseFieldMatchers(values: string[] | undefined, label: string, typed?: boolean): Record<string, MatcherValue> | undefined;
+export declare function parseFilterOptions(options: FilterOptionInput): EventFilter[] | undefined;
+export {};

package/dist/filter.d.ts

@@ -1,4 +1,6 @@
 import type { ChannelConfig, EventEnvelope, EventFilter, StringMatcher } from "./types.js";
-export declare function matchString(value: string | undefined, matcher: StringMatcher | undefined): boolean;
+export declare function matchString(value: string | undefined, matcher: StringMatcher | undefined, options?: {
+    segmentSafe?: boolean;
+}): boolean;
 export declare function eventMatchesFilter(event: EventEnvelope, filter: EventFilter): boolean;
 export declare function channelMatchesEvent(channel: ChannelConfig, event: EventEnvelope): boolean;

package/dist/filter.js

@@ -8,17 +8,30 @@ function getPathValue(input, path) {
     return;
   }, input);
 }
-function wildcardToRegExp(pattern) {
-  const escaped = pattern.replace(/[|\\{}()[\]^$+?.]/g, "\\$&").replace(/\*/g, ".*");
-  return new RegExp(`^${escaped}$`);
+function wildcardToRegExp(pattern, options = {}) {
+  let body = "";
+  for (let index = 0;index < pattern.length; index += 1) {
+    const char = pattern[index];
+    if (char === "*") {
+      if (pattern[index + 1] === "*") {
+        body += ".*";
+        index += 1;
+      } else {
+        body += options.segmentSafe ? "[^/]*" : ".*";
+      }
+    } else {
+      body += char.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+    }
+  }
+  return new RegExp(`^${body}$`);
 }
-function matchString(value, matcher) {
+function matchString(value, matcher, options = {}) {
   if (matcher === undefined)
     return true;
   if (value === undefined)
     return false;
   const matchers = Array.isArray(matcher) ? matcher : [matcher];
-  return matchers.some((item) => wildcardToRegExp(item).test(value));
+  return matchers.some((item) => wildcardToRegExp(item, options).test(value));
 }
 function matchRecord(input, matcher) {
   if (!matcher)
@@ -26,7 +39,9 @@ function matchRecord(input, matcher) {
   return Object.entries(matcher).every(([path, expected]) => {
     const actual = getPathValue(input, path);
     if (typeof expected === "string" || Array.isArray(expected)) {
-      return matchString(actual === undefined ? undefined : String(actual), expected);
+      return matchString(actual === undefined ? undefined : String(actual), expected, {
+        segmentSafe: path.endsWith("_path") || path.endsWith(".path")
+      });
     }
     return actual === expected;
   });

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { ChannelConfig, DeliveryResult, EmitOptions, EmitResult, EventEnvelope, EventInput, EventRedactor, ReplayOptions } from "./types.js";
+import type { ChannelConfig, DeliveryResult, EmitOptions, EmitResult, EventEnvelope, EventFilter, EventInput, EventRedactor, ReplayOptions } from "./types.js";
 import { type EventsStore } from "./storage.js";
 import { type TransportDispatchOptions } from "./transports.js";
 export * from "./types.js";
@@ -11,6 +11,16 @@ export interface EventsClientOptions extends TransportDispatchOptions {
     dataDir?: string;
     redactors?: EventRedactor[];
 }
+export interface ChannelMatchResult {
+    channelId: string;
+    matched: boolean;
+    event: EventEnvelope;
+    filters?: EventFilter[];
+    reason?: string;
+}
+export interface TestChannelOptions {
+    honorFilters?: boolean;
+}
 export declare function createEvent<TData extends Record<string, unknown>>(input: EventInput<TData>): EventEnvelope<TData>;
 export declare class EventsClient {
     private store;
@@ -24,7 +34,8 @@ export declare class EventsClient {
     listEvents(): Promise<EventEnvelope[]>;
     listDeliveries(): Promise<DeliveryResult[]>;
     deliver(event: EventEnvelope): Promise<DeliveryResult[]>;
-    testChannel(id: string, input?: Partial<EventInput>): Promise<DeliveryResult>;
+    matchChannel(id: string, input?: Partial<EventInput>): Promise<ChannelMatchResult>;
+    testChannel(id: string, input?: Partial<EventInput>, options?: TestChannelOptions): Promise<DeliveryResult>;
     replay(options?: ReplayOptions): Promise<{
         events: EventEnvelope[];
         deliveries: DeliveryResult[];

package/dist/index.js

@@ -8,17 +8,30 @@ function getPathValue(input, path) {
     return;
   }, input);
 }
-function wildcardToRegExp(pattern) {
-  const escaped = pattern.replace(/[|\\{}()[\]^$+?.]/g, "\\$&").replace(/\*/g, ".*");
-  return new RegExp(`^${escaped}$`);
+function wildcardToRegExp(pattern, options = {}) {
+  let body = "";
+  for (let index = 0;index < pattern.length; index += 1) {
+    const char = pattern[index];
+    if (char === "*") {
+      if (pattern[index + 1] === "*") {
+        body += ".*";
+        index += 1;
+      } else {
+        body += options.segmentSafe ? "[^/]*" : ".*";
+      }
+    } else {
+      body += char.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+    }
+  }
+  return new RegExp(`^${body}$`);
 }
-function matchString(value, matcher) {
+function matchString(value, matcher, options = {}) {
   if (matcher === undefined)
     return true;
   if (value === undefined)
     return false;
   const matchers = Array.isArray(matcher) ? matcher : [matcher];
-  return matchers.some((item) => wildcardToRegExp(item).test(value));
+  return matchers.some((item) => wildcardToRegExp(item, options).test(value));
 }
 function matchRecord(input, matcher) {
   if (!matcher)
@@ -26,7 +39,9 @@ function matchRecord(input, matcher) {
   return Object.entries(matcher).every(([path, expected]) => {
     const actual = getPathValue(input, path);
     if (typeof expected === "string" || Array.isArray(expected)) {
-      return matchString(actual === undefined ? undefined : String(actual), expected);
+      return matchString(actual === undefined ? undefined : String(actual), expected, {
+        segmentSafe: path.endsWith("_path") || path.endsWith(".path")
+      });
     }
     return actual === expected;
   });
@@ -52,6 +67,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 +186,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";
@@ -421,7 +489,7 @@ class EventsClient {
     }
     return deliveries;
   }
-  async testChannel(id, input = {}) {
+  async matchChannel(id, input = {}) {
     const channel = await this.store.getChannel(id);
     if (!channel)
       throw new Error(`Channel not found: ${id}`);
@@ -438,6 +506,34 @@ class EventsClient {
       time: input.time,
       id: input.id
     });
+    const matched = channelMatchesEvent(channel, event);
+    return {
+      channelId: channel.id,
+      matched,
+      event,
+      filters: channel.filters,
+      reason: matched ? undefined : channel.enabled ? "event did not match channel filters" : "channel is disabled"
+    };
+  }
+  async testChannel(id, input = {}, options = {}) {
+    const channel = await this.store.getChannel(id);
+    if (!channel)
+      throw new Error(`Channel not found: ${id}`);
+    const match = await this.matchChannel(id, input);
+    const event = match.event;
+    if (options.honorFilters && !match.matched) {
+      const timestamp = new Date().toISOString();
+      const result2 = createDeliveryResult(event, channel, [{
+        attempt: 1,
+        status: "skipped",
+        startedAt: timestamp,
+        completedAt: timestamp,
+        error: match.reason
+      }]);
+      result2.metadata = { reason: "filter_mismatch" };
+      await this.store.appendDelivery(result2);
+      return result2;
+    }
     const eventForChannel = await this.applyRedaction(event, channel);
     const result = await this.deliverWithRetry(eventForChannel, channel);
     await this.store.appendDelivery(result);
@@ -558,7 +654,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.7",
+  "version": "0.1.9",
   "description": "Shared event envelopes, local subscriptions, and webhook delivery for Hasna open-source apps",
   "type": "module",
   "main": "./dist/index.js",