@yalehwang/cloudpit 2.0.0 → 3.0.0

package/scripts/brand-allowlist-check.test.mjs

@@ -25,13 +25,14 @@
 
 import assert from 'node:assert/strict';
 import { execFileSync, spawnSync } from 'node:child_process';
-import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import test from 'node:test';
 import { fileURLToPath } from 'node:url';
 
 import {
+  CURRENT_DOC_SURFACES,
   SCANNED_SURFACES,
   checkDistributionIdentity,
   checkPackedManifest,
@@ -58,6 +59,19 @@ const REQUIRED_SURFACES = [
   'index.html',
   'public/manifest.json',
   'README.md',
+  'CONTRIBUTING.md',
+  'docs/README.de.md',
+  'docs/README.ja.md',
+  'docs/README.ko.md',
+  'docs/README.ru.md',
+  'docs/README.tr.md',
+  'docs/README.zh-CN.md',
+  'docs/README.zh-TW.md',
+  'docs/architecture/cockpit-attention/01-planes.puml',
+  'docs/architecture/cockpit-attention/CARD-PROVIDERS.md',
+  'docs/architecture/cockpit-attention/INTERACTION-PRINCIPLES.md',
+  'docs/architecture/cockpit-attention/README.md',
+  'docs/architecture/knowledge-application/FACT-CONTRACT.md',
   'src/modules/i18n/locales/**/*.json',
   'src/shared/utils.ts',
   'src/modules/chat-session/utils/session/pageTitleNotification.ts',
@@ -322,3 +336,258 @@ test('AC7: the deprecated package name is a violation on update paths', () => {
   assert.equal(violationsFor('npm show @yalehwang/cloudcli version').length, 1);
   assert.equal(violationsFor('npm update -g @yalehwang/cloudcli').length, 1);
 });
+
+/**
+ * The current-documentation sweep: the docs a reader lands on today. Historical surfaces
+ * (`docs/proposals/`, `docs/experiments/`, `adr/`, `CHANGELOG.md`, `NOTICE`, `LICENSE`) are
+ * deliberately absent and must stay untouched.
+ */
+const REQUIRED_DOC_SURFACES = [
+  'README.md',
+  'CONTRIBUTING.md',
+  'docs/README.de.md',
+  'docs/README.ja.md',
+  'docs/README.ko.md',
+  'docs/README.ru.md',
+  'docs/README.tr.md',
+  'docs/README.zh-CN.md',
+  'docs/README.zh-TW.md',
+  'docs/architecture/cockpit-attention/01-planes.puml',
+  'docs/architecture/cockpit-attention/CARD-PROVIDERS.md',
+  'docs/architecture/cockpit-attention/INTERACTION-PRINCIPLES.md',
+  'docs/architecture/cockpit-attention/README.md',
+  'docs/architecture/knowledge-application/FACT-CONTRACT.md',
+];
+
+test('current docs: the declared doc surfaces cover every named file and the real tree is green', () => {
+  const declaredDocGlobs = CURRENT_DOC_SURFACES.map((surface) => surface.glob).sort();
+  assert.deepEqual(
+    declaredDocGlobs,
+    [...REQUIRED_DOC_SURFACES].sort(),
+    'CURRENT_DOC_SURFACES must list exactly the current-doc surfaces the task names',
+  );
+
+  const scannedGlobs = new Set(SCANNED_SURFACES.map((surface) => surface.glob));
+  for (const required of REQUIRED_DOC_SURFACES) {
+    assert.ok(scannedGlobs.has(required), `the scan surface list must include ${required}`);
+  }
+
+  const result = runBrandAllowlistCheck({ root: ROOT });
+  assert.deepEqual(result.violations, [], JSON.stringify(result.violations, null, 2));
+  assert.equal(result.exitCode, 0);
+  assert.equal(
+    result.readings.docSurfaces,
+    REQUIRED_DOC_SURFACES.length,
+    `the docSurfaces reading must cover every named path, got ${result.readings.docSurfaces}`,
+  );
+  assert.deepEqual(
+    [...result.readings.docSurfaceFiles].sort(),
+    [...REQUIRED_DOC_SURFACES].sort(),
+    'the checked doc-surface files must be exactly the named paths',
+  );
+});
+
+test('current docs: injecting CloudCLI into a README H1, a translated H1 and an architecture doc reds the scan', () => {
+  const cases = [
+    {
+      file: 'README.md',
+      text: read('README.md').replace('<h1>Cloudpit</h1>', '<h1>CloudCLI</h1>'),
+    },
+    {
+      file: 'docs/README.ja.md',
+      text: read('docs/README.ja.md').replace('<h1>Cloudpit', '<h1>CloudCLI'),
+    },
+    {
+      file: 'docs/architecture/cockpit-attention/README.md',
+      text: `${read('docs/architecture/cockpit-attention/README.md')}\nCloudCLI 只做只读投影。\n`,
+    },
+  ];
+
+  for (const { file, text } of cases) {
+    assert.notEqual(text, read(file), `${file}: the false-form override must change the file`);
+    const result = runBrandAllowlistCheck({ root: ROOT, overrides: { [file]: text } });
+    assert.equal(result.exitCode, 1, `${file}: injecting CloudCLI must fail the check`);
+    assert.ok(
+      result.violations.some(
+        (violation) => violation.file === file && violation.message.includes('CloudCLI'),
+      ),
+      `${file}: the violation must name the file, got ${JSON.stringify(result.violations)}`,
+    );
+  }
+
+  // The head scan must not widen the allowlist: upstream attribution prose in a translated
+  // README body is expected to keep `CloudCLI UI` and stays outside the scanned lines.
+  const jaBodyOverride = `${read('docs/README.ja.md')}\nCloudCLI UI は上流の製品名です。\n`;
+  const bodyResult = runBrandAllowlistCheck({
+    root: ROOT,
+    overrides: { 'docs/README.ja.md': jaBodyOverride },
+  });
+  assert.equal(
+    bodyResult.exitCode,
+    0,
+    `translated-README body attribution must stay outside the head scan:\n${JSON.stringify(bodyResult.violations, null, 2)}`,
+  );
+});
+
+test('AC8: the code-wide CloudCLI sweep scans every text line and its allowlist is file-scoped', () => {
+  const brandLineGlobs = SCANNED_SURFACES
+    .filter((surface) => surface.kind === 'brand-lines')
+    .map((surface) => surface.glob);
+  for (const required of ['server/**', 'src/**', 'electron/**', 'scripts/**', 'public/**']) {
+    assert.ok(brandLineGlobs.includes(required), `the code-wide sweep must cover ${required}`);
+  }
+
+  const result = runBrandAllowlistCheck({ root: ROOT });
+  assert.equal(result.exitCode, 0, JSON.stringify(result.violations, null, 2));
+  assert.ok(
+    result.readings.brandLineFiles > 1500,
+    `the code-wide sweep must expand over the source tree, got ${result.readings.brandLineFiles} files`,
+  );
+
+  const brandLineFiles = new Set(
+    result.sources.filter((source) => source.brandLines).map((source) => source.file),
+  );
+  for (const unscannable of [
+    'server/shared/tests/architecture-ratchet.baseline.json',
+    'server/modules/quay/tests/contracts/README.md',
+    'scripts/brand-allowlist-check.mjs',
+    'scripts/brand-allowlist-check.test.mjs',
+  ]) {
+    assert.ok(!brandLineFiles.has(unscannable), `${unscannable} must stay outside the sweep`);
+  }
+  for (const file of brandLineFiles) {
+    assert.match(file, /\.(?:ts|tsx|js|mjs|cjs|sh|html)$/, `${file} is not a text source extension`);
+  }
+
+  // Negative control 1: a user-visible notification title.
+  const notificationFile = 'server/modules/notifications/services/notification-orchestrator.service.js';
+  const notificationResult = runBrandAllowlistCheck({
+    root: ROOT,
+    overrides: {
+      [notificationFile]: read(notificationFile)
+        .replace("title: sessionName || 'Cloudpit'", "title: sessionName || 'CloudCLI'"),
+    },
+  });
+  assert.equal(notificationResult.exitCode, 1, 'a CloudCLI notification title must red the sweep');
+  assert.ok(notificationResult.violations.some((violation) => violation.file === notificationFile));
+
+  // Negative control 2: a comment line in shipped backend source (the `code` kind skips these,
+  // the code-wide sweep must not).
+  const schemaFile = 'server/modules/database/schema.ts';
+  const commentResult = runBrandAllowlistCheck({
+    root: ROOT,
+    overrides: { [schemaFile]: ' * the CloudCLI project id.\n' },
+  });
+  assert.equal(commentResult.exitCode, 1, 'a CloudCLI comment must red the sweep');
+  assert.ok(
+    commentResult.violations.some(
+      (violation) => violation.file === schemaFile && violation.message.includes('CloudCLI'),
+    ),
+  );
+
+  // Positive control: the third-party plugin name stays green in the same sweep.
+  const prismResult = runBrandAllowlistCheck({
+    root: ROOT,
+    overrides: { [notificationFile]: `${read(notificationFile)}\n// PRISM CloudCLI\n` },
+  });
+  assert.equal(
+    prismResult.exitCode,
+    0,
+    `PRISM CloudCLI must stay allowlisted:\n${JSON.stringify(prismResult.violations, null, 2)}`,
+  );
+
+  // File scoping: the legacy literal is allowed inside the migration module and its tests, but
+  // the same token in product code is a violation.
+  const legacyFile = 'electron/userDataMigration.js';
+  const legacyResult = runBrandAllowlistCheck({
+    root: ROOT,
+    overrides: { [legacyFile]: `${read(legacyFile)}\nconst legacyTitle = 'CloudCLI';\n` },
+  });
+  assert.equal(legacyResult.exitCode, 0, 'the legacy install literal must stay allowed in its own file');
+
+  const productResult = runBrandAllowlistCheck({
+    root: ROOT,
+    overrides: { 'electron/cloud.js': "throw new Error('CloudCLI');\n" },
+  });
+  assert.equal(productResult.exitCode, 1, 'the legacy allowlist must not leak into another file');
+});
+
+/**
+ * Build a deterministic checkout fixture for the generated-cache regression. The real main
+ * checkout carried the e2e bundle cache under `server/node_modules/.cache`; a task worktree did
+ * not, so an arm that read the real tree would be green or red depending on where it ran. This
+ * fixture models both shapes at once — a generated cache next to real source — and supplies
+ * every declared surface the fixture does not model as an override, so no read ever depends on
+ * the host checkout.
+ *
+ * @returns {{ root: string, overrides: Record<string, string>, staleModule: string, gitHook: string, sourceFile: string }}
+ */
+function makeCacheFixture() {
+  const root = mkdtempSync(path.join(os.tmpdir(), 'cloudpit-brand-fixture-'));
+  for (const surface of SCANNED_SURFACES) {
+    const wildcardIndex = surface.glob.indexOf('/**');
+    if (wildcardIndex !== -1) {
+      mkdirSync(path.join(root, surface.glob.slice(0, wildcardIndex)), { recursive: true });
+    }
+  }
+
+  const staleModule = 'server/node_modules/.cache/quay-e2e-build/stale.mjs';
+  const gitHook = 'server/.git/hooks/pre-commit.sh';
+  const sourceFile = 'server/modules/demo/source.ts';
+  mkdirSync(path.dirname(path.join(root, staleModule)), { recursive: true });
+  mkdirSync(path.dirname(path.join(root, gitHook)), { recursive: true });
+  mkdirSync(path.dirname(path.join(root, sourceFile)), { recursive: true });
+  writeFileSync(path.join(root, staleModule), "export const stale = 'CloudCLI';\n");
+  writeFileSync(path.join(root, gitHook), 'echo CloudCLI\n');
+  writeFileSync(path.join(root, sourceFile), "export const brand = 'Cloudpit';\n");
+  writeFileSync(path.join(root, 'package.json'), JSON.stringify({
+    name: '@yalehwang/cloudpit',
+    bin: { cloudpit: 'dist-server/server/modules/cli/cli.js' },
+    productName: 'Cloudpit',
+    build: { productName: 'Cloudpit', artifactName: 'cloudpit-desktop-fixture' },
+  }));
+
+  /** @type {Record<string, string>} */
+  const overrides = {};
+  for (const surface of SCANNED_SURFACES) {
+    if (surface.glob.includes('/**')) continue;
+    if (existsSync(path.join(root, surface.glob))) continue;
+    overrides[surface.glob] = surface.kind === 'json-values' ? '{}' : '';
+  }
+
+  return { root, overrides, staleModule, gitHook, sourceFile };
+}
+
+test('regression: the code-wide sweep skips node_modules and .git caches but still reds real source', () => {
+  const { root, overrides, staleModule, gitHook, sourceFile } = makeCacheFixture();
+  try {
+    // The fixture is only meaningful if the skipped files really carry the swept token.
+    assert.match(readFileSync(path.join(root, staleModule), 'utf8'), /CloudCLI/, 'the cache fixture must carry CloudCLI');
+    assert.match(readFileSync(path.join(root, gitHook), 'utf8'), /CloudCLI/, 'the .git fixture must carry CloudCLI');
+
+    const green = runBrandAllowlistCheck({ root, overrides });
+    assert.deepEqual(green.violations, [], JSON.stringify(green.violations, null, 2));
+    assert.equal(green.exitCode, 0, 'a generated node_modules cache must not red the brand sweep');
+
+    const scannedFiles = new Set(green.sources.map((source) => source.file));
+    assert.ok(scannedFiles.has(sourceFile), 'the sweep must still reach real source under server/');
+    assert.ok(!scannedFiles.has(staleModule), 'the generated cache must stay outside the sweep');
+    assert.ok(!scannedFiles.has(gitHook), '.git internals must stay outside the sweep');
+    assert.ok(
+      [...scannedFiles].every((file) => !file.split('/').includes('node_modules')),
+      'no file with a node_modules path segment may be scanned',
+    );
+
+    const red = runBrandAllowlistCheck({
+      root,
+      overrides: { ...overrides, [sourceFile]: "export const brand = 'CloudCLI';\n" },
+    });
+    assert.equal(red.exitCode, 1, 'real source carrying CloudCLI must still red the sweep');
+    assert.ok(
+      red.violations.some((violation) => violation.file === sourceFile),
+      `the violation must name the source file, got ${JSON.stringify(red.violations)}`,
+    );
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/scripts/cloudpit-distribution-check.mjs

@@ -5,11 +5,17 @@
  * AC-454 asks whether the *external* release actually happened:
  *
  *   - `@yalehwang/cloudcli@1.42.0` is deprecated and the notice points at the new package;
- *   - `@yalehwang/cloudpit@2.0.0` is published and its packed tarball exposes only the
+ *   - `@yalehwang/cloudpit@<version>` is published and its packed tarball exposes only the
  *     `cloudpit` bin;
  *   - the `yaleh/cloudpit` repository URL, homepage, repository and bugs fields resolve;
- *   - the desktop `cloudpit-desktop-*` and `cloudpit-local-server-v2.0.0-*` release assets
- *     are downloadable;
+ *   - the desktop `cloudpit-desktop-*` and `cloudpit-local-server-v<version>-*` release
+ *     assets are downloadable;
+ *
+ * VERSIONED READING. The release being verified is a parameter, not a baked-in target:
+ * `NEW_VERSION` (3.0.0) is the default, and `--version <x.y.z>` reads any other release
+ * (for example the historical `--version 2.0.0` reading of AC-458's 2.0.0 release). The
+ * npm version document, the packed-manifest lookup, the GitHub release tag and the
+ * local-server asset prefix all derive from that one value.
  *   - README/NOTICE/LICENSE still carry the upstream CloudCLI UI attribution.
  *
  * ONE JUDGEMENT PATH. `distributionViolations(snapshot)` is the only place those six checks are
@@ -35,16 +41,23 @@ import { fileURLToPath } from 'node:url';
 /** The final legacy package, deprecated in favour of the new name. */
 export const OLD_PACKAGE = '@yalehwang/cloudcli';
 export const OLD_VERSION = '1.42.0';
-/** The renamed package and the version the release sequence publishes. */
+/** The renamed package and the default version this verifier reads. */
 export const NEW_PACKAGE = '@yalehwang/cloudpit';
-export const NEW_VERSION = '2.0.0';
+/** The release the default reading targets; `--version` overrides it per invocation. */
+export const NEW_VERSION = '3.0.0';
 /** The repository the rename points every URL field at. */
 export const REPOSITORY = 'yaleh/cloudpit';
 /** The attribution token the upstream licence terms require the documents to keep. */
 export const ATTRIBUTION = 'CloudCLI UI';
 /** Asset-name prefixes the desktop release must publish. */
 export const DESKTOP_ASSET_PREFIX = 'cloudpit-desktop-';
-export const LOCAL_SERVER_ASSET_PREFIX = `cloudpit-local-server-v${NEW_VERSION}-`;
+/** The local-server asset prefix for one release version (defaults to {@link NEW_VERSION}). */
+export function localServerAssetPrefix(version = NEW_VERSION) {
+  return `cloudpit-local-server-v${version}-`;
+}
+export const LOCAL_SERVER_ASSET_PREFIX = localServerAssetPrefix(NEW_VERSION);
+/** A semver-shaped release version accepted by `--version`. */
+const VERSION_PATTERN = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
 /** The repository fields AC-454 names. */
 export const REQUIRED_REPOSITORY_FIELDS = ['url', 'homepage', 'repository', 'bugs'];
 /** The six check groups, in one place so a count in a reading cannot drift from the judgements. */
@@ -128,9 +141,10 @@ const EXPECTED_REPOSITORY_PATHS = {
  * `collectReleaseSnapshot`, callers that want an offline reading use `loadSnapshotFromFile`.
  *
  * @param {DistributionSnapshot | null | undefined} snapshot
+ * @param {{ version?: string }} [options] release version to judge (defaults to NEW_VERSION)
  * @returns {DistributionViolation[]}
  */
-export function distributionViolations(snapshot) {
+export function distributionViolations(snapshot, { version = NEW_VERSION } = {}) {
   /** @type {DistributionViolation[]} */
   const violations = [];
   const npm = snapshot?.npm;
@@ -160,12 +174,12 @@ export function distributionViolations(snapshot) {
   if (
     !newPackage
     || newPackage.name !== NEW_PACKAGE
-    || newPackage.version !== NEW_VERSION
+    || newPackage.version !== version
     || newPackage.published !== true
   ) {
     violations.push(violation(
       'new-package',
-      `new package ${NEW_PACKAGE}@${NEW_VERSION} is not published`,
+      `new package ${NEW_PACKAGE}@${version} is not published`,
     ));
   }
   if (newPackage) {
@@ -226,7 +240,7 @@ export function distributionViolations(snapshot) {
     && asset.name.startsWith(prefix)
     && asset.downloadable === true
   ));
-  for (const prefix of [DESKTOP_ASSET_PREFIX, LOCAL_SERVER_ASSET_PREFIX]) {
+  for (const prefix of [DESKTOP_ASSET_PREFIX, localServerAssetPrefix(version)]) {
     if (!downloadable(prefix)) {
       violations.push(violation(
         'desktop-assets',
@@ -396,16 +410,17 @@ async function repositoryField(fetchImpl, field, url) {
 /**
  * @param {typeof fetch} fetchImpl
  * @param {any} release
+ * @param {string} version
  * @returns {Promise<ReleaseAssetSnapshot[]>}
  */
-async function releaseAssets(fetchImpl, release) {
+async function releaseAssets(fetchImpl, release, version) {
   /** @type {any[]} */
   const raw = Array.isArray(release?.assets) ? release.assets : [];
   return Promise.all(raw.map(async (asset) => {
     const name = String(asset?.name ?? '');
     const url = String(asset?.browser_download_url ?? '');
     const isCandidate = name.startsWith(DESKTOP_ASSET_PREFIX)
-      || name.startsWith(LOCAL_SERVER_ASSET_PREFIX);
+      || name.startsWith(localServerAssetPrefix(version));
     const downloadable = asset?.state === 'uploaded'
       && (isCandidate ? await resolves(fetchImpl, url) : true);
     return { name, url, downloadable };
@@ -428,6 +443,7 @@ async function releaseAssets(fetchImpl, release) {
  *   root?: string,
  *   fetchImpl?: typeof fetch,
  *   githubToken?: string | undefined,
+ *   version?: string,
  * }} [options]
  * @returns {Promise<DistributionSnapshot>}
  */
@@ -435,6 +451,7 @@ export async function collectReleaseSnapshot({
   root = process.cwd(),
   fetchImpl = globalThis.fetch,
   githubToken = process.env.GITHUB_TOKEN,
+  version = NEW_VERSION,
 } = {}) {
   if (typeof fetchImpl !== 'function') {
     throw new Error('no fetch implementation is available for --release');
@@ -445,10 +462,10 @@ export async function collectReleaseSnapshot({
   const [oldMetadata, newMetadata, packedManifest, repoMetadata, releaseMetadata] =
     await Promise.all([
       requestJson(fetchImpl, `https://registry.npmjs.org/${encodeURIComponent(OLD_PACKAGE)}/${OLD_VERSION}`),
-      requestJson(fetchImpl, `https://registry.npmjs.org/${encodeURIComponent(NEW_PACKAGE)}/${NEW_VERSION}`),
-      requestJson(fetchImpl, `https://unpkg.com/${NEW_PACKAGE}@${NEW_VERSION}/package.json`),
+      requestJson(fetchImpl, `https://registry.npmjs.org/${encodeURIComponent(NEW_PACKAGE)}/${version}`),
+      requestJson(fetchImpl, `https://unpkg.com/${NEW_PACKAGE}@${version}/package.json`),
       requestJson(fetchImpl, `https://api.github.com/repos/${REPOSITORY}`, { headers: githubHeaders }),
-      requestJson(fetchImpl, `https://api.github.com/repos/${REPOSITORY}/releases/tags/v${NEW_VERSION}`, {
+      requestJson(fetchImpl, `https://api.github.com/repos/${REPOSITORY}/releases/tags/v${version}`, {
         headers: githubHeaders,
       }),
     ]);
@@ -468,7 +485,7 @@ export async function collectReleaseSnapshot({
       },
       newPackage: {
         name: NEW_PACKAGE,
-        version: NEW_VERSION,
+        version,
         published: newMetadata.ok,
         tarballBin,
       },
@@ -486,7 +503,7 @@ export async function collectReleaseSnapshot({
         repositoryField(fetchImpl, 'bugs', packageJson?.bugs?.url),
       ]),
     },
-    release: { assets: await releaseAssets(fetchImpl, releaseMetadata.body) },
+    release: { assets: await releaseAssets(fetchImpl, releaseMetadata.body, version) },
     ownership: {
       readme: readTextOrEmpty(path.join(root, 'README.md')),
       notice: readTextOrEmpty(path.join(root, 'NOTICE')),
@@ -501,14 +518,16 @@ export function usage() {
     'Cloudpit distribution verifier (AC-457 carrier / AC-454 criterion)',
     '',
     'Usage:',
-    '  node scripts/cloudpit-distribution-check.mjs --release',
-    '  node scripts/cloudpit-distribution-check.mjs --fixture <snapshot.json> [--json]',
+    '  node scripts/cloudpit-distribution-check.mjs --release [--version <x.y.z>]',
+    '  node scripts/cloudpit-distribution-check.mjs --fixture <snapshot.json> [--version <x.y.z>] [--json]',
     '  node scripts/cloudpit-distribution-check.mjs --help',
     '',
     'Modes:',
     '  --release            read npm, GitHub secrets/URLs and the local documents, then judge',
     '  --fixture <path>     judge a recorded snapshot without network access',
     '  --root <dir>         repository root for local documents (default: current directory)',
+    `  --version <x.y.z>    release version to verify (default: ${NEW_VERSION}; e.g. 2.0.0`,
+    '                       reads the historical 2.0.0 release)',
     '  --json               print the verdict and violations as JSON',
     '  --help               print this help and exit 0',
     '',
@@ -521,6 +540,7 @@ export function usage() {
  *   mode: 'release' | 'fixture' | null,
  *   fixture: string | null,
  *   root: string,
+ *   version: string | null,
  *   json: boolean,
  *   help: boolean,
  *   error: string | null,
@@ -532,6 +552,7 @@ function parseArgs(argv) {
     mode: null,
     fixture: null,
     root: process.cwd(),
+    version: null,
     json: false,
     help: false,
     error: null,
@@ -552,6 +573,18 @@ function parseArgs(argv) {
     } else if (arg === '--root') {
       options.root = path.resolve(argv[index + 1] ?? '.');
       if (argv[index + 1] !== undefined) index += 1;
+    } else if (arg === '--version') {
+      options.version = argv[index + 1] ?? null;
+      if (options.version === null) {
+        if (options.error === null) options.error = '--version needs a semver value';
+      } else if (!VERSION_PATTERN.test(options.version)) {
+        if (options.error === null) {
+          options.error = `--version must be a semver version, got ${JSON.stringify(options.version)}`;
+        }
+        index += 1;
+      } else {
+        index += 1;
+      }
     } else if (arg === '--json') {
       options.json = true;
     } else if (arg === '--help' || arg === '-h') {
@@ -593,6 +626,7 @@ export async function main(argv = process.argv.slice(2), {
     return 2;
   }
 
+  const version = options.version ?? NEW_VERSION;
   /** @type {DistributionSnapshot} */
   let snapshot;
   /** @type {string} */
@@ -602,7 +636,7 @@ export async function main(argv = process.argv.slice(2), {
       snapshot = loadSnapshotFromFile(/** @type {string} */ (options.fixture));
       source = `fixture:${options.fixture}`;
     } else {
-      snapshot = await collectReleaseSnapshot({ root: options.root, fetchImpl });
+      snapshot = await collectReleaseSnapshot({ root: options.root, fetchImpl, version });
       source = 'release';
     }
   } catch (error) {
@@ -610,14 +644,14 @@ export async function main(argv = process.argv.slice(2), {
     return 2;
   }
 
-  const violations = distributionViolations(snapshot);
+  const violations = distributionViolations(snapshot, { version });
   const exitCode = violations.length === 0 ? 0 : 1;
 
   if (options.json) {
-    stdout.log(JSON.stringify({ source, exitCode, checks: CHECKS, violations }, null, 2));
+    stdout.log(JSON.stringify({ source, version, exitCode, checks: CHECKS, violations }, null, 2));
   } else {
     stdout.log(
-      `cloudpit-distribution: source=${source} checks=${CHECKS.length} `
+      `cloudpit-distribution: source=${source} version=${version} checks=${CHECKS.length} `
         + `violations=${violations.length}`,
     );
     for (const item of violations) {

package/scripts/cloudpit-distribution-check.test.mjs

@@ -16,6 +16,9 @@
  *   AC2e — the desktop/local-server assets are missing     → red names both asset prefixes.
  *   AC2f — the ownership notice is deleted from each doc   → red names `ownership`.
  *   AC4 — `--help` exits 0 and lists `--release`.
+ *   AC5 — a 2.0.0 snapshot is red under the 3.0.0 default and green with
+ *         `--version 2.0.0`: the historical release stays readable without being
+ *         mistaken for the current one.
  *
  * NOTHING HERE TOUCHES THE NETWORK. Fixture mode reads a JSON file; no arm runs `--release`.
  * The compliant snapshot reads the real README/NOTICE/LICENSE, so a document that loses its
@@ -40,6 +43,7 @@ import {
   OLD_VERSION,
   REPOSITORY,
   distributionViolations,
+  localServerAssetPrefix,
 } from './cloudpit-distribution-check.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
@@ -86,7 +90,7 @@ function compliantSnapshot() {
     },
     release: {
       assets: [
-        { name: `${DESKTOP_ASSET_PREFIX}2.0.0-linux-x64.deb`, downloadable: true },
+        { name: `${DESKTOP_ASSET_PREFIX}${NEW_VERSION}-linux-x64.deb`, downloadable: true },
         { name: `${LOCAL_SERVER_ASSET_PREFIX}linux-x64.tar.gz`, downloadable: true },
       ],
     },
@@ -102,14 +106,15 @@ function compliantSnapshot() {
  * Run the production CLI against one snapshot in fixture mode.
  *
  * @param {any} snapshot
+ * @param {string[]} [extraArgs] additional CLI arguments (e.g. `--version`)
  * @returns {{ status: number | null, stdout: string, stderr: string }}
  */
-function runFixture(snapshot) {
+function runFixture(snapshot, extraArgs = []) {
   const directory = mkdtempSync(path.join(tmpdir(), 'cloudpit-distribution-'));
   try {
     const fixture = path.join(directory, 'snapshot.json');
     writeFileSync(fixture, JSON.stringify(snapshot), 'utf8');
-    const result = spawnSync(process.execPath, [SCRIPT, '--fixture', fixture], {
+    const result = spawnSync(process.execPath, [SCRIPT, '--fixture', fixture, ...extraArgs], {
       encoding: 'utf8',
       // The fixture path is the only input; no environment switch can reach the live reader.
       env: { ...process.env, GITHUB_TOKEN: '' },
@@ -154,7 +159,7 @@ test('AC2b: a new package that is not published reds', () => {
   assert.equal(result.status, 1, result.stderr);
   assert.match(
     result.stderr,
-    /new-package: new package @yalehwang\/cloudpit@2\.0\.0 is not published/,
+    new RegExp(`new-package: new package @yalehwang/cloudpit@${NEW_VERSION.replaceAll('.', '\\.')} is not published`),
     result.stderr,
   );
 });
@@ -197,7 +202,7 @@ test('AC2d: each unresolvable repository field reds and is named', () => {
 test('AC2e: missing desktop and local-server assets red and name both prefixes', () => {
   const snapshot = compliantSnapshot();
   snapshot.release.assets = [
-    { name: `${DESKTOP_ASSET_PREFIX}2.0.0-linux-x64.deb`, downloadable: false },
+    { name: `${DESKTOP_ASSET_PREFIX}${NEW_VERSION}-linux-x64.deb`, downloadable: false },
   ];
 
   const result = runFixture(snapshot);
@@ -207,9 +212,10 @@ test('AC2e: missing desktop and local-server assets red and name both prefixes',
     /desktop release asset cloudpit-desktop-\* is missing or not downloadable/,
     result.stderr,
   );
-  assert.match(
-    result.stderr,
-    /desktop release asset cloudpit-local-server-v2\.0\.0-\* is missing or not downloadable/,
+  assert.ok(
+    result.stderr.includes(
+      `desktop release asset ${localServerAssetPrefix(NEW_VERSION)}* is missing or not downloadable`,
+    ),
     result.stderr,
   );
 });
@@ -248,8 +254,35 @@ test('AC2f: deleting the ownership notice from each document reds', () => {
   }
 });
 
-test('AC4: --help exits 0 and lists --release', () => {
+test('AC4: --help exits 0 and lists --release and --version', () => {
   const result = spawnSync(process.execPath, [SCRIPT, '--help'], { encoding: 'utf8' });
   assert.equal(result.status, 0, result.stderr);
   assert.match(result.stdout, /--release/, result.stdout);
+  assert.match(result.stdout, /--version/, result.stdout);
+  assert.ok(result.stdout.includes(NEW_VERSION), result.stdout);
+});
+
+test('AC5: the historical 2.0.0 release is readable only through an explicit --version', () => {
+  /** @param {string} version @returns {any} */
+  const historicalSnapshot = (version) => {
+    const snapshot = compliantSnapshot();
+    snapshot.npm.newPackage.version = version;
+    snapshot.release.assets[0].name = `${DESKTOP_ASSET_PREFIX}${version}-linux-x64.deb`;
+    snapshot.release.assets[1].name = `${localServerAssetPrefix(version)}linux-x64.tar.gz`;
+    return snapshot;
+  };
+
+  // Negative arm: under the 3.0.0 default the 2.0.0 snapshot is NOT read as the current
+  // release — the red names 3.0.0, so a stale 2.0.0 fixture cannot make the default green.
+  const asCurrent = runFixture(historicalSnapshot('2.0.0'));
+  assert.equal(asCurrent.status, 1, asCurrent.stderr);
+  assert.ok(
+    asCurrent.stderr.includes(`new package @yalehwang/cloudpit@${NEW_VERSION} is not published`),
+    asCurrent.stderr,
+  );
+
+  // Positive arm: the historical release remains verifiable when asked for explicitly.
+  const historical = runFixture(historicalSnapshot('2.0.0'), ['--version', '2.0.0']);
+  assert.equal(historical.status, 0, historical.stderr);
+  assert.match(historical.stdout, /violations=0/, historical.stdout);
 });

package/scripts/codex-protocol-smoke.mjs

@@ -222,7 +222,7 @@ class AppServerConnection {
 async function handshake(connection, experimentalApi) {
   const capabilities = experimentalApi ? { experimentalApi: true } : {};
   const reply = await connection.request('initialize', {
-    clientInfo: { name: 'cloudcli', title: 'CloudCLI', version: '1' },
+    clientInfo: { name: 'cloudpit', title: 'Cloudpit', version: '1' },
     capabilities,
   });
   connection.notify('initialized', {});

package/scripts/isolated-instance.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 #
-# A THROWAWAY, SAFE-TO-BOOT CloudCLI instance for verification work.
+# A THROWAWAY, SAFE-TO-BOOT Cloudpit instance for verification work.
 #
 # WHY IT EXISTS. Verifying a UI/API change by hand used to mean copying the live auth.db and
 # starting a second server on it. The resident-restore pass is ON by default, so that second