create-feltkit 0.3.12 → 0.3.13

package/README.md

@@ -1,7 +1,7 @@
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rkendel1/feltkit/main/docs/assets/feltkit-logo-dark.png">
-    <img src="https://raw.githubusercontent.com/rkendel1/feltkit/main/docs/assets/feltkit-logo.png" alt="FeltKit" width="160">
+    <source media="(prefers-color-scheme: dark)" srcset="https://cdn.jsdelivr.net/npm/@feltdb/feltkit/docs/assets/feltkit-logo-dark.png">
+    <img src="https://cdn.jsdelivr.net/npm/@feltdb/feltkit/docs/assets/feltkit-logo.png" alt="FeltKit" width="160">
   </picture>
 </p>
 
@@ -29,4 +29,5 @@ npm run managed:setup
 
 The managed starter's README walks through setup, deployment and verification.
 
-Documentation: https://github.com/rkendel1/concave#readme
+Documentation: shipped with the package. In a project, run `npx feltkit docs` (or read
+`node_modules/@feltdb/feltkit/docs/`); online: <https://cdn.jsdelivr.net/npm/@feltdb/feltkit/docs/README.md>.

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "create-feltkit",
-  "version": "0.3.12",
+  "version": "0.3.13",
   "description": "Create a FeltKit application: npm create feltkit@latest my-app (add -- --template managed for Managed FeltDB)",
   "license": "MIT",
   "type": "module",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/rkendel1/concave.git",
+    "url": "git+https://github.com/rkendel1/feltkit.git",
     "directory": "packages/create"
   },
   "engines": {
@@ -33,5 +33,6 @@
     "build": "node sync-template.mjs",
     "prepack": "node sync-template.mjs",
     "test": "node --test test/*.test.mjs"
-  }
+  },
+  "homepage": "https://www.npmjs.com/package/create-feltkit"
 }

package/template/README.md

@@ -92,13 +92,21 @@ Configure each one in **Studio → Services**: every service has its own screen,
 operation there is authorized as the dev user you choose with **Act as**. From a function:
 
 ```ts
+// Effects that announce this mutation's change: performed only if it commits (mutations only).
+ctx.afterCommit.webhooks.emit("task.created", { id });
+ctx.afterCommit.notifications.send({ recipient: "grace", type: "task.completed", title: "Done" });
+ctx.afterCommit.jobs.enqueue("projects.clear-completed", {});
+// Reads and stored files, right away:
 await ctx.services.files.upload({ name: "notes.txt", content: text });
-await ctx.services.notifications.send({ recipient: "grace", type: "task.completed", title: "Done" });
-await ctx.services.webhooks?.emit("task.created", { id });       // mutations only
-await ctx.services.jobs?.enqueue("projects.clear-completed", {}); // mutations only
 const greeting = await ctx.services.configuration.get("GREETING");
 ```
 
+Use `ctx.afterCommit` for anything that tells the world about the mutation's change. The same
+calls on `ctx.services` (`ctx.services.webhooks.emit`, `…notifications.send`, `…jobs.enqueue`)
+happen immediately and stay done even if the mutation then fails (a `CONFLICT` at commit), so
+receivers would hear about a change that never happened. `npx feltkit outbox list` shows every
+after-commit effect and its state.
+
 The starter already uses them: creating and completing a task emits `task.created` and
 `task.completed` to any registered webhook endpoint; completing someone else's task notifies
 its creator; and the job `projects.clear-completed` runs `projects:clearCompleted`.
@@ -121,8 +129,12 @@ service off, remove it from `services`.
 
 **Studio → Integrations → Connect an API** reads an OpenAPI document (JSON) or lets you
 describe the operations yourself, then writes `feltkit/<name>.ts` and grants `<name>.*` to the
-roles you choose. Each operation becomes a capability your functions, the agent and other apps
-can call (`<name>.<operation>`), with its permission, and every call recorded. The API key is
+roles you choose. Each operation becomes an AppPort capability (`<name>.<operation>`) with its
+permission, and every call is recorded. It is called through AppPort, not from a query or
+mutation: by the agent (MCP tools, proposals), by other apps and scripts (`POST /appport`), and by
+your frontend with an AppPort request carrying the session token. To act on the result inside
+your app, name a mutation in the operation's `onOutcome`: it runs as the caller with the call's
+record when the call finishes (success or failure). The API key is
 stored in FeltKit's custody; in production set `<NAME>_URL` and `FELTKIT_CREDENTIAL_<NAME>`.
 Then narrow each operation's `output` schema in that file to what the API returns.
 
@@ -360,4 +372,7 @@ operate this app.
 - Errors carry a code (`FORBIDDEN`, `INVALID_ARGUMENT`, `NOT_FOUND`, …) and usually a hint with
   the fix.
 
-FeltKit documentation: <https://github.com/rkendel1/feltkit#readme>
+FeltKit documentation ships with the package: `npx feltkit docs` lists it (guarantees, transactions,
+security, agents, path to production, backup) and `npx feltkit docs <name>` prints one. The same files
+are in `node_modules/@feltdb/feltkit/docs/`, and online at
+<https://cdn.jsdelivr.net/npm/@feltdb/feltkit/docs/README.md>.

package/template/feltkit/app.ts

@@ -19,7 +19,8 @@ export const app = feltkit({
     // Viewers read. They can see agent tasks but not start or approve them.
     viewer: ["projects.read", "tasks.read", "files.read", "notifications.read", "feltkit.agent.read"],
     // Agents can read, complete tasks, and leave notes. They cannot create or delete.
-    agent: ["projects.read", "tasks.read", "tasks.complete", "tasks.note", "files.read", "files.write", "notifications.send", "webhooks.emit", "webhooks.deliver"],
+    // feltkit.agent.*: discover the app (feltkit_context), work tasks, propose actions; a person approves.
+    agent: ["projects.read", "tasks.read", "tasks.complete", "tasks.note", "files.read", "files.write", "notifications.send", "webhooks.emit", "webhooks.deliver", "feltkit.agent.*"],
     // Admins configure the app in Studio → Services: the model (intelligence.*), stored
     // credentials (credential.*), configuration, API keys, webhooks, jobs, and schedules.
     // Credentials are stored by reference; the value never enters FeltDB.

package/template/feltkit/tasks.ts

@@ -42,7 +42,8 @@ export const create = app.mutation({
       createdBy: ctx.auth.requirePrincipal().id,
     });
     // Delivered, signed, to every webhook endpoint registered for "task.created" (Studio → Services → Webhooks).
-    await ctx.services.webhooks?.emit("task.created", { id, projectId, title: title.trim() });
+    // ctx.afterCommit: only if this mutation commits (ctx.services.* effects happen even if it does not).
+    ctx.afterCommit.webhooks.emit("task.created", { id, projectId, title: title.trim() });
     return id;
   },
 });
@@ -67,10 +68,10 @@ export const setDone = app.mutation({
     const who = ctx.auth.requirePrincipal().id;
     const task = await ctx.db.patch(tasks, id, done ? { done: true, completedAt: Date.now(), completedBy: who } : { done: false, completedAt: undefined, completedBy: undefined });
     if (done) {
-      await ctx.services.webhooks?.emit("task.completed", { id: task.id, projectId: task.projectId, completedBy: who });
+      ctx.afterCommit.webhooks.emit("task.completed", { id: task.id, projectId: task.projectId, completedBy: who });
       // Tell whoever created the task, when someone else completes it.
       if (task.createdBy !== who) {
-        await ctx.services.notifications.send({ recipient: task.createdBy, type: "task.completed", title: `${who} completed "${task.title}"`, data: { taskId: task.id }, idempotencyKey: `task.completed:${task.id}:${task.completedAt}` });
+        ctx.afterCommit.notifications.send({ recipient: task.createdBy, type: "task.completed", title: `${who} completed "${task.title}"`, data: { taskId: task.id }, idempotencyKey: `task.completed:${task.id}:${task.completedAt}` });
       }
     }
     return { id: task.id, done: task.done };

package/template/package.json

@@ -13,7 +13,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@feltdb/feltkit": "0.3.12",
+    "@feltdb/feltkit": "0.3.13",
     "react": "19.2.0",
     "react-dom": "19.2.0"
   },

package/template-managed/package.json

@@ -20,10 +20,10 @@
     "deploy:fly": "node scripts/deploy-fly.mjs"
   },
   "dependencies": {
-    "@feltdb/feltkit": "0.3.12"
+    "@feltdb/feltkit": "0.3.13"
   },
   "devDependencies": {
-    "@feltdb/core": ">=0.18.0 <1.0.0",
+    "@feltdb/core": ">=0.21.0 <1.0.0",
     "@types/node": "22.19.1",
     "typescript": "5.9.3"
   }