create-monolayer-app 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-monolayer-app",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "CLI to scaffold a new monolayer application",
   "type": "module",
   "bin": {

package/template/.agents/skills/monolayer-application-permissions/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: monolayer-application-permissions
+description: >
+  Apply viewer, editor, and owner permissions in monolayer React Router apps.
+  Use for application content access, editing interactions, or changes to
+  authentication and user context, including demos with sample or temporary data.
+---
+
+# Monolayer Application Permissions
+
+Build application features using the existing user context. The application is the sharing boundary: authorized users see the same content, subject to explicit product rules.
+
+Application content interactions follow these roles even in demos backed by sample or temporary data. Keep the requested storage and integration behavior.
+
+## Access model
+
+| Operation | `viewer` | `editor` | `owner` |
+| --- | --- | --- | --- |
+| Read, search, and navigate shared content | Allow | Allow | Allow |
+| Download content the user can read | Allow by default | Allow | Allow |
+| Create, edit, delete, upload, or import shared content | Deny | Allow | Allow |
+| Manage platform invitations or access grants | Platform sharing policy | Platform sharing policy | Platform sharing policy |
+
+Scope shared records to the trusted application, not the current user's email. Email is display or attribution data, not an immutable person ID or application identifier. Keep personal preferences separate where the product requires them.
+
+Invitations, grants, application deletion, and ownership transfer use the platform's separate authorization. `canWrite` grants no administrative authority; use the existing platform sharing integration instead of local grant rows. Application roles do not supply live collaboration, conflict resolution, or per-document permissions.
+
+## Existing context
+
+[lib/user-context.server.ts](../../../lib/user-context.server.ts) exports `userContext`, `userSchema`, and `userContextMiddleware`; the context contains `email` and `role`. [app/root.tsx](../../../app/root.tsx) registers the middleware. Reuse existing context and access helpers. Inspect registration when adding a protected route or investigating missing context.
+
+Production context depends on the platform authenticating and authorizing requests before they reach the application. Local schema validation does not establish header authenticity. See the development reference when changing that integration.
+
+## Authorization constraints
+
+- Preserve existing authentication, middleware registration, and development behavior unless an authentication change is part of the user's request. A demo or sample-only request does not imply such a change.
+- Read authority from `context.get(userContext)` on the server. Do not reparse identity headers in features or accept authority from client input. Pass request context or a trusted actor explicitly to server helpers; never store the current user in a module variable.
+- Authorize each write using the current request's role before database changes, file changes, external writes, or issuing write capabilities. A viewer's write returns `403`. Missing context is a configuration fault, never an owner fallback.
+- Keep reads free of shared-content mutations, including default records created on page visits.
+- Send only the identity fields and capabilities the interface needs. UI controls reflect permissions; every server write still checks permission when earlier loader data says editing is allowed.
+- Jobs, webhooks, sockets, and React Server Functions need their own trusted authorization. Request context does not persist into later work, and a saved email or role does not establish continuing authority.
+
+## Task-specific references
+
+Read the relevant sections when needed:
+
+- [Server examples](references/server-examples.md): write guards, application scope, protected downloads, and upload capabilities.
+- [Interface examples](references/interface-examples.md): capability data, read-only controls, sample-only demos, and denied saves.
+- [Development and verification](references/development-and-verification.md): local identity, isolated role fixtures, platform trust prerequisites, and checks selected by the changed behavior.
+
+Complete the requested feature and select checks for the affected behavior. For server writes, verify viewer denial without side effects and writer success; check application scope when data access changes. For local demos, check role-dependent interactions and the requested reset behavior. Report relevant verification gaps; isolated context fixtures do not verify deployed authentication.

package/template/.agents/skills/monolayer-application-permissions/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Monolayer Application Permissions"
+  short_description: "Use shared application roles in React Router"
+  default_prompt: "Use $monolayer-application-permissions to apply shared read and write permissions with the existing user middleware."

package/template/.agents/skills/monolayer-application-permissions/references/development-and-verification.md

@@ -0,0 +1,51 @@
+# Development and verification
+
+Use the sections needed for local role checks, authorization tests, or changes to the authentication integration.
+
+## Local identity
+
+[lib/user-context.server.ts](../../../../lib/user-context.server.ts) supplies `{ email: "developer@example.com", role: "owner" }` when `import.meta.env.DEV` is true. That branch ignores incoming identity headers; there is no runtime role selector in the current middleware.
+
+Use isolated contexts to exercise other roles without changing production authentication. If browser verification needs a role fixture, use an existing test harness or add a test-only mechanism within the requested scope. A deployed stage named `dev` is not grounds for enabling mock users.
+
+## Isolated request contexts
+
+This helper belongs only in test code. It represents context after authentication; it does not verify middleware registration or upstream header trust.
+
+```ts
+// tests/application-context.ts
+import { RouterContextProvider } from "react-router";
+import type { z } from "zod";
+import { userContext, userSchema } from "../lib/user-context.server";
+
+export function applicationContextForTest(user: z.input<typeof userSchema>) {
+  const context = new RouterContextProvider();
+  context.set(userContext, userSchema.parse(user));
+  return context;
+}
+```
+
+Create a context for each simulated request. Use `{ email: "reader@example.com", role: "viewer" }` for a viewer and different emails when checking shared-content behavior. To exercise missing-context handling, leave `userContext` unset.
+
+## Select checks by the changed behavior
+
+Use applicable cases; this table is not a checklist for every edit.
+
+| Changed behavior | Evidence to check |
+| --- | --- |
+| Shared reads | Different authorized users, including viewers, see the same application content. Reads do not create shared records. |
+| Mutations | Direct viewer requests return `403` with no database, file, or external writes. Valid editor and owner requests succeed. Client identity fields cannot override the trusted actor or attribution. |
+| Application scope | Reads and writes cannot expose or change another application's records. For shared storage, check the actual query or adapter boundary. |
+| Input validation | Invalid content fails before a write occurs. |
+| Downloads | Viewers receive only permitted application content. |
+| Uploads | Viewer requests cannot obtain upload capabilities or publish files through a completion operation. |
+| Access UI | Read-only controls preserve permitted navigation and downloads. A write with viewer context is denied even if the interface previously showed editor access; the interface explains the failure. |
+| Authentication wiring | Missing or invalid identity follows the existing `401` behavior. Missing required context never invents an owner or continues privileged work. |
+
+Use the project's test runner and real service boundaries. Check persisted data or side-effect calls after denials; disabled-button assertions do not prove authorization. Select existing type or build checks when affected imports, types, or server/browser boundaries warrant them. A presentation-only change does not require investigating deployed authentication.
+
+## Platform trust prerequisites
+
+In production, the middleware validates the shape of `x-user-email` and `x-user-authorization` and sets context. It does not verify their origin. The platform's protected ingress must authenticate the caller, authorize access to the application, replace or reject client-supplied identity headers, and prevent bypass to an unprotected application server.
+
+This repository does not include the upstream verifier or its deployment contract. When changing deployment or authentication integration, consult the platform's maintained contract for signature verification, header and cookie handling, and permission propagation. Do not infer those guarantees from local schema validation or promise immediate revocation. Report unverified deployment boundaries when they are part of the requested task; isolated role fixtures do not establish them.

package/template/.agents/skills/monolayer-application-permissions/references/interface-examples.md

@@ -0,0 +1,60 @@
+# Interface examples
+
+Use this reference when adding or changing access behavior in the interface. Reuse capabilities already exposed by the application.
+
+## Expose the capability the interface needs
+
+For application-wide controls, extend the root loader while preserving existing data and middleware exports. A page-specific control can use its own route loader instead.
+
+```ts
+// app/root.tsx — loader addition
+import { userContext } from "../lib/user-context.server";
+import type { Route } from "./+types/root";
+
+export function loader({ context }: Route.LoaderArgs) {
+  const user = context.get(userContext);
+
+  return { canWrite: user.role === "owner" || user.role === "editor" };
+}
+```
+
+Read the capability from loader data, using `useRouteLoaderData` with the actual route ID for descendants when needed. Server request context is separate from browser React context; keep `.server` runtime imports out of browser components.
+
+Return email or role only when the interface needs them. Never serialize authentication cookies, transport assertions, or provider tokens. Keep identity-dependent responses out of shared public caches.
+
+## Reflect access in existing controls
+
+Pass `canWrite` from loader data into existing controls. This example belongs inside the application's existing form; its server operation must authorize the write independently.
+
+```tsx
+type SaveControlProps = {
+  canWrite: boolean;
+  saving: boolean;
+};
+
+export function SaveControl({ canWrite, saving }: SaveControlProps) {
+  if (!canWrite) {
+    return <p>You have read access. An editor or owner can make changes.</p>;
+  }
+
+  return (
+    <button type="submit" disabled={saving}>
+      {saving ? "Saving…" : "Save"}
+    </button>
+  );
+}
+```
+
+Apply the same capability to editable fields, drag handles, keyboard shortcuts, and autosave. Use read-only fields when viewers should still select their contents. Preserve permitted navigation, search, and downloads; lack of write access does not hide shared content.
+
+## Sample and temporary data
+
+Use the same server-derived capability for simulated content changes. Completing a sample task is an editing interaction and requires editor or owner access. Filtering the list is a viewing interaction available to viewers; personal display preferences also remain available. Apply the capability to editing controls and their event handlers.
+
+Keep sample data and completion state in memory when refresh must reset them. Do not add persistence or external services solely to apply permissions. Preserve the existing user middleware and derive capabilities from its context. Local controls govern demo behavior; any server write still needs authorization using the current request.
+
+## Handle permission changes and denied saves
+
+An interface can show stale capabilities. Skip autosave when `canWrite` is false, and handle server denials even when it is true. Do not show an optimistic update as saved before server confirmation.
+
+A thrown `403` can replace the route with its error boundary and discard a draft. When the product requires draft recovery, use the application's structured action-error pattern to preserve the editor and unsaved content while returning status `403`. Handle `401` through the existing authentication flow; a denied write is not automatically a reason to redirect to login.

package/template/.agents/skills/monolayer-application-permissions/references/server-examples.md

@@ -0,0 +1,81 @@
+# Server examples
+
+Use the sections relevant to the changed server boundary. Reuse existing helpers. The helper below is illustrative; `lib/user-context.server.ts` already exists. Use the generated `Route` types for each route module.
+
+## Require write permission
+
+```ts
+// lib/application-access.server.ts
+import type { RouterContextProvider } from "react-router";
+import { userContext } from "./user-context.server";
+
+export function requireApplicationWriter(
+  context: Readonly<RouterContextProvider>
+) {
+  const user = context.get(userContext);
+
+  if (user.role !== "editor" && user.role !== "owner") {
+    throw new Response("Write access required", { status: 403 });
+  }
+
+  return user;
+}
+```
+
+Use the project's error mapping if it differs from thrown HTTP responses. Services called through multiple handlers need equivalent authorization at each entry point; a protected page loader does not authorize later mutations.
+
+## Protect a mutation
+
+`updateSharedContent` below represents the feature's application operation, not an existing module or SDK API. It validates input, restricts the update to the trusted application, and derives author attribution from `actor`. Preserve existing transaction and revision checks.
+
+```ts
+// app/routes/home.tsx — action addition
+import { requireApplicationWriter } from "../../lib/application-access.server";
+import { updateSharedContent } from "../../lib/shared-content.server";
+import type { Route } from "./+types/home";
+
+export async function action({ request, context }: Route.ActionArgs) {
+  const actor = requireApplicationWriter(context);
+  const input = await request.formData();
+
+  return await updateSharedContent({ input, actor });
+}
+```
+
+Authorize each intent when an action handles multiple operations. Client-supplied email, role, or capability fields cannot override the actor. Preserve existing origin checks and CSRF controls; they do not replace role authorization.
+
+## Keep storage scoped to the application
+
+For shared storage, include a trusted application identifier in read and mutation predicates. Obtain it from server configuration or trusted platform context; a submitted application ID is not authorization. Dedicated application storage can provide this boundary without adding a per-user filter.
+
+Recorded author email is attribution only. It neither makes content private nor gives its author additional permissions.
+
+## Protect a download
+
+Register the resource route under the existing root middleware; route registration generates its `Route` types. `readSharedExport` is an illustrative application operation that returns only permitted export fields from the trusted application and performs no writes.
+
+```ts
+// app/routes/content-export.ts
+import { readSharedExport } from "../../lib/shared-content.server";
+import { userContext } from "../../lib/user-context.server";
+import type { Route } from "./+types/content-export";
+
+export async function loader({ context }: Route.LoaderArgs) {
+  context.get(userContext);
+  const content = await readSharedExport();
+
+  return new Response(JSON.stringify(content), {
+    headers: {
+      "Content-Type": "application/json; charset=utf-8",
+      "Content-Disposition": 'attachment; filename="content.json"',
+      "Cache-Control": "private, no-store",
+    },
+  });
+}
+```
+
+Viewers can download readable content unless the product defines an additional restriction. Use the same access and scope checks for attachments and signed download URLs. Link to a resource download with an ordinary anchor or a `reloadDocument` link.
+
+## Upload capabilities
+
+A signed upload URL grants write authority before data is uploaded. Check write permission before issuing it or accepting uploaded data, and again when a separate completion request publishes the file. These are distinct write boundaries.

package/template/.claude/CLAUDE.md

@@ -12,6 +12,17 @@ Oxlint + Oxfmt (the underlying engine) provides robust linting and formatting. M
 
 ---
 
+## Monolayer Application Permissions
+
+Preserve existing authentication and workspace role behavior during feature work, including demos. Use [monolayer-application-permissions](.agents/skills/monolayer-application-permissions/SKILL.md) for application content access, editing interactions, or authentication/context changes.
+
+The default development role is `owner`, so testing only with that role can miss permission errors affecting other users. When verifying role-dependent behavior, temporarily change the role in the `import.meta.env.DEV` branch of [lib/user-context.server.ts](lib/user-context.server.ts):
+
+- Use `viewer` to verify that shared content remains readable, editing controls are hidden or disabled, and server writes return `403` without side effects.
+- Use `editor` to verify that permitted create, edit, delete, and upload flows work without requiring the `owner` role.
+
+Select checks relevant to the feature being changed. This testing exception does not require additional approval or a new role-selection mechanism. Restore the original role after testing and keep temporary role changes out of commits. Preserve the production authentication branch.
+
 ## Core Principles
 
 Write code that is **accessible, performant, type-safe, and maintainable**. Focus on clarity and explicit intent over brevity.

package/template/AGENTS.md

@@ -12,6 +12,17 @@ Oxlint + Oxfmt (the underlying engine) provides robust linting and formatting. M
 
 ---
 
+## Monolayer Application Permissions
+
+Preserve existing authentication and workspace role behavior during feature work, including demos. Use [monolayer-application-permissions](.agents/skills/monolayer-application-permissions/SKILL.md) for application content access, editing interactions, or authentication/context changes.
+
+The default development role is `owner`, so testing only with that role can miss permission errors affecting other users. When verifying role-dependent behavior, temporarily change the role in the `import.meta.env.DEV` branch of [lib/user-context.server.ts](lib/user-context.server.ts):
+
+- Use `viewer` to verify that shared content remains readable, editing controls are hidden or disabled, and server writes return `403` without side effects.
+- Use `editor` to verify that permitted create, edit, delete, and upload flows work without requiring the `owner` role.
+
+Select checks relevant to the feature being changed. This testing exception does not require additional approval or a new role-selection mechanism. Restore the original role after testing and keep temporary role changes out of commits. Preserve the production authentication branch.
+
 ## Core Principles
 
 Write code that is **accessible, performant, type-safe, and maintainable**. Focus on clarity and explicit intent over brevity.

package/template/app/root.tsx

@@ -7,9 +7,9 @@ import {
   ScrollRestoration,
 } from "react-router";
 
-import type { Route } from "./+types/root";
-
 import "./app.css";
+import { userContextMiddleware } from "../lib/user-context.server";
+import type { Route } from "./+types/root";
 
 export const links: Route.LinksFunction = () => [
   { rel: "preconnect", href: "https://fonts.googleapis.com" },
@@ -74,3 +74,5 @@ export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) {
     </main>
   );
 }
+
+export const middleware: Route.MiddlewareFunction[] = [userContextMiddleware];

package/template/lib/db/user-context.server.ts

@@ -0,0 +1,35 @@
+import { createContext } from "react-router";
+import { z } from "zod";
+
+import type { Route } from "../app/+types/root";
+
+export const userContextMiddleware: Route.MiddlewareFunction =
+  // oxlint-disable-next-line require-await
+  async ({ request, context }, next) => {
+    const result = userSchema.safeParse(
+      import.meta.env.DEV
+        ? {
+            email: "developer@example.com",
+            role: "owner",
+          }
+        : {
+            email: request.headers.get("x-user-email"),
+            role: request.headers.get("x-user-authorization"),
+          }
+    );
+
+    if (!result.success) {
+      throw new Response("Unauthorized", { status: 401 });
+    }
+
+    context.set(userContext, result.data);
+
+    return next();
+  };
+
+export const userSchema = z.object({
+  email: z.email(),
+  role: z.enum(["owner", "editor", "viewer"]),
+});
+
+export const userContext = createContext<z.infer<typeof userSchema>>();