// Generated from types/*.ts — do not edit.
// Regenerate with: npm run generate:typescript

/**
 * Resource-Watch Channel Commands — `createResourceWatch`.
 *
 * @module channels-resource-watch/commands
 */

import type { URI } from '../common/state.js';
import type { BaseParams } from '../common/commands.js';

// ─── createResourceWatch ─────────────────────────────────────────────────────

/**
 * Creates a resource watcher on the receiver's filesystem.
 *
 * The receiver allocates an `ahp-resource-watch:/<id>` channel URI and
 * returns it on {@link CreateResourceWatchResult.channel}. The caller then
 * [`subscribe`](/specification/subscriptions#subscribe-request)s to that channel to receive
 * `resourceWatch/changed` actions over the standard action envelope.
 *
 * The watch lifecycle is tied to subscription: when every subscriber has
 * unsubscribed (or the underlying connection drops), the receiver MUST
 * release the watcher. There is no explicit dispose command — `unsubscribe`
 * is the only handle the caller needs.
 *
 * Like the rest of the `resource*` family, `createResourceWatch` is
 * symmetrical and MAY be sent in either direction. Access is gated through
 * the same permission flow as `resourceRead`/`resourceWrite`.
 *
 * @category Commands
 * @method createResourceWatch
 * @direction Client ↔ Server
 * @messageType Request
 * @version 1
 * @throws `NotFound` (`-32008`) if `uri` does not exist.
 * @throws `PermissionDenied` (`-32009`) if the caller is not permitted to watch the URI.
 * @example
 * ```jsonc
 * // Client → Server
 * { "jsonrpc": "2.0", "id": 30, "method": "createResourceWatch",
 *   "params": {
 *     "channel": "ahp-root://",
 *     "uri": "file:///workspace",
 *     "recursive": true,
 *     "excludes": { "items": ["**\u002f.git/**", "**\u002fnode_modules/**"] }
 *   } }
 *
 * // Server → Client
 * { "jsonrpc": "2.0", "id": 30, "result": {
 *   "channel": "ahp-resource-watch:/d3a9f1e0-…"
 * } }
 * ```
 */
export interface CreateResourceWatchParams extends BaseParams {
  channel: 'ahp-root://';
  /** URI to watch. */
  uri: URI;
  /**
   * If `true`, the receiver MUST report changes for descendants of `uri`.
   * If `false` (default), only changes to `uri` itself — and, when `uri`
   * is a directory, its direct children — are reported.
   */
  recursive?: boolean;
  /**
   * Glob patterns or paths relative to `uri` to exclude from reporting.
   * Wrapped in `{ items }` for forward compatibility.
   */
  excludes?: { items: string[] };
  /**
   * Glob patterns or paths relative to `uri` to restrict reporting to.
   * Omit to report every change under `uri` subject to `excludes`.
   * Wrapped in `{ items }` for forward compatibility.
   */
  includes?: { items: string[] };
}

/**
 * Result of the `createResourceWatch` command.
 */
export interface CreateResourceWatchResult {
  /**
   * Receiver-assigned watch channel URI (`ahp-resource-watch:/<id>`). The
   * caller subscribes to this URI to start receiving change events and
   * unsubscribes to release the watcher.
   */
  channel: URI;
}