@jskit-ai/agent-docs 0.1.3 → 0.1.4

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

@@ -1,554 +0,0 @@
-# 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

@@ -1,107 +0,0 @@
-# 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