feat(config): top-level workspaces schema + --workspace selector

[BYK]

Summary

PR B of the workspaces redesign (design doc: .opencode/plans/workspaces-redesign-design.md, tracking #842). Adds a first-class, target-agnostic top-level workspaces: config key plus a --workspace selector so a single .craft.yml can describe multiple independently-versioned release units (e.g. cli@, mcp@).

This PR is the schema + resolver + selector groundwork only. It is fully backward-compatible and inert when no workspaces key is present — the full suite (1078 tests) passes unchanged. Threading the selection through prepare/publish and the publish-issue action layer comes in follow-up PRs (C/D).

What's in it

• Schema (schemas/project_config.ts): a top-level workspaces map. Each workspace mirrors the release-relevant subset of the top-level config and inherits unspecified fields from the top level. The workspace github block is partial so it can override just projectPath while inheriting owner/repo.
• Resolver (config.ts): getConfiguration() returns a resolved view — base config merged with the selected workspace's overrides — so getGitTagPrefix, getGlobalGitHubConfig, getVersioningPolicy, providers, and expandWorkspaceTargets(config.targets) all become workspace-aware with no per-accessor changes.
• Selector (index.ts): global --workspace <name> (env CRAFT_WORKSPACE). Applied before yargs parsing because command builders (notably publish, which derives --target choices from config.targets) run before middleware. Verified end-to-end.
• Validation: unknown/absent selection, or omitting it when workspaces are defined, fails fast with a helpful message listing available workspaces. Gated behind minVersion >= 2.27.0.
• checkMinimalConfigVersion dev-build relaxation: a pre-release build of X.Y.Z (e.g. 2.27.0-dev.0) now satisfies a minVersion up to X.Y.Z, so features can be dogfooded from a dev build before their release is cut. Released builds are unaffected; a genuinely-too-new minVersion (e.g. 2.28.0) is still correctly rejected.

Note: this "workspace" (a release unit) is distinct from the npm target's existing workspaces: true field (npm package discovery within one target). No schema clash — one is top-level, one is a target field. Docs (PR E) will disambiguate.

Review — critical bug caught & fixed

Adversarial review found a CRITICAL bug (C1): the publish builder calls getConfiguration() at parse time, which runs before the --workspace middleware — so with a workspaces config it threw "select a workspace" before the selection was applied, breaking craft publish for the very feature this ships. Fixed by resolving the workspace from raw argv/env before .parse(), plus a graceful fallback in the publish builder. Verified end-to-end with a built binary:

• craft targets --workspace cli → resolves the cli workspace's targets ✓
• CRAFT_WORKSPACE=cli and --workspace=mcp forms both work ✓
• no selection → friendly error listing cli, mcp ✓
• unknown workspace → Unknown workspace "nope". Available workspaces: cli, mcp. ✓

Testing

pnpm test (1078 passed, 1 skipped), tsc, pnpm lint (0 errors), prettier --check all clean. New tests cover schema parsing, the resolver merge (overrides win / base inherited / partial github), all error paths, the minVersion gate, cache re-resolution on selection change, and the publish-builder contract (regression for C1).

Part of #842.

🤖 Generated with opencode

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit c099bbf. Configure here.}

[cursor]

Stale workspaces minVersion gate

High Severity

WORKSPACES_MIN_VERSION is 2.27.0, but 2.27.x and 2.28.0 already shipped without top-level workspaces support. A config that sets minVersion: 2.27.0 (or 2.28.0) and defines workspaces still passes those older binaries' version check; Zod then strips the unknown key, so craft can run against the wrong release unit. The gate needs the version that will first ship this feature (currently heading to 2.29.0).

 

^{Reviewed by Cursor Bugbot for commit c099bbf. Configure here.}

[sentry]

Bug: The isVersionGteMinVersion function can crash if config.minVersion in .craft.yml contains SemVer build metadata (e.g., 2.27.0+build123), as it's not stripped before comparison.
_{Severity: MEDIUM}

Suggested Fix

Modify isVersionGteMinVersion and checkMinimalConfigVersion to strip build metadata from all SemVer objects before passing them to versionGreaterOrEqualThan. This can be done by creating a new SemVer object with the build property set to undefined regardless of whether the version is a pre-release or not. This will make the version comparison logic robust against versions with build metadata from any source.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: src/config.ts#L519-L527

Potential issue: The `versionGreaterOrEqualThan` function throws an exception if either
of the versions being compared contains SemVer build metadata (e.g., `+build123`). The
`checkMinimalConfigVersion` function only strips this metadata from pre-release
versions, not stable ones. A more critical issue exists in `isVersionGteMinVersion`,
which is called during workspace selection. If a user specifies a `minVersion` in their
`.craft.yml` configuration file with build metadata (e.g., `minVersion:
"2.27.0+linux"`), the application will crash because the metadata is not stripped before
being passed to `versionGreaterOrEqualThan` for comparison. This leads to an unhandled
exception when validating the workspace configuration.

_{Did we get this right? 👍 / 👎 to inform future reviews.}