Distillation

Date: Sep 8, 2026

• 🟡 (16:15) src/commands/workspace_cmds/list.ts defines the workspace list subcommand: command = ['list'], description 'List defined release workspaces as a JSON array', and handler() outputs formatJson(getWorkspaceNames()) with console.log.
• 🟡 (16:15) src/index.ts imports workspace from ./commands/workspace, registers it through .command(workspace), and defines global --workspace as a string option with description: 'Select a named workspace (release unit) from the configuration. Required when the config defines "workspaces". Env: CRAFT_WORKSPACE'.
• 🟡 (16:15) CLI initialization in src/index.ts selects the active workspace before yargs parsing via setActiveWorkspace(extractWorkspaceSelection(argv)), because yargs command builders may read and validate workspace-resolved configuration before middleware executes; extractWorkspaceSelection is the single source of truth for CLI/env selection precedence.
• 🟡 (16:15) src/index.ts global boolean handling uses fixGlobalBooleanFlags(process.argv.slice(2)): standalone known flags from GLOBAL_BOOLEAN_FLAGS receive injected '1', allowing env-backed booleans and explicit --flag=no overrides while disallowing positional --flag no notation. GLOBAL_BOOLEAN_FLAGS includes no-input (default isCI) and dry-run (default process.env.DRY_RUN, TODO to deprecate in favor of CRAFT_DRY_RUN).
• 🔴 (16:15) User stated that a following option, such as --workspace --dry-run, must never be mistaken for a workspace name.
• 🟡 (16:15) extractWorkspaceSelection() in src/utils/helpers.ts uses Node built-in parseArgs() with { workspace: { type: 'string' } }, allowPositionals: true, strict: false, and tokens: true; it supports --workspace foo and --workspace=foo.
• 🟡 (16:15) Workspace selection precedence/edge-case behavior in extractWorkspaceSelection(): the last --workspace occurrence decides; an empty or bare final workspace flag clears an earlier CLI value and falls back to CRAFT_WORKSPACE; a CLI value wins over CRAFT_WORKSPACE only when it has a value; inline negative values such as --workspace=-foo are valid, while separated --workspace --foo is invalid because non-inline values beginning with - are rejected.
• 🟡 (16:15) src/utils/helpers.ts defines MAX_STEP_OUTPUT_BYTES = 64 * 1024 (64 KB) to truncate GitHub Actions step-output values and avoid E2BIG when subsequent steps expand outputs into environment variables; rationale notes this is below the approximately 2 MB ARG_MAX and GitHub’s approximately 65,536-character issue-body limit.
• 🟡 (16:15) envToBool() treats '', 'undefined', 'null', '0', 'false', and 'no' case-insensitively as false; all other values are true.
• 🟡 (16:15) setGitHubActionsOutput(name, value) is a no-op without GITHUB_OUTPUT; it appends single-line values as ${name}=${value}\n and multiline values with a generated EOF_${Date.now()}_${Math.random().toString(36).slice(2)} heredoc delimiter.
• 🟡 (16:15) publish command builder computes permitted --target choices from getConfiguration().targets after workspace resolution, retaining only known target implementations via getAllTargetNames() and mapping with BaseTarget.getId; if configuration cannot resolve during parse time, it falls back to all known target names rather than aborting parsing.
• 🟡 (16:15) publish command’s target choices include configured target IDs plus SpecialTarget.All and SpecialTarget.None; default is SpecialTarget.All. Other documented options include --rev, --merge-target, --remote defaulting to 'origin', --no-merge, --keep-branch, --keep-downloads, --no-status-check, and --no-git-checks.
• 🟡 (16:15) publishMain() expands npm workspace targets through expandWorkspaceTargets(config.targets || []) before publishing, and keys publish state using getPublishStatePath(newVersion, getPublishStateGitHubConfig(publishStateGithubConfig), process.cwd(), getActiveWorkspace()), making state workspace-specific.
• 🟡 (16:15) getPublishStateGitHubConfig() permits CRAFT_PUBLISH_STATE_GITHUB_REPO only as a GitHub owner/repository pair matching /^(?<owner>[A-Za-z0-9_.-]+)\/(?<repo>[A-Za-z0-9_.-]+)$/; invalid values throw ConfigurationError('CRAFT_PUBLISH_STATE_GITHUB_REPO must be a GitHub owner/repository pair.'). This override is deliberately limited to publish-state identity because a controller checkout repository can differ from the workspace release GitHub configuration.
• 🟡 (16:15) Publish state is stored outside the repository; if legacy .craft-publish-${newVersion}.json exists in the project directory, Craft warns it will not read it for security because repository contents can be attacker-influenced through PRs, and directs workflows to $XDG_STATE_HOME/craft/.
• 🟡 (16:15) handleReleaseBranch() merge strategy decision: first attempt default Git merge strategy ort with --no-ff --no-edit; if that fails, abort and retry with -s resolve --no-ff --no-edit, chosen because it can handle criss-cross ambiguities differently and may succeed on files such as CHANGELOG.md. If both fail, it captures git.status().conflicted and git.diff(conflictedFiles), aborts, and throws MergeConflictError; a post-merge push failure instead throws PushError.
• 🟡 (16:15) Publish treats post-publish branch merging as housekeeping: merge/push failures are sent to Sentry with captureException(mergeError) and reported with manual remediation steps, but do not fail an otherwise fully published release. MergeConflictError messaging states both ort and resolve failed and may list conflicted files/diff; PushError messaging states local merge succeeded but remote push failed, likely due to an expired token during publishes longer than 1 hour.
• 🟡 (16:15) publishMain() determines no-merge via argv.noMerge || getNoMergeConfig().noMerge; when config auto-detection enables it, --merge-target is warned as ignored, and the source is reported as either CLI option, auto-detection for a compiled GitHub Action with dist/ folder, or config.