@jskit-ai/agent-docs 0.1.78 → 0.1.79

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

@@ -212,7 +212,9 @@ That matters because JSKIT maintenance policy changes over time. If the scaffold
 
 `jskit app verify` is worth noticing specifically. Linting, tests, and builds check your source code and runtime behavior. The JSKIT part of that flow runs `doctor`, which checks JSKIT-managed app state: installed package visibility, lock-file-backed managed files, and other JSKIT-specific health rules. It is there because a JSKIT app is not only code. It is also a descriptor-driven managed project.
 
-The starter scaffold also writes `.github/workflows/verify.yml`. That workflow stays intentionally small: it runs `npm run verify` for the normal GitHub Actions gate and leaves browser/auth/database-heavy review flows to app-specific local or CI setups. The `--against <base-ref>` review mode exists in the CLI for local pre-merge checks and for advanced CI pipelines, but it is not assumed by the starter scaffold.
+The starter scaffold also writes `.github/workflows/jskit-verify.yml`. JSKIT generates and owns that workflow as a projection of installed package `ci` contracts. The baseline runs checkout, Node setup, `npm ci`, and `npm run verify`. Packages can add job environment values, service containers, and explicit `before-verify` steps without taking ownership of the whole YAML file. For example, the database runtime adds migrations before verification and its MySQL driver adds a MariaDB service with synthetic CI-only credentials and `DB_CLIENT=mysql2`.
+
+The workflow content hash is recorded in `.jskit/lock.json`. Package lifecycle commands refresh it when installed requirements change and refuse to overwrite a workflow that differs from its recorded version. Application-specific CI belongs in another workflow. Use `npx jskit app sync-ci` to refresh an unmodified managed file, or `npx jskit app sync-ci --force` when you explicitly intend to replace an edited file that is already recorded as JSKIT-owned. The `--against <base-ref>` review mode still exists for local pre-merge checks and advanced CI pipelines, but the starter workflow does not assume it.
 
 The surface-specific script names are also worth noticing early, even in this tiny app. `dev:home`, `server:home`, and `build:home` are the first concrete places where surface selection shows up in the scaffold. They work by setting `VITE_SURFACE=home` on the client side and `SERVER_SURFACE=home` on the server side. In this first chapter, where `home` is the only surface, those variants behave almost the same as the default commands. Later, once more surfaces exist, those scripts become the simplest way to run or build just one surface at a time.
 
@@ -761,7 +763,7 @@ That keeps the ownership boundary clear: `packages/main` stays composition-only,
 
 The `.jskit/lock.json` file is also important. Treat it like JSKIT's own lock and state file. It records which runtime packages JSKIT believes are installed and which managed changes they introduced. When you use `jskit add`, `jskit update`, or generators that depend on installed package state, this file is part of the source of truth. It belongs in version control, and you should not hand-edit it.
 
-This file is narrower than `package.json`. `package.json` lists every npm dependency the app needs, including plain libraries such as Vue, Fastify, and Vuetify. `.jskit/lock.json` only tracks JSKIT package-install state: which JSKIT runtime packages were installed into the app and which files, text mutations, and dependency entries JSKIT is managing on their behalf.
+This file is narrower than `package.json`. `package.json` lists every npm dependency the app needs, including plain libraries such as Vue, Fastify, and Vuetify. `.jskit/lock.json` tracks JSKIT package-install state: which JSKIT runtime packages were installed, which files, text mutations, and dependency entries JSKIT manages on their behalf, and the owned hash of app-level projections such as the composed CI workflow.
 
 On a brand-new default app, the lock file is telling you that the app-local package and the standard shell package are installed from the start:
 
@@ -799,6 +801,12 @@ On a brand-new default app, the lock file is telling you that the app-local pack
         "text": { "...": "..." }
       }
     }
+  },
+  "managed": {
+    "ciWorkflow": {
+      "path": ".github/workflows/jskit-verify.yml",
+      "hash": "<generated-sha256>"
+    }
   }
 }
 ```

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

@@ -81,7 +81,17 @@ This gives you a clean ownership split:
 
 That split is worth keeping in mind through the rest of the guide. When you see `npm run verify`, read it as "run the app's JSKIT baseline verification policy, then any app-specific extra verification hook".
 
-The starter scaffold also includes `.github/workflows/verify.yml`. That workflow is intentionally conservative: it runs `npm run verify` and does not assume that every app can stand up full browser, auth, seed-data, and database verification inside hosted CI.
+The starter scaffold also includes `.github/workflows/jskit-verify.yml`. This is a JSKIT-managed projection, not a static template. Installed package descriptors can contribute CI environment values, services, and preparation steps through their top-level `ci` contract. JSKIT composes those contributions and renders one verification workflow in this order: checkout, Node setup, `npm ci`, package-contributed `before-verify` steps, and `npm run verify`.
+
+For example, `database-runtime` contributes the `database-migrations` step, while `database-runtime-mysql` contributes the MariaDB service and matching synthetic CI-only `DB_*` values. `DB_CLIENT` remains the canonical `mysql2` value. Local `.env` values are never copied into the workflow.
+
+The workflow path and generated content hash live under `managed.ciWorkflow` in `.jskit/lock.json`. Package add, remove, update, and app-wide package updates refresh this projection. If the workflow no longer matches its recorded hash, JSKIT refuses to overwrite it during those operations. Move application-specific jobs to another workflow, then explicitly regenerate the managed projection with:
+
+```bash
+npx jskit app sync-ci
+```
+
+The command refuses to replace an edited workflow unless you explicitly run `npx jskit app sync-ci --force`. Even with `--force`, it replaces the file only when `.jskit/lock.json` already records JSKIT ownership. It does not claim an unrecorded `.github/workflows/jskit-verify.yml` or remove a customized legacy `.github/workflows/verify.yml`.
 
 If your app uses a non-default npm registry for JSKIT packages, pass it to the maintained CLI command rather than hard-coding it in the scaffold. For example:
 
@@ -563,6 +573,7 @@ That state lives in `.jskit/lock.json`, which is why lifecycle commands all star
 - which package is installed
 - which install options were used
 - which files, text mutations, dependency entries, and migrations it owns
+- the path and content hash of the composed JSKIT CI workflow
 
 The easiest way to think about the lifecycle is:
 
@@ -571,6 +582,8 @@ The easiest way to think about the lifecycle is:
 3. `jskit position element ...` reapplies just the positioning layer
 4. `jskit remove package ...` removes the managed state
 
+Package add, update, and remove also recompose `.github/workflows/jskit-verify.yml` from the complete installed package set. No individual package owns that file through `mutations.files`; it is one app-level projection with contributions from many descriptors.
+
 That is a better mental model than thinking of these as three unrelated commands.
 
 ### `update` re-applies one installed package
@@ -692,6 +705,7 @@ In the current CLI, that includes checks such as:
 - installed package entries in `.jskit/lock.json`
 - whether managed files recorded in the lock still exist
 - whether installed packages are still visible in the package registry
+- whether package CI contributions compose without conflicts and match the managed workflow service, environment, preparation steps, and ordering
 - explicit `transport` passed to high-level CRUD hooks such as `useCrudList()`, `useCrudView()`, and `useCrudAddEdit()`, where the shared CRUD resource should derive the JSON:API transport automatically
 - certain JSKIT-specific app checks, such as invalid raw `mdi-*` icon literals in Vue templates when the app uses Vuetify's `mdi-svg` iconset
 - UI verification receipts for current dirty UI files in git, via `.jskit/verification/ui.json`
@@ -725,7 +739,7 @@ That is a different job from:
 
 Those commands can all pass while JSKIT-managed state is still inconsistent. `doctor` is the command that checks that JSKIT's own view of the app still makes sense.
 
-That is exactly why the starter scaffold routes `npm run verify` through `jskit app verify`.
+That is exactly why the starter scaffold routes `npm run verify` through `jskit app verify`. CI structure is checked before lint, test, client-test, and build scripts, so a stale database service or missing migration step fails directly instead of surfacing later as an opaque provider boot failure.
 
 It belongs there because JSKIT apps are not only source trees. They also have:
 

package/package.json

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

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

@@ -73,6 +73,75 @@ Local functions
 - `collectPlannedCapabilityIssues(plannedPackageIds, packageRegistry)`
 - `collectExclusiveCapabilityIssues(plannedPackageIds, packageRegistry)`
 
+### `src/server/cliRuntime/ci/composer.js`
+Exports
+- `CiCompositionError`
+- `composeCiContributions(packageEntries = [])`
+Local functions
+- `canonicalValue(value)`
+- `valuesMatch(left, right)`
+- `formatConflictValue(value)`
+- `normalizePackageEntries(packageEntries = [])`
+- `appendSource(sourceMap, key, packageId)`
+- `conflict({ kind, id, existing, incoming, existingPackages, incomingPackage })`
+- `sourcesToObject(sourceMap)`
+
+### `src/server/cliRuntime/ci/contract.js`
+Exports
+- `CI_STEP_PHASE_BEFORE_VERIFY`
+- `CI_STEP_PHASES`
+- `normalizeCiContribution(value, context = {})`
+Local functions
+- `isPlainObject(value)`
+- `invalidCiContract(message, { descriptorPath = "", packageId = "" } = {})`
+- `requirePlainObject(value, label, context)`
+- `rejectUnknownKeys(value, allowedKeys, label, context)`
+- `normalizeCiScalar(value, label, context)`
+- `normalizeCiEnvironment(value, label, context)`
+- `normalizeCiPorts(value, label, context)`
+- `normalizeCiHealthCheck(value, label, context)`
+- `normalizeCiService(value, index, context)`
+- `normalizeCiStep(value, index, context)`
+
+### `src/server/cliRuntime/ci/githubWorkflow.js`
+Exports
+- `GENERATED_WORKFLOW_HEADER`
+- `JSKIT_CI_WORKFLOW_RELATIVE_PATH`
+- `LEGACY_CI_WORKFLOW_RELATIVE_PATH`
+- `LEGACY_VERIFY_WORKFLOW_HASH`
+- `buildGithubWorkflowDocument(model = {})`
+- `parseGithubWorkflow(source = "")`
+- `renderGithubServiceOptions(service = {})`
+- `renderGithubWorkflow(model = {})`
+Local functions
+- `quoteDockerOptionValue(value)`
+- `renderGithubService(service = {})`
+
+### `src/server/cliRuntime/ci/managedWorkflow.js`
+Exports
+- `assertAppManagedCiWorkflowUnmodified({ appRoot })`
+- `assertManagedCiWorkflowUnmodified({ appRoot, lock, allowManagedOverwrite = false })`
+- `composeInstalledPackageCi({ lock, packageRegistry, installedPackageIds = null })`
+- `synchronizeAppCiWorkflow({ appRoot, allowManagedOverwrite = false, dryRun = false })`
+- `synchronizeManagedCiWorkflow({ appRoot, lock, packageRegistry, installedPackageIds = null, touchedFiles = null, dryRun = false, allowManagedOverwrite = false })`
+- `validateAppCiWorkflow({ appRoot })`
+- `validateManagedCiWorkflow({ appRoot, lock, packageRegistry })`
+Local functions
+- `contentHash(content = "")`
+- `collectInstalledPackageEntries({ lock, packageRegistry, installedPackageIds = null })`
+- `managedCiRecord(lock = {})`
+- `setManagedCiRecord(lock, record)`
+- `recoveryError(message, { force = false } = {})`
+- `inspectWorkflowOwnership({ appRoot, lock })`
+- `createValidationIssue(code, message, details = {})`
+- `formatRequirementPackages(packageIds = [])`
+- `describeCiRequirements(model = {})`
+- `normalizeActualEnvironment(value)`
+- `collectEnvironmentIssues({ expected, actual, sources, issues })`
+- `collectServiceIssues({ model, verifyJob, issues })`
+- `collectStepIssues({ model, verifyJob, issues })`
+- `loadAppCiContext(appRoot)`
+
 ### `src/server/cliRuntime/completion.js`
 Exports
 - `discoverPlacementTargets(appRoot)`
@@ -495,6 +564,10 @@ Exports
 Local functions
 - `ensureCommandSucceeded(result, label, { createCliError, cwd = "", stdout, stderr, quiet = false } = {})`
 
+### `src/server/commandHandlers/appCommands/syncCi.js`
+Exports
+- `runAppSyncCiCommand(ctx = {}, { appRoot = "", options = {}, stdout })`
+
 ### `src/server/commandHandlers/appCommands/updatePackages.js`
 Exports
 - `runAppUpdatePackagesCommand(ctx = {}, { appRoot = "", options = {}, stdout, stderr })`
@@ -884,6 +957,11 @@ Exports
 ### `src/server/index.js`
 Exports
 - `runCli`
+- `synchronizeAppCiWorkflow`
+- `validateAppCiWorkflow`
+- `composeCiContributions`
+- `JSKIT_CI_WORKFLOW_RELATIVE_PATH`
+- `renderGithubWorkflow`
 
 ### `src/server/shared/cliError.js`
 Exports