@mortar-ai/skill 0.1.0 → 0.3.0

package/README.md

@@ -1,8 +1,8 @@
 # @mortar-ai/skill
 
-[Claude Code](https://claude.ai/code) skill package for building on
-**Mortar** (the BaaS that AI bundles talk to).  Drop it into your skills
-directory + Claude becomes instantly Mortar-fluent: knows the SDK
+[Agent Skills](https://agentskills.io/) package for building on **Mortar** (the
+BaaS that AI bundles talk to). Install the canonical `SKILL.md` into a compatible
+agent's skill directory to teach it the SDK
 accessors, CLI commands, MCP tools, and — most importantly — the
 tenant-isolation + `auth.tenant_id()` RLS rules that are the easiest
 thing to get wrong.
@@ -17,6 +17,12 @@ mortar-skill-install
 
 Then restart Claude Code (or `/skill reload`).
 
+The same versioned `SKILL.md` is packaged into Fabric Harness. `manifest.json`
+binds the npm version and Harness preinstall to its SHA-256 digest; the Fabric
+Server rejects a Market install when the running Harness reports different
+bytes. npm is an external distribution channel and is not required by Fabric at
+runtime.
+
 Pairs naturally with the [Mortar MCP server](../mcp) — the skill teaches Claude
 *how* to think about Mortar; the MCP gives it live tools to *act* on a
 project.  Install both for the full Supabase-plugin-equivalent
@@ -29,6 +35,12 @@ The skill teaches Claude:
 - **SDK surface** — the `mortar.from()` / `auth` / `storage` /
   `realtime` / `compute` / `usage` / `cron` / `queue` / `comms`
   accessors + the account-scope `AccountClient`; which one to reach for
+- **Transaction boundaries** — atomic row batches and filtered mutations,
+  trusted cross-table row + PostgreSQL queue transactions, and why privileged
+  transaction clients must never enter browser/mobile bundles
+- **Storage consistency** — immutable physical object versions, atomic metadata
+  pointer switches, durable cleanup, and why object storage is not part of a
+  PostgreSQL ACID transaction
 - **CLI commands** — `mortar login / use / db / storage / compute /
   cron / queue / domains / comms / keys / tokens / topup / usage`
 - **MCP tools** — the 40 `mortar_*` tools and when an agent should use
@@ -56,6 +68,19 @@ Useful for team-shared skill repositories or in-repo skill packs.
 Re-run `mortar-skill-install` after `npm update @mortar-ai/skill`.
 Idempotent — overwrites in place.
 
+## Maintainer release
+
+`SKILL.md` is the only hand-edited instruction source. Regenerate the manifest
+and Harness copy before testing or publishing:
+
+```bash
+npm run sync
+npm run check
+npm pack --dry-run
+```
+
+Never edit `fabric/harness/internal/skills/preinstalled/mortar/` directly.
+
 ## License
 
 Apache-2.0 (same as the rest of Mortar).

package/{mortar-skill.md → SKILL.md}

@@ -1,10 +1,11 @@
 ---
-name: Mortar
-description: Required guidance for Fabric apps that need a database, backend, authentication, persistence, file storage, realtime collaboration, cloud functions, or product analytics.
-activation: auto
-priority: high
-triggers:
-  - keywords: [database, 数据库, backend, 后端, auth, authentication, 登录, 认证, persistence, 持久化, storage, upload, 文件, realtime, 实时, collaboration, compute, cloud, 云端]
+name: mortar
+description: Build or change Fabric applications that use Mortar for database, auth, storage, realtime, compute, or analytics. Use for Mortar schema and provisioning, SDK integration, RLS, transactions, or storage consistency; not for Fabric's own control plane or a different backend.
+metadata:
+  activation: auto
+  priority: high
+  triggers:
+    - keywords: [database, 数据库, backend, 后端, auth, authentication, 登录, 认证, persistence, 持久化, transaction, 事务, ACID, storage, upload, 文件, realtime, 实时, collaboration, compute, cloud, 云端]
 ---
 
 # Mortar for Fabric applications
@@ -59,14 +60,16 @@ below; if platform provisioning fails, report that platform failure.
    tenant. Do not edit or create `mortar.config.json`. Do not edit generated
    `integrations/mortar/types.ts`; Fabric regenerates it from the live schema.
 4. Run `npm install @mortar-ai/client` if the dependency is absent, then write app
-   code using the injected singleton.
-5. Type-check and build. Handle every `{ data, error }` result in UI code.
-
-Example schema operations (the tool schema is authoritative for all fields):
-
-```json
-{"kind":"create_table","table":"todos","access":"private","columns":[{"name":"title","type":"text","required":true},{"name":"done","type":"bool"},{"name":"user_id","type":"uuid","required":true}]}
-```
+   code using the injected singleton. Atomic batches, server-side filtered
+   mutations, and `DatabaseTransactions` require `@mortar-ai/client` 0.8.0 or
+   newer. If an existing project needs one of those capabilities and pins an
+   older version, update that dependency with npm and let npm update its lockfile;
+   do not rewrite unrelated dependencies.
+5. Before writing a multi-step mutation, choose the supported consistency
+   boundary: one-table batches and filtered mutations can use the bundle-safe
+   singleton; cross-table row + queue transactions require trusted server code;
+   object storage and external services never join a PostgreSQL transaction.
+6. Type-check and build. Handle every `{ data, error }` result in UI code.
 
 Supported migration kinds are `create_table`, `drop_table`, `set_table_access`,
 `add_column`, `drop_column`, `create_index`, `set_bucket_access`, `deploy_function`, `delete_function`,
@@ -109,21 +112,86 @@ const { data: created, error: insertError } = await mortar
   .insert({ title: 'Ship', done: false, user_id: userId })
   .select()
   .single();
+```
+
+Updates and deletes use the same filter chain. Useful operators include `eq`,
+`neq`, ranges, `like/ilike`, `in`, `is`, `order`, `limit`, `single`, and
+`maybeSingle`.
 
-const { data: updated, error: updateError } = await mortar
+### Atomic row mutations
+
+Pass an array when every insert or upsert must succeed or fail together. Mortar
+sends at most 200 rows in one request and executes the batch in one
+tenant-scoped PostgreSQL transaction. For upsert, a row with an `id` replaces
+that row's data; a row without an `id` inserts. Do not use a loop or
+`Promise.all` when partial completion would break an invariant.
+
+```ts
+const { data: createdTodos, error: batchError } = await mortar
   .from('todos')
-  .update({ done: true })
-  .eq('id', todoId)
+  .insert([
+    { title: 'Prepare', done: false, user_id: userId },
+    { title: 'Ship', done: false, user_id: userId },
+  ])
   .select();
+if (batchError) throw new Error(batchError.message);
 
-const { error: deleteError } = await mortar
+const { data: changedTodos, error: updateError } = await mortar
   .from('todos')
-  .delete()
-  .eq('id', todoId);
+  .update({ done: true })
+  .eq('user_id', userId)
+  .eq('archived', false)
+  .select();
+if (updateError) throw new Error(updateError.message);
 ```
 
-Useful chaining includes `eq`, `neq`, `gt/gte`, `lt/lte`, `like/ilike`, `in`,
-`is`, `order`, `range`, `limit`, `single`, and `maybeSingle`.
+Filtered `update` and `delete` select and mutate all matching rows inside one
+server-side transaction. Do not pre-select IDs and then update/delete them one
+at a time: that creates a race and loses the all-or-nothing guarantee. Chain
+`.select()` only when the app needs the affected rows returned.
+
+### Cross-table transactions are server-only
+
+`DatabaseTransactions` can atomically combine up to 200 cross-table row
+`insert` / by-ID `update` / by-ID `delete` operations and PostgreSQL-backed
+queue `enqueue` operations. It is intentionally not attached to the injected
+`mortar` singleton and requires an `app` or `admin` key. Its `execute` method
+throws on failure, so use `try`/`catch`, not a `{ data, error }` envelope.
+
+```ts
+import { DatabaseTransactions } from '@mortar-ai/client';
+
+const transactions = new DatabaseTransactions(serverOnlyMortarOptions);
+
+try {
+  const results = await transactions.execute([
+    { op: 'insert', table: 'orders', data: { customer_id: customerId, total } },
+    { op: 'enqueue', type: 'send_receipt', payload: { customer_id: customerId } },
+  ]);
+  console.log(results);
+} catch (error) {
+  // Nothing committed. Report or retry the whole idempotent operation.
+  throw error;
+}
+```
+
+Never instantiate `DatabaseTransactions` in Web, Desktop renderer,
+Keel/React Native, or WeChat client code. Never add an app/admin key to a
+client-side environment variable or source file. Use this API only in an
+already-approved trusted server environment that holds the key. If a Fabric
+project has no such path, report cross-table ACID as unsupported instead of
+simulating it with several public-client calls. A transactional queue enqueue
+also requires Mortar's PostgreSQL queue backend; otherwise the whole request
+fails without committing row changes.
+
+### Exact ACID boundary
+
+Mortar provides true ACID only for work executed in the same tenant-scoped
+PostgreSQL transaction: atomic row batches, filtered row mutations, and the
+trusted cross-table row + PostgreSQL queue API above. Object storage,
+compute/functions, communications providers, analytics delivery, and other
+external systems do not participate in that transaction. Never describe a
+workflow spanning them as one ACID transaction or claim two-phase commit.
 
 ## App-user authentication
 
@@ -139,15 +207,12 @@ const verified = await mortar.auth.verifyOtp({ email, token });
 
 const { data: sessionData } = await mortar.auth.getSession();
 const { data: userData, error: userError } = await mortar.auth.getUser();
-
-const { data: listener } = mortar.auth.onAuthStateChange((event, session) => {
-  // INITIAL_SESSION | SIGNED_IN | SIGNED_OUT | TOKEN_REFRESHED
-});
-listener.subscription.unsubscribe();
-
 await mortar.auth.signOut();
 ```
 
+Use `onAuthStateChange` when UI must react to session changes, and unsubscribe
+the returned subscription during cleanup.
+
 Password reset starts with `mortar.auth.resetPasswordForEmail(email)`; confirm via
 `passwordResetConfirm(email, token, newPassword)`. Never store or pass session
 tokens manually unless the user explicitly needs a server integration.
@@ -171,6 +236,22 @@ const { data: signed, error: signError } = await bucket.createSignedUrl(path, 36
 const { error: removeError } = await bucket.remove([path]);
 ```
 
+Applications address files by their stable logical `path`. Mortar stores new
+uploads under immutable internal physical versions, then atomically switches
+its PostgreSQL metadata pointer and durably schedules orphan/replaced versions
+for retryable cleanup. Never construct, persist, or expose Mortar's internal
+physical object key. Existing logical paths remain compatible, and application
+projects do not run or author the platform storage migration.
+
+This protocol keeps Mortar's own file metadata from pointing at a partial
+upload, but it does not make a separate application row and an object upload
+one transaction. When a business row must reference a file, generate an
+unguessable logical key. For a simple workflow, upload first and write the
+business row only after upload succeeds. For recoverable workflows, create a
+row with a stable idempotency key and `pending` state, upload, then mark it
+`ready`; reconcile stale rows to `failed` or retry them. Do not issue a database
+write and `bucket.upload()` concurrently and call the result atomic.
+
 Downloads mint a short-lived URL and fetch the object directly from the storage
 backend. Reuse `signed.signedUrl` until it nears expiry when rendering media.
 Prefer the signed URL directly in `<img src>`, `<video src>`, or `<audio src>`;
@@ -180,16 +261,9 @@ budget, but clients should still lazy-load visible media and cache/reuse each
 URL instead of signing again on every render. Signing authorizes a possible
 download; it does not prove bytes were served and must never be described or
 modeled as an object-egress charge. Only provider-observed access-log or billing
-reconciliation may record actual object egress. Use the third
-`createSignedUrl` argument to bound only the signing request when the UI needs
-a deadline:
-
-```ts
-const { data: signed, error } = await bucket.createSignedUrl(path, 900, {
-  signal: controller.signal,
-  timeoutMs: 10_000,
-});
-```
+reconciliation may record actual object egress. The optional third
+`createSignedUrl` argument (`{ signal, timeoutMs }`) bounds only the signing
+request when the UI needs a deadline.
 
 `bucket.download(path)` uses JavaScript `fetch()` against the object store and
 therefore needs a matching bucket CORS rule in browsers. Appunvs-managed Mortar
@@ -223,26 +297,10 @@ realtime only notifies peers.
 
 ## Compute and analytics
 
-Invoke only functions already deployed through `mortar_migrate`:
-
-```ts
-const response = await mortar.compute.invoke({
-  name: 'summarize',
-  method: 'POST',
-  body: JSON.stringify({ text }),
-  contentType: 'application/json',
-});
-if (!response.ok) throw new Error(await response.text());
-```
-
-Analytics calls are fire-and-forget except `flush`:
-
-```ts
-mortar.analytics.track('pageview', { path: location.pathname });
-mortar.analytics.identify(user.id, { plan: 'free' });
-mortar.analytics.captureError(error, { screen: 'checkout' });
-await mortar.analytics.flush();
-```
+Invoke only functions already deployed through `mortar_migrate`; check
+`response.ok` and read the response body. Analytics provides `track`,
+`identify`, `captureError`, and `flush`; events are fire-and-forget except
+`flush`.
 
 ## Boundary for non-Fabric development
 

package/bin/install.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * mortar-skill-install — copies mortar-skill.md into the user's Claude
+ * mortar-skill-install — copies the canonical SKILL.md into the user's Claude
  * Code skills directory.
  *
  * Default destination: `~/.claude/skills/mortar/SKILL.md`.  Override
@@ -26,7 +26,7 @@ function parseFlags(argv) {
 
 function main() {
   const flags = parseFlags(process.argv);
-  const src = resolve(__dirname, '..', 'mortar-skill.md');
+  const src = resolve(__dirname, '..', 'SKILL.md');
   if (!existsSync(src)) {
     console.error(`mortar-skill: source missing at ${src}`);
     process.exit(1);

package/index.js

@@ -9,7 +9,8 @@
 const { readFileSync } = require('node:fs');
 const { resolve } = require('node:path');
 
-const SKILL_PATH = resolve(__dirname, 'mortar-skill.md');
+const SKILL_PATH = resolve(__dirname, 'SKILL.md');
+const MANIFEST_PATH = resolve(__dirname, 'manifest.json');
 
 module.exports = {
   /**
@@ -20,5 +21,9 @@ module.exports = {
   skillContents() {
     return readFileSync(SKILL_PATH, 'utf8');
   },
+  manifest() {
+    return JSON.parse(readFileSync(MANIFEST_PATH, 'utf8'));
+  },
   SKILL_PATH,
+  MANIFEST_PATH,
 };

package/manifest.json

@@ -0,0 +1,16 @@
+{
+  "schema_version": 1,
+  "id": "mortar",
+  "version": "0.3.0",
+  "content_sha256": "sha256:c69dab74ad4a377086c0c883c4d400770600738de2741778fad21ec27e925f27",
+  "source_repo": "liamxujia/appunvs",
+  "source_path": "mortar/skill/SKILL.md",
+  "distributions": [
+    "harness_preinstalled",
+    "npm"
+  ],
+  "npm": {
+    "package": "@mortar-ai/skill",
+    "version": "0.3.0"
+  }
+}

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@mortar-ai/skill",
-  "version": "0.1.0",
-  "description": "Claude Code skill package for building on Mortar (BaaS). Drop `mortar-skill.md` into ~/.claude/skills/mortar/ to give Claude expert-level guidance about the Mortar SDK / CLI / MCP, tenant isolation + auth.tenant_id() RLS, and the 9 primitive × feature model.",
+  "version": "0.3.0",
+  "description": "Agent skill package for building Fabric applications on Mortar (BaaS), distributed from one versioned SKILL.md with a content-addressed manifest.",
   "main": "index.js",
-  "files": ["mortar-skill.md", "index.js", "README.md"],
+  "files": ["SKILL.md", "manifest.json", "index.js", "README.md"],
   "bin": {
     "mortar-skill-install": "bin/install.js"
   },
+  "scripts": {
+    "sync": "node scripts/sync-distributions.js",
+    "check": "node scripts/sync-distributions.js --check"
+  },
   "publishConfig": { "access": "public" },
   "license": "Apache-2.0"
 }