@jskit-ai/agent-docs 0.1.63 → 0.1.65

package/guide/agent/app-setup/authentication.md

@@ -18,7 +18,7 @@ If you are already continuing from the previous chapter, you are already in the
 
 **Default: Start With Local Auth**
 
-The default auth path does not require a Supabase project or a database. It uses `auth-local`, which stores local credentials and sessions in `.jskit/auth/` by default.
+The default auth path does not require a Supabase project or a database. It uses the local provider package, `auth-provider-local-core`, together with `auth-web`. The local provider stores credentials and sessions in `.jskit/auth/` by default.
 
 That is the recommended first step for most apps. After the app's core flow is working, switch to Supabase or add richer auth methods only if the product needs them.
 
@@ -27,11 +27,12 @@ That is the recommended first step for most apps. After the app's core flow is w
 From inside `exampleapp`, run:
 
 ```bash
-npx jskit add bundle auth-local
+npx jskit add package auth-provider-local-core
+npx jskit add package auth-web
 npm install
 ```
 
-`auth-local` installs the provider-neutral auth core, the auth web layer, and the local provider. It gives the app working register, login, logout, session, and password recovery flows without requiring an external auth service.
+These package installs add the provider-neutral auth core, the auth web layer, and the local provider. They give the app working register, login, logout, session, and password recovery flows without requiring an external auth service.
 
 The final `npm install` matters for the same reason it did in the shell chapter: `jskit add` rewrites the scaffold and updates `package.json`, but `npm install` is what actually downloads the newly referenced runtime packages.
 
@@ -468,7 +469,7 @@ At this point the guide has shown three distinct layers of client state:
 
 That progression is intentional. Packages keep their operational runtimes internally, but the app-facing shared state they surface to Vue code is store-based.
 
-## What `auth-local` adds to the app
+## What the local auth install adds to the app
 
 The interesting part of this chapter is that authentication appears in several different layers at once: environment config, public routing config, shell placements, and app-owned view wrappers.
 
@@ -527,7 +528,7 @@ config.surfaceDefinitions.auth = {
 
 That `requiresAuth: false` line is important. The auth surface must stay public, otherwise users would need to be logged in before they could reach the login page.
 
-The local provider does not need an app database profile mode or OAuth config. The stock login UI asks `/api/session` for the active provider capabilities and renders only what the selected provider actually supports. With `auth-local`, that means email/password login, registration, sign-out, session refresh, and password recovery when recovery is configured.
+The local provider does not need an app database profile mode or OAuth config. The stock login UI asks `/api/session` for the active provider capabilities and renders only what the selected provider actually supports. With the local provider, that means email/password login, registration, sign-out, session refresh, and password recovery when recovery is configured.
 
 Later, if you switch to Supabase, the Supabase provider can append the app-owned OAuth visibility config and profile mode settings it needs.
 

package/guide/agent/app-setup/initial-scaffolding.md

@@ -53,7 +53,8 @@ npx @jskit-ai/create-app exampleapp --tenancy-mode none
 cd exampleapp
 npm install
 
-npx jskit add bundle auth-local
+npx jskit add package auth-provider-local-core
+npx jskit add package auth-web
 
 npx jskit add package database-runtime-mysql \
   --db-host "$DB_HOST" \

package/guide/agent/app-setup/quickstart.md

@@ -48,7 +48,8 @@ npx @jskit-ai/create-app testapp --tenancy-mode personal
 cd testapp
 npm install
 
-npx jskit add bundle auth-local
+npx jskit add package auth-provider-local-core
+npx jskit add package auth-web
 
 npx jskit add package database-runtime-mysql \
   --db-host "$DB_HOST" \
@@ -82,7 +83,7 @@ npm install
 npm run db:migrate
 ```
 
-Keep authentication deliberately basic while the product is still taking shape. Start with `auth-local`, build the app's core workflows, then add Supabase, OAuth, OTP, provider linking, app-user projection, or workspace/account complexity when the product actually needs those features.
+Keep authentication deliberately basic while the product is still taking shape. Start with the local provider and `auth-web`, build the app's core workflows, then add Supabase, OAuth, OTP, provider linking, app-user projection, or workspace/account complexity when the product actually needs those features.
 
 At this point you have:
 

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

@@ -9,7 +9,7 @@ This chapter steps back and treats the CLI as a subject in its own right.
 That matters because `jskit` is not just "the thing that installs packages". It is the tool that helps you:
 
 - discover what JSKIT can do
-- inspect bundles, packages, and generators before using them
+- inspect packages, generators, and any catalog shortcuts before using them
 - apply and re-apply JSKIT-managed mutations to your app
 - keep managed files and lock state healthy
 - create your own app-local runtime packages
@@ -28,7 +28,7 @@ The easiest way to understand `jskit` is to separate it from the other tools in
 
 That separation is crucial.
 
-When you run a command such as `npx jskit add bundle auth-local`, JSKIT updates app-owned files and records what it changed. It does **not** replace npm, Vite, or Knex.
+When you run a command such as `npx jskit add package auth-provider-local-core`, JSKIT updates app-owned files and records what it changed. It does **not** replace npm, Vite, or Knex.
 
 The most important record of that managed state lives here:
 
@@ -98,6 +98,22 @@ npx jskit app adopt-managed-scripts
 
 That command rewrites known old scaffold values to the thin wrapper form above.
 
+For older apps that were installed before JSKIT source mutations replaced raw source appends, run the source migration after updating JSKIT packages:
+
+```bash
+npx jskit app update-packages
+npx jskit app migrate-source-mutations --dry-run
+npx jskit app migrate-source-mutations
+npm run verify
+```
+
+That migration is the one upgrade script for JSKIT-owned legacy source mutation shapes. It currently normalizes:
+
+- `packages/main/src/client/providers/MainClientProvider.js`: moves legacy appended `registerMainClientComponent(...)` calls before `class MainClientProvider`, which is the layout produced by current descriptor `mutations.source` installs.
+- `src/pages/**` CRUD form field modules: folds legacy `UI_CREATE_FORM_FIELDS.push(...)` and `UI_EDIT_FORM_FIELDS.push(...)` calls into the corresponding array literals.
+
+The command is idempotent, so rerunning it should report that the source files are already current.
+
 ## Discover first, change second
 
 One of the best habits in JSKIT is to inspect the catalog before mutating the app.
@@ -151,9 +167,7 @@ That distinction matters.
 
 #### Bundles
 
-A bundle is a curated install shortcut for several runtime packages that are meant to go together.
-
-In the current catalog, `auth-local` is the obvious example. It is a single bundle id, but it expands to several real runtime packages.
+A bundle is a curated install shortcut for several runtime packages that are meant to go together. Bundles can still appear in the catalog for compatibility and quick inspection, but the guide uses explicit package installs so the real runtime packages stay visible.
 
 #### Runtime packages
 
@@ -188,7 +202,7 @@ npx jskit list generators
 
 Those two commands are especially useful later in the guide, once you already know roughly what kind of thing you are looking for.
 
-If you want bundle members printed inline too, `npx jskit list --full` expands the bundle view. That is useful when you want a quick catalog scan without dropping straight into `show`.
+If you want bundle members printed inline too, `npx jskit list --full` expands the bundle view. That is useful when you are auditing a shortcut, but package ids are still the normal install vocabulary in this guide.
 
 One more detail is worth noticing. In repos that contain local package descriptors, `list packages` can also show app-local or repo-local packages in addition to the published catalog. So `list` is not only a remote catalog browser. It is also a view of what this app can currently see.
 
@@ -208,7 +222,7 @@ And the more useful inspection form is:
 npx jskit show <id> --details
 ```
 
-This command is unusually valuable in JSKIT because packages and bundles do more than "add a dependency". They can:
+This command is unusually valuable in JSKIT because packages and catalog shortcuts do more than "add a dependency". They can:
 
 - provide or require capabilities
 - register runtime providers
@@ -230,39 +244,42 @@ The plain form is useful when you only want to identify something quickly. `--de
 
 There are two especially common cases:
 
-- you found a bundle or package in `jskit list` and want to know what it really does before you install it
+- you found a package or shortcut in `jskit list` and want to know what it really does before you install it
 - you already know a package changed the shell, the runtime graph, or the app tree, and you want to see *how*
 
 That second case matters just as much as the first one. Later in the guide, chapters explain package behavior one feature at a time. `show --details` is the generic command that lets you inspect those same package contracts directly.
 
-### A first example: what does `auth-local` actually install?
+### A first example: inspect the local auth provider
 
 Run:
 
 ```bash
-npx jskit show auth-local --details
+npx jskit show auth-provider-local-core --details
 ```
 
 This output is short, but it already teaches something important:
 
-- `auth-local` is a **bundle**
-- it is not a runtime package by itself
+- `auth-provider-local-core` is a **runtime package**
+- it selects the local auth provider
+- it depends on the provider-neutral `auth-core`
 
-It expands to three real runtime packages:
+The default local auth install uses two direct package commands:
 
-- `@jskit-ai/auth-core`
-- `@jskit-ai/auth-web`
-- `@jskit-ai/auth-provider-local-core`
+```bash
+npx jskit add package auth-provider-local-core
+npx jskit add package auth-web
+```
 
-That is exactly the kind of thing you want to know before you mutate the app. For a bundle, this is often the main question:
+That is exactly the kind of thing you want to know before you mutate the app:
 
-- *what real packages am I about to get?*
+- which package selects the active provider?
+- which package adds the web auth routes and login UI?
 
-`auth-local` is a good example because the bundle name is short and convenient, but the detailed view makes the underlying install explicit. It also helps you keep the mental model straight:
+It also helps you keep the mental model straight:
 
-- bundles are install shortcuts
 - runtime packages are the things that actually provide capabilities
-- provider bundles also select one concrete `auth.provider`
+- `auth-provider-local-core` provides the selected `auth.provider`
+- `auth-web` consumes the selected provider and adds the web surface
 
 ### A richer example: what does `workspaces-web` contribute?
 
@@ -381,7 +398,7 @@ This is especially useful when you are asking questions like:
 
 #### "What app-owned files will it touch?"
 
-The `File writes`, `Text mutations`, and `Script mutations` sections answer one of the most practical questions in JSKIT:
+The `File writes`, `Text mutations`, `Source mutations`, and `Script mutations` sections answer one of the most practical questions in JSKIT:
 
 - *what will this package actually do to my app tree?*
 
@@ -395,7 +412,11 @@ For `@jskit-ai/workspaces-web`, the detailed view shows app-owned files such as:
 It also shows text mutations such as:
 
 - appending placement entries to `src/placement.js`
-- registering tokens in `packages/main/src/client/providers/MainClientProvider.js`
+
+And it shows source mutations such as:
+
+- adding imports to `packages/main/src/client/providers/MainClientProvider.js`
+- registering component tokens in `packages/main/src/client/providers/MainClientProvider.js`
 
 That matters because JSKIT packages are not only libraries. Many of them also write scaffold files into the app and extend app-owned provider files.
 
@@ -424,7 +445,7 @@ Not every package shows every section, and that is normal. A good reading order
    - what role does it play in the runtime graph?
 5. `Placement contributions` / `Placement outlets`
    - what UI surfaces does it add?
-6. `File writes` and `Text mutations`
+6. `File writes`, `Text mutations`, and `Source mutations`
    - what app-owned files will change?
 7. `Runtime providers` and `Container tokens`
    - what does it register internally?
@@ -475,14 +496,13 @@ This is not required, but it is genuinely useful once you start using commands s
 
 ## Installing runtime capability: `add`
 
-The install command comes in two main forms:
+The install command you will use most often is:
 
 ```bash
 npx jskit add package users-web
-npx jskit add bundle auth-local
 ```
 
-Those two examples look similar, but they do different things.
+That command installs one runtime package and its dependency chain.
 
 ### `add package`
 
@@ -518,15 +538,9 @@ npm run devlinks
 
 ### `add bundle`
 
-Use this when the catalog already offers a sensible grouped install:
-
-```bash
-npx jskit add bundle auth-local
-```
-
-Bundles are a convenience layer. They save you from having to remember and install several related runtime packages one by one.
+Bundles are a convenience layer for catalog shortcuts. Prefer package commands in setup docs and normal app work, especially for auth, because provider ownership is clearer when the selected provider package is installed explicitly.
 
-This is why `show auth-local --details` is useful first: it lets you see what the bundle will actually install. Lower-level bundles such as `auth-base` can still be useful when you are composing your own provider stack, but they require an installed selected provider such as `auth-provider-local-core` or `auth-provider-supabase-core`.
+If you do use a bundle shortcut, inspect it first with `npx jskit show <bundle-id> --details` so you can see the real packages and capabilities it will install.
 
 ### Generator packages are different
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.63",
+  "version": "0.1.65",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/reference/autogen/packages/auth-core.md

@@ -312,6 +312,7 @@ Exports
 - `logoutOutputValidator`
 - `oauthProviderCatalogEntryOutputValidator`
 - `authDeniedOutputSchema`
+- `authCapabilitiesOutputSchema`
 - `sessionOutputValidator`
 - `sessionUnavailableOutputValidator`
 - `createCommandMessages({ fields = {}, defaultMessage = "Invalid value." } = {})`

package/reference/autogen/packages/auth-provider-local-core.md

@@ -47,18 +47,22 @@ Local functions
 Exports
 - `createLocalAuthService`
 - `createLocalFileBackend`
+- `hashPassword`
+- `normalizePasswordStrategy`
+- `verifyPassword`
 
 ### `src/server/lib/passwords.js`
 Exports
 - `hashPassword(password)`
 - `verifyPassword(password, record)`
+- `normalizePasswordStrategy(strategy = null)`
 Local functions
 - `base64url(buffer)`
 - `fromBase64url(value)`
 
 ### `src/server/lib/service.js`
 Exports
-- `createLocalAuthService({ backend, config, profileProjector = null })`
+- `createLocalAuthService({ backend, config, profileProjector = null, passwordStrategy = null })`
 Local functions
 - `nowSeconds()`
 - `isoFromNow(seconds)`

package/reference/autogen/tooling/jskit-cli.md

@@ -138,6 +138,7 @@ Exports
 Local functions
 - `normalizePackageKind(rawValue, descriptorPath)`
 - `validateFileMutationShape(descriptor, descriptorPath)`
+- `validateSourceMutationShape(descriptor, descriptorPath)`
 - `validateLifecycleHookSpec(spec = {}, descriptorPath, label = "lifecycle hook")`
 - `validateLifecycleShape(descriptor, descriptorPath)`
 
@@ -187,6 +188,9 @@ Exports
 - `applyTextMutations`
 - `partitionPreFileConfigTextMutations`
 - `resolvePositioningMutations`
+- `applySourceMutations`
+- `partitionPreFileConfigSourceMutations`
+- `resolvePositioningSourceMutations`
 
 ### `src/server/cliRuntime/mutations/fileMutations.js`
 Exports
@@ -201,6 +205,32 @@ Exports
 Exports
 - `normalizeMutationRelativeFilePath(value = "")`
 
+### `src/server/cliRuntime/mutations/sourceMutations.js`
+Exports
+- `applySourceMutations(packageEntry, appRoot, sourceMutations, options, managedSource, touchedFiles, { dryRun = false } = {})`
+- `partitionPreFileConfigSourceMutations(sourceMutations = [])`
+- `resolvePositioningSourceMutations(descriptorMutations = {})`
+Local functions
+- `createSourceFile(relativeFile, sourceText)`
+- `normalizeSourceText(value = "")`
+- `insertText(sourceText, index, text)`
+- `appendBlock(sourceText, block)`
+- `renderImportMutation(mutation, options, packageId, mutationId)`
+- `sourceAlreadyHasImport(sourceFile, rendered)`
+- `ensureImport(sourceText, relativeFile, mutation, options, packageId, mutationId)`
+- `normalizeSourceArg(value = "")`
+- `callExpressionMatches(callExpression, callee, expectedArgs, uniqueArgIndex)`
+- `renderCallMutation(mutation, options, packageId, mutationId)`
+- `ensureCall(sourceText, relativeFile, mutation, options, packageId, mutationId)`
+- `sourceHasAssignmentToTarget(sourceFile, target)`
+- `renderAssignmentStatement(target, value)`
+- `ensureAssignment(sourceText, relativeFile, mutation, options, packageId, mutationId)`
+- `ensureExportConst(sourceText, relativeFile, mutation, options, packageId, mutationId)`
+- `applySourceMutationToContent(sourceText, relativeFile, mutation, options, packageId)`
+- `createManagedSourceRecord(relativeFile, mutation)`
+- `isPositioningSourceMutation(value = {})`
+- `isPreFileConfigSourceMutation(value = {})`
+
 ### `src/server/cliRuntime/mutations/surfaceTargets.js`
 Exports
 - `resolveSurfaceTargetPathsForMutation({ appRoot, packageId, mutation, configContext } = {})`
@@ -401,6 +431,27 @@ Local functions
 - `replaceWithSymlink(targetPath = "", sourceDir = "", { packageName = "" } = {})`
 - `maybeLinkCompanionPackages({ appRoot = "", repoRoot = "", stdout, createCliError })`
 
+### `src/server/commandHandlers/appCommands/migrateSourceMutations.js`
+Exports
+- `buildCrudFormFieldPushMigration(sourceText = "")`
+- `buildMainClientProviderMigration(sourceText = "")`
+- `runAppMigrateSourceMutationsCommand(_ctx = {}, { appRoot = "", options = {}, stdout })`
+Local functions
+- `createSourceFile(sourceText = "")`
+- `readStringLiteralValue(node)`
+- `readRegisterMainClientComponentToken(statement)`
+- `escapeRegExp(value = "")`
+- `findMatchingDelimiter(sourceText = "", openIndex = -1, openChar = "(", closeChar = ")")`
+- `readLineIndent(sourceText = "", index = 0)`
+- `readFormFieldKey(sourceText = "")`
+- `readFormFieldKeys(sourceText = "")`
+- `formatArrayEntry(entrySource = "", indent = " ")`
+- `findFormFieldArrayDeclaration(sourceText = "", arrayName = "")`
+- `findFormFieldPushCalls(sourceText = "", arrayName = "")`
+- `buildArrayContentWithAddedEntries(existingContent = "", entries = [], indent = "")`
+- `applyTextReplacements(sourceText = "", replacements = [])`
+- `collectCrudFormFieldCandidateFiles(appRoot = "")`
+
 ### `src/server/commandHandlers/appCommands/preparePreviewUser.js`
 Exports
 - `runAppPreparePreviewUserCommand(_ctx = {}, { appRoot = "", options = {}, stdout = process.stdout })`