@theholocron/cli 2.0.0-alpha.73 → 2.0.0-alpha.75

package/dist/cli.mjs

@@ -16,6 +16,7 @@ import { execFile, execFileSync, spawnSync } from "node:child_process";
 import { access, copyFile, mkdir, readFile, readdir, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
 import { pathToFileURL } from "node:url";
 import { promisify } from "node:util";
+import { homedir } from "node:os";
 //#region src/capabilities/index.ts
 const CARDINALITY = {
 	source: "single",
@@ -483,9 +484,12 @@ var PluginLoader = class {
 			throw new LoaderError(`failed to import \`${tuple.packageName}\` for capability \`${key}\`: ${err instanceof Error ? err.message : String(err)}`);
 		});
 		if (isPluginModule(mod)) {
+			const effectiveToken = this.context.cliTokens?.[tuple.provider] ?? this.context.cliToken;
 			const factory = mod.createPlugin({
 				...this.projectDefaults(),
 				...this.context,
+				...effectiveToken !== void 0 ? { cliToken: effectiveToken } : {},
+				cliTokens: void 0,
 				...tuple.options
 			}).capabilities[key];
 			if (typeof factory !== "function") throw new LoaderError(`\`${tuple.packageName}\` does not implement the \`${key}\` capability`);
@@ -913,7 +917,7 @@ var lint_default$1 = "name: Lint\n\non: # yamllint disable-line rule:truthy\n  w
 var release_default$1 = "name: Release\n\n# Semantic-release with OIDC Trusted Publishing — no NPM_TOKEN required.\n# The calling repo must have a .releaserc.json that configures branches,\n# plugins, and any publish options. npm@11+ is installed to support OIDC.\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    inputs:\n      run-build:\n        description: Run `pnpm build` before releasing\n        type: boolean\n        required: false\n        default: true\n    secrets:\n      SYNC_TOKEN:\n        description: >\n          Optional PAT with Contents write access. Required when the default\n          branch is protected by a ruleset — github.token cannot push through\n          rulesets, but a PAT with admin bypass can. Falls back to github.token.\n        required: false\n\njobs:\n  release:\n    name: Semantic release\n    permissions:\n      contents: write\n      id-token: write\n      issues: write\n      pull-requests: write\n    runs-on: ubuntu-latest\n    timeout-minutes: 30\n    # Do not cancel in-progress releases — a partial release is worse than a slow one.\n    concurrency:\n      group: release-${{ github.ref }}\n      cancel-in-progress: false\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n        with:\n          fetch-depth: 0\n          # Use SYNC_TOKEN when available — git push (tags, release commits)\n          # uses the checkout credential, not GITHUB_TOKEN env var. The\n          # built-in github.token cannot push through branch protection rulesets.\n          token: ${{ secrets.SYNC_TOKEN || github.token }}\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n\n      - name: Configure git identity\n        run: |\n          GIT_NAME=$(gh api user --jq .name 2>/dev/null || echo \"github-actions[bot]\")\n          GIT_EMAIL=$(gh api user --jq '\"\\(.id)+\\(.login)@users.noreply.github.com\"' 2>/dev/null || echo \"41898282+github-actions[bot]@users.noreply.github.com\")\n          git config --global user.name \"$GIT_NAME\"\n          git config --global user.email \"$GIT_EMAIL\"\n          git config --global format.signoff true\n        env:\n          GH_TOKEN: ${{ secrets.SYNC_TOKEN || github.token }}\n\n      - run: npm install -g npm@11 sigstore\n        name: Upgrade npm for OIDC support\n        # sigstore is required by libnpmpublish/provenance.js at module parse\n        # time — before any config takes effect. Some npm 11.x builds stopped\n        # bundling it; installing it globally into the same prefix ensures it\n        # resolves regardless of npm version. (Discovered 2026-07-09.)\n\n      - run: pnpm build\n        name: Build\n        if: ${{ inputs.run-build == true }}\n\n      - run: npx semantic-release\n        name: Release\n        env:\n          # Prefer SYNC_TOKEN (a PAT with Contents write) when available —\n          # the built-in github.token cannot push to protected default branches\n          # because rulesets block non-PAT pushes. Falls back to github.token\n          # for repos without branch protection.\n          GITHUB_TOKEN: ${{ secrets.SYNC_TOKEN || github.token }}\n          NPM_CONFIG_PROVENANCE: true\n";
 //#endregion
 //#region src/templates/workflows/review.yml
-var review_default$1 = "name: Review\n\n# ReviewDog is the annotation layer — posts inline PR diff annotations.\n# Runs on pull_request only: inline annotations require PR context,\n# and branch protection ensures all changes go through PRs anyway.\n# super-linter (lint.yml) is the CI gate covering push + PR events.\n# Gitleaks and YAML are intentionally duplicated: super-linter gates\n# merges; ReviewDog surfaces exact line annotations in the PR diff.\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n\nconcurrency:\n  group: review-${{ github.workflow }}-${{ github.ref }}\n  cancel-in-progress: true\n\njobs:\n  reviewdog:\n    name: Review PRs\n    runs-on: ubuntu-latest\n    timeout-minutes: 20\n    permissions:\n      contents: read\n      checks: write\n      pull-requests: write\n\n    steps:\n      - name: Checkout repository\n        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        with:\n          fetch-depth: 0\n\n      - name: Setup\n        if: ${{ hashFiles('pnpm-lock.yaml') != '' }}\n        uses: theholocron/.github/.github/actions/setup@main\n\n      - name: Install ReviewDog\n        uses: reviewdog/action-setup@d8a7baabd7f3e8544ee4dbde3ee41d0011c3a93f # v1\n        with:\n          reviewdog_version: latest\n\n      # Detect which tools are relevant for this repo, excluding node_modules.\n      # hashFiles('**/*') recurses into node_modules/.pnpm and produces false\n      # positives for repos that don't own those file types.\n      # -print -quit stops find after the first match without a pipe, avoiding\n      # the SIGPIPE/pipefail exit-141 that find|head-1 triggers under\n      # GitHub Actions' default bash --noprofile --norc -e -o pipefail mode.\n      - name: Detect project features\n        id: detect\n        shell: bash\n        run: |\n          has() { find . -not -path '*/node_modules/*' -name \"$1\" -print -quit 2>/dev/null | grep -q .; }\n          has_ext() { find . -not -path '*/node_modules/*' -name \"$1\" -print -quit 2>/dev/null | grep -q .; }\n          { { has 'eslint.config.js' || has 'eslint.config.mjs' || has 'eslint.config.cjs' || \\\n              has 'eslint.config.ts' || has '.eslintrc' || has '.eslintrc.js' || \\\n              has '.eslintrc.cjs' || has '.eslintrc.json' || has '.eslintrc.yaml' || \\\n              has '.eslintrc.yml'; } && grep -qF '\"eslint\":' package.json 2>/dev/null; } && echo \"eslint=true\" >> \"$GITHUB_OUTPUT\" || echo \"eslint=false\" >> \"$GITHUB_OUTPUT\"\n          { has 'tsconfig.json' && grep -qF '\"typescript\":' package.json 2>/dev/null; } && echo \"tsconfig=true\" >> \"$GITHUB_OUTPUT\" || echo \"tsconfig=false\" >> \"$GITHUB_OUTPUT\"\n          has_ext '*.sh' && echo \"shell=true\" >> \"$GITHUB_OUTPUT\" || echo \"shell=false\" >> \"$GITHUB_OUTPUT\"\n          has 'Dockerfile' || has_ext '*.Dockerfile' || has 'Containerfile' && \\\n            echo \"docker=true\" >> \"$GITHUB_OUTPUT\" || echo \"docker=false\" >> \"$GITHUB_OUTPUT\"\n          has_ext '.env*' && echo \"dotenv=true\" >> \"$GITHUB_OUTPUT\" || echo \"dotenv=false\" >> \"$GITHUB_OUTPUT\"\n          has_ext '*.md' && echo \"markdown=true\" >> \"$GITHUB_OUTPUT\" || echo \"markdown=false\" >> \"$GITHUB_OUTPUT\"\n\n      #\n      # Always applicable\n      #\n\n      - name: Gitleaks (secrets)\n        uses: reviewdog/action-gitleaks@2b7b5685e3e3eecddab5d30cfa04f18123031421 # v1\n        with:\n          reporter: github-pr-check\n          gitleaks_flags: --log-opts=${{ github.event.pull_request.base.sha }}..${{ github.event.pull_request.head.sha }}\n\n      - name: YamlLint\n        if: ${{ hashFiles('yamllint.config.yml') != '' }}\n        uses: reviewdog/action-yamllint@b5f7217d8c815ae374d1d55840d5e569d82f01f0 # v1\n        with:\n          reporter: github-pr-check\n          yamllint_flags: -c ${{ github.workspace }}/yamllint.config.yml ${{ github.workspace }}\n\n      - name: ActionLint (GitHub Actions)\n        if: ${{ hashFiles('.github/workflows/*.yml', '.github/workflows/*.yaml') != '' }}\n        uses: reviewdog/action-actionlint@6fb7acc99f4a1008869fa8a0f09cfca740837d9d # v1\n        with:\n          reporter: github-pr-check\n\n      #\n      # TypeScript / JavaScript\n      #\n\n      - name: ESLint\n        if: steps.detect.outputs.eslint == 'true'\n        uses: reviewdog/action-eslint@556a3fdaf8b4201d4d74d406013386aa4f7dab96 # v1.34.0\n        with:\n          reporter: github-pr-check\n          eslint_flags: .\n\n      - name: TypeScript\n        if: steps.detect.outputs.tsconfig == 'true'\n        uses: EPMatt/reviewdog-action-tsc@63d923a3c5b4497671940b8874f58a404e2351b5 # v1\n        with:\n          reporter: github-pr-check\n\n      #\n      # Shell\n      #\n\n      - name: ShellCheck\n        if: steps.detect.outputs.shell == 'true'\n        uses: reviewdog/action-shellcheck@4c07458293ac342d477251099501a718ae5ef86e # v1\n        with:\n          reporter: github-pr-check\n          fail_level: none\n\n      #\n      # Docker\n      #\n\n      - name: Hadolint\n        if: steps.detect.outputs.docker == 'true'\n        uses: reviewdog/action-hadolint@1b2cfa6ba72072ad35158d7ff3aa49bbdc03506d # v1\n        with:\n          reporter: github-pr-check\n          fail_level: none\n\n      #\n      # Environment files\n      #\n\n      - name: dotenv-linter\n        if: steps.detect.outputs.dotenv == 'true'\n        uses: dotenv-linter/action-dotenv-linter@afde61cfda2ecffe7bea35837b6f20b956c88689 # v3.0.0\n        with:\n          reporter: github-code-suggestions\n\n      #\n      # Documentation\n      #\n\n      - name: Alex (inclusive language)\n        if: steps.detect.outputs.markdown == 'true'\n        uses: reviewdog/action-alex@347481655add010a2ae302df34b57c9bcfa0d6e4 # v1\n        with:\n          reporter: github-pr-check\n";
+var review_default$1 = "name: Review\n\n# ReviewDog is the annotation layer — posts inline PR diff annotations.\n# Runs on pull_request only: inline annotations require PR context,\n# and branch protection ensures all changes go through PRs anyway.\n# super-linter (lint.yml) is the CI gate covering push + PR events.\n# Gitleaks and YAML are intentionally duplicated: super-linter gates\n# merges; ReviewDog surfaces exact line annotations in the PR diff.\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n\nconcurrency:\n  group: review-${{ github.workflow }}-${{ github.ref }}\n  cancel-in-progress: true\n\njobs:\n  reviewdog:\n    name: Review PRs\n    runs-on: ubuntu-latest\n    timeout-minutes: 20\n    permissions:\n      contents: read\n      checks: write\n      pull-requests: write\n\n    steps:\n      - name: Checkout repository\n        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        with:\n          fetch-depth: 0\n\n      - name: Setup\n        if: ${{ hashFiles('pnpm-lock.yaml') != '' }}\n        uses: theholocron/.github/.github/actions/setup@main\n\n      - name: Install ReviewDog\n        uses: reviewdog/action-setup@d8a7baabd7f3e8544ee4dbde3ee41d0011c3a93f # v1\n        with:\n          reviewdog_version: latest\n\n      # Detect which tools are relevant for this repo, excluding node_modules.\n      # hashFiles('**/*') recurses into node_modules/.pnpm and produces false\n      # positives for repos that don't own those file types.\n      # -print -quit stops find after the first match without a pipe, avoiding\n      # the SIGPIPE/pipefail exit-141 that find|head-1 triggers under\n      # GitHub Actions' default bash --noprofile --norc -e -o pipefail mode.\n      - name: Detect project features\n        id: detect\n        shell: bash\n        run: |\n          has() { find . -not -path '*/node_modules/*' -name \"$1\" -print -quit 2>/dev/null | grep -q .; }\n          has_ext() { find . -not -path '*/node_modules/*' -name \"$1\" -print -quit 2>/dev/null | grep -q .; }\n          { { has 'eslint.config.js' || has 'eslint.config.mjs' || has 'eslint.config.cjs' || \\\n              has 'eslint.config.ts' || has '.eslintrc' || has '.eslintrc.js' || \\\n              has '.eslintrc.cjs' || has '.eslintrc.json' || has '.eslintrc.yaml' || \\\n              has '.eslintrc.yml'; } && grep -qF '\"eslint\":' package.json 2>/dev/null; } && echo \"eslint=true\" >> \"$GITHUB_OUTPUT\" || echo \"eslint=false\" >> \"$GITHUB_OUTPUT\"\n          { has 'tsconfig.json' && grep -qF '\"typescript\":' package.json 2>/dev/null; } && echo \"tsconfig=true\" >> \"$GITHUB_OUTPUT\" || echo \"tsconfig=false\" >> \"$GITHUB_OUTPUT\"\n          has_ext '*.sh' && echo \"shell=true\" >> \"$GITHUB_OUTPUT\" || echo \"shell=false\" >> \"$GITHUB_OUTPUT\"\n          has 'Dockerfile' || has_ext '*.Dockerfile' || has 'Containerfile' && \\\n            echo \"docker=true\" >> \"$GITHUB_OUTPUT\" || echo \"docker=false\" >> \"$GITHUB_OUTPUT\"\n          has_ext '.env*' && echo \"dotenv=true\" >> \"$GITHUB_OUTPUT\" || echo \"dotenv=false\" >> \"$GITHUB_OUTPUT\"\n          has_ext '*.md' && echo \"markdown=true\" >> \"$GITHUB_OUTPUT\" || echo \"markdown=false\" >> \"$GITHUB_OUTPUT\"\n\n      #\n      # Always applicable\n      #\n\n      - name: Gitleaks (secrets)\n        uses: reviewdog/action-gitleaks@2b7b5685e3e3eecddab5d30cfa04f18123031421 # v1\n        with:\n          reporter: github-pr-check\n          tool_name: \"Review / gitleaks\"\n          gitleaks_flags: --log-opts=${{ github.event.pull_request.base.sha }}..${{ github.event.pull_request.head.sha }}\n\n      - name: YamlLint\n        if: ${{ hashFiles('yamllint.config.yml') != '' }}\n        uses: reviewdog/action-yamllint@b5f7217d8c815ae374d1d55840d5e569d82f01f0 # v1\n        with:\n          reporter: github-pr-check\n          tool_name: \"Review / yamllint\"\n          yamllint_flags: -c ${{ github.workspace }}/yamllint.config.yml ${{ github.workspace }}\n\n      - name: ActionLint (GitHub Actions)\n        if: ${{ hashFiles('.github/workflows/*.yml', '.github/workflows/*.yaml') != '' }}\n        uses: reviewdog/action-actionlint@6fb7acc99f4a1008869fa8a0f09cfca740837d9d # v1\n        with:\n          reporter: github-pr-check\n          tool_name: \"Review / actionlint\"\n\n      #\n      # TypeScript / JavaScript\n      #\n\n      - name: ESLint\n        if: steps.detect.outputs.eslint == 'true'\n        uses: reviewdog/action-eslint@556a3fdaf8b4201d4d74d406013386aa4f7dab96 # v1.34.0\n        with:\n          reporter: github-pr-check\n          tool_name: \"Review / eslint\"\n          eslint_flags: .\n\n      - name: TypeScript\n        if: steps.detect.outputs.tsconfig == 'true'\n        uses: EPMatt/reviewdog-action-tsc@63d923a3c5b4497671940b8874f58a404e2351b5 # v1\n        with:\n          reporter: github-pr-check\n          tool_name: \"Review / tsc\"\n\n      #\n      # Shell\n      #\n\n      - name: ShellCheck\n        if: steps.detect.outputs.shell == 'true'\n        uses: reviewdog/action-shellcheck@4c07458293ac342d477251099501a718ae5ef86e # v1\n        with:\n          reporter: github-pr-check\n          tool_name: \"Review / shellcheck\"\n          fail_level: none\n\n      #\n      # Docker\n      #\n\n      - name: Hadolint\n        if: steps.detect.outputs.docker == 'true'\n        uses: reviewdog/action-hadolint@1b2cfa6ba72072ad35158d7ff3aa49bbdc03506d # v1\n        with:\n          reporter: github-pr-check\n          tool_name: \"Review / hadolint\"\n          fail_level: none\n\n      #\n      # Environment files\n      #\n\n      - name: dotenv-linter\n        if: steps.detect.outputs.dotenv == 'true'\n        uses: dotenv-linter/action-dotenv-linter@afde61cfda2ecffe7bea35837b6f20b956c88689 # v3.0.0\n        with:\n          reporter: github-code-suggestions\n\n      #\n      # Documentation\n      #\n\n      - name: Alex (inclusive language)\n        if: steps.detect.outputs.markdown == 'true'\n        uses: reviewdog/action-alex@347481655add010a2ae302df34b57c9bcfa0d6e4 # v1\n        with:\n          reporter: github-pr-check\n          tool_name: \"Review / alex\"\n";
 //#endregion
 //#region src/templates/workflows/stale.yml
 var stale_default$1 = "name: Stale\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    inputs:\n      days-before-stale:\n        description: Days of inactivity before an issue is marked stale\n        type: number\n        required: false\n        default: 30\n      days-before-close:\n        description: Days of inactivity after stale label before closing\n        type: number\n        required: false\n        default: 5\n\njobs:\n  stale:\n    name: Mark stale issues and pull requests\n    permissions:\n      contents: write\n      issues: write\n      pull-requests: write\n    runs-on: ubuntu-latest\n    timeout-minutes: 10\n    steps:\n      - uses: actions/stale@1e223db275d687790206a7acac4d1a11bd6fe629 # v10.4.0\n        name: Run Stale\n        with:\n          close-issue-message: >\n            This issue was closed because it has been stalled for\n            ${{ inputs.days-before-close }} days with no activity.\n          days-before-close: ${{ inputs.days-before-close }}\n          days-before-stale: ${{ inputs.days-before-stale }}\n          exempt-all-pr-milestones: true\n          stale-issue-label: wontfix\n          stale-issue-message: >\n            This issue is stale because it has been open ${{ inputs.days-before-stale }}\n            days with no activity. Remove the stale label or comment, or this will be\n            closed in ${{ inputs.days-before-close }} days.\n          stale-pr-label: wontfix\n          stale-pr-message: >\n            This PR is stale because it has been open ${{ inputs.days-before-stale }}\n            days with no activity. Remove the stale label or comment, or this will be\n            closed in ${{ inputs.days-before-close }} days.\n";
@@ -4072,15 +4076,181 @@ async function fileExists(path) {
 	}
 }
 //#endregion
+//#region src/token-args.ts
+var TokenParseError = class extends Error {
+	name = "TokenParseError";
+};
+/**
+* Converts raw --token CLI values into a typed result.
+*
+* Bare form:   --token ghp_xxx            → { cliToken: "ghp_xxx" }
+* Keyed form:  --token github=ghp_xxx     → { cliTokens: { github: "ghp_xxx" } }
+* Mixed:       --token github=ghp_xxx --token v_yyy
+*                                         → { cliToken: "v_yyy", cliTokens: { github: "ghp_xxx" } }
+*
+* Values may contain "=" (e.g. base64 strings) — only the first "=" is treated as a separator.
+*/
+function parseTokenArgs(tokens) {
+	if (tokens.length === 0) return {};
+	const cliTokens = {};
+	const bare = [];
+	for (const raw of tokens) {
+		const eqIdx = raw.indexOf("=");
+		if (eqIdx === -1) {
+			bare.push(raw);
+			continue;
+		}
+		const vendor = raw.slice(0, eqIdx);
+		const value = raw.slice(eqIdx + 1);
+		if (vendor.trim() === "") throw new TokenParseError(`invalid --token value "${raw}": vendor name must not be empty`);
+		if (/\s/.test(vendor)) throw new TokenParseError(`invalid --token value "${raw}": vendor name must not contain whitespace`);
+		if (value === "") throw new TokenParseError(`invalid --token value "${raw}": token value must not be empty`);
+		cliTokens[vendor] = value;
+	}
+	if (bare.length > 1) throw new TokenParseError(`only one bare --token value is allowed; got ${bare.length.toString()} — use vendor=value form for multiple tokens`);
+	const result = {};
+	if (bare.length === 1) result.cliToken = bare[0];
+	if (Object.keys(cliTokens).length > 0) result.cliTokens = cliTokens;
+	return result;
+}
+//#endregion
+//#region src/update-notifier.ts
+const PACKAGE_NAME = "@theholocron/cli";
+const CACHE_TTL_MS = 1440 * 60 * 1e3;
+const FETCH_TIMEOUT_MS = 3e3;
+function getCacheDir() {
+	return process.env["HOLOCRON_CACHE_DIR"] ?? join(homedir(), ".cache", "holocron");
+}
+function getCachePath() {
+	return join(getCacheDir(), "update-check.json");
+}
+function readCache() {
+	try {
+		return JSON.parse(readFileSync(getCachePath(), "utf8"));
+	} catch {
+		return null;
+	}
+}
+function writeCache(entry) {
+	try {
+		mkdirSync(getCacheDir(), { recursive: true });
+		writeFileSync(getCachePath(), JSON.stringify(entry));
+	} catch {}
+}
+async function fetchLatestVersion(channel) {
+	try {
+		const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME)}`, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+		if (!res.ok) return null;
+		const data = await res.json();
+		return data["dist-tags"][channel] ?? data["dist-tags"]["latest"] ?? null;
+	} catch {
+		return null;
+	}
+}
+function getChannel(version) {
+	return /^[^-]+-([a-zA-Z]+)/.exec(version)?.[1] ?? "latest";
+}
+function isUpdateAvailable(current, latest) {
+	const normalize = (v) => v.replace(/^v/, "");
+	const c = normalize(current);
+	const l = normalize(latest);
+	if (c === l) return false;
+	const splitPre = (v) => {
+		const idx = v.indexOf("-");
+		return idx === -1 ? [v, ""] : [v.slice(0, idx), v.slice(idx + 1)];
+	};
+	const [cRelease, cPre] = splitPre(c);
+	const [lRelease, lPre] = splitPre(l);
+	const parseRelease = (r) => r.split(".").map(Number);
+	const cParts = parseRelease(cRelease);
+	const lParts = parseRelease(lRelease);
+	for (let i = 0; i < Math.max(cParts.length, lParts.length); i++) {
+		const cv = cParts[i] ?? 0;
+		const lv = lParts[i] ?? 0;
+		if (lv > cv) return true;
+		if (lv < cv) return false;
+	}
+	if (!lPre && cPre) return true;
+	if (lPre && !cPre) return false;
+	const cPreParts = cPre.split(".");
+	const lPreParts = lPre.split(".");
+	for (let i = 0; i < Math.max(cPreParts.length, lPreParts.length); i++) {
+		const cv = cPreParts[i] ?? "";
+		const lv = lPreParts[i] ?? "";
+		const cvNum = Number(cv);
+		const lvNum = Number(lv);
+		if (!isNaN(cvNum) && !isNaN(lvNum)) {
+			if (lvNum > cvNum) return true;
+			if (lvNum < cvNum) return false;
+		} else {
+			if (lv > cv) return true;
+			if (lv < cv) return false;
+		}
+	}
+	return false;
+}
+function formatNotice(current, latest) {
+	const installCmd = `npm install -g ${PACKAGE_NAME}`;
+	const raw1 = `Update available: ${current} → ${latest}`;
+	const raw2 = `Run ${installCmd} to update`;
+	const width = Math.max(raw1.length, raw2.length) + 4;
+	const bar = chalk.yellow("─".repeat(width));
+	const border = chalk.yellow("│");
+	const pad = (raw, styled) => `${border} ${styled}${" ".repeat(width - 2 - raw.length)} ${border}`;
+	return [
+		"",
+		chalk.yellow(`╭${bar}╮`),
+		pad(raw1, `Update available: ${chalk.dim(current)} → ${chalk.green(latest)}`),
+		pad(raw2, `Run ${chalk.cyan(installCmd)} to update`),
+		chalk.yellow(`╰${bar}╯`),
+		""
+	].join("\n");
+}
+async function checkForUpdates(currentVersion) {
+	if (process.env["CI"] || process.env["NO_UPDATE_NOTIFIER"]) return null;
+	const channel = getChannel(currentVersion);
+	const cache = readCache();
+	const now = Date.now();
+	let latestVersion = null;
+	if (cache && now - cache.checkedAt < CACHE_TTL_MS) latestVersion = cache.latestVersion;
+	else {
+		latestVersion = await fetchLatestVersion(channel);
+		if (latestVersion) writeCache({
+			latestVersion,
+			checkedAt: now
+		});
+	}
+	if (!latestVersion || !isUpdateAvailable(currentVersion, latestVersion)) return null;
+	return () => {
+		process.stderr.write(formatNotice(currentVersion, latestVersion) + "\n");
+	};
+}
+//#endregion
 //#region src/cli.ts
 const { version: CLI_VERSION } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
+/** Parses --token values and returns the context spread, or null on parse error (exits with code 1). */
+function tokenContext(rawTokens) {
+	if (!rawTokens?.length) return {};
+	try {
+		return parseTokenArgs(rawTokens);
+	} catch (err) {
+		if (err instanceof TokenParseError) {
+			console.error(`--token: ${err.message}`);
+			process.exitCode = 1;
+			return null;
+		}
+		throw err;
+	}
+}
+const updateCheckPromise = checkForUpdates(CLI_VERSION);
 await yargs(hideBin(process.argv)).scriptName("holocron").usage("$0 <command> [options]").option("dry-run", {
 	type: "boolean",
 	default: false,
 	describe: "Print what would be mutated without calling capability mutators. Commands branch on this; read-only commands ignore it."
 }).option("token", {
 	type: "string",
-	describe: "Vendor token passed to plugins as `cliToken`, taking precedence over env vars. Unambiguous for single-plugin commands; for multi-plugin flows pass per-vendor env vars instead."
+	array: true,
+	describe: "Vendor token override for plugins. Bare form: --token <value> (fallback for all plugins, single-plugin commands). Keyed form: --token vendor=value (targets a specific provider; repeat for each). Example: --token github=ghp_xxx --token vercel=v_yyy"
 }).option("cwd", {
 	type: "string",
 	default: process.cwd(),
@@ -4091,26 +4261,30 @@ await yargs(hideBin(process.argv)).scriptName("holocron").usage("$0 <command> [o
 	type: "string",
 	describe: "Repo coords (\"owner/name\"). Defaults to plugin-specific resolution."
 }), async (argv) => {
+	const tokens = tokenContext(argv.token);
+	if (!tokens) return;
 	if ((await runDoctor({
 		loaded: await loadConfig(argv.cwd),
 		context: {
 			repoRoot: argv.cwd,
 			dryRun: argv.dryRun,
 			...argv.repo ? { repo: argv.repo } : {},
-			...argv.token ? { cliToken: argv.token } : {}
+			...tokens
 		}
 	})).summary.fail > 0) process.exitCode = 1;
 }).command("setup", "Apply infra setup actions across every configured capability", (y) => y.option("repo", {
 	type: "string",
 	describe: "Repo coords (\"owner/name\"). Defaults to plugin-specific resolution."
 }), async (argv) => {
+	const tokens = tokenContext(argv.token);
+	if (!tokens) return;
 	if ((await runSetup({
 		loaded: await loadConfig(argv.cwd),
 		context: {
 			repoRoot: argv.cwd,
 			dryRun: argv.dryRun,
 			...argv.repo ? { repo: argv.repo } : {},
-			...argv.token ? { cliToken: argv.token } : {}
+			...tokens
 		}
 	})).summary.fail > 0) process.exitCode = 1;
 }).command("skills", "Manage agent skills from the @theholocron/skills registry", (y) => y.command("install", "Copy skills from @theholocron/skills into .agents/ with agent symlinks", () => {}, async (argv) => {
@@ -4163,6 +4337,8 @@ await yargs(hideBin(process.argv)).scriptName("holocron").usage("$0 <command> [o
 	default: "repo",
 	describe: "Scope: \"repo\" (default), \"env=<name>\", or \"org=<name>\""
 }), async (argv) => {
+	const tokens = tokenContext(argv.token);
+	if (!tokens) return;
 	const scopeArg = argv.scope;
 	const scope = parseScope(scopeArg);
 	if ((await runSecretSet({
@@ -4170,7 +4346,7 @@ await yargs(hideBin(process.argv)).scriptName("holocron").usage("$0 <command> [o
 		context: {
 			repoRoot: argv.cwd,
 			dryRun: argv.dryRun,
-			...argv.token ? { cliToken: argv.token } : {}
+			...tokens
 		},
 		name: argv.name,
 		...argv.value ? { value: argv.value } : {},
@@ -4190,12 +4366,14 @@ await yargs(hideBin(process.argv)).scriptName("holocron").usage("$0 <command> [o
 	default: ["production", "preview"],
 	describe: "Deployment targets to sync to. Defaults to production + preview."
 }), async (argv) => {
+	const tokens = tokenContext(argv.token);
+	if (!tokens) return;
 	if ((await runSecretsSync({
 		loaded: await loadConfig(argv.cwd),
 		context: {
 			repoRoot: argv.cwd,
 			dryRun: argv.dryRun,
-			...argv.token ? { cliToken: argv.token } : {}
+			...tokens
 		},
 		environmentId: argv.environmentId,
 		...argv.projectId ? { projectId: argv.projectId } : {},
@@ -4214,12 +4392,14 @@ await yargs(hideBin(process.argv)).scriptName("holocron").usage("$0 <command> [o
 	choices: ["production", "staging"],
 	describe: "Named environment to deploy into. Omit for a branch preview."
 }), async (argv) => {
+	const tokens = tokenContext(argv.token);
+	if (!tokens) return;
 	if ((await runDeploy({
 		loaded: await loadConfig(argv.cwd),
 		context: {
 			repoRoot: argv.cwd,
 			dryRun: argv.dryRun,
-			...argv.token ? { cliToken: argv.token } : {}
+			...tokens
 		},
 		projectId: argv.projectId,
 		branch: argv.branch,
@@ -4257,13 +4437,15 @@ await yargs(hideBin(process.argv)).scriptName("holocron").usage("$0 <command> [o
 	type: "string",
 	describe: "Repo coords (\"owner/name\"). Defaults to plugin-specific resolution."
 }), async (argv) => {
+	const tokens = tokenContext(argv.token);
+	if (!tokens) return;
 	if ((await runSync({
 		loaded: await loadConfig(argv.cwd),
 		context: {
 			repoRoot: argv.cwd,
 			dryRun: argv.dryRun,
 			...argv.repo ? { repo: argv.repo } : {},
-			...argv.token ? { cliToken: argv.token } : {}
+			...tokens
 		},
 		...argv.steps && argv.steps.length > 0 ? { steps: argv.steps } : {}
 	})).summary.fail > 0) process.exitCode = 1;
@@ -4286,7 +4468,9 @@ await yargs(hideBin(process.argv)).scriptName("holocron").usage("$0 <command> [o
 	describe: "Write generated files to this local directory instead of pushing (for validation)"
 }), async (argv) => {
 	const outputDir = argv["output-dir"];
-	const token = outputDir ? "no-token-needed" : argv.token ?? process.env.GITHUB_TOKEN ?? process.env.HOLOCRON_GITHUB_TOKEN;
+	const parsed = tokenContext(argv.token);
+	if (!parsed) return;
+	const token = outputDir ? "no-token-needed" : parsed.cliTokens?.["github"] ?? parsed.cliToken ?? process.env.GITHUB_TOKEN ?? process.env.HOLOCRON_GITHUB_TOKEN;
 	if (!token) {
 		console.error("sync-github: GitHub token required — pass --token or set GITHUB_TOKEN");
 		process.exitCode = 1;
@@ -4421,6 +4605,7 @@ await yargs(hideBin(process.argv)).scriptName("holocron").usage("$0 <command> [o
 }).command("list", "List every provider with a stored bootstrap token", () => {}, async () => {
 	await runAuthList();
 }).demandCommand(1, "Run `holocron auth --help` to see available auth subcommands."), () => {}).demandCommand(1, "Run `holocron --help` to see available commands.").strict().help().parse();
+(await updateCheckPromise)?.();
 /**
 * Parse `--scope` strings: `repo` | `env=NAME` | `org=NAME`.
 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/cli",
-  "version": "2.0.0-alpha.73",
+  "version": "2.0.0-alpha.75",
   "description": "The Holocron CLI — a pluggable, capability-based orchestrator for spinning up and operating software projects.",
   "homepage": "https://github.com/theholocron/holocron/tree/main/packages/cli#readme",
   "bugs": "https://github.com/theholocron/holocron/issues",