@celilo/cli 2.3.0 → 3.0.0

package/CELILO_CORE_MODULES.md

@@ -85,4 +85,4 @@ Each entry: `module id` — what it is — **provides** / **requires** capabilit
 
 ## Archived / superseded
 
-`modules/archive/` holds retired modules — **dns-external** (VPS authoritative DNS + WireGuard, superseded by the `dns_internal`/`dns_registrar` split), **gmail** (email-reading capability), **namecheap-api** (registrar-config via Namecheap API, superseded by the **namecheap** DDNS module). Reference only; not deployed.
+`modules/__archive__/` holds retired modules — **dns-external** (VPS authoritative DNS + WireGuard, superseded by the `dns_internal`/`dns_registrar` split), **gmail** (email-reading capability), **namecheap-api** (registrar-config via Namecheap API, superseded by the **namecheap** DDNS module). Reference only; not deployed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "2.3.0",
+  "version": "3.0.0",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -58,9 +58,9 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1109.0",
     "@aws-sdk/lib-storage": "^3.1101.0",
-    "@celilo/capabilities": "^4.3.0",
+    "@celilo/capabilities": "^5.0.0",
     "@celilo/cli-display": "^0.2.0",
-    "@celilo/core": "^0.12.0",
+    "@celilo/core": "^0.13.0",
     "@celilo/event-bus": "^0.6.0",
     "ajv": "^8.18.0",
     "drizzle-orm": "^0.36.4",

package/src/api/serve.ts

@@ -139,7 +139,19 @@ async function runCommand(argv: string[], forward: (msg: ServerMessage) => void)
     stderr: 'pipe',
   });
 
-  await Promise.all([pumpLines(child.stdout, forward), pumpLines(child.stderr, forward)]);
+  // Each stream is pumped separately and the log message names its origin,
+  // so a client can keep stderr distinguishable from the command's result
+  // (celilo#1362 — the two used to merge into one undifferentiated channel).
+  const markStream =
+    (stream: 'stdout' | 'stderr') =>
+    (msg: ServerMessage): void => {
+      forward(msg.type === 'log' ? { ...msg, stream } : msg);
+    };
+
+  await Promise.all([
+    pumpLines(child.stdout, markStream('stdout')),
+    pumpLines(child.stderr, markStream('stderr')),
+  ]);
   const exitCode = await child.exited;
   forward(resultMessage(exitCode === 0, exitCode));
   return exitCode;

package/src/cli/commands/module-health.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from 'bun:test';
+import { formatResult } from './module-health';
+
+describe('module health rendering — the waiver annotation', () => {
+  test('a waived no-checks module renders the waiver beside the verdict, not instead of it', () => {
+    const output = formatResult({
+      moduleId: 'namecheap',
+      status: 'no-checks',
+      checks: [],
+      waiver: {
+        reason: 'API-only: a real check is hard and may not be worth forcing',
+        by: 'peba',
+        at: '2026-09-09',
+      },
+    });
+
+    // The unmeasured verdict is still stated.
+    expect(output).toContain('no health check defined');
+    // The annotation names the human's words, who, and when.
+    expect(output).toContain(
+      'waived: API-only: a real check is hard and may not be worth forcing (by peba at 2026-09-09)',
+    );
+  });
+
+  test('a no-checks module without a waiver renders no waiver line', () => {
+    const output = formatResult({
+      moduleId: 'iptables',
+      status: 'no-checks',
+      checks: [],
+    });
+
+    expect(output).toContain('no health check defined');
+    expect(output).not.toContain('waived:');
+  });
+});

package/src/cli/commands/module-health.ts

@@ -26,12 +26,20 @@ const CHECK_ICONS: Record<string, string> = {
   skip: '○',
 };
 
-function formatResult(result: HealthCheckResult): string {
+export function formatResult(result: HealthCheckResult): string {
   const icon = STATUS_ICONS[result.status] || '?';
   const lines: string[] = [];
 
   if (result.status === 'no-checks') {
     lines.push(`  ${result.moduleId} ${icon} no health check defined`);
+    // Annotate the waiver beside the verdict, never instead of it: the
+    // module is still unmeasured, a human just decided it needs no check
+    // (openspec/changes/health-waiver-mechanism, D3).
+    if (result.waiver) {
+      lines.push(
+        `      waived: ${result.waiver.reason} (by ${result.waiver.by} at ${result.waiver.at})`,
+      );
+    }
     return lines.join('\n');
   }
 
@@ -70,10 +78,10 @@ export async function handleModuleHealth(
   let results: HealthCheckResult[];
 
   if (moduleId) {
-    const result = await runModuleHealthCheck(moduleId, db, { debug });
+    const result = await runModuleHealthCheck(moduleId, db, { debug, quiet: jsonOutput });
     results = [result];
   } else {
-    results = await runAllHealthChecks(db, { debug });
+    results = await runAllHealthChecks(db, { debug, quiet: jsonOutput });
   }
 
   if (jsonOutput) {

package/src/cli/commands/module-publish.test.ts

@@ -99,6 +99,28 @@ describe('handleModulePublish — manifest reading', () => {
     expect(result.success).toBe(false);
     if (!result.success) expect(result.error).toContain('manifest.yml missing id or version');
   });
+
+  test('a failed module does not stop the sweep — every module is attempted and every failure is named', async () => {
+    // celilo#1369: the loop bailed at the first failed module, so modules
+    // after it were never attempted (release run 6705 left nine modules
+    // unpublished). Three dirs that each fail before any registry access,
+    // at three different checks, prove the loop reaches all of them: the
+    // returned error must name every dir, not only the first.
+    const dirA = join(TEST_DIR, 'a-missing-id');
+    const dirB = join(TEST_DIR, 'b-missing-manifest');
+    const dirC = join(TEST_DIR, 'c-missing-version');
+    for (const d of [dirA, dirB, dirC]) await mkdir(d, { recursive: true });
+    await writeFile(join(dirA, 'manifest.yml'), 'version: "1.0.0"\n');
+    await writeFile(join(dirC, 'manifest.yml'), 'id: c-module\n');
+
+    const result = await handleModulePublish([dirA, dirB, dirC], { token: 'tok' });
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error).toContain(dirA);
+      expect(result.error).toContain(dirB);
+      expect(result.error).toContain(dirC);
+    }
+  });
 });
 
 // ── Revision auto-detection algorithm ────────────────────────────────────────

package/src/cli/commands/module-publish.ts

@@ -385,23 +385,25 @@ export async function handleModulePublish(
   for (const moduleDir of args) {
     const outcome = await publishOneModule(moduleDir, opts);
     outcomes.push(outcome);
-    if (outcome.status === 'failed') {
-      // Print summary so far, then bail. Publishes are non-destructive so
-      // re-running after fixing the underlying issue picks up where we left
-      // off (already-published modules are skipped at the registry level
-      // when --revision is explicit, and auto-revision just picks the next
-      // slot — nothing duplicates).
-      printSummary(outcomes);
-      return {
-        success: false,
-        error: outcome.message,
-      };
-    }
     console.log(outcome.message);
   }
 
+  // celilo#1369: every module is attempted even after a failure, and every
+  // failure is reported together at the end. A publish is non-destructive so
+  // re-running after fixing the underlying issue picks up where we left off
+  // (already-published modules are skipped at the registry level when
+  // --revision is explicit, and auto-revision just picks the next slot —
+  // nothing duplicates).
   printSummary(outcomes);
 
+  const failed = outcomes.filter((o) => o.status === 'failed');
+  if (failed.length > 0) {
+    return {
+      success: false,
+      error: failed.map((o) => o.message).join('\n'),
+    };
+  }
+
   if (args.length === 1) {
     // Backward-compat single-module shape — keep the existing message/data
     // contract for callers (and tests) that depend on it. By this point no

package/src/cli/commands/module-update.ts

@@ -52,7 +52,7 @@ type UpdateOutcome =
   | { status: 'failed'; moduleId: string; error: string }
   // `skipped` means the path expanded from a glob but isn't an
   // upgradable target — either no manifest at all (probably a non-
-  // module sibling like `modules/archive/`) or a real module that
+  // module sibling like `modules/__archive__/`) or a real module that
   // isn't installed in this celilo. Treated as a soft pass so
   // `celilo module update modules/*` does what users expect.
   | { status: 'skipped'; moduleId: string; reason: string };
@@ -115,34 +115,86 @@ export function classifyVersionChange(installed: string, latest: string): Versio
 }
 
 /**
- * Download a module package from the registry into a temp file and run
- * the standard updateOne path against it. Cleans the temp file in a
- * finally block so a mid-flight failure doesn't leak a tar.zst on disk.
+ * Download a registry package into a temp file. Shared by `fetchAndUpdate`
+ * (the full update path) and `fetchTargetManifest` (the upgrade gate that
+ * must read the TARGET manifest before it mutates anything). The index entry
+ * carries the published sha256; absence is tolerated, matching
+ * `fetchAndUpdate`'s original tolerance for entries predating cksum.
  */
-export async function fetchAndUpdate(
+export async function downloadRegistryPackage(
   client: RegistryClient,
   moduleId: string,
   version: string,
-  db: ReturnType<typeof getDb>,
-  flags: Record<string, string | boolean>,
-): Promise<UpdateOutcome> {
+): Promise<{ ok: true; tmpPath: string } | { ok: false; error: string }> {
   const tmpPath = join(tmpdir(), `${moduleId}-${version}-${Date.now()}.netapp`);
   try {
-    // The index entry carries the published sha256. Look it up here rather than
-    // thread it through five call sites, so a short download is caught as a bad
-    // transfer instead of surfacing later as "zlib: unexpected end of file".
-    // Absence is tolerated: an entry predating cksum still downloads.
     const entries = await client.getIndex(moduleId).catch(() => []);
     const cksum = entries.find((entry) => entry.vers === version)?.cksum;
     const pkgData = await client.download(moduleId, version, cksum);
     await Bun.write(tmpPath, pkgData);
+    return { ok: true, tmpPath };
   } catch (err) {
     return {
-      status: 'failed',
-      moduleId,
+      ok: false,
       error: `Download failed: ${err instanceof Error ? err.message : String(err)}`,
     };
   }
+}
+
+/**
+ * Read the manifest of a registry version WITHOUT installing it: download,
+ * extract to a temp dir, parse manifest.yml, clean up. Used by the upgrade
+ * path to gate on the target's capability requirements before any state
+ * changes (celilo#1361). Failure to fetch or parse is not itself fatal — the
+ * caller proceeds to `fetchAndUpdate`, which reports the same failure through
+ * its own channel.
+ */
+export async function fetchTargetManifest(
+  client: RegistryClient,
+  moduleId: string,
+  version: string,
+): Promise<{ ok: true; manifest: ModuleManifest } | { ok: false }> {
+  const downloaded = await downloadRegistryPackage(client, moduleId, version);
+  if (!downloaded.ok) return { ok: false };
+  try {
+    const extractResult = await extractPackage(downloaded.tmpPath);
+    if (!extractResult.success || !extractResult.tempDir) return { ok: false };
+    try {
+      const manifestPath = join(extractResult.tempDir, 'manifest.yml');
+      if (!existsSync(manifestPath)) return { ok: false };
+      const parsed = parseYaml(readFileSync(manifestPath, 'utf-8'));
+      return { ok: true, manifest: ModuleManifestSchema.parse(parsed) };
+    } finally {
+      await cleanupTempDir(extractResult.tempDir);
+    }
+  } catch {
+    return { ok: false };
+  } finally {
+    try {
+      await unlink(downloaded.tmpPath);
+    } catch {}
+  }
+}
+
+/**
+ * Download a module package from the registry into a temp file and run
+ * the standard updateOne path against it. Cleans the temp file in a
+ * finally block so a mid-flight failure doesn't leak a tar.zst on disk.
+ */
+export async function fetchAndUpdate(
+  client: RegistryClient,
+  moduleId: string,
+  version: string,
+  db: ReturnType<typeof getDb>,
+  flags: Record<string, string | boolean>,
+): Promise<UpdateOutcome> {
+  // The download (index lookup, cksum verification, temp write) is shared
+  // with `fetchTargetManifest`, which reads the same package before this
+  // update path ever runs.
+  const downloaded = await downloadRegistryPackage(client, moduleId, version);
+  if (!downloaded.ok) {
+    return { status: 'failed', moduleId, error: downloaded.error };
+  }
   try {
     // Registry packages are pre-verified at publish time; skip the
     // signature check here to match `module import`'s registry path.
@@ -153,14 +205,14 @@ export async function fetchAndUpdate(
     // log line — without it, output would say "v1.0.0 → v1.0.0" because
     // the manifest semver doesn't include the +N revision.
     return await updateOne(
-      tmpPath,
+      downloaded.tmpPath,
       db,
       { ...flags, 'skip-verify': true },
       { quiet: true, displayVersion: version },
     );
   } finally {
     try {
-      await unlink(tmpPath);
+      await unlink(downloaded.tmpPath);
     } catch {}
   }
 }
@@ -560,7 +612,7 @@ export async function handleModuleUpdate(
   );
 
   // Skips that fall under a wildcard expansion (e.g. modules/* picking
-  // up `modules/archive/`) shouldn't even be mentioned — they're not
+  // up `modules/__archive__/`) shouldn't even be mentioned — they're not
   // signal. Skips for "module not installed" ARE signal because the
   // user explicitly named the path; surface those.
   const meaningfulSkips = skipped.filter((r) => !r.reason.startsWith('not a module directory'));

package/src/cli/commands/module-upgrade-gate.test.ts

@@ -0,0 +1,154 @@
+/**
+ * The registry-poll capability gate (celilo#1361): `module upgrade` reads the
+ * TARGET version's manifest BEFORE updating anything, and defers — without
+ * changing any state — when the deployed capability providers cannot serve
+ * its requirements.
+ *
+ * celilo-website burned six release revisions (+1 through +6) on exactly
+ * this: every poll attempt updated the stored version, failed in caddy's
+ * publish hook ("sourceDir is required" against a provider built before
+ * b67c9423), recorded the new version beside the old VERIFIED state, and
+ * re-triggered on the next tick. The gate makes that sequence impossible.
+ *
+ * The RegistryClient is spied (the established pattern in
+ * `module-import-registry.test.ts`); the download returns a REAL tar package
+ * carrying only a manifest, which is all `fetchTargetManifest` reads.
+ */
+
+import { afterEach, beforeEach, describe, expect, spyOn, test } from 'bun:test';
+import type { Mock } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { create as tarCreate } from 'tar';
+import { getDb } from '../../db/client';
+import { capabilities, modules } from '../../db/schema';
+import type { IndexEntry } from '../../registry/client';
+import { RegistryClient } from '../../registry/client';
+import { resetTestDbPath } from '../../test-utils/db-path';
+import { handleModuleUpgrade } from './module-upgrade';
+
+function entry(vers: string): IndexEntry {
+  return { name: 'celilo-website', vers, deps: [], cksum: 'abc', yanked: false };
+}
+
+/** A minimal registry package: a tar whose root is manifest.yml. */
+async function packageWithManifest(manifestYaml: string): Promise<ArrayBuffer> {
+  const dir = mkdtempSync(join(tmpdir(), 'celilo-upgrade-pkg-'));
+  await writeFile(join(dir, 'manifest.yml'), manifestYaml);
+  const tarPath = join(dir, 'pkg.netapp');
+  await tarCreate({ file: tarPath, cwd: dir, portable: true }, ['manifest.yml']);
+  const bytes = await Bun.file(tarPath).arrayBuffer();
+  rmSync(dir, { recursive: true, force: true });
+  return bytes;
+}
+
+const MANIFEST = (publicWebVersion: string) => `
+celilo_contract: "1.0"
+id: celilo-website
+name: Celilo Website
+version: 2.0.0
+requires:
+  capabilities:
+    - name: public_web
+      version: ${publicWebVersion}
+`;
+
+let tempDir: string;
+let getIndexSpy: Mock<(name: string) => Promise<IndexEntry[]>>;
+let downloadSpy: Mock<(name: string, vers: string) => Promise<ArrayBuffer>>;
+
+beforeEach(() => {
+  tempDir = mkdtempSync(join(tmpdir(), 'celilo-upgrade-test-'));
+  process.env.CELILO_DB_PATH = join(tempDir, 'test.db');
+  process.env.CELILO_DATA_DIR = tempDir;
+  getIndexSpy = spyOn(RegistryClient.prototype, 'getIndex').mockResolvedValue([entry('2.0.0')]);
+  downloadSpy = spyOn(RegistryClient.prototype, 'download').mockResolvedValue(new ArrayBuffer(0));
+});
+
+afterEach(() => {
+  getIndexSpy.mockRestore();
+  downloadSpy.mockRestore();
+  rmSync(tempDir, { recursive: true, force: true });
+  resetTestDbPath();
+  delete process.env.CELILO_DATA_DIR;
+});
+
+function seedFleet(caddyPublicWebVersion: string): void {
+  const db = getDb();
+  // sourcePath must be a real writable dir: when the gate does NOT fire, the
+  // flow proceeds into updateOne, which stages the new copy beside it.
+  const installDir = (id: string): string => {
+    const p = join(tempDir, 'modules', id);
+    mkdirSync(p, { recursive: true });
+    return p;
+  };
+  db.insert(modules)
+    .values({
+      id: 'celilo-website',
+      name: 'Celilo Website',
+      version: '1.0.5',
+      manifestData: { id: 'celilo-website', name: 'Celilo Website', version: '1.0.5' },
+      sourcePath: installDir('celilo-website'),
+    })
+    .run();
+  db.insert(modules)
+    .values({
+      id: 'caddy',
+      name: 'Caddy',
+      version: '2.3.3+1',
+      manifestData: { id: 'caddy', name: 'Caddy', version: '2.3.3' },
+      sourcePath: installDir('caddy'),
+    })
+    .run();
+  db.insert(capabilities)
+    .values({
+      moduleId: 'caddy',
+      capabilityName: 'public_web',
+      version: caddyPublicWebVersion,
+      data: {},
+    })
+    .run();
+}
+
+describe('handleModuleUpgrade — the capability gate (celilo#1361)', () => {
+  test('defers an upgrade whose requirement no deployed provider serves', async () => {
+    seedFleet('3.1.0');
+    downloadSpy.mockImplementation(async () => packageWithManifest(MANIFEST('4.0.0')));
+
+    const result = await handleModuleUpgrade(['celilo-website'], {});
+
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.deferred).toBe(true);
+      expect(result.error).toContain('deferred');
+      expect(result.error).toContain('public_web@4.0.0');
+      expect(result.error).toContain('caddy');
+    }
+    // The point of deferring: NO state changed. The stored version still
+    // reads the installed release and will re-read as up-to-date-candidate
+    // next tick instead of looking upgraded-but-broken (celilo#1363's shape).
+    const row = getDb()
+      .select()
+      .from(modules)
+      .all()
+      .find((m) => m.id === 'celilo-website');
+    expect(row?.version).toBe('1.0.5');
+  });
+
+  test('does not defer when the deployed provider serves the requirement', async () => {
+    seedFleet('3.1.0');
+    downloadSpy.mockImplementation(async () => packageWithManifest(MANIFEST('3.0.0')));
+
+    const result = await handleModuleUpgrade(['celilo-website'], {});
+
+    // Whatever happens downstream (the minimal package has no scripts), the
+    // gate itself must not have fired — `deferred` marks a capability wall.
+    if (!result.success) {
+      expect(result.deferred).toBeUndefined();
+    } else {
+      expect(result.success).toBe(true);
+    }
+  });
+});

package/src/cli/commands/module-upgrade.ts

@@ -22,6 +22,7 @@ import type { ModuleManifest } from '../../manifest/schema';
 import { RegistryClient } from '../../registry/client';
 import { createModuleBackup, createSystemStateBackup } from '../../services/backup-create';
 import { getDefaultBackupStorage } from '../../services/backup-storage';
+import { capabilityBlockersForManifest } from '../../services/capability-compat';
 import {
   type DeployPosture,
   type UpgradePolicy,
@@ -33,6 +34,7 @@ import { deployModule } from '../../services/module-deploy';
 import { getArg, getFlag } from '../parser';
 import { log } from '../prompts';
 import type { CommandResult } from '../types';
+import { fetchTargetManifest } from './module-update';
 import { classifyVersionChange, fetchAndUpdate } from './module-update';
 
 const VALID_POLICIES: readonly UpgradePolicy[] = ['by-semver', 'always-safe', 'always-fast'];
@@ -181,6 +183,28 @@ export async function upgradeOneModule(
 ): Promise<CommandResult> {
   const moduleId = mod.id;
 
+  // GATE (celilo#1361): read the TARGET manifest BEFORE anything mutates, and
+  // refuse an upgrade whose capability requirements no deployed provider
+  // serves. Deploying first and failing in the module's publish hook is how
+  // celilo-website burned six release revisions (+1 through +6): each failure
+  // recorded the new version, re-triggered the poll, and changed nothing.
+  // A deferral changes no state and retries once the provider lands.
+  const targetManifestCheck = await fetchTargetManifest(client, moduleId, targetVersion);
+  if (targetManifestCheck.ok) {
+    const blockers = capabilityBlockersForManifest(db, targetManifestCheck.manifest);
+    if (blockers.length > 0) {
+      const why = blockers.map((b) => b.message).join('; ');
+      return {
+        success: false,
+        deferred: true,
+        error: `${moduleId} upgrade to ${targetVersion} deferred: the deployed providers cannot serve its capability requirements: ${why}. Upgrade the provider module first; the registry poll retries automatically.`,
+        details: blockers,
+      };
+    }
+  }
+  // A failed fetch here is NOT deferred — `fetchAndUpdate` below reports the
+  // same failure through its own channel with the real error text.
+
   // Update FIRST (refresh stored def). Every downstream decision — the
   // backup gate and the posture policy — must consult the TARGET version's
   // manifest, not the installed one. Gating on the pre-update manifest skipped
@@ -320,6 +344,7 @@ async function runRegistryPoll(
 
   log.info(`Registry poll: ${targets.length} module(s) to upgrade.`);
   const upgraded: string[] = [];
+  const deferred: string[] = [];
   const failed: string[] = [];
   // Serial, in installed order. (Strict provider-before-consumer ordering via
   // topologicalOrder is a refinement; the poll is idempotent + re-runs.)
@@ -327,14 +352,29 @@ async function runRegistryPoll(
     const mod = rowById.get(t.moduleId);
     if (!mod) continue;
     const result = await upgradeOneModule(mod, t.to, client, db, flags);
-    if (result.success) upgraded.push(`${t.moduleId}→${t.to}`);
-    else failed.push(`${t.moduleId}: ${result.error}`);
+    if (result.success) {
+      upgraded.push(`${t.moduleId}→${t.to}`);
+    } else if (result.deferred) {
+      // Expected steady state while a provider upgrade is still pending: the
+      // consumer retries next tick. Not a failure — celilo#1361.
+      deferred.push(`${t.moduleId}: ${result.error}`);
+    } else {
+      failed.push(`${t.moduleId}: ${result.error}`);
+    }
   }
 
   if (failed.length > 0) {
     return {
       success: false,
-      error: `Registry poll: upgraded ${upgraded.length}, FAILED ${failed.length}:\n  ${failed.join('\n  ')}`,
+      error:
+        `Registry poll: upgraded ${upgraded.length}, deferred ${deferred.length}, FAILED ${failed.length}:\n` +
+        `  ${[...failed, ...(deferred.length > 0 ? [`(deferred) ${deferred.join('\n  (deferred) ')}`] : [])].join('\n  ')}`,
+    };
+  }
+  if (deferred.length > 0) {
+    return {
+      success: true,
+      message: `Registry poll: upgraded ${upgraded.length}, deferred ${deferred.length} (capability requirements not yet served — retries next poll):\n  ${deferred.join('\n  ')}`,
     };
   }
   return {

package/src/cli/commands/publish/helpers.ts

@@ -91,8 +91,9 @@ export function buildWorkspaceVersionMap(): WorkspaceVersionMap {
 }
 
 /**
- * List every publishable module under modules/. Excludes `archive/`
- * (operator-confirmed: not publishable) and any dir lacking a
+ * List every publishable module under modules/. Excludes `__archive__/`
+ * (operator-confirmed: not publishable, and renamed with the dunder prefix so
+ * nothing mistakes it for a module) and any dir lacking a
  * manifest.yml.
  */
 export function listModuleDirs(): string[] {
@@ -100,7 +101,7 @@ export function listModuleDirs(): string[] {
   if (!existsSync(modulesRoot)) return [];
   const out: string[] = [];
   for (const name of readdirSync(modulesRoot)) {
-    if (name === 'archive') continue;
+    if (name === '__archive__') continue;
     const dir = join(modulesRoot, name);
     let st: ReturnType<typeof statSync>;
     try {

package/src/cli/commands/publish/index.ts

@@ -120,6 +120,12 @@ export function parseOptions(argv: string[]): ParsedFlags {
   const trackAlphaFlag = argv.includes('--track-alpha');
   const alphaModulesFlag = argv.includes('--alpha-modules');
   const skipChangesets = argv.includes('--skip-changesets');
+  const skipModulesFlag = argv.includes('--skip-modules');
+  const modulesOnlyFlag = argv.includes('--modules-only');
+  if (skipModulesFlag && modulesOnlyFlag) {
+    console.error('✗ --skip-modules and --modules-only are mutually exclusive.');
+    process.exit(1);
+  }
   const promoteArg = takeFlagValue('--promote');
   const skippedModules: string[] = [];
   for (let i = argv.indexOf('--skip-module'); i >= 0; i = argv.indexOf('--skip-module', i + 1)) {
@@ -162,7 +168,13 @@ export function parseOptions(argv: string[]): ParsedFlags {
   }
 
   return {
-    options: { allowStale, autoYes: yes, mode, skippedModules },
+    options: {
+      allowStale,
+      autoYes: yes,
+      mode,
+      skippedModules,
+      modulePhase: modulesOnlyFlag ? 'only' : skipModulesFlag ? 'skip' : 'run',
+    },
     dryRun,
     releaseTouch,
     skipChangesets,