pyric-admin 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 +122 -32
  2. package/README.md.orig +49 -0
  3. package/package.json +3 -2
package/README.md CHANGED
@@ -1,49 +1,139 @@
1
- # pyric-admin
1
+ <p align="center">
2
+ <img src="https://pyric.dev/pyric-logo.svg" alt="Pyric" width="180" />
3
+ </p>
2
4
 
3
- Firebase Admin-shaped adapters that can run against either a Pyric sandbox or
4
- real Firebase Admin SDK backends.
5
+ <h1 align="center">Firebase that runs in the browser</h1>
5
6
 
6
- Use `pyric-admin` when you want server/admin ergonomics while keeping the same
7
- backend-selection model as the client package.
7
+ <p align="center">Agentic coding without production consequences</p>
8
8
 
9
- > **Alpha.** This package is an early alpha. The admin-shaped subpaths are
10
- > best-effort mirror contracts of `firebase-admin` — not guaranteed parity.
11
- > Any exported surface beyond the mirrored shapes is experimental public-alpha
12
- > and may change without notice.
9
+ <p align="center"><a href="https://pyric.dev">pyric.dev</a></p>
13
10
 
14
- ## Subpaths
11
+ <br />
15
12
 
16
- | Subpath | Surface |
17
- |---|---|
18
- | `pyric-admin/app` | Admin app initialization for sandbox or production |
19
- | `pyric-admin/firestore` | Admin Firestore shape over sandbox or `firebase-admin/firestore` |
20
- | `pyric-admin/auth` | Admin Auth shape over sandbox or `firebase-admin/auth` |
21
- | `pyric-admin/database` | Admin Realtime Database shape over sandbox or `firebase-admin/database` |
22
- | `pyric-admin/storage` | Admin Storage shape over sandbox or `firebase-admin/storage` |
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.
23
14
 
24
- ## Example
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.
25
17
 
26
- ```ts
27
- import { initializeApp } from 'pyric-admin/app';
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
28
100
  import { initializeSandbox } from 'pyric/sandbox';
29
- import { getFirestore } from 'pyric-admin/firestore';
101
+ import { initializeApp } from 'pyric-admin/app';
102
+ import { getDatabase } from 'pyric-admin/database';
30
103
 
31
- const app = initializeApp({ sandbox: initializeSandbox() });
32
- const db = getFirestore(app);
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) |
33
116
 
34
- await db.collection('posts').doc('hello').set({ title: 'Hello' });
117
+ ```bash
118
+ npm install -D pyric-tools # the CLI; sufficient for most apps
119
+ npm install pyric pyric-admin # for direct sandbox control
35
120
  ```
36
121
 
37
- Production apps pass normal Firebase Admin credentials:
122
+ Node 22 or later. All packages are ESM-only with subpath exports (`pyric/firestore`, not `pyric`).
38
123
 
39
- ```ts
40
- import { initializeApp, cert } from 'pyric-admin/app';
124
+ ## Development
41
125
 
42
- const app = initializeApp({
43
- credential: cert(serviceAccount),
44
- });
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
45
133
  ```
46
134
 
47
- ## Docs
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
48
138
 
49
- - [Firestore docs](docs/firestore/)
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,49 @@
1
+ # pyric-admin
2
+
3
+ Firebase Admin-shaped adapters that can run against either a Pyric sandbox or
4
+ real Firebase Admin SDK backends.
5
+
6
+ Use `pyric-admin` when you want server/admin ergonomics while keeping the same
7
+ backend-selection model as the client package.
8
+
9
+ > **Alpha.** This package is an early alpha. The admin-shaped subpaths are
10
+ > best-effort mirror contracts of `firebase-admin` — not guaranteed parity.
11
+ > Any exported surface beyond the mirrored shapes is experimental public-alpha
12
+ > and may change without notice.
13
+
14
+ ## Subpaths
15
+
16
+ | Subpath | Surface |
17
+ |---|---|
18
+ | `pyric-admin/app` | Admin app initialization for sandbox or production |
19
+ | `pyric-admin/firestore` | Admin Firestore shape over sandbox or `firebase-admin/firestore` |
20
+ | `pyric-admin/auth` | Admin Auth shape over sandbox or `firebase-admin/auth` |
21
+ | `pyric-admin/database` | Admin Realtime Database shape over sandbox or `firebase-admin/database` |
22
+ | `pyric-admin/storage` | Admin Storage shape over sandbox or `firebase-admin/storage` |
23
+
24
+ ## Example
25
+
26
+ ```ts
27
+ import { initializeApp } from 'pyric-admin/app';
28
+ import { initializeSandbox } from 'pyric/sandbox';
29
+ import { getFirestore } from 'pyric-admin/firestore';
30
+
31
+ const app = initializeApp({ sandbox: initializeSandbox() });
32
+ const db = getFirestore(app);
33
+
34
+ await db.collection('posts').doc('hello').set({ title: 'Hello' });
35
+ ```
36
+
37
+ Production apps pass normal Firebase Admin credentials:
38
+
39
+ ```ts
40
+ import { initializeApp, cert } from 'pyric-admin/app';
41
+
42
+ const app = initializeApp({
43
+ credential: cert(serviceAccount),
44
+ });
45
+ ```
46
+
47
+ ## Docs
48
+
49
+ - [Firestore docs](docs/firestore/)
package/package.json CHANGED
@@ -1,6 +1,7 @@
1
1
  {
2
2
  "name": "pyric-admin",
3
- "version": "0.1.0-alpha.7",
3
+ "version": "0.1.0-alpha.8",
4
+ "homepage": "https://pyric.dev",
4
5
  "description": "Pyric admin-shape adapters (firestore, auth, database, storage) with swappable sandbox/prod backends. Mirrors firebase-admin.",
5
6
  "type": "module",
6
7
  "exports": {
@@ -35,7 +36,7 @@
35
36
  "typecheck": "bun x tsc -p tsconfig.json --noEmit"
36
37
  },
37
38
  "dependencies": {
38
- "pyric": "^0.1.0-alpha.7",
39
+ "pyric": "^0.1.0-alpha.8",
39
40
  "firebase-admin": "^13.0.0"
40
41
  },
41
42
  "devDependencies": {