@cratis/pi 7.101.0 → 7.103.0

package/package/corpus/skills/cratis-engineering-local-cross-repo-verification/references/npm-yarn.md

@@ -0,0 +1,78 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# npm and Yarn
+
+## Pack the package, not a link
+
+Requires node, tar and Yarn 4. Run the producer's normal build first. The helper does
+not run a separate build; Yarn's normal pack lifecycle hooks still run.
+
+```bash
+stamp=$(bash "$local" stamp "$producer")
+bash "$local" pack-npm "$producer" "$stamp"
+```
+
+It requires clean tracked workspace manifests, temporarily changes all non-private
+workspace versions and packs actual tarballs. It restores those manifests on
+success and failure; inspect diffs for other lifecycle-generated output. Yarn's
+`%s-%v.tgz` output slugifies a scoped name (`@cratis/foo` becomes `@cratis-foo`).
+Inspect dependency ranges in packed manifests: the helper changes versions, not
+arbitrary inter-package dependency constraints. Include every required workspace
+and verify the consumer resolves the intended tarballs.
+
+Do not use `portal:` or `link:` for this proof: filesystem package boundaries can
+create duplicate React instances or mismatched context providers, and may hide
+missing packed files. A tarball exercises what a downstream install receives.
+
+## Consumer overlay
+
+```bash
+bash "$local" use-npm "$consumer" "$stamp"
+cd "$consumer"
+yarn install
+# Run the repository's frontend build, lint, specs and reproducing UI action.
+```
+
+The helper selects every tarball ending in `-<stamp>.tgz` in the npm feed, reads
+each packed manifest for its package name, and adds root `resolutions` using
+absolute `file:` tarball paths. This also overrides transitive packages absent
+from consumer manifests, rather than silently falling back to published versions. It backs
+up root `package.json`, `yarn.lock` if present, and the pre-existing diff in the
+per-worktree session. It refuses another active npm backup. Check the install
+output/lockfile for the selected local versions; a successful install alone is not
+proof that the changed code was exercised.
+
+If Vite still serves the old package, stop the dev server and clear only the
+consumer's stale `node_modules/.vite` prebundle, then restart it. Never edit
+`node_modules` files to implement the fix. `use-npm` does not run install or clear
+caches itself. Unique stamps avoid tarball cache collisions.
+
+## Restore without discarding work
+
+```bash
+bash "$local" restore "$consumer"
+bash "$local" check "$consumer"
+```
+
+Restoration compares the manifest with the saved original and overlay. Only the
+overlay's own resolution values may differ; unrelated manifest edits cause a
+refusal. Formatting alone is not a conflict. For Yarn 4 lockfiles, unchanged
+entries, metadata and headers must remain byte-identical. The guard accepts
+entries resolving to the exact overlay tarballs (including Yarn locator/hash
+suffixes) and removal of old entries for those same package names. Those local
+package blocks are treated as overlay-owned, including checksums and dependencies.
+Thus the normal `use-npm` → `yarn install` → `restore` flow puts back both original
+files, including edits that existed before `use-npm`.
+
+Unrelated lockfile edits, metadata/install churn, unsupported lockfile syntax, or
+a newly created/deleted lockfile require manual review. The helper restores
+neither file and retains backups on a conflict. Read the saved before-diff and
+files, undo only local overlay changes manually, and retry. Merge later user
+changes instead of replacing them with the backup. Do not blindly checkout the
+consumer manifests. Reinstall released dependencies after restoration, then run
+`check` before any commit/push.
+
+Review `clean "$consumer" --stamp "$stamp"` before `--apply`. Passing the consumer
+allows Yarn cache discovery; no consumer or unavailable Yarn yields a reported
+skip. Unresolved backups block cleanup rather than silently losing recovery data.

package/package/corpus/skills/cratis-engineering-local-cross-repo-verification/references/other-environments.md

@@ -0,0 +1,60 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Other developer machines and agent hosts
+
+The corpus has no dependency on a particular home directory, queue runner or
+Docker desktop application. Execute the same helper from the installed skill.
+Use macOS or Linux with bash/git; Windows requires WSL. Add the toolchains selected
+by the recipe and check disk capacity before packing or building images.
+
+## Workspace-local feed
+
+On an ephemeral agent host, use an absolute ignored workspace directory:
+
+```bash
+export CRATIS_LOCAL_FEED=/absolute/workspace/.ai-work/local-feed
+# No CRATIS_LOCAL_RUN is needed when this host has no queue wrapper.
+stamp=$(bash "$local" stamp "$producer")
+```
+
+Keep the feed available for the entire consumer restore/test. `use-nuget` and
+`use-npm` record absolute paths, so do not move the workspace halfway through.
+Use the default per-worktree session inside the Git directory, or set
+`CRATIS_LOCAL_SESSION_DIR` to a unique ignored/external directory for that checkout.
+Do not share a session among consumers. Config at
+`${XDG_CONFIG_HOME:-$HOME/.config}/cratis/local-packages.env` is trusted shell code;
+on a host with no config, environment variables suffice. Do not put secrets in it.
+
+## Images and architecture
+
+A local tag must be loaded into the daemon used by the consumer tests. A remote
+builder or separate job daemon does not automatically share images. When necessary,
+transfer a task-owned `docker save` archive to the test job and `docker load` it
+there without pushing to a registry. Inspect the loaded tag and architecture,
+then run the actual container spec. Align `linux-arm64` publish with arm64 images,
+or `linux-x64` with amd64. Report any emulation and Release/Debug difference when
+comparing timings. Workspace sharing alone does not share a Docker image store.
+
+## Optional queue adapter
+
+`CRATIS_LOCAL_RUN` names an executable accepting `<kind> <label> -- <command...>`.
+The helper sends pack operations through it. A host may choose its own bounded
+queue and execution deadlines; do not copy another machine's process limits.
+Separately wrap consumer builds, Docker builds and container specs according to
+that host's policy. Queue timeout, cancellation and skipped checks are not passes.
+No wrapper is installed or configured by this skill.
+
+## Finish even on a failed proof
+
+Run `check` before any consumer commit/push. Restore overlays, unset shell/IDE and
+image selections, reinstall released dependencies where appropriate, then check
+again. Review `clean "$consumer" --stamp "$stamp"` and apply only its expected
+subjects. Stop task-owned containers first. Resolve npm backup conflicts rather
+than bypassing them. Report unreachable Docker/Yarn cleanup as incomplete.
+
+If a job is cancelled, preserve its session/backups and record what still needs
+restoration rather than assuming workspace disposal cleaned a shared feed, global
+NuGet cache or remote daemon. Do not delete artifacts another active task needs.
+After successful local proof, the normal authorized producer release and consumer
+released-version pin bump remain necessary.

package/package/corpus/skills/cratis-engineering-local-cross-repo-verification/references/worked-examples.md

@@ -0,0 +1,97 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Worked examples
+
+Use absolute producer/consumer paths for your checkouts and the entry point's
+`local` helper variable. These recipes define work to execute, not pre-verified
+results. Substitute actual regression filters and CI commands; stop on a failed
+step. Apply the entry point's check/restore/cleanup sequence to both repositories.
+
+## Chronicle kernel → Studio integration specs
+
+1. Reproduce Studio's integration bug against its released client/kernel. Record
+   the regression filter and inspect Studio's CI build/test commands.
+2. Generate the stamp and pack client packages plus their full dependency closure.
+   A client solution filter can omit CodeAnalysis. Include its package explicitly:
+
+   ```bash
+   stamp=$(bash "$local" stamp "$producer")
+   bash "$local" pack-nuget "$producer" "$stamp" path/to/client.slnf
+   bash "$local" pack-nuget "$producer" "$stamp" \
+     Source/Clients/DotNET.CodeAnalysis.Package/DotNET.CodeAnalysis.Package.csproj
+   ```
+
+   Create the filter in ignored scratch space with paths appropriate to that
+   Chronicle checkout. Inspect the nuspec dependencies: Contracts and every other
+   local dependency must exist in the feed at the same stamp. Do not proceed if a
+   required package is missing simply because one pack command passed.
+3. Publish the Release development kernel for the daemon's RID, build Workbench
+   `wwwroot`, and build/inspect `cratis/chronicle:<stamp>-development-slim` as in
+   [docker-images.md](docker-images.md). Preserve generated proxy edits.
+4. Run `use-nuget` with the client IDs Studio needs. Include transitive IDs missing
+   from Studio CPM explicitly. Source the printed env and use its generated NuGet
+   config when source mapping requires it. Verify local assets after restore.
+5. Select the image and run Studio's actual solution/spec project:
+
+   ```bash
+   export CHRONICLE_KERNEL_VERSION="$stamp"
+   cd "$consumer"
+   dotnet build path/to/Studio.slnx -c Release -p:StudioFullBuild=true -warnaserror
+   dotnet test Source/Integrations/Specs/Specs.csproj -c Release --no-build \
+     --filter '<regression>'
+   ```
+
+   Studio defaults kernel selection to the client version when the environment
+   override is absent. Ensure logs show the stamped local image. Local Debug
+   Studio builds skip analyzers; use `-p:StudioFullBuild=true` to match CI analyzer
+   coverage. Then run all required consumer gates, not only the filtered spec.
+6. If the bug remains, change Chronicle and repeat with a distinct stamp. If it
+   passes, run `check` before commits/pushes, restore, unset overrides, check again,
+   stop task-owned containers and review/apply stamp-scoped cleanup. Release the
+   producer normally and bump Studio to released pins later; never commit local
+   package versions or the local image selector.
+
+In run time this loop takes minutes: client packs about 1–2 minutes, kernel
+publish a few minutes, image build seconds with a warm cache, the Studio spec
+project build about 6 minutes, and the spec class itself seconds. When the spec
+fails because the local kernel refuses to start (for example a startup
+requirement the consumer's container setup does not satisfy yet), that is a
+real finding about the consumer, not about the overlay: read the container log
+before changing the producer.
+
+## Fundamentals → Arc
+
+For a .NET Fundamentals fix, build/spec the producer, generate its stamp and
+`pack-nuget` the affected projects and dependency closure. In Arc, run `use-nuget`
+with the required Fundamentals package IDs, source the printed env/config, restore,
+then build/spec Arc with its CI configuration. Inspect `project.assets.json` to
+confirm the actual stamp. No image is required unless the reproducer needs one.
+
+For a JavaScript Fundamentals fix, run the producer's normal build and
+`pack-npm`, then `use-npm` in Arc and install. Run Arc frontend build/specs and the
+reproducer. Include all affected workspace tarballs so a transitive dependency
+cannot silently remain released. A green producer-only spec is not consumer proof.
+Finish with the entry point's commit checks, restoration and cleanup.
+
+## Components → Studio frontend
+
+Build/spec Components using its own package scripts, including any required
+Storybook gate. Then:
+
+```bash
+stamp=$(bash "$local" stamp "$producer")
+bash "$local" pack-npm "$producer" "$stamp"
+bash "$local" use-npm "$consumer" "$stamp"
+cd "$consumer"
+yarn install
+```
+
+Confirm the Components `file:` tarball resolutions. Run Studio's frontend build,
+lint/specs and exercise the broken dialog/page. If Vite serves stale assets, stop
+the dev server, clear only its `.vite` prebundle and restart. Avoid `link:` and
+`portal:` because duplicate React/context instances distort the reproduction.
+Overlay-only lockfile changes from Yarn install are restored automatically.
+Review npm backups if unrelated changes cause `restore` to refuse; preserve
+that work, restore only local changes and retry. Reinstall released packages,
+run `check`, and review/apply cleanup for this stamp.