pyric-tools 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.
- package/README.md +135 -121
- package/README.md.orig +125 -0
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -1,125 +1,139 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
>
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
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
|
|
100
|
+
import { initializeSandbox } from 'pyric/sandbox';
|
|
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) |
|
|
61
116
|
|
|
62
117
|
```bash
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
bun run dev:agent # pyric dev --bridge --seed seed.json
|
|
118
|
+
npm install -D pyric-tools # the CLI; sufficient for most apps
|
|
119
|
+
npm install pyric pyric-admin # for direct sandbox control
|
|
66
120
|
```
|
|
67
121
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
##
|
|
84
|
-
|
|
85
|
-
The
|
|
86
|
-
registries (`pyric/firestore` + `pyric/rules`) so the surface can't drift from
|
|
87
|
-
the library — the canonical, always-current list is the
|
|
88
|
-
[agent tool inventory](../../docs/agent-tools.md).
|
|
89
|
-
|
|
90
|
-
**Sandbox-routed** — dispatched against the connected browser sandbox
|
|
91
|
-
(`createFirestoreDataTools` + `createFirestoreSimulatorTools` +
|
|
92
|
-
`createFirestoreInspectTools`):
|
|
93
|
-
|
|
94
|
-
- data: `firestore_get_document` / `_list_documents` / `_create_document` / `_update_document` / `_delete_document` / `_query_where` / `firestore_create_with_auto_id`
|
|
95
|
-
- stateful simulator session: `firestore_simulator_create` / `_execute` / `_read` / `_batch` / `_undo` / `_redo` / `_events` / `_transaction`
|
|
96
|
-
- diagnostics: `sandbox_inspect` — single-call sandbox state/rules snapshot
|
|
97
|
-
|
|
98
|
-
**In-process** — run on the bridge process itself (`createFirestoreRulesTools`):
|
|
99
|
-
|
|
100
|
-
- `firestore_simulate_rules`
|
|
101
|
-
- `firestore_rules_stdlib_list` / `_get`
|
|
102
|
-
- `firestore_lint_rules`
|
|
103
|
-
- `firestore_resolve_modules`
|
|
104
|
-
|
|
105
|
-
### Gaps from the playground tool surface
|
|
106
|
-
|
|
107
|
-
The `packages/playground/` app ships richer diagnostic tools that
|
|
108
|
-
the `pyric bridge` does NOT register out of the box today. They're
|
|
109
|
-
playground-specific orchestrators built on top of `useRuntimeStore`
|
|
110
|
-
and other browser-only state:
|
|
111
|
-
|
|
112
|
-
- `inspect_firestore_traffic` — structured dump of the sandbox traffic log
|
|
113
|
-
- `seed_firestore_data_as_admin` — admin-bypass bulk writes for fixture setup
|
|
114
|
-
- `generate_fixture_from_session` — snapshot `sandbox.history()` as a replay fixture
|
|
115
|
-
- `try_rules_edit` — replay events under a proposed rules edit
|
|
116
|
-
- `debug_firestore_rules` — orchestrator over simulate + lint + history + state
|
|
117
|
-
|
|
118
|
-
These are powerful and worth lifting into the library so any
|
|
119
|
-
`pyric bridge` user gets them. The blockers are: `inspect_traffic`
|
|
120
|
-
needs a generic traffic-log API on `Sandbox` (today the playground
|
|
121
|
-
maintains its own ring buffer); `try_rules_edit` + `debug_firestore_rules`
|
|
122
|
-
are orchestrators that depend on the replay engine being wired to a
|
|
123
|
-
generic "session" abstraction. Tracked as a follow-up — the underlying
|
|
124
|
-
primitives (`sandbox.history()`, `pyric/sandbox/replay`, the rules
|
|
125
|
-
simulator) all exist.
|
|
122
|
+
Node 22 or later. All packages are ESM-only with subpath exports (`pyric/firestore`, not `pyric`).
|
|
123
|
+
|
|
124
|
+
## Development
|
|
125
|
+
|
|
126
|
+
Requires Bun and Node 22 or later.
|
|
127
|
+
|
|
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
|
|
133
|
+
```
|
|
134
|
+
|
|
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.
|
|
136
|
+
|
|
137
|
+
## Stability
|
|
138
|
+
|
|
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,125 @@
|
|
|
1
|
+
# pyric-tools
|
|
2
|
+
|
|
3
|
+
The Pyric CLI + programmatic helpers for `firebase-tools`-shaped work
|
|
4
|
+
(deploy, bridge, discover, identity-toolkit configuration).
|
|
5
|
+
|
|
6
|
+
> **Alpha.** This package is an early alpha. The `firebase-tools`-mirrored
|
|
7
|
+
> surfaces (deploy, discover, auth configuration) are best-effort mirror
|
|
8
|
+
> contracts; non-mirrored exports (e.g. `pyric-tools/serve/worker`,
|
|
9
|
+
> `pyric-tools/verify`, `pyric-tools/credentials`) are experimental
|
|
10
|
+
> public-alpha surfaces that may change without notice. The MCP tool surface
|
|
11
|
+
> (tool names and shapes) will consolidate during early alpha — do not treat
|
|
12
|
+
> tool names as stable.
|
|
13
|
+
|
|
14
|
+
## CLI subcommands
|
|
15
|
+
|
|
16
|
+
| Command | What it does |
|
|
17
|
+
|---|---|
|
|
18
|
+
| `pyric init [dir]` | Scaffold a pyric project — never prompts, idempotent, safe to rerun. `--template web` (default): a servable app with **canonical `firebase/*` imports** (owner-based rules, `seed.json`, `dev`/`dev:agent` scripts, real `firebase` dep) — `pyric dev` runs it on the sandbox; any standard bundler runs the same code on real Firebase. The swap is environmental, never a code edit. `--template node`: script-style scaffold whose backend is picked by `PYRIC_TARGET=sandbox\|firebase`. Also `--name`, `--force` (overwrite scaffold-owned files), `--json` (machine result on stdout: `{template, dir, created, merged, skipped, conflicts, nextSteps}`) |
|
|
19
|
+
| `pyric bridge` | Stand up an HTTP+WebSocket bridge an MCP client (Claude Code, Cursor) connects to |
|
|
20
|
+
| `pyric dev` | Local dev server with the pyric sandbox standing in for Firebase: serves `hosting.public`, resolves unmodified `firebase/*` imports to a pyric sandbox via a served import map, deploys + hot-reloads `firestore.rules` (SSE), opens an emulator-style sign-in helper for `signInWithPopup`/`signInWithRedirect`. The sandbox runs in a **SharedWorker by default** — one backend shared by every tab of the origin (live cross-tab sync), kept in the browser's IndexedDB so **your sandbox data — Firestore docs, auth users, RTDB, storage objects, and the traffic history — survives a refresh/restart by default** (see the persistence guide's coverage matrix for the exact tiers); a per-tab in-page sandbox is the fallback when SharedWorker is unavailable. Flags + exit codes: [CLI reference](docs/reference/cli.md#pyric-dev); persistence, ephemeral runs, clearing data, and SharedWorker tips: [persistence & multi-tab](docs/how-to/serve-persistence-and-multi-tab.md) |
|
|
21
|
+
| `pyric snapshot` | Promote lived sandbox state (live `dev --persist`, else `.pyric/state/state.json`) to a committable fixture; `pyric dev --seed <fixture>` re-serves it (docs + users). `--out`, `--port`, `--force`, `--json` |
|
|
22
|
+
| `pyric deploy <target>` | Deploy `rules` / `indexes` / `database` / `hosting` / `functions` to a real Firebase project |
|
|
23
|
+
| `pyric rules:lint <path>` | Lint a Firestore rules file |
|
|
24
|
+
| `pyric rules:validate <path>` | Validate Firestore rules structure |
|
|
25
|
+
| `pyric rules:simulate` | Local rules simulator |
|
|
26
|
+
| `pyric database:rules:lint <path>` | Lint a Realtime Database rules JSON file |
|
|
27
|
+
| `pyric database:rules:validate <path>` | Validate Realtime Database rules expressions |
|
|
28
|
+
| `pyric database:rules:simulate` | Local Realtime Database rules simulator |
|
|
29
|
+
| `pyric auth:configure-provider <id> <enabled>` | Identity Toolkit: enable/disable an auth provider |
|
|
30
|
+
| `pyric auth:manage-domains <add\|remove\|list> [domain]` | Identity Toolkit: authorized domains |
|
|
31
|
+
| `pyric firestore:discover [collection]` | Crawl a Firestore to infer schema |
|
|
32
|
+
|
|
33
|
+
Every command's full flags, defaults, exit codes, and environment variables are
|
|
34
|
+
in the **[CLI reference](docs/reference/cli.md)**. Task guides and the rest of
|
|
35
|
+
the docs are indexed in **[docs/](docs/README.md)**.
|
|
36
|
+
|
|
37
|
+
### Persistence caveats (documented limits)
|
|
38
|
+
|
|
39
|
+
- **Anonymous users don't persist** (no round-trip key) — but their *documents
|
|
40
|
+
do*. An app that calls `signInAnonymously` on load mints a new uid every
|
|
41
|
+
reload under `--persist`, so docs owned by prior anonymous uids accumulate
|
|
42
|
+
unreachably. Use the sign-in helper (or seeded users) for owner-based data
|
|
43
|
+
you want durable.
|
|
44
|
+
- **The state file is not a point-in-time snapshot** — firestore and auth
|
|
45
|
+
sections flush on independent debounces; a crash between them can persist
|
|
46
|
+
docs whose owner user hasn't flushed yet (or vice versa).
|
|
47
|
+
- **One writer tab at a time (in-page fallback only)** — when several per-tab
|
|
48
|
+
in-page sandboxes share one `.pyric/state` file, the first tab to flush holds
|
|
49
|
+
the writer lock; others run read-only (console warning + `persistReadOnly`
|
|
50
|
+
diagnostic) so they can't erase the writer's data. On the default SharedWorker
|
|
51
|
+
path this can't happen — the single worker is the sole writer.
|
|
52
|
+
- **Loss window** — the final unsaved change can be lost if the tab CLOSES
|
|
53
|
+
within the flush debounce while the state exceeds ~60KB (keepalive cap);
|
|
54
|
+
smaller states flush on unload, and reloads are always safe. A reset (or
|
|
55
|
+
any delete-all) that empties a non-empty state first preserves the prior
|
|
56
|
+
file at `.pyric/state/state.json.bak`.
|
|
57
|
+
|
|
58
|
+
### Agent onboarding (init → dev → MCP)
|
|
59
|
+
|
|
60
|
+
Three parseable steps, no flags to discover:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
pyric init myapp --json # → {..., "nextSteps": [...]}
|
|
64
|
+
cd myapp && bun install
|
|
65
|
+
bun run dev:agent # pyric dev --bridge --seed seed.json
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Readiness probe: `GET <url>/__pyric/init.json` → 200 once serving (body
|
|
69
|
+
carries the live rules hash). MCP endpoint: `<url>/__pyric/mcp`. With
|
|
70
|
+
`pyric dev --json`, stdout's single line carries `{url, port, mcpUrl,
|
|
71
|
+
rulesHash}`.
|
|
72
|
+
|
|
73
|
+
## Programmatic subpaths
|
|
74
|
+
|
|
75
|
+
| Subpath | Surface |
|
|
76
|
+
|---|---|
|
|
77
|
+
| `pyric-tools/deploy` | `fromServiceAccount`, `getDeploy`, `createFirestoreDeployTools`, `createRtdbDeployTools`, `createHostingDeployTools`, `createFunctionsDeployTools` |
|
|
78
|
+
| `pyric-tools/bridge` | `createBridge`, `startServer` (Node) / `connectBridge` (browser via conditional export). Vite integration is `pyricSandbox({ bridge })` in `pyric-tools/vite`. |
|
|
79
|
+
| `pyric-tools/vite` | `pyricSandbox(opts)`, the dev-only firebase→sandbox swap plugin. Opts: `rules`, `persist`/`fresh`, `seed`, `capture`, `bridge` (MCP), `ui` (Pyric Studio at `/__pyric/ui/`, parity with `dev --ui`). |
|
|
80
|
+
| `pyric-tools/discover` | `crawl`, `findCollectionGroup`, `createRestCrawlerFirestore`, `createFirestoreDiscoverTools` |
|
|
81
|
+
| `pyric-tools/auth` | `getAuthTools` (Identity Toolkit-driven provider + domain configuration) |
|
|
82
|
+
|
|
83
|
+
## MCP tool surface (`pyric bridge`)
|
|
84
|
+
|
|
85
|
+
The bridge registers two toolsets, sourced directly from `pyric`'s own tool
|
|
86
|
+
registries (`pyric/firestore` + `pyric/rules`) so the surface can't drift from
|
|
87
|
+
the library — the canonical, always-current list is the
|
|
88
|
+
[agent tool inventory](../../docs/agent-tools.md).
|
|
89
|
+
|
|
90
|
+
**Sandbox-routed** — dispatched against the connected browser sandbox
|
|
91
|
+
(`createFirestoreDataTools` + `createFirestoreSimulatorTools` +
|
|
92
|
+
`createFirestoreInspectTools`):
|
|
93
|
+
|
|
94
|
+
- data: `firestore_get_document` / `_list_documents` / `_create_document` / `_update_document` / `_delete_document` / `_query_where` / `firestore_create_with_auto_id`
|
|
95
|
+
- stateful simulator session: `firestore_simulator_create` / `_execute` / `_read` / `_batch` / `_undo` / `_redo` / `_events` / `_transaction`
|
|
96
|
+
- diagnostics: `sandbox_inspect` — single-call sandbox state/rules snapshot
|
|
97
|
+
|
|
98
|
+
**In-process** — run on the bridge process itself (`createFirestoreRulesTools`):
|
|
99
|
+
|
|
100
|
+
- `firestore_simulate_rules`
|
|
101
|
+
- `firestore_rules_stdlib_list` / `_get`
|
|
102
|
+
- `firestore_lint_rules`
|
|
103
|
+
- `firestore_resolve_modules`
|
|
104
|
+
|
|
105
|
+
### Gaps from the playground tool surface
|
|
106
|
+
|
|
107
|
+
The `packages/playground/` app ships richer diagnostic tools that
|
|
108
|
+
the `pyric bridge` does NOT register out of the box today. They're
|
|
109
|
+
playground-specific orchestrators built on top of `useRuntimeStore`
|
|
110
|
+
and other browser-only state:
|
|
111
|
+
|
|
112
|
+
- `inspect_firestore_traffic` — structured dump of the sandbox traffic log
|
|
113
|
+
- `seed_firestore_data_as_admin` — admin-bypass bulk writes for fixture setup
|
|
114
|
+
- `generate_fixture_from_session` — snapshot `sandbox.history()` as a replay fixture
|
|
115
|
+
- `try_rules_edit` — replay events under a proposed rules edit
|
|
116
|
+
- `debug_firestore_rules` — orchestrator over simulate + lint + history + state
|
|
117
|
+
|
|
118
|
+
These are powerful and worth lifting into the library so any
|
|
119
|
+
`pyric bridge` user gets them. The blockers are: `inspect_traffic`
|
|
120
|
+
needs a generic traffic-log API on `Sandbox` (today the playground
|
|
121
|
+
maintains its own ring buffer); `try_rules_edit` + `debug_firestore_rules`
|
|
122
|
+
are orchestrators that depend on the replay engine being wired to a
|
|
123
|
+
generic "session" abstraction. Tracked as a follow-up — the underlying
|
|
124
|
+
primitives (`sandbox.history()`, `pyric/sandbox/replay`, the rules
|
|
125
|
+
simulator) all exist.
|
package/package.json
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pyric-tools",
|
|
3
|
-
"version": "0.1.0-alpha.
|
|
3
|
+
"version": "0.1.0-alpha.8",
|
|
4
|
+
"homepage": "https://pyric.dev",
|
|
4
5
|
"description": "Pyric CLI binary (`pyric`) + programmatic deploy / bridge / discover / auth-config helpers. Mirrors firebase-tools.",
|
|
5
6
|
"type": "module",
|
|
6
7
|
"exports": {
|
|
@@ -98,7 +99,7 @@
|
|
|
98
99
|
"fflate": "^0.8.2",
|
|
99
100
|
"firebase": "^12.12.0",
|
|
100
101
|
"firebase-admin": "^13.0.0",
|
|
101
|
-
"pyric": "^0.1.0-alpha.
|
|
102
|
+
"pyric": "^0.1.0-alpha.8",
|
|
102
103
|
"ws": "^8.18.0",
|
|
103
104
|
"zod": "^3.23.0"
|
|
104
105
|
},
|