@jskit-ai/agent-docs 0.1.64 → 0.1.65

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

@@ -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.
@@ -382,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?*
 
@@ -396,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.
 
@@ -425,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?

package/package.json

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

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 })`