diff --git a/.build/just/bump-version.ts b/.build/just/bump-version.ts new file mode 100644 index 0000000..8cb38ff --- /dev/null +++ b/.build/just/bump-version.ts @@ -0,0 +1,62 @@ +// Bumps one part of the semantic version in package.json, for `just bump `. +// +// The parts after the one bumped are reset to 0, and a pre-release or build suffix is dropped: +// +// 2.0.1 major -> 3.0.0 minor -> 2.1.0 patch -> 2.0.2 +// 2.1.0-rc.1 patch -> 2.1.1 +// +// Only the "version" value is rewritten, in place, so the file keeps its own indentation, key order +// and line endings - re-serialising the JSON would reformat it. +// +// bun bump-version.ts [package.json] [--dry-run] + +import { readFileSync, writeFileSync } from "node:fs"; + +const parts = ["major", "minor", "patch"] as const; +type Part = (typeof parts)[number]; + +const args = process.argv.slice(2); +const dryRun = args.includes("--dry-run"); +const [part, file = "package.json"] = args.filter((arg) => arg !== "--dry-run"); + +if (!parts.includes(part as Part)) { + console.error(`Expected one of ${parts.join(", ")}, not '${part ?? ""}'.`); + process.exit(1); +} + +const text = readFileSync(file, "utf8"); +const versionPattern = /("version"\s*:\s*")([^"]*)(")/; +const match = versionPattern.exec(text); +if (!match) { + console.error(`No "version" field in ${file}.`); + process.exit(1); +} + +const current = match[2]; +const semver = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(current); +if (!semver) { + console.error(`'${current}' in ${file} is not a major.minor.patch version.`); + process.exit(1); +} + +let [major, minor, patch] = semver.slice(1, 4).map(Number); +switch (part as Part) { + case "major": + [major, minor, patch] = [major + 1, 0, 0]; + break; + case "minor": + [minor, patch] = [minor + 1, 0]; + break; + case "patch": + patch += 1; + break; +} + +const next = `${major}.${minor}.${patch}`; +if (dryRun) { + console.log(` ${file}: ${current} -> ${next} (dry run, nothing written)`); + process.exit(0); +} + +writeFileSync(file, text.replace(versionPattern, `$1${next}$3`)); +console.log(` ${file}: ${current} -> ${next}`); diff --git a/.build/just/dotnet.just b/.build/just/dotnet.just new file mode 100644 index 0000000..9507263 --- /dev/null +++ b/.build/just/dotnet.just @@ -0,0 +1,53 @@ +# .NET recipes: tools, restore, build, clean, test and pack, all against one solution. +# +# Override these in the root Justfile. `solution_file` is the one nearly every repository sets; "." +# lets dotnet find the single solution or project in the repository root. + +solution_file := "." +build_configuration := "Debug" +artifacts_folder := "./artifacts" + +# Every test. A TUnit/MTP tree-node filter: /assembly/namespace/class/test. +test_filter := "/*/*/*/*/" + +# Restore the repository's .NET local tools (.config/dotnet-tools.json) +[group('Build and Test')] +ensure-tools: + dotnet tool restore + +# Restore NuGet packages for the solution +[group('Build and Test')] +restore *args: + echo "==> Restoring {{ BLUE }}{{ solution_file }}{{ NORMAL }}" + dotnet restore "{{ solution_file }}" {{ args }} + +# Build the solution with build_configuration (default: Debug) +[group('Build and Test')] +build *args: + echo "==> Building {{ BLUE }}{{ solution_file }}{{ NORMAL }} ({{ GREEN }}{{ current_version }}{{ NORMAL }}) with configuration {{ YELLOW }}{{ build_configuration }}{{ NORMAL }}" + dotnet build "{{ solution_file }}" --configuration "{{ build_configuration }}" {{ args }} + +# Clean the solution with build_configuration (default: Debug) +[group('Build and Test')] +clean *args: + echo "==> Cleaning {{ BLUE }}{{ solution_file }}{{ NORMAL }} with configuration {{ YELLOW }}{{ build_configuration }}{{ NORMAL }}" + dotnet clean "{{ solution_file }}" --configuration "{{ build_configuration }}" {{ args }} + +# Run the tests matching a tree-node filter (default: every test) +# +# just test "/*/*/*/*[Category=Unit]" +# just test "/*/*/ProjectHarnessTests/*" +# +# Exit code 8 - "no test ran" - is ignored, so a filter that matches nothing in one test project does +# not fail the run for the others. +[doc('Run the tests matching a tree-node filter (default: every test)')] +[group('Build and Test')] +test filter=test_filter *args: + echo "==> Testing {{ BLUE }}{{ solution_file }}{{ NORMAL }} ({{ YELLOW }}{{ build_configuration }}{{ NORMAL }}) with filter {{ GREEN }}{{ filter }}{{ NORMAL }}" + dotnet test --project "{{ solution_file }}" --configuration "{{ build_configuration }}" --treenode-filter "{{ filter }}" --ignore-exit-code 8 {{ args }} + +# Pack every packable project into artifacts_folder (default: ./artifacts) +[group('Build and Test')] +pack artifact_folder=artifacts_folder *args: + echo "==> Packing {{ BLUE }}{{ solution_file }}{{ NORMAL }} ({{ GREEN }}{{ current_version }}{{ NORMAL }}) to {{ YELLOW }}{{ artifact_folder }}{{ NORMAL }}" + dotnet pack "{{ solution_file }}" --configuration "{{ build_configuration }}" --output "{{ artifact_folder }}" {{ args }} diff --git a/.build/just/env.just b/.build/just/env.just new file mode 100644 index 0000000..6156f34 --- /dev/null +++ b/.build/just/env.just @@ -0,0 +1,56 @@ +# The environment every recipe runs in: telemetry opt-outs, and the .NET CLI speed-ups. +# +# `export` hands each value to every process a recipe starts - dotnet, bun, pwsh, git. Each one is a +# default: `env(NAME, value)` keeps whatever the caller's environment already says, so a developer +# who has opted back in, or a CI job that sets its own value, is never overridden. + +# -- Telemetry and tracking -------------------------------------------------------------------------- + +# The .NET CLI, MSBuild and Aspire. +export DOTNET_CLI_TELEMETRY_OPTOUT := env("DOTNET_CLI_TELEMETRY_OPTOUT", "1") +export MSBUILD_TELEMETRY_OPTOUT := env("MSBUILD_TELEMETRY_OPTOUT", "1") +export ASPIRE_CLI_TELEMETRY_OPTOUT := env("ASPIRE_CLI_TELEMETRY_OPTOUT", "true") +export ASPIRE_DASHBOARD_TELEMETRY_OPTOUT := env("ASPIRE_DASHBOARD_TELEMETRY_OPTOUT", "true") + +# The Azure SDKs and the Azure MCP server. +export AZURE_CORE_COLLECT_TELEMETRY := env("AZURE_CORE_COLLECT_TELEMETRY", "0") +export AZURE_MCP_COLLECT_TELEMETRY := env("AZURE_MCP_COLLECT_TELEMETRY", "0") + +# PowerShell, for scripts a recipe runs through pwsh, and Git Credential Manager. +export POWERSHELL_TELEMETRY_OPTOUT := env("POWERSHELL_TELEMETRY_OPTOUT", "1") +export GCM_TELEMETRY_OPTOUT := env("GCM_TELEMETRY_OPTOUT", "1") + +# JavaScript tooling: Next.js, Astro, Yarn, and the funding banners printed by postinstall scripts. +export NEXT_TELEMETRY_DISABLED := env("NEXT_TELEMETRY_DISABLED", "1") +export ASTRO_TELEMETRY_DISABLED := env("ASTRO_TELEMETRY_DISABLED", "1") +export YARN_ENABLE_TELEMETRY := env("YARN_ENABLE_TELEMETRY", "0") +export DISABLE_OPENCOLLECTIVE := env("DISABLE_OPENCOLLECTIVE", "true") + +# Claude Code, when a recipe launches it. +export CLAUDE_CLI_TELEMETRY_OPTOUT := env("CLAUDE_CLI_TELEMETRY_OPTOUT", "1") +export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC := env("CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC", "1") +export DISABLE_ERROR_REPORTING := env("DISABLE_ERROR_REPORTING", "1") +export DISABLE_TELEMETRY := env("DISABLE_TELEMETRY", "1") + +# The cross-tool conventions, honoured by Bun and many other CLIs. +export DO_NOT_TRACK := env("DO_NOT_TRACK", "1") +export TELEMETRY_DISABLED := env("TELEMETRY_DISABLED", "1") + +# -- .NET CLI speed and noise ------------------------------------------------------------------------ + +# No welcome banner or first-run notice. +export DOTNET_NOLOGO := env("DOTNET_NOLOGO", "1") + +# The NativeAOT CLI host (.NET 11): near-instant `dotnet --version`, `--help` and tool launches, with +# everything else falling back to the managed CLI. On by default; opt out with DOTNET_CLI_ENABLEAOT=false. +export DOTNET_CLI_ENABLEAOT := env("DOTNET_CLI_ENABLEAOT", "true") + +# The MSBuild server (DOTNET_CLI_USE_MSBUILD_SERVER) is deliberately left to the SDK's own default. +# Forcing it on makes every `dotnet build` share one long-lived MSBuild process, and its NuGet SDK +# resolver keeps the settings it first read: a build under a different nuget.config - a test +# harness's throwaway consumer, a second repository - then resolves SDKs with the wrong sources and +# fallback folders, and fails with MSB4242. Set it yourself where every build shares one NuGet +# configuration; `just scrub` shuts the server down. + +# Multithreaded MSBuild (-mt) is deliberately not set here. Purview.BuildSdk bootstraps it into the +# repository's Directory.Build.rsp, so a plain `dotnet build` and an IDE build get it as well. diff --git a/.build/just/index.just b/.build/just/index.just new file mode 100644 index 0000000..beda195 --- /dev/null +++ b/.build/just/index.just @@ -0,0 +1,41 @@ +# The barrel for the shared just modules. The root Justfile imports this file, and nothing else: +# +# set allow-duplicate-variables +# set allow-duplicate-recipes +# +# import ".build/just/index.just" +# +# Every module gives its variables a default. The root Justfile overrides one by defining the same +# name - `solution_file := "src/Acme.slnx"` - and overrides a no-op hook such as `_after-bump` the +# same way. Both settings are what let a root definition win; without them a duplicate is an error. +# +# The required modules are imported unconditionally. The optional ones use `import?`, so a module is +# switched on by copying its file into this folder and off by deleting it: this file never changes. +# +# These files are copied verbatim from the purview-buildsdk-justfile skill. Change a recipe there, +# not here, and put anything specific to one repository in its root Justfile. + +# Telemetry opt-outs and the .NET CLI speed-ups, exported to every recipe. +import "env.just" + +# version, bump +import "version.just" + +# ensure-tools, restore, build, clean, test, pack +import "dotnet.just" + +# lint-check, lint-fix, vs, scrub +import "utilities.just" + +# pipeline-pr, pipeline-build, pipeline-tests - local runs of the Purview.Build pipeline +import "purview-build.just" + +# skills-* - agent skills through the skills CLI, run by skills.mts (no .NET involved) +import "skills.just" + +# Optional. pipeline-pack-validate, pipeline-local-release, pipeline-release - for a repository that +# packs NuGet packages. +import? "purview-build-nuget.just" + +# Optional. docs, docs-install, docs-check - for a pm-docs-site project site (purview-dev/pm-skills). +import? "docs.just" diff --git a/.build/just/purview-build-nuget.just b/.build/just/purview-build-nuget.just new file mode 100644 index 0000000..2154876 --- /dev/null +++ b/.build/just/purview-build-nuget.just @@ -0,0 +1,30 @@ +# Optional: Purview.Build pipeline runs that pack, validate and publish NuGet packages. Copy this file +# into the module folder only when the repository packs packages; the barrel imports it if present. +# +# Pack validation reads PackValidation in .config/purview-build.json. Its RequiredContent lists every +# file each package must contain, and a packed file it does not list fails the run - so a new file +# under a package's Sdk/, build/ or buildTransitive/ needs a RequiredContent entry too. + +# Run the pipeline through pack and pack validation (restore, build, lint, tests, pack, validate), publishing nothing +[group('Pipeline')] +pipeline-pack-validate *args: ensure-tools + echo "==> Running the pack and validate pipeline" + {{ pipeline_tool }} --Build:RunPack=true --Build:ValidatePack=true --Release:Mode=None {{ args }} + +# Run the release pipeline, publishing to a local NuGet feed (restore, build, lint, tests, pack, validate, publish) +# +# `just` runs recipes through sh, which strips backslashes from unquoted arguments. Set the +# LOCAL_NUGET_FEED_PATH environment variable, or use forward slashes: +# +# just pipeline-local-release --PublishLocalNuGet:LocalFeedPath=p:/_sync-projects/.local-nuget/ +[doc('Run the release pipeline, publishing to a local NuGet feed (restore, build, lint, tests, pack, validate, publish)')] +[group('Pipeline')] +pipeline-local-release *args: ensure-tools + echo "==> Running the local release pipeline" + {{ pipeline_tool }} --Release:Mode=LocalNuGet {{ args }} + +# Run the release pipeline, publishing to NuGet (restore, build, lint, tests, pack, validate, publish, GitHub release) +[group('Pipeline')] +pipeline-release *args: ensure-tools + echo "==> Running the release pipeline" + {{ pipeline_tool }} --Release:Mode=NuGet {{ args }} diff --git a/.build/just/purview-build.just b/.build/just/purview-build.just new file mode 100644 index 0000000..244e44c --- /dev/null +++ b/.build/just/purview-build.just @@ -0,0 +1,24 @@ +# Local runs of the Purview.Build pipeline - the same `dotnet purview-build` tool, and the same +# .config/purview-build.json, that CI runs. Every Build stage - tests, lint, pack and pack validation - +# runs unless that file or an argument turns it off. Anything after the recipe name is passed to the +# tool, so a setting can be overridden for one run: `just pipeline-pr --Build:TestFilter="/*/*/*/*[Category=Unit]"`. + +pipeline_tool := "dotnet purview-build" + +# Run the PR pipeline (restore, build, lint, tests, pack, validate), as configured +[group('Pipeline')] +pipeline-pr *args: ensure-tools + echo "==> Running the PR pipeline" + {{ pipeline_tool }} {{ args }} + +# Run the build pipeline (restore, build, lint, pack, validate), without tests +[group('Pipeline')] +pipeline-build *args: ensure-tools + echo "==> Running the build pipeline" + {{ pipeline_tool }} --Build:RunTests=false --Release:Mode=None {{ args }} + +# Run the pipeline with tests forced on and release off (restore, build, lint, tests, pack, validate) +[group('Pipeline')] +pipeline-tests *args: ensure-tools + echo "==> Running the tests pipeline" + {{ pipeline_tool }} --Build:RunTests=true --Release:Mode=None {{ args }} diff --git a/.build/just/skills.just b/.build/just/skills.just new file mode 100644 index 0000000..6dea181 --- /dev/null +++ b/.build/just/skills.just @@ -0,0 +1,59 @@ +# The agent-skill recipes: a thin wrapper over the standard skills CLI (`bun x skills@1` by default). +# +# The work is done by skills.mts, beside this file, which needs no .NET at all - no solution to +# evaluate, no restore and no build - so a repository whose build is broken can still install the +# skills that might help fix it. It runs under Bun, then Deno, and falls back to Node with the +# generated skills.mjs. Set PURVIEW_SKILLS_RUNTIME to choose, for example `node`, `bun` or `deno run -A`. +# +# Every recipe here is run by a person, on purpose. Never make one a dependency of build, test or +# default, or call skills-add, -install, -update or -fix from a git hook: they change the repository. +# skills-check is read-only. +# +# Settings live in the "Skills" section of .config/purview-build-sdk.json: +# +# { "Skills": { "Agents": ["claude-code", "codex"], "Runner": "bun" } } +# +# Pass a one-off through *args, for example `just skills-update --dry-run --agents claude-code,codex`, +# or set the matching PURVIEW_SKILLS_* environment variable. + +skills_script := source_directory() / "skills" + +# Runs skills.mts (or skills.mjs) from the repository root with the given arguments. +_skills_run := 'purview_skills() { if [ -n "${PURVIEW_SKILLS_RUNTIME:-}" ]; then case "$PURVIEW_SKILLS_RUNTIME" in node*) $PURVIEW_SKILLS_RUNTIME "' + skills_script + '.mjs" "$@" ;; *) $PURVIEW_SKILLS_RUNTIME "' + skills_script + '.mts" "$@" ;; esac; elif command -v bun >/dev/null 2>&1; then bun "' + skills_script + '.mts" "$@"; elif command -v deno >/dev/null 2>&1; then deno run -A "' + skills_script + '.mts" "$@"; elif command -v node >/dev/null 2>&1; then node "' + skills_script + '.mjs" "$@"; else echo "error PRSKL0004: the skills recipes need Bun, Deno or Node.js on PATH." >&2; return 1; fi; }; purview_skills' + +# Install skills from another repository through the skills CLI (append '#' to pin it) +# +# just skills-add purview-dev/engineering-playbook +[doc("Install skills from another repository through the skills CLI (append '#' to pin it)")] +[group('Agent Skills')] +skills-add source *args: + echo "==> Installing skills from {{ BLUE }}{{ source }}{{ NORMAL }}" + {{ _skills_run }} add {{ quote(source) }} --root "{{ justfile_directory() }}" {{ args }} + +# Restore every skill skills-lock.json records - how a fresh clone gets the repository's skills back +[group('Agent Skills')] +skills-install *args: + {{ _skills_run }} install --root "{{ justfile_directory() }}" {{ args }} + +# Update the agent skills by re-adding every unique source in skills-lock.json +# +# Each source is re-added at its latest with every skill it has, which refreshes the installed skills +# and adds any a source has gained; `skills update` is never run. skills-fix then removes links from +# agent directories Skills.Agents does not select, and does nothing when it is unset. +# +# just skills-update --dry-run +[doc('Update the agent skills by re-adding every unique source in skills-lock.json')] +[group('Agent Skills')] +skills-update *args: + {{ _skills_run }} update --root "{{ justfile_directory() }}" {{ args }} + {{ _skills_run }} fix --root "{{ justfile_directory() }}" {{ args }} + +# Check that only the skill directories of the agents in Skills.Agents exist +[group('Agent Skills')] +skills-check *args: + {{ _skills_run }} check --root "{{ justfile_directory() }}" {{ args }} + +# Remove the skills CLI's links from agent directories Skills.Agents does not select +[group('Agent Skills')] +skills-fix *args: + {{ _skills_run }} fix --root "{{ justfile_directory() }}" {{ args }} diff --git a/.build/just/skills.mjs b/.build/just/skills.mjs new file mode 100644 index 0000000..7c56ae8 --- /dev/null +++ b/.build/just/skills.mjs @@ -0,0 +1,686 @@ +// GENERATED from skills.mts by scripts/sync-skills-script.mjs in purview-dev/build-sdk - do not edit. +// It is skills.mts with the TypeScript removed, for a machine with Node but neither Bun nor Deno. + +// The Purview.BuildSdk agent-skill commands: a thin wrapper over the standard skills CLI +// (`bun x skills@1` by default), run by the skills-* recipes in skills.just. +// +// Nothing here needs .NET. There is no solution to evaluate, no package to restore and no project +// that has to build, so a repository whose build is broken can still install the skills that might +// help fix it. +// +// add skills add "" --skill "*" - append '#' to the source to pin it +// install [source] add , or restore skills-lock.json with skills experimental_install +// update re-add every unique skills-lock.json source at its latest, with every skill +// check fail when a skill directory exists for an agent that is not selected +// fix remove the skills CLI's links from those directories +// +// Settings, highest first: command-line options, PURVIEW_SKILLS_* environment variables, the +// "Skills" section of .config/purview-build-sdk.json, then the defaults below. Every command runs +// from the repository root, because skills-lock.json and the agent directories belong to the +// repository rather than to a project. +// +// skills.mts is the source. skills.mjs is generated from it by Node's own type stripper, for a +// machine with Node but neither Bun nor Deno: edit this file, then run `just skills-script-sync`. +// Keep to erasable TypeScript (no enums, namespaces or parameter properties) so both stay possible. + +import { spawnSync } from "node:child_process"; +import { existsSync, lstatSync, readdirSync, readFileSync, rmdirSync, statSync, unlinkSync } from "node:fs"; +import { delimiter, dirname, join, relative, resolve } from "node:path"; +import process from "node:process"; +import { parseArgs } from "node:util"; + +const configKeys = [ + "Agents", + "Runner", + "RunnerCandidates", + "Package", + "Command", + "LockFile", + "DryRun", + "AgentDirectories", +]; + +// Each package runner spells "run this npm package" its own way. Every form was checked against the +// real tool, because a wrong one is a command that simply does not run. A runner missing from this +// table still works: it falls through to ' ', the form most new runners adopt. +const launchers = { + skills: () => "skills", + npx: (spec) => `npx -y ${spec}`, + bunx: (spec) => `bunx ${spec}`, + bun: (spec) => `bun x ${spec}`, + pnpm: (spec) => `pnpm dlx ${spec}`, + yarn: (spec) => `yarn dlx ${spec}`, + deno: (spec) => `deno run -A npm:${spec}`, +}; + +// Where the skills CLI writes a project-scope install for each agent, from its own agent table +// (skills 1.7.6, docs/agents.md). Only check and fix read this, and only when agents are selected. +// The CLI adds agents independently of this script; add one through Skills.AgentDirectories in +// .config/purview-build-sdk.json rather than waiting for a release. +const defaultAgentDirectories = [ + { + path: ".agents/skills", + agents: [ + "amp", + "antigravity", + "antigravity-cli", + "cline", + "codex", + "cursor", + "deepagents", + "dexto", + "droid", + "firebender", + "fx", + "gemini-cli", + "github-copilot", + "kilo", + "kimi-code-cli", + "loaf", + "opencode", + "pi", + "promptscript", + "replit", + "sarvam-code", + "universal", + "warp", + "zed", + ], + }, + { path: ".adal/skills", agents: ["adal"] }, + { path: ".aider-desk/skills", agents: ["aider-desk"] }, + { path: ".augment/skills", agents: ["augment"] }, + { path: ".autohand/skills", agents: ["autohand-code"] }, + { path: ".bob/skills", agents: ["bob"] }, + { path: ".claude/skills", agents: ["claude-code"] }, + { path: ".codeartsdoer/skills", agents: ["codearts-agent"] }, + { path: ".codebuddy/skills", agents: ["codebuddy"] }, + { path: ".codemaker/skills", agents: ["codemaker"] }, + { path: ".codestudio/skills", agents: ["codestudio"] }, + { path: ".commandcode/skills", agents: ["command-code"] }, + { path: ".continue/skills", agents: ["continue"] }, + { path: ".cortex/skills", agents: ["cortex"] }, + { path: ".crush/skills", agents: ["crush"] }, + { path: ".devin/skills", agents: ["devin"] }, + { path: ".forge/skills", agents: ["forgecode"] }, + { path: ".goose/skills", agents: ["goose"] }, + { path: ".grok/skills", agents: ["grok"] }, + { path: ".hermes/skills", agents: ["hermes-agent"] }, + { path: ".iflow/skills", agents: ["iflow-cli"] }, + { path: ".inferencesh/skills", agents: ["inference-sh"] }, + { path: ".jazz/skills", agents: ["jazz"] }, + { path: ".junie/skills", agents: ["junie"] }, + { path: ".kimchi/skills", agents: ["kimchi"] }, + { path: ".kiro/skills", agents: ["kiro-cli"] }, + { path: ".kode/skills", agents: ["kode"] }, + { path: ".lingma/skills", agents: ["lingma"] }, + { path: ".mcpjam/skills", agents: ["mcpjam"] }, + { path: ".minimax/skills", agents: ["minimax-code"] }, + { path: ".moxby/skills", agents: ["moxby"] }, + { path: ".mux/skills", agents: ["mux"] }, + { path: ".neovate/skills", agents: ["neovate"] }, + { path: ".ona/skills", agents: ["ona"] }, + { path: ".openhands/skills", agents: ["openhands"] }, + { path: ".pochi/skills", agents: ["pochi"] }, + { path: ".posit/assistant/skills", agents: ["posit-assistant"] }, + { path: ".qoder/skills", agents: ["qoder", "qoder-cn"] }, + { path: ".qwen/skills", agents: ["qwen-code"] }, + { path: ".reasonix/skills", agents: ["reasonix"] }, + { path: ".roo/skills", agents: ["roo"] }, + { path: ".rovodev/skills", agents: ["rovodev"] }, + { path: ".tabnine/agent/skills", agents: ["tabnine-cli"] }, + { path: ".terramind/skills", agents: ["terramind"] }, + { path: ".tinycloud/skills", agents: ["tinycloud"] }, + { path: ".trae/skills", agents: ["trae", "trae-cn"] }, + { path: ".vibe/skills", agents: ["mistral-vibe"] }, + { path: ".windsurf/skills", agents: ["windsurf"] }, + { path: ".zcode/skills", agents: ["zcode"] }, + { path: ".zencoder/skills", agents: ["zencoder", "zenflow"] }, + { path: "agent/skills", agents: ["eve"] }, + { path: "data/skills", agents: ["astrbot"] }, + // openclaw installs into a root 'skills/', the folder a repository authors its own skills in. It is + // listed so selecting openclaw is not an unknown agent, but the authored folder is never touched. + { path: "skills", agents: ["openclaw"] }, +]; + +const usage = `Usage: skills.mts [options] + +Commands: + add Install every skill a source has (append '#' to pin it) + install [source] Install from a source, or restore skills-lock.json + update Re-add every skills-lock.json source at its latest + check Fail when a skill directory exists for an unselected agent + fix Remove the skills CLI's links from those directories + +Options: + --root Repository root (default: the nearest folder holding .git) + --config Settings file (default: .config/purview-build-sdk.json) + --agents Agents to install to, separated by ',', ';' or spaces + --runner Package runner: bun, npx, bunx, pnpm, yarn, deno or skills + --command Launch the skills CLI with this command instead + --package Package the launcher runs (default: skills@1) + --lock-file skills-lock.json location (default: the repository root) + --dry-run Print the skills CLI commands without running them +`; + +class SkillsError extends Error {} + +let failed = false; + +function report(code, message) { + console.error(`error ${code}: ${message}`); + failed = true; +} + +function warn(code, message) { + console.error(`warning ${code}: ${message}`); +} + +function info(message) { + console.log(message); +} + +function environment(name) { + const value = process.env[name]; + return value === undefined || value.trim() === "" ? undefined : value.trim(); +} + +function splitList(value) { + return value + .replace(/^[\s,;"']+|[\s,;"']+$/g, "") + .split(/[\s,;]+/) + .filter((entry) => entry.length > 0); +} + +function quote(value) { + if (value.includes('"')) throw new SkillsError(`'${value}' contains a double quote, which cannot be passed safely.`); + return `"${value}"`; +} + +function unique(values) { + const seen = new Set(); + return values.filter((value) => { + const key = value.toLowerCase(); + if (seen.has(key)) return false; + seen.add(key); + return true; + }); +} + +// The nearest ancestor holding '.git' - a directory in a clone, a file in a worktree or a submodule. +// The recipes always pass --root; this only matters when the script is run by hand. +function findRepositoryRoot(start) { + for (let directory = resolve(start); ; directory = dirname(directory)) { + if (existsSync(join(directory, ".git"))) return directory; + if (dirname(directory) === directory) return resolve(start); + } +} + +function readConfig(configPath) { + if (!existsSync(configPath)) return {}; + + let document; + try { + document = JSON.parse(readFileSync(configPath, "utf8")); + } catch (exception) { + throw new SkillsError(`PRSKL0018 '${configPath}' is not valid JSON: ${(exception).message}`); + } + + const section = (document)?.["Skills"]; + if (section === undefined) return {}; + if (section === null || typeof section !== "object" || Array.isArray(section)) + throw new SkillsError(`PRSKL0018 '${configPath}': "Skills" must be an object.`); + + for (const key of Object.keys(section)) { + if (!configKeys.includes(key)) + warn("PRSKL0019", `'${configPath}': "Skills.${key}" is not a setting and is ignored. Known: ${configKeys.join(", ")}.`); + } + + return section; +} + +function configString(config, key, configPath) { + const value = config[key]; + if (value === undefined || value === null) return undefined; + if (typeof value !== "string") throw new SkillsError(`PRSKL0018 '${configPath}': "Skills.${key}" must be a string.`); + return value.trim() === "" ? undefined : value.trim(); +} + +function configList(config, key, configPath) { + const value = config[key]; + if (value === undefined || value === null) return undefined; + if (typeof value === "string") return splitList(value); + if (Array.isArray(value) && value.every((entry) => typeof entry === "string")) + return value.flatMap((entry) => splitList(entry)); + throw new SkillsError(`PRSKL0018 '${configPath}': "Skills.${key}" must be a string or an array of strings.`); +} + +function configBoolean(config, key, configPath) { + const value = config[key]; + if (value === undefined || value === null) return undefined; + if (typeof value !== "boolean") throw new SkillsError(`PRSKL0018 '${configPath}': "Skills.${key}" must be true or false.`); + return value; +} + +function configAgentDirectories(config, configPath) { + const value = config["AgentDirectories"]; + if (value === undefined || value === null) return []; + if (typeof value !== "object" || Array.isArray(value)) + throw new SkillsError(`PRSKL0018 '${configPath}': "Skills.AgentDirectories" must map a directory to its agents.`); + + return Object.entries(value).map(([path, agents]) => { + if (typeof agents === "string") return { path, agents: splitList(agents) }; + if (Array.isArray(agents) && agents.every((entry) => typeof entry === "string")) + return { path, agents: agents }; + throw new SkillsError(`PRSKL0018 '${configPath}': "Skills.AgentDirectories.${path}" must be a string or an array of strings.`); + }); +} + +function parseBoolean(value) { + if (value === undefined) return undefined; + return ["1", "true", "yes", "on"].includes(value.toLowerCase()); +} + +function resolveSettings(values) { + const option = (name) => { + const value = values[name]; + return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined; + }; + + const root = resolve(option("root") ?? findRepositoryRoot(process.cwd())); + const configPath = resolve(root, option("config") ?? environment("PURVIEW_SKILLS_CONFIG") ?? ".config/purview-build-sdk.json"); + const config = readConfig(configPath); + + const agents = option("agents") ?? environment("PURVIEW_SKILLS_AGENTS"); + const candidates = environment("PURVIEW_SKILLS_RUNNER_CANDIDATES"); + const lockFile = option("lock-file") ?? environment("PURVIEW_SKILLS_LOCK_FILE") ?? configString(config, "LockFile", configPath); + + return { + root, + configPath, + agents: agents !== undefined ? splitList(agents) : (configList(config, "Agents", configPath) ?? []), + runner: option("runner") ?? environment("PURVIEW_SKILLS_RUNNER") ?? configString(config, "Runner", configPath) ?? "bun", + runnerCandidates: + candidates !== undefined + ? splitList(candidates) + : (configList(config, "RunnerCandidates", configPath) ?? ["bun", "npx", "bunx", "pnpm", "yarn", "deno"]), + packageSpec: + option("package") ?? environment("PURVIEW_SKILLS_PACKAGE") ?? configString(config, "Package", configPath) ?? "skills@1", + command: option("command") ?? environment("PURVIEW_SKILLS_COMMAND") ?? configString(config, "Command", configPath) ?? "", + lockFile: resolve(root, lockFile ?? "skills-lock.json"), + dryRun: + values["dry-run"] === true || + (parseBoolean(environment("PURVIEW_SKILLS_DRY_RUN")) ?? configBoolean(config, "DryRun", configPath) ?? false), + agentDirectories: [...defaultAgentDirectories, ...configAgentDirectories(config, configPath)], + }; +} + +function launcherFor(runner, spec) { + const launcher = launchers[runner]; + return launcher === undefined ? `${runner} ${spec}` : launcher(spec); +} + +// PATH is probed directly rather than by starting a version check: no process, nothing to download, +// nothing to hang. PATHEXT is honoured on Windows, where these commands are .cmd shims. +function findOnPath(names) { + const windows = process.platform === "win32"; + const extensions = windows ? ["", ...(environment("PATHEXT") ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)] : [""]; + const directories = (process.env["PATH"] ?? "") + .split(delimiter) + .map((entry) => entry.trim().replace(/^"|"$/g, "")) + .filter((entry) => entry.length > 0); + + for (const name of names) { + for (const directory of directories) { + for (const extension of extensions) { + const candidate = join(directory, name + extension); + try { + if (statSync(candidate).isFile()) return { name, path: candidate }; + } catch { + // Not here; a malformed PATH entry must not stop the probe either. + } + } + } + } + + return undefined; +} + +// 'skills' already on PATH is tried first because it needs no download, then the configured runner, +// then the other candidates - so a machine with Node but no Bun still installs. +function resolveLauncher(settings) { + if (settings.command !== "") return settings.command; + + const found = findOnPath(unique(["skills", settings.runner, ...settings.runnerCandidates])); + if (found !== undefined) { + const launcher = launcherFor(found.name, settings.packageSpec); + info(`Using the skills CLI via '${launcher}' (${found.path}).`); + return launcher; + } + + // A dry run runs nothing, so it works on a machine with no runner at all. + if (settings.dryRun) return launcherFor(settings.runner, settings.packageSpec); + + throw new SkillsError( + `PRSKL0004 Cannot run the skills CLI: none of ${unique(["skills", settings.runner, ...settings.runnerCandidates]).join(", ")} was found on PATH. ` + + "Install Bun (which provides 'bun x') or Node.js (which provides npx), or any of pnpm, yarn or deno, " + + "or install the CLI globally with 'npm install -g skills'. Choose a runner with --runner or Skills.Runner; " + + "replace the launcher entirely with --command or Skills.Command.", + ); +} + +function agentArguments(settings) { + // The CLI does not split a comma-separated --agent, so each agent gets its own flag. + return settings.agents.map((agent) => ` --agent ${quote(agent)}`).join(""); +} + +function execute(settings, commandLine) { + info(settings.dryRun ? `Agent skills (dry run): ${commandLine}` : `Agent skills: ${commandLine}`); + if (settings.dryRun) return 0; + + const result = spawnSync(commandLine, { cwd: settings.root, shell: true, stdio: "inherit" }); + if (result.error !== undefined) { + console.error(result.error.message); + return 1; + } + + return result.status ?? 1; +} + +function addSource(settings, source) { + const launcher = resolveLauncher(settings); + // '-y' keeps 'add' non-interactive. '*' is every skill the source has, and a re-run is safe: the + // CLI reinstalls each skill it is given, replacing the installed copy. + const exitCode = execute(settings, `${launcher} add ${quote(source)} --skill "*"${agentArguments(settings)} -y`); + if (exitCode !== 0) report("PRSKL0008", `Agent skills: adding '${source}' failed with exit code ${exitCode}.`); +} + +function install(settings, source) { + if (source !== undefined) { + addSource(settings, source); + return; + } + + if (!existsSync(settings.lockFile)) + throw new SkillsError( + `PRSKL0007 Nothing to install: no source was given, and '${settings.lockFile}' does not exist to restore from. ` + + "Install from a source first, for example: just skills-add purview-dev/build-sdk", + ); + + const exitCode = execute(settings, `${resolveLauncher(settings)} experimental_install`); + if (exitCode !== 0) report("PRSKL0008", `Agent skills: restoring '${settings.lockFile}' failed with exit code ${exitCode}.`); +} + +function readLockSources(lockFile) { + let document; + try { + document = JSON.parse(readFileSync(lockFile, "utf8")); + } catch (exception) { + throw new SkillsError(`PRSKL0007 Cannot read '${lockFile}': ${(exception).message}`); + } + + const skills = (document)?.skills ?? {}; + const sources = Object.values(skills) + .map((entry) => (typeof entry?.source === "string" ? entry.source.trim() : "")) + .filter((source) => source.length > 0); + + return unique(sources).sort((left, right) => left.toLowerCase().localeCompare(right.toLowerCase())); +} + +// Update is 'add', never 'skills update'. 'skills add' reinstalls every skill it selects, so one +// re-add of each source, with every skill it has, both refreshes what is installed and brings in +// anything the source has gained. The lockfile's own skill names are deliberately not reused: naming +// them would leave out a skill added since. Every source is attempted even when one fails. +function update(settings) { + if (!existsSync(settings.lockFile)) + throw new SkillsError( + `PRSKL0007 Cannot update agent skills: '${settings.lockFile}' does not exist. ` + + "Update re-adds the sources the skills CLI recorded there; install skills first with: just skills-add ", + ); + + const sources = readLockSources(settings.lockFile); + if (sources.length === 0) { + info(`Agent skills: no sources recorded in ${settings.lockFile}.`); + return; + } + + const launcher = resolveLauncher(settings); + const failures = []; + for (const source of sources) { + const exitCode = execute(settings, `${launcher} add ${quote(source)} --skill "*"${agentArguments(settings)} -y`); + if (exitCode !== 0) { + report("PRSKL0008", `Agent skills: re-adding '${source}' failed with exit code ${exitCode}.`); + failures.push(source); + } + } + + if (settings.dryRun) info(`Agent skills: dry run, ${sources.length} source(s), nothing changed.`); + else if (failures.length === 0) info(`Agent skills: ${sources.length} source(s) refreshed.`); +} + +function pathExists(path) { + // lstat does not follow a link, so a dangling one still counts as present. + try { + return lstatSync(path, { throwIfNoEntry: false }) !== undefined; + } catch { + return false; + } +} + +// Removes a link and never its target: unlink on Unix, and on Windows the directory form for a +// directory symlink or junction. +function deleteLink(path) { + try { + unlinkSync(path); + } catch { + rmdirSync(path); + } +} + +// When agents are selected, the only agent skill directories allowed are theirs, plus '.agents/skills', +// the CLI's canonical store that every agent directory links into. With fix set, the CLI's links are +// removed - a link only, never its target - and folders left empty go too. A real file is not provably +// the CLI's, so it is kept and reported. +function enforceDirectories(settings, fix) { + if (settings.agents.length === 0) { + info( + "Agent skills: no agents are selected, so the skills CLI auto-detects agents and every agent skill directory is expected. " + + `Set Skills.Agents in ${relative(settings.root, settings.configPath).replace(/\\/g, "/")} (or pass --agents) to enforce a layout.`, + ); + return; + } + + // '*' is every agent, so every directory is allowed. + if (settings.agents.includes("*")) return; + + const windows = process.platform === "win32"; + const key = (path) => (windows ? path.toLowerCase() : path); + const selected = settings.agents.map((agent) => agent.toLowerCase()); + const root = resolve(settings.root); + const toRelative = (path) => relative(root, path).replace(/\\/g, "/"); + + const directories = settings.agentDirectories + .map((entry) => ({ path: entry.path.replace(/\\/g, "/").replace(/^\/+|\/+$/g, ""), agents: entry.agents })) + .filter((entry) => entry.path.length > 0); + + const known = new Set(directories.flatMap((entry) => entry.agents.map((agent) => agent.toLowerCase()))); + for (const agent of settings.agents.filter((agent) => !known.has(agent.toLowerCase()))) + warn( + "PRSKL0016", + `Agent skills: '${agent}' is selected but has no known skills directory, so none is allowed for it. ` + + `Add it to Skills.AgentDirectories in ${toRelative(settings.configPath)} if the skills CLI supports it.`, + ); + + const allowed = new Set([key(".agents/skills")]); + for (const entry of directories) { + if (entry.agents.some((agent) => selected.includes(agent.toLowerCase()))) allowed.add(key(entry.path)); + } + + const protectedPaths = new Set([key(resolve(root, "skills"))]); + + const grouped = new Map(); + for (const entry of directories.filter((candidate) => !allowed.has(key(candidate.path)))) { + const existing = grouped.get(key(entry.path)); + if (existing === undefined) grouped.set(key(entry.path), { path: entry.path, agents: [...entry.agents] }); + else existing.agents.push(...entry.agents); + } + + const removed = []; + let violations = 0; + const kept = []; + + const prune = (path) => { + const stats = lstatSync(path); + if (stats.isSymbolicLink()) { + deleteLink(path); + removed.push(toRelative(path)); + return; + } + + if (!stats.isDirectory()) { + kept.push(toRelative(path)); + return; + } + + for (const child of readdirSync(path).sort()) prune(join(path, child)); + + if (readdirSync(path).length === 0) { + rmdirSync(path); + removed.push(toRelative(path)); + } + }; + + const ordered = [...grouped.values()].sort((left, right) => + left.path < right.path ? -1 : left.path > right.path ? 1 : 0, + ); + + for (const directory of ordered) { + const full = resolve(root, directory.path); + if (protectedPaths.has(key(full)) || !pathExists(full)) continue; + + kept.length = 0; + + // A dry run changes nothing, so it names what fix would clean up and leaves the outcome open. + if (fix && settings.dryRun) { + info( + `Agent skills (dry run): would remove the skills CLI's links from '${directory.path}', ` + + `the skills directory for ${directory.agents.join(", ")}, which the selected agents do not include.`, + ); + continue; + } + + if (fix) { + prune(full); + + // A folder that only ever held the agent's skills is left empty; remove it too, but never + // climb to the repository root. + let parent = dirname(full); + while ( + !pathExists(full) && + parent.length > root.length && + existsSync(parent) && + readdirSync(parent).length === 0 + ) { + rmdirSync(parent); + removed.push(toRelative(parent)); + parent = dirname(parent); + } + + if (!pathExists(full)) continue; + } + + violations++; + const agents = directory.agents.join(", "); + if (fix) { + // The CLI copies rather than links for some agent selections, so a kept folder can hold every + // file of every skill: name enough to recognise, then count the rest. + const sample = kept.slice(0, 5).join(", ") + (kept.length > 5 ? ` and ${kept.length - 5} more` : ""); + report( + "PRSKL0015", + `Agent skills: '${directory.path}' is the skills directory for ${agents}, which the selected agents (${settings.agents.join(", ")}) do not include, ` + + `and still holds content the skills CLI did not create: ${sample}. Remove it by hand.`, + ); + } else { + report( + "PRSKL0015", + `Agent skills: '${directory.path}' is the skills directory for ${agents}, which the selected agents (${settings.agents.join(", ")}) do not include. ` + + "Remove it with: just skills-fix", + ); + } + } + + for (const path of removed) info(`Agent skills: removed ${path}`); + + if (fix && settings.dryRun) info("Agent skills: dry run, nothing removed."); + else if (violations === 0) + info( + fix + ? `Agent skills: ${removed.length} path(s) removed; only the directories for ${settings.agents.join(", ")} exist.` + : `Agent skills: only the directories for ${settings.agents.join(", ")} exist.`, + ); +} + +function main(argv) { + const { values, positionals } = parseArgs({ + args: argv, + allowPositionals: true, + options: { + root: { type: "string" }, + config: { type: "string" }, + agents: { type: "string" }, + runner: { type: "string" }, + command: { type: "string" }, + package: { type: "string" }, + "lock-file": { type: "string" }, + "dry-run": { type: "boolean" }, + help: { type: "boolean", short: "h" }, + }, + }); + + const [command, ...rest] = positionals; + if (values.help === true || command === undefined || command === "help") { + info(usage); + return command === undefined && values.help !== true ? 1 : 0; + } + + const settings = resolveSettings(values); + + switch (command) { + case "add": + if (rest[0] === undefined) throw new SkillsError("PRSKL0007 'add' needs a source, for example: add purview-dev/build-sdk"); + addSource(settings, rest[0]); + break; + case "install": + install(settings, rest[0]); + break; + case "update": + update(settings); + break; + case "check": + enforceDirectories(settings, false); + break; + case "fix": + enforceDirectories(settings, true); + break; + default: + console.error(`Unknown command '${command}'.`); + info(usage); + return 1; + } + + return failed ? 1 : 0; +} + +try { + process.exitCode = main(process.argv.slice(2)); +} catch (exception) { + if (exception instanceof SkillsError) { + const match = /^(PRSKL\d{4}) ([\s\S]*)$/.exec(exception.message); + if (match === null) report("PRSKL0018", exception.message); + else report(match[1] ?? "", match[2] ?? ""); + } else { + console.error((exception).message); + } + + process.exitCode = 1; +} diff --git a/.build/just/skills.mts b/.build/just/skills.mts new file mode 100644 index 0000000..9e85a86 --- /dev/null +++ b/.build/just/skills.mts @@ -0,0 +1,700 @@ +// The Purview.BuildSdk agent-skill commands: a thin wrapper over the standard skills CLI +// (`bun x skills@1` by default), run by the skills-* recipes in skills.just. +// +// Nothing here needs .NET. There is no solution to evaluate, no package to restore and no project +// that has to build, so a repository whose build is broken can still install the skills that might +// help fix it. +// +// add skills add "" --skill "*" - append '#' to the source to pin it +// install [source] add , or restore skills-lock.json with skills experimental_install +// update re-add every unique skills-lock.json source at its latest, with every skill +// check fail when a skill directory exists for an agent that is not selected +// fix remove the skills CLI's links from those directories +// +// Settings, highest first: command-line options, PURVIEW_SKILLS_* environment variables, the +// "Skills" section of .config/purview-build-sdk.json, then the defaults below. Every command runs +// from the repository root, because skills-lock.json and the agent directories belong to the +// repository rather than to a project. +// +// skills.mts is the source. skills.mjs is generated from it by Node's own type stripper, for a +// machine with Node but neither Bun nor Deno: edit this file, then run `just skills-script-sync`. +// Keep to erasable TypeScript (no enums, namespaces or parameter properties) so both stay possible. + +import { spawnSync } from "node:child_process"; +import { existsSync, lstatSync, readdirSync, readFileSync, rmdirSync, statSync, unlinkSync } from "node:fs"; +import { delimiter, dirname, join, relative, resolve } from "node:path"; +import process from "node:process"; +import { parseArgs } from "node:util"; + +type AgentDirectory = { path: string; agents: string[] }; + +type Settings = { + root: string; + configPath: string; + agents: string[]; + runner: string; + runnerCandidates: string[]; + packageSpec: string; + command: string; + lockFile: string; + dryRun: boolean; + agentDirectories: AgentDirectory[]; +}; + +type ConfigSection = Record; + +const configKeys: string[] = [ + "Agents", + "Runner", + "RunnerCandidates", + "Package", + "Command", + "LockFile", + "DryRun", + "AgentDirectories", +]; + +// Each package runner spells "run this npm package" its own way. Every form was checked against the +// real tool, because a wrong one is a command that simply does not run. A runner missing from this +// table still works: it falls through to ' ', the form most new runners adopt. +const launchers: Record string> = { + skills: () => "skills", + npx: (spec: string) => `npx -y ${spec}`, + bunx: (spec: string) => `bunx ${spec}`, + bun: (spec: string) => `bun x ${spec}`, + pnpm: (spec: string) => `pnpm dlx ${spec}`, + yarn: (spec: string) => `yarn dlx ${spec}`, + deno: (spec: string) => `deno run -A npm:${spec}`, +}; + +// Where the skills CLI writes a project-scope install for each agent, from its own agent table +// (skills 1.7.6, docs/agents.md). Only check and fix read this, and only when agents are selected. +// The CLI adds agents independently of this script; add one through Skills.AgentDirectories in +// .config/purview-build-sdk.json rather than waiting for a release. +const defaultAgentDirectories: AgentDirectory[] = [ + { + path: ".agents/skills", + agents: [ + "amp", + "antigravity", + "antigravity-cli", + "cline", + "codex", + "cursor", + "deepagents", + "dexto", + "droid", + "firebender", + "fx", + "gemini-cli", + "github-copilot", + "kilo", + "kimi-code-cli", + "loaf", + "opencode", + "pi", + "promptscript", + "replit", + "sarvam-code", + "universal", + "warp", + "zed", + ], + }, + { path: ".adal/skills", agents: ["adal"] }, + { path: ".aider-desk/skills", agents: ["aider-desk"] }, + { path: ".augment/skills", agents: ["augment"] }, + { path: ".autohand/skills", agents: ["autohand-code"] }, + { path: ".bob/skills", agents: ["bob"] }, + { path: ".claude/skills", agents: ["claude-code"] }, + { path: ".codeartsdoer/skills", agents: ["codearts-agent"] }, + { path: ".codebuddy/skills", agents: ["codebuddy"] }, + { path: ".codemaker/skills", agents: ["codemaker"] }, + { path: ".codestudio/skills", agents: ["codestudio"] }, + { path: ".commandcode/skills", agents: ["command-code"] }, + { path: ".continue/skills", agents: ["continue"] }, + { path: ".cortex/skills", agents: ["cortex"] }, + { path: ".crush/skills", agents: ["crush"] }, + { path: ".devin/skills", agents: ["devin"] }, + { path: ".forge/skills", agents: ["forgecode"] }, + { path: ".goose/skills", agents: ["goose"] }, + { path: ".grok/skills", agents: ["grok"] }, + { path: ".hermes/skills", agents: ["hermes-agent"] }, + { path: ".iflow/skills", agents: ["iflow-cli"] }, + { path: ".inferencesh/skills", agents: ["inference-sh"] }, + { path: ".jazz/skills", agents: ["jazz"] }, + { path: ".junie/skills", agents: ["junie"] }, + { path: ".kimchi/skills", agents: ["kimchi"] }, + { path: ".kiro/skills", agents: ["kiro-cli"] }, + { path: ".kode/skills", agents: ["kode"] }, + { path: ".lingma/skills", agents: ["lingma"] }, + { path: ".mcpjam/skills", agents: ["mcpjam"] }, + { path: ".minimax/skills", agents: ["minimax-code"] }, + { path: ".moxby/skills", agents: ["moxby"] }, + { path: ".mux/skills", agents: ["mux"] }, + { path: ".neovate/skills", agents: ["neovate"] }, + { path: ".ona/skills", agents: ["ona"] }, + { path: ".openhands/skills", agents: ["openhands"] }, + { path: ".pochi/skills", agents: ["pochi"] }, + { path: ".posit/assistant/skills", agents: ["posit-assistant"] }, + { path: ".qoder/skills", agents: ["qoder", "qoder-cn"] }, + { path: ".qwen/skills", agents: ["qwen-code"] }, + { path: ".reasonix/skills", agents: ["reasonix"] }, + { path: ".roo/skills", agents: ["roo"] }, + { path: ".rovodev/skills", agents: ["rovodev"] }, + { path: ".tabnine/agent/skills", agents: ["tabnine-cli"] }, + { path: ".terramind/skills", agents: ["terramind"] }, + { path: ".tinycloud/skills", agents: ["tinycloud"] }, + { path: ".trae/skills", agents: ["trae", "trae-cn"] }, + { path: ".vibe/skills", agents: ["mistral-vibe"] }, + { path: ".windsurf/skills", agents: ["windsurf"] }, + { path: ".zcode/skills", agents: ["zcode"] }, + { path: ".zencoder/skills", agents: ["zencoder", "zenflow"] }, + { path: "agent/skills", agents: ["eve"] }, + { path: "data/skills", agents: ["astrbot"] }, + // openclaw installs into a root 'skills/', the folder a repository authors its own skills in. It is + // listed so selecting openclaw is not an unknown agent, but the authored folder is never touched. + { path: "skills", agents: ["openclaw"] }, +]; + +const usage: string = `Usage: skills.mts [options] + +Commands: + add Install every skill a source has (append '#' to pin it) + install [source] Install from a source, or restore skills-lock.json + update Re-add every skills-lock.json source at its latest + check Fail when a skill directory exists for an unselected agent + fix Remove the skills CLI's links from those directories + +Options: + --root Repository root (default: the nearest folder holding .git) + --config Settings file (default: .config/purview-build-sdk.json) + --agents Agents to install to, separated by ',', ';' or spaces + --runner Package runner: bun, npx, bunx, pnpm, yarn, deno or skills + --command Launch the skills CLI with this command instead + --package Package the launcher runs (default: skills@1) + --lock-file skills-lock.json location (default: the repository root) + --dry-run Print the skills CLI commands without running them +`; + +class SkillsError extends Error {} + +let failed = false; + +function report(code: string, message: string): void { + console.error(`error ${code}: ${message}`); + failed = true; +} + +function warn(code: string, message: string): void { + console.error(`warning ${code}: ${message}`); +} + +function info(message: string): void { + console.log(message); +} + +function environment(name: string): string | undefined { + const value = process.env[name]; + return value === undefined || value.trim() === "" ? undefined : value.trim(); +} + +function splitList(value: string): string[] { + return value + .replace(/^[\s,;"']+|[\s,;"']+$/g, "") + .split(/[\s,;]+/) + .filter((entry: string) => entry.length > 0); +} + +function quote(value: string): string { + if (value.includes('"')) throw new SkillsError(`'${value}' contains a double quote, which cannot be passed safely.`); + return `"${value}"`; +} + +function unique(values: string[]): string[] { + const seen: Set = new Set(); + return values.filter((value: string) => { + const key = value.toLowerCase(); + if (seen.has(key)) return false; + seen.add(key); + return true; + }); +} + +// The nearest ancestor holding '.git' - a directory in a clone, a file in a worktree or a submodule. +// The recipes always pass --root; this only matters when the script is run by hand. +function findRepositoryRoot(start: string): string { + for (let directory = resolve(start); ; directory = dirname(directory)) { + if (existsSync(join(directory, ".git"))) return directory; + if (dirname(directory) === directory) return resolve(start); + } +} + +function readConfig(configPath: string): ConfigSection { + if (!existsSync(configPath)) return {}; + + let document: unknown; + try { + document = JSON.parse(readFileSync(configPath, "utf8")); + } catch (exception) { + throw new SkillsError(`PRSKL0018 '${configPath}' is not valid JSON: ${(exception as Error).message}`); + } + + const section = (document as Record | null)?.["Skills"]; + if (section === undefined) return {}; + if (section === null || typeof section !== "object" || Array.isArray(section)) + throw new SkillsError(`PRSKL0018 '${configPath}': "Skills" must be an object.`); + + for (const key of Object.keys(section)) { + if (!configKeys.includes(key)) + warn("PRSKL0019", `'${configPath}': "Skills.${key}" is not a setting and is ignored. Known: ${configKeys.join(", ")}.`); + } + + return section as ConfigSection; +} + +function configString(config: ConfigSection, key: string, configPath: string): string | undefined { + const value = config[key]; + if (value === undefined || value === null) return undefined; + if (typeof value !== "string") throw new SkillsError(`PRSKL0018 '${configPath}': "Skills.${key}" must be a string.`); + return value.trim() === "" ? undefined : value.trim(); +} + +function configList(config: ConfigSection, key: string, configPath: string): string[] | undefined { + const value = config[key]; + if (value === undefined || value === null) return undefined; + if (typeof value === "string") return splitList(value); + if (Array.isArray(value) && value.every((entry: unknown) => typeof entry === "string")) + return value.flatMap((entry: string) => splitList(entry)); + throw new SkillsError(`PRSKL0018 '${configPath}': "Skills.${key}" must be a string or an array of strings.`); +} + +function configBoolean(config: ConfigSection, key: string, configPath: string): boolean | undefined { + const value = config[key]; + if (value === undefined || value === null) return undefined; + if (typeof value !== "boolean") throw new SkillsError(`PRSKL0018 '${configPath}': "Skills.${key}" must be true or false.`); + return value; +} + +function configAgentDirectories(config: ConfigSection, configPath: string): AgentDirectory[] { + const value = config["AgentDirectories"]; + if (value === undefined || value === null) return []; + if (typeof value !== "object" || Array.isArray(value)) + throw new SkillsError(`PRSKL0018 '${configPath}': "Skills.AgentDirectories" must map a directory to its agents.`); + + return Object.entries(value as Record).map(([path, agents]: [string, unknown]) => { + if (typeof agents === "string") return { path, agents: splitList(agents) }; + if (Array.isArray(agents) && agents.every((entry: unknown) => typeof entry === "string")) + return { path, agents: agents as string[] }; + throw new SkillsError(`PRSKL0018 '${configPath}': "Skills.AgentDirectories.${path}" must be a string or an array of strings.`); + }); +} + +function parseBoolean(value: string | undefined): boolean | undefined { + if (value === undefined) return undefined; + return ["1", "true", "yes", "on"].includes(value.toLowerCase()); +} + +function resolveSettings(values: Record): Settings { + const option = (name: string): string | undefined => { + const value = values[name]; + return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined; + }; + + const root = resolve(option("root") ?? findRepositoryRoot(process.cwd())); + const configPath = resolve(root, option("config") ?? environment("PURVIEW_SKILLS_CONFIG") ?? ".config/purview-build-sdk.json"); + const config = readConfig(configPath); + + const agents = option("agents") ?? environment("PURVIEW_SKILLS_AGENTS"); + const candidates = environment("PURVIEW_SKILLS_RUNNER_CANDIDATES"); + const lockFile = option("lock-file") ?? environment("PURVIEW_SKILLS_LOCK_FILE") ?? configString(config, "LockFile", configPath); + + return { + root, + configPath, + agents: agents !== undefined ? splitList(agents) : (configList(config, "Agents", configPath) ?? []), + runner: option("runner") ?? environment("PURVIEW_SKILLS_RUNNER") ?? configString(config, "Runner", configPath) ?? "bun", + runnerCandidates: + candidates !== undefined + ? splitList(candidates) + : (configList(config, "RunnerCandidates", configPath) ?? ["bun", "npx", "bunx", "pnpm", "yarn", "deno"]), + packageSpec: + option("package") ?? environment("PURVIEW_SKILLS_PACKAGE") ?? configString(config, "Package", configPath) ?? "skills@1", + command: option("command") ?? environment("PURVIEW_SKILLS_COMMAND") ?? configString(config, "Command", configPath) ?? "", + lockFile: resolve(root, lockFile ?? "skills-lock.json"), + dryRun: + values["dry-run"] === true || + (parseBoolean(environment("PURVIEW_SKILLS_DRY_RUN")) ?? configBoolean(config, "DryRun", configPath) ?? false), + agentDirectories: [...defaultAgentDirectories, ...configAgentDirectories(config, configPath)], + }; +} + +function launcherFor(runner: string, spec: string): string { + const launcher = launchers[runner]; + return launcher === undefined ? `${runner} ${spec}` : launcher(spec); +} + +// PATH is probed directly rather than by starting a version check: no process, nothing to download, +// nothing to hang. PATHEXT is honoured on Windows, where these commands are .cmd shims. +function findOnPath(names: string[]): { name: string; path: string } | undefined { + const windows = process.platform === "win32"; + const extensions = windows ? ["", ...(environment("PATHEXT") ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)] : [""]; + const directories = (process.env["PATH"] ?? "") + .split(delimiter) + .map((entry: string) => entry.trim().replace(/^"|"$/g, "")) + .filter((entry: string) => entry.length > 0); + + for (const name of names) { + for (const directory of directories) { + for (const extension of extensions) { + const candidate = join(directory, name + extension); + try { + if (statSync(candidate).isFile()) return { name, path: candidate }; + } catch { + // Not here; a malformed PATH entry must not stop the probe either. + } + } + } + } + + return undefined; +} + +// 'skills' already on PATH is tried first because it needs no download, then the configured runner, +// then the other candidates - so a machine with Node but no Bun still installs. +function resolveLauncher(settings: Settings): string { + if (settings.command !== "") return settings.command; + + const found = findOnPath(unique(["skills", settings.runner, ...settings.runnerCandidates])); + if (found !== undefined) { + const launcher = launcherFor(found.name, settings.packageSpec); + info(`Using the skills CLI via '${launcher}' (${found.path}).`); + return launcher; + } + + // A dry run runs nothing, so it works on a machine with no runner at all. + if (settings.dryRun) return launcherFor(settings.runner, settings.packageSpec); + + throw new SkillsError( + `PRSKL0004 Cannot run the skills CLI: none of ${unique(["skills", settings.runner, ...settings.runnerCandidates]).join(", ")} was found on PATH. ` + + "Install Bun (which provides 'bun x') or Node.js (which provides npx), or any of pnpm, yarn or deno, " + + "or install the CLI globally with 'npm install -g skills'. Choose a runner with --runner or Skills.Runner; " + + "replace the launcher entirely with --command or Skills.Command.", + ); +} + +function agentArguments(settings: Settings): string { + // The CLI does not split a comma-separated --agent, so each agent gets its own flag. + return settings.agents.map((agent: string) => ` --agent ${quote(agent)}`).join(""); +} + +function execute(settings: Settings, commandLine: string): number { + info(settings.dryRun ? `Agent skills (dry run): ${commandLine}` : `Agent skills: ${commandLine}`); + if (settings.dryRun) return 0; + + const result = spawnSync(commandLine, { cwd: settings.root, shell: true, stdio: "inherit" }); + if (result.error !== undefined) { + console.error(result.error.message); + return 1; + } + + return result.status ?? 1; +} + +function addSource(settings: Settings, source: string): void { + const launcher = resolveLauncher(settings); + // '-y' keeps 'add' non-interactive. '*' is every skill the source has, and a re-run is safe: the + // CLI reinstalls each skill it is given, replacing the installed copy. + const exitCode = execute(settings, `${launcher} add ${quote(source)} --skill "*"${agentArguments(settings)} -y`); + if (exitCode !== 0) report("PRSKL0008", `Agent skills: adding '${source}' failed with exit code ${exitCode}.`); +} + +function install(settings: Settings, source: string | undefined): void { + if (source !== undefined) { + addSource(settings, source); + return; + } + + if (!existsSync(settings.lockFile)) + throw new SkillsError( + `PRSKL0007 Nothing to install: no source was given, and '${settings.lockFile}' does not exist to restore from. ` + + "Install from a source first, for example: just skills-add purview-dev/build-sdk", + ); + + const exitCode = execute(settings, `${resolveLauncher(settings)} experimental_install`); + if (exitCode !== 0) report("PRSKL0008", `Agent skills: restoring '${settings.lockFile}' failed with exit code ${exitCode}.`); +} + +function readLockSources(lockFile: string): string[] { + let document: unknown; + try { + document = JSON.parse(readFileSync(lockFile, "utf8")); + } catch (exception) { + throw new SkillsError(`PRSKL0007 Cannot read '${lockFile}': ${(exception as Error).message}`); + } + + const skills = (document as { skills?: Record } | null)?.skills ?? {}; + const sources = Object.values(skills) + .map((entry: { source?: unknown }) => (typeof entry?.source === "string" ? entry.source.trim() : "")) + .filter((source: string) => source.length > 0); + + return unique(sources).sort((left: string, right: string) => left.toLowerCase().localeCompare(right.toLowerCase())); +} + +// Update is 'add', never 'skills update'. 'skills add' reinstalls every skill it selects, so one +// re-add of each source, with every skill it has, both refreshes what is installed and brings in +// anything the source has gained. The lockfile's own skill names are deliberately not reused: naming +// them would leave out a skill added since. Every source is attempted even when one fails. +function update(settings: Settings): void { + if (!existsSync(settings.lockFile)) + throw new SkillsError( + `PRSKL0007 Cannot update agent skills: '${settings.lockFile}' does not exist. ` + + "Update re-adds the sources the skills CLI recorded there; install skills first with: just skills-add ", + ); + + const sources = readLockSources(settings.lockFile); + if (sources.length === 0) { + info(`Agent skills: no sources recorded in ${settings.lockFile}.`); + return; + } + + const launcher = resolveLauncher(settings); + const failures: string[] = []; + for (const source of sources) { + const exitCode = execute(settings, `${launcher} add ${quote(source)} --skill "*"${agentArguments(settings)} -y`); + if (exitCode !== 0) { + report("PRSKL0008", `Agent skills: re-adding '${source}' failed with exit code ${exitCode}.`); + failures.push(source); + } + } + + if (settings.dryRun) info(`Agent skills: dry run, ${sources.length} source(s), nothing changed.`); + else if (failures.length === 0) info(`Agent skills: ${sources.length} source(s) refreshed.`); +} + +function pathExists(path: string): boolean { + // lstat does not follow a link, so a dangling one still counts as present. + try { + return lstatSync(path, { throwIfNoEntry: false }) !== undefined; + } catch { + return false; + } +} + +// Removes a link and never its target: unlink on Unix, and on Windows the directory form for a +// directory symlink or junction. +function deleteLink(path: string): void { + try { + unlinkSync(path); + } catch { + rmdirSync(path); + } +} + +// When agents are selected, the only agent skill directories allowed are theirs, plus '.agents/skills', +// the CLI's canonical store that every agent directory links into. With fix set, the CLI's links are +// removed - a link only, never its target - and folders left empty go too. A real file is not provably +// the CLI's, so it is kept and reported. +function enforceDirectories(settings: Settings, fix: boolean): void { + if (settings.agents.length === 0) { + info( + "Agent skills: no agents are selected, so the skills CLI auto-detects agents and every agent skill directory is expected. " + + `Set Skills.Agents in ${relative(settings.root, settings.configPath).replace(/\\/g, "/")} (or pass --agents) to enforce a layout.`, + ); + return; + } + + // '*' is every agent, so every directory is allowed. + if (settings.agents.includes("*")) return; + + const windows = process.platform === "win32"; + const key = (path: string): string => (windows ? path.toLowerCase() : path); + const selected = settings.agents.map((agent: string) => agent.toLowerCase()); + const root = resolve(settings.root); + const toRelative = (path: string): string => relative(root, path).replace(/\\/g, "/"); + + const directories = settings.agentDirectories + .map((entry: AgentDirectory) => ({ path: entry.path.replace(/\\/g, "/").replace(/^\/+|\/+$/g, ""), agents: entry.agents })) + .filter((entry: AgentDirectory) => entry.path.length > 0); + + const known: Set = new Set(directories.flatMap((entry: AgentDirectory) => entry.agents.map((agent: string) => agent.toLowerCase()))); + for (const agent of settings.agents.filter((agent: string) => !known.has(agent.toLowerCase()))) + warn( + "PRSKL0016", + `Agent skills: '${agent}' is selected but has no known skills directory, so none is allowed for it. ` + + `Add it to Skills.AgentDirectories in ${toRelative(settings.configPath)} if the skills CLI supports it.`, + ); + + const allowed: Set = new Set([key(".agents/skills")]); + for (const entry of directories) { + if (entry.agents.some((agent: string) => selected.includes(agent.toLowerCase()))) allowed.add(key(entry.path)); + } + + const protectedPaths: Set = new Set([key(resolve(root, "skills"))]); + + const grouped: Map = new Map(); + for (const entry of directories.filter((candidate: AgentDirectory) => !allowed.has(key(candidate.path)))) { + const existing = grouped.get(key(entry.path)); + if (existing === undefined) grouped.set(key(entry.path), { path: entry.path, agents: [...entry.agents] }); + else existing.agents.push(...entry.agents); + } + + const removed: string[] = []; + let violations = 0; + const kept: string[] = []; + + const prune = (path: string): void => { + const stats = lstatSync(path); + if (stats.isSymbolicLink()) { + deleteLink(path); + removed.push(toRelative(path)); + return; + } + + if (!stats.isDirectory()) { + kept.push(toRelative(path)); + return; + } + + for (const child of readdirSync(path).sort()) prune(join(path, child)); + + if (readdirSync(path).length === 0) { + rmdirSync(path); + removed.push(toRelative(path)); + } + }; + + const ordered = [...grouped.values()].sort((left: AgentDirectory, right: AgentDirectory) => + left.path < right.path ? -1 : left.path > right.path ? 1 : 0, + ); + + for (const directory of ordered) { + const full = resolve(root, directory.path); + if (protectedPaths.has(key(full)) || !pathExists(full)) continue; + + kept.length = 0; + + // A dry run changes nothing, so it names what fix would clean up and leaves the outcome open. + if (fix && settings.dryRun) { + info( + `Agent skills (dry run): would remove the skills CLI's links from '${directory.path}', ` + + `the skills directory for ${directory.agents.join(", ")}, which the selected agents do not include.`, + ); + continue; + } + + if (fix) { + prune(full); + + // A folder that only ever held the agent's skills is left empty; remove it too, but never + // climb to the repository root. + let parent = dirname(full); + while ( + !pathExists(full) && + parent.length > root.length && + existsSync(parent) && + readdirSync(parent).length === 0 + ) { + rmdirSync(parent); + removed.push(toRelative(parent)); + parent = dirname(parent); + } + + if (!pathExists(full)) continue; + } + + violations++; + const agents = directory.agents.join(", "); + if (fix) { + // The CLI copies rather than links for some agent selections, so a kept folder can hold every + // file of every skill: name enough to recognise, then count the rest. + const sample = kept.slice(0, 5).join(", ") + (kept.length > 5 ? ` and ${kept.length - 5} more` : ""); + report( + "PRSKL0015", + `Agent skills: '${directory.path}' is the skills directory for ${agents}, which the selected agents (${settings.agents.join(", ")}) do not include, ` + + `and still holds content the skills CLI did not create: ${sample}. Remove it by hand.`, + ); + } else { + report( + "PRSKL0015", + `Agent skills: '${directory.path}' is the skills directory for ${agents}, which the selected agents (${settings.agents.join(", ")}) do not include. ` + + "Remove it with: just skills-fix", + ); + } + } + + for (const path of removed) info(`Agent skills: removed ${path}`); + + if (fix && settings.dryRun) info("Agent skills: dry run, nothing removed."); + else if (violations === 0) + info( + fix + ? `Agent skills: ${removed.length} path(s) removed; only the directories for ${settings.agents.join(", ")} exist.` + : `Agent skills: only the directories for ${settings.agents.join(", ")} exist.`, + ); +} + +function main(argv: string[]): number { + const { values, positionals } = parseArgs({ + args: argv, + allowPositionals: true, + options: { + root: { type: "string" }, + config: { type: "string" }, + agents: { type: "string" }, + runner: { type: "string" }, + command: { type: "string" }, + package: { type: "string" }, + "lock-file": { type: "string" }, + "dry-run": { type: "boolean" }, + help: { type: "boolean", short: "h" }, + }, + }); + + const [command, ...rest] = positionals; + if (values.help === true || command === undefined || command === "help") { + info(usage); + return command === undefined && values.help !== true ? 1 : 0; + } + + const settings = resolveSettings(values as Record); + + switch (command) { + case "add": + if (rest[0] === undefined) throw new SkillsError("PRSKL0007 'add' needs a source, for example: add purview-dev/build-sdk"); + addSource(settings, rest[0]); + break; + case "install": + install(settings, rest[0]); + break; + case "update": + update(settings); + break; + case "check": + enforceDirectories(settings, false); + break; + case "fix": + enforceDirectories(settings, true); + break; + default: + console.error(`Unknown command '${command}'.`); + info(usage); + return 1; + } + + return failed ? 1 : 0; +} + +try { + process.exitCode = main(process.argv.slice(2)); +} catch (exception) { + if (exception instanceof SkillsError) { + const match = /^(PRSKL\d{4}) ([\s\S]*)$/.exec(exception.message); + if (match === null) report("PRSKL0018", exception.message); + else report(match[1] ?? "", match[2] ?? ""); + } else { + console.error((exception as Error).message); + } + + process.exitCode = 1; +} diff --git a/.build/just/utilities.just b/.build/just/utilities.just new file mode 100644 index 0000000..d813497 --- /dev/null +++ b/.build/just/utilities.just @@ -0,0 +1,44 @@ +# Formatting, opening the solution, and scrubbing the build output. + +csharpier := "dotnet csharpier" + +# Check formatting with CSharpier +[group('Utilities')] +lint-check: + {{ csharpier }} check . + +# Format the code with CSharpier +[group('Utilities')] +lint-fix: + {{ csharpier }} format . + +# Open the solution in Visual Studio, or whichever application is registered for it +[group('Utilities')] +[windows] +vs: + start "" "{{ solution_file }}" + +# Open the solution in whichever application is registered for it +[group('Utilities')] +[macos] +vs: + open "{{ solution_file }}" + +# Open the solution in whichever application is registered for it +[group('Utilities')] +[linux] +vs: + xdg-open "{{ solution_file }}" + +# Delete every bin/, obj/ and artifacts_folder, stop the build servers, and restore from scratch +# +# The build servers go first: the MSBuild server and the compiler server hold files open under obj/, +# which on Windows stops them being deleted. node_modules/ and .git/ are never searched. +[doc('Delete every bin/, obj/ and artifacts_folder, stop the build servers, and restore from scratch')] +[group('Utilities')] +scrub: + echo "==> Scrubbing build output and stopping the build servers" + dotnet build-server shutdown + find . \( -name node_modules -o -name .git \) -prune -o -type d \( -name bin -o -name obj \) -prune -exec rm -rf {} + + rm -rf "{{ artifacts_folder }}" + just restore --force-evaluate diff --git a/.build/just/version.just b/.build/just/version.just new file mode 100644 index 0000000..09dbb37 --- /dev/null +++ b/.build/just/version.just @@ -0,0 +1,28 @@ +# The package version, from package.json: the single source of truth Purview.BuildSdk versions every +# project and package from. + +version_file := "package.json" + +# Read by just itself rather than by spawning bun, so `just --list` needs no Node tooling. +current_version := if path_exists(version_file) == "true" { replace_regex(read(version_file), '(?s).*?"version"\s*:\s*"([^"]*)".*', '$1') } else { "0.0.0" } + +# Display the current version, from package.json +[group('Version')] +version: + echo "==> Current version: {{ GREEN }}{{ current_version }}{{ NORMAL }} (from {{ version_file }}, stamped into every build by Purview.BuildSdk)" + +# Bump one part of the version in package.json - major, minor or patch - resetting the parts after it +# +# just bump minor # 2.0.1 -> 2.1.0 +# just bump patch --dry-run # print the new version, write nothing +# +# A pre-release suffix is dropped. Requires Bun. Afterwards it runs `_after-bump`, which does nothing +# unless the root Justfile overrides it to refresh whatever else pins the version. +[doc('Bump one part of the version in package.json - major, minor or patch - resetting the parts after it')] +[arg("part", pattern="major|minor|patch")] +[group('Version')] +bump part *args: && _after-bump + bun "{{ source_directory() / 'bump-version.ts' }}" "{{ part }}" "{{ version_file }}" {{ args }} + +# Runs after a successful `bump`. Override it in the root Justfile, e.g. `_after-bump: version-sync`. +_after-bump: diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index bc9bc27..ec846e1 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -10,14 +10,14 @@ "rollForward": false }, "dotnet-inspect": { - "version": "0.27.0", + "version": "0.28.0", "commands": [ "dotnet-inspect" ], "rollForward": false }, "purview.build": { - "version": "0.9.0", + "version": "0.9.2", "commands": [ "purview-build" ], diff --git a/.config/purview-build.json b/.config/purview-build.json index 3519bd8..a1ed7c0 100644 --- a/.config/purview-build.json +++ b/.config/purview-build.json @@ -66,7 +66,7 @@ // Purview.Containers.Wsl is multi-target: lib/net10.0 and lib/net11.0 are the portable facades // (net11.0 is compiled with runtime-async), and the *-windows10.0.19041 builds are the WSLC // implementations. A portable consumer loads the Windows implementation (plus the WSLC - // projection, its Windows SDK dependencies and the native SDK) from payload// via the + // projection, its Windows SDK dependencies and the native SDK) from payload/win-x64/ via the // buildTransitive targets; one payload serves both portable targets because a .NET 11 process // loads a .NET 10 assembly. "purview.containers.wsl": [ @@ -82,8 +82,8 @@ "purview-logo-light.png", "buildTransitive/Purview.Containers.Wsl.props", "buildTransitive/Purview.Containers.Wsl.targets", - "payload/win-x64/*", - "payload/win-arm64/*" + // x64 only: the backend does not support ARM64, so no win-arm64 payload is shipped. + "payload/win-x64/*" ], "purview.containers.azurekeyvaultemulator": [ "lib/$(TFM)/Purview.Containers.AzureKeyVaultEmulator.dll", diff --git a/.config/purview-docs.yml b/.config/purview-docs.yml index 083274c..b1ae5b7 100644 --- a/.config/purview-docs.yml +++ b/.config/purview-docs.yml @@ -14,9 +14,10 @@ description: >- WSL Containers (WSLC) with no Docker installation, or Docker through Testcontainers. Containers are created through backend-neutral abstractions (Purview.Containers.Core) and the backend is resolved at run time, so the same test code runs on WSLC (Purview.Containers.Wsl) or Docker - (Purview.Containers.Docker) unchanged. The WSLC backend talks to the WSLC managed C# API directly — - no wslc.exe, no docker CLI, no Docker.DotNet. - Typed service modules add PostgreSQL, Redis, SQL Server, MySQL, RabbitMQ, Azurite, and NATS, each + (Purview.Containers.Docker) unchanged. The WSLC backend uses the WSLC managed C# API directly, with a + bounded wslc CLI fallback only for the few features the SDK lacks — no docker CLI, no Docker.DotNet. + Typed service modules add PostgreSQL, Redis, SQL Server, MySQL, RabbitMQ, Azurite, NATS, and the Azure + Key Vault and Service Bus emulators, each with its own defaults, configuration, readiness wait strategy, and connection-string helper. The umbrella package Purview.Containers brings the abstractions plus both backends in a single reference. origin: >- @@ -30,20 +31,18 @@ useWhen: >- integration tests, and you want the same suite to run on WSL Containers on a Windows developer machine and on Docker in CI without changing a line of test code. avoidWhen: >- - You need a container runtime other than WSL Containers or Docker, or you require API stability: the - public API, defaults, and packaging rules can change between prereleases and there is no production - support guarantee. + You need a container runtime other than WSL Containers or Docker, or the WSL Containers backend on an + ARM64 machine: it supports x64 only (Docker works on any architecture). repository: purview-dev/containers category: developer-tooling status: preview -experimental: true +experimental: false order: 90 docs: source: github-path path: docs/wiki exclude: - _Sidebar.md - - Home.md targetFrameworks: - net10.0 - net10.0-windows10.0.19041.0 @@ -78,13 +77,20 @@ packages: description: Azurite module — defaults, account key, and Azure Storage connection string. - id: Purview.Containers.Nats description: NATS module — defaults, configuration, and client endpoint. -acknowledgments: + - id: Purview.Containers.AzureKeyVaultEmulator + description: Azure Key Vault emulator module — secrets, keys and certificates endpoints, and certificate-pinned Azure SDK clients. + - id: Purview.Containers.AzureServiceBusEmulator + description: Azure Service Bus emulator module — the emulator with its SQL Server sidecar, AMQP and management connection strings, and explicit licence acceptance. + - id: Purview.Containers.Environment + description: Standalone bind-sharing resolver for Docker-compatible CLI consumers — verifies native, WSL and shared-remote paths; no backend dependency. + - id: Purview.Containers.Aspire + description: Opt-in Aspire AppHost adapter that translates container bind sources with the Environment resolver.acknowledgments: - name: Testcontainers for .NET url: https://github.com/testcontainers/testcontainers-dotnet description: The Docker backend is driven by Testcontainers and the module connection-string shapes follow it; Purview.Containers is not affiliated with or endorsed by the Testcontainers project. - name: Microsoft WSL Containers url: https://www.nuget.org/packages/Microsoft.WSL.Containers - description: The managed C# API behind WSLC that the WSL Containers backend is built against directly, with no wslc.exe or docker CLI. + description: The managed C# API behind WSLC that the WSL Containers backend is built against directly, with a bounded wslc CLI fallback and no docker CLI. useCases: - audience: developer title: The same test on WSL Containers or Docker @@ -133,7 +139,8 @@ useCases: - audience: developer title: A typed service module instead of a bare image scenario: >- - You need a throwaway PostgreSQL (or Redis, SQL Server, MySQL, RabbitMQ, Azurite, NATS) and do not + You need a throwaway PostgreSQL (or Redis, SQL Server, MySQL, RabbitMQ, Azurite, NATS, or an Azure + emulator) and do not want to look up its image, port, environment, and readiness probe every time. code: | await using var postgres = new PostgreSqlBuilder() @@ -148,7 +155,8 @@ useCases: returns once the instance is genuinely ready, and GetConnectionString() points at the mapped host port — the same shape Testcontainers modules use. evidence: >- - Seven service modules ship (PostgreSQL, Redis, SQL Server, MySQL, RabbitMQ, Azurite, NATS), and a + Nine service modules ship (PostgreSQL, Redis, SQL Server, MySQL, RabbitMQ, Azurite, NATS, and the Azure + Key Vault and Service Bus emulators), and a module contributes only its image, ports, environment, wait strategy, and connection string — never the shared runtime. docsPage: modules @@ -169,13 +177,13 @@ useCases: which runtime a machine has before a test runs. evidence: >- Purview.Containers.Wsl ships a portable net10.0 facade and a net10.0-windows10.0.19041.0 - implementation, and the repository builds twenty-one throwaway consumer projects to prove the + implementation, and the repository builds twenty-eight throwaway consumer projects to prove the target-framework contract and the PCC0001/PCC0002 guards. docsPage: consumer-requirements - audience: contributor title: Add a service module scenario: >- - You want to add a module for another service, or fix one of the existing seven, and need to know + You want to add a module for another service, or fix one of the existing nine, and need to know exactly what a module is allowed to contribute. outcome: >- A module supplies only the default image, ports, environment, its own WithXxx configuration, a diff --git a/.editorconfig b/.editorconfig index a9b39cb..b0390ec 100644 --- a/.editorconfig +++ b/.editorconfig @@ -1,4 +1,4 @@ -# Purview.BuildSdk 2.0.0 - managed file, do not edit +# Purview.BuildSdk 2.2.0 - managed file, do not edit # # This file is written by Purview.BuildSdk and is replaced whenever the SDK version changes. The version # on the first line is how the SDK recognises a file it owns: a .editorconfig without that marker is diff --git a/.github/workflows/integration-wsl.yml b/.github/workflows/integration-wsl.yml index 0edcf7d..98c8655 100644 --- a/.github/workflows/integration-wsl.yml +++ b/.github/workflows/integration-wsl.yml @@ -1,7 +1,7 @@ name: Integration (WSL Containers) # The WSLC suites need Windows Server 2025 with nested virtualisation, which GitHub's `windows-2025` -# hosted runners provide. The pre-release WSL channel carries wslc and its directory is not on PATH. +# hosted runners provide. WSL Containers ships in the stable WSL channel (3.0.1 and later). # # Coverage: # - every pull request: the WSLC contract suite, from pr.yml's `integration-wsl` job (fast) @@ -9,7 +9,7 @@ name: Integration (WSL Containers) # - manually: either the hosted matrix or a self-hosted Windows runner carrying the custom `wslc` # label (useful when a warm image store matters), selected with the `runner` input # -# Runner prerequisites are documented in docs/wiki/Testing.md. +# Runner prerequisites are documented in docs/wiki/contributing/Testing.md. on: workflow_dispatch: inputs: @@ -54,12 +54,12 @@ jobs: PURVIEW_CONTAINERS_REQUIRE_BACKEND: wsl WSL_UTF8: "1" steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v7 with: ref: ${{ inputs.ref || github.ref }} - name: Set up .NET - uses: actions/setup-dotnet@v4 + uses: actions/setup-dotnet@v6 with: # Keep in sync with `sdk.version` in global.json (and the other workflows). dotnet-version: "11.0.100" @@ -67,18 +67,22 @@ jobs: - name: Install WSL Containers shell: pwsh run: | - wsl --update --pre-release + # WSL Containers is generally available in the stable WSL channel (WSL 3.0.1 and later), so this + # installs exactly what a consumer gets. The backend's floor is MinimumWslVersion, which follows + # MicrosoftWSLContainersVersion in Directory.Packages.props; read it from there so the two + # cannot drift. + wsl --update + wsl --version $wslc = 'C:\Program Files\WSL\wslc.exe' if (-not (Test-Path $wslc)) { - # The feature reached GA in some channels; fall back to the stable update before failing. - wsl --update + throw "wslc.exe was not installed at $wslc; the runner did not get a WSL build with containers." } - wsl --version - if (-not (Test-Path $wslc)) { - throw "wslc.exe was not installed at $wslc; the hosted runner did not get a WSL build with containers." + $minimum = [version](Select-Xml -Path Directory.Packages.props -XPath '//MicrosoftWSLContainersVersion').Node.InnerText + $installed = [version]((& $wslc version) -replace '^wslc\s+', '') + if ($installed -lt $minimum) { + throw "WSL $installed is older than $minimum, the minimum Purview.Containers.Wsl supports." } - $env:PATH = "C:\Program Files\WSL;$env:PATH" - & $wslc version + Write-Host "wslc $installed (minimum $minimum)" - name: Restore run: dotnet restore src/Containers.slnx @@ -136,12 +140,12 @@ jobs: PURVIEW_CONTAINERS_REQUIRE_BACKEND: wsl WSL_UTF8: "1" steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v7 with: ref: ${{ inputs.ref || github.ref }} - name: Set up .NET - uses: actions/setup-dotnet@v4 + uses: actions/setup-dotnet@v6 with: # Keep in sync with `sdk.version` in global.json (and the other workflows). dotnet-version: "11.0.100" diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml index c83922a..758dd3b 100644 --- a/.github/workflows/pr.yml +++ b/.github/workflows/pr.yml @@ -6,10 +6,15 @@ on: # `ready_for_review` is not one of the default activity types, so a draft PR would never # re-evaluate the required build gate once it is marked ready for review. types: [opened, synchronize, reopened, ready_for_review] + # Every merge to main is built and tested too, so main's own status reflects what was merged rather + # than the last PR head. This never publishes: releases still come only from release/** (release.yml). + push: + branches: [main] concurrency: group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true + # A newer push to a PR supersedes the older run; on main every merge gets its own complete run. + cancel-in-progress: ${{ github.event_name == 'pull_request' }} jobs: build: @@ -43,8 +48,8 @@ jobs: PURVIEW_CONTAINERS_BACKEND: docker PURVIEW_CONTAINERS_REQUIRE_BACKEND: docker steps: - - uses: actions/checkout@v4 - - uses: actions/setup-dotnet@v4 + - uses: actions/checkout@v7 + - uses: actions/setup-dotnet@v6 with: # Keep in sync with `sdk.version` in global.json. dotnet-version: "11.0.100" @@ -56,7 +61,7 @@ jobs: run: dotnet test src/tests/Modules.Docker.IntegrationTests/Modules.Docker.IntegrationTests.csproj --configuration Release --treenode-filter '/*/*/*/*' --timeout 15m --retry-failed-tests 2 --retry-failed-tests-delay 5s --retry-failed-tests-max-percentage 50 # WSLC needs a Windows host with nested virtualisation. windows-2025 provides it (Windows Server - # 2025); wslc ships in the pre-release WSL channel and its directory is not on PATH. This is the + # 2025); wslc ships in the stable WSL channel (3.0.1 and later). This is the # contract suite only: the full module matrix is too slow for every pull request and runs in the # nightly integration-wsl workflow instead. integration-wsl: @@ -68,26 +73,30 @@ jobs: PURVIEW_CONTAINERS_REQUIRE_BACKEND: wsl WSL_UTF8: "1" steps: - - uses: actions/checkout@v4 - - uses: actions/setup-dotnet@v4 + - uses: actions/checkout@v7 + - uses: actions/setup-dotnet@v6 with: # Keep in sync with `sdk.version` in global.json. dotnet-version: "11.0.100" - name: Install WSL Containers shell: pwsh run: | - wsl --update --pre-release + # WSL Containers is generally available in the stable WSL channel (WSL 3.0.1 and later), so this + # installs exactly what a consumer gets. The backend's floor is MinimumWslVersion, which follows + # MicrosoftWSLContainersVersion in Directory.Packages.props; read it from there so the two + # cannot drift. + wsl --update + wsl --version $wslc = 'C:\Program Files\WSL\wslc.exe' if (-not (Test-Path $wslc)) { - # The feature reached GA in some channels; fall back to the stable update before failing. - wsl --update + throw "wslc.exe was not installed at $wslc; the runner did not get a WSL build with containers." } - wsl --version - if (-not (Test-Path $wslc)) { - throw "wslc.exe was not installed at $wslc; the hosted runner did not get a WSL build with containers." + $minimum = [version](Select-Xml -Path Directory.Packages.props -XPath '//MicrosoftWSLContainersVersion').Node.InnerText + $installed = [version]((& $wslc version) -replace '^wslc\s+', '') + if ($installed -lt $minimum) { + throw "WSL $installed is older than $minimum, the minimum Purview.Containers.Wsl supports." } - $env:PATH = "C:\Program Files\WSL;$env:PATH" - & $wslc version + Write-Host "wslc $installed (minimum $minimum)" - name: Restore run: dotnet restore src/Containers.slnx - name: Build diff --git a/.gitignore b/.gitignore index ebeeb74..8d45c18 100644 --- a/.gitignore +++ b/.gitignore @@ -665,3 +665,4 @@ sketch # Per-agent folders (including .claude/) are local too - never commit a copy. .agents/skills/ .claude/ + diff --git a/AGENTS.md b/AGENTS.md index 2ee30fc..f6c5257 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -39,7 +39,7 @@ whenever a target framework, a backend package or the `buildTransitive` assets c | `src/Directory.Build.props` / `src/Directory.Build.targets` | Solution-wide SDK import, package metadata and the shared package icon | | `.config/purview-build.json` | Shared `Purview.Build` pipeline configuration: solution, test discovery/filter and the **exhaustive** pack-validation manifest | | `Directory.Build.rsp` | Purview.BuildSdk-managed MSBuild response file: enables the .NET 11 multithreaded build (`-mt`) and disables node reuse (`-nr:false`). Delete its marker line to take ownership | -| `Justfile` | Supported local workflow commands | +| `Justfile` / `.build/just/` | Supported local workflow commands: the root `Justfile` holds this repository's own recipes (`test` override, `verify-consumers`, samples) and imports the shared modules in `.build/just/`, copied verbatim from the `purview-buildsdk-justfile` skill - change them there, not here | | `skills` | The agent skills this repository authors and publishes | | `.agents/skills` | Skills installed from other repositories by the skills CLI (gitignored; `skills-lock.json` is the tracked record) | @@ -59,7 +59,15 @@ whenever a target framework, a backend package or the `buildTransitive` assets c managed bridge networks/aliases, Linux capabilities, session host loopback, builds and reuse. WSLC uses the managed `Microsoft.WSL.Containers` 3.0.5 SDK for lifecycle, images, networks, capabilities and host loopback, and the SDK-owned session with a bounded `wslc` subprocess only for SDK-missing capabilities - (entrypoint/user/labels, copy, builds, reuse); ordinary SDK-only consumers need no CLI. + (entrypoint/user/labels, copy, builds, reuse); ordinary SDK-only consumers need no CLI. `wslc` is + found on PATH or at `%ProgramFiles%\WSL\wslc.exe`. +- **The WSLC backend is x64 only** (no ARM64 or x86 payload; `PCC0002` rejects a non-x64 Windows + consumer and the facade reports `wsl` unavailable in a non-x64 process). The WSL floor is + `MinimumWslVersion` in `Directory.Packages.props` (it follows the `Microsoft.WSL.Containers` SDK + pin) and is enforced at run time by `WslRequirements`. Do not add a Windows-build check: WSL owns + that floor and reports `WSL_E_OS_NOT_SUPPORTED`. Every unavailable/incompatible reason must name its + fix (for example "Run 'wsl --update'"). The authoritative host list is + [Consumer Requirements](docs/wiki/Consumer-Requirements.md#host-requirements-wsl-containers-backend). - Never swallow caller cancellation as a successful exec/stop. Startup is a total five-minute managed budget; exec defaults to one minute, stop to 15 seconds and cleanup to 30 seconds. Synchronous WSLC native calls cannot be safely interrupted; never advertise hard zero-hang guarantees. @@ -131,27 +139,30 @@ whenever a target framework, a backend package or the `buildTransitive` assets c dropped): `Purview.Containers.Core` (abstractions) and the service modules target **`net10.0` and `net11.0`** on any platform. `Purview.Containers.Wsl` is **multi-target**: `net10.0`/`net11.0` (portable facades) and `net10.0-windows10.0.19041.0`/`net11.0-windows10.0.19041.0` (the WSLC implementations). - Purview.BuildSdk's `Current` target-framework set supplies the `net10.0;net11.0` list to the library - subtree, while `src/Directory.Build.props` pins that set to `net11.0-windows10.0.19041.0` for - `src/tests` so the WSLC tests bind the implementation; `Wsl.csproj` adds the Windows - builds with a platform-identifier condition (never a literal TFM). The Docker integration projects + `src/Directory.Build.props` selects Purview.BuildSdk's `Supported` target-framework set + (`PurviewTargetFrameworkSet=Supported`, `net10.0;net11.0` in BuildSdk 2.2.0) for every project that + declares no target of its own, and pins that set to `net11.0-windows10.0.19041.0` for `src/tests` so + the WSLC tests bind the implementation. `Wsl.csproj` derives its four targets from the same set (each + supported framework plus its `-windows10.0.19041.0` build) and selects files with a + platform-identifier condition (never a literal TFM). The Docker integration projects declare `net10.0` directly so they run on Linux **and** keep the lowest supported framework under test. The contract, the failures that enforce it and the CI workarounds are documented in [Consumer Requirements](docs/wiki/Consumer-Requirements.md); update that page whenever a target framework, the `buildTransitive` defaults, the payload layout or the `PCC0001`/`PCC0002` guards change. -- The `net11.0` library builds are compiled with `runtime-async=on` (`PurviewRuntimeAsync=false` opts out): - Purview.BuildSdk applies it to every `net11.0`+ target together with the C# 15 - `updated-memory-safety-rules` tier (`MemorySafetyRules=2`), so the repository does not repeat either - switch. The runtime manages suspension instead of compiler-generated state machines, which lowers async - overhead and makes live stack traces name the real methods. `Wsl.UnitTests/BuildFeatureTests.cs` guards - it. The `net10.0` builds keep the classic state machines. Because `closed` hierarchies require +- The `net11.0` builds are compiled with `runtime-async=on` and the C# 15 + `updated-memory-safety-rules` tier. Purview.BuildSdk 2.2.0 makes both **opt-in**, so + `src/Directory.Build.props` sets `PurviewRuntimeAsync=true` and `MemorySafetyRules=2` explicitly; do not + remove them. The runtime manages suspension instead of compiler-generated state machines, which lowers + async overhead and makes live stack traces name the real methods. `Wsl.UnitTests/BuildFeatureTests.cs` + guards both. The `net10.0` builds keep the classic state machines. Because `closed` hierarchies require `System.Runtime.CompilerServices.IsClosedTypeAttribute` and C# unions require `UnionAttribute` (both .NET 11 runtime types), neither is used: no public hierarchy here is closed anyway — `WaitStrategy`, `ContainerException` and the backend interfaces are documented extension points. - `Purview.Containers.Wsl` ships `Sdk/buildTransitive/Purview.Containers.Wsl.{props,targets}` so consumers inherit `WindowsSdkPackageVersion`/`PlatformTarget` defaults, a clear error for an unsupported target - framework (`PCC0001`) or a 32-bit Windows consumer (`PCC0002`), and — for a platform-neutral consumer - on a Windows build host — a copy of the WSLC implementation payload (`wslc/`) that the portable facade + framework (`PCC0001`) or a non-x64 Windows consumer (`PCC0002`), and — for a platform-neutral consumer + on a Windows build host — a copy of the x64-only WSLC implementation payload (`payload/win-x64/`, + copied to `wslc/`) that the portable facade loads at run time. Those assets are framework-agnostic, so NuGet never raises `NU1202` at restore time; the guards are the fail-fast path. Keep them, and keep the `RequiredContent` entries (including `payload/**`) that declare them. They belong to the WSL backend package only. @@ -162,8 +173,9 @@ whenever a target framework, a backend package or the `buildTransitive` assets c tests) registers explicitly instead — `WslcTest.EnsureBackendRegistered()`. - `src/Directory.Build.props` sets `EnableWindowsTargeting=true` because the shared CI agent is `ubuntu-latest`; removing it fails the pipeline with `NETSDK1100`. -- The project is **experimental**: keep the experimental notice in `README.md`, `docs/wiki/Home.md` and - the package READMEs, and keep versions on a `-prerelease.N` suffix. +- Versions stay on a `-prerelease.N` suffix until the stable 1.0.0 release, which includes the WSL + Containers backend. The docs, README and package READMEs must not carry experimental or preview + notices. ## Module rules @@ -227,6 +239,23 @@ whenever a target framework, a backend package or the `buildTransitive` assets c - Use the shared `WslcTest` helper in `src/tests/SharedTestingFramework` for WSLC integration skip/availability checks; the Docker suites use their own `DockerTest` helper. Unit tests may use the modules' `BuildConfigurationForTesting()` internal hook. +- **Unit tests must never load the WSL Containers SDK at run time.** The `*.UnitTests` projects run on + the shared **Linux** CI agent (`ubuntu-latest`). The `Microsoft.WSL.Containers` assembly's module + initializer loads the Windows-only native `wslcsdk.dll`, so the first run-time use of *any* SDK + type fails there with `TypeInitializationException` / `DllNotFoundException` (`Unable to load shared + library 'wslcsdk.dll'`), even though the same test passes on a Windows machine. In a unit test (and + in any code path a unit test reaches), never pass, box, construct, call or enumerate an SDK type + such as `Component`, `ServiceVersion` or `WslcService`. + - Keep testable logic SDK-free and map SDK values at the single call site that already runs + against the SDK. For example, `WslComponent` (in `WslRequirements.cs`) mirrors the SDK's + `Component` flags, and `WslContainerRuntime.GetInfoAsync` converts with + `(WslComponent)(int)component`. + - When mirroring an SDK enum, define its values *from* the SDK constants + (`VirtualMachinePlatform = Sdk.Component.VirtualMachinePlatform`). The compiler folds them into + this assembly, so the values cannot drift and nothing loads the SDK. + - Reproduce the Linux condition locally before pushing: delete every `wslcsdk.dll` under + `src/tests/Wsl.UnitTests/bin//net11.0-windows10.0.19041.0/` and run + `Wsl.UnitTests`; rebuild to restore it. - `Wsl.UnitTests/ConsumerRequirementsTests.cs` guards the published target framework of the Windows build this project binds (`.NETCoreApp,Version=v11.0` plus `Windows10.0.19041.0`), and `Wsl.UnitTests/BuildFeatureTests.cs` guards that the net11.0 build has no compiler-generated async @@ -245,7 +274,7 @@ just lint-check / just lint-fix # CSharpier check / format just pack # build + dotnet pack into ./artifacts just verify-consumers # build throwaway consumers against the packed packages just pipeline-pack-validate # restore, build, lint, test, pack, validate -just scrub # reset bin/obj, clean, forced restore, build-server shutdown +just scrub # build-server shutdown, delete bin/obj and artifacts, forced restore ``` Commit messages follow Conventional Commits enforced by the `commit-msg` lefthook @@ -254,21 +283,24 @@ Commit messages follow Conventional Commits enforced by the `commit-msg` lefthoo ## Versioning and releases - `package.json` is the authoritative release and package version. Do not diverge project versions by hand. -- `.github/workflows/pr.yml` builds and tests pull requests through the shared - `purview-dev/build/.github/workflows/purview-build.yml`, with pack and validation enabled. +- `.github/workflows/pr.yml` builds and tests pull requests **and every push to `main`** through the + shared `purview-dev/build/.github/workflows/purview-build.yml`, with pack and validation enabled (plus + the Docker and WSLC contract jobs). A push to `main` never publishes; superseded PR runs are + cancelled, `main` runs are not. - `.github/workflows/release.yml` runs the shared release pipeline with `release-mode: NuGet` on a push to a `release/**` branch (or a manual dispatch), **not** on a push to `main`. Cut a release by merging the version bump into `main`, then pushing a `release/v…` branch named after the version from it (for example `release/v1.0.9` for `1.0.0-prerelease.9`). `.config/purview-build.json` sets the `TrunkReservesMinor` eligibility policy; a version whose `v` tag already exists is skipped (`REL002`), so every release needs a new `package.json` version. See - [Release Flow](docs/wiki/Release-Flow.md). + [Release Flow](docs/wiki/contributing/Release-Flow.md). - `.github/workflows/integration-wsl.yml` runs the WSLC integration suites. The fast contract suite runs on a hosted `windows-2025` runner on every pull request from `pr.yml`; the full service-module matrix runs nightly on `windows-2025` and can be dispatched manually against either the hosted runner or a - self-hosted Windows runner with the custom `wslc` label (documented in [Testing](docs/wiki/Testing.md)). - `windows-2022` and Windows 10 do not support WSL Containers. `.github/actionlint.yaml` declares the - custom label. + self-hosted Windows runner with the custom `wslc` label (documented in [Testing](docs/wiki/contributing/Testing.md)). + The WSLC suites run on the hosted `windows-2025` runner (GitHub's hosted `windows-2022` runner cannot + run them), and the workflows bring WSL up to date with the stable-channel `wsl --update`; no + `--pre-release` channel is used. `.github/actionlint.yaml` declares the custom label. - The workflows pin `dotnet-version` to `global.json`'s `sdk.version`; keep them in sync, and keep `.config/purview-build.json` pointing at `src/Containers.slnx`. The shared workflow runs on `ubuntu-latest`, which is why `EnableWindowsTargeting=true` must stay in `src/Directory.Build.props`. diff --git a/Directory.Packages.props b/Directory.Packages.props index 4534c24..39bfd97 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -28,8 +28,15 @@ --> 3.0.5 + + $(MicrosoftWSLContainersVersion) 10.0.26100.80 - 1.76.0 + 1.87.0 @@ -38,20 +45,20 @@ .NET 10 servicing line on purpose: the .NET 8/.NET 9 lines are no longer supported, and a component declares the lowest band a consumer on the oldest supported framework can take. --> - + - + - + - - - + + + @@ -62,21 +69,21 @@ package is licensed under the Microsoft Testing Platform Tools terms, which permit use in OSI-approved open-source projects; it never ships in a Purview package. --> - - + + - - + + - + - - + + - - + + diff --git a/Justfile b/Justfile index e7e96bc..af3830c 100644 --- a/Justfile +++ b/Justfile @@ -1,129 +1,55 @@ -set quiet +# Recipes for Purview.Containers. Run `just` for the list. +# +# The shared recipes come from .build/just/, copied verbatim from the purview-buildsdk-justfile +# skill. Change them there, not here; this file holds what belongs to this repository. -export TESTINGPLATFORM_EXITCODE_IGNORE := "8" -export DOTNET_CLI_TELEMETRY_OPTOUT := "1" -export DOTNET_SKIP_FIRST_TIME_EXPERIENCE := "1" -export DO_NOT_TRACK := "1" +set quiet -root_folder := "./src/" -solution_file := root_folder + "Containers.slnx" -test_solution := solution_file -build_configuration := "Debug" +# Let a definition here override a module's default variable or no-op hook. +set allow-duplicate-variables +set allow-duplicate-recipes -pipeline_tool := "dotnet purview-build" +import ".build/just/index.just" -artifact_folder := "./artifacts/" +solution_file := "src/Containers.slnx" -# Displays the list of available commands +# The test runner treats "no test ran" (exit 8) as success, so a filter that matches nothing in one +# test project - the WSLC suites under a Unit filter, for example - does not fail the run. +export TESTINGPLATFORM_EXITCODE_IGNORE := env("TESTINGPLATFORM_EXITCODE_IGNORE", "8") [private] default: just --list -# Restore the repository's .NET local tools (.config/dotnet-tools.json) -[private] -ensure-pipeline-tool: - dotnet tool restore - -# Run the PR pipeline (restore, build, lint, tests, pack, validate) -[group('Pipeline')] -pipeline-pr *args: - just ensure-pipeline-tool - echo "Running PR pipeline..." - {{ pipeline_tool }} {{ args }} - -# Run the build pipeline (restore, build, lint) -[group('Pipeline')] -pipeline-build *args: - just ensure-pipeline-tool - echo "Running build pipeline..." - {{ pipeline_tool }} --Build:RunTests=false --Release:Mode=None {{ args }} - -# Run the release pipeline (restore, build, lint, tests, pack, publish, GitHub release) -[group('Pipeline')] -pipeline-release *args: - just ensure-pipeline-tool - echo "Running release pipeline..." - {{ pipeline_tool }} --Release:Mode=NuGet {{ args }} - -# Run the release pipeline (restore, build, lint, tests, pack, local nuget publish) -# Note: `just` runs recipes through the shell, which strips backslashes from unquoted arguments. -# Use the LOCAL_NUGET_FEED_PATH environment variable or forward slashes, e.g. -# just pipeline-local-release --PublishLocalNuGet:LocalFeedPath=p:/_sync-projects/.local-nuget/ -[group('Pipeline')] -pipeline-local-release *args: - just ensure-pipeline-tool - echo "Running local release pipeline..." - {{ pipeline_tool }} --Release:Mode=LocalNuGet {{ args }} - -# Run the pipeline with tests enabled -[group('Pipeline')] -pipeline-tests *args: - just ensure-pipeline-tool - echo "Running tests pipeline..." - {{ pipeline_tool }} --Build:RunTests=true --Release:Mode=None {{ args }} - -# Run the pipeline through pack + validate (restore, build, lint, tests, pack, validate pack contents) without publishing/releasing -[group('Pipeline')] -pipeline-pack-validate *args: - just ensure-pipeline-tool - echo "Running pack + validate pipeline..." - {{ pipeline_tool }} --Build:RunPack=true --Build:ValidatePack=true --Release:Mode=None {{ args }} - # ----------------------------------------------------------------------------- # Build and Test # ----------------------------------------------------------------------------- -# Builds the solution with the specified configuration (default: Debug) -[group('Build and Test')] -build *args: - echo "Building {{ BLUE }}{{ solution_file }}{{ NORMAL }} with {{ YELLOW }}{{ build_configuration }}{{ NORMAL }}..." - dotnet build "{{ solution_file }}" --configuration "{{ build_configuration }}" {{ args }} - -# Restore NuGet packages for the solution -[group('Build and Test')] -restore *args: - dotnet restore {{ solution_file }} {{ args }} - -# Runs tests for the solution with the specified configuration (default: Debug) -# Test modules run serially by default: a WSLC session exclusively locks its image-store VHD, so parallel -# test assemblies contend for the shared store and fail with 0x80070020 ("file is being used by another -# process"). Override by appending the flag, e.g. -# just test '/*/*/*/*/' --max-parallel-test-modules 4 +# Overrides the shared `test` on purpose. The test projects must run one at a time +# (--max-parallel-test-modules 1): a WSLC session exclusively locks its image-store VHD, so parallel +# test assemblies contend for the shared store and fail with 0x80070020 ("file is being used by +# another process"). Override by appending the flag, e.g. +# +# just test '/*/*/*/*/' --max-parallel-test-modules 4 # # Failures are retried at the test-project level by Microsoft.Testing.Platform's retry extension. It # restarts the test host for each attempt, which also gives WSLC a fresh session; the delay lets the -# previous host release the session VHD. -# -# --results-directory-layout per-module is a .NET 11 run-level option: every test application gets its -# own report folder, so a multi-module run cannot have one module's identically named report overwrite -# another's. +# previous host release the session VHD. --results-directory-layout per-module (.NET 11) gives every +# test application its own report folder, so one module's report cannot overwrite another's. +[doc('Run the tests matching a tree-node filter, one test project at a time (default: every test)')] [group('Build and Test')] -test filter="/*/*/*/*/" *args: - echo "Running tests for {{ BLUE }}{{ test_solution }}{{ NORMAL }} with {{ YELLOW }}{{ build_configuration }}{{ NORMAL }}..." - dotnet test --solution "{{ test_solution }}" --configuration "{{ build_configuration }}" --max-parallel-test-modules 1 --treenode-filter={{ filter }} --retry-failed-tests 2 --retry-failed-tests-delay 5s --retry-failed-tests-max-percentage 50 --results-directory-layout per-module {{ args }} - -# Cleans the solution with the specified configuration (default: Debug) +test filter=test_filter *args: + echo "==> Testing {{ BLUE }}{{ solution_file }}{{ NORMAL }} ({{ YELLOW }}{{ build_configuration }}{{ NORMAL }}) with filter {{ GREEN }}{{ filter }}{{ NORMAL }}, one test project at a time" + dotnet test --solution "{{ solution_file }}" --configuration "{{ build_configuration }}" --max-parallel-test-modules 1 --treenode-filter "{{ filter }}" --retry-failed-tests 2 --retry-failed-tests-delay 5s --retry-failed-tests-max-percentage 50 --results-directory-layout per-module {{ args }} + +# Verifies the documented consumer requirements (docs/wiki/Consumer-Requirements.md) by packing and +# then building throwaway consumer projects against the produced packages: the supported target +# frameworks, the shipped buildTransitive defaults, the PCC0001/PCC0002 guard errors (including the +# x64-only rule) and the payload the portable facade loads. Slower than unit tests: it packs and +# restores from nuget.org. +[doc('Pack, then build throwaway consumer projects that assert the published consumer contract')] [group('Build and Test')] -clean *args: - echo "Cleaning {{ BLUE }}{{ solution_file }}{{ NORMAL }} with {{ YELLOW }}{{ build_configuration }}{{ NORMAL }}..." - dotnet clean "{{ solution_file }}" --configuration "{{ build_configuration }}" {{ args }} - -# Packs the package into a NuGet package and outputs it to the specified folder -[group('Build and Test')] -pack *args: - just build - echo "Packing {{ BLUE }}{{ solution_file }}{{ NORMAL }} with {{ YELLOW }}{{ build_configuration }}{{ NORMAL }}..." - dotnet pack "{{ solution_file }}" --configuration "{{ build_configuration }}" --no-restore --output "{{ artifact_folder }}" {{ args }} - -# Verifies the documented consumer requirements and workarounds (docs/wiki/Consumer-Requirements.md) -# by packing and then building throwaway consumer projects against the produced packages: the -# "just reference the package from a .NET 11 Windows project" path, the shipped buildTransitive -# defaults, the guard errors for unsupported target frameworks, and the non-.NET-11 escape hatch -# that deliberately does not work. Slower than unit tests (packs and restores from nuget.org). -[group('Build and Test')] -verify-consumers *args: - just pack +verify-consumers *args: pack pwsh -NoProfile -File scripts/verify-consumers.ps1 {{ args }} # ----------------------------------------------------------------------------- @@ -149,51 +75,11 @@ sample-docker: dotnet run --project samples/getting-started/DockerSample/DockerSample.csproj # ----------------------------------------------------------------------------- -# Formatting -# ----------------------------------------------------------------------------- - -# Checks for linting issues in the root folder -[group('Formatting')] -lint-check: - echo "Linting checking {{ BLUE }}root folder{{ NORMAL }}..." - dotnet csharpier check . - -# Fixes linting issues in the root folder -[group('Formatting')] -lint-fix: - echo "Linting fixing {{ BLUE }}root folder{{ NORMAL }}..." - dotnet csharpier format . - -# ----------------------------------------------------------------------------- -# Versioning and Release +# Utilities # ----------------------------------------------------------------------------- -# Displays the current version of the project. -# Requires Bun. -[group('Versioning and Release')] -version: - bun -e "console.log('Current Version: {{ GREEN }}' + require('./package.json').version + '{{ NORMAL }}')" - -# ----------------------------------------------------------------------------- -# System / Shell -# ----------------------------------------------------------------------------- - -# Opens the solution in the default associated application -[group('Utilities')] -vs: - echo "Opening {{ BLUE }}{{ solution_file }}{{ NORMAL }}..." - open "{{ solution_file }}" - -# Opens the root folder in Visual Studio Code +# Opens the source folder in Visual Studio Code [group('Utilities')] code: - echo "Opening {{ BLUE }}Visual Studio Code{{ NORMAL }}..." - code "{{ root_folder }}" - -# Clean up the repository by removing build artifacts, bin/obj folders etc, and shutting down the build server -[group('Utilities')] -scrub: - find . -type d \( -name bin -o -name obj \) -exec rm -rf {} + - just clean - just restore --force-evaluate - dotnet build-server shutdown + echo "Opening {{ BLUE }}src/{{ NORMAL }} in Visual Studio Code..." + code "src/" diff --git a/README.md b/README.md index a4be38a..789a7cf 100644 --- a/README.md +++ b/README.md @@ -32,23 +32,18 @@ to one minute, stop to 15 seconds and cleanup to 30 seconds, all configurable. C propagated; synchronous native WSLC calls cannot be forcibly interrupted. Disposal follows Testcontainers' `WithCleanUp`: containers are removed by default, `.WithCleanUp(false)` retains them for inspection, and `.WithAutoRemove()` is opted into separately. See -[Capabilities and Cancellation](docs/wiki/Backend-Capabilities.md) for APIs, ownership and limits. - -> **Experimental.** This project is an experiment in running throwaway containers through Microsoft -> WSL Containers. The public API, defaults and packaging rules can change between prereleases, and -> there is no production support guarantee. Pin the exact package version you build against, and read -> [Consumer Requirements](docs/wiki/Consumer-Requirements.md) before adopting it. - -> **Status: preview.** Backend-neutral abstractions, two backends (WSL Containers and Docker), wait -> strategies, the `Image`/`Tag` parser, registry auth, observability, hardening, and **nine service -> modules** (PostgreSQL, Redis, SQL Server, RabbitMQ, Azurite, NATS, MySQL, Azure Key Vault Emulator, Azure Service Bus Emulator). On WSLC, **images are shared -> by default** (`StorageMode.Shared`): sessions reuse a stable image store -> (`%LOCALAPPDATA%\Purview\WslContainers\images`) so images are pulled once, not per session; -> `StorageMode.PerSession` provides isolation. Move the store with `PURVIEW_CONTAINERS_STORAGE_PATH` or -> `WslContainerRuntimeOptions.StoragePath`. Named volumes are retained by default; set -> `PURVIEW_CONTAINERS_CLEAN_VOLUMES=true` (or `ContainerCleanup.CleanUpVolumesOnExit`) to delete the -> volumes the library created when the process or session ends. Runnable samples live in -> `samples/getting-started`. +[Capabilities and Cancellation](docs/wiki/guide/Backend-Capabilities.md) for APIs, ownership and limits. + +**Features.** Backend-neutral abstractions, two backends (WSL Containers and Docker), wait +strategies, the `Image`/`Tag` parser, registry auth, observability, hardening, and **nine service +modules** (PostgreSQL, Redis, SQL Server, RabbitMQ, Azurite, NATS, MySQL, Azure Key Vault Emulator, Azure +Service Bus Emulator). On WSLC, **images are shared by default** (`StorageMode.Shared`): sessions reuse a +stable image store (`%LOCALAPPDATA%\Purview\WslContainers\images`) so images are pulled once, not per +session; `StorageMode.PerSession` provides isolation. Move the store with +`PURVIEW_CONTAINERS_STORAGE_PATH` or `WslContainerRuntimeOptions.StoragePath`. Named volumes are retained +by default; set `PURVIEW_CONTAINERS_CLEAN_VOLUMES=true` (or `ContainerCleanup.CleanUpVolumesOnExit`) to +delete the volumes the library created when the process or session ends. Runnable samples live in +`samples/getting-started`. **Documentation:** [Containers documentation](https://purview.dev/docs/containers/) @@ -60,7 +55,7 @@ for inspection, and `.WithAutoRemove()` is opted into separately. See referencing the umbrella package, Testcontainers or WSLC. It verifies native paths, running WSL translations and explicit shared-remote mappings against the daemon using two-way file markers. `Purview.Containers.Aspire` adds opt-in `builder.AddContainerEnvironment()` integration for any -Aspire AppHost. Both target `net10.0` and `net11.0`; the adapter requires Aspire 13.6.5 or later. +Aspire AppHost. Both target `net10.0` and `net11.0`; the adapter requires Aspire 17.0.0 or later. These are separate from the existing Docker backend's automatic WSL2 path handling. Docker Engine inside a WSL distribution is not Microsoft WSL Containers. See the [environment package guide](src/src/Environment/Sdk/README.md) and @@ -75,13 +70,14 @@ want to fix the runtime. **WSL Containers backend** -- Windows 11 (22H2 or later) or Windows Server 2025 with **WSL Containers**, installed via - `wsl --install --no-distribution` (verified against - WSL 3.0.5.0). +- An **x64** Windows host where WSL 2 runs (Windows 11, Windows 10 version 2004 or later, or Windows + Server 2025) with virtualisation enabled and **WSL 3.0.5 or later** from the stable channel: + `wsl --install --no-distribution`, or `wsl --update`. ARM64 is not supported. The full list is in + [Host requirements](docs/wiki/Consumer-Requirements.md#host-requirements-wsl-containers-backend). - A consuming project that is **.NET 10 or .NET 11** (.NET 8 and .NET 9 are not supported). A platform-neutral `net10.0` or `net11.0` project binds the portable facade and gets automatic WSLC-or-Docker selection; a Windows target framework (`net10.0-windows10.0.19041.0` or - `net11.0-windows10.0.19041.0`, x64 or arm64) binds the matching implementation directly. The + `net11.0-windows10.0.19041.0`, x64 only) binds the matching implementation directly. The `Purview.Containers.Wsl` package ships MSBuild defaults for the supporting settings. **Docker backend** @@ -96,8 +92,8 @@ enough for a consumer. Verify: ```powershell -wsl --version # WSL Containers installed (verified against 3.0.5.0) -wslc version # e.g. 3.0.5.0 +wsl --version # WSL 3.0.5 or later (run 'wsl --update' if older) +wslc version # ships with WSL (%ProgramFiles%\WSL\wslc.exe); e.g. 3.0.5.0 ``` ```bash @@ -173,7 +169,7 @@ string amqp = rabbitMq.GetConnectionString(); ## Repository layout -``` +```text src/ Containers.slnx canonical solution (restore, build, test, pack) src/ @@ -205,12 +201,12 @@ The project documentation lives in [`docs/wiki`](docs/wiki/Home.md) and is publi - [Getting Started](docs/wiki/Getting-Started.md) — prerequisites, first container, first module. - [Backends: WSLC or Docker](docs/wiki/Backends.md) — how to choose, side-by-side project setup, CI example, troubleshooting. - [Consumer Requirements](docs/wiki/Consumer-Requirements.md) — the target-framework contract, the `PCC0001`/`PCC0002` guards, and the CI workarounds. -- [Architecture](docs/wiki/Architecture.md) — the shared session model, concurrency and cleanup decisions. -- [Lifecycle](docs/wiki/Lifecycle.md), [Networking](docs/wiki/Networking.md), [Wait Strategies](docs/wiki/Wait-Strategies.md). +- [Architecture](docs/wiki/contributing/Architecture.md) — the shared session model, concurrency and cleanup decisions. +- [Lifecycle](docs/wiki/guide/Lifecycle.md), [Networking](docs/wiki/guide/Networking.md), [Wait Strategies](docs/wiki/guide/Wait-Strategies.md). - [Modules](docs/wiki/Modules.md) — the module contract and every shipped module. -- [Testing](docs/wiki/Testing.md) — unit vs integration categories and the serial WSLC test rule. -- [Packaging](docs/wiki/Packaging.md) and [Release Flow](docs/wiki/Release-Flow.md) — what ships and how it is released. -- [Contributing](docs/wiki/Contributing.md) and [Contributing Modules](docs/wiki/Contributing-Modules.md). +- [Testing](docs/wiki/contributing/Testing.md) — unit vs integration categories and the serial WSLC test rule. +- [Packaging](docs/wiki/contributing/Packaging.md) and [Release Flow](docs/wiki/contributing/Release-Flow.md) — what ships and how it is released. +- [Contributing](docs/wiki/contributing/README.md) and [Contributing Modules](docs/wiki/Contributing-Modules.md). Every package also ships its own `README.md` (from `src/src//Sdk/README.md`), so `dotnet add package Purview.Containers.` brings documentation specific to that package. @@ -301,7 +297,7 @@ Every test process owns a single shared WSLC session and, by default, uses the s `storage.vhdx`**, and the lock is taken lazily on the first store access — so running test assemblies in parallel makes the losers fail with `0x80070020`: -``` +```text The process cannot access the file because it is being used by another process. ``` @@ -338,7 +334,7 @@ just sample-docker # needs a Docker daemon ### Verifying the consumer contract ```powershell -just verify-consumers # pack, then build 25 throwaway consumer projects against ./artifacts +just verify-consumers # pack, then build 28 throwaway consumer projects against ./artifacts just verify-consumers -Keep # same, keeping the generated projects for inspection ``` diff --git a/bun.lock b/bun.lock new file mode 100644 index 0000000..d216ca2 --- /dev/null +++ b/bun.lock @@ -0,0 +1,96 @@ +{ + "lockfileVersion": 2, + "configVersion": 1, + "workspaces": { + "": { + "name": "containers", + "devDependencies": { + "oxfmt": "^0.79.0", + "oxlint": "^1.94.0", + }, + }, + }, + "packages": { + "@oxfmt/binding-android-arm-eabi": ["@oxfmt/binding-android-arm-eabi@0.79.0", "", { "os": "android", "cpu": "arm" }, "sha512-xOCQ/rvokUXs8SxOQY5Wy2ukPaZJZ0PmdJovN0ryB1c8DVEtbcvliLdYtINUYh8QOTpmBOctIisSJk9tvh+J6w=="], + + "@oxfmt/binding-android-arm64": ["@oxfmt/binding-android-arm64@0.79.0", "", { "os": "android", "cpu": "arm64" }, "sha512-WMLDvCjjchUYtI6zXKOdzTDGm72BaYZiz1/VhB1rrxdakUZRlJh1aMr3CT6ui51uHcWVBycULIXSZHpw6u2pTQ=="], + + "@oxfmt/binding-darwin-arm64": ["@oxfmt/binding-darwin-arm64@0.79.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-+LzSN7w7tULz96ntS1Uqe5oI00XZ0o/m/t3+eSfiQp3aTPnj2eGUafqEWryMLk84j7x9NiF+GEP2YT4/BfClgA=="], + + "@oxfmt/binding-darwin-x64": ["@oxfmt/binding-darwin-x64@0.79.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-KFiMRhKeiiooaS1dKc4r8AZgOrfOhwVe1yf/aRef+8BajJwtVjMtlsQl/BNRxtkFbq13GjEo/4Q+9YhFGU4o6g=="], + + "@oxfmt/binding-freebsd-x64": ["@oxfmt/binding-freebsd-x64@0.79.0", "", { "os": "freebsd", "cpu": "x64" }, "sha512-lHVIp0g8ZOFKiqVscvttp+3HJkkRH6XkGgfAA0lVexIlE1mMFVp4V7RBdxz/P9p7T8pSNsYdapFWvdT21Mib9w=="], + + "@oxfmt/binding-linux-arm-gnueabihf": ["@oxfmt/binding-linux-arm-gnueabihf@0.79.0", "", { "os": "linux", "cpu": "arm" }, "sha512-Pt35GoxiMUfnr+23cuzk07XQVvISDFxxPcp/aFVB87+RQvJoQaBo/XN7Re9XxgElvbELdyxTLnV9XM2aTfJeUA=="], + + "@oxfmt/binding-linux-arm-musleabihf": ["@oxfmt/binding-linux-arm-musleabihf@0.79.0", "", { "os": "linux", "cpu": "arm" }, "sha512-zPi9Dni58VKp3r1QUcFvnbJNfBr49qyecq0vlM4SaX/MSjmguq77VngirghDua5tyhIDfqdUMTCK2KRlnZFp/g=="], + + "@oxfmt/binding-linux-arm64-gnu": ["@oxfmt/binding-linux-arm64-gnu@0.79.0", "", { "os": "linux", "cpu": "arm64", "libc": "glibc" }, "sha512-XhRehATEWjwX7VVEgDUD+7pfHYncQIJaEU0qsHvEKtu9XX0QYzcKvXhU9+URfiGX9WRh3wy2Ow+YCc3EeHtImg=="], + + "@oxfmt/binding-linux-arm64-musl": ["@oxfmt/binding-linux-arm64-musl@0.79.0", "", { "os": "linux", "cpu": "arm64", "libc": "musl" }, "sha512-gbVjFZYug0MEyqvuTAzXGNxFJmBqBO32o1Fud1lG8bGs6oVz48ZtNQyEcAzqrOwaaG+Sxtv4gVzcsfht9aqmkg=="], + + "@oxfmt/binding-linux-ppc64-gnu": ["@oxfmt/binding-linux-ppc64-gnu@0.79.0", "", { "os": "linux", "cpu": "ppc64", "libc": "glibc" }, "sha512-0N0sD3vnllyuiNh1r6zKvNXWE/CakcPKJAespg7XE2+sfvxpz5Q1iFah8sF5aedsOmVvbZaOPZcSHVmMosT1fA=="], + + "@oxfmt/binding-linux-riscv64-gnu": ["@oxfmt/binding-linux-riscv64-gnu@0.79.0", "", { "os": "linux", "cpu": "none", "libc": "glibc" }, "sha512-YtjqUHolcX6cv0ZMZuKQCM4H0ae/okcowy0wGcPHJk4O+8zjy3TvNhzDQ1/KGCkMJO8Fwulm1JcPJsraVJ3p+w=="], + + "@oxfmt/binding-linux-riscv64-musl": ["@oxfmt/binding-linux-riscv64-musl@0.79.0", "", { "os": "linux", "cpu": "none", "libc": "musl" }, "sha512-H2gb9bEBr5tcdP5FU8JYTfgOavXDorWcAAlwci/zEKF2jzgh/oEr/SAw6aHB9n3FLEvnKvOh0A1fjku+vgYoUA=="], + + "@oxfmt/binding-linux-s390x-gnu": ["@oxfmt/binding-linux-s390x-gnu@0.79.0", "", { "os": "linux", "cpu": "s390x", "libc": "glibc" }, "sha512-aZUbyWW5dSOxT/u6suWc4S9GVDt7YPPNMKQon+z79M8dpXmosadcFHAb7jBhpU7Hdsd2GN6/y3nd0JFTsGddZw=="], + + "@oxfmt/binding-linux-x64-gnu": ["@oxfmt/binding-linux-x64-gnu@0.79.0", "", { "os": "linux", "cpu": "x64", "libc": "glibc" }, "sha512-5pW/ZHYfjjQ71gQR+EKzDz8ZzWIDHlTUtWtxVFNgZbKxVZnRxiSXVrllbjpJtx1q8VtSPZ+Lyg9BLny3yw+PTA=="], + + "@oxfmt/binding-linux-x64-musl": ["@oxfmt/binding-linux-x64-musl@0.79.0", "", { "os": "linux", "cpu": "x64", "libc": "musl" }, "sha512-3IVUerTDB7Dvd90c1EurAzlVnlE9Azl7Wn8e33qX3wL/IqnslF+P7HvwkD+VeMbHxRtuw0EEBGSArZFXpUAZrQ=="], + + "@oxfmt/binding-openharmony-arm64": ["@oxfmt/binding-openharmony-arm64@0.79.0", "", { "os": "none", "cpu": "arm64" }, "sha512-C5QDgJBtu9+/2BQScoP7ynv54PLOqfoSqhRWwI0D0RPOwYD4tYj0TUdJbXMO1fNegL/5zJiSOxkq6II2xvttWg=="], + + "@oxfmt/binding-win32-arm64-msvc": ["@oxfmt/binding-win32-arm64-msvc@0.79.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-zlW1m8M49vNGgqQF/ze80KW8pZMicnW2XDZGBHuYtXTRYn4ewvgpqN9wwoqb6uLZZfb1R1zaQWKEB8cs7KYjwA=="], + + "@oxfmt/binding-win32-ia32-msvc": ["@oxfmt/binding-win32-ia32-msvc@0.79.0", "", { "os": "win32", "cpu": "ia32" }, "sha512-wbb7hFv2wK3SCTfu8dl1ydNsXM5dmH+PJMU3sojCkfKcG29VDpITL5/AtouCzXjkOc90QRkcAZcg36gP0KqoHA=="], + + "@oxfmt/binding-win32-x64-msvc": ["@oxfmt/binding-win32-x64-msvc@0.79.0", "", { "os": "win32", "cpu": "x64" }, "sha512-JLaeaQ+4LkQiVXY06JIV1dBFEDJzssvDieK/3Poi6CsY+c4UxghZVrrsfcKGJ5R/0F2Sw3C5Lf5Hu0sM5qJfPw=="], + + "@oxlint/binding-android-arm-eabi": ["@oxlint/binding-android-arm-eabi@1.94.0", "", { "os": "android", "cpu": "arm" }, "sha512-730FKSBsKg/NawYnpI3gXRroXptOVqY32iYBPLUZaSx0vgYzOeiNtwojZL4gJdzo9wDvHUlstShmGRHrWcbRYg=="], + + "@oxlint/binding-android-arm64": ["@oxlint/binding-android-arm64@1.94.0", "", { "os": "android", "cpu": "arm64" }, "sha512-8v8TICIiZpXLot1HSq5+vsG9NEKQ5czQBYlUqJR75OVfFDr3cGOmRU/CtHDWnS4tm8nW+Z4Y357qGToSfYqFvA=="], + + "@oxlint/binding-darwin-arm64": ["@oxlint/binding-darwin-arm64@1.94.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-NePcRMO/ltt1Pnytohl6pl0bd/QyRX8HbpptuDz9LK7FTsFD4lKxDMBt7di9k6IFLO0J05jO2nm7wGqIh6dRHA=="], + + "@oxlint/binding-darwin-x64": ["@oxlint/binding-darwin-x64@1.94.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-QV+m+OaEgLmYyillvP1wKXhMm6tDZEWx3vG7Wjmx9ybg15+6YMfqzvp6e+uPukC6zNywuule0vMn0fZgihZzZA=="], + + "@oxlint/binding-freebsd-x64": ["@oxlint/binding-freebsd-x64@1.94.0", "", { "os": "freebsd", "cpu": "x64" }, "sha512-KVZjca581nrV6P71kZ9M1otBib9LH0IMn9rr4mrnbRp18V0HiZhBHbU26gji/Ieq2G34qMacnMc3zrmKmvWqWA=="], + + "@oxlint/binding-linux-arm-gnueabihf": ["@oxlint/binding-linux-arm-gnueabihf@1.94.0", "", { "os": "linux", "cpu": "arm" }, "sha512-AMQtgQJk8DgdIV+qaQ5sFoHAko4iKa8zo+gYqELy2grtU8hXWB08DAGB3u90aQL1YSxbd3zqHjgcODBHDFyzBQ=="], + + "@oxlint/binding-linux-arm-musleabihf": ["@oxlint/binding-linux-arm-musleabihf@1.94.0", "", { "os": "linux", "cpu": "arm" }, "sha512-ZLzoGVGAmQkp9leeB5rNxAXLcvlmkmd/GY71LKd5uikk+28NEApY3S2FB3pq6MkfOCFFnFg6QgD9lJIjd07D0Q=="], + + "@oxlint/binding-linux-arm64-gnu": ["@oxlint/binding-linux-arm64-gnu@1.94.0", "", { "os": "linux", "cpu": "arm64", "libc": "glibc" }, "sha512-N1dW6o7cY90hLVkDsvz8nWIFOwbO+n272pvW7uLYB7u47HagJVnLChfK6QA9dWFdiPudud9zfksVUOciHc5PNA=="], + + "@oxlint/binding-linux-arm64-musl": ["@oxlint/binding-linux-arm64-musl@1.94.0", "", { "os": "linux", "cpu": "arm64", "libc": "musl" }, "sha512-7tCF4OV/bGDQ2xxgb+sDI97SpmmDrUII4JxTG553voJVA9cnkbXSGSXzo78Ax73BuhEOPoQc2Qi6VrfT0cDG2A=="], + + "@oxlint/binding-linux-ppc64-gnu": ["@oxlint/binding-linux-ppc64-gnu@1.94.0", "", { "os": "linux", "cpu": "ppc64", "libc": "glibc" }, "sha512-B5vUHE4wNisVEuaYxwFUn6tY+vw7A+9APxxqGKI+UmP3yKLpkhnt0qsaCrzjpX55F8rCRHBaTvIDdYo32NE36g=="], + + "@oxlint/binding-linux-riscv64-gnu": ["@oxlint/binding-linux-riscv64-gnu@1.94.0", "", { "os": "linux", "cpu": "none", "libc": "glibc" }, "sha512-/U0b15+c4hTodo8YhEqDlQ6OjnGKvc8igjM/mh23ukqqCUBKiBCaxqUV8bcaofK9uZ+f8wCygkyXLS6LN25YSA=="], + + "@oxlint/binding-linux-riscv64-musl": ["@oxlint/binding-linux-riscv64-musl@1.94.0", "", { "os": "linux", "cpu": "none", "libc": "musl" }, "sha512-ba94Vwl0qOnwXIXNDR33AEbLXuX++ckM74t+9Te7CiPSPAHivhOYyeEkUAicrvOEei1pxXkWggLbFeBFFBTuHA=="], + + "@oxlint/binding-linux-s390x-gnu": ["@oxlint/binding-linux-s390x-gnu@1.94.0", "", { "os": "linux", "cpu": "s390x", "libc": "glibc" }, "sha512-GVwwwms3O8pdgbCiPavwq2vltyB4661GkDz6kJduZ0E5nsSJUDJ0svaP+ePYpuDVYi4+K1qhCKnWa/Ec8I4LUA=="], + + "@oxlint/binding-linux-x64-gnu": ["@oxlint/binding-linux-x64-gnu@1.94.0", "", { "os": "linux", "cpu": "x64", "libc": "glibc" }, "sha512-iUfCFJN8ZIresSnpTfiIkhF3s8X+XA4I9KJ249QwR2QYTMwh0+pla1pj1xaFi+HtR9McjM4Jaemf70HzX7ilOQ=="], + + "@oxlint/binding-linux-x64-musl": ["@oxlint/binding-linux-x64-musl@1.94.0", "", { "os": "linux", "cpu": "x64", "libc": "musl" }, "sha512-RqWVeWpDACS4Oh0m21OBmy+CQ50CbbhuHFmNNPVS2P/4R3d188MjEuEuV7So82/tAM8UAT+UuMDtRDESd9NJ7g=="], + + "@oxlint/binding-openharmony-arm64": ["@oxlint/binding-openharmony-arm64@1.94.0", "", { "os": "none", "cpu": "arm64" }, "sha512-K/2DHOUoypwYVqzxJMRPdMuBKjAetZEAsGPP7rHimd+2+5J1TxM+17pG8kw+ayH4+rqBXiPd+H9wgPcU+fF77A=="], + + "@oxlint/binding-win32-arm64-msvc": ["@oxlint/binding-win32-arm64-msvc@1.94.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-hYOCaOJiB4ZCGswBWKl3JQrhqu6mnC5DCUw/1UMNzRXgsHIJ0V226J43LAVICVIDGlhFUZTYShFW+wHWpt6qCQ=="], + + "@oxlint/binding-win32-ia32-msvc": ["@oxlint/binding-win32-ia32-msvc@1.94.0", "", { "os": "win32", "cpu": "ia32" }, "sha512-1l1FDlzbPmAeDoZ8UGspOE2dOmz1ZL6SlDsvOmRCmWSQjCdTy5LzUepS8mO/SGpAoz4D6WAt/yNZAUyHqbkmkQ=="], + + "@oxlint/binding-win32-x64-msvc": ["@oxlint/binding-win32-x64-msvc@1.94.0", "", { "os": "win32", "cpu": "x64" }, "sha512-I3eZdd4bemIJQDNv9XDV/FEofDxIoN32tzCv98wIgLdW05EqxZb5hF4AwPrRzHD/dQhl0n7KgPy5AQPfM0HWrA=="], + + "oxfmt": ["oxfmt@0.79.0", "", { "dependencies": { "tinypool": "2.2.0" }, "optionalDependencies": { "@oxfmt/binding-android-arm-eabi": "0.79.0", "@oxfmt/binding-android-arm64": "0.79.0", "@oxfmt/binding-darwin-arm64": "0.79.0", "@oxfmt/binding-darwin-x64": "0.79.0", "@oxfmt/binding-freebsd-x64": "0.79.0", "@oxfmt/binding-linux-arm-gnueabihf": "0.79.0", "@oxfmt/binding-linux-arm-musleabihf": "0.79.0", "@oxfmt/binding-linux-arm64-gnu": "0.79.0", "@oxfmt/binding-linux-arm64-musl": "0.79.0", "@oxfmt/binding-linux-ppc64-gnu": "0.79.0", "@oxfmt/binding-linux-riscv64-gnu": "0.79.0", "@oxfmt/binding-linux-riscv64-musl": "0.79.0", "@oxfmt/binding-linux-s390x-gnu": "0.79.0", "@oxfmt/binding-linux-x64-gnu": "0.79.0", "@oxfmt/binding-linux-x64-musl": "0.79.0", "@oxfmt/binding-openharmony-arm64": "0.79.0", "@oxfmt/binding-win32-arm64-msvc": "0.79.0", "@oxfmt/binding-win32-ia32-msvc": "0.79.0", "@oxfmt/binding-win32-x64-msvc": "0.79.0" }, "peerDependencies": { "@astrojs/compiler-rs": "^0.5.0", "svelte": "^5.0.0", "vite-plus": "*" }, "optionalPeers": ["@astrojs/compiler-rs", "svelte", "vite-plus"], "bin": { "oxfmt": "bin/oxfmt" } }, "sha512-92iLHGxAgtYk6jLp/1ZBnEeABveNduHZgMDQj7tyqO9iafuJG3q+YHJq0R5Aa4YT+E6xswMQXdmPZYMwynS8ig=="], + + "oxlint": ["oxlint@1.94.0", "", { "optionalDependencies": { "@oxlint/binding-android-arm-eabi": "1.94.0", "@oxlint/binding-android-arm64": "1.94.0", "@oxlint/binding-darwin-arm64": "1.94.0", "@oxlint/binding-darwin-x64": "1.94.0", "@oxlint/binding-freebsd-x64": "1.94.0", "@oxlint/binding-linux-arm-gnueabihf": "1.94.0", "@oxlint/binding-linux-arm-musleabihf": "1.94.0", "@oxlint/binding-linux-arm64-gnu": "1.94.0", "@oxlint/binding-linux-arm64-musl": "1.94.0", "@oxlint/binding-linux-ppc64-gnu": "1.94.0", "@oxlint/binding-linux-riscv64-gnu": "1.94.0", "@oxlint/binding-linux-riscv64-musl": "1.94.0", "@oxlint/binding-linux-s390x-gnu": "1.94.0", "@oxlint/binding-linux-x64-gnu": "1.94.0", "@oxlint/binding-linux-x64-musl": "1.94.0", "@oxlint/binding-openharmony-arm64": "1.94.0", "@oxlint/binding-win32-arm64-msvc": "1.94.0", "@oxlint/binding-win32-ia32-msvc": "1.94.0", "@oxlint/binding-win32-x64-msvc": "1.94.0" }, "peerDependencies": { "oxlint-tsgolint": ">=7.0.2007", "vite-plus": "*" }, "optionalPeers": ["oxlint-tsgolint", "vite-plus"], "bin": { "oxlint": "bin/oxlint" } }, "sha512-Fnt+3wSKRhtLmvgRfxgRX0excSPCoyiXRol4eWKZLtXxWMQtwQ3KjKQUYXOw5loyinfnZfGzh4RCYf7opfL0vw=="], + + "tinypool": ["tinypool@2.2.0", "", {}, "sha512-jBrmx4lYmaC9k/mgPbylxs7kBUxHtD8256up+HjLaDFfXScKJQyil+SWXSvhAtT7XHo+yTVlpB81PGmHP8oLSQ=="], + } +} diff --git a/docs/wiki/Backends.md b/docs/wiki/Backends.md index d04c251..0a24857 100644 --- a/docs/wiki/Backends.md +++ b/docs/wiki/Backends.md @@ -32,9 +32,9 @@ Service modules (`Purview.Containers.PostgreSql`, `Redis`, …) are backend-neut | | WSL Containers | Docker | | --- | --- | --- | | **Package** | `Purview.Containers.Wsl` | `Purview.Containers.Docker` | -| **Prerequisite** | Windows 11 (22H2 or later) or Windows Server 2025 with WSL Containers (`wsl --install --no-distribution`) | any reachable Docker daemon (Docker Desktop, Docker Engine in WSL2, a VM, or a CI runner) | -| **Host OS** | Windows only | Windows, Linux, macOS | -| **Project target framework** | `net10.0` or `net11.0`, any platform (portable facade), or `net10.0-windows10.0.19041.0`/`net11.0-windows10.0.19041.0`, x64 or arm64 (implementation bound directly) | `net10.0` or `net11.0`, any platform | +| **Prerequisite** | an x64 Windows host where WSL 2 runs (Windows 11, Windows 10 2004+, Windows Server 2025) with WSL 3.0.5 or later (`wsl --install --no-distribution` or `wsl --update`); see [host requirements](Consumer-Requirements.md#host-requirements-wsl-containers-backend) | any reachable Docker daemon (Docker Desktop, Docker Engine in WSL2, a VM, or a CI runner) | +| **Host OS** | Windows only, x64 only (no ARM64) | Windows, Linux, macOS | +| **Project target framework** | `net10.0` or `net11.0`, any platform (portable facade), or `net10.0-windows10.0.19041.0`/`net11.0-windows10.0.19041.0`, x64 only (implementation bound directly) | `net10.0` or `net11.0`, any platform | | **How containers run** | the managed SDK, with `wslc` CLI fallback for SDK-missing features | the Docker Engine API via Testcontainers | | **Images** | a shared store (`%LOCALAPPDATA%\Purview\WslContainers\images`) reused across runs; the location is configurable | the daemon's own image store | | **Leak protection** | session disposal plus a process-exit hook | the Testcontainers resource reaper (Ryuk) | @@ -136,8 +136,8 @@ inside a test. WSL Containers: ```powershell -wsl --version # WSL itself -wslc version # the WSLC runtime +wsl --version # WSL itself: 3.0.5 or later ('wsl --update' if older) +wslc version # the WSLC CLI, shipped with WSL (%ProgramFiles%\WSL\wslc.exe) ``` ```csharp @@ -224,17 +224,17 @@ dotnet add package Purview.Containers.Wsl enable - + ``` This project runs WSLC on a Windows host. A platform-neutral `net10.0` or `net11.0` project binds the portable facade; a Windows target framework (`net10.0-windows10.0.19041.0` or -`net11.0-windows10.0.19041.0`, x64 or arm64) binds the implementation directly. +`net11.0-windows10.0.19041.0`, x64 only) binds the implementation directly. `WindowsSdkPackageVersion` is supplied by the package. A project older than -.NET 10 (including .NET 8 and .NET 9) fails the build with `PCC0001`, and a 32-bit Windows consumer with -`PCC0002`; see [Consumer Requirements](Consumer-Requirements.md). +.NET 10 (including .NET 8 and .NET 9) fails the build with `PCC0001`, and a non-x64 (ARM64 or x86) +Windows consumer with `PCC0002`; see [Consumer Requirements](Consumer-Requirements.md). > On a non-Windows host this project has **no usable backend** (the facade reports `wsl` unavailable). > To also run on Docker there, add `Purview.Containers.Docker` or use the umbrella — see Option 3. @@ -253,7 +253,7 @@ dotnet add package Purview.Containers.Docker enable - + ``` @@ -278,7 +278,7 @@ dotnet add package Purview.Containers enable - + ``` @@ -369,7 +369,7 @@ backend when it starts. That is what lets the same test suite run on whichever r To fail loudly instead of falling back — the usual choice in CI — name the backend: -``` +```shell PURVIEW_CONTAINERS_BACKEND=docker # if Docker is not reachable, the test fails and says why ``` @@ -391,8 +391,8 @@ jobs: # Optional. "auto" (the default) also selects Docker when WSL Containers is absent. PURVIEW_CONTAINERS_BACKEND: docker steps: - - uses: actions/checkout@v4 - - uses: actions/setup-dotnet@v4 + - uses: actions/checkout@v7 + - uses: actions/setup-dotnet@v6 with: dotnet-version: 10.0.x - run: dotnet restore @@ -410,8 +410,9 @@ jobs: the probe report instead of quietly selecting something else. For a **Windows** job that should exercise WSLC, use a `windows-2025` runner (Windows Server 2025 with -nested virtualisation). The WSL build with `wslc` is in the pre-release channel and its directory is not on -`PATH`: +nested virtualisation). WSL Containers ships in the stable WSL channel, so `wsl --update` brings the +runner to WSL 3.0.5 or later; the library finds `wslc` at `%ProgramFiles%\WSL\wslc.exe` without a `PATH` +change: ```yaml integration-windows: @@ -423,24 +424,23 @@ nested virtualisation). The WSL build with `wslc` is in the pre-release channel PURVIEW_CONTAINERS_REQUIRE_BACKEND: wsl WSL_UTF8: "1" steps: - - uses: actions/checkout@v4 - - uses: actions/setup-dotnet@v4 + - uses: actions/checkout@v7 + - uses: actions/setup-dotnet@v6 with: dotnet-version: 11.0.x - name: Install WSL Containers shell: pwsh run: | - wsl --update --pre-release + wsl --update wsl --version - $env:PATH = "C:\Program Files\WSL;$env:PATH" & 'C:\Program Files\WSL\wslc.exe' version - run: dotnet restore - run: dotnet build --configuration Release --no-restore - run: dotnet test --configuration Release --no-build --retry-failed-tests 2 --retry-failed-tests-delay 5s ``` -> `windows-2025` is the only hosted runner that supports WSL Containers: Windows Server 2022 and Windows 10 -> are not supported. Windows runners bill at 2×, and a cold runner has to pull every image, so run the fast +> The WSLC suites run on the hosted `windows-2025` runner; GitHub's hosted `windows-2022` runner cannot +> run them. Windows runners bill at 2×, and a cold runner has to pull every image, so run the fast > contract suite on pull requests and the full service-module matrix nightly or on demand. If you run on a > self-hosted Windows runner instead, keep `PURVIEW_CONTAINERS_REQUIRE_BACKEND=wsl` so a host without WSLC > fails rather than silently skipping every test. @@ -480,7 +480,7 @@ release its image-store VHD. Unsupported options throw `ContainerNotSupportedException` rather than being ignored, so a difference between backends never turns into a silently weaker test. -See [Capabilities and Cancellation](Backend-Capabilities.md) for shared APIs, managed deadlines, +See [Capabilities and Cancellation](guide/Backend-Capabilities.md) for shared APIs, managed deadlines, resource ownership and the synchronous-native-call cancellation limitation. ## Troubleshooting @@ -499,8 +499,9 @@ No usable container backend was found (selection: auto). Install or fix a backend, or set PURVIEW_CONTAINERS_BACKEND to one of: wsl, docker. ``` -Fix the runtime it names (for WSLC: `wsl --install --no-distribution`; for Docker: start the daemon, or -point `DOCKER_HOST` at it), or pin the backend that does work. +Fix the runtime it names (for WSLC: `wsl --install --no-distribution`, or `wsl --update` for a WSL older +than 3.0.5; for Docker: start the daemon, or point `DOCKER_HOST` at it), or pin the backend that does work. +Each reason names its own fix. **`The selected container backend 'docker' is not usable: …`** — you named a backend that cannot run here. This is intentional: a named backend never falls back to another one, so a CI job cannot pass by silently @@ -510,7 +511,8 @@ using the wrong runtime. backend whose package is not referenced by the project. **`PCC0001` / `PCC0002`** — a build-time guard from the WSL Containers backend package: the consuming project -is neither .NET 10 nor .NET 11 (Windows or platform-neutral), or is a 32-bit Windows consumer. See +is neither .NET 10 nor .NET 11 (Windows or platform-neutral), or is a non-x64 (ARM64 or x86) Windows +consumer — the backend is x64 only. See [Consumer Requirements](Consumer-Requirements.md), or switch the project to the Docker backend. **The same image is pulled twice** — expected when both runtimes are used: WSLC and Docker keep separate @@ -520,6 +522,6 @@ image stores. - [Getting Started](Getting-Started.md) — install, first container, first typed module. - [Consumer Requirements](Consumer-Requirements.md) — the target-framework contract, the guards and the workarounds. -- [Architecture](Architecture.md#backend-selection) — how resolution and registration work internally. +- [Architecture](contributing/Architecture.md#backend-selection) — how resolution and registration work internally. - [Modules](Modules.md) — the service modules and their readiness strategies. diff --git a/docs/wiki/Consumer-Requirements.md b/docs/wiki/Consumer-Requirements.md index 22c2f4a..f4b78fb 100644 --- a/docs/wiki/Consumer-Requirements.md +++ b/docs/wiki/Consumer-Requirements.md @@ -1,9 +1,8 @@ # Consumer Requirements -> **Experimental.** `Purview.Containers.*` is an experimental project: the public API, the -> defaults and these requirements can change between prereleases, and there is no production -> support guarantee. Treat every version as a preview and pin the exact package version you build -> against. +What a .NET project and its host need to use `Purview.Containers`: the supported target frameworks +(.NET 10 and .NET 11), the WSL Containers host requirements (x64, WSL 3.0.5 or later), and the +`PCC0001`/`PCC0002` build errors that enforce them. The WSL Containers backend package is **multi-target**. It ships Windows builds (`net10.0-windows10.0.19041.0` and `net11.0-windows10.0.19041.0`, the implementations, built on the @@ -21,10 +20,11 @@ the `net11.0` assets, which are compiled with `runtime-async=on` and can use the ## Which package requires what The WSLC SDK-only path keeps its existing prerequisites. Entry-point/user/label overrides, reuse, file -copy and Dockerfile builds additionally require the installed `wslc` CLI on PATH; named networks, +copy and Dockerfile builds additionally require the `wslc` CLI that ships with WSL (found on PATH or at +`%ProgramFiles%\WSL\wslc.exe`); named networks, aliases, Linux capabilities and host loopback use the managed SDK (3.0.5+). The CLI operates in the SDK-owned session/store, not the user's default CLI session. Missing CLI support -fails explicitly, without switching backends. See [Capabilities and Cancellation](Backend-Capabilities.md) +fails explicitly, without switching backends. See [Capabilities and Cancellation](guide/Backend-Capabilities.md) for operation deadlines, resource ownership and native cancellation limits. | Package | Target framework | Notes | @@ -35,7 +35,7 @@ for operation deadlines, resource ownership and native cancellation limits. | `Purview.Containers.Wsl` | `net10.0`, `net11.0`, `net10.0-windows10.0.19041.0` and `net11.0-windows10.0.19041.0` | The WSL Containers backend: portable facades plus the Windows implementations. **The requirements on this page are its contract.** | | `Purview.Containers.Docker` | `net10.0` and `net11.0`, any platform | The Docker backend (Testcontainers). Needs a reachable Docker daemon, not a Windows target framework. | | `Purview.Containers.Environment` | `net10.0` and `net11.0`, any platform | Standalone Docker-compatible CLI bind-sharing resolver; no Aspire, Testcontainers or WSLC dependency. | -| `Purview.Containers.Aspire` | `net10.0` and `net11.0`, any platform | Optional adapter requiring Aspire 13.6.5+ and the Environment package; no backend dependency. | +| `Purview.Containers.Aspire` | `net10.0` and `net11.0`, any platform | Optional adapter requiring Aspire 17.0.0+ and the Environment package; no backend dependency. | The standalone resolver requires a reachable Linux-container daemon through its selected CLI, working credential helpers on `PATH`, and client write access to bind-source directories for verification markers. @@ -65,7 +65,7 @@ backend selection. A Windows-targeting project can be explicit: ```xml net10.0-windows10.0.19041.0 - x64 + x64 10.0.26100.80 ``` @@ -81,9 +81,9 @@ file, and because the defaults only fill in a value when you have not chosen one | --- | --- | --- | | 1 | **.NET 10 or .NET 11** | `Purview.Containers.Wsl` ships `lib/net10.0/` and `lib/net11.0/` (facades) and `lib/net10.0-windows10.0.19041/` and `lib/net11.0-windows10.0.19041/` (implementations). `Purview.Containers` and the service modules ship `lib/net10.0/` and `lib/net11.0/` too. Anything older — including .NET 8 and .NET 9 — is unsupported. | | 2 | **A Windows-specific target framework that names the OS version** (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`) — *only when you want the implementation bound directly; a platform-neutral project binds the facade and still runs WSLC on a Windows host* | The `Microsoft.WSL.Containers` projection only ships Windows assets. `net10.0-windows` on its own is not enough. | -| 3 | **64-bit** (`PlatformTarget` `x64`/`arm64`, or a matching `RuntimeIdentifier`) | The native `wslcsdk.dll` ships for `win-x64` and `win-arm64` only. | +| 3 | **x64** (`PlatformTarget` `x64`, the default, or the `win-x64` `RuntimeIdentifier`) | The Windows implementation is compiled for x64 and only the `win-x64` native `wslcsdk.dll` is deployed. ARM64 and x86 are not supported. | | 4 | **`WindowsSdkPackageVersion` at least `10.0.26100.80`** | The projection is compiled against `Microsoft.Windows.SDK.NET` `10.0.26100.79`; the pack the SDK resolves for a `10.0.19041.0` target framework is older. | -| 5 | **A Windows 11 (22H2 or later) or Windows Server 2025 host with WSL Containers** to actually run containers | The library drives WSLC; it never installs or updates WSL for you. Windows 10 and Windows Server 2022 are not supported by WSL Containers. | +| 5 | **A host that meets the [host requirements](#host-requirements-wsl-containers-backend)** to actually run containers | The library drives WSLC; it never installs or updates WSL for you. | ### 1. .NET 10 or .NET 11 @@ -125,15 +125,22 @@ the implementation was built against, so NuGet selects no compile assets for it. version. (The `Microsoft.WSL.Containers` package itself is `net8.0-windows10.0.19041.0`, which a `net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0` project consumes without issue.) -### 3. 64-bit consumers only +### 3. x64 consumers only -The native WSL Containers SDK is shipped for `win-x64` and `win-arm64` only. A 32-bit (`x86`) -consumer builds but cannot load `wslcsdk.dll` at runtime, so the packages fail the build instead: +The WSL Containers backend supports **x64 only**: the Windows implementation is compiled for x64 and +the package deploys only the `win-x64` native SDK. A Windows-target-framework consumer that is not x64 +(`PlatformTarget` `arm64` or `x86`, or a non-x64 `RuntimeIdentifier` such as `win-arm64`) would fail +to load `wslcsdk.dll` at run time, so the packages fail the build instead: ```text -error PCC0002: Purview.Containers.Wsl requires a 64-bit (x64 or arm64) consumer ... +error PCC0002: Purview.Containers.Wsl requires an x64 consumer on a Windows target framework ... ``` +Remove `PlatformTarget` (x64 is the default), set it to `x64`, or choose the `win-x64` +`RuntimeIdentifier`. A platform-neutral (`net10.0`/`net11.0`) consumer still builds anywhere; in a +non-x64 process the facade reports the backend unavailable ("supports x64 processes only"), so +automatic selection falls through to Docker. + ### 4. Windows SDK targeting pack version `Microsoft.WSL.Containers` 3.0.5's projection references `Microsoft.Windows.SDK.NET` @@ -151,10 +158,40 @@ for you, so you only need it if you want to override the value deliberately. ### 5. Host prerequisites -The build requirements above are host-independent. Running containers needs a Windows 11 (22H2 or later) -or Windows Server 2025 host with WSL Containers installed (`wsl --install --no-distribution`) — see +The build requirements above are host-independent. Running containers needs a host that meets the +[host requirements](#host-requirements-wsl-containers-backend) below — see also [Getting Started](Getting-Started.md). +## Host requirements (WSL Containers backend) + +This is the authoritative list; other pages state the short form and link here. + +1. **x64 only.** The backend runs in x64 processes. ARM64 and x86 are not supported: a Windows-target + consumer fails the build with `PCC0002`, and a platform-neutral consumer in a non-x64 process sees + the backend reported unavailable, so automatic selection falls through to Docker. +2. **WSL 3.0.5 or later**, from the normal stable channel: `wsl --install --no-distribution` for a new + install, or `wsl --update`. WSL Containers has been generally available in the stable channel since + WSL 3.0.1; the `--pre-release` channel is not needed. The floor follows the bundled + `Microsoft.WSL.Containers` SDK (3.0.5) and is checked at run time: an older WSL is reported as + incompatible with "Run 'wsl --update'". +3. **Windows wherever WSL 2 runs:** Windows 11, Windows 10 version 2004 (build 19041) or later with + current updates, or Windows Server 2025. The library carries no Windows-version check of its own — + WSL decides, and an unsupported Windows is reported as `WSL_E_OS_NOT_SUPPORTED` with the fix. +4. **Virtualisation** enabled in the firmware, plus the Windows **Virtual Machine Platform** feature + (`wsl --install --no-distribution` enables it; a restart is required). +5. **The `wslc` CLI** ships with WSL and is needed only for the CLI-backed features (entrypoint, user + and label overrides, file copy, image builds and reuse). The library finds it on PATH or at + `%ProgramFiles%\WSL\wslc.exe`, so no PATH change is needed. + +Tested on Windows 11 23H2 (development) and Windows Server 2025 (the `windows-2025` CI runner); +Windows 10 and Windows Server 2022 are untested. + +A host that falls short is reported with its fix, by `WslContainerBackend.GetInfoAsync()` and in +`ContainerBackendUnavailableException`. For example: "The Virtual Machine Platform Windows feature is +not enabled… run 'wsl --install --no-distribution'…", "WSL 3.0.3 is older than WSL 3.0.5, the +minimum… Run 'wsl --update'.", or, when WSL is newer than the bundled SDK, "Update the +Purview.Containers.Wsl package…". + ## What the packages do for you `Purview.Containers.Wsl` ships two `buildTransitive` MSBuild files. NuGet imports them for **direct and @@ -180,8 +217,8 @@ runs on WSLC locally and Docker in CI with no further configuration: net10.0 - - + + ``` @@ -199,9 +236,9 @@ always wins over these defaults. | Error | Raised by | Meaning | Fix | | --- | --- | --- | --- | | `PCC0001` | the shipped guard target | The consumer's target framework is neither .NET 10/.NET 11 on Windows 10.0.19041.0+ nor a platform-neutral .NET 10/.NET 11 framework | Retarget as above. | -| `PCC0002` | the shipped guard target | The consumer is not 64-bit | Remove your `PlatformTarget`, set it to `x64`/`arm64`, or choose a matching `RuntimeIdentifier`. | +| `PCC0002` | the shipped guard target | The consumer is not x64 (ARM64 and x86 are not supported) | Remove your `PlatformTarget` (x64 is the default), set it to `x64`, or choose the `win-x64` `RuntimeIdentifier`. | | `CS1705` | the C# compiler | `WindowsSdkPackageVersion` is older than the projection requires | Set `WindowsSdkPackageVersion` to `10.0.26100.80` or later. | -| `CS8012` | the C# compiler | A referenced assembly targets a different processor (seen when a consumer forces `x86`) | Use a 64-bit consumer. | +| `CS8012` | the C# compiler | A referenced assembly targets a different processor (seen when a consumer forces `x86`) | Use an x64 consumer. | | `NETSDK1100` | the .NET SDK | A Windows-targeted project is being built on a non-Windows operating system | Set `EnableWindowsTargeting` (see below). | | `CS0234`/`CS0246` for `Microsoft.WSL`/`Purview` types | the C# compiler | The package contributed no compile assets (an unsupported target framework, or an unverified escape hatch) | Fix the target framework; `PCC0001` explains the same problem with a clearer message. | @@ -221,7 +258,7 @@ system, set the EnableWindowsTargeting property to true"*). This is exactly how this repository's own CI works: the shared `purview-dev/build` workflow runs on **`ubuntu-latest`**, so `src/Directory.Build.props` sets `EnableWindowsTargeting=true` and the -pipeline is filtered to `[Category=Unit]`. See [Testing](Testing.md). +pipeline is filtered to `[Category=Unit]`. See [Testing](contributing/Testing.md). What it does and does not do: @@ -269,7 +306,7 @@ unconditionally — every inner build is supported: net10.0;net11.0;net10.0-windows10.0.19041.0 - + ``` @@ -280,7 +317,7 @@ condition is no longer needed. ## Verifying these requirements -`just verify-consumers` packs the solution and builds twenty-five throwaway consumer projects against the +`just verify-consumers` packs the solution and builds twenty-eight throwaway consumer projects against the produced packages, asserting every claim on this page: | Case | Consumer | Expected outcome | @@ -310,6 +347,9 @@ produced packages, asserting every claim on this page: | 23 | a `net10.0` consumer of the Aspire adapter | builds; no backend required | | 24 | a plain `net11.0` consumer of the WSL Containers backend | builds; the `wsl` registration is generated (the runtime-async facade) | | 25 | a `net11.0` consumer of modules with only the umbrella `Purview.Containers` | builds; both registrations are generated (one reference) | +| 26 | `.NET 11` + Windows with `PlatformTarget=arm64` | `PCC0002` — the backend is x64 only | +| 27 | `.NET 11` + Windows with `RuntimeIdentifier=win-arm64` | `PCC0002` — the backend is x64 only | +| 28 | a plain `net10.0` consumer of the WSL Containers backend | builds; the x64 implementation payload (`wslc/`, including `wslcsdk.dll`) is copied to the output | The script is `scripts/verify-consumers.ps1` and it only writes to the temp folder. It needs network access (it restores transitive dependencies from nuget.org), so it is a local/CI-explicit step @@ -318,6 +358,6 @@ rather than part of the `[Category=Unit]` filter. ## Related - [Getting Started](Getting-Started.md) — prerequisites and the first container. -- [Packaging](Packaging.md) — what each package contains, including the `buildTransitive` assets. -- [Testing](Testing.md) — the Linux CI run, the unit filter and the serial WSLC rule. +- [Packaging](contributing/Packaging.md) — what each package contains, including the `buildTransitive` assets. +- [Testing](contributing/Testing.md) — the Linux CI run, the unit filter and the serial WSLC rule. - [Modules](Modules.md) — the service modules that inherit these defaults. diff --git a/docs/wiki/Contributing-Modules.md b/docs/wiki/Contributing-Modules.md index 5610232..905d3f4 100644 --- a/docs/wiki/Contributing-Modules.md +++ b/docs/wiki/Contributing-Modules.md @@ -1,18 +1,19 @@ # Contributing a module -How to add a new service module to `Purview.Containers`. +How to add a new service module to `Purview.Containers`: the configuration record, builder and +container a module provides, what it may and may not contribute, and the tests it needs. ## Files -``` -src/src/MyService/ - MyService.csproj -> PackageId Purview.Containers.MyService - MyServiceConfiguration.cs -> immutable record, module fields - MyServiceBuilder.cs -> fluent builder - MyServiceContainer.cs -> container, connection string / endpoints -src/tests/MyService.UnitTests/ -src/tests/MyService.IntegrationTests/ -``` +| Path | Purpose | +| --- | --- | +| `src/src/MyService/MyService.csproj` | The project; packs as `Purview.Containers.MyService` | +| `src/src/MyService/MyServiceConfiguration.cs` | Immutable configuration record with the module's fields | +| `src/src/MyService/MyServiceBuilder.cs` | The fluent builder | +| `src/src/MyService/MyServiceContainer.cs` | The container, with its connection string and endpoints | +| `src/src/MyService/Sdk/README.md` | The package README | +| `src/tests/MyService.UnitTests/` | Unit tests | +| `src/tests/MyService.IntegrationTests/` | Integration tests against a real container | ## Steps @@ -77,7 +78,7 @@ public class MyServiceBuilder : ContainerBuilder **Experimental.** The API, defaults and packaging rules can change between prereleases; there is no -> production support guarantee. - ## 1. Reference a package | Package | Use it when | @@ -111,7 +111,7 @@ just test '/*/*/*/*[Category=Unit]' # unit tests only (no runtime required) Integration tests need a **running backend**: WSL Containers or a Docker daemon, depending on which you selected. A WSLC session exclusively locks its image-store VHD, so test modules run serially by default — -see [Testing](Testing.md) for the details and how to run a subset. +see [Testing](contributing/Testing.md) for the details and how to run a subset. To see a container start end to end, run one of the samples in this repository: @@ -128,12 +128,12 @@ just pack # build + dotnet pack into ./artifacts just pipeline-pack-validate # shared pipeline: restore, build, lint, test, pack, validate ``` -See [Contributing](Contributing.md) for the full local workflow and [Release Flow](Release-Flow.md) for +See [Contributing](contributing/README.md) for the full local workflow and [Release Flow](contributing/Release-Flow.md) for versioning and publishing. ## Next steps -- [Architecture](Architecture.md) — the session model, concurrency rules and cleanup decisions. -- [Wait Strategies](Wait-Strategies.md) — started vs ready, and composing your own checks. -- [Networking](Networking.md) — port mapping behaviour under WSLC. -- [Packaging](Packaging.md) — what lands in each package. +- [Architecture](contributing/Architecture.md) — the session model, concurrency rules and cleanup decisions. +- [Wait Strategies](guide/Wait-Strategies.md) — started vs ready, and composing your own checks. +- [Networking](guide/Networking.md) — port mapping behaviour under WSLC. +- [Packaging](contributing/Packaging.md) — what lands in each package. diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md index 3891366..22731cd 100644 --- a/docs/wiki/Home.md +++ b/docs/wiki/Home.md @@ -1,29 +1,33 @@ -# Purview.Containers Wiki - -Purview.Containers is a Testcontainers-style library for .NET that runs throwaway Linux containers for -integration testing on **Microsoft WSL Containers (WSLC)** with **no Docker installation**, or on -**Docker** through Testcontainers. The WSLC backend is built directly against the -`Microsoft.WSL.Containers` 3.0.5 managed package, with a bounded `wslc` CLI fallback only for -capabilities the SDK does not expose. See [Capabilities and Cancellation](Backend-Capabilities.md). - -This wiki is the project documentation hub. The packages are published under the -`Purview.Containers.*` package IDs. - -> **Experimental.** This project is an experiment in running throwaway containers through Microsoft -> WSL Containers. The public API, defaults and packaging rules can change between prereleases, and -> there is no production support guarantee. Pin the exact package version you build against and read -> [Consumer Requirements](Consumer-Requirements.md) before adopting it. - -## Start here - -- [Getting Started](Getting-Started.md) -- [Backends: WSLC or Docker](Backends.md) -- [Consumer Requirements](Consumer-Requirements.md) -- [Architecture](Architecture.md) -- [Lifecycle](Lifecycle.md) -- [Networking](Networking.md) -- [Wait Strategies](Wait-Strategies.md) -- [Modules](Modules.md) +# Purview.Containers + +Purview.Containers is a Testcontainers-style .NET library for integration tests that run throwaway +Linux containers on **Microsoft WSL Containers (WSLC)**, with no Docker installation, or on **Docker** +through Testcontainers. The same test code runs on either runtime. The WSLC backend is built directly +against the `Microsoft.WSL.Containers` 3.0.5 managed package, with a bounded `wslc` CLI fallback only for +capabilities the SDK does not expose; see [Capabilities and Cancellation](guide/Backend-Capabilities.md). + +The packages are published under the `Purview.Containers.*` package IDs. + +## Documentation + +| Section | Page | What it answers | +| --- | --- | --- | +| Start | [Getting Started](Getting-Started.md) | Install the packages and run a first container. | +| Start | [Using in Your Tests (auto)](Using-in-Your-Tests.md) | Zero-configuration tests that pick WSLC or Docker themselves. | +| Start | [Backends: WSLC or Docker](Backends.md) | Choosing, pinning and troubleshooting a backend, locally and in CI. | +| Start | [Consumer Requirements](Consumer-Requirements.md) | Target frameworks, host requirements, and the build errors that enforce them. | +| Start | [Modules](Modules.md) | The nine service modules, their defaults and readiness checks. | +| Guide | [Lifecycle](guide/Lifecycle.md) | Start, stop, dispose and cleanup semantics. | +| Guide | [Wait Strategies](guide/Wait-Strategies.md) | Composable readiness checks. | +| Guide | [Networking](guide/Networking.md) | Ports, bridged networking, aliases and host loopback. | +| Guide | [Connection Strings](guide/Connection-Strings.md) | Connection strings and endpoints from a running container. | +| Guide | [Capabilities and Cancellation](guide/Backend-Capabilities.md) | Parity APIs, SDK and CLI boundaries, timeouts and cancellation. | +| Contributing | [Contributing](contributing/README.md) | Build, lint, test and pack locally. | +| Contributing | [Contributing Modules](Contributing-Modules.md) | Adding a new service module. | +| Contributing | [Architecture](contributing/Architecture.md) | How the packages, backends and runtime fit together. | +| Contributing | [Testing](contributing/Testing.md) | Test tiers, the serial-run rule and the CI suites. | +| Contributing | [Packaging](contributing/Packaging.md) | What each package ships and how the manifest is validated. | +| Contributing | [Release Flow](contributing/Release-Flow.md) | Versioning, the pipeline and cutting a release. | ## Packages @@ -64,16 +68,17 @@ This wiki is the project documentation hub. The packages are published under the ## Requirements -- **WSL Containers backend:** Windows 11 (22H2 or later) or Windows Server 2025 with **WSL Containers**, installed via - `wsl --install --no-distribution`. Verified against WSL **3.0.5.0**; `wsl --version` and `wslc version` - should both report 3.0.5.0 or later. +- **WSL Containers backend:** an **x64** Windows host where WSL 2 runs (Windows 11, Windows 10 version + 2004 or later, or Windows Server 2025) with virtualisation enabled and **WSL 3.0.5 or later** from the + stable channel (`wsl --install --no-distribution`, or `wsl --update`). ARM64 is not supported. See + [Host requirements](Consumer-Requirements.md#host-requirements-wsl-containers-backend). - **Docker backend:** any reachable Docker daemon (Docker Desktop, Docker Engine in WSL2, or a CI runner). Verify with `docker info`. - .NET SDK 11 to build (the repository pins `11.0.100` in `global.json`). - A consuming project must be a **.NET 10 or .NET 11** project when it uses the **WSL Containers backend** (**.NET 8 and .NET 9 are not supported**). The recommended shape is platform-neutral (`net10.0` or `net11.0`): it binds the portable facade and gets automatic WSLC-or-Docker selection. A Windows target - framework (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 or arm64) binds the + framework (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 only) binds the implementation directly. The abstractions and the service modules target `net10.0` and `net11.0` and are portable, but they need a backend package to run — see [Backends: WSLC or Docker](Backends.md) for the side-by-side setup. The full contract, the exact errors @@ -81,8 +86,8 @@ This wiki is the project documentation hub. The packages are published under the [Consumer Requirements](Consumer-Requirements.md). ```powershell -wsl --version # WSL Containers installed (verified against 3.0.5.0) -wslc version # e.g. 3.0.5.0 +wsl --version # WSL 3.0.5 or later (run 'wsl --update' if older) +wslc version # ships with WSL (%ProgramFiles%\WSL\wslc.exe); e.g. 3.0.5.0 ``` The library reports missing prerequisites through `WslContainerRuntime.GetInfoAsync()`; it never installs or @@ -124,13 +129,5 @@ example and the troubleshooting reference. | `src/tests` | TUnit unit and integration test projects (WSLC and Docker suites). | | `samples/getting-started` | Runnable WSLC and Docker samples (`just sample-wsl`, `just sample-docker`). | | `docs/wiki` | This wiki, aggregated by the purview-dev website. | -| `purview-build.json` | Shared `Purview.Build` pipeline configuration, including the exhaustive pack manifest. | -| `.agents` | Package-delivered agent skills, agents and prompts. | - -## Workflow - -- [Testing](Testing.md) — unit vs integration categories, session locking, and the serial test rule. -- [Packaging](Packaging.md) — what each package ships and how the pack manifest is validated. -- [Release Flow](Release-Flow.md) — versioning, pipeline commands and the release gate. -- [Contributing](Contributing.md) — build, lint, test and pack locally. -- [Contributing Modules](Contributing-Modules.md) — adding a new service module. +| `.config/purview-build.json` | Shared `Purview.Build` pipeline configuration, including the exhaustive pack manifest. | +| `skills` | The agent skills this repository authors and publishes (`npx skills add purview-dev/containers`). | diff --git a/docs/wiki/Modules.md b/docs/wiki/Modules.md index 46e0b8e..8fd9bcd 100644 --- a/docs/wiki/Modules.md +++ b/docs/wiki/Modules.md @@ -1,11 +1,14 @@ # Modules -Module architecture for `Purview.Containers`. +Typed service modules for .NET integration tests: PostgreSQL, Redis, SQL Server, MySQL, RabbitMQ, +Azurite, NATS and the Azure Key Vault and Service Bus emulators. Each is a thin layer over +`Purview.Containers` that supplies the image, ports, readiness check and connection string, and runs +on WSL Containers or Docker. ## Principle Modules are thin packages layered on the backend-neutral abstractions -([`Purview.Containers.Core`](Architecture.md)). A module supplies only: +([`Purview.Containers.Core`](contributing/Architecture.md)). A module supplies only: - default image - default ports @@ -124,7 +127,7 @@ public sealed class PostgreSqlContainer : ContainerBase Every module builder also registers a connection string provider, so the polymorphic `IContainer.GetConnectionString()` returns the same value as the module's own `GetConnectionString()`. -See [Connection Strings](Connection-Strings.md). `ConnectionMode.Container` (container-to-container) is +See [Connection Strings](guide/Connection-Strings.md). `ConnectionMode.Container` (container-to-container) is not supported yet. Every module exposes `GetConnectionString()` with the same shape it has in Testcontainers, so test code diff --git a/docs/wiki/Using-in-Your-Tests.md b/docs/wiki/Using-in-Your-Tests.md index ffc4dd4..8d7364c 100644 --- a/docs/wiki/Using-in-Your-Tests.md +++ b/docs/wiki/Using-in-Your-Tests.md @@ -13,10 +13,10 @@ a Mac) — nothing changes between them. - - + + - + ``` diff --git a/docs/wiki/_Sidebar.md b/docs/wiki/_Sidebar.md index 67e1d13..71b847d 100644 --- a/docs/wiki/_Sidebar.md +++ b/docs/wiki/_Sidebar.md @@ -1,17 +1,20 @@ - [Home](Home.md) -- [Getting Started](Getting-Started.md) -- [Using in Your Tests (auto)](Using-in-Your-Tests.md) -- [Backends: WSLC or Docker](Backends.md) -- [Capabilities and Cancellation](Backend-Capabilities.md) -- [Consumer Requirements](Consumer-Requirements.md) -- [Architecture](Architecture.md) -- [Lifecycle](Lifecycle.md) -- [Networking](Networking.md) -- [Wait Strategies](Wait-Strategies.md) -- [Connection Strings](Connection-Strings.md) -- [Modules](Modules.md) -- [Testing](Testing.md) -- [Packaging](Packaging.md) -- [Release Flow](Release-Flow.md) -- [Contributing Modules](Contributing-Modules.md) -- [Contributing](Contributing.md) +- **Start** + - [Getting Started](Getting-Started.md) + - [Using in Your Tests (auto)](Using-in-Your-Tests.md) + - [Backends: WSLC or Docker](Backends.md) + - [Consumer Requirements](Consumer-Requirements.md) + - [Modules](Modules.md) +- **Guide** + - [Lifecycle](guide/Lifecycle.md) + - [Wait Strategies](guide/Wait-Strategies.md) + - [Networking](guide/Networking.md) + - [Connection Strings](guide/Connection-Strings.md) + - [Capabilities and Cancellation](guide/Backend-Capabilities.md) +- **Contributing** + - [Contributing](contributing/README.md) + - [Contributing Modules](Contributing-Modules.md) + - [Architecture](contributing/Architecture.md) + - [Testing](contributing/Testing.md) + - [Packaging](contributing/Packaging.md) + - [Release Flow](contributing/Release-Flow.md) diff --git a/docs/wiki/_redirects.yml b/docs/wiki/_redirects.yml new file mode 100644 index 0000000..4972623 --- /dev/null +++ b/docs/wiki/_redirects.yml @@ -0,0 +1,17 @@ +# Moved and removed pages, kept reachable on purview.dev. previous: current +# Either side is a slug or a Markdown path from the docs root. Never remove a released pair; when a +# page moves again, update its destination here rather than chaining redirects. +redirects: + # Grouped into topic folders. + lifecycle: guide/lifecycle + wait-strategies: guide/wait-strategies + networking: guide/networking + connection-strings: guide/connection-strings + backend-capabilities: guide/backend-capabilities + architecture: contributing/architecture + testing: contributing/testing + packaging: contributing/packaging + release-flow: contributing/release-flow + # Removed in b0e31f8; their content now lives in Capabilities and Cancellation. + wslc-api-investigation: guide/backend-capabilities + wslc-capability-matrix: guide/backend-capabilities diff --git a/docs/wiki/Architecture.md b/docs/wiki/contributing/Architecture.md similarity index 72% rename from docs/wiki/Architecture.md rename to docs/wiki/contributing/Architecture.md index 9d66cfb..9bb92ad 100644 --- a/docs/wiki/Architecture.md +++ b/docs/wiki/contributing/Architecture.md @@ -4,43 +4,73 @@ Design for a Testcontainers-style .NET library with pluggable container backends ## Core model -The library is split into a backend-neutral abstraction assembly and one assembly per backend: - -``` -Purview.Containers (net10.0 + net11.0) umbrella: references Core, Wsl and Docker - └─ Purview.Containers.Core (net10.0 + net11.0, portable) the backend-neutral abstractions - ├─ IContainer / IContainerConfiguration / ContainerConfiguration the container contract - ├─ ContainerBuilder fluent configuration + validation - ├─ ContainerBase typed module container (delegates to the backend) - ├─ ContainerBackends + IContainerBackend backend registry and selection - ├─ Waiting / Images / Mounts / Networking / Diagnostics readiness, model, secrets - ├─ IConnectionStringProvider / ConnectionMode / ContainerConnectionStringProvider connection strings - └─ Runtime/ContainerException neutral error taxonomy - -Purview.Containers.Wsl (net10.0 + net11.0 facades, - net10.0 + net11.0 windows10.0.19041.0 implementations) - ├─ WslContainerBackend : IContainerBackend registers itself as "wsl" - ├─ WslContainerRuntime : IContainerRuntime process singleton, owns the shared session - │ ├─ SessionSettings (name, storagePath, cpu/mem, gpu, timeout) - │ ├─ SemaphoreSlim -> serialises session-mutating and container-lifecycle ops - │ ├─ ImageCatalog -> pull policies + keyed dedup of concurrent pulls - │ ├─ PortAllocator -> native random host ports (windowsPort=0) - │ └─ SessionHandle -> Microsoft.WSL.Containers.Session (internal) - ├─ WslContainer : IContainer WSLC-backed container - ├─ WslContainerSession : IContainerSession image pull + container create/start/stop/delete/exec - └─ WslResource / WslCommand / WslFileCopy owned resources; bounded CLI fallback in that same session - -IContainer : IConnectionStringProvider, IAsyncDisposable - StartAsync / StopAsync / DisposeAsync / ExecAsync / GetMappedPublicPort / - GetConnectionString / GetLogsAsync / tailing IAsyncEnumerable - CopyAsync / ReadFileAsync / WaitForExitAsync / DeleteAsync +The library is split into a backend-neutral abstraction assembly and one assembly per backend. Modules +reference the abstractions only; the backend is resolved at run time. + + +```mermaid +flowchart TB + tests([Your tests]) -- references --> umbrella[Purview.Containers] + tests -- references --> modules[Service modules] + umbrella --> core[Purview.Containers.Core] + umbrella --> wsl[Purview.Containers.Wsl] + umbrella --> docker[Purview.Containers.Docker] + modules -- references only --> core + wsl -- implements IContainerBackend --> core + docker -- implements IContainerBackend --> core + wsl -- lifecycle, images, networks --> wslcSdk[Microsoft.WSL.Containers SDK] + wsl -- entrypoint, copy, builds, reuse --> wslcCli[wslc CLI] + wslcSdk --> wslcSession[(WSLC session)] + wslcCli --> wslcSession + docker --> testcontainers[Testcontainers] --> dockerDaemon[(Docker daemon)] ``` +[LikeC4 model](../diagrams/package-architecture.c4) + + +| Package | Target frameworks | Key types | +| --- | --- | --- | +| `Purview.Containers` | `net10.0`, `net11.0` | None: the umbrella references Core, Wsl and Docker | +| `Purview.Containers.Core` | `net10.0`, `net11.0` | `IContainer`, `IContainerConfiguration`/`ContainerConfiguration` (the contract); `ContainerBuilder` (fluent configuration and validation); `ContainerBase` (typed module container); `ContainerBackends`, `IContainerBackend` (registry and selection); `IConnectionStringProvider`, `ConnectionMode`, `ContainerConnectionStringProvider`; `Runtime/ContainerException` (the neutral error taxonomy); the `Waiting`, `Images`, `Mounts`, `Networking` and `Diagnostics` namespaces | +| `Purview.Containers.Wsl` | `net10.0`, `net11.0` facades; `net10.0`/`net11.0-windows10.0.19041.0` x64 implementations | `WslContainerBackend` (registers as `wsl`); `WslContainerRuntime` (process singleton that owns the shared session); `WslContainer`; `WslContainerSession` (pull, create, start, stop, delete, exec); `WslResource`, `WslCommand`, `WslFileCopy` (owned resources and the bounded CLI fallback in the same session); `WslRequirements` (host requirements and their fixes) | +| `Purview.Containers.Docker` | `net10.0`, `net11.0` | `DockerContainerBackend` (registers as `docker`); `DockerContainer`; `DockerEndpoint` (daemon discovery) | + +Inside the WSL backend, one gate in `WslContainerRuntime` serialises every session-mutating and +container-lifecycle operation, `WslContainerSession` de-duplicates concurrent pulls of the same image, +and random host ports are allocated natively (`windowsPort=0`) and read back from the container. + +The container contract every backend implements: + +```csharp +public interface IContainer : IConnectionStringProvider, IAsyncDisposable +{ + string Id { get; } + string Name { get; } + ContainerState State { get; } + string Image { get; } + string? NetworkIp { get; } + + Task StartAsync(CancellationToken cancellationToken = default); + Task StopAsync(CancellationToken cancellationToken = default); + Task DeleteAsync(CancellationToken cancellationToken = default); + Task ExecAsync(string[] command, ExecOptions? options = null, CancellationToken cancellationToken = default); + + ushort GetMappedPublicPort(ushort containerPort); + IReadOnlyDictionary GetMappedPublicPorts(); + + Task GetLogsAsync(LogOutput? stream = null, CancellationToken cancellationToken = default); + IAsyncEnumerable GetLogsAsync(CancellationToken cancellationToken); + + Task CopyAsync(string source, string target, CancellationToken cancellationToken = default); + Task ReadFileAsync(string path, CancellationToken cancellationToken = default); + Task WaitForExitAsync(CancellationToken cancellationToken = default); +} +``` `IContainerBackend.CreateNetworkAsync` and `BuildImageAsync` return owned `IContainerResource` instances on either backend. Docker delegates to Testcontainers. WSLC networks and their deletion use the managed SDK; CLI-backed resources (image builds) target the SDK-owned session/store, while lifecycle, images and network operations remain SDK-backed. Dispose containers before networks/images. See -[Capabilities and Cancellation](Backend-Capabilities.md). +[Capabilities and Cancellation](../guide/Backend-Capabilities.md). A module (`Purview.Containers.PostgreSql`, `Purview.Containers.Redis`, …) derives its container from `ContainerBase` and references `Purview.Containers.Core` only. The backend is resolved at run time through @@ -53,16 +83,18 @@ Microsoft types (`Session`, `Container`, `Process`, `ContainerSettings`, …) ar ## Target frameworks Every package ships `net10.0` and `net11.0` assets. **.NET 8 and .NET 9 are dropped**; the contract is in -[Consumer Requirements](Consumer-Requirements.md). Purview.BuildSdk's `Current` target-framework set -supplies that pair; the repository does not hand-maintain it. +[Consumer Requirements](../Consumer-Requirements.md). Purview.BuildSdk's `Supported` target-framework set +(selected in `src/Directory.Build.props`) supplies that pair; the repository does not hand-maintain it, +and the WSL backend derives its Windows builds from the same set. - `net10.0` is the floor. A consumer that has not moved to .NET 11 keeps the classic compiler-generated async state machines and the .NET 10 library surface. - `net11.0` is compiled with `runtime-async=on` and the C# 15 updated memory-safety rules (`MemorySafetyRules=2`). The runtime manages suspension and resumption instead of compiler-generated state machines, which lowers async overhead and makes live stack traces (profiler, `new StackTrace()`, - debugger) name the real methods. `PurviewRuntimeAsync=false` opts out for a local experiment; - `Wsl.UnitTests/BuildFeatureTests.cs` guards that the shipped default is on. + debugger) name the real methods. Purview.BuildSdk 2.2.0 makes both features opt-in, so + `src/Directory.Build.props` enables them (`PurviewRuntimeAsync=true`, `MemorySafetyRules=2`); + `Wsl.UnitTests/BuildFeatureTests.cs` guards that both are on in the shipped build. - The WSL Containers backend uses the same split for its Windows builds, and a single implementation payload serves both portable targets because a .NET 11 process loads a .NET 10 assembly. @@ -93,7 +125,7 @@ Resolution is cached per process, so probes run once; `Reset()` (tests) and `Reg cache. Package consumers get registration from the generated module initializer in `Purview.Containers.Core.targets`; project-reference consumers register explicitly with `Register(...)`. Consumer-facing guidance (including the CI example) is in -[Backends: WSLC or Docker](Backends.md). +[Backends: WSLC or Docker](../Backends.md). ## Session lifetime model @@ -181,4 +213,4 @@ Isolated stores are transient and are removed when their session terminates. - Public surface deliberately small; WSLC types internal. - One opt-in accessor (`IWslContainerAccessor`) exposes `Inspect()` / raw handle for advanced users. -- Third-party modules subclass the generic builder (see [Modules](Modules.md)). \ No newline at end of file +- Third-party modules subclass the generic builder (see [Modules](../Modules.md)). \ No newline at end of file diff --git a/docs/wiki/Packaging.md b/docs/wiki/contributing/Packaging.md similarity index 91% rename from docs/wiki/Packaging.md rename to docs/wiki/contributing/Packaging.md index bb9c288..cb26e11 100644 --- a/docs/wiki/Packaging.md +++ b/docs/wiki/contributing/Packaging.md @@ -20,7 +20,7 @@ Each package ships exactly: | `buildTransitive/Purview.Containers.Core.props` / `.targets` | **Core (abstractions) package.** Declares the `PurviewContainersBackends` list and turns it into a generated backend initializer in the consuming assembly. | | `buildTransitive/Purview.Containers.Wsl.props` / `.targets` | **WSL Containers backend only.** Defaults `WindowsSdkPackageVersion`/`PlatformTarget` and raises `PCC0001`/`PCC0002` for unsupported consumers. | | `buildTransitive/Purview.Containers.Docker.props` | **Docker backend only.** Adds the Docker backend to the `PurviewContainersBackends` list. | -| `payload/win-x64/*`, `payload/win-arm64/*` | **WSL Containers backend only.** The Windows implementation, the WSLC projection, its Windows SDK dependencies and the native SDK. The portable facades load them at run time on a Windows host; the `buildTransitive` targets copy the matching folder to the consumer output. One payload (built from the lowest Windows target) serves both portable targets, because a .NET 11 process loads a .NET 10 assembly. | +| `payload/win-x64/*` | **WSL Containers backend only.** The Windows implementation, the WSLC projection, its Windows SDK dependencies and the native SDK. The backend is x64 only, so there is no ARM64 payload. The portable facades load them at run time on an x64 Windows host; the `buildTransitive` targets copy the folder to the consumer output. One payload (built from the lowest Windows target) serves both portable targets, because a .NET 11 process loads a .NET 10 assembly. | Portable PDBs are delivered through the `.snupkg`, never inside the `.nupkg`. The umbrella `Purview.Containers` package has no `buildTransitive` of its own: its dependencies' assets flow @@ -31,7 +31,7 @@ transitively. `Purview.Containers.Wsl` ships `lib/net10.0/` and `lib/net11.0/` (the facades), `lib/net10.0-windows10.0.19041/` and `lib/net11.0-windows10.0.19041/` (the implementations), with the `payload/` folders alongside. Every package therefore restores on a portable `net10.0` or `net11.0` project. Consumers must target .NET 10 or -.NET 11; see [Consumer Requirements](Consumer-Requirements.md). +.NET 11; see [Consumer Requirements](../Consumer-Requirements.md). ## Package metadata @@ -94,6 +94,7 @@ alongside the `Sdk/README.md`. Removing content from a package means removing th 3. Add the package to `RequiredContent` in `purview-build.json`. 4. Prove it with `just pack` and `just pipeline-pack-validate`. +> [!IMPORTANT] > **Packaging a backend or a new MSBuild asset?** NuGet only auto-imports `buildTransitive/.props` > and `buildTransitive/.targets`, so an asset named after anything else — including a shorter > product name — is shipped but never applied. A regression here is invisible to the build of this @@ -111,4 +112,4 @@ package with no rule, or a packed entry matched by no glob, fails validation. ## Related - [Release Flow](Release-Flow.md) — how packages are versioned and published. -- [Contributing Modules](Contributing-Modules.md) — the module contract a new package follows. +- [Contributing Modules](../Contributing-Modules.md) — the module contract a new package follows. diff --git a/docs/wiki/Contributing.md b/docs/wiki/contributing/README.md similarity index 78% rename from docs/wiki/Contributing.md rename to docs/wiki/contributing/README.md index b5160b2..f0bc0a9 100644 --- a/docs/wiki/Contributing.md +++ b/docs/wiki/contributing/README.md @@ -5,18 +5,19 @@ request. ## Prerequisites -- Windows with **WSL Containers** for integration tests; see [Getting Started](Getting-Started.md). +- Windows with **WSL Containers** for integration tests; see [Getting Started](../Getting-Started.md). - .NET SDK 11 (pinned in `global.json` as `11.0.100`). -- The library projects split by framework: Purview.BuildSdk's `Current` target-framework set gives the - backend-neutral abstractions and the service modules `net10.0;net11.0` (the `net11.0` build adds - `runtime-async=on` and the C# 15 updated memory-safety rules). +- The library projects split by framework: Purview.BuildSdk's `Supported` target-framework set + (selected in `src/Directory.Build.props`) gives the backend-neutral abstractions and the service + modules `net10.0;net11.0` (the `net11.0` build adds `runtime-async=on` and the C# 15 updated + memory-safety rules, both opted into explicitly in `src/Directory.Build.props`). `src/src/Wsl/Wsl.csproj` is multi-target (`net10.0`/`net11.0` facades plus `net10.0-windows10.0.19041.0`/`net11.0-windows10.0.19041.0` implementations) because the WSL Containers projection is Windows-only. `src/tests` pins the same set to `net11.0-windows10.0.19041.0` (`src/Directory.Build.props`), which also sets `EnableWindowsTargeting=true` so the solution builds on the Linux CI agent. Do not remove that property: without it the shared pipeline fails with `NETSDK1100`. See - [Consumer Requirements](Consumer-Requirements.md). + [Consumer Requirements](../Consumer-Requirements.md). - [just](https://github.com/casey/just) for the repository recipes, and `dotnet tool restore` for the pinned local tools (CSharpier, dotnet-inspect). - [Bun](https://bun.sh) only for `just version` and the commit hook tooling; the commit hook runs @@ -40,7 +41,7 @@ just verify-consumers # build throwaway consumers against the packed p just pipeline-pack-validate # full local gate: restore, build, lint, test, pack, validate ``` -`just scrub` resets the repository (`bin`/`obj`, clean, forced restore, build-server shutdown) when a stale +`just scrub` resets the repository (build-server shutdown, `bin`/`obj` and `artifacts` deleted, forced restore) when a stale restore or compiler state is suspected. ## Commits @@ -57,9 +58,9 @@ A change is not complete until the affected documentation matches: - **`src/src//Sdk/README.md`** — the package's own README, shipped inside the `.nupkg`. Update it whenever a module's public API, defaults, readiness or endpoints change. - **`docs/wiki`** — the user-facing wiki aggregated by the purview-dev website. Update the topic page - ([Consumer Requirements](Consumer-Requirements.md), [Architecture](Architecture.md), - [Lifecycle](Lifecycle.md), [Networking](Networking.md), [Wait Strategies](Wait-Strategies.md), - [Modules](Modules.md), [Testing](Testing.md), [Packaging](Packaging.md), [Release Flow](Release-Flow.md)) + ([Consumer Requirements](../Consumer-Requirements.md), [Architecture](Architecture.md), + [Lifecycle](../guide/Lifecycle.md), [Networking](../guide/Networking.md), [Wait Strategies](../guide/Wait-Strategies.md), + [Modules](../Modules.md), [Testing](Testing.md), [Packaging](Packaging.md), [Release Flow](Release-Flow.md)) and `_Sidebar.md` when adding a page. - **`purview-build.json`** — the exhaustive `PackValidation.RequiredContent` manifest has to keep matching what the packages actually contain; see [Packaging](Packaging.md). @@ -75,6 +76,6 @@ A change is not complete until the affected documentation matches: ## Related -- [Contributing Modules](Contributing-Modules.md) — the module contract for new service packages. +- [Contributing Modules](../Contributing-Modules.md) — the module contract for new service packages. - [Packaging](Packaging.md) — package contents and validation rules. - [Release Flow](Release-Flow.md) — versioning and what CI does on a PR and on release. diff --git a/docs/wiki/Release-Flow.md b/docs/wiki/contributing/Release-Flow.md similarity index 82% rename from docs/wiki/Release-Flow.md rename to docs/wiki/contributing/Release-Flow.md index 924363c..5099d62 100644 --- a/docs/wiki/Release-Flow.md +++ b/docs/wiki/contributing/Release-Flow.md @@ -9,13 +9,13 @@ applies that value to `Version` and `PackageVersion` for every project, so a rel bump — never a manual project-file edit. `package.json` also carries the repository, homepage and issue URLs that end up in each nuspec. -The project is **experimental**, so versions stay on a `-prerelease.N` suffix: consumers should pin an -exact version rather than float, and each bump can change the API or the -[consumer requirements](Consumer-Requirements.md). +Versions use a `-prerelease.N` suffix until the stable 1.0.0 release, which will include the WSL Containers +backend. Until then, consumers should pin an exact version rather than float, and each bump can change +the API or the [consumer requirements](../Consumer-Requirements.md). ## Local commands -The `Justfile` wraps the common steps: +The `Justfile` wraps the common steps. The shared recipes live in `.build/just/` (copied verbatim from the `purview-buildsdk-justfile` skill); the root `Justfile` adds this repository's own: | Command | What it does | | --- | --- | @@ -23,8 +23,8 @@ The `Justfile` wraps the common steps: | `just test` | `dotnet test` across the solution, one test module at a time (see [Testing](Testing.md)). | | `just lint-check` / `just lint-fix` | CSharpier check / format over the repository root. | | `just pack` | Build (Debug) and `dotnet pack` into `./artifacts`. | -| `just verify-consumers` | Pack, then build throwaway consumer projects that assert the published consumer contract ([Consumer Requirements](Consumer-Requirements.md)). | -| `just scrub` | Delete `bin`/`obj`, clean, re-restore with `--force-evaluate`, and shut down the build server. | +| `just verify-consumers` | Pack, then build throwaway consumer projects that assert the published consumer contract ([Consumer Requirements](../Consumer-Requirements.md)). | +| `just scrub` | Shut down the build servers, delete `bin`/`obj` and `artifacts`, and re-restore with `--force-evaluate`. | | `just pipeline-pack-validate` | Shared pipeline: restore, build, lint, test, pack and **validate** the packages, without publishing. | ## The shared pipeline @@ -48,8 +48,9 @@ the run with the failing module's output. ## GitHub Actions -- `.github/workflows/pr.yml` — pull requests build and test via the shared - `purview-dev/build/.github/workflows/purview-build.yml`, with pack and validation enabled. +- `.github/workflows/pr.yml` — pull requests **and every push to `main`** build and test via the shared + `purview-dev/build/.github/workflows/purview-build.yml`, with pack and validation enabled, plus the + Docker and WSLC contract jobs. A push to `main` builds only; it never publishes. - `.github/workflows/release.yml` — a push to a **`release/**` branch** (or a manual `workflow_dispatch`) calls `purview-dev/build/.github/workflows/purview-release.yml` with `release-mode: NuGet`. It evaluates release eligibility and, when eligible, builds, tests, packs, publishes to NuGet and creates the @@ -97,9 +98,9 @@ The shared workflow runs on **`ubuntu-latest`**, so the Linux agent builds the p `src/Directory.Build.props` sets `EnableWindowsTargeting=true`; removing it fails the pipeline with `NETSDK1100`. The agent has no WSL Containers, which is why the pipeline is filtered to `[Category=Unit]` — see -[Consumer Requirements](Consumer-Requirements.md) and [Testing](Testing.md). +[Consumer Requirements](../Consumer-Requirements.md) and [Testing](Testing.md). ## Related - [Packaging](Packaging.md) — the package contents and the validation manifest. -- [Contributing](Contributing.md) — the local workflow before raising a PR. +- [Contributing](README.md) — the local workflow before raising a PR. diff --git a/docs/wiki/Testing.md b/docs/wiki/contributing/Testing.md similarity index 83% rename from docs/wiki/Testing.md rename to docs/wiki/contributing/Testing.md index b136e2f..2275b5a 100644 --- a/docs/wiki/Testing.md +++ b/docs/wiki/contributing/Testing.md @@ -33,7 +33,7 @@ runtime fails the job instead of skipping every test. > The shared `purview-dev/build` workflow runs on **`ubuntu-latest`**, so the pipeline builds the portable > `net10.0`/`net11.0` projects and the `net11.0-windows…` test projects on Linux. That works because > `src/Directory.Build.props` sets `EnableWindowsTargeting=true`; without it the SDK reports `NETSDK1100`. -> See [Consumer Requirements](Consumer-Requirements.md) for what that workaround does and does not +> See [Consumer Requirements](../Consumer-Requirements.md) for what that workaround does and does not > cover. ```powershell @@ -48,7 +48,7 @@ to Docker, so a WSLC host runs the WSLC suites and a Docker-only host runs the D (`Docker.IntegrationTests` for the container contract, `Modules.Docker.IntegrationTests` for the nine service modules) skip themselves when no daemon is reachable, and the WSLC suites skip themselves when the host lacks the WSL Containers components. Set `PURVIEW_CONTAINERS_REQUIRE_BACKEND=wsl|docker` to turn that -skip into a failure — the CI integration jobs do. See [Backends: WSLC or Docker](Backends.md) for +skip into a failure — the CI integration jobs do. See [Backends: WSLC or Docker](../Backends.md) for consumer-facing setup and CI examples. ```powershell @@ -104,12 +104,14 @@ existed are never deleted, and the shared image store and host bind mounts are u The WSLC half used to be manual-only because no hosted runner was assumed to have WSL Containers. That is no longer true: GitHub's `windows-2025` runner is Windows Server 2025 with hardware nested virtualisation, -and `wsl --update --pre-release` installs a WSL build that includes `wslc`. The binary is not on `PATH`, so -the workflow adds `C:\Program Files\WSL` and calls it by absolute path. +and WSL Containers ships in the stable WSL channel, so `wsl --update` brings the runner to WSL 3.0.5 or +later, including `wslc`. The workflow checks `C:\Program Files\WSL\wslc.exe` and prints its version by +absolute path; the library itself finds `wslc` there without a `PATH` change. Coverage is split for cost: -- **Every pull request**: `pr.yml` runs `Wsl.IntegrationTests` on `windows-2025` (the contract suite). +- **Every pull request and push to `main`**: `pr.yml` runs `Wsl.IntegrationTests` on `windows-2025` + (the contract suite). - **Nightly**: `.github/workflows/integration-wsl.yml` runs the contract suite and the nine service-module suites on `windows-2025`, one project at a time. - **On demand**: the same workflow accepts `runner: self-hosted` to use a warm self-hosted Windows runner @@ -125,10 +127,10 @@ gh run watch ### Hosted runner notes Windows runners bill at 2× and the full module matrix pulls several GB of images on a cold runner, so the -full matrix is nightly rather than per-PR. `windows-2022` and Windows 10 do not support WSL Containers; -`windows-2025` is the only hosted option. The WSLC API surface is pinned by the -`Microsoft.WSL.Containers` package, so a hosted runner with a newer pre-release WSL may report the runtime -as incompatible. The workflow sets `PURVIEW_CONTAINERS_REQUIRE_BACKEND=wsl`, which turns that into a failed +full matrix is nightly rather than per-PR. The WSLC suites run on the hosted `windows-2025` runner; +GitHub's hosted `windows-2022` runner cannot run them. The WSLC API surface is pinned by the +`Microsoft.WSL.Containers` package (3.0.5), so a runner whose WSL is older than that floor, or newer than +the bundled SDK supports, reports the runtime as incompatible. The workflow sets `PURVIEW_CONTAINERS_REQUIRE_BACKEND=wsl`, which turns that into a failed job rather than a green run with every test skipped. ### Self-hosted runner prerequisites @@ -136,10 +138,13 @@ job rather than a green run with every test skipped. Register a **Windows x64** runner for this repository (or organisation) with the labels `self-hosted` and the custom **`wslc`** label, and install on that machine: -- Windows 11 (22H2 or later) or Windows Server 2025 with **WSL Containers**: - `wsl --install --no-distribution`, verified with `wsl --version` and `wslc version`. Windows 10 and - Windows Server 2022 do not support WSL Containers. +- A host that meets the + [host requirements](../Consumer-Requirements.md#host-requirements-wsl-containers-backend): x64, a Windows + where WSL 2 runs, virtualisation enabled, and **WSL 3.0.5 or later** from the stable channel + (`wsl --install --no-distribution` or `wsl --update`), verified with `wsl --version` and `wslc version`. - The **.NET 11 SDK** the repository pins in `global.json` (`11.0.100`). +- GitHub Actions runner **2.327.1 or later**: the workflows use `actions/checkout@v7` and + `actions/setup-dotnet@v6`, which run on Node.js 24. The job's first step prints `wsl --version` and `wslc version`, so a mis-provisioned runner fails immediately instead of surfacing as container timeouts. `actionlint` is told about the custom label in @@ -163,12 +168,12 @@ startup; it cannot substitute for real runtime validation. `Wsl.UnitTests/ConsumerRequirementsTests.cs` guards the shape of the shipped library inside the normal unit run: the Windows build targets `.NETCoreApp,Version=v10.0`, targets `Windows10.0.19041.0` and declares only that OS platform. If the target framework ever drifts, that test fails — and -[Consumer Requirements](Consumer-Requirements.md), the package READMEs and the shipped +[Consumer Requirements](../Consumer-Requirements.md), the package READMEs and the shipped `buildTransitive` defaults all have to move with it. The behavioural side is covered by `just verify-consumers`, which packs the packages and builds throwaway consumer projects for every documented outcome (see -[Consumer Requirements](Consumer-Requirements.md#verifying-these-requirements)). It is deliberately +[Consumer Requirements](../Consumer-Requirements.md#verifying-these-requirements)). It is deliberately outside the `[Category=Unit]` filter because it packs and restores from nuget.org: ```powershell @@ -179,4 +184,4 @@ just verify-consumers -Keep # same, keeping the generated projects for inspec ## Related - [Architecture](Architecture.md) — session lifetime, the concurrency gate and the shared-store fallback. -- [Getting Started](Getting-Started.md) — running the tests locally. +- [Getting Started](../Getting-Started.md) — running the tests locally. diff --git a/docs/wiki/diagrams/package-architecture.c4 b/docs/wiki/diagrams/package-architecture.c4 new file mode 100644 index 0000000..cb73a4a --- /dev/null +++ b/docs/wiki/diagrams/package-architecture.c4 @@ -0,0 +1,77 @@ +// How the Purview.Containers packages fit together, and what each backend drives. +// Rendered on purview.dev in place of the Mermaid diagram in contributing/Architecture.md; +// change both in the same commit. +specification { + element package { + style { + shape rectangle + } + } + element consumer { + style { + shape person + color secondary + } + } + element external { + style { + shape rectangle + color muted + } + } +} + +model { + tests = consumer 'Your tests' { + description 'Reference the umbrella, or one module plus a backend' + } + umbrella = package 'Purview.Containers' { + description 'Umbrella: Core plus both backends, no code of its own' + } + modules = package 'Service modules' { + description 'PostgreSql, Redis, MsSql, MySql, RabbitMq, Azurite, Nats, Key Vault and Service Bus emulators' + } + core = package 'Purview.Containers.Core' { + description 'Backend-neutral contract, builders, wait strategies and ContainerBackends selection' + } + wsl = package 'Purview.Containers.Wsl' { + description 'WSLC backend: portable facades plus the x64 Windows implementation' + } + docker = package 'Purview.Containers.Docker' { + description 'Docker backend over Testcontainers' + } + wslcSdk = external 'Microsoft.WSL.Containers SDK' { + description 'Managed WSLC API' + } + wslcCli = external 'wslc CLI' { + description 'Bounded fallback for SDK-missing features' + } + wslcSession = external 'WSLC session' { + description 'One shared, process-wide session' + } + testcontainers = external 'Testcontainers' + dockerDaemon = external 'Docker daemon' + + tests -> umbrella 'references' + tests -> modules 'references' + umbrella -> core + umbrella -> wsl + umbrella -> docker + modules -> core 'references only' + wsl -> core 'implements IContainerBackend' + docker -> core 'implements IContainerBackend' + wsl -> wslcSdk 'lifecycle, images, networks' + wsl -> wslcCli 'entrypoint, copy, builds, reuse' + wslcSdk -> wslcSession + wslcCli -> wslcSession + docker -> testcontainers + testcontainers -> dockerDaemon +} + +views { + view packageArchitecture { + title 'Package architecture' + include * + autoLayout TopBottom + } +} diff --git a/docs/wiki/Backend-Capabilities.md b/docs/wiki/guide/Backend-Capabilities.md similarity index 98% rename from docs/wiki/Backend-Capabilities.md rename to docs/wiki/guide/Backend-Capabilities.md index 5e9b389..2c755f2 100644 --- a/docs/wiki/Backend-Capabilities.md +++ b/docs/wiki/guide/Backend-Capabilities.md @@ -1,5 +1,8 @@ # Backend capabilities and cancellation +Which container features `Purview.Containers` supports on WSL Containers and on Docker, where the +WSLC backend uses the managed SDK or the `wslc` CLI, and how timeouts and cancellation behave. + The Docker backend is implemented with Testcontainers for .NET. WSLC uses `Microsoft.WSL.Containers` 3.0.5 for lifecycle, images, named networks and aliases, Linux capabilities and session host-loopback support, with the `wslc` CLI only for capabilities missing from the managed diff --git a/docs/wiki/Connection-Strings.md b/docs/wiki/guide/Connection-Strings.md similarity index 96% rename from docs/wiki/Connection-Strings.md rename to docs/wiki/guide/Connection-Strings.md index daa3b26..c133fe5 100644 --- a/docs/wiki/Connection-Strings.md +++ b/docs/wiki/guide/Connection-Strings.md @@ -66,4 +66,4 @@ provider used before `Configure` throws `ConnectionStringProviderNotConfiguredEx ## Module reference -See [Modules](Modules.md) for each module's default connection string and any extra endpoint accessors. +See [Modules](../Modules.md) for each module's default connection string and any extra endpoint accessors. diff --git a/docs/wiki/Lifecycle.md b/docs/wiki/guide/Lifecycle.md similarity index 96% rename from docs/wiki/Lifecycle.md rename to docs/wiki/guide/Lifecycle.md index 04f646b..d5a812e 100644 --- a/docs/wiki/Lifecycle.md +++ b/docs/wiki/guide/Lifecycle.md @@ -1,6 +1,7 @@ # Lifecycle -Container lifecycle semantics for `Purview.Containers`. +How a `Purview.Containers` test container starts, stops and is disposed on WSL Containers or Docker: +the state model, cleanup guarantees, startup deadlines and container reuse. ## Public API diff --git a/docs/wiki/Networking.md b/docs/wiki/guide/Networking.md similarity index 95% rename from docs/wiki/Networking.md rename to docs/wiki/guide/Networking.md index 8c4e882..1adff28 100644 --- a/docs/wiki/Networking.md +++ b/docs/wiki/guide/Networking.md @@ -1,5 +1,8 @@ # Networking +Container networking in `Purview.Containers` on WSL Containers and Docker: bridged networking, +mapped host ports, managed networks with alias DNS, and WSLC host loopback. + Containers default to `ContainerNetworkingMode.Bridged`. The default WSLC bridge supports container-to-container IP traffic but not container-name DNS. `None` disables networking. diff --git a/docs/wiki/Wait-Strategies.md b/docs/wiki/guide/Wait-Strategies.md similarity index 60% rename from docs/wiki/Wait-Strategies.md rename to docs/wiki/guide/Wait-Strategies.md index 319a87a..4ff7b95 100644 --- a/docs/wiki/Wait-Strategies.md +++ b/docs/wiki/guide/Wait-Strategies.md @@ -2,31 +2,36 @@ Composable readiness waits. **A started WSLC container is not necessarily a ready service** — `Container.Start()` returns once the init process is running; readiness is checked separately. -> **Status: implemented.** Verified by integration tests (`tests/Wsl.IntegrationTests/WaitStrategyTests.cs`). - ## Model +Every strategy implements `IWaitStrategy`, and the built-in ones derive from `WaitStrategy`, which adds +the fluent `WithTimeout`, `WithInterval` and `WithRetries`: + +```csharp +public interface IWaitStrategy +{ + TimeSpan? Timeout { get; } // null: the container's StartupTimeout + TimeSpan Interval { get; } // default 250 ms + int? Retries { get; } // optional maximum number of failed checks + + Task UntilAsync(WaitContext context, CancellationToken cancellationToken); +} + +// WaitContext: Container, NetworkIp, GetHostPort(ushort containerPort), FirstHostPort ``` -IWaitStrategy - TimeSpan? Timeout // null → container StartupTimeout - TimeSpan Interval // default 250 ms - int? Retries // optional max failed checks - Task UntilAsync(WaitContext context, CancellationToken ct) - -WaitContext { IContainer Container; string? NetworkIp; int? GetHostPort(ushort); int? FirstHostPort; } - -Wait (factory) - ForContainerRunning() - ForExitCode(long expectedExitCode = 0) - ForTcpPort(ushort containerPort, TimeSpan? connectTimeout = null) - ForHttp(string path = "/") → HttpWaitStrategy { ForPort, ForScheme, ForStatusCode, ForStatusPredicate, ForHeader, AllowInsecureTls } - ForLogMessage(string) | ForLogMessage(Regex) - ForCommand(params string[]) → CommandWaitStrategy { ForExitCode } - ForCustom(Func>) - ForAll(params IWaitStrategy[]) | ForAny(params IWaitStrategy[]) - -WaitStrategy.WithTimeout / .WithInterval / .WithRetries (fluent) -``` + +The `Wait` factory creates them: + +| Factory | Ready when | +| --- | --- | +| `Wait.ForContainerRunning()` | The init process is running (not a service-readiness check) | +| `Wait.ForExitCode(long exitCode = 0)` | A one-shot container exits with the expected code | +| `Wait.ForTcpPort(ushort containerPort, TimeSpan? connectTimeout = null)` | A TCP connection to the mapped host port succeeds | +| `Wait.ForHttp(string path = "/")` | An HTTP(S) request succeeds; returns `HttpWaitStrategy` with `ForPort`, `ForScheme`, `ForStatusCode`, `ForStatusPredicate`, `ForHeader` and `AllowInsecureTls` | +| `Wait.ForLogMessage(string)`, `Wait.ForLogMessage(Regex)` | The container output contains the message | +| `Wait.ForCommand(params string[] command)` | A command run in the container succeeds. It returns `WaitStrategy`; the instance is a `CommandWaitStrategy`, whose `ForExitCode(int)` sets a different expected code | +| `Wait.ForCustom(Func>)` | Your predicate returns `true` | +| `Wait.ForAll(params IWaitStrategy[])`, `Wait.ForAny(params IWaitStrategy[])` | Every one, or any one, of the strategies is ready | - Waits run inside `StartAsync()` after the container starts. `StartAsync` only returns once every configured strategy is ready (or throws `ContainerTimeoutException`). - Default timeout = the container's `StartupTimeout` (5 min). This is also the total managed startup diff --git a/docs/wiki/index.md b/docs/wiki/index.md deleted file mode 100644 index 434f717..0000000 --- a/docs/wiki/index.md +++ /dev/null @@ -1,25 +0,0 @@ -# Purview Containers - -Throwaway Linux containers for .NET integration testing — Testcontainers-style APIs for **Microsoft WSL -Containers (WSLC)** with no Docker installation, and for **Docker** through Testcontainers. The same test -code runs on either runtime; see [Backends: WSLC or Docker](Backends.md). - -[Get started](Getting-Started.md){ .md-button .md-button--primary } -[Choose a backend](Backends.md){ .md-button } - -## Guides - -- [Getting Started](Getting-Started.md) -- [Using in your tests (auto)](Using-in-Your-Tests.md) -- [Backends: WSLC or Docker](Backends.md) -- [Consumer requirements](Consumer-Requirements.md) -- [Architecture](Architecture.md) -- [Lifecycle](Lifecycle.md) -- [Networking](Networking.md) -- [Wait strategies](Wait-Strategies.md) -- [Modules](Modules.md) -- [Testing](Testing.md) -- [Packaging](Packaging.md) -- [Release flow](Release-Flow.md) -- [Contributing modules](Contributing-Modules.md) -- [Contributing](Contributing.md) diff --git a/global.json b/global.json index a12bdeb..4a0ba47 100644 --- a/global.json +++ b/global.json @@ -5,7 +5,7 @@ "allowPrerelease": false }, "msbuild-sdks": { - "Purview.BuildSdk": "2.0.0" + "Purview.BuildSdk": "2.2.0" }, "test": { "runner": "Microsoft.Testing.Platform" diff --git a/package.json b/package.json index 913bebf..27175ea 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "containers", - "version": "1.0.0-prerelease.13", + "version": "1.0.0-prerelease.14", "description": "Testcontainers-style library for .NET that runs throwaway Linux containers for integration testing, on Microsoft WSL Containers or Docker.", "license": "MIT", "author": { @@ -14,5 +14,9 @@ "repository": { "type": "git", "url": "git+https://github.com/purview-dev/containers.git" + }, + "devDependencies": { + "oxfmt": "^0.79.0", + "oxlint": "^1.94.0" } } \ No newline at end of file diff --git a/samples/getting-started/AutoSample/AutoSample.csproj b/samples/getting-started/AutoSample/AutoSample.csproj index 4b7fd83..52c2d7b 100644 --- a/samples/getting-started/AutoSample/AutoSample.csproj +++ b/samples/getting-started/AutoSample/AutoSample.csproj @@ -22,6 +22,23 @@ + + + + + + 10.0.26100.80 enable enable diff --git a/scripts/verify-consumers.ps1 b/scripts/verify-consumers.ps1 index 668f36b..e575b83 100644 --- a/scripts/verify-consumers.ps1 +++ b/scripts/verify-consumers.ps1 @@ -37,6 +37,9 @@ 23 net10.0 + Aspire adapter -> builds, no backend required 24 plain net11.0 + WSL backend (the runtime-async facade) -> builds, wsl registration generated 25 net11.0 + umbrella Purview.Containers + modules (one ref) -> builds, both registrations generated + 26 net11 windows + PlatformTarget=arm64 -> fails PCC0002 (the backend is x64 only) + 27 net11 windows + RuntimeIdentifier=win-arm64 -> fails PCC0002 (the backend is x64 only) + 28 plain net10.0 + WSL backend (portable facade) -> builds, x64 payload (wslc/) copied .PARAMETER FeedPath Folder holding the packed .nupkg files. Defaults to /artifacts. @@ -500,6 +503,17 @@ public static class Program -Items $umbrellaItems ` -Sources @{ 'Smoke.Auto.cs' = $autoSource } ` -RequireText @('WslContainerBackend.Create()', 'DockerContainerBackend.Create()') + + New-ConsumerCase -Id '26' -Name 'net11 windows + PlatformTarget=arm64 (x64 only)' ` + -Properties "$sdkVersionarm64" -Expect 'PCC0002' + + New-ConsumerCase -Id '27' -Name 'net11 windows + RuntimeIdentifier=win-arm64 (x64 only)' ` + -Properties "$sdkVersionwin-arm64" -Expect 'PCC0002' + + New-ConsumerCase -Id '28' -Name 'plain net10.0 + WSL backend copies the x64 payload' ` + -Framework 'net10.0' ` + -Sources @{ 'Smoke.Portable.cs' = $portableSource } ` + -RequireFile 'wslcsdk.dll' ) diff --git a/skills-lock.json b/skills-lock.json index 2109813..c7c73c0 100644 --- a/skills-lock.json +++ b/skills-lock.json @@ -1,131 +1,149 @@ { - "version": 2, + "version": 1, "skills": { - "purview-architecture": { - "source": "purview-dev/engineering-playbook", + "add-catalogue-project": { + "source": "purview-dev/purview-dev", "sourceType": "github", - "skillPath": "skills/purview-architecture/SKILL.md", - "computedHash": "2500e935ff2ccb350f26ebb9be321dc9f99800121aa9412fdc597f95c2c465c8" + "skillPath": "skills/add-catalogue-project/SKILL.md", + "computedHash": "015f5c8a22346676710b774a1b4110e9172c2b6817e7de0113682004fafe9610" }, - "purview-architecture-testing": { - "source": "purview-dev/engineering-playbook", + "add-project-intake": { + "source": "purview-dev/purview-dev", "sourceType": "github", - "skillPath": "skills/purview-architecture-testing/SKILL.md", - "computedHash": "23af6d9baeb408e1e3f4034cef6539d7efa3fecb1b4da918cb539bd8dfbd5a00" + "skillPath": "skills/add-project-intake/SKILL.md", + "computedHash": "86a3326465defe4b1f15f228009137a99735e981c3de99eff52211975ce22368" + }, + "audit-catalogue-projects": { + "source": "purview-dev/purview-dev", + "sourceType": "github", + "skillPath": "skills/audit-catalogue-projects/SKILL.md", + "computedHash": "a6e763e87018419d3688f00d72e84f062284dba8cc037a673d15e4ca308a82fb" + }, + "docs-aggregation-rules": { + "source": "purview-dev/purview-dev", + "sourceType": "github", + "skillPath": "skills/docs-aggregation-rules/SKILL.md", + "computedHash": "569fdb2ea736d5e5727cd8a1341495355511b317874f6e0c6c86f7f0780a44ad" + }, + "github-repo-metadata": { + "source": "purview-dev/purview-dev", + "sourceType": "github", + "skillPath": "skills/github-repo-metadata/SKILL.md", + "computedHash": "f9123757d3dba91141e5384fa28161d151f5121b3aa9846f30142a74804f4945" + }, + "project-manifest-reference": { + "source": "purview-dev/purview-dev", + "sourceType": "github", + "skillPath": "skills/project-manifest-reference/SKILL.md", + "computedHash": "f0b43eddb34866e6869047c1641fa90bc099475cfddab888cab3feba74d3dd0c" }, "purview-buildsdk-adoption": { "source": "purview-dev/build-sdk", "sourceType": "github", "skillPath": "skills/purview-buildsdk-adoption/SKILL.md", - "computedHash": "d90f4aeacaa6aab263d6e6096fec9c49e50e3869798325c0e8b7e0b74fde2987" + "computedHash": "41e63a4e8bc212e21224dac2628ab835d24784a31a4e70ad8a517e7f8801128e" }, "purview-buildsdk-configuration": { "source": "purview-dev/build-sdk", "sourceType": "github", "skillPath": "skills/purview-buildsdk-configuration/SKILL.md", - "computedHash": "c3bb16976c92287262fba1d8c09ecad2c2e3a87ba958c8f3d7b59336c94118f1" + "computedHash": "2a44c84025cc6342f928b2e91b4157bbd340657a1f0b1de80b133f1f106e0e53" + }, + "purview-buildsdk-docs-sync": { + "source": "purview-dev/build-sdk", + "sourceType": "github", + "skillPath": "skills/purview-buildsdk-docs-sync/SKILL.md", + "computedHash": "24d5e86ee5f3877b519c0f85be21c20ad47c051156debe72a42e6f025e3c345d" + }, + "purview-buildsdk-justfile": { + "source": "purview-dev/build-sdk", + "sourceType": "github", + "skillPath": "skills/purview-buildsdk-justfile/SKILL.md", + "computedHash": "fc0ae370f56320723ed3dd4fc0d3851cb876de250035583ac35ecbc4f2374e26" + }, + "purview-buildsdk-msbuild-properties": { + "source": "purview-dev/build-sdk", + "sourceType": "github", + "skillPath": "skills/purview-buildsdk-msbuild-properties/SKILL.md", + "computedHash": "e1dde3293f2a003b4e8f6d2ea418405684add2f7cfa6ec2f53bb3415d8f326ed" }, "purview-buildsdk-project-detection": { "source": "purview-dev/build-sdk", "sourceType": "github", "skillPath": "skills/purview-buildsdk-project-detection/SKILL.md", - "computedHash": "1821fcce1adebd46e56a832988e4c400c73eee3f9f5100c9a1a338666f8d74da" + "computedHash": "15a8581770e22b49e867e82cf02d606d15949e00d221bace997fa87f8e7e7d76" }, "purview-buildsdk-project-layout": { "source": "purview-dev/build-sdk", "sourceType": "github", "skillPath": "skills/purview-buildsdk-project-layout/SKILL.md", - "computedHash": "758ce881a2ffe6aee4cb9bacb5feae07b8cc993d1eabe34b5576db2cdef3d1ab" + "computedHash": "392e9be03d076322090cabfa4062afa2755dd25ee9a98e3896d05773628ddb92" }, "purview-buildsdk-repository-review": { "source": "purview-dev/build-sdk", "sourceType": "github", "skillPath": "skills/purview-buildsdk-repository-review/SKILL.md", - "computedHash": "b5f83029c4eaa8153db80ca686ea970e6bf5cb5f2d55d9e0971174f6fa2cb188" + "computedHash": "cc41baaf97b63639352894b726e3f92b6f2cd757862f8af008c81972aa989b2d" + }, + "purview-buildsdk-settings-docs-sync": { + "source": "purview-dev/build-sdk", + "sourceType": "github", + "skillPath": "skills/purview-buildsdk-settings-docs-sync/SKILL.md", + "computedHash": "76d5dd5b32a0937af024afe92132e221b8947f7cd11a29176bb606f772e2ed5a" }, "purview-buildsdk-skill-installation": { "source": "purview-dev/build-sdk", "sourceType": "github", "skillPath": "skills/purview-buildsdk-skill-installation/SKILL.md", - "computedHash": "9389b31fd8ac05c5fa37155cbf5e52c220422ddd496f7995c46ba5ee590ea111" + "computedHash": "9b824ac73ed6e068dc1f4dfa714ff44129cb4c816e9dfa3b8f08ad0eed4d8179" }, "purview-buildsdk-skill-tests": { "source": "purview-dev/build-sdk", "sourceType": "github", "skillPath": "skills/purview-buildsdk-skill-tests/SKILL.md", - "computedHash": "27b3520ced5c5a8009cfb47149f0fc1826246275d3ec2991667e1543b011d657" + "computedHash": "2f6c1a04975389723cc85093f9e15fc56248afa70f9c003b74bd53875cbb1f1f" }, - "purview-buildsdk-testing": { + "purview-buildsdk-skills-layout": { "source": "purview-dev/build-sdk", "sourceType": "github", - "skillPath": "skills/purview-buildsdk-testing/SKILL.md", - "computedHash": "e7e00ede43f5ee8aa4517329e4fdbde00a5a01bd8e98ea42990c851060bcaf9e" + "skillPath": "skills/purview-buildsdk-skills-layout/SKILL.md", + "computedHash": "1046f7229df832897c6cf80b87c2f6745ea52e89e4e08083a92e6582bb86e742" }, - "purview-component-compatibility": { - "source": "purview-dev/engineering-playbook", - "sourceType": "github", - "skillPath": "skills/purview-component-compatibility/SKILL.md", - "computedHash": "070634caa90d032e2319d6799edbee973be0f9380008917474909328e74f143b" - }, - "purview-engineering-principles": { - "source": "purview-dev/engineering-playbook", - "sourceType": "github", - "skillPath": "skills/purview-engineering-principles/SKILL.md", - "computedHash": "d1b0d2b50e635160f96d03d2790cb725242434bb28b1b47913371bb39d83215b" - }, - "purview-org-harvest": { - "source": "purview-dev/engineering-playbook", - "sourceType": "github", - "skillPath": "skills/purview-org-harvest/SKILL.md", - "computedHash": "040b34d9cd41f23e71dbe1500b0748793377703d1032e1135ed0a3eeeee4a7f8" - }, - "purview-persistence": { - "source": "purview-dev/engineering-playbook", - "sourceType": "github", - "skillPath": "skills/purview-persistence/SKILL.md", - "computedHash": "28e92fa8bccc241ca864b6731148bd721f47699baf3a1a2ec07cce42ed650bae" - }, - "purview-telemetry": { - "source": "purview-dev/engineering-playbook", - "sourceType": "github", - "skillPath": "skills/purview-telemetry/SKILL.md", - "computedHash": "f92aab10e3d2be7b24be559316537ba7d0485d0e479c67f4d5c6126f5f2fc652" - }, - "purview-telemetry-design": { - "source": "purview-dev/telemetry-sourcegenerator", + "purview-buildsdk-testing": { + "source": "purview-dev/build-sdk", "sourceType": "github", - "skillPath": "skills/purview-telemetry-design/SKILL.md", - "computedHash": "5580f584aeee260b51ff1103c4cfebb181ee3025bc2166aa5fae5950c9bdc4e1" + "skillPath": "skills/purview-buildsdk-testing/SKILL.md", + "computedHash": "920a5d4e7ff8c429f4d883044574248f30f2e1df1af2a18d84530b40d1851ddb" }, - "purview-telemetry-diagnostics": { - "source": "purview-dev/telemetry-sourcegenerator", + "purview-site-assessment": { + "source": "purview-dev/purview-dev", "sourceType": "github", - "skillPath": "skills/purview-telemetry-diagnostics/SKILL.md", - "computedHash": "1b9c7119ae9474086489b0a241533fef38d4980a3729d71d18c03c2c2302266a" + "skillPath": "skills/purview-site-assessment/SKILL.md", + "computedHash": "5a119c0bbb680e2183f9bfa9dde0cdb35b14d38a8a1419ef21e4fe981366a11b" }, - "purview-telemetry-migration": { - "source": "purview-dev/telemetry-sourcegenerator", + "purview-site-docs": { + "source": "purview-dev/purview-dev", "sourceType": "github", - "skillPath": "skills/purview-telemetry-migration/SKILL.md", - "computedHash": "b89e05b97313a019bc88bb47fafbe73cc31559056078e5857efef96979a30e87" + "skillPath": "skills/purview-site-docs/SKILL.md", + "computedHash": "aad7582179f21d19780c1053069942b1285ae39f744ea1fae590840c6eb8a94e" }, - "purview-telemetry-multi-targeting": { - "source": "purview-dev/telemetry-sourcegenerator", + "purview-site-integration": { + "source": "purview-dev/purview-dev", "sourceType": "github", - "skillPath": "skills/purview-telemetry-multi-targeting/SKILL.md", - "computedHash": "213bedc6f672b76c3d973dcf6abeb74eb54703ded5beadbdb92f02599a0ec47a" + "skillPath": "skills/purview-site-integration/SKILL.md", + "computedHash": "5c9f6b7fb88efdddbc55d68d817199d227a3d5d01c99df94c3d462a1e7c5a2f8" }, - "purview-telemetry-quickstart": { - "source": "purview-dev/telemetry-sourcegenerator", + "site-validation-loop": { + "source": "purview-dev/purview-dev", "sourceType": "github", - "skillPath": "skills/purview-telemetry-quickstart/SKILL.md", - "computedHash": "ffc12991fcd936f7378c8b9bb49f8d0e309073df0460d41df8d598e7806a5e43" + "skillPath": "skills/site-validation-loop/SKILL.md", + "computedHash": "9d62878fcd457bad46f00d4dc55625ab379551ef1ea3103de90ddc911af8b223" }, - "purview-testing-conventions": { - "source": "purview-dev/engineering-playbook", + "use-case-authoring": { + "source": "purview-dev/purview-dev", "sourceType": "github", - "skillPath": "skills/purview-testing-conventions/SKILL.md", - "computedHash": "e053513db856852a23aad0e22625e1408fdd63377acb793e6d720fe37b9f7214" + "skillPath": "skills/use-case-authoring/SKILL.md", + "computedHash": "078f2b4df03c103b6bbae9edd94d1872483bc1dd0a6a46614d1764650607d80b" } } } diff --git a/skills/purview-containers-capabilities/SKILL.md b/skills/purview-containers-capabilities/SKILL.md index 5e3c197..4163b03 100644 --- a/skills/purview-containers-capabilities/SKILL.md +++ b/skills/purview-containers-capabilities/SKILL.md @@ -14,7 +14,8 @@ metadata: Docker uses Testcontainers for .NET. WSLC ordinarily uses its managed SDK (3.0.5): lifecycle, images, named networks and aliases, Linux capabilities and host loopback are SDK-backed; entrypoint/user/labels, -reuse, image builds and copy need the `wslc` CLI on PATH. The CLI targets the same +reuse, image builds and copy need the `wslc` CLI that ships with WSL (found on PATH or at +`%ProgramFiles%\WSL\wslc.exe`). The CLI targets the same SDK-owned session and image store, not the user's default CLI session. There is no Docker dependency on the WSLC path and no silent runtime fallback when an operation is unsupported. diff --git a/skills/purview-containers-consumer-requirements/SKILL.md b/skills/purview-containers-consumer-requirements/SKILL.md index 977b67f..30b2a37 100644 --- a/skills/purview-containers-consumer-requirements/SKILL.md +++ b/skills/purview-containers-consumer-requirements/SKILL.md @@ -25,7 +25,8 @@ A consumer of any backend other than WSL needs only a portable `net10.0` or `net .NET 9 are unsupported. WSLC features missing from the managed SDK (entrypoint/user/labels, reuse, copy -and Dockerfile builds) additionally require `wslc` on PATH; networks/aliases, Linux capabilities and +and Dockerfile builds) additionally require the `wslc` CLI that ships with WSL (found on PATH or at +`%ProgramFiles%\WSL\wslc.exe`); networks/aliases, Linux capabilities and host loopback use the managed SDK 3.0.5. The ordinary SDK-only path is unchanged. Use `purview-containers-capabilities` for the feature/cancellation boundary. @@ -44,7 +45,7 @@ A Windows-targeting project binds the implementation directly, with no run-time ```xml net10.0-windows10.0.19041.0 - x64 + x64 10.0.26100.80 ``` @@ -59,9 +60,29 @@ value you have not chosen. | --- | --- | --- | | 1 | **.NET 10 or .NET 11** (.NET 8 and .NET 9 are unsupported) | the package ships `lib/net10.0/` and `lib/net11.0/` (facades) plus `lib/net10.0-windows10.0.19041/` and `lib/net11.0-windows10.0.19041/` (implementations) | | 2 | **A Windows target framework that names the OS version** — *only* if you want the implementation bound directly | the `Microsoft.WSL.Containers` projection ships Windows assets only | -| 3 | **64-bit** — `PlatformTarget` `x64`/`arm64`, or a matching `RuntimeIdentifier` | the native `wslcsdk.dll` ships for `win-x64` and `win-arm64` only | +| 3 | **x64** — `PlatformTarget` `x64` (the default), or the `win-x64` `RuntimeIdentifier` | the implementation is compiled for x64 and only the `win-x64` native `wslcsdk.dll` is deployed; ARM64 and x86 are not supported | | 4 | **`WindowsSdkPackageVersion` ≥ `10.0.26100.80`** | the projection is compiled against `Microsoft.Windows.SDK.NET` `10.0.26100.79`, and the pack the SDK resolves for a `10.0.19041.0` target framework is older | -| 5 | **Windows 11 or Windows Server 2025 with WSL Containers**, to actually run anything | the library drives WSLC; it never installs or updates it for you; a Windows target framework does not imply Windows 10 runtime support | +| 5 | **A host that can run WSL Containers**, to actually run anything (see below) | the library drives WSLC; it never installs or updates it for you | + +### Host requirements + +- **x64 only.** A non-x64 Windows-target consumer fails the build with `PCC0002`; a platform-neutral + consumer in a non-x64 process sees `wsl` reported unavailable ("supports x64 processes only"), so + automatic selection falls through to Docker. +- **WSL 3.0.5 or later** from the normal stable channel — `wsl --install --no-distribution` for a new + install, or `wsl --update`. The `--pre-release` channel is not needed. The floor follows the bundled + `Microsoft.WSL.Containers` SDK (3.0.5) and is checked at run time. +- **Windows wherever WSL 2 runs**: Windows 11, Windows 10 version 2004 (build 19041) or later with + current updates, or Windows Server 2025. The library adds no Windows-version check; WSL reports an + unsupported Windows as `WSL_E_OS_NOT_SUPPORTED`. +- **Virtualisation** enabled in firmware plus the Virtual Machine Platform feature + (`wsl --install --no-distribution` enables it; restart required). +- **`wslc`** ships with WSL and is needed only for the CLI-backed features; it is found on PATH or at + `%ProgramFiles%\WSL\wslc.exe`. + +Tested on Windows 11 23H2 and Windows Server 2025; Windows 10 and Windows Server 2022 are untested. +`GetInfoAsync()` and `ContainerBackendUnavailableException` name the fix for each shortfall (for +example "Run 'wsl --update'"). ### Always spell out the Windows version @@ -101,7 +122,7 @@ package, and use `PURVIEW_CONTAINERS_BACKEND` to pin which one runs. | Error | Raised by | Means | Fix | | --- | --- | --- | --- | | `PCC0001` | the shipped guard target | the target framework is neither .NET 10 nor .NET 11 on Windows `10.0.19041.0`+ nor a platform-neutral .NET 10/.NET 11 framework | retarget as above | -| `PCC0002` | the shipped guard target | the consumer is not 64-bit | remove `PlatformTarget`, set it to `x64`/`arm64`, or choose a matching `RuntimeIdentifier` | +| `PCC0002` | the shipped guard target | the consumer is not x64 (ARM64 and x86 are not supported) | remove `PlatformTarget` (x64 is the default), set it to `x64`, or choose the `win-x64` `RuntimeIdentifier` | | `CS1705` naming `Microsoft.Windows.SDK.NET` | the compiler | the resolved Windows SDK targeting pack is older than the projection's | pin `WindowsSdkPackageVersion` to `10.0.26100.80` | | `CS0234`/`CS0246` for `Microsoft.WSL`/`Purview` types | the compiler | the package contributed no compile assets — an unsupported target framework, or an unverified escape hatch | fix the target framework; `PCC0001` says the same thing more clearly | | `NETSDK1100` | the SDK | building a Windows-targeted project on a non-Windows agent | set `EnableWindowsTargeting=true` | @@ -122,7 +143,8 @@ The repository proves every row above rather than asserting it: compiler-generated async state machines (runtime-async is on). If either drifts, the test fails, and this page, the package READMEs and the `buildTransitive` defaults all have to move with it. - `just verify-consumers` proves the **behaviour**: it packs, then builds throwaway consumer projects - for every documented outcome, including the guard errors (`PlatformTarget=x86` → `PCC0002`; + for every documented outcome, including the guard errors (`PlatformTarget=x86`, `PlatformTarget=arm64` + and `RuntimeIdentifier=win-arm64` → `PCC0002`; `net8.0-windows` → `PCC0001`; `net11.0-windows` without an OS version → `PCC0001`). It sits outside the `[Category=Unit]` filter because it restores from nuget.org. diff --git a/skills/purview-containers-quickstart/SKILL.md b/skills/purview-containers-quickstart/SKILL.md index 396d895..0105ffc 100644 --- a/skills/purview-containers-quickstart/SKILL.md +++ b/skills/purview-containers-quickstart/SKILL.md @@ -14,9 +14,6 @@ metadata: Throwaway Linux containers for .NET tests, behind one API, over either **WSL Containers** (no Docker installation on Windows) or **Docker** (anywhere). The same test code runs on both. -> **Experimental and prerelease.** The API, defaults and packaging rules can change between releases. -> Pin the version you adopt. - ## Which package | Package | Use it when | @@ -84,8 +81,13 @@ A **named** backend never silently falls back: if it cannot run, the test fails diagnostics. That is usually what you want in CI. The library never installs a runtime. `WslContainerRuntime.GetInfoAsync()` and -`DockerContainerBackend.GetInfoAsync()` report what is missing. Verify a host with `wsl --version` and -`wslc version`, or `docker info`. +`DockerContainerBackend.GetInfoAsync()` report what is missing and how to fix it. Verify a host with +`wsl --version` and `wslc version`, or `docker info`. + +WSLC needs an **x64** Windows host where WSL 2 runs (Windows 11, Windows 10 version 2004 or later, or +Windows Server 2025) with virtualisation enabled and **WSL 3.0.5 or later** from the stable channel: +`wsl --install --no-distribution`, or `wsl --update`. ARM64 is not supported; on a non-x64 process +`wsl` reports unavailable and automatic selection falls through to Docker. ## A generic container diff --git a/skills/purview-containers-testing/SKILL.md b/skills/purview-containers-testing/SKILL.md index 87d122e..25ef9ec 100644 --- a/skills/purview-containers-testing/SKILL.md +++ b/skills/purview-containers-testing/SKILL.md @@ -73,8 +73,9 @@ Print `wsl --version` and `wslc version` in WSLC jobs so provisioning failures a ## CI shape - **Docker half** — runs on every pull request, on `ubuntu-latest`. -- **WSLC contract** — runs on every pull request on `windows-2025`, with nested virtualisation and - WSL Containers installed by the workflow. +- **WSLC contract** — runs on every pull request on the hosted `windows-2025` runner (GitHub's hosted + `windows-2022` runner cannot run the WSLC suites), with nested virtualisation and the stable WSL + brought to 3.0.5 or later by `wsl --update` in the workflow. - **Full WSLC matrix** — runs nightly on `windows-2025`, or on demand on a hosted or self-hosted runner: ```bash @@ -86,7 +87,8 @@ Print `wsl --version` and `wslc version` in WSLC jobs so provisioning failures a shared WSLC image store is never contended. Use `scope: contract` for the backend contract alone. Self-hosted runner prerequisites: a **Windows x64** runner labelled `self-hosted` and `wslc`, with -WSL Containers installed (`wsl --install --no-distribution`) and the pinned .NET SDK. Tell +virtualisation enabled, WSL 3.0.5 or later from the stable channel (`wsl --install --no-distribution` +or `wsl --update`) and the pinned .NET SDK. ARM64 runners are not supported. Tell `actionlint` about the custom label in `.github/actionlint.yaml`. > The shared pipeline runs on `ubuntu-latest`, so it builds the portable `net10.0`/`net11.0` projects **and** diff --git a/src/Directory.Build.props b/src/Directory.Build.props index f8d7df9..9d74ba1 100644 --- a/src/Directory.Build.props +++ b/src/Directory.Build.props @@ -3,17 +3,36 @@ Purview.Containers true + Supported <_PurviewIsTestSubtree Condition="$([System.String]::Copy('$(MSBuildProjectDirectory)').Replace('\', '/').Contains('/src/tests/'))" >true - net11.0-windows10.0.19041.0 + net11.0-windows10.0.19041.0 + + true + 2 x64 10.0.26100.80 true @@ -29,10 +48,10 @@ purview-logo-light.png README.md - - https://github.com/purview-dev/containers + + https://purview.dev/projects/containers/ diff --git a/src/src/Aspire/Sdk/README.md b/src/src/Aspire/Sdk/README.md index 006112e..7b5ce60 100644 --- a/src/src/Aspire/Sdk/README.md +++ b/src/src/Aspire/Sdk/README.md @@ -1,7 +1,5 @@ # Purview.Containers.Aspire -> **Experimental.** Pin the exact prerelease version; the API and defaults may change. - Apply verified container bind-source resolution to any Aspire AppHost. ```csharp diff --git a/src/src/AzureKeyVaultEmulator/Sdk/README.md b/src/src/AzureKeyVaultEmulator/Sdk/README.md index 6c92a28..cf3975e 100644 --- a/src/src/AzureKeyVaultEmulator/Sdk/README.md +++ b/src/src/AzureKeyVaultEmulator/Sdk/README.md @@ -14,18 +14,16 @@ container can hand out clients that are already wired for the emulator. ## Requirements -- **WSL Containers backend:** Windows 10/11 with WSL Containers (`wsl --install --no-distribution`), and a +- **WSL Containers backend:** an x64 Windows host with WSL 3.0.5 or later (`wsl --install --no-distribution` or `wsl --update`), and a `.NET 10` or `.NET 11` project. A platform-neutral `net10.0` or `net11.0` project binds the portable facade and gets automatic WSLC-or-Docker selection; a Windows target framework - (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 or arm64) binds the implementation directly. The + (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 only; ARM64 is not supported) binds the implementation directly. The `Purview.Containers.Wsl` package supplies `buildTransitive` defaults for `WindowsSdkPackageVersion`/`PlatformTarget` and (for a platform-neutral consumer on a Windows build host) the implementation payload, rejecting an unsupported consumer with `PCC0001`/`PCC0002` — see the [consumer requirements](https://github.com/purview-dev/containers/blob/main/docs/wiki/Consumer-Requirements.md). - **Docker backend:** any reachable Docker daemon (`docker info`), with a `net10.0` or `net11.0` project on any platform. No Windows target framework and no `PCC` guards apply. -- **Experimental:** the API, defaults and packaging can change between prereleases; there is no - production support guarantee. - The emulator is not a replacement for Azure Key Vault; it exists to make developing against it easier. ## Quick start @@ -111,5 +109,5 @@ certificate is installed into the trust store, the default client options work. - [Backends: WSLC or Docker](https://github.com/purview-dev/containers/blob/main/docs/wiki/Backends.md) — choosing and configuring the runtime. - [Modules](https://github.com/purview-dev/containers/blob/main/docs/wiki/Modules.md) — the module contract and readiness choices. -- [Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/Wait-Strategies.md) — overriding readiness checks. +- [Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/guide/Wait-Strategies.md) — overriding readiness checks. - [Azure Key Vault Emulator](https://github.com/james-gould/azure-keyvault-emulator) — the emulator itself. diff --git a/src/src/AzureServiceBusEmulator/Sdk/README.md b/src/src/AzureServiceBusEmulator/Sdk/README.md index f66688b..27c286e 100644 --- a/src/src/AzureServiceBusEmulator/Sdk/README.md +++ b/src/src/AzureServiceBusEmulator/Sdk/README.md @@ -14,10 +14,10 @@ its state in SQL Server), and needs a backend package (`Purview.Containers.Wsl` ## Requirements -- **WSL Containers backend:** Windows 10/11 with WSL Containers (`wsl --install --no-distribution`), and a +- **WSL Containers backend:** an x64 Windows host with WSL 3.0.5 or later (`wsl --install --no-distribution` or `wsl --update`), and a `.NET 10` or `.NET 11` project. A platform-neutral `net10.0` or `net11.0` project binds the portable facade and gets automatic WSLC-or-Docker selection; a Windows target framework - (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 or arm64) binds the implementation directly. The + (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 only; ARM64 is not supported) binds the implementation directly. The `Purview.Containers.Wsl` package supplies `buildTransitive` defaults for `WindowsSdkPackageVersion`/`PlatformTarget` and (for a platform-neutral consumer on a Windows build host) the implementation payload, rejecting an unsupported consumer with `PCC0001`/`PCC0002` — see the @@ -25,11 +25,9 @@ its state in SQL Server), and needs a backend package (`Purview.Containers.Wsl` - **Docker backend:** any reachable Docker daemon (`docker info`), with a `net10.0` or `net11.0` project on any platform. No Windows target framework and no `PCC` guards apply. - **SQL Server sidecar:** the default is SQL Server 2025 (`mcr.microsoft.com/mssql/server:2025-latest`), - which is x64 only and needs at least 2000 MB of memory in the WSLC session VM or Docker host. On ARM64, + which is x64 only and needs at least 2000 MB of memory in the WSLC session VM or Docker host. On an ARM64 Docker host (the WSLC backend is x64 only), `WithSqlServerImage("mcr.microsoft.com/azure-sql-edge:latest")` is an alternative the emulator supports. SQL Server 2022 does not start on WSLC (it fails to create `/.system` as the non-root `mssql` user). -- **Experimental:** the API, defaults and packaging can change between prereleases; there is no - production support guarantee. - The emulator is for local development and testing only; it is not a replacement for Azure Service Bus. ## Quick start @@ -170,7 +168,8 @@ What this module and its tests have established: time and any unconsumed messages are lost with the container. - **Slow, memory-hungry start.** About a minute per instance, and the SQL Server sidecar needs at least 2000 MB. Running several emulators at once multiplies both, which is why sharing one is recommended. -- **x64 only by default.** SQL Server 2025 has no ARM64 image. +- **x64 only by default.** SQL Server 2025 has no ARM64 image (this matters only on an ARM64 Docker + host; the WSLC backend is x64 only). - **Host connections only.** The connection strings point at `127.0.0.1` and the mapped host ports. An application under test that runs in another container cannot use them (`ConnectionMode.Container` is not supported). @@ -207,5 +206,5 @@ known. - [Backends: WSLC or Docker](https://github.com/purview-dev/containers/blob/main/docs/wiki/Backends.md) — choosing and configuring the runtime. - [Modules](https://github.com/purview-dev/containers/blob/main/docs/wiki/Modules.md) — the module contract and readiness choices. -- [Networking](https://github.com/purview-dev/containers/blob/main/docs/wiki/Networking.md) — how containers reach each other by IP. +- [Networking](https://github.com/purview-dev/containers/blob/main/docs/wiki/guide/Networking.md) — how containers reach each other by IP. - [Azure Service Bus Emulator](https://learn.microsoft.com/azure/service-bus-messaging/overview-emulator) — the emulator itself. diff --git a/src/src/Azurite/Sdk/README.md b/src/src/Azurite/Sdk/README.md index 4f9e232..ff6577d 100644 --- a/src/src/Azurite/Sdk/README.md +++ b/src/src/Azurite/Sdk/README.md @@ -12,18 +12,16 @@ See the [Getting Started guide](https://github.com/purview-dev/containers/blob/m ## Requirements -- **WSL Containers backend:** Windows 10/11 with WSL Containers (`wsl --install --no-distribution`), and a +- **WSL Containers backend:** an x64 Windows host with WSL 3.0.5 or later (`wsl --install --no-distribution` or `wsl --update`), and a `.NET 10` or `.NET 11` project. A platform-neutral `net10.0` or `net11.0` project binds the portable facade and gets automatic WSLC-or-Docker selection; a Windows target framework - (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 or arm64) binds the implementation directly. The + (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 only; ARM64 is not supported) binds the implementation directly. The `Purview.Containers.Wsl` package supplies `buildTransitive` defaults for `WindowsSdkPackageVersion`/`PlatformTarget` and (for a platform-neutral consumer on a Windows build host) the implementation payload, rejecting an unsupported consumer with `PCC0001`/`PCC0002` — see the [consumer requirements](https://github.com/purview-dev/containers/blob/main/docs/wiki/Consumer-Requirements.md). - **Docker backend:** any reachable Docker daemon (`docker info`), with a `net10.0` or `net11.0` project on any platform. No Windows target framework and no `PCC` guards apply. -- **Experimental:** the API, defaults and packaging can change between prereleases; there is no - production support guarantee. ## Quick start diff --git a/src/src/Containers/Sdk/README.md b/src/src/Containers/Sdk/README.md index b16e3cb..4e5c43e 100644 --- a/src/src/Containers/Sdk/README.md +++ b/src/src/Containers/Sdk/README.md @@ -59,14 +59,11 @@ not change. - **.NET 10 or .NET 11** (.NET 8 and .NET 9 are not supported). The abstractions and service modules are portable; the WSL Containers backend is multi-target and stays dormant on non-Windows hosts. See the [consumer requirements](https://github.com/purview-dev/containers/blob/main/docs/wiki/Consumer-Requirements.md). -- Either a Windows 10/11 host with **WSL Containers** (`wsl --install --no-distribution`) or a reachable - **Docker** daemon. +- Either an x64 Windows host with **WSL 3.0.5 or later** (`wsl --install --no-distribution` or + `wsl --update`; ARM64 is not supported) or a reachable **Docker** daemon. ## Documentation - [Using it in your tests (auto)](https://github.com/purview-dev/containers/blob/main/docs/wiki/Using-in-Your-Tests.md) - [Backends: WSLC or Docker](https://github.com/purview-dev/containers/blob/main/docs/wiki/Backends.md) - [Modules](https://github.com/purview-dev/containers/blob/main/docs/wiki/Modules.md) - -> **Experimental.** The public API, defaults and packaging rules can change between prereleases; there is -> no production support guarantee. \ No newline at end of file diff --git a/src/src/Core/Sdk/README.md b/src/src/Core/Sdk/README.md index c5d9232..ef1c8d8 100644 --- a/src/src/Core/Sdk/README.md +++ b/src/src/Core/Sdk/README.md @@ -43,7 +43,7 @@ Defaults: total startup 5 minutes; exec/exit wait 1 minute; stop 15 seconds; cle copy/read/log snapshots 1 minute. Fluent timeout overrides and cancellation tokens are supported. Native synchronous WSLC calls cannot be safely interrupted; these are managed deadlines, not a hard runtime isolation guarantee. See the -[capability contract](https://github.com/purview-dev/containers/blob/main/docs/wiki/Backend-Capabilities.md). +[capability contract](https://github.com/purview-dev/containers/blob/main/docs/wiki/guide/Backend-Capabilities.md). ## Backend registration @@ -87,6 +87,3 @@ callers that want to apply their own policy. - [Purview.Containers.Wsl](https://www.nuget.org/packages/Purview.Containers.Wsl) — WSL Containers backend. - Documentation wiki: . - -> **Experimental.** The public API, defaults and packaging rules can change between prereleases, and -> there is no production support guarantee. Pin the exact package version you build against. diff --git a/src/src/Directory.Build.props b/src/src/Directory.Build.props index 80c534b..84b0486 100644 --- a/src/src/Directory.Build.props +++ b/src/src/Directory.Build.props @@ -6,8 +6,9 @@ net10.0 and net11.0: .NET 10 is the lowest consumer that is still supported (.NET 8 and .NET 9 are deliberately dropped), and the net11.0 build lets a .NET 11 consumer bind the .NET 11 assembly instead (runtime-async compilation, .NET 11 library APIs and C# 15 features). That list - is Purview.BuildSdk's `Current` target-framework set - the default when a project declares no - target of its own - so this file must not restate it. Only the WSL Containers backend is + is Purview.BuildSdk's `Supported` target-framework set, selected in the parent + src/Directory.Build.props for every project that declares no target of its own, so this file + must not restate it. Only the WSL Containers backend is Windows-only, so it adds its own Windows target frameworks in its project file. The parent Directory.Build.props still owns the repo-wide identity (NamespacePrefix), the SDK diff --git a/src/src/Docker/DockerContainer.cs b/src/src/Docker/DockerContainer.cs index f722fb1..b70c2a2 100644 --- a/src/src/Docker/DockerContainer.cs +++ b/src/src/Docker/DockerContainer.cs @@ -1,6 +1,5 @@ using System.Diagnostics.CodeAnalysis; using System.Runtime.CompilerServices; -using DotNet.Testcontainers.Configurations; using Purview.Containers.Runtime; using Purview.Containers.Waiting; using TcContainer = DotNet.Testcontainers.Containers.IContainer; @@ -151,9 +150,7 @@ public async Task ExecAsync( // Testcontainers' argv overload cannot supply exec settings and logs argv. Send environment // separately through its Docker client transport rather than embedding secrets in a shell command. - using var client = TestcontainersSettings - .OS.DockerEndpointAuthConfig.GetDockerClientBuilder(Guid.NewGuid()) - .Build(); + using var client = DockerEndpoint.CreateClient(); var created = await client .Exec.CreateContainerExecAsync( Handle.Id, @@ -353,9 +350,7 @@ public async Task DeleteAsync(CancellationToken cancellationToken = default) deadline.Token.ThrowIfCancellationRequested(); if (_handle is not null && !_deleted) { - using var client = TestcontainersSettings - .OS.DockerEndpointAuthConfig.GetDockerClientBuilder(Guid.NewGuid()) - .Build(); + using var client = DockerEndpoint.CreateClient(); try { await client @@ -398,9 +393,7 @@ public async Task WaitForExitAsync(CancellationToken cancellationToken = d async Task ObserveExitAsync() { - using var client = TestcontainersSettings - .OS.DockerEndpointAuthConfig.GetDockerClientBuilder(Guid.NewGuid()) - .Build(); + using var client = DockerEndpoint.CreateClient(); var result = await client.Containers.WaitContainerAsync(Handle.Id, _lifetime.Token).ConfigureAwait(false); return result.StatusCode; } diff --git a/src/src/Docker/DockerContainerBackend.cs b/src/src/Docker/DockerContainerBackend.cs index 54b2192..e75bff9 100644 --- a/src/src/Docker/DockerContainerBackend.cs +++ b/src/src/Docker/DockerContainerBackend.cs @@ -46,14 +46,23 @@ public IContainer CreateContainer(IContainerConfiguration configuration) /// public async Task GetInfoAsync(CancellationToken cancellationToken = default) { + // Testcontainers reports "no daemon discovered" as a null endpoint, not an exception. Discovery + // itself can take several seconds (it probes each configured provider in turn), so the ping + // deadline starts only once an endpoint is known; otherwise a slow discovery would leave the ping + // no time and a healthy daemon would be reported as not responding. + var endpoint = DockerEndpoint.TryResolve(); + if (endpoint is null) + { + return Unavailable(DockerEndpoint.NotFoundMessage); + } + + var probeTimeout = TimeSpan.FromSeconds(10); using var deadline = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken); - deadline.CancelAfter(TimeSpan.FromSeconds(10)); + deadline.CancelAfter(probeTimeout); + try { - // Resolving the endpoint throws when no Docker environment can be discovered, and the ping - // throws when the daemon is not running; both are reported as "unavailable" with the reason. - var endpoint = TestcontainersSettings.OS.DockerEndpointAuthConfig; - using var client = endpoint.GetDockerClientBuilder(Guid.NewGuid()).Build(); + using var client = DockerEndpoint.CreateClient(endpoint); await client.System.PingAsync(deadline.Token).ConfigureAwait(false); var info = await client.System.GetSystemInfoAsync(deadline.Token).ConfigureAwait(false); return new ContainerBackendInfo( @@ -64,16 +73,23 @@ public async Task GetInfoAsync(CancellationToken cancellat [] ); } + catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested) + { + return Unavailable( + $"The Docker daemon at {endpoint.Endpoint} did not respond within {probeTimeout.TotalSeconds:0} seconds. " + + "Check that it is running and reachable, or point DOCKER_HOST at a running daemon." + ); + } catch (Exception exception) when (!cancellationToken.IsCancellationRequested) { - return new ContainerBackendInfo( - Name, - IsAvailable: false, - IsCompatible: false, - Version: string.Empty, - MissingComponents: [$"{exception.GetType().Name}: {exception.Message}"] + return Unavailable( + $"The Docker daemon at {endpoint.Endpoint} could not be reached ({exception.GetType().Name}: {exception.Message}). " + + "Check that it is running, or point DOCKER_HOST at a running daemon." ); } + + ContainerBackendInfo Unavailable(string reason) => + new(Name, IsAvailable: false, IsCompatible: false, Version: string.Empty, MissingComponents: [reason]); } /// @@ -146,8 +162,7 @@ CancellationToken cancellationToken cancellationToken.ThrowIfCancellationRequested(); if (configuration.RegistryCredentials is { } credentials && configuration.PullPolicy != Images.PullPolicy.Never) { - var endpoint = TestcontainersSettings.OS.DockerEndpointAuthConfig; - using var client = endpoint.GetDockerClientBuilder(Guid.NewGuid()).Build(); + using var client = DockerEndpoint.CreateClient(); var pull = configuration.PullPolicy == Images.PullPolicy.Always; if (!pull) { diff --git a/src/src/Docker/DockerEndpoint.cs b/src/src/Docker/DockerEndpoint.cs new file mode 100644 index 0000000..3aa702e --- /dev/null +++ b/src/src/Docker/DockerEndpoint.cs @@ -0,0 +1,34 @@ +using DotNet.Testcontainers.Configurations; +using Purview.Containers.Runtime; + +namespace Purview.Containers.Docker; + +/// +/// The single place the Docker backend resolves Testcontainers' daemon endpoint. Testcontainers returns +/// (rather than throwing) when none of its discovery providers finds a daemon, +/// so every caller would otherwise fail with a bare ; this turns that +/// into a that says what to fix. +/// +static class DockerEndpoint +{ + internal const string NotFoundMessage = + "No Docker daemon was found. Start a Docker-compatible engine (Docker Desktop, Docker Engine, " + + "Rancher Desktop or Podman), or point DOCKER_HOST (or docker.host in ~/.testcontainers.properties) " + + "at a running daemon."; + + /// Resolves the daemon endpoint, or throws a . + internal static IDockerEndpointAuthenticationConfiguration Resolve() => + TryResolve() ?? throw new ContainerBackendUnavailableException(NotFoundMessage); + + /// Resolves the daemon endpoint, or returns when none was discovered. + internal static IDockerEndpointAuthenticationConfiguration? TryResolve() => + TestcontainersSettings.OS?.DockerEndpointAuthConfig; + + /// Creates a Docker client for the resolved endpoint. + internal static global::Docker.DotNet.DockerClient CreateClient() => CreateClient(Resolve()); + + /// Creates a Docker client for . + internal static global::Docker.DotNet.DockerClient CreateClient( + IDockerEndpointAuthenticationConfiguration endpoint + ) => endpoint.GetDockerClientBuilder(Guid.NewGuid()).Build(); +} diff --git a/src/src/Docker/DockerFileCopy.cs b/src/src/Docker/DockerFileCopy.cs index e92d0f8..768725d 100644 --- a/src/src/Docker/DockerFileCopy.cs +++ b/src/src/Docker/DockerFileCopy.cs @@ -1,5 +1,3 @@ -using DotNet.Testcontainers.Configurations; - namespace Purview.Containers.Docker; static class DockerFileCopy @@ -15,9 +13,7 @@ CancellationToken cancellationToken using var archive = await ContainerResourceArchive .CreateAsync(source, target, mode, cancellationToken) .ConfigureAwait(false); - using var client = TestcontainersSettings - .OS.DockerEndpointAuthConfig.GetDockerClientBuilder(Guid.NewGuid()) - .Build(); + using var client = DockerEndpoint.CreateClient(); await client .Containers.ExtractArchiveToContainerAsync( id, diff --git a/src/src/Docker/DockerVolumeCleanup.cs b/src/src/Docker/DockerVolumeCleanup.cs index 65585bd..8971804 100644 --- a/src/src/Docker/DockerVolumeCleanup.cs +++ b/src/src/Docker/DockerVolumeCleanup.cs @@ -1,7 +1,6 @@ using System.Collections.Concurrent; using System.Net; using Docker.DotNet.Models; -using DotNet.Testcontainers.Configurations; using Purview.Containers.Mounts; namespace Purview.Containers.Docker; @@ -167,6 +166,5 @@ static void EnsureProcessExitHook() }; } - static global::Docker.DotNet.DockerClient CreateClient() => - TestcontainersSettings.OS.DockerEndpointAuthConfig.GetDockerClientBuilder(Guid.NewGuid()).Build(); + static global::Docker.DotNet.DockerClient CreateClient() => DockerEndpoint.CreateClient(); } diff --git a/src/src/Docker/Sdk/README.md b/src/src/Docker/Sdk/README.md index 878d074..f824013 100644 --- a/src/src/Docker/Sdk/README.md +++ b/src/src/Docker/Sdk/README.md @@ -61,7 +61,7 @@ PURVIEW_CONTAINERS_BACKEND=docker # or "auto" (the default) to probe WSLC fi one minute for exec/copy/read/log snapshots, 15 seconds for stop and 30 seconds for cleanup. Reuse follows Testcontainers semantics and disables normal reaper cleanup; `DeleteAsync` removes retained containers explicitly. See - [capabilities and ownership](https://github.com/purview-dev/containers/blob/main/docs/wiki/Backend-Capabilities.md). + [capabilities and ownership](https://github.com/purview-dev/containers/blob/main/docs/wiki/guide/Backend-Capabilities.md). - Named volumes created through `WithVolumeMount` are tracked by the backend. Set `ContainerCleanup.CleanUpVolumesOnExit` (or `PURVIEW_CONTAINERS_CLEAN_VOLUMES=true`) before creating containers to force-remove those containers and the volumes the backend created when the process exits; @@ -69,6 +69,3 @@ PURVIEW_CONTAINERS_BACKEND=docker # or "auto" (the default) to probe WSLC fi store and bind mounts are untouched. - Log tailing polls the accumulated output until the container stops, because the Testcontainers API exposes no positioned log stream. - -> **Experimental.** The public API, defaults and packaging rules can change between prereleases, and -> there is no production support guarantee. Pin the exact package version you build against. diff --git a/src/src/Docker/WslDockerHost.cs b/src/src/Docker/WslDockerHost.cs index a1fa43b..30141f2 100644 --- a/src/src/Docker/WslDockerHost.cs +++ b/src/src/Docker/WslDockerHost.cs @@ -1,7 +1,6 @@ using System.ComponentModel; using System.Diagnostics; using System.Text; -using DotNet.Testcontainers.Configurations; namespace Purview.Containers.Docker; @@ -43,13 +42,14 @@ internal string Resolve(string path) internal static WslDockerHost? Detect() { - var endpoint = TestcontainersSettings.OS.DockerEndpointAuthConfig; - if (!OperatingSystem.IsWindows() || !IsLocalTcp(endpoint.Endpoint)) + // No discovered daemon means there is nothing to translate for; starting a container reports it. + var endpoint = DockerEndpoint.TryResolve(); + if (endpoint is null || !OperatingSystem.IsWindows() || !IsLocalTcp(endpoint.Endpoint)) { return null; } - using var client = endpoint.GetDockerClientBuilder(Guid.NewGuid()).Build(); + using var client = DockerEndpoint.CreateClient(endpoint); using CancellationTokenSource timeout = new(TimeSpan.FromSeconds(5)); var info = client.System.GetSystemInfoAsync(timeout.Token).ConfigureAwait(false).GetAwaiter().GetResult(); var distribution = FindDistribution(endpoint.Endpoint, info.KernelVersion, info.OperatingSystem, info.ID, Run); diff --git a/src/src/Environment/Sdk/README.md b/src/src/Environment/Sdk/README.md index 505afed..a6ca33c 100644 --- a/src/src/Environment/Sdk/README.md +++ b/src/src/Environment/Sdk/README.md @@ -1,7 +1,5 @@ # Purview.Containers.Environment -> **Experimental.** Pin the exact prerelease version; the API and defaults may change. - Resolve client-side bind sources against a Docker-compatible daemon without assuming the daemon runs on the client machine. This library has no Aspire or AspireC4 dependency. diff --git a/src/src/MsSql/Sdk/README.md b/src/src/MsSql/Sdk/README.md index f0f4b7d..9346b49 100644 --- a/src/src/MsSql/Sdk/README.md +++ b/src/src/MsSql/Sdk/README.md @@ -11,18 +11,16 @@ connection-string generation and readiness probing. ## Requirements -- **WSL Containers backend:** Windows 10/11 with WSL Containers (`wsl --install --no-distribution`), and a +- **WSL Containers backend:** an x64 Windows host with WSL 3.0.5 or later (`wsl --install --no-distribution` or `wsl --update`), and a `.NET 10` or `.NET 11` project. A platform-neutral `net10.0` or `net11.0` project binds the portable facade and gets automatic WSLC-or-Docker selection; a Windows target framework - (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 or arm64) binds the implementation directly. The + (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 only; ARM64 is not supported) binds the implementation directly. The `Purview.Containers.Wsl` package supplies `buildTransitive` defaults for `WindowsSdkPackageVersion`/`PlatformTarget` and (for a platform-neutral consumer on a Windows build host) the implementation payload, rejecting an unsupported consumer with `PCC0001`/`PCC0002` — see the [consumer requirements](https://github.com/purview-dev/containers/blob/main/docs/wiki/Consumer-Requirements.md). - **Docker backend:** any reachable Docker daemon (`docker info`), with a `net10.0` or `net11.0` project on any platform. No Windows target framework and no `PCC` guards apply. -- **Experimental:** the API, defaults and packaging can change between prereleases; there is no - production support guarantee. ## Quick start diff --git a/src/src/MySql/Sdk/README.md b/src/src/MySql/Sdk/README.md index bd02535..65075fb 100644 --- a/src/src/MySql/Sdk/README.md +++ b/src/src/MySql/Sdk/README.md @@ -11,18 +11,16 @@ connection-string generation. ## Requirements -- **WSL Containers backend:** Windows 10/11 with WSL Containers (`wsl --install --no-distribution`), and a +- **WSL Containers backend:** an x64 Windows host with WSL 3.0.5 or later (`wsl --install --no-distribution` or `wsl --update`), and a `.NET 10` or `.NET 11` project. A platform-neutral `net10.0` or `net11.0` project binds the portable facade and gets automatic WSLC-or-Docker selection; a Windows target framework - (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 or arm64) binds the implementation directly. The + (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 only; ARM64 is not supported) binds the implementation directly. The `Purview.Containers.Wsl` package supplies `buildTransitive` defaults for `WindowsSdkPackageVersion`/`PlatformTarget` and (for a platform-neutral consumer on a Windows build host) the implementation payload, rejecting an unsupported consumer with `PCC0001`/`PCC0002` — see the [consumer requirements](https://github.com/purview-dev/containers/blob/main/docs/wiki/Consumer-Requirements.md). - **Docker backend:** any reachable Docker daemon (`docker info`), with a `net10.0` or `net11.0` project on any platform. No Windows target framework and no `PCC` guards apply. -- **Experimental:** the API, defaults and packaging can change between prereleases; there is no - production support guarantee. ## Quick start @@ -67,4 +65,4 @@ strategy with `WithWaitStrategy(...)` if you need different behaviour. - [Backends: WSLC or Docker](https://github.com/purview-dev/containers/blob/main/docs/wiki/Backends.md) — choosing and configuring the runtime. - [Modules](https://github.com/purview-dev/containers/blob/main/docs/wiki/Modules.md) — the module contract and readiness choices. -- [Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/Wait-Strategies.md) — overriding readiness checks. +- [Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/guide/Wait-Strategies.md) — overriding readiness checks. diff --git a/src/src/Nats/Sdk/README.md b/src/src/Nats/Sdk/README.md index eda60d5..27d2c61 100644 --- a/src/src/Nats/Sdk/README.md +++ b/src/src/Nats/Sdk/README.md @@ -11,18 +11,16 @@ package — bring your own client. ## Requirements -- **WSL Containers backend:** Windows 10/11 with WSL Containers (`wsl --install --no-distribution`), and a +- **WSL Containers backend:** an x64 Windows host with WSL 3.0.5 or later (`wsl --install --no-distribution` or `wsl --update`), and a `.NET 10` or `.NET 11` project. A platform-neutral `net10.0` or `net11.0` project binds the portable facade and gets automatic WSLC-or-Docker selection; a Windows target framework - (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 or arm64) binds the implementation directly. The + (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 only; ARM64 is not supported) binds the implementation directly. The `Purview.Containers.Wsl` package supplies `buildTransitive` defaults for `WindowsSdkPackageVersion`/`PlatformTarget` and (for a platform-neutral consumer on a Windows build host) the implementation payload, rejecting an unsupported consumer with `PCC0001`/`PCC0002` — see the [consumer requirements](https://github.com/purview-dev/containers/blob/main/docs/wiki/Consumer-Requirements.md). - **Docker backend:** any reachable Docker daemon (`docker info`), with a `net10.0` or `net11.0` project on any platform. No Windows target framework and no `PCC` guards apply. -- **Experimental:** the API, defaults and packaging can change between prereleases; there is no - production support guarantee. ## Quick start @@ -56,4 +54,4 @@ with `WithWaitStrategy(...)`. Endpoint accessors resolve the mapped host ports, - [Backends: WSLC or Docker](https://github.com/purview-dev/containers/blob/main/docs/wiki/Backends.md) — choosing and configuring the runtime. - [Modules](https://github.com/purview-dev/containers/blob/main/docs/wiki/Modules.md) — the module contract and readiness choices. -- [Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/Wait-Strategies.md) — overriding readiness checks. +- [Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/guide/Wait-Strategies.md) — overriding readiness checks. diff --git a/src/src/PostgreSql/Sdk/README.md b/src/src/PostgreSql/Sdk/README.md index 68af22c..50e6990 100644 --- a/src/src/PostgreSql/Sdk/README.md +++ b/src/src/PostgreSql/Sdk/README.md @@ -11,18 +11,16 @@ See the [Getting Started guide](https://github.com/purview-dev/containers/blob/m ## Requirements -- **WSL Containers backend:** Windows 10/11 with WSL Containers (`wsl --install --no-distribution`), and a +- **WSL Containers backend:** an x64 Windows host with WSL 3.0.5 or later (`wsl --install --no-distribution` or `wsl --update`), and a `.NET 10` or `.NET 11` project. A platform-neutral `net10.0` or `net11.0` project binds the portable facade and gets automatic WSLC-or-Docker selection; a Windows target framework - (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 or arm64) binds the implementation directly. The + (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 only; ARM64 is not supported) binds the implementation directly. The `Purview.Containers.Wsl` package supplies `buildTransitive` defaults for `WindowsSdkPackageVersion`/`PlatformTarget` and (for a platform-neutral consumer on a Windows build host) the implementation payload, rejecting an unsupported consumer with `PCC0001`/`PCC0002` — see the [consumer requirements](https://github.com/purview-dev/containers/blob/main/docs/wiki/Consumer-Requirements.md). - **Docker backend:** any reachable Docker daemon (`docker info`), with a `net10.0` or `net11.0` project on any platform. No Windows target framework and no `PCC` guards apply. -- **Experimental:** the API, defaults and packaging can change between prereleases; there is no - production support guarantee. ## Quick start @@ -61,4 +59,4 @@ your own with `WithWaitStrategy(...)`. Call `GetConnectionString()` after `Start - [Backends: WSLC or Docker](https://github.com/purview-dev/containers/blob/main/docs/wiki/Backends.md) — choosing and configuring the runtime. - [Modules](https://github.com/purview-dev/containers/blob/main/docs/wiki/Modules.md) — the module contract and readiness choices. -- [Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/Wait-Strategies.md) — overriding readiness checks. +- [Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/guide/Wait-Strategies.md) — overriding readiness checks. diff --git a/src/src/RabbitMq/Sdk/README.md b/src/src/RabbitMq/Sdk/README.md index e5ec9ed..be389a5 100644 --- a/src/src/RabbitMq/Sdk/README.md +++ b/src/src/RabbitMq/Sdk/README.md @@ -11,18 +11,16 @@ bring your own client. ## Requirements -- **WSL Containers backend:** Windows 10/11 with WSL Containers (`wsl --install --no-distribution`), and a +- **WSL Containers backend:** an x64 Windows host with WSL 3.0.5 or later (`wsl --install --no-distribution` or `wsl --update`), and a `.NET 10` or `.NET 11` project. A platform-neutral `net10.0` or `net11.0` project binds the portable facade and gets automatic WSLC-or-Docker selection; a Windows target framework - (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 or arm64) binds the implementation directly. The + (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 only; ARM64 is not supported) binds the implementation directly. The `Purview.Containers.Wsl` package supplies `buildTransitive` defaults for `WindowsSdkPackageVersion`/`PlatformTarget` and (for a platform-neutral consumer on a Windows build host) the implementation payload, rejecting an unsupported consumer with `PCC0001`/`PCC0002` — see the [consumer requirements](https://github.com/purview-dev/containers/blob/main/docs/wiki/Consumer-Requirements.md). - **Docker backend:** any reachable Docker daemon (`docker info`), with a `net10.0` or `net11.0` project on any platform. No Windows target framework and no `PCC` guards apply. -- **Experimental:** the API, defaults and packaging can change between prereleases; there is no - production support guarantee. ## Quick start @@ -68,4 +66,4 @@ startup failure (`eacces` reading `.erlang.cookie`). See - [Backends: WSLC or Docker](https://github.com/purview-dev/containers/blob/main/docs/wiki/Backends.md) — choosing and configuring the runtime. - [Modules](https://github.com/purview-dev/containers/blob/main/docs/wiki/Modules.md) — the module contract and readiness choices. -- [Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/Wait-Strategies.md) — overriding readiness checks. +- [Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/guide/Wait-Strategies.md) — overriding readiness checks. diff --git a/src/src/Redis/Sdk/README.md b/src/src/Redis/Sdk/README.md index 76c9740..92612ed 100644 --- a/src/src/Redis/Sdk/README.md +++ b/src/src/Redis/Sdk/README.md @@ -11,18 +11,16 @@ package — bring your own client. ## Requirements -- **WSL Containers backend:** Windows 10/11 with WSL Containers (`wsl --install --no-distribution`), and a +- **WSL Containers backend:** an x64 Windows host with WSL 3.0.5 or later (`wsl --install --no-distribution` or `wsl --update`), and a `.NET 10` or `.NET 11` project. A platform-neutral `net10.0` or `net11.0` project binds the portable facade and gets automatic WSLC-or-Docker selection; a Windows target framework - (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 or arm64) binds the implementation directly. The + (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 only; ARM64 is not supported) binds the implementation directly. The `Purview.Containers.Wsl` package supplies `buildTransitive` defaults for `WindowsSdkPackageVersion`/`PlatformTarget` and (for a platform-neutral consumer on a Windows build host) the implementation payload, rejecting an unsupported consumer with `PCC0001`/`PCC0002` — see the [consumer requirements](https://github.com/purview-dev/containers/blob/main/docs/wiki/Consumer-Requirements.md). - **Docker backend:** any reachable Docker daemon (`docker info`), with a `net10.0` or `net11.0` project on any platform. No Windows target framework and no `PCC` guards apply. -- **Experimental:** the API, defaults and packaging can change between prereleases; there is no - production support guarantee. ## Quick start @@ -63,4 +61,4 @@ await using var garnet = new RedisBuilder("ghcr.io/microsoft/garnet:latest").Bui - [Backends: WSLC or Docker](https://github.com/purview-dev/containers/blob/main/docs/wiki/Backends.md) — choosing and configuring the runtime. - [Modules](https://github.com/purview-dev/containers/blob/main/docs/wiki/Modules.md) — the module contract and readiness choices. -- [Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/Wait-Strategies.md) — overriding readiness checks. +- [Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/guide/Wait-Strategies.md) — overriding readiness checks. diff --git a/src/src/Wsl/Sdk/README.md b/src/src/Wsl/Sdk/README.md index 52eb8aa..df9cea5 100644 --- a/src/src/Wsl/Sdk/README.md +++ b/src/src/Wsl/Sdk/README.md @@ -5,7 +5,8 @@ throwaway Linux containers for .NET integration testing built directly on the `M 3.0.5 managed API, with **no Docker installation**, Docker.DotNet or Testcontainers dependency. Lifecycle, images, named networks and aliases, Linux capabilities and session host-loopback support all use the managed SDK. Capabilities still missing from it use a bounded `wslc` CLI fallback in the same -session: entrypoint/user/labels, reuse, file copy and Dockerfile builds require `wslc` on PATH. +session: entrypoint/user/labels, reuse, file copy and Dockerfile builds require the `wslc` CLI that +ships with WSL (found on PATH or at `%ProgramFiles%\WSL\wslc.exe`). ```bash dotnet add package Purview.Containers.Wsl @@ -29,13 +30,21 @@ consuming assembly. To also run the same test code on Docker in Linux CI, refere ## Requirements -- Windows 11 or Windows Server 2025 with **WSL Containers** (`wsl --install --no-distribution`). +- **An x64 Windows host where WSL 2 runs** (Windows 11, Windows 10 version 2004 or later with current + updates, or Windows Server 2025), with virtualisation enabled in the firmware and the Virtual Machine + Platform feature on. ARM64 and x86 are not supported. +- **WSL 3.0.5 or later** from the stable channel: `wsl --install --no-distribution` (new install) or + `wsl --update`. No `--pre-release` channel is needed. The floor follows the bundled + `Microsoft.WSL.Containers` SDK and is checked at run time; an older WSL is reported with the fix. The + library adds no Windows-version check of its own: WSL decides, and reports `WSL_E_OS_NOT_SUPPORTED`. + Tested on Windows 11 23H2 and Windows Server 2025; the full list is in the + [host requirements](https://github.com/purview-dev/containers/blob/main/docs/wiki/Consumer-Requirements.md#host-requirements-wsl-containers-backend). - **A .NET 10 or .NET 11 project** (.NET 8 and .NET 9 are not supported). The recommended target framework is platform-neutral (`net10.0` or `net11.0`): it binds the facade and gives you automatic WSLC-or-Docker selection. A Windows target framework - (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 or arm64) binds the implementation + (`net10.0-windows10.0.19041.0` or `net11.0-windows10.0.19041.0`, x64 only; ARM64 is not supported) binds the implementation directly. Anything older than .NET 10, or a Windows TFM below Windows 10.0.19041.0, fails the build with - `PCC0001`; a 32-bit Windows consumer fails with `PCC0002`; and without the packages' MSBuild defaults a + `PCC0001`; a non-x64 (ARM64 or x86) Windows consumer fails with `PCC0002`; and without the packages' MSBuild defaults a stale `WindowsSdkPackageVersion` fails with `CS1705`. - This package supplies the `buildTransitive` defaults for `WindowsSdkPackageVersion` and `PlatformTarget` that every module package inherits, and (for a platform-neutral consumer on a Windows @@ -43,9 +52,7 @@ consuming assembly. To also run the same test code on Docker in Linux CI, refere reference and the `EnableWindowsTargeting` workaround for non-Windows CI agents are in the [consumer requirements](https://github.com/purview-dev/containers/blob/main/docs/wiki/Consumer-Requirements.md). - Verify the host with `wsl --version` and `wslc version`. The library never installs or updates WSL - itself; `WslContainerRuntime.GetInfoAsync()` reports what is missing. -- **Experimental:** this is an experiment in driving WSL Containers. The public API, defaults and - packaging rules can change between prereleases, and there is no production support guarantee. + itself; `WslContainerRuntime.GetInfoAsync()` reports what is missing and how to fix it. ## Quick start @@ -98,7 +105,7 @@ are available. Exec/stop cancellation is propagated, not returned as a successfu Synchronous native SDK calls cannot be interrupted safely. Managed waits and CLI processes are bounded, but a blocked native call can outlive cancellation. CLI creation currently rejects privileged mode combined with CLI-only features and multi-line environment values. See -[capabilities and cancellation](https://github.com/purview-dev/containers/blob/main/docs/wiki/Backend-Capabilities.md). +[capabilities and cancellation](https://github.com/purview-dev/containers/blob/main/docs/wiki/guide/Backend-Capabilities.md). `IContainer` (and `WslContainer`) exposes `StartAsync`, `StopAsync`, `ExecAsync`, `GetMappedPublicPort`, `GetMappedPublicPorts`, `GetLogsAsync(LogOutput?)` and a tailing `IAsyncEnumerable` @@ -182,9 +189,9 @@ raw command/build output. See the [project wiki](https://github.com/purview-dev/containers/blob/main/docs/wiki/Home.md): [Getting Started](https://github.com/purview-dev/containers/blob/main/docs/wiki/Getting-Started.md), -[Architecture](https://github.com/purview-dev/containers/blob/main/docs/wiki/Architecture.md), -[Lifecycle](https://github.com/purview-dev/containers/blob/main/docs/wiki/Lifecycle.md), -[Networking](https://github.com/purview-dev/containers/blob/main/docs/wiki/Networking.md) and -[Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/Wait-Strategies.md). +[Architecture](https://github.com/purview-dev/containers/blob/main/docs/wiki/contributing/Architecture.md), +[Lifecycle](https://github.com/purview-dev/containers/blob/main/docs/wiki/guide/Lifecycle.md), +[Networking](https://github.com/purview-dev/containers/blob/main/docs/wiki/guide/Networking.md) and +[Wait Strategies](https://github.com/purview-dev/containers/blob/main/docs/wiki/guide/Wait-Strategies.md). Ready-made service modules ship as `Purview.Containers.PostgreSql`, `Redis`, `MsSql`, `RabbitMq`, `Azurite`, `Nats`, `MySql` and `AzureKeyVaultEmulator`. diff --git a/src/src/Wsl/Sdk/buildTransitive/Purview.Containers.Wsl.targets b/src/src/Wsl/Sdk/buildTransitive/Purview.Containers.Wsl.targets index 908cae5..b3456b7 100644 --- a/src/src/Wsl/Sdk/buildTransitive/Purview.Containers.Wsl.targets +++ b/src/src/Wsl/Sdk/buildTransitive/Purview.Containers.Wsl.targets @@ -6,9 +6,10 @@ has been evaluated, so an explicit PlatformTarget or RuntimeIdentifier always wins. The values set here are defaults only. - PlatformTarget: wslcsdk.dll (the native WSL Containers SDK) ships for win-x64 and win-arm64 - only. A consumer left on the default AnyCPU is corrected to x64 here; an explicit x86 (32-bit) - consumer fails with PCC0002 instead of failing later at runtime with a load error. + PlatformTarget: the backend supports x64 only - the Windows implementation is compiled for x64 and + only the win-x64 native SDK (wslcsdk.dll) is deployed. A consumer left on the default AnyCPU is + corrected to x64 here; an explicit x86 or arm64 consumer fails with PCC0002 instead of failing later + at runtime with a load error. Target framework: because build and buildTransitive assets are framework-agnostic, NuGet does not reject an incompatible target framework at restore time with NU1202 - it silently @@ -23,9 +24,9 @@ --> @@ -84,14 +85,14 @@ <_PurviewContainersWslIsWindows Condition="'$(TargetPlatformIdentifier)' == 'Windows'" >true <_PurviewContainersWslPlatformTargetSupported - Condition="'$(_PurviewContainersWslIsWindows)' != 'true' OR '$(PlatformTarget)' == 'x64' OR '$(PlatformTarget)' == 'arm64' OR ('$(PlatformTarget)' == '' AND '$(RuntimeIdentifier)' != '')" + Condition="'$(_PurviewContainersWslIsWindows)' != 'true' OR '$(PlatformTarget)' == 'x64' OR ('$(PlatformTarget)' == '' AND $(RuntimeIdentifier.EndsWith('-x64')))" >true @@ -108,12 +109,8 @@ Condition="'$(TargetFramework)' != '' AND '$(OS)' == 'Windows_NT' AND '$(TargetPlatformIdentifier)' != 'Windows'" > - <_PurviewContainersWslPayloadRid - Condition="'$(RuntimeIdentifier)' == 'win-arm64' OR '$(PlatformTarget)' == 'arm64'" - >win-arm64 - <_PurviewContainersWslPayloadRid Condition="'$(_PurviewContainersWslPayloadRid)' == ''" - >win-x64 - <_PurviewContainersWslPayloadSource>$(MSBuildThisFileDirectory)..\payload\$(_PurviewContainersWslPayloadRid)\ + + <_PurviewContainersWslPayloadSource>$(MSBuildThisFileDirectory)..\payload\win-x64\ diff --git a/src/src/Wsl/Wsl.csproj b/src/src/Wsl/Wsl.csproj index 39aefdc..5bc73de 100644 --- a/src/src/Wsl/Wsl.csproj +++ b/src/src/Wsl/Wsl.csproj @@ -19,9 +19,17 @@ platform-neutral consumer gets the facade. The approach rests on the extracted and tested result that the WSLC projection is a net8.0-windows asset loadable by a net10.0 or net11.0 process. + + The list is derived from Purview.BuildSdk's `Supported` set (selected in src/Directory.Build.props) + rather than restated: each supported framework contributes its portable build and its + -windows10.0.19041.0 build, so this package always targets exactly what the other packages do. + The payload target below and the pack manifest still name net10.0 (the lowest supported build) + and fail fast if the set moves. --> - net10.0;net10.0-windows10.0.19041.0;net11.0;net11.0-windows10.0.19041.0 + + $(PurviewTargetFrameworksSupported);$([MSBuild]::Unescape($(PurviewTargetFrameworksSupported.Replace(';', '-windows10.0.19041.0;'))))-windows10.0.19041.0 WSL Containers (WSLC) backend for Purview.Containers: run WSLC-native throwaway Linux containers from any .NET 10 or .NET 11 project, with automatic Docker fallback. wsl;wslc;containers;linux;windows;testing;integration;testcontainers MIT @@ -56,6 +64,9 @@ + + +