pyric 0.1.0-alpha.7 → 0.1.0-alpha.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +132 -47
  2. package/README.md.orig +54 -0
  3. package/package.json +3 -2
package/README.md CHANGED
@@ -1,54 +1,139 @@
1
- # pyric
2
-
3
- Firebase-shaped client SDK adapters with a swappable in-process sandbox
4
- backend, plus Pyric's rules tooling and sandbox runtime.
5
-
6
- > **Alpha.** This package is an early alpha. The Firebase-mirrored subpaths
7
- > (`pyric/app`, `pyric/firestore`, `pyric/auth`, `pyric/database`,
8
- > `pyric/storage`) are best-effort mirror contracts of the modular Web SDK —
9
- > not guaranteed parity. Non-mirrored exports (e.g. `pyric/sandbox/internal`,
10
- > the rules tooling subpaths) are experimental public-alpha surfaces that may
11
- > change without notice.
12
-
13
- `pyric` mirrors Firebase's modular Web SDK subpaths:
14
-
15
- | Subpath | Surface |
16
- |---|---|
17
- | `pyric/app` | `initializeApp`, `PyricApp`, sandbox/prod app tags |
18
- | `pyric/firestore` | Firestore modular SDK mirror plus data/inspect tool factories |
19
- | `pyric/auth` | Auth modular SDK mirror plus sandbox auth helpers |
20
- | `pyric/database` | Realtime Database modular SDK mirror plus admin tools |
21
- | `pyric/storage` | Storage modular SDK mirror plus storage admin tools |
22
- | `pyric/rules` | Firestore rules parser, linter, validator, simulator, stdlib tooling |
23
- | `pyric/rules/node` | Node-only rules module resolution helpers |
24
- | `pyric/rules/rtdb` | Realtime Database rules facade: mapper, parser/linter, simulator, deploy/read rule tool factory |
25
- | `pyric/rules/rtdb-constraints` | Realtime Database rules constraint helpers |
26
- | `pyric/sandbox` | In-process Firebase sandbox runtime |
27
- | `pyric/sandbox/internal` | Adapter-only internal protocol surface |
28
- | `pyric/sandbox/admin-compat` | Chainable admin-compat Firestore wrapper over the sandbox |
29
-
30
- ## Example
31
-
32
- ```ts
33
- import { initializeApp } from 'pyric/app';
1
+ <p align="center">
2
+ <img src="https://pyric.dev/pyric-logo.svg" alt="Pyric" width="180" />
3
+ </p>
4
+
5
+ <h1 align="center">Firebase that runs in the browser</h1>
6
+
7
+ <p align="center">Agentic coding without production consequences</p>
8
+
9
+ <p align="center"><a href="https://pyric.dev">pyric.dev</a></p>
10
+
11
+ <br />
12
+
13
+ Pyric is Firestore, Auth, Realtime Database, Storage, *Messaging soon*, and the Security Rules engine, implemented in TypeScript and running inside the application process. In the browser, that process is the page itself: the whole backend executes in the tab. In Node, it is the Node process, so tests and scripts get the same backend with no browser involved.
14
+
15
+ ## Built for dev, disappears in prod
16
+ This is not the Firebase Emulator Suite behind a wrapper. There is no Java process, no localhost port, and no cloud Firebase project connected.
17
+
18
+ Application code keeps using `firebase/*` imports which are mapped to the sandbox during development. When you ship to production, the map goes away, and the app talks to production services.
19
+
20
+ Pyric's tooling maps one-to-one to standard Firebase tools.
21
+
22
+ ```bash
23
+ npm i pyric === npm i firebase
24
+ npm i pyric-admin === npm i firebase-admin
25
+ npm i pyric-tools === npm i firebase-tools
26
+ ```
27
+
28
+ The pyric CLI, `pyric-tools`, is for managing the pyric environment and not meant to overlap with the utility of the Firebase CLI, `firebase-tools`. The small overlap `pyric login`, `pyric deploy`, is an extreme subset of the Firebase CLI's functionality and offered for convenience.
29
+
30
+ ### Backed by conformance
31
+ The services are an independent implementation of Firebase's observable behavior, and that claim is tested rather than assumed: probes run against production Firebase, their recorded behavior is committed as observations, and CI replays every observation against the sandbox on every change. The section [What matches Firebase and what doesn't](#what-matches-firebase-and-what-doesnt) has the numbers.
32
+
33
+ Because the services live in the process, the backend becomes local state. Data, identities, security rules, and time-ordered events can be seeded, snapshotted, reset, and replayed the way source code is edited.
34
+
35
+ ## Where a coding agent runs Firebase code
36
+ Agents already know the Firebase SDK. They don't need a new API to learn, they need somewhere to run the code they already write. Pyric is that target: the same `firebase/*` calls, executed against a local sandbox instead of production. On the map of an agent's tools it doesn't sit beside Firebase as an alternative, it sits under the code the agent already generates, as the thing that code runs against during development. Because the sandbox is fully local, there is no Firebase project and no account in the loop.
37
+
38
+ Traditionally, Firebase development begins with an account, a project, enabled services, the Emulator Suite and its Java dependency, and hand-wired switching between emulator and production in the SDK. An agent working in that environment touches real infrastructure, so writes, deploys, and rules changes need supervision.
39
+
40
+ A backend that runs inside the app removes the infrastructure from the loop. A developer gets a full Firebase stack in the first ten seconds of a project. An agent gets the whole backend as an inspectable, resettable tool surface it can exercise without supervision.
41
+
42
+ ## Getting Started
43
+
44
+ Install the CLI in an existing Firebase app or a new one:
45
+
46
+ ```bash
47
+ npm i -g pyric-tools # installs the `pyric` command
48
+ npx pyric init --template web # scaffold, or just run pyric dev in an existing app
49
+ npx pyric dev
50
+ ```
51
+
52
+ `pyric dev` serves the app against the in-process sandbox. The app's own `firebase/*` imports resolve to the sandbox during development; nothing in the application source changes. The sandbox holds data, identities, and rules, and everything it does is observable through the mechanisms below.
53
+
54
+ ## Security rules as a library
55
+
56
+ Pyric includes a rules engine for Firestore and Realtime Database rules: parser, linter, validator, and simulator, usable in-process and from the CLI.
57
+
58
+ ```bash
59
+ pyric rules:lint firestore.rules
60
+ pyric rules:simulate --stdin
61
+ pyric database:rules:validate database.rules.json
62
+ ```
63
+
64
+ Rules edits take effect in the running app without a deploy. Realtime Database `.validate` rules are evaluated on writes, matching production behavior.
65
+
66
+ ## Everything the sandbox does is an event
67
+
68
+ The sandbox emits a typed event for every operation it performs: reads, writes, auth transitions, and rules verdicts, including denials with the rule, path, and data that produced them. The diagnostics are consumers of that stream:
69
+
70
+ - Traffic inspection: what the app actually did, live, in the `pyric dev --ui` console or through the `@pyric/ui` traffic and events components.
71
+ - Denial inspection: a rejected operation carries its verdict instead of a bare `permission-denied` error.
72
+ - Capture and replay: `pyric snapshot` records state, and captured sessions replay through the same event stream, which is what `pyric verify` is built on.
73
+
74
+ ## Browser Sandbox connected to local MCP
75
+
76
+ Pyric provides a local MCP server with 51 tools. Yes, that's a lot. But the surface is wide because Firebase's is, and there's ongoing work to consolidate it into fewer, sharper tools. Pyric connects the browser sandbox to the server over a web socket bridge (the included [Claude Code plugin](pyric-plugin/README.md) auto-wires this) or composes programmatically into any agent framework. The inventory is in [docs/agent-tools.md](docs/agent-tools.md). The tools unique to its environment:
77
+
78
+ - `firestore_simulate_rules` and `rtdb_simulate_access` evaluate a rules verdict for a hypothetical operation without performing it.
79
+ - `firestore_simulator_*` runs a stateful Firestore session with seed, execute, batch, transaction, undo, redo, and an inspectable event log.
80
+ - `sandbox_inspect`, `firestore_discover_paths`, and `rtdb_crawl_structure` map what exists in the data and how it is shaped.
81
+ - `rtdb_validated_write` runs pre-flight checks before writing: it infers the schema at the target path, validates the payload against it, and simulates the rules verdict, returning schema warnings and simulation results alongside the write outcome.
82
+ - `firestore_extract_indexes` derives composite-index definitions from the query shapes in source.
83
+ - The deploy factories (`firestore_deploy_rules`, `firestore_deploy_indexes`, `rtdb_deploy_rules`, `hosting_deploy`, `functions_deploy`) drive the Firebase control plane over REST, without the `firebase-tools` CLI.
84
+
85
+ ## Work that carries to production
86
+
87
+ A sandbox session produces the artifacts a production deploy needs. Rules leave the sandbox already exercised against the app's actual behavior; `pyric deploy rules` ships them. Composite indexes come from `firestore_extract_indexes` instead of a hand-maintained `firestore.indexes.json`; `pyric deploy indexes` ships those. And `pyric verify` replays a captured session against a candidate ruleset and reports which operations change verdict before production finds out.
88
+
89
+ ## What matches Firebase and what doesn't
90
+
91
+ A sandbox is only useful if it behaves like the real service. The evidence: 138 committed observations of production Firebase behavior, replayed against the sandbox in CI on every change, and a public compatibility matrix of 610 rows, 539 conforming today. Known divergences are documented rather than hidden, and an undocumented divergence is treated as a bug.
92
+
93
+ Per service: [Firestore](packages/pyric/docs/firestore/COMPAT.md), [Auth](packages/pyric/docs/auth/COMPAT.md), [Realtime Database](packages/pyric/docs/database/COMPAT.md), [Storage](packages/pyric/docs/storage/COMPAT.md). How the system works: [running the conformance system](docs/conformance/how-to-run-the-conformance-system.md).
94
+
95
+ ## Using the packages directly
96
+
97
+ Most apps never import Pyric. For tests, Node scripts, and programmatic control of sandboxes, the `pyric/*` and `pyric-admin/*` packages mirror the Firebase SDKs' shape:
98
+
99
+ ```js
34
100
  import { initializeSandbox } from 'pyric/sandbox';
35
- import { getFirestore, collection, getDocs } from 'pyric/firestore';
101
+ import { initializeApp } from 'pyric-admin/app';
102
+ import { getDatabase } from 'pyric-admin/database';
103
+
104
+ initializeApp({ sandbox: initializeSandbox() }); // the only non-firebase-admin line
105
+ const db = getDatabase();
106
+ await db.ref('rooms/lobby').set({ topic: 'launch day' });
107
+ ```
108
+
109
+ | Package | Purpose | Docs |
110
+ |---|---|---|
111
+ | `pyric` | Web SDK mirror, rules tooling, sandbox runtime | [docs](packages/pyric/docs/) |
112
+ | `pyric-admin` | `firebase-admin` mirror over sandbox or production | [docs](packages/pyric-admin/docs/firestore/) |
113
+ | `pyric-tools` | The `pyric` CLI: `dev`, `init`, MCP bridge, deploy, verify | [docs](packages/pyric-tools/docs/) |
114
+ | `@pyric/ui` | Headless React admin components and hooks | [docs](packages/ui/docs/) |
115
+ | `@pyric/studio` | The local console behind `pyric dev --ui` | [README](packages/studio/README.md) |
116
+
117
+ ```bash
118
+ npm install -D pyric-tools # the CLI; sufficient for most apps
119
+ npm install pyric pyric-admin # for direct sandbox control
120
+ ```
121
+
122
+ Node 22 or later. All packages are ESM-only with subpath exports (`pyric/firestore`, not `pyric`).
123
+
124
+ ## Development
36
125
 
37
- const app = initializeApp({ sandbox: initializeSandbox() });
38
- const db = getFirestore(app);
126
+ Requires Bun and Node 22 or later.
39
127
 
40
- const snap = await getDocs(collection(db, 'posts'));
128
+ ```bash
129
+ bun install
130
+ bun run build
131
+ bun test packages/pyric packages/pyric-admin packages/pyric-tools packages/ui
132
+ npm run test:packaging
41
133
  ```
42
134
 
43
- To target production Firebase instead, pass normal Firebase app options to
44
- `initializeApp`. Downstream Firestore/Auth/Database/Storage calls keep the same
45
- shape.
135
+ Examples: [examples/vite-sandbox-app](examples/vite-sandbox-app/), the shape `pyric init --template web` generates, and [examples/admin-playground](examples/admin-playground/), a `@pyric/ui` showcase.
46
136
 
47
- ## Docs
137
+ ## Stability
48
138
 
49
- - [Firestore](docs/firestore/)
50
- - [Auth](docs/auth/)
51
- - [Realtime Database](docs/database/)
52
- - [Storage](docs/storage/)
53
- - [Rules](docs/rules/)
54
- - [Sandbox](docs/sandbox/)
139
+ Alpha, `0.1.0-alpha.7`, published as an experimental product. The one stability goal is the Firebase mirror: code written against mirrored surfaces is intended to keep working, tracked in the compatibility matrices. Pyric-specific APIs (sandbox lifecycle, replay, serve and bridge internals) are public-alpha and may change between releases.
package/README.md.orig ADDED
@@ -0,0 +1,54 @@
1
+ # pyric
2
+
3
+ Firebase-shaped client SDK adapters with a swappable in-process sandbox
4
+ backend, plus Pyric's rules tooling and sandbox runtime.
5
+
6
+ > **Alpha.** This package is an early alpha. The Firebase-mirrored subpaths
7
+ > (`pyric/app`, `pyric/firestore`, `pyric/auth`, `pyric/database`,
8
+ > `pyric/storage`) are best-effort mirror contracts of the modular Web SDK —
9
+ > not guaranteed parity. Non-mirrored exports (e.g. `pyric/sandbox/internal`,
10
+ > the rules tooling subpaths) are experimental public-alpha surfaces that may
11
+ > change without notice.
12
+
13
+ `pyric` mirrors Firebase's modular Web SDK subpaths:
14
+
15
+ | Subpath | Surface |
16
+ |---|---|
17
+ | `pyric/app` | `initializeApp`, `PyricApp`, sandbox/prod app tags |
18
+ | `pyric/firestore` | Firestore modular SDK mirror plus data/inspect tool factories |
19
+ | `pyric/auth` | Auth modular SDK mirror plus sandbox auth helpers |
20
+ | `pyric/database` | Realtime Database modular SDK mirror plus admin tools |
21
+ | `pyric/storage` | Storage modular SDK mirror plus storage admin tools |
22
+ | `pyric/rules` | Firestore rules parser, linter, validator, simulator, stdlib tooling |
23
+ | `pyric/rules/node` | Node-only rules module resolution helpers |
24
+ | `pyric/rules/rtdb` | Realtime Database rules facade: mapper, parser/linter, simulator, deploy/read rule tool factory |
25
+ | `pyric/rules/rtdb-constraints` | Realtime Database rules constraint helpers |
26
+ | `pyric/sandbox` | In-process Firebase sandbox runtime |
27
+ | `pyric/sandbox/internal` | Adapter-only internal protocol surface |
28
+ | `pyric/sandbox/admin-compat` | Chainable admin-compat Firestore wrapper over the sandbox |
29
+
30
+ ## Example
31
+
32
+ ```ts
33
+ import { initializeApp } from 'pyric/app';
34
+ import { initializeSandbox } from 'pyric/sandbox';
35
+ import { getFirestore, collection, getDocs } from 'pyric/firestore';
36
+
37
+ const app = initializeApp({ sandbox: initializeSandbox() });
38
+ const db = getFirestore(app);
39
+
40
+ const snap = await getDocs(collection(db, 'posts'));
41
+ ```
42
+
43
+ To target production Firebase instead, pass normal Firebase app options to
44
+ `initializeApp`. Downstream Firestore/Auth/Database/Storage calls keep the same
45
+ shape.
46
+
47
+ ## Docs
48
+
49
+ - [Firestore](docs/firestore/)
50
+ - [Auth](docs/auth/)
51
+ - [Realtime Database](docs/database/)
52
+ - [Storage](docs/storage/)
53
+ - [Rules](docs/rules/)
54
+ - [Sandbox](docs/sandbox/)
package/package.json CHANGED
@@ -1,7 +1,8 @@
1
1
  {
2
2
  "name": "pyric",
3
- "version": "0.1.0-alpha.7",
4
- "description": "Firebase for agents — modular Web SDK adapters (firestore, auth, database, storage) with swappable sandbox/prod backends, plus rules tooling and in-process sandbox. Mirrors firebase.",
3
+ "version": "0.1.0-alpha.8",
4
+ "homepage": "https://pyric.dev",
5
+ "description": "Firebase for agents \u2014 modular Web SDK adapters (firestore, auth, database, storage) with swappable sandbox/prod backends, plus rules tooling and in-process sandbox. Mirrors firebase.",
5
6
  "type": "module",
6
7
  "exports": {
7
8
  "./app": {