@nocobase/app-template-default 1.0.0-beta.73 → 1.0.0-beta.75

package/AGENTS.md

@@ -53,7 +53,7 @@ A feature with a page and an API touches five places: a migration for the table,
 
 ## System settings are part of feature delivery
 
-A bare create-app stays Home-only with no settings routes or menu. As the application develops business capabilities, inspect its current state on every iteration and automatically register the prepared Users and Roles and permissions contribution from `client/pages/settings/routes.ts` once in `client/routes.ts`; preserve it and reconcile missing management surfaces on every iteration, without a first-build flag or one-time setup stage. Whenever an application adds lifecycles, workflows, approvals, notifications, files or other configurable capabilities, automatically include their real administration surfaces without requiring a second user request. Follow [system settings delivery](.agents/skills/nocobase-app-development/references/system-settings.md); in particular, every used process includes a definitions directory, standard diagram, supported parameters and authorized execution history. Do not add demo plugins or empty settings for unused capabilities. The template preinstalls `#components/lifecycle-diagram` (React Flow + ELK) and `client/extensions/nocobase-workflow-management/`: use them by default, preserve their visuals unless the user explicitly requests another style, and connect authorized parameter bindings through `LifecycleDiagram.configuration` to the real editor. These are UI Registry sources; an npm package lookup is not a component availability check.
+A bare create-app shows Home to signed-in users and System settings → App foundation only to unrestricted administrators. The Foundation plugin owns this initial settings group; the navigation transform merges its entry into the application settings group when business administration is registered. As the application develops business capabilities, inspect its current state on every iteration and automatically register the prepared Users and Roles and permissions contribution from `client/pages/settings/routes.ts` once in `client/routes.ts`; preserve it and reconcile missing management surfaces on every iteration, without a first-build flag or one-time setup stage. Whenever an application adds lifecycles, workflows, approvals, notifications, files or other configurable capabilities, automatically include their real administration surfaces without requiring a second user request. Follow [system settings delivery](.agents/skills/nocobase-app-development/references/system-settings.md); in particular, every used process includes a definitions directory, standard diagram, supported parameters and authorized execution history. Do not add demo plugins or empty settings for unused capabilities. The template preinstalls `#components/lifecycle-diagram` (React Flow + ELK) and `client/extensions/nocobase-workflow-management/`: use them by default, preserve their visuals unless the user explicitly requests another style, and connect authorized parameter bindings through `LifecycleDiagram.configuration` to the real editor. These are UI Registry sources; an npm package lookup is not a component availability check.
 
 ## Rules that apply everywhere
 
@@ -101,7 +101,7 @@ When reporting or opening this application's address, use the `Local:` URL print
 
 Scope all verification — formatting, lint, type checking, tests, builds and runtime checks — to the affected files, projects, or packages and their affected consumers. Do not run full-application or workspace-wide checks, or an aggregate `pnpm check`, as a routine step after each edit. Documentation-only changes need formatting and link checks for the changed documents, not type checking, runtime tests, or builds. Report which checks ran, their scope, and any unverified behavior.
 
-Add tests for what you changed — a route's authenticated, unauthenticated, and unauthorized responses; a migration's `up` and `down` against a real database; a page's actual behavior — in `tests/`, never beside the source; browser tests go in `tests/playwright/`. See [testing and verification](.agents/skills/nocobase-app-development/references/testing.md).
+Add tests for what you changed — a route's authenticated, unauthenticated, and unauthorized responses; a migration's `up` and `down` against a real database; a page's actual behavior — in `tests/`, never beside the source; browser tests go in `tests/playwright/`. Start page tests from `tests/components/page-harness.test.tsx`, which keeps application hooks real and supplies external responses through the test fixture. See [testing and verification](.agents/skills/nocobase-app-development/references/testing.md).
 
 For any UI work, start with [the frontend workflow](.agents/skills/nocobase-app-development/references/frontend/ui-workflow.md), which decides the workflow and routes to the styling rules, the theme token contract and the rest.
 
@@ -123,3 +123,9 @@ When the built-in mechanism genuinely cannot express what is being asked, changi
 | [.agents/rules/components.md](.agents/rules/components.md)             | Adding or changing a component, a shadcn primitive, a UI Library item, or the visual design                  |
 | [.agents/rules/shell.md](.agents/rules/shell.md)                       | Changing layouts, the header, sidebar, breadcrumbs, the account menu or loading indicators                   |
 | [.agents/rules/build-and-deploy.md](.agents/rules/build-and-deploy.md) | Changing the build, packing a deployment, the Docker image, `CDN_BASE_URL`, or building for another platform |
+
+## Visible and manageable role assignments
+
+Assign application business roles to explicitly identified users through the prepared User management role-assignment UI. Never seed a business permission set onto `authenticated:*`, broaden the inherited platform `member` role, or write startup reconciliation that grants access to everyone merely to make a feature usable. Unchecked actions in one role do not revoke grants inherited from another. If the user explicitly requests a global default role, first deliver a permission-protected administration control that shows its recipients and allows changing or removing the assignment; show inherited roles and their source in user access details. Without that UI, use explicit user assignments and explain the limitation. Keep page access independent from business operations.
+
+Run `pnpm exec vitest run tests/logic/authorization-assignment-safety.test.ts` after permission initialization changes and before delivery. It boots the real application on an isolated database and inspects initialized wildcard assignments and the inherited member role. Keep this test in generated applications. An intentional global default requires explicit user authorization, a working administration surface and corresponding acceptance tests before deliberately updating the expected baseline; do not delete, skip or loosen the guard to make tests pass. Test an ordinary user with only the configured role: inspect all effective grant sources and verify both hidden buttons and rejected direct API calls.

package/README.MD

@@ -6,7 +6,7 @@ You own everything in this directory. Add pages, API routes, database tables, an
 
 ## Default and Examples
 
-Default provides the application shell and product capabilities without example plugins or business demo pages. Application-owned business API routes start empty, and new databases receive no article sample data. A bare create-app shows Home only, with no System settings routes or menu. As business capabilities are developed, the app development skill reconciles missing core administration on every iteration and registers the prepared Users and Roles and permissions contribution (`client/pages/settings/routes.ts`); each actually used configurable capability includes its administration as part of feature delivery. Its built-in Users integration lists direct Authorization Permission Sets as application roles, while access assigned to all authenticated users remains separate. Use `app-template-examples` for article management and runnable plugin demonstrations.
+Default provides the application shell and product capabilities without example plugins or business demo pages. Application-owned business API routes start empty, and new databases receive no article sample data. A bare create-app shows Home and, for unrestricted administrators only, System settings → App foundation. Foundation is installed and registered on both Client and Server; its read-only overview is available at `/foundation` under the application base path. As business capabilities are developed, the app development skill reconciles missing core administration on every iteration and registers the prepared Users and Roles and permissions contribution (`client/pages/settings/routes.ts`); each actually used configurable capability includes its administration as part of feature delivery. Its built-in Users integration lists direct Authorization Permission Sets as application roles, while access assigned to all authenticated users remains separate. Use `app-template-examples` for article management and runnable plugin demonstrations.
 
 Existing Default installations retain their data when example plugins are unregistered. If an installation already ran the article migration, retain its original migration sources as described in the [upgrade migration rules](.agents/skills/nocobase-app-upgrade/references/edge-cases.md#migrations) before upgrading. Do not erase migration history or delete existing data to make an upgrade start.
 
@@ -401,6 +401,8 @@ An environment variable a section declares takes precedence over the file, and t
 
 Tests live in `tests/`, never beside the source they cover. Put logic and integration tests under `tests/logic/` and component tests under `tests/components/`. Browser tests belong in `tests/playwright/`, which Vitest skips. Playwright does not start the application: start it first (`pnpm dev`, or `pnpm build` and then the built application), then run `pnpm test:e2e`; each test reads the application URL, including its base path, from `APP_URL`. Tests that only need a real server, real authentication, or a real database run under Vitest with `createAppTest()` from `@nocobase/app-testing/server`.
 
+Application tests use the `/server`, `/client` and `/cli` entries of `@nocobase/app-testing`. Start page tests from `tests/components/page-harness.test.tsx`: it uses `renderWithApp()` with real application hooks, strict translations, permission checks and a test toaster. Answer requests through `answerApi()` and replace external services through `services`, without also registering their owning plugins. The template's Vitest configuration includes client plugins in custom package scopes so their contexts and service tokens remain shared. See `.agents/skills/nocobase-app-development/references/testing.md` for fixture ownership and complete server, migration and CLI examples.
+
 ### Notification testing
 
 With the `notification:test` `send` permission, send a real message through the durable Notification Manager with `POST <APP_BASE_PATH>/api/notifications/testSends`. `GET <APP_BASE_PATH>/api/notifications/testTargets` lists each configured channel and the fields its test takes: Email tests require an address and IM tests use the configured logical target. The server enforces the permission when the message is submitted.

package/cli/plugins.ts

@@ -1,8 +1,9 @@
 import { defineCliPlugins, type AppCliPlugins } from '@nocobase/app-cli';
+import foundation from '@nocobase/app-plugin-foundation/cli';
 import scheduler from '@nocobase/app-plugin-scheduler/cli';
 
 // Array order is command registration order. A plugin contributes its commands
 // by appearing in this list; removing its entry and its import removes them.
-const cliPlugins: AppCliPlugins = defineCliPlugins([scheduler]);
+const cliPlugins: AppCliPlugins = defineCliPlugins([scheduler, foundation]);
 
 export default cliPlugins;

package/client/components/default-access-editor.tsx

@@ -0,0 +1,183 @@
+import { useId, type ReactElement, type ReactNode } from 'react';
+import { Input } from '#components/ui/input';
+import { Label } from '#components/ui/label';
+import {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '#components/ui/select';
+
+export interface DefaultAccessChoice {
+  readonly value: string;
+  readonly label: string;
+}
+export interface DefaultAccessScopeControl {
+  readonly id: string;
+  readonly action: string;
+  readonly scope: string;
+  readonly value: string;
+  readonly options: readonly DefaultAccessChoice[];
+  readonly configuration?: ReactNode;
+  readonly error?: string | undefined;
+}
+export interface DefaultAccessEditorProps {
+  readonly ruleKey: string;
+  readonly resource: string;
+  readonly resources: readonly DefaultAccessChoice[];
+  readonly scopes: readonly DefaultAccessScopeControl[];
+  readonly existing?: boolean;
+  readonly readOnly?: boolean;
+  readonly keyError?: string | undefined;
+  readonly resourceError?: string | undefined;
+  readonly labels: {
+    readonly key: string;
+    readonly resource: string;
+    readonly chooseResource: string;
+    readonly action: string;
+    readonly scope: string;
+    readonly noScopes: string;
+  };
+  readonly onKeyChange: (value: string) => void;
+  readonly onResourceChange: (value: string) => void;
+  readonly onScopeChange: (id: string, value: string) => void;
+}
+
+/** Controlled fields only: the host owns API authorization, drafts, validation and writes. */
+export function DefaultAccessEditor({
+  ruleKey,
+  resource,
+  resources,
+  scopes,
+  existing = false,
+  readOnly = false,
+  keyError,
+  resourceError,
+  labels,
+  onKeyChange,
+  onResourceChange,
+  onScopeChange,
+}: DefaultAccessEditorProps): ReactElement {
+  const id = useId();
+  return (
+    <div className='flex min-w-0 flex-col gap-6'>
+      <div className='grid gap-4 sm:grid-cols-2'>
+        <div className='flex min-w-0 flex-col gap-2'>
+          <Label htmlFor={`${id}-key`}>{labels.key} *</Label>
+          <Input
+            id={`${id}-key`}
+            name='ruleKey'
+            value={ruleKey}
+            required
+            disabled={existing || readOnly}
+            aria-invalid={Boolean(keyError)}
+            aria-describedby={keyError ? `${id}-key-error` : undefined}
+            onChange={(event) => onKeyChange(event.target.value)}
+          />
+          {keyError && (
+            <p id={`${id}-key-error`} className='text-sm text-destructive'>
+              {keyError}
+            </p>
+          )}
+        </div>
+        <div className='flex min-w-0 flex-col gap-2'>
+          <Label htmlFor={`${id}-resource`}>{labels.resource} *</Label>
+          <Select
+            value={resource}
+            items={resources}
+            disabled={existing || readOnly}
+            onValueChange={(value) => {
+              if (value !== null) onResourceChange(value);
+            }}
+          >
+            <SelectTrigger
+              id={`${id}-resource`}
+              className='w-full'
+              aria-invalid={Boolean(resourceError)}
+              aria-describedby={
+                resourceError ? `${id}-resource-error` : undefined
+              }
+            >
+              <SelectValue placeholder={labels.chooseResource} />
+            </SelectTrigger>
+            <SelectContent className='w-auto max-w-[min(var(--container-sm),var(--available-width))] min-w-(--anchor-width) [&_[data-slot=select-item]>:first-child]:whitespace-normal'>
+              <SelectGroup>
+                {resources.map((option) => (
+                  <SelectItem key={option.value} value={option.value}>
+                    {option.label}
+                  </SelectItem>
+                ))}
+              </SelectGroup>
+            </SelectContent>
+          </Select>
+          {resourceError && (
+            <p id={`${id}-resource-error`} className='text-sm text-destructive'>
+              {resourceError}
+            </p>
+          )}
+        </div>
+      </div>
+      <div className='overflow-hidden rounded-lg border'>
+        {scopes.length ? (
+          scopes.map((scope) => (
+            <div
+              key={scope.id}
+              className='grid min-w-0 gap-3 border-b p-4 last:border-b-0 sm:grid-cols-3'
+            >
+              <div className='min-w-0 break-words text-sm font-medium'>
+                {scope.action}
+              </div>
+              <div className='flex min-w-0 flex-col gap-2 sm:col-span-2'>
+                <Label htmlFor={`${id}-${scope.id}`}>
+                  {scope.scope || labels.scope}
+                </Label>
+                <Select
+                  value={scope.value}
+                  items={scope.options}
+                  disabled={readOnly}
+                  onValueChange={(value) => {
+                    if (value !== null) onScopeChange(scope.id, value);
+                  }}
+                >
+                  <SelectTrigger
+                    id={`${id}-${scope.id}`}
+                    className='w-full'
+                    aria-label={`${scope.action} · ${scope.scope || labels.scope}`}
+                    aria-invalid={Boolean(scope.error)}
+                    aria-describedby={
+                      scope.error ? `${id}-${scope.id}-error` : undefined
+                    }
+                  >
+                    <SelectValue />
+                  </SelectTrigger>
+                  <SelectContent className='w-auto max-w-[min(var(--container-sm),var(--available-width))] min-w-(--anchor-width) [&_[data-slot=select-item]>:first-child]:whitespace-normal'>
+                    <SelectGroup>
+                      {scope.options.map((option) => (
+                        <SelectItem key={option.value} value={option.value}>
+                          {option.label}
+                        </SelectItem>
+                      ))}
+                    </SelectGroup>
+                  </SelectContent>
+                </Select>
+                {scope.error && (
+                  <p
+                    id={`${id}-${scope.id}-error`}
+                    className='text-sm text-destructive'
+                  >
+                    {scope.error}
+                  </p>
+                )}
+                {scope.configuration}
+              </div>
+            </div>
+          ))
+        ) : (
+          <p className='p-4 text-sm text-muted-foreground'>{labels.noScopes}</p>
+        )}
+      </div>
+    </div>
+  );
+}