@lantharos/pult 0.0.0-stage → 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lantharos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# @lantharos/pult
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The other side of your app. Describe your inboxes, resources, actions, pages and flags in code next to your app, and Pult turns them into a console your team runs the product from. Every action runs back inside your app.
+
+```bash
+bun add @lantharos/pult
+```
+
+Then run `bunx pult init` to set up a config, a first resource and inbox, and the client. Everything is imported from `"@lantharos/pult"`, and the package also gives you the `pult` command.
+
+Resources are the records your team looks up and acts on, and flags can target them:
+
+```ts
+// src/users/user.pult.ts
+import { b, flag, resource } from "@lantharos/pult"
+import { z } from "zod"
+
+export const user = resource("user", {
+  get: (id) => db.user.byId(id),
+  find: (query) => db.user.search(query),
+  title: (u) => u.username,
+  render: (u) => [b.fields({ email: b.sensitive(u.email), plan: u.plan })],
+  actions: (action) => ({
+    ban: action({
+      input: z.object({ reason: z.string().min(3) }),
+      when: (u) => u.banned === null,
+      danger: "reauth",
+      run: ({ record, input }) => banUser(record.id, input.reason),
+    }),
+  }),
+})
+
+export const newEditor = flag("new-editor", { target: user })
+```
+
+Inboxes collect what needs a look, each item linked to the record it's about:
+
+```ts
+// src/users/reports.pult.ts
+import { b, inbox } from "@lantharos/pult"
+import { z } from "zod"
+import { user } from "./user.pult"
+
+export const reports = inbox("reports", {
+  resource: user,
+  data: z.object({ reason: z.string(), body: z.string() }),
+  title: (data) => data.reason,
+  render: (item) => [b.markdown(item.data.body), b.actions("ban")],
+})
+```
+
+Your app sends items as things happen and reads flags where it needs them:
+
+```ts
+// src/pult.ts
+import { createPult } from "@lantharos/pult"
+import project from "../.pult"
+import { reports } from "./users/reports.pult"
+import { newEditor } from "./users/user.pult"
+
+export const pult = createPult({ project })
+pult.listen()
+
+export async function report(userId: string, reason: string, body: string) {
+  await pult.send(reports, { record: userId, fingerprint: userId, data: { reason, body } })
+}
+
+export const editorFor = (userId: string) => pult.flag(newEditor, userId)
+```
+
+On Cloudflare Workers, set `delivery: { mode: "webhook", path: "/pult" }` in `pult.config.ts` and hand those requests to `pult.handler()` instead of calling `listen()`.
+
+The `pult` command sets up, builds, checks and deploys your definitions:
+
+- `pult init` writes a config, a first resource and inbox, and the client.
+- `pult build` compiles your definitions into `.pult/`. Commit it.
+- `pult check` catches broken references and stale builds. Run it in CI.
+- `pult diff` shows what a deploy would change, including who gains which permission.
+- `pult deploy` pushes your definitions to the environment behind `PULT_KEY`.
+- `pult dev` rebuilds on every change.
+
+Everything else is in the [docs](https://docs.pult.sh).
+
+## License
+
+MIT