@jskit-ai/agent-docs 0.1.1

package/guide/human/generators/crud-generators.md

@@ -0,0 +1,556 @@
+<!-- Generated by `npm run agent-docs:build` from `docs/guide/generators/crud-generators.md`. Do not edit manually. -->
+
+# CRUD Generators
+
+CRUD generation in JSKIT is really one workflow split across two generator packages:
+
+- `crud-server-generator` creates the app-local server/resource package
+- `crud-ui-generator` creates the route tree that uses that shared resource contract
+
+So the real order is always:
+
+1. create a real table
+2. scaffold the server package around it
+3. scaffold the UI around the generated resource file
+
+This chapter uses three examples, in increasing complexity:
+
+- `contacts`: the baseline full CRUD walkthrough
+- `addresses`: a child CRUD with its own routed list page
+- `comments`: a child CRUD that lives inside the parent page, with only the child routes being routed
+
+The examples assume the guide app already has the database and workspace/admin setup from the earlier chapters. That is why the route roots below live under `w/[workspaceSlug]/admin/...`.
+
+This is the workflow chapter.
+
+It is meant to answer:
+
+- which generator do I run first?
+- what order do the server and UI steps go in?
+- what shape of CRUD should I generate for this feature?
+
+Once that workflow is clear, continue with [Advanced CRUDs](/guide/generators/advanced-cruds) for the generated package anatomy, ownership model, and customization boundaries.
+
+## The two generator packages
+
+### `crud-server-generator` `@jskit-ai/crud-server-generator` `(0.1.47)`
+
+This is the server-side half.
+
+It introspects a real table and writes an app-local package with things like:
+
+- repository logic
+- service logic
+- route registration
+- action definitions
+- the shared resource module that describes the CRUD contract
+
+The main subcommand is:
+
+- `scaffold`
+
+There is also:
+
+- `scaffold-field`
+
+which is for patching one extra field into an already-generated resource module after a schema change.
+
+### `crud-ui-generator` `@jskit-ai/crud-ui-generator` `(0.1.22)`
+
+This is the UI half.
+
+It reads the generated shared resource module and creates app-owned pages under an explicit route root relative to `src/pages/`.
+
+The main subcommand is:
+
+- `crud`
+
+That command can generate any combination of:
+
+- `list`
+- `view`
+- `new`
+- `edit`
+
+That flexibility is what makes the later `comments` example possible.
+
+## Understanding ownership filters
+
+`--ownership-filter` is one of the most important CRUD generator options.
+
+It is not just "one more flag." It tells JSKIT what kind of ownership the generated CRUD assumes:
+
+- whether records are shared or owner-scoped
+- which owner columns the CRUD expects
+- what request context the generated routes and repository use to filter records
+
+In plain English, it answers:
+
+- who should be able to see these rows?
+- what kind of owner does each row belong to?
+
+The supported values are:
+
+| Value | Plain meaning | Typical owner columns |
+| --- | --- | --- |
+| `auto` | infer ownership from the real table during generation | inferred from table shape |
+| `public` | no owner scoping | no `workspace_id` or `user_id` required |
+| `user` | rows belong to one user | `user_id` |
+| `workspace` | rows belong to one workspace | `workspace_id` |
+| `workspace_user` | rows belong to one workspace and one user together | `workspace_id` and `user_id` |
+
+### What each value means
+
+#### `public`
+
+Choose `public` when the same records should be visible across the app, subject only to the usual route/action permissions.
+
+This is the right mental model for things like:
+
+- global lookup tables
+- app-wide reference data
+- shared configuration records that are not owned by one user or one workspace
+
+A `public` CRUD does **not** expect owner scoping columns.
+
+#### `user`
+
+Choose `user` when each record belongs to one user, regardless of which app surface is showing it.
+
+This is the right mental model for things like:
+
+- my own saved items
+- my saved views
+- my personal preferences records when they are stored as CRUD rows
+
+The important owner column is:
+
+- `user_id`
+
+#### `workspace`
+
+Choose `workspace` when records belong to the workspace as a whole.
+
+This is the most common choice for workspace-admin CRUDs such as:
+
+- contacts
+- appointments
+- products
+- workspace-wide CRM records
+
+The important owner column is:
+
+- `workspace_id`
+
+This is why the chapter's `contacts` example uses `workspace`: the records belong to the workspace, not to one specific member inside it.
+
+#### `workspace_user`
+
+Choose `workspace_user` when a record belongs to a workspace **and** to a specific user within that workspace.
+
+This is the right mental model for things like:
+
+- personal notes inside a workspace
+- per-user workspace drafts
+- user-owned workspace artifacts that should not be visible to every workspace member
+
+The important owner columns are:
+
+- `workspace_id`
+- `user_id`
+
+This is stricter than plain `workspace`. The row is not only "inside this workspace." It is "inside this workspace, for this user."
+
+#### `auto`
+
+`auto` is not a runtime mode. It is a **generation-time inference**.
+
+When you scaffold against a real table, the generator inspects the table columns and resolves `auto` like this:
+
+- `workspace_id` and `user_id` present -> `workspace_user`
+- `workspace_id` only -> `workspace`
+- `user_id` only -> `user`
+- neither present -> `public`
+
+So `auto` is useful when the table already exists and its ownership columns already tell the truth.
+
+If you already know the intended ownership model and want the command to fail when the table does not match it, choose the explicit value instead of `auto`.
+
+### Which one should I choose?
+
+Use this rule of thumb:
+
+- choose `public` for shared reference/config data
+- choose `user` for "my own" records
+- choose `workspace` for workspace-wide business data
+- choose `workspace_user` for personal records that still live inside a workspace
+- choose `auto` when you are scaffolding from an existing table and want JSKIT to infer ownership from the owner columns already present
+
+Another useful way to think about it is this:
+
+- if two different users in the same workspace should normally see the same row, that is probably `workspace`
+- if they should **not** normally see the same row, that is probably `workspace_user`
+- if the row is not workspace-specific at all, it is probably `public` or `user`
+
+### One more important constraint
+
+Ownership also has to make sense for the target surface.
+
+In practice:
+
+- `workspace` and `workspace_user` belong on workspace-enabled surfaces
+- `public` and `user` can live on non-workspace surfaces too
+
+So if you are generating under a route like:
+
+```text
+w/[workspaceSlug]/admin/...
+```
+
+then `workspace` is usually the normal default. If you are generating a CRUD for a global operator or account area, `public` or `user` may make more sense.
+
+## Example 1: `contacts`
+
+This is the baseline pattern. If you understand this example, the rest of the chapter becomes much easier.
+
+### Step 1: create the table first
+
+Start with a real table. The server generator reads the database schema; it does not invent it for you.
+
+Example:
+
+```sql
+CREATE TABLE contacts (
+  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
+  workspace_id BIGINT UNSIGNED NOT NULL,
+  full_name VARCHAR(190) NOT NULL,
+  email VARCHAR(190) NULL,
+  phone VARCHAR(50) NULL,
+  notes TEXT NULL,
+  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  KEY idx_contacts_workspace_id (workspace_id)
+);
+```
+
+The exact fields will vary by app. What matters for the generator is:
+
+- the table already exists
+- the ownership columns match the ownership filter you are going to choose
+- the column names are stable enough to become part of your app's resource contract
+
+In this table, `workspace_id` is the important ownership clue. That is why the next step uses:
+
+```bash
+--ownership-filter workspace
+```
+
+This CRUD is not "my contacts." It is "the workspace's contacts."
+
+### Step 2: scaffold the server package
+
+Now generate the server-side CRUD package:
+
+```bash
+npx jskit generate crud-server-generator scaffold \
+  --namespace contacts \
+  --surface admin \
+  --ownership-filter workspace \
+  --table-name contacts
+```
+
+This creates an app-local package under `packages/contacts/`.
+
+The most important file from the UI point of view is:
+
+```text
+packages/contacts/src/shared/contactResource.js
+```
+
+That file is the shared CRUD contract. The UI generator reads it to decide:
+
+- which operations exist
+- which fields are readable or writable
+- which relations are exposed
+- how to build the generated pages
+
+So even though the server scaffold writes many files, the resource file is the bridge between the server and UI halves.
+
+### Step 3: scaffold the UI
+
+Once the resource file exists, generate the UI route tree:
+
+```bash
+npx jskit generate crud-ui-generator crud \
+  w/[workspaceSlug]/admin/contacts \
+  --resource-file packages/contacts/src/shared/contactResource.js \
+  --id-param contactId \
+  --display-fields fullName,email,phone
+```
+
+That creates the baseline CRUD route tree:
+
+- `w/[workspaceSlug]/admin/contacts/index.vue`
+- `w/[workspaceSlug]/admin/contacts/new.vue`
+- `w/[workspaceSlug]/admin/contacts/[contactId]/index.vue`
+- `w/[workspaceSlug]/admin/contacts/[contactId]/edit.vue`
+- shared `_components` files under the same route root
+
+This is the most important mental model in the whole chapter:
+
+- `crud-server-generator` creates the reusable CRUD contract and server package
+- `crud-ui-generator` turns that contract into app-owned pages
+
+If you want to see exactly what lands in `packages/contacts/`, which files own repository/service/action logic, and how search/filter customization is supposed to work, continue with [Advanced CRUDs](/guide/generators/advanced-cruds) once this baseline flow is clear.
+
+### Why this is the baseline example
+
+`contacts` is the cleanest first example because nothing fancy is happening yet:
+
+- it has a normal routed list page
+- it has a normal routed view page
+- it has normal `new` and `edit` pages
+- it uses one straightforward resource contract
+
+That is the shape to learn first.
+
+## Example 2: `addresses`
+
+Now move to a child CRUD with its own URL.
+
+This is the right pattern when the child collection deserves its own list page.
+
+Example route:
+
+```text
+.../contacts/3/addresses
+```
+
+In the guide app's real route tree, that becomes:
+
+```text
+w/[workspaceSlug]/admin/contacts/[contactId]/addresses
+```
+
+### Step 1: create the child table
+
+Example:
+
+```sql
+CREATE TABLE addresses (
+  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
+  workspace_id BIGINT UNSIGNED NOT NULL,
+  contact_id BIGINT UNSIGNED NOT NULL,
+  label VARCHAR(100) NULL,
+  line_1 VARCHAR(190) NOT NULL,
+  line_2 VARCHAR(190) NULL,
+  suburb VARCHAR(120) NULL,
+  state VARCHAR(80) NULL,
+  postcode VARCHAR(20) NULL,
+  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  KEY idx_addresses_workspace_id (workspace_id),
+  KEY idx_addresses_contact_id (contact_id)
+);
+```
+
+The important extra column here is `contact_id`. This is what makes the CRUD a child of a contact instead of a top-level resource.
+
+### Step 2: scaffold the server package
+
+```bash
+npx jskit generate crud-server-generator scaffold \
+  --namespace addresses \
+  --surface admin \
+  --ownership-filter workspace \
+  --table-name addresses
+```
+
+### Step 3: scaffold the UI at the child route root
+
+```bash
+npx jskit generate crud-ui-generator crud \
+  w/[workspaceSlug]/admin/contacts/[contactId]/addresses \
+  --resource-file packages/addresses/src/shared/addressResource.js \
+  --id-param addressId \
+  --display-fields label,line1,postcode
+```
+
+That gives you a proper child CRUD with its own list, view, new, and edit pages under the contact route.
+
+### The important refinement: parent title handling
+
+This is where nested CRUD starts to feel real.
+
+An addresses list page should not show a generic heading like `Addresses`. It should usually show whose addresses these are, for example:
+
+- `Jane Smith's addresses`
+- `Acme Pty Ltd's addresses`
+
+The awkward case is when there are **no child rows yet**. If the list is empty, you cannot derive the parent title from the first address record.
+
+That is why JSKIT has `useCrudListParentTitle()`:
+
+```js
+const parentTitle = useCrudListParentTitle({
+  listRuntime: records,
+  resource: uiResource,
+  recordIdParam: "addressId",
+  fallbackLoadError: "Unable to load contact.",
+  notFoundMessage: "Contact not found."
+});
+```
+
+That helper does the nice thing automatically:
+
+- if the child list already has rows, it derives the parent title from the first child record
+- if the child list is empty, it loads the parent record directly
+
+This is exactly the pattern used in the real app codebase for nested CRUD lists like a contact's pets. It avoids the common broken state where an empty child list loses all context about the parent it belongs to.
+
+So the `addresses` example is important because it teaches the first truly practical nested-CRUD problem:
+
+- the route is child-scoped
+- the data is child-scoped
+- but the page still needs a reliable parent identity even when the child list is empty
+
+## Example 3: `comments` in-page
+
+This is the advanced example.
+
+Sometimes a child resource is real enough to deserve its own CRUD operations, but **not** important enough to deserve its own full-screen list page.
+
+Comments are a good example:
+
+- they matter
+- they need persistence
+- they may need `view`, `new`, or `edit` routes
+- but the main screen is still the contact view page
+
+So the pattern is:
+
+- keep the contact page as the real host
+- render the comments list inside that page
+- route only the child operations underneath it
+
+### Step 1: create the table
+
+Example:
+
+```sql
+CREATE TABLE comments (
+  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
+  workspace_id BIGINT UNSIGNED NOT NULL,
+  contact_id BIGINT UNSIGNED NOT NULL,
+  author_user_id BIGINT UNSIGNED NULL,
+  body TEXT NOT NULL,
+  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  KEY idx_comments_workspace_id (workspace_id),
+  KEY idx_comments_contact_id (contact_id)
+);
+```
+
+### Step 2: scaffold the server package
+
+```bash
+npx jskit generate crud-server-generator scaffold \
+  --namespace comments \
+  --surface admin \
+  --ownership-filter workspace \
+  --table-name comments
+```
+
+### Step 3: make the parent page able to host routed children
+
+If the contact view page should stay visible while child comment routes render underneath it, first upgrade it into a routed host:
+
+```bash
+npx jskit generate ui-generator add-subpages \
+  w/[workspaceSlug]/admin/contacts/[contactId]/index.vue \
+  --title "Contact" \
+  --subtitle "View and manage this contact."
+```
+
+That is the point where the comments example deliberately overlaps with the `ui-generator` chapter. This pattern needs both:
+
+- CRUD scaffolding for the comments resource
+- a routed host in the parent contact page
+
+### Step 4: generate only the routed child operations
+
+Now generate the comments UI without a list page:
+
+```bash
+npx jskit generate crud-ui-generator crud \
+  w/[workspaceSlug]/admin/contacts/[contactId]/index/comments \
+  --resource-file packages/comments/src/shared/commentResource.js \
+  --operations view,new,edit \
+  --id-param commentId
+```
+
+This is the key move.
+
+By leaving `list` out:
+
+- you do **not** generate a standalone comments list page
+- the host contact page stays responsible for showing the comment list
+- the generated child routes still handle things like `new`, `view`, and `edit`
+
+### What the host page does
+
+The host page then renders the comment list directly, usually with lower-level CRUD composables such as:
+
+- `useCrudList()`
+- `useCrudAddEdit()`
+- `useCrudView()` when needed
+
+That is the same general pattern already used in the real app for embedded child records like pet notes: the record list lives inside the main view page, while routed child pages handle the operations that still deserve their own URLs.
+
+This pattern is useful when the child records are supporting detail rather than a destination in their own right.
+
+That is the real lesson of the `comments` example:
+
+- a child CRUD does **not** have to mean "make another full-screen list page"
+- you can keep the parent page as the main experience and route only the child operations that benefit from their own URLs
+
+## When `scaffold-field` matters
+
+After the initial scaffold, schema changes are normal.
+
+Suppose you add a `preferred_name` column to `contacts`. You do not have to regenerate the whole package just to expose that one new writable field.
+
+That is what `scaffold-field` is for:
+
+```bash
+npx jskit generate crud-server-generator scaffold-field \
+  preferredName \
+  packages/contacts/src/shared/contactResource.js \
+  --table-name contacts
+```
+
+Use this when:
+
+- the CRUD package already exists
+- the table has changed
+- you want to patch one writable field into the generated resource file
+
+It is a maintenance tool, not the first step in the workflow.
+
+## Summary
+
+The important thing is not memorizing commands. It is learning the three shapes:
+
+- `contacts`: a normal top-level CRUD
+- `addresses`: a child CRUD with its own routed list page
+- `comments`: a child CRUD that lives inside the parent page, with only the child operations routed
+
+Once you understand those three shapes, the two generator packages stop feeling like separate tools.
+
+They become one workflow:
+
+1. model the table
+2. scaffold the server/resource package
+3. scaffold only the UI shape that the feature actually needs
+
+The next chapter is [Advanced CRUDs](/guide/generators/advanced-cruds). Read it as the structural follow-on to this one: this chapter teaches how to generate the CRUD, and the next one teaches how to reason about the files you now own.

package/guide/human/generators/intro.md

@@ -0,0 +1,109 @@
+<!-- Generated by `npm run agent-docs:build` from `docs/guide/generators/intro.md`. Do not edit manually. -->
+
+# Generators
+
+By the end of the app-setup chapters, the guide app already has the main structural pieces in place:
+
+- a real shell
+- authenticated users
+- a database layer
+- operator tooling
+- workspace-aware routing
+
+This section changes focus.
+
+Generators are the part of JSKIT that write app-owned files on top of installed runtime packages.
+
+That is different from `npx jskit add package ...`:
+
+- `add package` installs reusable runtime capability into the app
+- `generate ...` creates local pages, components, placements, and support files that your app owns directly
+
+So the normal flow is:
+
+1. install the runtime packages that make the feature possible
+2. decide the exact app-owned route, component, or package you want
+3. run `npx jskit generate ...`
+4. review and keep editing the generated files
+
+One important detail: generator packages such as `ui-generator`, `crud-server-generator`, and `crud-ui-generator` are tooling surfaces. You normally do **not** add them to your app with `jskit add package ...`. You use them through the CLI, and they mutate your app-owned files.
+
+This intro is also the shared starting point for the rest of the generators section.
+
+## Recap From Previous Chapters
+
+To get back to the same starting point used in the later generator chapters, run:
+
+```bash
+SUPABASE_URL=...
+SUPABASE_KEY=...
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_NAME=exampleapp
+DB_USER=exampleapp
+DB_PASSWORD=secret
+
+npx @jskit-ai/create-app exampleapp --tenancy-mode personal
+cd exampleapp
+npm install
+
+npx jskit add package shell-web
+npx jskit add package auth-provider-supabase-core \
+  --auth-supabase-url "$SUPABASE_URL" \
+  --auth-supabase-publishable-key "$SUPABASE_KEY" \
+  --app-public-url "http://localhost:5173"
+npx jskit add bundle auth-base
+npx jskit add package database-runtime-mysql \
+  --db-host "$DB_HOST" \
+  --db-port "$DB_PORT" \
+  --db-name "$DB_NAME" \
+  --db-user "$DB_USER" \
+  --db-password "$DB_PASSWORD"
+npx jskit add package users-web
+npx jskit add package console-web
+npx jskit add package workspaces-core
+npx jskit add package workspaces-web
+npm install
+npm run db:migrate
+```
+
+If you are already continuing from the earlier guide chapters, you are already in the right place and can skip that setup.
+
+That baseline matters because the later generator examples assume:
+
+- a shell with placements and routed pages
+- authenticated users and user-owned routes
+- database-backed runtime packages
+- console and workspace surfaces that real generated pages can target
+
+## Current generator families
+
+Right now the guide splits generators into two practical groups:
+
+- `@jskit-ai/ui-generator` for non-CRUD pages, placed UI, subpage hosts, and generic outlets
+- `@jskit-ai/crud-server-generator` plus `@jskit-ai/crud-ui-generator` for end-to-end CRUD scaffolding
+
+For CRUD work, there are also two guide layers on purpose:
+
+- [CRUD Generators](/guide/generators/crud-generators) teaches the end-to-end workflow for generating a working CRUD
+- [Advanced CRUDs](/guide/generators/advanced-cruds) explains the generated package anatomy, ownership structure, and the safest places to customize it
+
+The intended reading order is:
+
+1. `CRUD Generators`
+2. `Advanced CRUDs`
+
+## Why generators matter
+
+This is one of the main JSKIT ideas:
+
+- packages own reusable framework/runtime behavior
+- generators write the app-local files that make that behavior concrete in your app
+
+That keeps the runtime reusable without hiding your real app UI behind opaque framework internals.
+
+## Next sections
+
+- [UI Generators](/guide/generators/ui-generators) covers the non-CRUD workflow built around `ui-generator`
+- [CRUD Generators](/guide/generators/crud-generators) covers the combined server-and-UI CRUD workflow using `contacts`, nested `addresses`, and in-page `comments`
+- [Advanced CRUDs](/guide/generators/advanced-cruds) is the follow-on chapter after `CRUD Generators`, and goes deeper into the generated CRUD structure, ownership boundaries, and search/filter customization