npm - @jskit-ai/agent-docs - Versions diffs - 0.1.131 → 0.1.133 - Mend

@jskit-ai/agent-docs 0.1.131 → 0.1.133

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.

Files changed (171) hide show

package/guide/agent/app-setup/upgrade-beta-1-to-final.md DELETED Viewed

@@ -1,252 +0,0 @@
-<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/site/guide/app-setup/upgrade-beta-1-to-final.md`. Do not edit manually. -->
-# Upgrade guide from Beta 1 to Final Release
-> Temporary migration guide. Delete this page after every maintained application has upgraded to the Final Release package model.
-This is a one-way upgrade. Final Release does not read, translate, or preserve Beta 1 JSKIT state.
-## 1. Start from a clean commit
-Commit or stash application work. Record the current database migration status and make a normal database backup before changing packages.
-Do not run a Final Release JSKIT command until the package manifests have been converted.
-## 2. Move package metadata into package.json
-For every JSKIT package, move the exported metadata from `package.descriptor.mjs` into the package's top-level `jskit` object.
-Keep identity in standard npm fields:
-```json
-{
-  "name": "@acme/example-core",
-  "version": "1.2.3",
-  "description": "Example runtime package.",
-  "jskit": {
-    "kind": "runtime",
-    "capabilities": {
-      "provides": [],
-      "requires": []
-    },
-    "runtime": {
-      "server": { "providers": [] },
-      "client": { "providers": [] }
-    },
-    "mutations": {
-      "dependencies": { "runtime": {}, "dev": {} },
-      "files": []
-    }
-  }
-}
-```
-Remove `packageId`, `version`, and `description` from the moved object. Delete every `package.descriptor.mjs` after its data is represented in `package.json`.
-## 3. Use npm dependencies for package relationships
-Move every package relationship from `jskit.dependsOn` to the appropriate standard npm field:
-- `dependencies` for required runtime packages;
-- `optionalDependencies` for optional runtime integrations;
-- `peerDependencies` for host-provided libraries;
-- `devDependencies` for build and generator tooling.
-Pin `@jskit-ai/*` packages to exact versions. Remove `jskit.dependsOn` completely.
-Rename provider-class `static dependsOn` to `static startsAfter`, then audit every entry. Keep only providers whose registration or boot must complete before the declaring provider reaches the same phase. JSKIT completes registration for the entire graph before beginning any boot method, so a lazily consumed service does not justify an ordering edge.
-## 4. Remove Beta 1 project state
-Delete these paths from the application:
-```text
-.jskit/lock.json
-.jskit/verification/
-.jskit/vite.dev.proxy.json
-```
-Remove ignore rules created solely for `.jskit/verification/`.
-Do not translate these paths into replacements. Final Release derives package state from `package.json`, `package-lock.json`, installed package manifests, application config, migration files, and generated CI.
-Delete the app-local Vite proxy loader and any `vite.shared.mjs` file used only for that generated JSON. Pass the application's API target to the standard plugin instead:
-```js
-createJskitClientBootstrapPlugin({
-  proxyTarget: apiProxyTarget
-})
-```
-Installed packages now declare development proxies in `package.json.jskit.vite.proxy`, and the plugin derives the active proxy table directly whenever Vite starts.
-## 5. Replace command usage
-Update scripts, workflow files, runbooks, and automation:
-| Beta 1 | Final Release |
-| --- | --- |
-| `jskit package migrations ...` | `jskit migrations sync` |
-| `jskit app sync-ci` | `jskit ci generate` |
-| CI drift validation through `doctor` alone | `jskit migrations sync --check` and `jskit ci generate --check` |
-| `jskit update package ...` | update npm versions explicitly or run `jskit app update-packages` |
-| `jskit position element ...` | edit application-owned placements directly |
-| `jskit app verify-ui ...` | run the application's Playwright command directly |
-Delete automation for package adoption, source-mutation migration, managed-script adoption, UI receipts, or package replay. Final Release has no corresponding commands.
-## 6. Install the coordinated Final Release
-Update every direct `@jskit-ai/*` dependency in the root application and npm workspaces to the coordinated Final Release versions, then install from scratch with the application's normal npm workflow:
-```bash
-npm install
-npm ls
-```
-Resolve npm peer or capability errors as package-graph errors. Do not add overrides that mix Beta 1 and Final Release packages.
-## 7. Move neutral web operations out of users-web
-Final Release owns browser request, command, list, view, add/edit, permission,
-paging, and generated CRUD UI APIs in `@jskit-ai/http-web`. There are no
-`users-web` compatibility exports.
-Add the coordinated `@jskit-ai/http-web` version to every application or
-workspace that uses these APIs. Keep `@jskit-ai/users-web` only where the code
-actually uses account, profile, or user-specific shell UI.
-Update imports as follows:
-| Beta 1 import or API | Final Release import or API |
-| --- | --- |
-| `@jskit-ai/users-web/client/composables/useCommand` | `@jskit-ai/http-web/client/composables/useCommand` |
-| `@jskit-ai/users-web/client/composables/useEndpointResource` | `@jskit-ai/http-web/client/composables/useEndpointResource` |
-| `@jskit-ai/users-web/client/composables/useList` | `@jskit-ai/http-web/client/composables/useList` |
-| `@jskit-ai/users-web/client/composables/useView` | `@jskit-ai/http-web/client/composables/useView` |
-| `@jskit-ai/users-web/client/composables/useAddEdit` | `@jskit-ai/http-web/client/composables/useAddEdit` |
-| `@jskit-ai/users-web/client/composables/useAccess` | `@jskit-ai/http-web/client/composables/useAccess` |
-| `@jskit-ai/users-web/client/composables/usePagedCollection` | `@jskit-ai/http-web/client/composables/usePagedCollection` |
-| `@jskit-ai/users-web/client/composables/useRealtimeQueryInvalidation` | `@jskit-ai/http-web/client/composables/useRealtimeQueryInvalidation` |
-| `@jskit-ai/users-web/client/composables/runtime/useUiFeedback` | `@jskit-ai/http-web/client/composables/useUiFeedback` |
-| `@jskit-ai/users-web/client/composables/useCrud*` | `@jskit-ai/http-web/client/composables/useCrud*` |
-| `@jskit-ai/users-web/client/components/Crud*` | `@jskit-ai/http-web/client/components/Crud*` |
-| `@jskit-ai/users-web/client/filters` | `@jskit-ai/http-web/client/filters` |
-| `@jskit-ai/users-web/client/bulkActions` | `@jskit-ai/http-web/client/bulkActions` |
-| `@jskit-ai/users-web/client/rowActions` | `@jskit-ai/http-web/client/rowActions` |
-| `@jskit-ai/users-web/client/lib/permissions` | `@jskit-ai/http-web/client/lib/permissions` |
-| `@jskit-ai/users-web/client/support/contractGuards` | `@jskit-ai/http-web/client/support/contractGuards` |
-| `configureUsersWebHttpClient(...)` | `configureHttpWebClient(...)` from `@jskit-ai/http-web/client/lib/httpClient` |
-| `usersWebHttpClient` | `httpWebClient` from `@jskit-ai/http-web/client/lib/httpClient` |
-Search every application workspace, generated route tree, test fixture, and
-app bootstrap. An application that leaves even one removed import will fail at
-module resolution; this is intentional because Final Release contains no
-forwarding bridge.
-`crud-ui-generator` now installs `@jskit-ai/http-web`. `ui-generator` installs
-no users product. Existing generated files are application-owned, so update
-their imports directly or deliberately regenerate them and review the diff.
-After all imports are updated, remove `@jskit-ai/users-web` from any workspace
-that used it only for neutral client APIs. This prevents those applications
-from activating users, authentication, uploads, storage, or database
-capabilities accidentally.
-## 8. Use the separated CRUD package boundaries
-Final Release separates shared resource contracts, browser CRUD, and
-database-backed CRUD:
-- `@jskit-ai/resource-crud-core` owns environment-neutral CRUD resource,
-  field, lookup, namespace, and list-filter contracts;
-- `@jskit-ai/http-web` owns browser request runtimes and generated CRUD UI;
-- `@jskit-ai/crud-core` owns database-backed server CRUD services and
-  repositories.
-Update shared-contract imports as follows:
-| Beta 1 import | Final Release import |
-| --- | --- |
-| `@jskit-ai/kernel/shared/support/crudFieldContract` | `@jskit-ai/resource-crud-core/shared/crudFieldContract` |
-| `@jskit-ai/kernel/shared/support/crudLookup` | `@jskit-ai/resource-crud-core/shared/crudLookup` |
-| `@jskit-ai/kernel/shared/support/crudListFilters` | `@jskit-ai/resource-crud-core/shared/crudListFilters` |
-| `@jskit-ai/crud-core/shared/crudResource` | `@jskit-ai/resource-crud-core/shared/crudResource` |
-| `@jskit-ai/crud-core/shared/crudNamespaceSupport` | `@jskit-ai/resource-crud-core/shared/crudNamespaceSupport` |
-| `checkCrudLookupFormControl` from `@jskit-ai/crud-core/shared/crudFieldSupport` | `checkCrudLookupFormControl` from `@jskit-ai/resource-crud-core/shared/crudFieldContract` |
-| `isCrudRuntimeOutputOnlyFieldKey` from `@jskit-ai/crud-core/shared/crudFieldSupport` | `isCrudRuntimeOutputOnlyFieldKey` from `@jskit-ai/resource-crud-core/shared/crudLookup` |
-There is no `@jskit-ai/crud-core/client` surface. Replace browser imports from
-that surface with the corresponding `@jskit-ai/http-web` API. Add
-`@jskit-ai/resource-crud-core` directly wherever application code imports its
-contracts. Remove `@jskit-ai/crud-core` from client-only and generator-only
-workspaces; retain it only where database-backed server CRUD is used.
-The current CRUD UI templates import `@jskit-ai/http-web`, and the CRUD UI
-generator no longer installs the server CRUD runtime. Existing generated files
-are application-owned, so update their imports directly or deliberately
-regenerate them and review the diff.
-If application tests or package tooling refer to workspaces-web mutation IDs,
-rename the `users-web-*` prefix on workspaces-web-owned mutations to
-`workspaces-web-*`. Package-internal `UsersWorkspace*` component paths are not
-public APIs; remove any direct imports and use the exported workspaces-web
-provider surface.
-If application code imported repository persistence helpers from
-`@jskit-ai/assistant-core/server`, keep those helpers with the repository that
-uses them or use the matching database-runtime primitive. Assistant core no
-longer owns database persistence utilities.
-## 9. Generate deterministic projections
-Synchronize package migration files without applying them:
-```bash
-npx jskit migrations sync
-```
-Review the migration diff. Existing Knex migration files and migration-table history remain intact.
-Runtime-package migration mutations must be deterministic without install
-options. Convert an option-parameterized runtime migration into a generator
-mutation, or materialize it as a fixed app-local package migration before the
-upgrade.
-Generate the JSKIT CI workflow:
-```bash
-npx jskit ci generate
-```
-Move application-specific CI into separate workflow files. The generated JSKIT workflow is replaced in full whenever this command runs.
-## 10. Verify the application
-```bash
-npx jskit lint-packages
-npx jskit doctor
-npx jskit migrations sync --check
-npx jskit ci generate --check
-npm run verify
-```
-Run the application's Playwright suite directly for UI changes.
-Apply database migrations only after reviewing the synchronized files:
-```bash
-npm run db:migrate
-```
-Commit package manifests, `package-lock.json`, synchronized migrations, generated CI, and required application changes together.
-## 11. Update strict resource boundaries
-Applications that pass JavaScript `Date` objects into resource validation must convert them to strings. `date` uses `YYYY-MM-DD`; `time` uses offset-free `HH:MM[:SS[.fraction]]`; and `dateTime` uses RFC 3339 with seconds and a `Z` or numeric offset. Select `epochMilliseconds` or `epochSeconds` explicitly for numeric epochs and preserve `temporalPrecision`.
-Generated generic CRUD repositories serialize supported database temporal output. Custom repositories must return strict temporal strings and write ISO/RFC 3339 strings themselves.
-For a generated view that needs delete confirmation, rerun its `crud-ui-generator crud` command with `--delete-confirmation`. Use `--force` only when replacing generated page output deliberately. For a customized view, preserve the customization and add the public `CrudViewScreen` `actions` slot, `CrudDeleteAction`, and `useCrudDeleteAction()` integration.
-Review the complete application diff and run its full verification suite before applying database migrations.

package/guide/agent/app-setup/working-with-the-jskit-cli.md DELETED Viewed

@@ -1,325 +0,0 @@
-<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/site/guide/app-setup/working-with-the-jskit-cli.md`. Do not edit manually. -->
-# Working with the JSKIT CLI
-JSKIT uses normal npm state. `package.json` declares dependencies, `package-lock.json` fixes the installed graph, and each package publishes its JSKIT metadata in `package.json.jskit`.
-The CLI has four jobs:
-1. install packages and collect missing configuration;
-2. run generators;
-3. synchronize immutable migration files;
-4. generate the JSKIT CI workflow.
-Application source belongs to the application. Git records changes to it. JSKIT does not maintain a second project-state ledger.
-## Package metadata
-A JSKIT package is an ordinary npm package with a `jskit` object in `package.json`:
-```json
-{
-  "name": "@acme/example-core",
-  "version": "1.2.3",
-  "type": "module",
-  "dependencies": {
-    "@jskit-ai/kernel": "0.1.148"
-  },
-  "jskit": {
-    "kind": "runtime",
-    "capabilities": {
-      "provides": ["example.core"],
-      "requires": []
-    },
-    "options": {},
-    "runtime": {
-      "server": {
-        "providers": []
-      },
-      "client": {
-        "providers": []
-      }
-    },
-    "vite": {
-      "proxy": {}
-    },
-    "mutations": {
-      "dependencies": {
-        "runtime": {},
-        "dev": {}
-      },
-      "packageJson": {
-        "scripts": {}
-      },
-      "files": [],
-      "text": [],
-      "source": []
-    }
-  }
-}
-```
-Package identity, version, description, exports, npm dependencies, peer dependencies, and optional dependencies stay in their standard `package.json` fields. Do not repeat npm dependencies in a JSKIT-specific dependency graph.
-`jskit.mutations.dependencies` has a narrower job: it adds direct dependencies
-needed by generated application-owned source or application-level tooling. It
-does not declare relationships between JSKIT packages and does not affect
-package ordering.
-`runtime.server.providers` and `runtime.client.providers` declare runtime entrypoints. A provider class may use `static startsAfter` when its own registration or boot genuinely requires another provider to have completed the same lifecycle phase first. JSKIT registers every provider before booting any provider, so later service consumption does not require an ordering declaration.
-`jskit.vite.proxy` declares development proxy requirements as path-keyed metadata. `createJskitClientBootstrapPlugin({ proxyTarget })` reads those declarations directly from the installed npm graph when Vite starts. Package installation does not generate an intermediate proxy file.
-Use exact versions for `@jskit-ai/*` dependencies. npm's `package-lock.json` remains the reproducible installation record.
-## Install a package
-```bash
-npx jskit add package shell-web
-```
-Short JSKIT ids resolve to their `@jskit-ai/*` package ids. A full package id also works:
-```bash
-npx jskit add package @jskit-ai/shell-web
-```
-The command:
-1. resolves the requested package;
-2. computes the resulting npm package graph and validates capabilities and CI contributions;
-3. collects missing configuration for installed runtime packages in dependency order;
-4. asks for the requested package last;
-5. writes an exact direct dependency and runs `npm install` when needed;
-6. applies the requested package's initial app mutations;
-7. synchronizes package migrations;
-8. regenerates the JSKIT CI workflow.
-Validation happens before application files or migrations are changed. A CI contribution conflict or incomplete capability graph stops the install.
-Use `--dry-run` to inspect a supported install without writing, and `--json` when another tool needs structured output.
-```bash
-npx jskit add package database-runtime-mysql --dry-run
-npx jskit add package database-runtime-mysql --json
-```
-## Configuration prompts
-`jskit add` scans installed runtime packages for declared options. Packages with unresolved required configuration are prompted dependency-first. The requested package is prompted last.
-This means a partially configured app can recover during the next normal package addition. Configuration discovery comes from:
-- the installed npm dependency graph;
-- each installed package's `package.json.jskit.options`;
-- current application config and environment values.
-Sensitive values can be written through the package's declared environment mutation. They are not stored in JSKIT project state.
-For automation, pass package options inline:
-```bash
-npx jskit add package database-runtime-mysql \
-  --db-host database \
-  --db-port 3306 \
-  --db-name app \
-  --db-user app \
-  --db-password "$DB_PASSWORD"
-```
-## Third-party packages
-Third-party authors publish an ordinary npm package containing `package.json.jskit`. No JSKIT registration step is required.
-Install it at an exact version, then target it by its npm id:
-```bash
-npm install --save-exact @acme/example-core@1.2.3
-npx jskit add package @acme/example-core
-```
-The CLI reads the installed package manifest and its package files directly. Package templates referenced by `jskit.mutations.files` must be included in the npm package's `files` allowlist.
-If an ecosystem package should support a short id or appear in the built-in JSKIT list, it can additionally be included in the JSKIT catalog. That is discovery metadata for the built-in distribution, not a requirement for package execution.
-## Bundles
-A bundle selects two or more runtime packages for one installation:
-```bash
-npx jskit add bundle auth-local
-```
-Bundle definitions contain package ids only. npm dependencies still define package dependency relationships. Configuration follows the same dependency-first order, with the explicitly requested packages last.
-## Generators
-List and inspect generators:
-```bash
-npx jskit list generators
-npx jskit show package crud-server-generator
-```
-Run a generator:
-```bash
-npx jskit generate crud-server-generator scaffold contacts \
-  --surface app \
-  --grant-policy workspace_member
-```
-Generator packages are development dependencies. Their transitive dependencies are tooling dependencies and are not activated as application runtime packages.
-Generated source belongs to the application immediately. Edit it normally and review it in Git.
-## App-local packages
-Create a local package:
-```bash
-npx jskit create package contacts
-```
-This creates `packages/contacts/package.json` with a `jskit` object and adds an exact `file:` dependency to the application.
-The package can use standard npm dependencies and exports. Put server and client providers in `package.json.jskit.runtime`.
-## Migrations
-Packages declare migration templates with `install-migration` file mutations. Synchronize them into the application with:
-```bash
-npx jskit migrations sync
-```
-Check without writing:
-```bash
-npx jskit migrations sync --check
-```
-Migration ids are immutable. The same package and migration id must always produce the same content. A conflict fails instead of overwriting migration history.
-Runtime-package migrations are deterministic projections and cannot reference
-install options. Use a generator when a migration must be parameterized for a
-specific generated feature.
-Synchronization changes files only. Apply database migrations separately:
-```bash
-npm run db:migrate
-```
-Create an app-owned package migration with:
-```bash
-npx jskit create migration \
-  --package @local/contacts \
-  --id add-contact-status
-```
-Implement the package template, run `npx jskit migrations sync`, review the generated migration, and then run the database migration command.
-## CI generation
-Generate the JSKIT verification workflow:
-```bash
-npx jskit ci generate
-```
-Check it without writing:
-```bash
-npx jskit ci generate --check
-```
-This command fully generates one file:
-```text
-.github/workflows/jskit-verify.yml
-```
-Do not edit that file. Put application-specific CI jobs in separate, application-owned workflow files.
-Packages contribute CI environment values, services, and pre-verification steps through `package.json.jskit.ci`. Conflicting contributions fail with the contributing package ids.
-## Update JSKIT packages
-```bash
-npm run jskit:update
-```
-The script runs `jskit app update-packages`. It installs current `@jskit-ai/*` packages at exact versions, aligns JSKIT references in npm workspaces, refreshes npm resolution, synchronizes migrations, and regenerates CI.
-Preview registry changes with:
-```bash
-npx jskit app update-packages --dry-run
-```
-Package updates do not regenerate application source. Review upstream release notes and make application changes explicitly.
-## Remove a package
-```bash
-npx jskit remove package @jskit-ai/example-core
-```
-The command removes the application's direct npm dependency, runs npm install, and regenerates CI. App source and database migration history are retained. Delete application-owned source only when you have reviewed its remaining consumers.
-An npm-transitive package cannot be removed directly. Remove or replace the direct package that depends on it.
-## Inspect and validate
-Useful read-only commands:
-```bash
-npx jskit list packages
-npx jskit list generators
-npx jskit show package shell-web
-npx jskit list-placements
-npx jskit list-component-tokens
-```
-Validate package metadata:
-```bash
-npx jskit lint-packages
-```
-Validate an application:
-```bash
-npx jskit doctor
-```
-`doctor` checks the installed package graph, capability closure, provider declarations, migrations, generated CI, surfaces, placements, CRUD ownership, and other architecture contracts.
-The normal CI sequence is:
-```bash
-npm ci
-npx jskit migrations sync --check
-npx jskit ci generate --check
-npm run verify
-```
-## Command summary
-```text
-jskit add package <id>
-jskit add bundle <id>
-jskit generate <generator-id> [subcommand]
-jskit create package <name>
-jskit create migration --package <id> --id <migration-id>
-jskit migrations sync [--check]
-jskit ci generate [--check]
-jskit remove package <id>
-jskit app update-packages [--dry-run]
-jskit doctor
-jskit lint-packages
-jskit list <packages|generators|bundles>
-jskit show <package|bundle> <id>
-```