@pylonsync/create-pylon 0.3.51 → 0.3.54

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pylonsync/create-pylon",
-  "version": "0.3.51",
-  "description": "Scaffold a new Pylon app — realtime backend + Next.js frontend in one command. Run via `npm create @pylonsync/pylon@latest`.",
+  "version": "0.3.54",
+  "description": "Scaffold a new Pylon app — realtime backend + web/mobile/expo frontends in one command. Run via `npm create @pylonsync/pylon@latest`.",
   "publishConfig": {
     "access": "public"
   },
@@ -10,7 +10,8 @@
     "create-pylon": "./bin/create-pylon.js"
   },
   "files": [
-    "bin"
+    "bin",
+    "templates"
   ],
   "engines": {
     "node": ">=18"

package/templates/_root/.env.example

@@ -0,0 +1,9 @@
+# Backend port the Pylon control plane listens on.
+PYLON_PORT=4321
+
+# Where the Next.js dev server can reach the control plane.
+PYLON_TARGET=http://localhost:4321
+
+# Cookie name the auth helpers look for.
+# Pattern: `${app_name}_session` from the Pylon manifest.
+PYLON_COOKIE_NAME=__APP_NAME_SNAKE___session

package/templates/_root/README.md

@@ -0,0 +1,43 @@
+# __APP_NAME__
+
+Scaffolded by [@pylonsync/create-pylon](https://npmjs.com/@pylonsync/create-pylon).
+
+## Layout
+
+```
+apps/
+  api/         Pylon backend — schema, policies, function handlers
+  web/         Next.js frontend (if you picked --platforms web)
+  mobile/      Swift / SwiftUI app (if you picked --platforms mobile)
+  expo/        Expo + React Native app (if you picked --platforms expo)
+
+packages/
+  ui/          Shared shadcn-style React primitives (web only)
+```
+
+## Getting started
+
+```sh
+# Install
+bun install   # or pnpm install / yarn / npm install
+
+# Run everything (the API + every frontend you picked)
+bun run dev
+```
+
+- **api** on http://localhost:4321 — Pylon control plane
+- **web** on http://localhost:3000 — Next.js (if scaffolded)
+- **expo** runs Metro on a separate port (if scaffolded)
+- **mobile** lives in `apps/mobile/` — open in Xcode or run `swift run`
+
+## What to do next
+
+- Edit `apps/api/schema.ts` to add entities + policies.
+- Drop handlers into `apps/api/functions/` — auto-discovered by name.
+- For web: components in `apps/web/src/app/components/`.
+- For mobile: SwiftUI views in `apps/mobile/Sources/__APP_NAME_PASCAL__/`.
+- For expo: screens in `apps/expo/src/screens/`.
+
+## Docs
+
+[pylonsync.com/docs](https://pylonsync.com/docs)

package/templates/backend/b2b/apps/api/functions/archiveProject.ts

@@ -0,0 +1,15 @@
+import { mutation, v } from "@pylonsync/functions";
+
+/**
+ * Soft-delete: set archived = true. Project policy gates updates to
+ * org owner/admin only, so a regular member can't archive a project
+ * even if they created it. Restore by writing archived = false (this
+ * scaffold doesn't ship a restore action — left as an exercise).
+ */
+export default mutation({
+	args: { id: v.id("Project") },
+	async handler(ctx, args: { id: string }) {
+		await ctx.db.update("Project", args.id, { archived: true });
+		return await ctx.db.get("Project", args.id);
+	},
+});

package/templates/backend/b2b/apps/api/functions/createOrg.ts

@@ -0,0 +1,43 @@
+import { mutation, v } from "@pylonsync/functions";
+
+/**
+ * Create a new Org with the caller as owner. Atomically writes the
+ * Org row + the founding Membership; both must succeed or neither
+ * does (Pylon mutations run in a single transaction).
+ */
+export default mutation({
+	args: { slug: v.string(), name: v.string() },
+	async handler(ctx, args: { slug: string; name: string }) {
+		if (!ctx.auth.userId) {
+			throw ctx.error("UNAUTHENTICATED", "log in first");
+		}
+		const slug = args.slug.trim().toLowerCase();
+		if (!/^[a-z0-9][a-z0-9-]{1,30}[a-z0-9]$/.test(slug)) {
+			throw ctx.error(
+				"INVALID_SLUG",
+				"slug must be 3–32 chars, alphanumeric + dashes, no leading/trailing dash",
+			);
+		}
+		const name = args.name.trim();
+		if (!name) {
+			throw ctx.error("EMPTY_NAME", "org name cannot be empty");
+		}
+		const dup = (await ctx.db.query("Org", { slug })) as any[];
+		if (dup.length > 0) {
+			throw ctx.error("SLUG_TAKEN", `org slug "${slug}" is taken`);
+		}
+		const orgId = await ctx.db.insert("Org", {
+			slug,
+			name,
+			ownerId: ctx.auth.userId,
+			createdAt: new Date().toISOString(),
+		});
+		await ctx.db.insert("Membership", {
+			orgId,
+			userId: ctx.auth.userId,
+			role: "owner",
+			createdAt: new Date().toISOString(),
+		});
+		return await ctx.db.get("Org", orgId);
+	},
+});

package/templates/backend/b2b/apps/api/functions/createProject.ts

@@ -0,0 +1,25 @@
+import { mutation, v } from "@pylonsync/functions";
+
+/**
+ * Create a Project inside an Org. Project policy already gates this
+ * to org members; we additionally trim the name and stamp the caller
+ * as creator.
+ */
+export default mutation({
+	args: { orgId: v.id("Org"), name: v.string() },
+	async handler(ctx, args: { orgId: string; name: string }) {
+		if (!ctx.auth.userId) {
+			throw ctx.error("UNAUTHENTICATED", "log in first");
+		}
+		const name = args.name.trim();
+		if (!name) throw ctx.error("EMPTY_NAME", "project name cannot be empty");
+		const id = await ctx.db.insert("Project", {
+			orgId: args.orgId,
+			name,
+			createdBy: ctx.auth.userId,
+			archived: false,
+			createdAt: new Date().toISOString(),
+		});
+		return await ctx.db.get("Project", id);
+	},
+});

package/templates/backend/b2b/apps/api/functions/inviteMember.ts

@@ -0,0 +1,49 @@
+import { mutation, v } from "@pylonsync/functions";
+
+/**
+ * Add a User to an Org with a role. Membership policy already gates
+ * this to owners / admins; we additionally validate the role string
+ * here (Pylon enforces enum at the schema level too, but a clearer
+ * error message is nicer than a generic constraint failure).
+ *
+ * For a real app, replace this with an email-invite flow that emits
+ * an Invite row + emails the user — but the wiring is the same: the
+ * Membership row is what grants access.
+ */
+const ROLES = new Set(["owner", "admin", "member"]);
+
+export default mutation({
+	args: {
+		orgId: v.id("Org"),
+		userId: v.id("User"),
+		role: v.string(),
+	},
+	async handler(
+		ctx,
+		args: { orgId: string; userId: string; role: string },
+	) {
+		if (!ROLES.has(args.role)) {
+			throw ctx.error(
+				"INVALID_ROLE",
+				`role must be one of ${[...ROLES].join(", ")}`,
+			);
+		}
+		const dup = (await ctx.db.query("Membership", {
+			orgId: args.orgId,
+			userId: args.userId,
+		})) as any[];
+		if (dup.length > 0) {
+			throw ctx.error(
+				"ALREADY_MEMBER",
+				"user is already a member of this org",
+			);
+		}
+		const id = await ctx.db.insert("Membership", {
+			orgId: args.orgId,
+			userId: args.userId,
+			role: args.role,
+			createdAt: new Date().toISOString(),
+		});
+		return await ctx.db.get("Membership", id);
+	},
+});

package/templates/backend/b2b/apps/api/functions/myOrgs.ts

@@ -0,0 +1,37 @@
+import { query } from "@pylonsync/functions";
+
+/**
+ * List every Org the caller belongs to. Joins Membership against Org
+ * so the response carries everything the org switcher needs to render
+ * a row (name, slug, the caller's role).
+ */
+export default query({
+	args: {},
+	async handler(ctx) {
+		if (!ctx.auth.userId) return [];
+		const memberships = await ctx.db.query("Membership", {
+			userId: ctx.auth.userId,
+		});
+		const out: Array<{
+			id: string;
+			slug: string;
+			name: string;
+			role: string;
+			createdAt: string;
+		}> = [];
+		for (const m of memberships as any[]) {
+			const org = (await ctx.db.get("Org", m.orgId)) as any;
+			if (!org) continue;
+			out.push({
+				id: org.id,
+				slug: org.slug,
+				name: org.name,
+				role: m.role,
+				createdAt: org.createdAt,
+			});
+		}
+		return out.sort((a, b) =>
+			Date.parse(b.createdAt) - Date.parse(a.createdAt),
+		);
+	},
+});

package/templates/backend/b2b/apps/api/functions/orgMembers.ts

@@ -0,0 +1,13 @@
+import { query, v } from "@pylonsync/functions";
+
+/**
+ * List every member of an Org. Membership policy gates this to
+ * org-admins + owners (members see only their own row), so non-admin
+ * callers get a single-element array; admins get everyone.
+ */
+export default query({
+	args: { orgId: v.id("Org") },
+	async handler(ctx, args: { orgId: string }) {
+		return await ctx.db.query("Membership", { orgId: args.orgId });
+	},
+});

package/templates/backend/b2b/apps/api/functions/orgProjects.ts

@@ -0,0 +1,18 @@
+import { query, v } from "@pylonsync/functions";
+
+/**
+ * Every Project in an Org. Project policy enforces tenant scope, so
+ * even if the caller passes a foreign `orgId` they're not a member of,
+ * the query returns nothing.
+ */
+export default query({
+	args: { orgId: v.id("Org") },
+	async handler(ctx, args: { orgId: string }) {
+		const rows = (await ctx.db.query("Project", {
+			orgId: args.orgId,
+		})) as any[];
+		return rows
+			.filter((r) => !r.archived)
+			.sort((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt));
+	},
+});

package/templates/backend/b2b/apps/api/functions/removeMember.ts

@@ -0,0 +1,29 @@
+import { mutation, v } from "@pylonsync/functions";
+
+/**
+ * Remove a User from an Org. Refuses to remove the org's owner
+ * (transfer ownership first via setMemberRole + a manual Org.ownerId
+ * update — left as an exercise; this scaffold stops at the safety
+ * check).
+ */
+export default mutation({
+	args: { orgId: v.id("Org"), userId: v.id("User") },
+	async handler(ctx, args: { orgId: string; userId: string }) {
+		const org = (await ctx.db.get("Org", args.orgId)) as any;
+		if (!org) throw ctx.error("NOT_FOUND", "org not found");
+		if (org.ownerId === args.userId) {
+			throw ctx.error(
+				"OWNER_CANT_LEAVE",
+				"the org owner can't be removed; transfer ownership first",
+			);
+		}
+		const memberships = (await ctx.db.query("Membership", {
+			orgId: args.orgId,
+			userId: args.userId,
+		})) as any[];
+		for (const m of memberships) {
+			await ctx.db.delete("Membership", m.id);
+		}
+		return memberships[0] ?? null;
+	},
+});

package/templates/backend/b2b/apps/api/functions/setMemberRole.ts

@@ -0,0 +1,38 @@
+import { mutation, v } from "@pylonsync/functions";
+
+const ROLES = new Set(["owner", "admin", "member"]);
+
+/**
+ * Promote/demote a member. Only one row per (orgId, userId) so we
+ * find by composite then update. Setting role=owner does NOT change
+ * Org.ownerId — those are separate concepts (the founder vs current
+ * org-leadership members); this scaffold leaves transfer-of-ownership
+ * as a separate flow.
+ */
+export default mutation({
+	args: {
+		orgId: v.id("Org"),
+		userId: v.id("User"),
+		role: v.string(),
+	},
+	async handler(
+		ctx,
+		args: { orgId: string; userId: string; role: string },
+	) {
+		if (!ROLES.has(args.role)) {
+			throw ctx.error(
+				"INVALID_ROLE",
+				`role must be one of ${[...ROLES].join(", ")}`,
+			);
+		}
+		const memberships = (await ctx.db.query("Membership", {
+			orgId: args.orgId,
+			userId: args.userId,
+		})) as any[];
+		if (memberships.length === 0) {
+			throw ctx.error("NOT_A_MEMBER", "user is not a member of this org");
+		}
+		await ctx.db.update("Membership", memberships[0].id, { role: args.role });
+		return await ctx.db.get("Membership", memberships[0].id);
+	},
+});

package/templates/backend/b2b/apps/api/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@__APP_NAME_KEBAB__/api",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "pylon dev schema.ts --port 4321",
+    "build": "pylon codegen schema.ts --out pylon.manifest.json && pylon codegen client pylon.manifest.json --out pylon.client.ts",
+    "schema:push": "pylon schema push pylon.manifest.json --sqlite dev.db",
+    "schema:inspect": "pylon schema inspect --sqlite dev.db"
+  },
+  "dependencies": {
+    "@pylonsync/sdk": "^__PYLON_VERSION__",
+    "@pylonsync/functions": "^__PYLON_VERSION__"
+  },
+  "devDependencies": {
+    "@pylonsync/cli": "^__PYLON_VERSION__",
+    "typescript": "^5.5.0"
+  }
+}

package/templates/backend/b2b/apps/api/schema.ts

@@ -0,0 +1,171 @@
+import {
+	entity,
+	field,
+	query,
+	action,
+	policy,
+	buildManifest,
+} from "@pylonsync/sdk";
+
+// ---------------------------------------------------------------------------
+// Multi-tenant SaaS schema. The shape:
+//
+//   User       — global, one per real person (auth-managed)
+//   Org        — a tenant. Has a unique slug. Owner is the founding User.
+//   Membership — pivot row: which Users belong to which Orgs, and at
+//                what role (owner | admin | member).
+//   Project    — an org-scoped resource. Every row belongs to one Org;
+//                policies enforce that a query without `orgId` returns
+//                nothing.
+//
+// Pylon's policy expression language can read `auth.userId` and any
+// columns on the row. Cross-row checks (e.g. "is the caller a member
+// of this org?") are expressed by joining a Membership probe into the
+// allowRead/allowInsert/etc. expression.
+// ---------------------------------------------------------------------------
+
+const Org = entity("Org", {
+	slug: field.string(),
+	name: field.string(),
+	ownerId: field.id("User"),
+	createdAt: field.datetime(),
+});
+
+const Membership = entity("Membership", {
+	orgId: field.id("Org"),
+	userId: field.id("User"),
+	role: field.enum_(["owner", "admin", "member"]),
+	createdAt: field.datetime(),
+});
+
+const Project = entity("Project", {
+	orgId: field.id("Org"),
+	name: field.string(),
+	createdBy: field.id("User"),
+	archived: field.bool(),
+	createdAt: field.datetime(),
+});
+
+// ---------------------------------------------------------------------------
+// Function declarations
+// ---------------------------------------------------------------------------
+
+const myOrgs = query("myOrgs");
+const orgMembers = query("orgMembers");
+const orgProjects = query("orgProjects");
+
+const createOrg = action("createOrg", {
+	input: [
+		{ name: "slug", type: "string" },
+		{ name: "name", type: "string" },
+	],
+});
+
+const inviteMember = action("inviteMember", {
+	input: [
+		{ name: "orgId", type: "id(Org)" },
+		{ name: "userId", type: "id(User)" },
+		{ name: "role", type: "string" },
+	],
+});
+
+const removeMember = action("removeMember", {
+	input: [
+		{ name: "orgId", type: "id(Org)" },
+		{ name: "userId", type: "id(User)" },
+	],
+});
+
+const setMemberRole = action("setMemberRole", {
+	input: [
+		{ name: "orgId", type: "id(Org)" },
+		{ name: "userId", type: "id(User)" },
+		{ name: "role", type: "string" },
+	],
+});
+
+const createProject = action("createProject", {
+	input: [
+		{ name: "orgId", type: "id(Org)" },
+		{ name: "name", type: "string" },
+	],
+});
+
+const archiveProject = action("archiveProject", {
+	input: [{ name: "id", type: "id(Project)" }],
+});
+
+// ---------------------------------------------------------------------------
+// Policies — RBAC enforced on every read/write.
+//
+// Each entity's policy hooks read `auth.userId` and check membership
+// of the row's `orgId` via the Membership table. Pylon evaluates
+// policy expressions against the database, so a `Membership(orgId,
+// userId)` probe is a join the planner pushes into the same query —
+// no per-request round trip.
+// ---------------------------------------------------------------------------
+
+const orgPolicy = policy({
+	name: "org_membership",
+	entity: "Org",
+	// Anyone can read an org if they're a member; only the owner can update.
+	allowRead: "exists(Membership where orgId = data.id and userId = auth.userId)",
+	allowInsert: "auth.userId == data.ownerId",
+	allowUpdate: "data.ownerId == auth.userId",
+	allowDelete: "data.ownerId == auth.userId",
+});
+
+const membershipPolicy = policy({
+	name: "membership_admin",
+	entity: "Membership",
+	// You can see your own memberships, plus all memberships in any org
+	// where you're an owner/admin (so the admin UI can list everyone).
+	allowRead:
+		"data.userId == auth.userId or exists(Membership where orgId = data.orgId and userId = auth.userId and (role = 'owner' or role = 'admin'))",
+	allowInsert:
+		"exists(Membership where orgId = data.orgId and userId = auth.userId and (role = 'owner' or role = 'admin'))",
+	allowUpdate:
+		"exists(Membership where orgId = data.orgId and userId = auth.userId and (role = 'owner' or role = 'admin'))",
+	allowDelete:
+		"exists(Membership where orgId = data.orgId and userId = auth.userId and (role = 'owner' or role = 'admin'))",
+});
+
+const projectPolicy = policy({
+	name: "project_org_scope",
+	entity: "Project",
+	// Tenant scope: you can only touch a project if you're a member of
+	// its org. Regardless of which `orgId` the client claims, the policy
+	// pulls the row's actual orgId and checks membership.
+	allowRead:
+		"exists(Membership where orgId = data.orgId and userId = auth.userId)",
+	allowInsert:
+		"exists(Membership where orgId = data.orgId and userId = auth.userId)",
+	// Only owners/admins can rename or archive.
+	allowUpdate:
+		"exists(Membership where orgId = data.orgId and userId = auth.userId and (role = 'owner' or role = 'admin'))",
+	allowDelete:
+		"exists(Membership where orgId = data.orgId and userId = auth.userId and (role = 'owner' or role = 'admin'))",
+});
+
+// ---------------------------------------------------------------------------
+// Manifest
+// ---------------------------------------------------------------------------
+
+const manifest = buildManifest({
+	name: "__APP_NAME_SNAKE__",
+	version: "0.0.1",
+	entities: [Org, Membership, Project],
+	queries: [myOrgs, orgMembers, orgProjects],
+	actions: [
+		createOrg,
+		inviteMember,
+		removeMember,
+		setMemberRole,
+		createProject,
+		archiveProject,
+	],
+	policies: [orgPolicy, membershipPolicy, projectPolicy],
+	routes: [],
+});
+
+console.log(JSON.stringify(manifest));

package/templates/backend/b2b/apps/api/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["schema.ts", "functions/**/*.ts"]
+}

package/templates/backend/barebones/apps/api/functions/createWidget.ts

@@ -0,0 +1,22 @@
+import { mutation, v } from "@pylonsync/functions";
+
+/**
+ * Insert a new Widget. Initializes count to 0 and stamps the time.
+ * Returns the inserted row so the client can render it without a
+ * follow-up read.
+ */
+export default mutation({
+	args: { name: v.string() },
+	async handler(ctx, args: { name: string }) {
+		const trimmed = args.name.trim();
+		if (!trimmed) {
+			throw ctx.error("EMPTY_NAME", "name cannot be empty");
+		}
+		const id = await ctx.db.insert("Widget", {
+			name: trimmed,
+			count: 0,
+			createdAt: new Date().toISOString(),
+		});
+		return await ctx.db.get("Widget", id);
+	},
+});

package/templates/backend/barebones/apps/api/functions/listWidgets.ts

@@ -0,0 +1,18 @@
+import { query } from "@pylonsync/functions";
+
+/**
+ * Live query — every Widget, newest first. Subscribed via the React
+ * `useQuery` / Swift `PylonQuery` / RN `useQuery` hooks; rerenders
+ * whenever a row is inserted, updated, or deleted.
+ */
+export default query({
+	args: {},
+	async handler(ctx) {
+		const rows = await ctx.db.query("Widget", {});
+		return [...rows].sort((a: any, b: any) => {
+			const ad = Date.parse(a.createdAt) || 0;
+			const bd = Date.parse(b.createdAt) || 0;
+			return bd - ad;
+		});
+	},
+});

package/templates/backend/barebones/apps/api/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@__APP_NAME_KEBAB__/api",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "pylon dev schema.ts --port 4321",
+    "build": "pylon codegen schema.ts --out pylon.manifest.json && pylon codegen client pylon.manifest.json --out pylon.client.ts",
+    "schema:push": "pylon schema push pylon.manifest.json --sqlite dev.db",
+    "schema:inspect": "pylon schema inspect --sqlite dev.db"
+  },
+  "dependencies": {
+    "@pylonsync/sdk": "^__PYLON_VERSION__",
+    "@pylonsync/functions": "^__PYLON_VERSION__"
+  },
+  "devDependencies": {
+    "@pylonsync/cli": "^__PYLON_VERSION__",
+    "typescript": "^5.5.0"
+  }
+}