pyric 0.0.1 → 0.1.0-alpha.10

package/dist/rules/test/spec.d.ts.map

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

package/dist/rules/test/spec.js

@@ -0,0 +1,327 @@
+import { z } from 'zod';
+// ---- Canonical shared primitives ----
+/**
+ * THE Firestore rules method union — the one canonical declaration.
+ * Everything that talks about per-method access (the simulator's
+ * `TestCase`, the playground's workspace-test runner, the app-spec
+ * access matrix) imports this; nothing redeclares it.
+ *
+ * Note: this is the RULES vocabulary (`request.method`). Data-plane
+ * vocabularies that include `set` (sandbox `RequestEvent`, traffic
+ * types) are deliberately distinct — `set` lowers to create/update at
+ * rules-evaluation time.
+ */
+export const FIRESTORE_METHODS = ['get', 'list', 'create', 'update', 'delete'];
+/**
+ * THE test-identity shape — a signed-in principal for a rules check.
+ * Custom claims live under `token` and read as
+ * `request.auth.token.<name>` in rules. `null` at usage sites means
+ * unauthenticated; the shape itself is always a signed-in identity.
+ */
+export const TestIdentitySchema = z.object({
+    uid: z.string(),
+    token: z.record(z.unknown()).optional(),
+});
+// ---- Simplified agent-friendly types ----
+export const FunctionMockSchema = z.object({
+    function: z.enum(['get', 'exists']).describe('Firestore function to mock'),
+    path: z.string().describe('Document path, e.g. "users/alice"'),
+    result: z.union([z.record(z.unknown()), z.boolean()]).describe('Document data for get, boolean for exists'),
+});
+/**
+ * Item 0.D / Item 7 — typed write-mode discriminator.
+ *
+ * Without this, an `update` test had to pre-merge its payload into the
+ * post-state by hand (because the simulator just used `tc.data` as the
+ * after-state). That works for shallow updates, but for nested-map
+ * updates and dot-path updates it silently produces the wrong shape —
+ * which then makes `request.resource.data.x.y` and `getAfter()` lie.
+ *
+ * The four modes mirror what the Firestore admin SDK actually emits:
+ *   create               → write fails if doc exists; after = payload
+ *   set { merge: false } → full replace; pre-state irrelevant
+ *   set { merge: true }  → recursive merge of pre-state and payload
+ *   update               → top-level keys replace; dot-paths patch nested maps
+ *
+ * `writeMode` is optional. When omitted, the simulator falls back to the
+ * legacy "tc.data IS the full after-state" behavior, which keeps every
+ * existing test passing. New tests SHOULD set writeMode whenever the
+ * rule reads nested maps or calls getAfter()/existsAfter().
+ */
+export const WriteModeSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('create') }),
+    z.object({ kind: z.literal('set'), merge: z.boolean() }),
+    z.object({ kind: z.literal('update') }),
+    z.object({ kind: z.literal('delete') }),
+]);
+/**
+ * Shape of `request.query` — only populated for `list` operations
+ * (REBUILD_PLAN.md Item 6 follow-up). Production exposes:
+ *   - limit:   the requested page size
+ *   - offset:  the start offset within the result set
+ *   - orderBy: the orderBy clause as a string (field name with optional direction)
+ *
+ * Unset fields read as `null` from rules. Tests SHOULD set this whenever the
+ * rule under evaluation references `request.query.<x>`; otherwise the field
+ * read returns null and the rule may silently DENY.
+ */
+export const ListQuerySchema = z.object({
+    limit: z.number().optional(),
+    offset: z.number().optional(),
+    orderBy: z.string().optional(),
+});
+export const TestCaseSchema = z.object({
+    description: z.string().describe('Human-readable description of what this test verifies'),
+    expectation: z.enum(['ALLOW', 'DENY']).describe('Expected outcome'),
+    method: z.enum(FIRESTORE_METHODS).describe('Firestore method to test'),
+    path: z.string().describe('Document path, e.g. "users/alice"'),
+    auth: z.union([TestIdentitySchema, z.null()]).optional().describe('Auth context; null or omitted for unauthenticated'),
+    data: z.record(z.unknown()).optional().describe('request.resource.data for write operations'),
+    resource: z.record(z.unknown()).optional().describe('Existing document data (resource.data)'),
+    functionMocks: z.array(FunctionMockSchema).optional().describe('Mock get()/exists() calls in rules'),
+    /**
+     * Optional `request.query` payload for `list` operations only. Populating
+     * this is the only way to satisfy rules that read `request.query.limit /
+     * .offset / .orderBy` — without it, the field read returns null and a
+     * naive `request.query.limit < 100` evaluates as `null < 100 → false → DENY`.
+     * Ignored for non-list methods.
+     */
+    query: ListQuerySchema.optional().describe('request.query payload (list ops only): limit/offset/orderBy.'),
+    /**
+     * Override for `request.time` (REBUILD_PLAN.md Item 0.F). ISO-8601 string.
+     * Defaults to wallclock when omitted — but date-gated rules then evaluate
+     * non-deterministically across CI runs. Set this whenever the rule under
+     * test references `request.time`.
+     */
+    requestTime: z.string().optional().describe('Override for request.time (ISO-8601). Defaults to wallclock.'),
+    /**
+     * Optional explicit write semantics (REBUILD_PLAN.md Item 0.D / Item 7).
+     * When set, the simulator runs `projectAfterState(writeMode, resource, data)`
+     * to derive both `request.resource.data` AND the value `getAfter(path)`
+     * returns. When omitted, the simulator preserves legacy behavior:
+     * `tc.data` IS the after-state.
+     */
+    writeMode: WriteModeSchema.optional().describe('Optional write-mode override; controls update merge semantics and getAfter() projection.'),
+});
+/**
+ * Project the DECIDING rule from a simulated {@link TestResult}.
+ *
+ * For an ALLOW, picks the `ALLOW` trace entry (evaluation short-circuits on the
+ * first allowing rule, so it's unique). For a DENY, picks the rule the sandbox
+ * would report as responsible: the first `DENY`/`ERROR` entry, falling back to
+ * the last evaluated rule. Returns `undefined` when no rule was evaluated
+ * (implicit deny — no matching `allow`) or the simulator abstained
+ * (`UNSUPPORTED`). Never invents data: a missing line/trace stays absent.
+ */
+export function projectEvaluatedRule(result) {
+    if (result.decision === 'UNSUPPORTED')
+        return undefined;
+    const allowed = result.decision === 'ALLOW';
+    const deciding = allowed
+        ? result.trace.find((t) => t.verdict === 'ALLOW')
+        : (result.trace.find((t) => t.verdict === 'DENY' || t.verdict === 'ERROR') ??
+            result.trace[result.trace.length - 1]);
+    if (!deciding)
+        return undefined;
+    const info = { verdict: allowed ? 'allow' : 'deny' };
+    if (deciding.line !== undefined)
+        info.line = deciding.line;
+    if (deciding.conditionText !== undefined)
+        info.expression = deciding.conditionText;
+    if (deciding.expressionTrace !== undefined)
+        info.expressionTrace = deciding.expressionTrace;
+    return info.line !== undefined || info.expression !== undefined || info.expressionTrace !== undefined
+        ? info
+        : undefined;
+}
+export function renderLegacyDebugMessages(result) {
+    const out = [];
+    for (const note of result.notes)
+        out.push(note);
+    for (const entry of result.trace) {
+        const ops = entry.operations.join(',');
+        const head = `Rule #${entry.ruleIndex} (${ops})`;
+        if (entry.verdict === 'ALLOW') {
+            out.push(`${head} → ALLOW`);
+        }
+        else if (entry.verdict === 'DENY') {
+            out.push(`${head} → deny`);
+        }
+        else if (entry.verdict === 'UNSUPPORTED') {
+            out.push(`${head} → unsupported: ${entry.message ?? ''}`);
+        }
+        else {
+            out.push(`${head} → error: ${entry.message ?? ''}`);
+        }
+    }
+    out.push(`Simulated: ${result.decision}`);
+    return out;
+}
+// ---- Path normalization ----
+const DB_PREFIX = '/databases/(default)/documents/';
+export function normalizeDocPath(path) {
+    const clean = path.startsWith('/') ? path.slice(1) : path;
+    return `${DB_PREFIX}${clean}`;
+}
+export function buildApiTestCase(tc, opts = {}) {
+    const request = {
+        auth: tc.auth === null || tc.auth === undefined
+            ? undefined
+            : { uid: tc.auth.uid, token: tc.auth.token ?? {} },
+        // Firestore rules engine expects request.method as a short verb
+        // ('get' | 'list' | 'create' | 'update' | 'delete'). Sending the full
+        // gRPC method string (firestore.googleapis.com/.../GetDocument) makes
+        // the engine fail to map the request to any allow rule, so every
+        // ALLOW-expectation test case silently returns DENY. Discovered by
+        // the production-parity smoke test against the live Rules Test API.
+        method: tc.method,
+        path: normalizeDocPath(tc.path),
+    };
+    if (tc.data) {
+        request.resource = { data: tc.data };
+    }
+    if (tc.requestTime) {
+        request.time = tc.requestTime;
+    }
+    if (tc.query) {
+        request.query = tc.query;
+    }
+    const result = {
+        expectation: tc.expectation,
+        request,
+    };
+    if (opts.expressionReportLevel) {
+        result.expressionReportLevel = opts.expressionReportLevel;
+    }
+    if (tc.resource) {
+        result.resource = { data: tc.resource };
+    }
+    if (tc.functionMocks && tc.functionMocks.length > 0) {
+        result.functionMocks = tc.functionMocks.map(buildFunctionMock);
+    }
+    return result;
+}
+// ═══════════════════════════════════════════════════════════════
+// Storage rules test surface
+// ═══════════════════════════════════════════════════════════════
+//
+// Storage rules ride the SAME `projects.test` endpoint as Firestore
+// (live-confirmed against firebaserules.googleapis.com/v1/projects/<p>:test),
+// but the request shape is Storage-shaped, not Firestore-shaped:
+//   - the ruleset header is `service firebase.storage`
+//   - the path is a resource name `/b/{bucket}/o/{object}` (NOT the
+//     `/databases/(default)/documents/...` Firestore prefix)
+//   - `method` is a short verb (get/list/create/update/delete)
+//   - `resource` carries `size`/`contentType`/`metadata` directly, with no
+//     `.data` wrapper (production tolerates `size` as a string too)
+//   - cross-service function mocks use the QUALIFIED names `firestore.get` /
+//     `firestore.exists` (Firestore-internal mocks use the bare `get`/`exists`);
+//     and — same fix as `buildFunctionMock` — an `exists()` mock must send a
+//     bool `{ value: true/false }`, never a map, or the API rejects it and the
+//     mock silently resolves to DENY.
+//
+// These builders live BESIDE the Firestore ones and share nothing mutable with
+// them, so adding the Storage surface can't regress Firestore.
+/** The rules methods a Storage test case may exercise — short verbs only.
+ *  The coarse umbrellas (`read`/`write`) are a GRANT-side vocabulary; a
+ *  request is always one precise granular verb. */
+export const STORAGE_TEST_METHODS = ['get', 'list', 'create', 'update', 'delete'];
+/** Default bucket used when a case omits one. The bucket name is opaque to
+ *  the rules engine (matched by the `{bucket}` path param), so any stable
+ *  value works; keep it constant so observation paths are reproducible. */
+export const DEFAULT_STORAGE_BUCKET = 'demo-pyric.appspot.com';
+export const StorageFunctionMockSchema = z.object({
+    function: z.enum(['get', 'exists']).describe('Cross-service Firestore function to mock'),
+    path: z.string().describe('Firestore document path in collection/doc form, e.g. "users/alice"'),
+    result: z.union([z.record(z.unknown()), z.boolean()]).describe('Document fields for get, boolean for exists'),
+});
+/**
+ * Lift an object path to the Storage resource-name form the rules engine and
+ * the evaluator both match against: `/b/{bucket}/o/{object}`. A path that is
+ * already absolute has its leading slash stripped before the object segment so
+ * `"images/x"` and `"/images/x"` normalize identically.
+ */
+export function normalizeStoragePath(objectPath, bucket = DEFAULT_STORAGE_BUCKET) {
+    const clean = objectPath.startsWith('/') ? objectPath.slice(1) : objectPath;
+    return `/b/${bucket}/o/${clean}`;
+}
+/** Convert a {@link StorageTestCase} into the production Rules Test API wire
+ *  shape. Symmetric with {@link buildApiTestCase} for Firestore. */
+export function buildStorageApiTestCase(tc) {
+    const request = {
+        auth: tc.auth === null || tc.auth === undefined
+            ? undefined
+            : { uid: tc.auth.uid, token: tc.auth.token ?? {} },
+        // Short verb — same class of bug as Firestore's request.method: sending
+        // anything but get/list/create/update/delete makes the engine map the
+        // request to no allow rule, silently denying every ALLOW case.
+        method: tc.method,
+        path: normalizeStoragePath(tc.path, tc.bucket),
+    };
+    if (tc.resource)
+        request.resource = tc.resource;
+    if (tc.requestTime)
+        request.time = tc.requestTime;
+    const result = { expectation: tc.expectation, request };
+    if (tc.existingResource)
+        result.resource = tc.existingResource;
+    if (tc.functionMocks && tc.functionMocks.length > 0) {
+        result.functionMocks = tc.functionMocks.map(buildStorageFunctionMock);
+    }
+    return result;
+}
+/**
+ * Build a cross-service Firestore function mock for a Storage ruleset. Unlike
+ * the Firestore-internal {@link buildFunctionMock} (bare `get`/`exists`), a
+ * Storage rule reaching into Firestore names the function with its service
+ * QUALIFIER — `firestore.get` / `firestore.exists` — live-confirmed against the
+ * production endpoint. The `exists()` result is a bool `{ value }`, never the
+ * `{ value: { data } }` map shape (the same fix `buildFunctionMock` carries):
+ * a map there is rejected with a bool/map type error and silently denies.
+ */
+export function buildStorageFunctionMock(mock) {
+    const fnName = mock.function === 'get' ? 'firestore.get' : 'firestore.exists';
+    // The rule's path literal resolves to the full Firestore resource name
+    // (/databases/(default)/documents/<doc>); the mock's exactValue must match
+    // it. `normalizeDocPath` produces exactly that from the collection/doc form.
+    const normalizedPath = normalizeDocPath(mock.path);
+    const result = {
+        function: fnName,
+        args: [{ exactValue: normalizedPath }],
+        result: undefined,
+    };
+    if (mock.function === 'get') {
+        result.result = { value: { data: mock.result } };
+    }
+    else {
+        result.result = { value: mock.result === true };
+    }
+    return result;
+}
+export function buildFunctionMock(mock) {
+    // Function name must be the short verb ('get' | 'exists') — the same class
+    // of bug as request.method. The Rules Test API rejects 'firestore.get' /
+    // 'firestore.exists' as not matching any service-declared function, so the
+    // mock is ignored and the real get() returns null → rule denies.
+    const fnName = mock.function === 'get' ? 'get' : 'exists';
+    const normalizedPath = normalizeDocPath(mock.path);
+    const result = {
+        function: fnName,
+        args: [{ exactValue: normalizedPath }],
+        result: undefined,
+    };
+    if (mock.function === 'get') {
+        result.result = { value: { data: mock.result } };
+    }
+    else {
+        // exists() returns a bool, not a map. Sending the map shape used for
+        // get() here — { value: { data: {} } } / undefined — makes the
+        // production Rules Test API reject the mock with "Type error.
+        // Received: [map] Expected: [bool]", which silently resolves to DENY
+        // and poisons every observation that mocks exists() to true.
+        // Live-verified fix: emit a bool value directly.
+        result.result = { value: mock.result === true };
+    }
+    return result;
+}
+//# sourceMappingURL=spec.js.map

package/dist/rules/test/spec.js.map

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

package/dist/rules/tools.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Tool factories for `pyric/rules` per F1.
+ *
+ *   - `createFirestoreRulesTools()`: pure-local rules tooling
+ *     (lint, parse, resolve-modules, simulate) + the Rules Test API
+ *     client (test, takes ProjectScope).
+ *   - `createFirestoreSimulatorTools({ resolveSandbox })`: stateful
+ *     simulator tools — create, execute, read, batch, transaction,
+ *     undo, events. Tools operate against a session-scoped
+ *     LocalEnvironment resolved per dispatch.
+ *
+ * Per F2: identity is a value; lifecycle is a resolver. The
+ * `resolveSandbox` resolver returns the session's
+ * LocalEnvironment — handlers call it inside `execute` so reset /
+ * swap is transparent.
+ *
+ * Per F5: handlers are self-contained — only deps + args + ctx;
+ * no globals.
+ */
+import type { ToolHandler } from '@inbrowser/agent';
+import type { ProjectScope } from '../project-scope.js';
+import { type FirestoreSimulatorToolDeps as FirestoreSimulatorToolDepsImpl } from './simulator-tools-impl.js';
+export type FirestoreSimulatorToolDeps = Pick<FirestoreSimulatorToolDepsImpl, 'resolveSandbox'>;
+export interface FirestoreRulesToolDeps {
+    /** Optional ProjectScope for the test-rules tool (calls Google's
+     *  Firebase Rules Test API). When omitted, `firestore_test_rules`
+     *  is dropped from the factory's output. */
+    scope?: ProjectScope;
+}
+/**
+ * Pure-local Firestore rules tooling, plus the optional Rules Test
+ * API client when `scope` is supplied. Bundles:
+ *
+ *   - `firestore_lint_rules`
+ *   - `firestore_resolve_modules`
+ *   - `firestore_simulate_rules`
+ *   - `firestore_test_rules` (only when `scope` is supplied)
+ */
+export declare function createFirestoreRulesTools(deps?: FirestoreRulesToolDeps): ToolHandler[];
+export declare function createFirestoreSimulatorTools(deps: FirestoreSimulatorToolDeps): ToolHandler[];
+//# sourceMappingURL=tools.d.ts.map

package/dist/rules/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/rules/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAMxD,OAAO,EAEL,KAAK,0BAA0B,IAAI,8BAA8B,EAClE,MAAM,2BAA2B,CAAC;AAInC,MAAM,MAAM,0BAA0B,GAAG,IAAI,CAC3C,8BAA8B,EAC9B,gBAAgB,CACjB,CAAC;AAIF,MAAM,WAAW,sBAAsB;IACrC;;gDAE4C;IAC5C,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,GAAE,sBAA2B,GAChC,WAAW,EAAE,CAkFf;AAUD,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,0BAA0B,GAC/B,WAAW,EAAE,CAKf"}

package/dist/rules/tools.js

@@ -0,0 +1,120 @@
+/**
+ * Tool factories for `pyric/rules` per F1.
+ *
+ *   - `createFirestoreRulesTools()`: pure-local rules tooling
+ *     (lint, parse, resolve-modules, simulate) + the Rules Test API
+ *     client (test, takes ProjectScope).
+ *   - `createFirestoreSimulatorTools({ resolveSandbox })`: stateful
+ *     simulator tools — create, execute, read, batch, transaction,
+ *     undo, events. Tools operate against a session-scoped
+ *     LocalEnvironment resolved per dispatch.
+ *
+ * Per F2: identity is a value; lifecycle is a resolver. The
+ * `resolveSandbox` resolver returns the session's
+ * LocalEnvironment — handlers call it inside `execute` so reset /
+ * swap is transparent.
+ *
+ * Per F5: handlers are self-contained — only deps + args + ctx;
+ * no globals.
+ */
+import { resolveModules } from './modules/resolver.js';
+import { SimulateFirestoreRulesHandler } from './simulator/handler.js';
+import { createFirestoreRulesStdlibTools } from './stdlib-tools.js';
+import { TestFirestoreRulesHandler } from './test/handler.js';
+import { createFirestoreSimulatorTools as createFirestoreSimulatorToolsImpl, } from './simulator-tools-impl.js';
+/**
+ * Pure-local Firestore rules tooling, plus the optional Rules Test
+ * API client when `scope` is supplied. Bundles:
+ *
+ *   - `firestore_lint_rules`
+ *   - `firestore_resolve_modules`
+ *   - `firestore_simulate_rules`
+ *   - `firestore_test_rules` (only when `scope` is supplied)
+ */
+export function createFirestoreRulesTools(deps = {}) {
+    const handlers = [
+        // `firestore_lint_rules` + `firestore_resolve_modules` are
+        // provided by `createFirestoreRulesStdlibTools()` (browser-safe;
+        // stdlib content inlined at build time) and spread in below.
+        // Node consumers that need `basePath`-driven relative-import
+        // resolution should call the `resolveModules` function directly
+        // — the public tool surface intentionally keeps the schema
+        // browser-friendly.
+        {
+            name: 'firestore_simulate_rules',
+            description: 'Simulate Firestore security rules locally against a list of test cases. Same shape as `firestore_test_rules` but in-process — no propagation wait, no side effects. Supports get()/exists() via functionMocks.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    source: { type: 'string' },
+                    testCases: { type: 'array' },
+                },
+                required: ['source', 'testCases'],
+            },
+            async execute(args) {
+                const { source, testCases } = args;
+                const handler = new SimulateFirestoreRulesHandler();
+                const result = handler.simulate(source, testCases);
+                return {
+                    ok: result.success,
+                    summary: result.success
+                        ? `${result.data.results.filter((r) => r.state === 'PASSED').length}/${result.data.results.length} test cases passed`
+                        : `Simulation failed: ${result.error.message}`,
+                    data: result,
+                };
+            },
+        },
+        // Stdlib reference tools (list + get) — pure data, browser-safe.
+        // Defined in `./stdlib-tools.ts` so consumers that only need the
+        // reference (the playground, browser docs generators) don't pull
+        // in the Node-only resolver via this Node-only factory.
+        ...createFirestoreRulesStdlibTools(),
+    ];
+    if (deps.scope) {
+        const scope = deps.scope;
+        // Deployed-rules inspection is a separate opt-in surface. Browser and
+        // Node callers that need parsed rules wire `createFirestoreInspectTool`
+        // directly from `pyric/rules`.
+        handlers.push({
+            name: 'firestore_test_rules',
+            description: 'Test Firestore security rules against test cases via the Firebase Rules Test API. Requires a ProjectScope (auth credentials).',
+            parameters: {
+                type: 'object',
+                properties: {
+                    source: { type: 'string' },
+                    testCases: { type: 'array' },
+                    expressionReportLevel: { type: 'string', enum: ['NONE', 'VISITED', 'FULL'] },
+                },
+                required: ['source', 'testCases'],
+            },
+            async execute(args) {
+                const { source, testCases, expressionReportLevel } = args;
+                const handler = new TestFirestoreRulesHandler();
+                const result = await handler.execute(scope, source, testCases, { expressionReportLevel });
+                return {
+                    ok: result.success,
+                    summary: result.success
+                        ? `${result.data.passed}/${result.data.passed + result.data.failed} test cases passed`
+                        : `Rules test failed: ${result.error.message}`,
+                    data: result,
+                };
+            },
+        });
+    }
+    return handlers;
+}
+// ─── createFirestoreSimulatorTools ────────────────────────────────────
+//
+// Implementation lives in ./simulator-tools-impl.ts so the same factory
+// can run in both Node and browser bundles without forcing the Node-only
+// `resolveModules` (disk reads) into the browser. The /node entry below
+// wires `resolveModules` from `./modules/resolver.js`; the browser-safe
+// `/simulator` entry wires `resolveModulesBrowser`. See `./simulator.ts`.
+//
+export function createFirestoreSimulatorTools(deps) {
+    return createFirestoreSimulatorToolsImpl({
+        resolveSandbox: deps.resolveSandbox,
+        resolveModulesFn: resolveModules,
+    });
+}
+//# sourceMappingURL=tools.js.map

package/dist/rules/tools.js.map

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

package/dist/rules/write/handler.d.ts

@@ -0,0 +1,6 @@
+import type { ProjectScope } from '../../project-scope.js';
+import type { WriteFirestoreRulesResult } from './spec.js';
+export declare class WriteFirestoreRulesHandler {
+    execute(scope: ProjectScope, source: string): Promise<WriteFirestoreRulesResult>;
+}
+//# sourceMappingURL=handler.d.ts.map

package/dist/rules/write/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../src/rules/write/handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAC;AAO3D,qBAAa,0BAA0B;IAC/B,OAAO,CAAC,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,CAAC;CAkIvF"}