@nwire/cli 0.7.1 → 0.8.0

package/README.md

@@ -1,36 +1,78 @@
 # @nwire/cli
 
-> The `nwire` umbrella CLI — `dev`, `run`, `cache`, `studio`, `call`, `please`, `ls`, `infra`, …
+> The `nwire` umbrella CLI — `dev`, `run`, `cache`, `studio`, `please`, `ls`, `trace`, `watch`, `replay`, `infra`, …
 
-## What it does
-
-Built on citty: one root command per file under `commands/`. Long-lived processes (`dev`, `run`, `studio`) go through `@nwire/kernel`; build/quality passthroughs (`fmt`, `lint`, `check`) shell out. Reads `nwire.config.ts` (or falls back to convention) to locate the consumer's apps registry and `.nwire/` cache.
-
-## Install
+Built on citty: one root command per file under `commands/`. Long-lived
+processes (`dev`, `run`, `studio`) go through `@nwire/kernel`;
+build/quality passthroughs (`fmt`, `lint`, `check`, `test`) shell out.
+Reads `nwire.config.ts` (or falls back to convention) to locate the
+consumer's apps registry and the `.nwire/` cache.
 
 ```bash
 pnpm add -D @nwire/cli
 ```
 
-After install the `nwire` binary is on your `node_modules/.bin`. With `pnpm dlx` (or aliased globally) you can run anywhere.
+After install the `nwire` binary is on `node_modules/.bin`.
 
-## Quick start
+## Commands
 
 ```bash
-nwire dev # boot every app in the registry, hot-reload
-nwire run learnflow-api # boot one wire
-nwire cache # rebuild.nwire/*.json from source
-nwire studio # open Studio against the cache + live runtime
-nwire please <action> # dispatch an action from the command line
-nwire ls # list actions / events / actors per app
-nwire infra up # docker-compose up (postgres/redis/mongo/mailhog/logto/minio)
+# Run / develop
+nwire dev              # boot every app in the registry, hot-reload
+nwire run <wire>       # boot one wire
+nwire ps               # list running processes
+nwire logs <wire>      # tail logs
+
+# Static + dynamic introspection
+nwire cache            # rebuild .nwire/*.json from source
+nwire ls               # list actions / events / actors per app
+nwire studio           # open Studio against the cache + live runtime
+
+# Live observability (hooks + events)
+nwire trace [--correlation <id>] [--limit N]
+                       # tail event stream from a running wire; with --correlation
+                       # renders the causation tree.
+nwire watch <hook> [--limit N]
+                       # tail hook-step telemetry. Supports wildcards:
+                       # `nwire watch plugin.boot:*`
+nwire replay --file <recording.json> [--hook <name>]
+                       # replay a recorded hook run against the live wire,
+                       # or print an offline trace.
+
+# Operator
+nwire please <action> [--<arg> <value> ...]
+                       # dispatch an action / query / defineCommand
+
+# Quality + build
+nwire fmt / nwire lint / nwire check / nwire test / nwire build
+
+# Misc
+nwire infra up         # docker-compose up (postgres/redis/mongo/mailhog/logto/minio)
+nwire doctor           # environment + config sanity check
 ```
 
-## API surface
+Running `nwire` with no args prints a greeting + the command list.
+
+## Surface
+
+| Export                          | Role                                                         |
+| ------------------------------- | ------------------------------------------------------------ |
+| `nwire` binary                  | One subcommand per file under `src/commands/`.               |
+| `loadConfig(cwd)`               | Programmatic config loader.                                  |
+| `resolveAppsEntry(cwd, config)` | Locate the apps registry from convention or config.          |
+
+Adding a command: write `src/commands/<name>.ts` with citty's
+`defineCommand`, register it in `src/cli.ts`. To make it reachable
+from Studio + MCP, register a kernel router handler too.
+
+## Related
 
-- `nwire` CLI binary (one subcommand per file).
-- `loadConfig(cwd)` / `resolveAppsEntry(cwd, config)` — programmatic entry resolution.
+- `@nwire/kernel` — host for long-lived processes; the CLI delegates `dev`/`run`/`studio` to it.
+- `@nwire/scan` — `nwire cache` writes `.nwire/*.json` via this package.
+- `@nwire/please` — `nwire please` delegates here.
+- `@nwire/mcp` — same kernel router exposed to AI clients over stdio.
+- `@nwire/studio` — `nwire studio` boots the Vite dev server for it.
 
-## When to use
+## Status
 
-Every Nwire project after `pnpm install`. Fits every level.
+v0.x — command surface is additive. `trace` / `watch` / `replay` operate on the runtime's `/__nwire/*` HTTP+SSE endpoints; offline modes fall back to `.nwire/` cache where possible.

package/dist/__tests__/bench.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bench.test.d.ts.map

package/dist/__tests__/bench.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bench.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/bench.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/bench.test.js

@@ -0,0 +1,94 @@
+/**
+ * Unit tests for `nwire bench`.
+ *
+ * The command shells out to a real `k6` binary at runtime, so we don't
+ * exercise the full execution path here. We do test the pieces that
+ * deserve assertions:
+ *
+ *   - scenario path resolution (walks up from CWD and finds the right file)
+ *   - the k6 argv builder (env flags + script tail)
+ *   - the command meta + arg shape
+ */
+import { describe, it, expect, afterEach, beforeEach } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { benchCommand, buildK6Args, resolveScenarioPath, } from "../commands/bench.js";
+let target;
+beforeEach(() => {
+    target = mkdtempSync(join(tmpdir(), "bench-test-"));
+});
+afterEach(() => {
+    if (target)
+        rmSync(target, { recursive: true, force: true });
+});
+describe("nwire bench — command meta", () => {
+    it("registers a `bench` subcommand with the expected flags", () => {
+        const meta = benchCommand.meta;
+        expect(meta.name).toBe("bench");
+        expect(benchCommand.args).toMatchObject({
+            scenario: expect.any(Object),
+            vus: expect.any(Object),
+            duration: expect.any(Object),
+            ramp: expect.any(Object),
+            "base-url": expect.any(Object),
+            out: expect.any(Object),
+        });
+    });
+});
+describe("resolveScenarioPath", () => {
+    it("returns null when no scripts/k6 folder exists anywhere in the walk", () => {
+        expect(resolveScenarioPath("action", target, [target])).toBeNull();
+    });
+    it("finds a script when scripts/k6/<file> exists in CWD", () => {
+        mkdirSync(join(target, "scripts", "k6"), { recursive: true });
+        writeFileSync(join(target, "scripts", "k6", "action-dispatch.js"), "// stub\n");
+        const found = resolveScenarioPath("action", target, [target]);
+        expect(found).toBe(join(target, "scripts", "k6", "action-dispatch.js"));
+    });
+    it("walks up from a root to find the framework's scripts/k6", () => {
+        mkdirSync(join(target, "scripts", "k6"), { recursive: true });
+        writeFileSync(join(target, "scripts", "k6", "mixed-workload.js"), "// stub\n");
+        mkdirSync(join(target, "nested", "deeper"), { recursive: true });
+        const found = resolveScenarioPath("mixed", target, [join(target, "nested", "deeper")]);
+        expect(found).toBe(join(target, "scripts", "k6", "mixed-workload.js"));
+    });
+});
+describe("buildK6Args", () => {
+    it("emits run + env vars + script path", () => {
+        const argv = buildK6Args({
+            script: "/path/to/action-dispatch.js",
+            args: {
+                scenario: "action",
+                vus: 50,
+                duration: "30s",
+                ramp: "10s",
+                baseUrl: "http://localhost:3030",
+            },
+        });
+        expect(argv[0]).toBe("run");
+        expect(argv).toContain("-e");
+        expect(argv).toContain("VUS=50");
+        expect(argv).toContain("DURATION=30s");
+        expect(argv).toContain("RAMP=10s");
+        expect(argv).toContain("BASE_URL=http://localhost:3030");
+        expect(argv[argv.length - 1]).toBe("/path/to/action-dispatch.js");
+    });
+    it("inserts --summary-export when a summaryOut path is provided", () => {
+        const argv = buildK6Args({
+            script: "/x.js",
+            args: {
+                scenario: "read",
+                vus: 1,
+                duration: "1s",
+                ramp: "1s",
+                baseUrl: "http://localhost:1",
+            },
+            summaryOut: "/tmp/read.json",
+        });
+        expect(argv).toContain("--summary-export");
+        const i = argv.indexOf("--summary-export");
+        expect(argv[i + 1]).toBe("/tmp/read.json");
+    });
+});
+//# sourceMappingURL=bench.test.js.map

package/dist/__tests__/bench.test.js.map

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

package/dist/__tests__/replay.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=replay.test.d.ts.map

package/dist/__tests__/replay.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/replay.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/replay.test.js

@@ -0,0 +1,202 @@
+/**
+ * Unit tests for `nwire replay`.
+ *
+ * Same shape as `trace.test.ts`: we don't drive the full citty command
+ * end-to-end (it calls `process.exit`), we exercise the composable parts:
+ *
+ *   • command meta + arg shape
+ *   • loadRecording() against real fixture files
+ *   • postReplay() happy path against a stubbed wire
+ *   • postReplay() returns null when wire answers 404 / 501 (graceful fallback)
+ *   • renderOfflineDiff() output (offline fallback)
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { createServer } from "node:http";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { replayCommand, loadRecording, postReplay, renderOfflineDiff, renderReplayResult, } from "../commands/replay.js";
+let server;
+let tmp;
+afterEach(async () => {
+    if (server) {
+        await new Promise((res) => server.close(() => res()));
+        server = undefined;
+    }
+    if (tmp) {
+        rmSync(tmp, { recursive: true, force: true });
+        tmp = undefined;
+    }
+});
+function fixtureRecording() {
+    return {
+        hookId: "h_test",
+        hookName: "submission.submit",
+        runId: "r_1",
+        outcome: "completed",
+        steps: [
+            {
+                hookName: "submission.submit",
+                hookId: "h_test",
+                runId: "r_1",
+                stepId: 0,
+                stepKind: "chain",
+                stepName: "validate",
+                phase: "start",
+                ts: 0,
+            },
+            {
+                hookName: "submission.submit",
+                hookId: "h_test",
+                runId: "r_1",
+                stepId: 0,
+                stepKind: "chain",
+                stepName: "validate",
+                phase: "end",
+                ts: 1,
+                durationMs: 1,
+            },
+        ],
+        ctxIn: { studentId: "s1" },
+        ctxOut: { studentId: "s1", validated: true },
+        capturedAt: "2026-05-29T10:00:00.000Z",
+    };
+}
+function writeFixture(rec) {
+    tmp = mkdtempSync(join(tmpdir(), "replay-test-"));
+    const path = join(tmp, "rec.json");
+    writeFileSync(path, JSON.stringify(rec));
+    return path;
+}
+describe("nwire replay — command meta", () => {
+    it("registers a `replay` subcommand with a positional file + optional --hook", () => {
+        expect(replayCommand.meta).toBeDefined();
+        const meta = replayCommand.meta;
+        expect(meta.name).toBe("replay");
+        const args = replayCommand.args;
+        expect(args.file).toMatchObject({ type: "positional", required: true });
+        expect(args.hook).toMatchObject({ type: "string" });
+    });
+});
+describe("loadRecording", () => {
+    it("loads + parses a recording JSON file", () => {
+        const rec = fixtureRecording();
+        const path = writeFixture(rec);
+        const out = loadRecording(path);
+        expect(out.hookName).toBe("submission.submit");
+        expect(out.steps).toHaveLength(2);
+    });
+    it("rejects a file whose shape doesn't look like a Recording", () => {
+        tmp = mkdtempSync(join(tmpdir(), "replay-test-"));
+        const path = join(tmp, "bad.json");
+        writeFileSync(path, JSON.stringify({ hello: "world" }));
+        expect(() => loadRecording(path)).toThrow(/not a Recording/);
+    });
+});
+describe("postReplay — happy path against a stubbed wire", () => {
+    it("POSTs the recording and parses the wire response", async () => {
+        const rec = fixtureRecording();
+        server = createServer((req, res) => {
+            if (req.method === "POST" && req.url === "/_nwire/hooks/replay") {
+                const chunks = [];
+                req.on("data", (c) => chunks.push(c));
+                req.on("end", () => {
+                    const body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+                    expect(body.recording.hookName).toBe("submission.submit");
+                    res.writeHead(200, { "content-type": "application/json" });
+                    res.end(JSON.stringify({
+                        matches: true,
+                        drift: [],
+                        recorded: body.recording,
+                        replayed: { stepCount: 2, outcome: "completed" },
+                    }));
+                });
+                return;
+            }
+            res.writeHead(404);
+            res.end();
+        });
+        await new Promise((res) => server.listen(0, "127.0.0.1", res));
+        const port = server.address().port;
+        const result = await postReplay({
+            url: `http://127.0.0.1:${port}`,
+            recording: rec,
+        });
+        expect(result).not.toBeNull();
+        expect(result.matches).toBe(true);
+        expect(result.replayed.stepCount).toBe(2);
+    });
+});
+describe("postReplay — graceful fallback when endpoint is missing", () => {
+    it("returns null on 404 (no /_nwire/hooks/replay mount)", async () => {
+        server = createServer((_req, res) => {
+            res.writeHead(404);
+            res.end();
+        });
+        await new Promise((res) => server.listen(0, "127.0.0.1", res));
+        const port = server.address().port;
+        const result = await postReplay({
+            url: `http://127.0.0.1:${port}`,
+            recording: fixtureRecording(),
+        });
+        expect(result).toBeNull();
+    });
+    it("returns null on 501 Not Implemented", async () => {
+        server = createServer((_req, res) => {
+            res.writeHead(501);
+            res.end();
+        });
+        await new Promise((res) => server.listen(0, "127.0.0.1", res));
+        const port = server.address().port;
+        const result = await postReplay({
+            url: `http://127.0.0.1:${port}`,
+            recording: fixtureRecording(),
+        });
+        expect(result).toBeNull();
+    });
+    it("throws on other non-OK statuses (5xx that isn't 501)", async () => {
+        server = createServer((_req, res) => {
+            res.writeHead(500);
+            res.end("boom");
+        });
+        await new Promise((res) => server.listen(0, "127.0.0.1", res));
+        const port = server.address().port;
+        await expect(postReplay({ url: `http://127.0.0.1:${port}`, recording: fixtureRecording() })).rejects.toThrow(/500/);
+    });
+});
+describe("renderOfflineDiff", () => {
+    it("includes the offline-only banner + the step trace", () => {
+        const out = renderOfflineDiff(fixtureRecording());
+        expect(out).toContain("/_nwire/hooks/replay");
+        expect(out).toContain("offline-only");
+        expect(out).toContain("submission.submit");
+        expect(out).toContain("validate");
+        expect(out).toContain("outcome=completed");
+    });
+});
+describe("renderReplayResult", () => {
+    it("prints the match banner + step alignment", () => {
+        const rec = fixtureRecording();
+        const out = renderReplayResult({
+            matches: true,
+            drift: [],
+            recorded: rec,
+            replayed: { stepCount: rec.steps.length, outcome: "completed" },
+        });
+        expect(out).toContain("matches");
+        expect(out).toContain("validate");
+    });
+    it("surfaces drift entries when matches=false", () => {
+        const rec = fixtureRecording();
+        const out = renderReplayResult({
+            matches: false,
+            drift: ["step[1]: recorded=chain/validate/end replayed=chain/validate/error"],
+            recorded: rec,
+            replayed: { stepCount: 2, outcome: "failed" },
+        });
+        expect(out).toContain("drift");
+        expect(out).toContain("validate/error");
+        expect(out).toContain("outcome=failed");
+    });
+});
+//# sourceMappingURL=replay.test.js.map

package/dist/__tests__/replay.test.js.map

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

package/dist/__tests__/trace.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=trace.test.d.ts.map

package/dist/__tests__/trace.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/trace.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/trace.test.js

@@ -0,0 +1,136 @@
+/**
+ * Unit tests for `nwire trace`.
+ *
+ * Long-running stream behaviour is intentionally NOT exercised end-to-end
+ * (timing-flakey). We test the small composable pieces: command meta,
+ * wire discovery against a real loopback HTTP server, the SSE parser,
+ * and the line/tree formatters.
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { createServer } from "node:http";
+import { traceCommand, formatSummaryLine, renderTree, shortId, formatTimestamp } from "../commands/trace.js";
+import { SseParser } from "../lib/sse.js";
+import { findWireUrl } from "../lib/wire-discovery.js";
+let server;
+afterEach(async () => {
+    if (server) {
+        await new Promise((res) => server.close(() => res()));
+        server = undefined;
+    }
+    delete process.env.NWIRE_INSPECT_URL;
+});
+describe("nwire trace — command meta", () => {
+    it("registers a `trace` subcommand with optional --correlation and --limit", () => {
+        expect(traceCommand.meta).toBeDefined();
+        const meta = traceCommand.meta;
+        expect(meta.name).toBe("trace");
+        expect(traceCommand.args).toMatchObject({
+            correlation: expect.any(Object),
+            limit: expect.any(Object),
+        });
+    });
+});
+describe("findWireUrl — port-probe discovery", () => {
+    it("returns the URL of a stubbed HTTP server that answers /_nwire/events/recent", async () => {
+        server = createServer((req, res) => {
+            if (req.url?.startsWith("/_nwire/events/recent")) {
+                res.writeHead(200, { "content-type": "application/json" });
+                res.end("[]");
+                return;
+            }
+            res.writeHead(404);
+            res.end();
+        });
+        await new Promise((res) => server.listen(0, "127.0.0.1", res));
+        const port = server.address().port;
+        process.env.NWIRE_INSPECT_URL = `http://127.0.0.1:${port}`;
+        const url = await findWireUrl();
+        expect(url).toBe(`http://127.0.0.1:${port}`);
+    });
+    it("strips a trailing slash from NWIRE_INSPECT_URL", async () => {
+        process.env.NWIRE_INSPECT_URL = "http://127.0.0.1:9999/";
+        expect(await findWireUrl()).toBe("http://127.0.0.1:9999");
+    });
+});
+describe("SseParser — frame extraction", () => {
+    it("parses a single complete frame", () => {
+        const parser = new SseParser();
+        const out = parser.feed(`data: {"a":1}\n\n`);
+        expect(out).toEqual([{ a: 1 }]);
+    });
+    it("parses multiple frames in one feed call", () => {
+        const parser = new SseParser();
+        const out = parser.feed(`data: {"a":1}\n\ndata: {"b":2}\n\ndata: {"c":3}\n\n`);
+        expect(out).toEqual([{ a: 1 }, { b: 2 }, { c: 3 }]);
+    });
+    it("buffers a partial frame across two feed calls", () => {
+        const parser = new SseParser();
+        expect(parser.feed(`data: {"a":`)).toEqual([]);
+        expect(parser.feed(`1}\n\n`)).toEqual([{ a: 1 }]);
+    });
+    it("ignores SSE comment / heartbeat frames", () => {
+        const parser = new SseParser();
+        const out = parser.feed(`: heartbeat\n\ndata: {"k":"v"}\n\n`);
+        expect(out).toEqual([{ k: "v" }]);
+    });
+    it("joins multi-line data: payloads with newline", () => {
+        const parser = new SseParser();
+        const out = parser.feed(`data: {"a":\ndata: 1}\n\n`);
+        expect(out).toEqual([{ a: 1 }]);
+    });
+    it("tolerates \\r\\n line endings", () => {
+        const parser = new SseParser();
+        const out = parser.feed(`data: {"a":1}\r\n\r\n`);
+        expect(out).toEqual([{ a: 1 }]);
+    });
+    it("drops frames whose JSON is malformed", () => {
+        const parser = new SseParser();
+        expect(parser.feed(`data: {not-json}\n\n`)).toEqual([]);
+    });
+});
+describe("trace — formatters", () => {
+    it("formatTimestamp pads to HH:MM:SS.mmm", () => {
+        const ts = formatTimestamp("2026-05-29T10:05:03.040Z");
+        expect(ts).toMatch(/^\d{2}:\d{2}:\d{2}\.\d{3}$/);
+    });
+    it("shortId returns 8 chars (strips known prefixes)", () => {
+        expect(shortId("evt_abc12345678")).toBe("12345678");
+        expect(shortId(undefined)).toBe("--------");
+    });
+    it("formatSummaryLine includes the event name", () => {
+        const line = formatSummaryLine({
+            name: "Submission.Submitted",
+            envelope: {
+                messageId: "m_abcdefgh",
+                causationId: "c_zyxwvuts",
+                correlationId: "k_corrcorr",
+                occurredAt: "2026-05-29T10:00:00.000Z",
+            },
+        });
+        // strip ANSI for readability — picocolors emits codes only when stdout is a TTY,
+        // so under vitest most colours are dropped already.
+        expect(line).toContain("Submission.Submitted");
+        expect(line).toMatch(/\d{2}:\d{2}:\d{2}\.\d{3}/);
+    });
+    it("renderTree nests children under their causation parent", () => {
+        const tree = renderTree([
+            { name: "Root", envelope: { messageId: "ROOT" } },
+            { name: "ChildA", envelope: { messageId: "A", causationId: "ROOT" } },
+            { name: "ChildB", envelope: { messageId: "B", causationId: "ROOT" } },
+            { name: "GrandA", envelope: { messageId: "GA", causationId: "A" } },
+        ]);
+        expect(tree).toContain("Root");
+        expect(tree).toContain("ChildA");
+        expect(tree).toContain("ChildB");
+        expect(tree).toContain("GrandA");
+        // ChildA appears before GrandA in the output (parent before child)
+        expect(tree.indexOf("ChildA")).toBeLessThan(tree.indexOf("GrandA"));
+    });
+    it("renderTree treats orphans as additional roots", () => {
+        const tree = renderTree([
+            { name: "Orphan", envelope: { messageId: "X", causationId: "missing-parent" } },
+        ]);
+        expect(tree).toContain("Orphan");
+    });
+});
+//# sourceMappingURL=trace.test.js.map

package/dist/__tests__/trace.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.test.js","sourceRoot":"","sources":["../../src/__tests__/trace.test.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACzD,OAAO,EAAE,YAAY,EAAe,MAAM,WAAW,CAAC;AAGtD,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC1G,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEpD,IAAI,MAA0B,CAAC;AAE/B,SAAS,CAAC,KAAK,IAAI,EAAE;IACnB,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,IAAI,OAAO,CAAO,CAAC,GAAG,EAAE,EAAE,CAAC,MAAO,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAC7D,MAAM,GAAG,SAAS,CAAC;IACrB,CAAC;IACD,OAAO,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;AACvC,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,4BAA4B,EAAE,GAAG,EAAE;IAC1C,EAAE,CAAC,wEAAwE,EAAE,GAAG,EAAE;QAChF,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;QACxC,MAAM,IAAI,GAAG,YAAY,CAAC,IAAyB,CAAC;QACpD,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAChC,MAAM,CAAE,YAAmD,CAAC,IAAI,CAAC,CAAC,aAAa,CAAC;YAC9E,WAAW,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;YAC/B,KAAK,EAAQ,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;SAChC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,oCAAoC,EAAE,GAAG,EAAE;IAClD,EAAE,CAAC,6EAA6E,EAAE,KAAK,IAAI,EAAE;QAC3F,MAAM,GAAG,YAAY,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;YACjC,IAAI,GAAG,CAAC,GAAG,EAAE,UAAU,CAAC,uBAAuB,CAAC,EAAE,CAAC;gBACjD,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC;gBAC3D,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBACd,OAAO;YACT,CAAC;YACD,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;YACnB,GAAG,CAAC,GAAG,EAAE,CAAC;QACZ,CAAC,CAAC,CAAC;QACH,MAAM,IAAI,OAAO,CAAO,CAAC,GAAG,EAAE,EAAE,CAAC,MAAO,CAAC,MAAM,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC;QACtE,MAAM,IAAI,GAAI,MAAM,CAAC,OAAO,EAAkB,CAAC,IAAI,CAAC;QACpD,OAAO,CAAC,GAAG,CAAC,iBAAiB,GAAG,oBAAoB,IAAI,EAAE,CAAC;QAC3D,MAAM,GAAG,GAAG,MAAM,WAAW,EAAE,CAAC;QAChC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,oBAAoB,IAAI,EAAE,CAAC,CAAC;IAC/C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gDAAgD,EAAE,KAAK,IAAI,EAAE;QAC9D,OAAO,CAAC,GAAG,CAAC,iBAAiB,GAAG,wBAAwB,CAAC;QACzD,MAAM,CAAC,MAAM,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,8BAA8B,EAAE,GAAG,EAAE;IAC5C,EAAE,CAAC,gCAAgC,EAAE,GAAG,EAAE;QACxC,MAAM,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;QAC7C,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yCAAyC,EAAE,GAAG,EAAE;QACjD,MAAM,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,qDAAqD,CAAC,CAAC;QAC/E,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACtD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+CAA+C,EAAE,GAAG,EAAE;QACvD,MAAM,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;QAC/B,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC/C,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wCAAwC,EAAE,GAAG,EAAE;QAChD,MAAM,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,oCAAoC,CAAC,CAAC;QAC9D,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8CAA8C,EAAE,GAAG,EAAE;QACtD,MAAM,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;QACrD,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;QACjD,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,MAAM,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;QAC/B,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC1D,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,oBAAoB,EAAE,GAAG,EAAE;IAClC,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,MAAM,EAAE,GAAG,eAAe,CAAC,0BAA0B,CAAC,CAAC;QACvD,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,4BAA4B,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACzD,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACpD,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2CAA2C,EAAE,GAAG,EAAE;QACnD,MAAM,IAAI,GAAG,iBAAiB,CAAC;YAC7B,IAAI,EAAM,sBAAsB;YAChC,QAAQ,EAAE;gBACR,SAAS,EAAM,YAAY;gBAC3B,WAAW,EAAI,YAAY;gBAC3B,aAAa,EAAE,YAAY;gBAC3B,UAAU,EAAK,0BAA0B;aAC1C;SACF,CAAC,CAAC;QACH,iFAAiF;QACjF,oDAAoD;QACpD,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,sBAAsB,CAAC,CAAC;QAC/C,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,0BAA0B,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wDAAwD,EAAE,GAAG,EAAE;QAChE,MAAM,IAAI,GAAG,UAAU,CAAC;YACtB,EAAE,IAAI,EAAE,MAAM,EAAI,QAAQ,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE;YACnD,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE;YACrE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE;YACrE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,EAAE;SACpE,CAAC,CAAC;QACH,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAC/B,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACjC,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACjC,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACjC,mEAAmE;QACnE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IACtE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+CAA+C,EAAE,GAAG,EAAE;QACvD,MAAM,IAAI,GAAG,UAAU,CAAC;YACtB,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,EAAE,gBAAgB,EAAE,EAAE;SAChF,CAAC,CAAC;QACH,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/watch.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=watch.test.d.ts.map

package/dist/__tests__/watch.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/watch.test.ts"],"names":[],"mappings":""}