@bitakit/cli 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,198 @@
1
+ # Actions
2
+
3
+ Use this for a button, link, menu entry, shortcut or any operation a control runs. Define it once in
4
+ the owning plugin; every bound control gets label, disabled, pending, confirmation and messages from it.
5
+
6
+ ## Add an Action
7
+
8
+ ```sh
9
+ npx bitakit add action todos/sort
10
+ ```
11
+
12
+ - The file path is the ID, `<plugin>.<path>`: `actions/sort.ts` is `todos.sort`;
13
+ `npx bitakit add action todos/bulk/archive` writes `actions/bulk/archive.ts`, ID `todos.bulk.archive`.
14
+ The command never overwrites a file; to change the sample's `todos.clear`, edit `actions/clear.ts`.
15
+ App-wide Actions live in `src/actions/<name>.ts` (ID `<name>`); create those by hand.
16
+ - Each file default-exports one `defineAction({ ... })`; prefix helper files with `-`. Renaming the
17
+ file renames the ID; `npm run typecheck` flags stale IDs in `<Action>`, `useAction` and `slots`,
18
+ but search interceptor `action` targets and `<id>.*` catalog keys yourself.
19
+ - `title` is a literal or a translation key; a `<id>.title` catalog entry wins over a literal.
20
+ Without `title`, the last ID segment is used (`clear-done` shows "Clear done").
21
+
22
+ ## Derive state from services and settings
23
+
24
+ `src/plugins/todos/actions/add.ts` (from the sample):
25
+
26
+ ```ts
27
+ import { defineAction } from '@bitakit/core';
28
+
29
+ export default defineAction<string>({
30
+ title: 'Add',
31
+ // Bound buttons stay disabled while the input is empty or the list is full.
32
+ enabled: ({ input, services, settings }) =>
33
+ !!input?.trim() && services.todos.list.state.get().todos.length < settings.todos.limit.get(),
34
+ execute: ({ services, input }) => services.todos.list.add(input),
35
+ });
36
+ ```
37
+
38
+ - `title`, `description`, `tooltip`, `variant`, `href`, `enabled`, `visible`, `checked` and `value`
39
+ take a value or a function of `{ input, services, config, settings, app }`. Functions re-run when
40
+ a store or setting they read changes; `input` there is raw and may be `undefined` (menus, search).
41
+ - `enabled: false` disables bound controls and `visible: false` renders nothing; both block
42
+ execution. They are UI rules, not server authorization.
43
+ - `input: z.string().trim().min(1)` (any Standard Schema or object with `parse`) replaces
44
+ `defineAction<string>`: it infers the type and `execute` gets the parsed value. zod is not in the
45
+ generated `package.json`; ask the user before adding it. A schema disables controls while the
46
+ input is invalid only when `enabled` is not set.
47
+
48
+ ## Run, confirm and report
49
+
50
+ `src/plugins/todos/actions/clear.ts`:
51
+
52
+ ```ts
53
+ import { defineAction } from '@bitakit/core';
54
+
55
+ export default defineAction({
56
+ title: 'Clear all',
57
+ enabled: ({ services }) => services.todos.list.state.get().todos.length > 0,
58
+ confirm: {
59
+ title: 'Delete every todo?',
60
+ description: 'This cannot be undone.',
61
+ destructive: true,
62
+ },
63
+ execute: ({ services }) => services.todos.list.clear(),
64
+ success: 'All todos deleted',
65
+ });
66
+ ```
67
+
68
+ - `variant: 'destructive'` on an Action styles menu items only; give a bound `<Button>` its own
69
+ `variant` prop.
70
+ - `execute` gets `{ input, services, config, settings, app, events, signal, id, get, update }`. Its
71
+ return value becomes `{ status: 'completed', value }`; a throw makes the run fail.
72
+ - `confirm`: a string (title only), `{ title, description, destructive? }`, or a function returning
73
+ one of those or `false` to skip the question. Declining skips the run with reason `cancelled`.
74
+ - `success` / `failure`: a string (tried as a translation key first), `{ messageKey, values }`,
75
+ `false`, or a function of `{ result | error, input, services }`. Success is silent by default.
76
+ - `concurrency`: `'exclusive'` (default; skips a second run while one is pending), `'per-input'`
77
+ (pending per input, as `todos.remove` does for rows) or `'latest'` (aborts the previous `signal`).
78
+
79
+ ## Use another plugin's service and place the Action
80
+
81
+ `npx bitakit add action print/list` creates `src/plugins/print/actions/list.ts` (ID `print.list`):
82
+
83
+ ```ts
84
+ import { defineAction } from '@bitakit/core';
85
+
86
+ export default defineAction({
87
+ title: 'Print list',
88
+ slots: ['todos.toolbar'],
89
+ // todos.list belongs to another plugin; listing it turns a missing service into a startup error.
90
+ requires: ['todos.list'],
91
+ enabled: ({ services }) => services.todos.list.state.get().todos.length > 0,
92
+ execute: () => window.print(),
93
+ });
94
+ ```
95
+
96
+ - `requires` lists services of other plugins only; the plugin's own services need no entry.
97
+ - `slots` places the Action in a declared actions slot ([slots.md](slots.md) declares and renders
98
+ `todos.toolbar`); `groups` is logical membership and never places UI.
99
+ - `shortcut: { keys: 'Mod+Shift+P' }` adds a keyboard shortcut with the same guards as a click. To
100
+ block or check another plugin's Action, use an interceptor ([interceptors.md](interceptors.md)).
101
+ - `href` makes a navigation Action, like the sample's `todos/actions/open.ts`:
102
+ `defineAction({ title: 'Todos', href: '/todos', slots: ['shell.navigation'] })`. The page is its
103
+ own file ([plugins-and-pages.md](plugins-and-pages.md)).
104
+ - `dialog: { component, size? }` opens a `ui/dialogs/` component (`npx bitakit add dialog
105
+ <plugin>/<name>`) instead of running `execute`; defining both throws.
106
+
107
+ ## Bind controls
108
+
109
+ `src/plugins/todos/ui/todos-controls.tsx` (render `<TodosControls />` from `ui/pages/index.tsx`):
110
+
111
+ ```tsx
112
+ 'use client';
113
+ import { useState } from 'react';
114
+ import { Action, ActionButton, ActionLink } from '@bitakit/ui';
115
+ import { Button, Input } from '@bitakit/ui/components';
116
+
117
+ export function TodosControls() {
118
+ const [title, setTitle] = useState('');
119
+ return (
120
+ <div className="flex gap-2">
121
+ <Input
122
+ value={title}
123
+ aria-label="New todo"
124
+ onChange={(event) => setTitle(event.target.value)}
125
+ />
126
+ {/* An empty child receives the Action's title. Keep the draft when the run was skipped. */}
127
+ <Action
128
+ id="todos.add"
129
+ input={title}
130
+ onExecuted={(result) => result.status === 'completed' && setTitle('')}
131
+ >
132
+ <Button />
133
+ </Action>
134
+ <ActionButton action="todos.clear" as={Button} variant="outline" />
135
+ <ActionLink action="todos.open" />
136
+ </div>
137
+ );
138
+ }
139
+ ```
140
+
141
+ - `<Action id input onExecuted onError kind pending>` merges `onClick`, `disabled` and `aria-busy`
142
+ into its one child; leave those to the Action. `onExecuted` also fires for `{ status: 'skipped' }`
143
+ (declined confirm, interceptor).
144
+ - `ActionButton` and `ActionLink` take `action` (not `id`, which stays the HTML attribute) and `as`.
145
+ - An `href` Action renders as a real link (a plain `<a>` child becomes the router link). A hidden
146
+ or unregistered Action renders nothing; a misspelled ID fails `npm run typecheck`.
147
+
148
+ ## Build a custom control with useAction
149
+
150
+ `src/plugins/todos/ui/clear-button.tsx`:
151
+
152
+ ```tsx
153
+ 'use client';
154
+ import { useAction } from '@bitakit/ui';
155
+ import { Button } from '@bitakit/ui/components';
156
+
157
+ export function ClearButton() {
158
+ const clear = useAction('todos.clear');
159
+ if (!clear?.visible) return null;
160
+ return (
161
+ <Button variant="outline" {...clear.props()}>
162
+ {clear.pending ? 'Clearing…' : clear.title}
163
+ </Button>
164
+ );
165
+ }
166
+ ```
167
+
168
+ - `useAction(id, input?)` is `undefined` until the Action is registered; then it holds the state
169
+ (`title`, `enabled`, `visible`, `pending`, `disabled`, `status`, `error`, ...), the getters `props()`,
170
+ `linkProps()`, `checkedProps()`, `valueProps()`, `menuItemProps()`, and `execute(input?)`, which
171
+ resolves to the outcome and rejects on failure (the getters report errors for you).
172
+
173
+ ## Keep several Actions in one file
174
+
175
+ `src/plugins/print/actions.ts` can hold `print.list` (same ID) instead of `actions/list.ts`:
176
+
177
+ ```ts
178
+ import { defineAction } from '@bitakit/core';
179
+
180
+ export default {
181
+ list: defineAction({
182
+ title: 'Print list',
183
+ slots: ['todos.toolbar'],
184
+ execute: () => window.print(),
185
+ }),
186
+ };
187
+ ```
188
+
189
+ - Each key becomes `<plugin>.<key>`, so splitting into `actions/<key>.ts` later keeps the IDs; one
190
+ ID in both forms fails at startup as a duplicate.
191
+ - A bare `export default defineAction(...)` in `actions.ts` fails at app start ("Collection needs
192
+ named entries"); typecheck and doctor do not catch it.
193
+
194
+ ## Explain it to the user
195
+
196
+ Name the owning plugin and ID (`todos.clear` in `src/plugins/todos/actions/clear.ts`), the service it
197
+ calls and where it appears (the todos page, `shell.navigation` or the `todos.toolbar` slot). Tell them
198
+ how to try it: open `/todos`, add a todo, use the button, and expect any confirmation or disabled rule.
@@ -0,0 +1,164 @@
1
+ # Interceptors
2
+
3
+ Use an interceptor to block an Action run at the last moment, to observe Action runs across
4
+ plugins, or to watch calls to a service method, without editing the Action or service itself.
5
+
6
+ ## Block an Action run
7
+
8
+ ```bash
9
+ npx bitakit add interceptor todos/no-duplicates
10
+ ```
11
+
12
+ The command writes `src/plugins/todos/interceptors/no-duplicates.ts` with a logging template that
13
+ observes `todos.*`. Replace its body:
14
+
15
+ ```ts
16
+ import { defineInterceptor } from '@bitakit/core';
17
+
18
+ export default defineInterceptor({
19
+ action: 'todos.add',
20
+ before: ({ input, services }) => {
21
+ const title = String(input ?? '')
22
+ .trim()
23
+ .toLowerCase();
24
+ // Returning false skips the run; any other value lets it continue.
25
+ return !services.todos.list.state
26
+ .get()
27
+ .todos.some((todo) => todo.title.toLowerCase() === title);
28
+ },
29
+ });
30
+ ```
31
+
32
+ - When `before` returns `false`, the caller receives `{ status: 'skipped', reason: 'intercepted' }`.
33
+ The run shows no toast, throws no error and changes no Action state. A returned promise is
34
+ awaited, and the control shows pending while it waits.
35
+ - `<Action onExecuted>` also fires for skipped runs. To keep the typed title after a blocked add,
36
+ check the status in the sample page:
37
+ `onExecuted={(result) => { if (result.status === 'completed') setTitle(''); }}`.
38
+ - Hook context: `id`, the raw `input` (typed `unknown`, so narrow it), `signal`, `get`, `update`,
39
+ `services`, `config`, `app` and `translate`. Read settings with
40
+ `app.settings.todos.limit.get()`. `app.events` only has `on`. The `settings` and `events`
41
+ shortcuts of an Action's `execute` are not available here.
42
+ - `before` runs only for a visible, enabled Action. If it throws, the run fails and `onError`
43
+ receives the error, so return `false` to block a run quietly.
44
+ - This is a client execution rule. Keep server authorization on the server.
45
+
46
+ ## Watch Actions of another plugin
47
+
48
+ ```bash
49
+ npx bitakit add interceptor activity/todo-errors
50
+ ```
51
+
52
+ `src/plugins/activity/interceptors/todo-errors.ts`:
53
+
54
+ ```ts
55
+ import { defineInterceptor } from '@bitakit/core';
56
+
57
+ export default defineInterceptor({
58
+ action: 'todos.*',
59
+ // Without this, an interceptor only sees the Actions of its own plugin (activity).
60
+ scope: 'global',
61
+ after: ({ id, input }) => console.info('[activity] done', id, input),
62
+ onError: ({ id, error }) => console.error('[activity] failed', id, error),
63
+ });
64
+ ```
65
+
66
+ - `scope: 'plugin'` is the default for plugin interceptors and matches only Actions that the
67
+ same plugin registered, even when `action` names another plugin's ID. Set `scope: 'global'` to
68
+ reach other plugins.
69
+ - `action` takes one ID, a list of IDs, an ID prefix such as `'todos.*'`, or `'*'`. Omit it to
70
+ match every Action of the same plugin. Patterns match Action IDs, not `groups`.
71
+ - `after` receives `result`, the value returned by `execute`, for completed runs. `onError`
72
+ receives `error` for failed runs. Skipped runs reach neither hook. The return values and
73
+ promises of these hooks never change the outcome, and their own errors are only logged.
74
+ - `order` (default `0`) sorts all Action interceptors, lowest first. The first `before` that
75
+ returns `false` stops the remaining interceptors.
76
+ - `requires: ['todos.list']` makes startup fail with a clear message when that service is
77
+ missing. `npx bitakit doctor` checks these names.
78
+
79
+ ## Add an app-wide interceptor
80
+
81
+ `bitakit add` has no app-level target. To add one, create `src/interceptors/action-log.ts`:
82
+
83
+ ```ts
84
+ import { defineInterceptor } from '@bitakit/core';
85
+
86
+ export default defineInterceptor({
87
+ action: '*',
88
+ after: ({ id }) => console.info('[action-log]', id),
89
+ });
90
+ ```
91
+
92
+ - Files in `src/interceptors/` are global by default. Set `scope: 'plugin'` to limit one of them
93
+ to the app's own `src/actions`.
94
+ - All app interceptors are active by default. To select some of them, list their file names in
95
+ `bitakit.config.ts` next to `package.json` (create it if the app has none):
96
+
97
+ ```ts
98
+ import { defineBitaKit } from '@bitakit/discovery';
99
+
100
+ export default defineBitaKit({
101
+ interceptors: { enabled: ['action-log'] },
102
+ });
103
+ ```
104
+
105
+ A name without a matching file stops `bitakit generate`. This list never affects plugin
106
+ interceptors.
107
+
108
+ - Put rules that belong to one feature in that feature's plugin folder so the rule is removed
109
+ together with the plugin.
110
+
111
+ ## Observe a service method
112
+
113
+ ```bash
114
+ npx bitakit add interceptor todos/trace-list
115
+ ```
116
+
117
+ Replace the template in `src/plugins/todos/interceptors/trace-list.ts`:
118
+
119
+ ```ts
120
+ import { defineInterceptor } from '@bitakit/core';
121
+
122
+ export default [
123
+ defineInterceptor({
124
+ service: 'todos.list',
125
+ method: 'add',
126
+ after: ({ args }) => console.info('[todos] added', args[0]),
127
+ }),
128
+ defineInterceptor({
129
+ service: 'todos.list',
130
+ method: 'clear',
131
+ before: () => console.info('[todos] clearing'),
132
+ }),
133
+ ];
134
+ ```
135
+
136
+ - Service hooks only observe. They receive `service`, `method` and `args`, plus the awaited
137
+ `result` or the `error`, and cannot block a call or change it. Leave `args` and `result`
138
+ unchanged.
139
+ - They see every call made through the service container, from Actions, pages and other
140
+ services. They do not see a service calling its own methods internally.
141
+ - Each definition targets either `action` or `service`. Setting both throws. To cover several
142
+ targets, default-export an array as above.
143
+ - Omit `method` to observe every public method. `service: 'todos.*'` matches a name prefix.
144
+ Hooks run synchronously, and their promises are ignored.
145
+
146
+ ## Choose an interceptor, `enabled`, `execute` or an event
147
+
148
+ - For a rule the user should see before clicking, such as a disabled button, use the owner's
149
+ Action `enabled`. The sample `todos.add` already checks `todos.limit` there.
150
+ - For a rule that is part of the operation itself, put it in `execute` or in the service method.
151
+ - Use an interceptor for a rule over Actions you do not own, a rule shared by many Actions, or a
152
+ check that must run asynchronously at execution time.
153
+ - To react to a change, listen to the owner's event, as `activity` does with `todos.changed`.
154
+ Use an interceptor's `after` only when the owner emits no event.
155
+
156
+ ## Explain it to the user
157
+
158
+ - Say which plugin owns the interceptor (for example "todos, in
159
+ `src/plugins/todos/interceptors/no-duplicates.ts`") and which Action ID or service it targets.
160
+ If it uses `scope: 'global'`, say that it reaches Actions of other plugins.
161
+ - Say what the user will notice. A blocked run does nothing visible: the todo is not added and
162
+ no message appears. Observers only write to the browser console.
163
+ - To try it, open `/todos`, add "Milk" twice and see that only one appears. For an observer, open
164
+ the browser console and add or clear a todo.
@@ -0,0 +1,165 @@
1
+ # Plugins and pages
2
+
3
+ Use this when the user asks for a new feature, a new screen or a sidebar entry. The example is
4
+ `about`: a page-only plugin at `/about` with a link in the Shell sidebar.
5
+
6
+ ## Create a plugin
7
+
8
+ ```sh
9
+ npx bitakit add plugin about
10
+ ```
11
+
12
+ - Default: `ui/pages/index.tsx` (served at `/about`) and, only when `@bitakit/shell` is in
13
+ `package.json`, `actions/open.ts`, which places the link in `shell.navigation`. Without Shell
14
+ the page is reached by URL only.
15
+ - `--example` writes a complete feature: `services/list.ts`, `events.ts`, the Actions `add`,
16
+ `remove`, `clear` and `open`, and a list page. `--minimal` writes only `services/list.ts`,
17
+ `events.ts` and `actions/add.ts`: no page and no link.
18
+ - The templates are a starting point. Replace their bodies, placeholder subtitles ("Edit this
19
+ page in ...") and tutorial comments with the real feature, and delete files it does not need.
20
+ - Names start with a lowercase letter and use lowercase letters, digits and single hyphens
21
+ (`about`, `release-notes`). Choose a name the app does not already own: the CLI refuses
22
+ `settings`, `api`, `login` and `register` because those are app routes (`--minimal` skips this
23
+ check), and `app` is the app's own plugin ID, so `bitakit generate` rejects it as a duplicate.
24
+ `npx bitakit info` lists the existing plugin IDs.
25
+ - The CLI never overwrites. It stops when the folder or file already exists.
26
+
27
+ ## Folder = feature, file path = ID
28
+
29
+ Everything for one feature lives in `src/plugins/<name>/`. Discovery derives IDs and URLs from
30
+ file paths, so there is nothing to register.
31
+
32
+ | File in `src/plugins/...` | Becomes |
33
+ | --------------------------------------------- | ------------------------------- |
34
+ | `about/actions/open.ts` | Action `about.open` |
35
+ | `todos/services/list.ts` | Service `todos.list` |
36
+ | `about/ui/pages/index.tsx` | Page `/about` |
37
+ | `about/ui/pages/team.tsx` or `team/index.tsx` | Page `/about/team` |
38
+ | `todos/ui/pages/[id].tsx` | Page `/todos/<id>`, `params.id` |
39
+
40
+ - Dots and folders mean the same: `ui/pages/team.history.tsx` equals `ui/pages/team/history.tsx`.
41
+ - Every file with a default export under `ui/pages/` becomes a page (a `-` name prefix excludes
42
+ a file). Put shared components in `ui/components/`, which discovery treats as ordinary imports.
43
+ - Renaming a file changes its ID or URL. Update the `href`s and `<Action id>`s that use it.
44
+
45
+ ## Add a page
46
+
47
+ ```sh
48
+ npx bitakit add page about/team
49
+ ```
50
+
51
+ This writes `src/plugins/about/ui/pages/team.tsx` for `/about/team`; nested names such as
52
+ `about/team/history` work too. The plugin's root page is `ui/pages/index.tsx`:
53
+
54
+ ```tsx
55
+ 'use client';
56
+ import { PageHeader } from '@bitakit/ui/components';
57
+
58
+ export default function AboutPage() {
59
+ return (
60
+ <div className="flex flex-col gap-6">
61
+ <PageHeader title="About" subtitle="What this app is for and who builds it." />
62
+ <p className="text-sm text-muted-foreground">This app keeps a short list of things to do.</p>
63
+ </div>
64
+ );
65
+ }
66
+ ```
67
+
68
+ - Start every file under `ui/` with `'use client'`. The page is the default export.
69
+ - `PageHeader` renders the page's heading: `title`, optional `subtitle`, and `trailing` for
70
+ page-level buttons. Build the rest from `@bitakit/ui/components` (`Button`, `Input`, `Badge`,
71
+ `Separator`, ...) and theme classes such as `text-muted-foreground`; layout with flex and gap.
72
+ - Bind each button that runs an operation to its Action (`<Action id="todos.add"><Button /></Action>`)
73
+ and read service state with `useServiceState`, as `todos/ui/pages/index.tsx` does.
74
+
75
+ ## Read a URL parameter
76
+
77
+ `bitakit add page` accepts plain names only, so create a parameter page by hand:
78
+ `src/plugins/todos/ui/pages/[id].tsx`.
79
+
80
+ ```tsx
81
+ 'use client';
82
+ import { useServiceState } from '@bitakit/ui';
83
+ import { PageHeader } from '@bitakit/ui/components';
84
+
85
+ // Served at /todos/<id>; URL parameters are always strings, so convert before comparing.
86
+ export default function TodoPage({ params }: { params: { id: string } }) {
87
+ const todo = useServiceState('todos.list', (state) =>
88
+ state.todos.find((candidate) => candidate.id === Number(params.id)),
89
+ );
90
+ return <PageHeader title={todo?.title ?? 'Todo not found'} subtitle={`Todo ${params.id}`} />;
91
+ }
92
+ ```
93
+
94
+ - `PluginPage` passes the decoded segments as the `params` prop. Each `[name]` matches exactly
95
+ one segment; catch-all and optional segments are not supported in plugin pages.
96
+ - An exact page wins over a parameter page: `ui/pages/new.tsx` serves `/todos/new` before `[id]`.
97
+ - Render a "not found" state yourself when the parameter matches nothing.
98
+
99
+ ## Choose a layout
100
+
101
+ ```sh
102
+ npx bitakit add layout full-page
103
+ ```
104
+
105
+ Replace the template in `src/layouts/full-page.tsx` with `import { AppShell } from '@bitakit/shell';`
106
+ and `export default AppShell.FullPage;`. A page opts in with one export:
107
+
108
+ ```tsx
109
+ 'use client';
110
+ import { PageHeader } from '@bitakit/ui/components';
111
+
112
+ // The name of src/layouts/full-page.tsx: this page renders without the sidebar and header.
113
+ export const layout = 'full-page';
114
+
115
+ export default function AboutTeamPage() {
116
+ return <PageHeader title="Team" subtitle="The people behind this app." />;
117
+ }
118
+ ```
119
+
120
+ - Values: no export or `'app'` for the normal frame, `'blank'` for a bare page, or the file name
121
+ of a layout in `src/layouts/<name>.tsx`. An unknown name stops startup with an error that names the
122
+ missing `src/layouts/<name>.tsx` and the valid choices.
123
+ - Shell's `AppShell` applies the choice. In an app without Shell, read its layout before relying
124
+ on `export const layout`.
125
+ - `AppShell.FullPage` keeps Shell's page spacing and the `shell.content.before/after` regions;
126
+ `'blank'` keeps nothing.
127
+
128
+ ## Link the page in the sidebar
129
+
130
+ `src/plugins/about/actions/open.ts`:
131
+
132
+ ```ts
133
+ import { defineAction } from '@bitakit/core';
134
+
135
+ export default defineAction({
136
+ title: 'About',
137
+ href: '/about',
138
+ groups: ['navigation'],
139
+ slots: ['shell.navigation'],
140
+ });
141
+ ```
142
+
143
+ - `slots: ['shell.navigation']` places the link; `groups` is only a logical query. Shell renders
144
+ an Action with `href` as a native link, labelled by `title`.
145
+ - `src/configs/shell.ts` names the navigation slot (`navigationSlot: 'shell.navigation'`). Other
146
+ placements, such as `shell.toolbar` or a plugin's own Action slot, are in [slots.md](slots.md).
147
+ - `npx bitakit doctor` warns when a link's `href` has no page or app route.
148
+
149
+ ## Plugin pages and app routes
150
+
151
+ - The catch-all route `src/app/(app)/[...path]/page.tsx` renders `<PluginPage>` inside
152
+ `AppShell`. Plugin pages render in the browser once the BitaKit runtime is ready; the server
153
+ sends no page content for them.
154
+ - Keep pages that need server rendering, Next.js `metadata`, server-side redirects or API route
155
+ handlers as native routes in `src/app` (for example `src/app/(app)/pricing/page.tsx`).
156
+ - An app route at the same path wins over a plugin page; doctor reports it as an error.
157
+ - Check with `npm run typecheck` (it runs `bitakit generate`) and `npx bitakit doctor`, which
158
+ confirms that every plugin page can be reached and every navigation link has a page.
159
+
160
+ ## Explain it to the user
161
+
162
+ Say which plugin owns the page (`src/plugins/about`), that its URL comes from the file
163
+ `ui/pages/index.tsx` (`/about`), and that the sidebar entry is the Action `about.open` placed in
164
+ Shell's `shell.navigation` slot. To try it: start the dev server, click "About" in the navigation (the
165
+ sidebar, or the top bar in Shell's navbar layout) or open `/about`.