Distillation

Date: Aug 25, 2026

• 🔴 (16:27) User stated that a following CLI option (for example, --workspace --dry-run) must never be mistaken for a workspace name.
• 🟡 (16:27) Search results identified workspace-related implementation in src/utils/workspaces.ts, selected-workspace publish-state filename isolation in src/utils/publishState.ts, raw-argv workspace selection in src/utils/helpers.ts, workspace resolution in src/config.ts, and workspace-related command behavior/tests in src/commands/{targets,publish,prepare}.ts.
• 🟡 (16:27) src/utils/publishState.ts:78-119 documents and implements lossless workspace identity in publish-state paths: when a workspace is selected, it prefixes filenames with workspace-${Buffer.from(workspace).toString('base64url')}-; getPublishStateFilename(version, githubConfig, cwd, workspace) uses this prefix in GitHub and non-GitHub filename forms, and workspace?: string is documented as isolating publish state for a selected release workspace.
• 🟡 (16:28) src/utils/helpers.ts:42-72 implements extractWorkspaceSelection(argv, env = process.env): reads CRAFT_WORKSPACE, parses raw argv with Node parseArgs({ options: { workspace: { type: 'string' } }, allowPositionals: true, strict: false, tokens: true }), scans parser tokens, and returns the final valid --workspace selection or the environment value.
• 🟡 (16:28) extractWorkspaceSelection() precedence/validation behavior: the last workspace token decides; each candidate resets prior selection; only nonempty string values are accepted; a separate value beginning with - is rejected, while an inline --workspace=-foo value is accepted; a bare/empty final option falls back to CRAFT_WORKSPACE; return expression is workspace || envWorkspace.
• 🟡 (16:28) src/utils/helpers.ts:24-40 explains why selected workspace parsing occurs before yargs: command builders may access configuration before middleware, including publish deriving --target choices from config.targets; supported forms are --workspace foo and --workspace=foo.
• 🟡 (16:28) Existing src/utils/__tests__/helpers.test.ts coverage for extractWorkspaceSelection() includes no selection, split and inline values, inline option-looking --workspace=-cli, rejected split option-looking --workspace -cli, CLI-versus-CRAFT_WORKSPACE precedence, repeated workspace options, --workspace --dry-run, bare --workspace with and without env fallback, and --workspace=.
• 🟡 (16:28) src/index.ts:16,97-98 imports extractWorkspaceSelection and calls setActiveWorkspace(extractWorkspaceSelection(argv)); the comment says this function is the source of truth for selection precedence.
• 🟡 (16:28) src/config.ts:67 sets WORKSPACES_MIN_VERSION = '2.29.0'; comments state dev builds such as 2.29.0-dev.0 satisfy the requirement through pre-release relaxation in checkMinimalConfigVersion.
• 🟡 (16:28) src/config.ts:70-95 stores selected workspace in _activeWorkspaceName; setActiveWorkspace(name) updates it and invalidates _configCache and _globalGitHubConfigCache; getActiveWorkspace() returns the current selection.
• 🟡 (16:28) src/config.ts:98-160 resolves a named workspace by shallowly overriding top-level release-relevant fields; github is shallow-merged so workspace projectPath can inherit base owner/repo; if merged GitHub config lacks owner or repo, resolved.github is deleted to retain git-remote fallback; workspaces is stripped from the resolved config.
• 🟡 (16:28) resolveWorkspaceConfig() throws ConfigurationError for an unknown workspace, reporting either Available workspaces: ${available.join(', ')}. or No workspaces are defined in the configuration..
• 🟡 (16:28) src/config.ts:205-240 applyWorkspaceSelection() behavior: no workspaces and no active selection returns config unchanged; an active selection without configured workspaces throws; configured workspaces without a selection throw and list available names; both configured workspaces and a selection require minVersion >= 2.29.0, then resolve the selected workspace.
• 🟡 (16:28) src/commands/targets.ts:6-12 defines targets (“List defined targets as JSON array”), gets getConfiguration().targets || [], and expands workspace targets. src/commands/__tests__/targets.test.ts includes cases for unexpanded/no-workspace targets, expanded workspace targets, empty target list, and undefined targets.
• 🟡 (16:28) Search evidence in src/commands/publish.ts shows selected workspace config affects target choices (:63-69), workspace targets are expanded before publishing (:683-684), and publish logic uses the selected/expanded target set. src/commands/prepare.ts:342-369,908 carries configured targets into automatic version-bump behavior.