Distillation

Date: Aug 26, 2026

• 🔴 (13:19) User stated that a following option such as --workspace --dry-run must never be mistaken for a workspace name.
• 🟡 (13:19) src/utils/helpers.ts implements extractWorkspaceSelection(argv, env = process.env), which reads CRAFT_WORKSPACE, parses raw arguments with Node parseArgs({ options: { workspace: { type: 'string' } }, allowPositionals: true, strict: false, tokens: true }), and returns the final valid --workspace value or the environment value.
• 🟡 (13:19) extractWorkspaceSelection() supports both --workspace foo and --workspace=foo; the last workspace option occurrence decides. A bare/empty final --workspace clears any prior CLI value and falls back to CRAFT_WORKSPACE.
• 🟡 (13:19) extractWorkspaceSelection() accepts a dash-prefixed workspace only as an inline value (for example, --workspace=-foo); a separate following dash-prefixed token is rejected as a workspace value. The CLI takes precedence over CRAFT_WORKSPACE only when it contains a valid value.
• 🟡 (13:19) src/config.ts defines WORKSPACES_MIN_VERSION = '2.29.0'; dev builds such as 2.29.0-dev.0 satisfy this gate through checkMinimalConfigVersion prerelease relaxation.
• 🟡 (13:19) setActiveWorkspace(name) stores _activeWorkspaceName, clears _configCache and _globalGitHubConfigCache, and must run before configuration is first resolved so subsequent reads apply the new selection; getActiveWorkspace() returns the selected workspace or undefined.
• 🟡 (13:19) Workspace config resolution in resolveWorkspaceConfig() requires the requested workspace name to be an own key of base.workspaces; otherwise it throws ConfigurationError naming the unknown workspace and listing available workspaces, or stating that none are defined.
• 🟡 (13:19) resolveWorkspaceConfig() shallowly overrides each defined workspace release-relevant field over the top-level config, strips workspaces and minVersion from the resolved result, does not deep-merge arrays/objects, and shallow-merges github so workspace projectPath can inherit base owner/repo.
• 🟡 (13:19) During workspace github merging, if the resulting object lacks owner or repo, resolveWorkspaceConfig() deletes resolved.github; this intentionally permits getGlobalGitHubConfig() to fall back to Git remote detection instead of treating an incomplete GitHub object as configured.
• 🟡 (13:19) applyWorkspaceSelection() behavior: no configured workspaces plus no selection returns config unchanged; selected workspace without configured workspaces throws; configured workspaces without explicit selection throws and lists available names; both present require minVersion >= 2.29.0 and return the merged workspace config.
• 🟡 (13:19) getGlobalGitHubConfig(clearCache = false) reads the active resolved config’s github block; absent config, it creates a Git client at the config directory (or .), selects origin or the first remote, and derives { owner, repo } only from a github.com remote. It caches a frozen config or null; cached null throws ConfigurationError.
• 🟡 (13:19) getGitTagPrefix() uses the first github target’s tagPrefix from the active configuration. If multiple GitHub targets have differing prefixes, it warns and still returns the first; for independently versioned monorepo products it advises one top-level workspaces entry per product, or separate .craft.yml files, each with one GitHub target and its own tagPrefix.