fix: simplify updater to @mosaic/mosaic only, add explicit tea repo/login flags (#387)

BREAKING CHANGE: Remove legacy @mosaic/cli fallback from update-checker.
The updater now targets only @mosaic/mosaic — legacy package compatibility
is out of scope per approved breaking change.

- update-checker.ts: remove LEGACY_PKG, INSTALLED_PACKAGE_ORDER, candidate
  iteration, and cache key comparison. Single query for @mosaic/mosaic only.
- update-checker.test.ts: remove legacy fallback and cross-contamination
  tests. Add test asserting no @mosaic/cli queries are made.
- pr-merge.sh: add --repo and --login flags to tea merge command; resolve
  OWNER/REPO before case block.
- issue-close.sh: add --repo and --login flags to tea issue commands;
  resolve OWNER/REPO after detect_platform.
- pr-ci-wait.sh: no changes needed (uses curl, not tea).
- detect-platform.sh: no changes needed (provides get_repo_owner/name).

Ref: #387

apps/gateway/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaic/gateway",
-  "version": "0.1.0",
+  "version": "0.0.5",
   "repository": {
     "type": "git",
     "url": "https://git.mosaicstack.dev/mosaic/mosaic-stack.git",

docs/scratchpads/387-updater-wrapper-gitea-20260404.md

@@ -0,0 +1,54 @@
+# Scratchpad — issue #387 updater simplification + Gitea wrapper repo context
+
+- Objective: simplify updater behavior to `@mosaic/mosaic` only, and fix Gitea wrapper scripts so merge/CI/issue operations work reliably when tea needs explicit repo/login context.
+- Scope:
+  - `packages/mosaic/src/runtime/update-checker.ts`
+  - `packages/mosaic/__tests__/update-checker.test.ts`
+  - any package metadata/version bumps needed
+  - repo-source git wrappers under `packages/mosaic/framework/tools/git/`
+- Constraints:
+  - Jason approved breaking changes; legacy `@mosaic/cli` support is out of scope.
+  - Keep changes focused and mergeable.
+- Acceptance:
+  - updater only targets `@mosaic/mosaic`
+  - wrapper path works on Gitea in this environment without manual repo guessing
+  - PR merges squash-only after green CI
+
+## Progress
+
+### 2026-04-04
+
+#### Update Checker Simplification (DONE)
+
+- Removed `LEGACY_PKG`, `INSTALLED_PACKAGE_ORDER` constants — only `PKG = '@mosaic/mosaic'` remains
+- `getInstalledVersion()` — removed loop over multiple packages, only checks `@mosaic/mosaic`
+- `getLatestVersion()` — removed `installedPackage` parameter and candidate iteration; single query for `@mosaic/mosaic`
+- `checkForUpdate()` — removed `currentPackage`-based cache key comparison; cache is now package-agnostic
+- `RegistryCache` — removed `currentPackage` and `targetPackage` fields
+- `formatUpdateNotice()` — removed `targetChanged` branch (package migration notice no longer relevant)
+- All legacy fallback/compatibility logic removed
+
+#### Test Updates (DONE)
+
+- Removed legacy `@mosaic/cli` fallback test
+- Removed cache cross-contamination test (was testing legacy→modern package transition)
+- Added `does not query legacy @mosaic/cli package` test — asserts no `@mosaic/cli` npm commands are issued
+- Added `returns empty result when package is not installed` test
+- All 8 tests pass ✅
+
+#### Gitea Wrapper Fixes (DONE)
+
+- `pr-merge.sh`:
+  - Added `OWNER=$(get_repo_owner)` / `REPO=$(get_repo_name)` before case block
+  - tea merge command now includes `--repo $OWNER/$REPO --login ${GITEA_LOGIN:-mosaicstack}`
+- `issue-close.sh`:
+  - Added `OWNER=$(get_repo_owner)` / `REPO=$(get_repo_name)` after detect_platform
+  - Both `tea issue comment` and `tea issue close` now include `--repo "$OWNER/$REPO" --login "${GITEA_LOGIN:-mosaicstack}"`
+- `pr-ci-wait.sh`: No changes needed — uses curl API calls (not tea), already passes owner/repo correctly
+- `detect-platform.sh`: No changes needed — provides the `get_repo_owner`/`get_repo_name` functions used by wrappers
+
+#### Verification
+
+- `vitest run` — 8/8 tests pass
+- `tsc --noEmit` — no errors in update-checker.ts (pre-existing workspace dep errors unrelated)
+- `eslint` — clean, no warnings

docs/scratchpads/update-checker-package-20260404.md

@@ -0,0 +1,34 @@
+# Scratchpad — updater package target fix (#382)
+
+- Objective: Fix `mosaic update` so modern installs query `@mosaic/mosaic` instead of stale `@mosaic/cli`.
+- Scope: updater logic, user-facing update/install hints, tests, package version bump(s).
+- Constraints: preserve backward compatibility for older `@mosaic/cli` installs if practical.
+- Acceptance:
+  - fresh installs using `@mosaic/mosaic` report latest correctly
+  - older installs do not regress unnecessarily
+  - tests cover package lookup behavior
+  - release version bumped for changed package(s)
+
+## Decisions
+
+- Prefer `@mosaic/mosaic` when both modern and legacy packages are installed globally.
+- For legacy `@mosaic/cli` installs, query `@mosaic/cli` first, then fall back to `@mosaic/mosaic` if the legacy package is not published.
+- Share install-target selection from `packages/mosaic` so both the consolidated CLI and the legacy `packages/cli` entrypoint print/install the same package target.
+- Extend the update cache to persist the resolved target package as well as the version so cached checks preserve the migration target.
+
+## Validation
+
+- `pnpm install`
+- `pnpm --filter @mosaic/mosaic test -- __tests__/update-checker.test.ts`
+- `pnpm exec eslint --no-warn-ignored packages/mosaic/src/runtime/update-checker.ts packages/mosaic/src/cli.ts packages/mosaic/src/index.ts packages/mosaic/__tests__/update-checker.test.ts packages/cli/src/cli.ts`
+- `pnpm --filter @mosaic/mosaic lint`
+- pre-push hooks: `typecheck`, `lint`, `format:check`
+
+## Review
+
+- Manual review of the updater diff caught and fixed a cache regression where fallback results would lose the resolved package target on subsequent cached checks.
+
+## Risks / Notes
+
+- Direct `pnpm --filter @mosaic/mosaic typecheck` and `pnpm --filter @mosaic/cli ...` checks were not representative in this worktree because `packages/cli` is excluded from `pnpm-workspace.yaml` and the standalone package check lacked the built workspace dependency graph.
+- The repo's pre-push hooks provided the authoritative validation path here and passed: root `typecheck`, `lint`, and `format:check`.

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaic/cli",
-  "version": "0.0.16",
+  "version": "0.0.17",
   "repository": {
     "type": "git",
     "url": "https://git.mosaicstack.dev/mosaic/mosaic-stack.git",

packages/cli/src/cli.ts

@@ -314,7 +314,8 @@ program
   .description('Check for and install Mosaic CLI updates')
   .option('--check', 'Check only, do not install')
   .action(async (opts: { check?: boolean }) => {
-    const { checkForUpdate, formatUpdateNotice } = await import('@mosaic/mosaic');
+    const { checkForUpdate, formatUpdateNotice, getInstallCommand } =
+      await import('@mosaic/mosaic');
     const { execSync } = await import('node:child_process');
 
     console.log('Checking for updates…');
@@ -344,7 +345,7 @@ program
     try {
       // Relies on @mosaic:registry in ~/.npmrc — do NOT pass --registry
       // globally or non-@mosaic deps will 404 against the Gitea registry.
-      execSync('npm install -g @mosaic/cli@latest', {
+      execSync(getInstallCommand(result), {
         stdio: 'inherit',
         timeout: 60_000,
       });

packages/config/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaic/config",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "repository": {
     "type": "git",
     "url": "https://git.mosaicstack.dev/mosaic/mosaic-stack.git",

packages/mosaic/__tests__/update-checker.test.ts

@@ -1,7 +1,40 @@
-import { describe, expect, it } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { semverLt, formatUpdateNotice } from '../src/runtime/update-checker.js';
 import type { UpdateCheckResult } from '../src/runtime/update-checker.js';
 
+const { execSyncMock, cacheFiles } = vi.hoisted(() => ({
+  execSyncMock: vi.fn(),
+  cacheFiles: new Map<string, string>(),
+}));
+
+vi.mock('node:child_process', () => ({
+  execSync: execSyncMock,
+}));
+
+vi.mock('node:fs', () => ({
+  existsSync: vi.fn((path: string) => cacheFiles.has(path)),
+  mkdirSync: vi.fn(),
+  readFileSync: vi.fn((path: string) => {
+    const value = cacheFiles.get(path);
+    if (value === undefined) {
+      throw new Error(`ENOENT: ${path}`);
+    }
+    return value;
+  }),
+  writeFileSync: vi.fn((path: string, content: string) => {
+    cacheFiles.set(path, content);
+  }),
+}));
+
+vi.mock('node:os', () => ({
+  homedir: vi.fn(() => '/mock-home'),
+}));
+
+async function importUpdateChecker() {
+  vi.resetModules();
+  return import('../src/runtime/update-checker.js');
+}
+
 describe('semverLt', () => {
   it('returns true when a < b', () => {
     expect(semverLt('0.0.1', '0.0.2')).toBe(true);
@@ -25,6 +58,11 @@ describe('semverLt', () => {
 });
 
 describe('formatUpdateNotice', () => {
+  beforeEach(() => {
+    execSyncMock.mockReset();
+    cacheFiles.clear();
+  });
+
   it('returns empty string when up to date', () => {
     const result: UpdateCheckResult = {
       current: '1.0.0',
@@ -49,4 +87,83 @@ describe('formatUpdateNotice', () => {
     expect(notice).toContain('0.1.0');
     expect(notice).toContain('Update available');
   });
+
+  it('uses @mosaic/mosaic for installs', async () => {
+    execSyncMock.mockImplementation((command: string) => {
+      if (command.includes('ls -g --depth=0 --json')) {
+        return JSON.stringify({
+          dependencies: {
+            '@mosaic/mosaic': { version: '0.0.19' },
+          },
+        });
+      }
+
+      if (command.includes('view @mosaic/mosaic version')) {
+        return '0.0.20';
+      }
+
+      throw new Error(`Unexpected command: ${command}`);
+    });
+
+    const { checkForUpdate } = await importUpdateChecker();
+    const result = checkForUpdate({ skipCache: true });
+    const notice = formatUpdateNotice(result);
+
+    expect(result.current).toBe('0.0.19');
+    expect(result.latest).toBe('0.0.20');
+    expect(result.currentPackage).toBe('@mosaic/mosaic');
+    expect(result.targetPackage).toBe('@mosaic/mosaic');
+    expect(notice).toContain('@mosaic/mosaic@latest');
+  });
+
+  it('does not query legacy @mosaic/cli package', async () => {
+    execSyncMock.mockImplementation((command: string) => {
+      if (command.includes('view @mosaic/cli')) {
+        throw new Error('Should not query @mosaic/cli');
+      }
+
+      if (command.includes('ls -g --depth=0 --json')) {
+        return JSON.stringify({
+          dependencies: {
+            '@mosaic/mosaic': { version: '0.0.19' },
+          },
+        });
+      }
+
+      if (command.includes('view @mosaic/mosaic version')) {
+        return '0.0.20';
+      }
+
+      throw new Error(`Unexpected command: ${command}`);
+    });
+
+    const { checkForUpdate } = await importUpdateChecker();
+    const result = checkForUpdate({ skipCache: true });
+
+    expect(result.targetPackage).toBe('@mosaic/mosaic');
+    expect(result.latest).toBe('0.0.20');
+    // Verify no @mosaic/cli queries were made
+    const calls = execSyncMock.mock.calls.map((c: any[]) => c[0] as string);
+    expect(calls.some((c) => c.includes('@mosaic/cli'))).toBe(false);
+  });
+
+  it('returns empty result when package is not installed', async () => {
+    execSyncMock.mockImplementation((command: string) => {
+      if (command.includes('ls -g --depth=0 --json')) {
+        return JSON.stringify({ dependencies: {} });
+      }
+
+      if (command.includes('view @mosaic/mosaic version')) {
+        return '';
+      }
+
+      throw new Error(`Unexpected command: ${command}`);
+    });
+
+    const { checkForUpdate } = await importUpdateChecker();
+    const result = checkForUpdate({ skipCache: true });
+
+    expect(result.current).toBe('');
+    expect(result.updateAvailable).toBe(false);
+  });
 });

packages/mosaic/framework/tools/git/issue-close.sh

@@ -45,6 +45,8 @@ fi
 
 # Detect platform and close issue
 detect_platform
+OWNER=$(get_repo_owner)
+REPO=$(get_repo_name)
 
 if [[ "$PLATFORM" == "github" ]]; then
     if [[ -n "$COMMENT" ]]; then
@@ -54,9 +56,9 @@ if [[ "$PLATFORM" == "github" ]]; then
     echo "Closed GitHub issue #$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     if [[ -n "$COMMENT" ]]; then
-        tea issue comment "$ISSUE_NUMBER" "$COMMENT"
+        tea issue comment "$ISSUE_NUMBER" "$COMMENT" --repo "$OWNER/$REPO" --login "${GITEA_LOGIN:-mosaicstack}"
     fi
-    tea issue close "$ISSUE_NUMBER"
+    tea issue close "$ISSUE_NUMBER" --repo "$OWNER/$REPO" --login "${GITEA_LOGIN:-mosaicstack}"
     echo "Closed Gitea issue #$ISSUE_NUMBER"
 else
     echo "Error: Unknown platform"

packages/mosaic/framework/tools/git/pr-merge.sh

@@ -89,6 +89,8 @@ if [[ "$SKIP_QUEUE_GUARD" != true ]]; then
 fi
 
 PLATFORM=$(detect_platform)
+OWNER=$(get_repo_owner)
+REPO=$(get_repo_name)
 
 case "$PLATFORM" in
     github)
@@ -97,8 +99,7 @@ case "$PLATFORM" in
         eval "$CMD"
         ;;
     gitea)
-        # tea pr merge syntax
-        CMD="tea pr merge $PR_NUMBER --style squash"
+        CMD="tea pr merge $PR_NUMBER --style squash --repo $OWNER/$REPO --login ${GITEA_LOGIN:-mosaicstack}"
 
         # Delete branch after merge if requested
         if [[ "$DELETE_BRANCH" == true ]]; then

packages/mosaic/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaic/mosaic",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "repository": {
     "type": "git",
     "url": "https://git.mosaicstack.dev/mosaic/mosaic-stack.git",

packages/mosaic/src/cli.ts

@@ -12,6 +12,7 @@ import {
   backgroundUpdateCheck,
   checkForUpdate,
   formatUpdateNotice,
+  getInstallCommand,
 } from './runtime/update-checker.js';
 import { runWizard } from './wizard.js';
 import { ClackPrompter } from './prompter/clack-prompter.js';
@@ -354,7 +355,7 @@ program
     try {
       // Relies on @mosaic:registry in ~/.npmrc — do NOT pass --registry
       // globally or non-@mosaic deps will 404 against the Gitea registry.
-      execSync('npm install -g @mosaic/cli@latest', {
+      execSync(getInstallCommand(result), {
         stdio: 'inherit',
         timeout: 60_000,
       });

packages/mosaic/src/index.ts

@@ -1 +1,11 @@
 export const VERSION = '0.0.0';
+
+export {
+  backgroundUpdateCheck,
+  checkForUpdate,
+  formatUpdateNotice,
+  getInstallCommand,
+  getInstalledVersion,
+  getLatestVersion,
+  semverLt,
+} from './runtime/update-checker.js';

packages/mosaic/src/runtime/update-checker.ts

@@ -1,6 +1,6 @@
 /**
- * Mosaic update checker — compares installed @mosaic/cli version against the
- * Gitea npm registry and reports when an upgrade is available.
+ * Mosaic update checker — compares the installed @mosaic/mosaic package
+ * against the Gitea npm registry and reports when an upgrade is available.
  *
  * Used by:
  *  - CLI startup (non-blocking background check)
@@ -23,8 +23,12 @@ import { join } from 'node:path';
 export interface UpdateCheckResult {
   /** Currently installed version (empty if not found) */
   current: string;
+  /** Currently installed package name */
+  currentPackage?: string;
   /** Latest published version (empty if check failed) */
   latest: string;
+  /** Package that should be installed for the latest version */
+  targetPackage?: string;
   /** True when a newer version is available */
   updateAvailable: boolean;
   /** ISO timestamp of this check */
@@ -36,7 +40,7 @@ export interface UpdateCheckResult {
 // ─── Constants ──────────────────────────────────────────────────────────────
 
 const REGISTRY = 'https://git.mosaicstack.dev/api/packages/mosaic/npm/';
-const CLI_PKG = '@mosaic/cli';
+const PKG = '@mosaic/mosaic';
 const CACHE_DIR = join(homedir(), '.cache', 'mosaic');
 const CACHE_FILE = join(CACHE_DIR, 'update-check.json');
 const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
@@ -154,31 +158,40 @@ function writeCache(entry: RegistryCache): void {
 // ─── Public API ─────────────────────────────────────────────────────────────
 
 /**
- * Get the currently installed version of @mosaic/cli.
- * Returns empty string if not installed.
+ * Get the currently installed @mosaic/mosaic version.
  */
-export function getInstalledVersion(): string {
-  // Fast path: check via package.json require chain
+export function getInstalledVersion(): { name: string; version: string } {
   try {
     const raw = npmExec(`ls -g --depth=0 --json 2>/dev/null`, 3000);
     if (raw) {
       const data = JSON.parse(raw) as {
         dependencies?: Record<string, { version?: string }>;
       };
-      return data?.dependencies?.[CLI_PKG]?.version ?? '';
+      const version = data?.dependencies?.[PKG]?.version;
+      if (version) {
+        return { name: PKG, version };
+      }
     }
   } catch {
     // fall through
   }
-  return '';
+  return { name: '', version: '' };
 }
 
 /**
- * Fetch the latest published version from the Gitea npm registry.
+ * Fetch the latest published @mosaic/mosaic version from the Gitea npm registry.
  * Returns empty string on failure.
  */
-export function getLatestVersion(): string {
-  return npmExec(`view ${CLI_PKG} version --registry=${REGISTRY}`);
+export function getLatestVersion(): { name: string; version: string } {
+  const version = npmExec(`view ${PKG} version --registry=${REGISTRY}`);
+  if (version) {
+    return { name: PKG, version };
+  }
+  return { name: '', version: '' };
+}
+
+export function getInstallCommand(result: Pick<UpdateCheckResult, 'targetPackage'>): string {
+  return `npm i -g ${result.targetPackage || PKG}@latest`;
 }
 
 /**
@@ -188,31 +201,45 @@ export function getLatestVersion(): string {
  * Never throws.
  */
 export function checkForUpdate(options?: { skipCache?: boolean }): UpdateCheckResult {
-  const current = getInstalledVersion();
+  const currentInfo = getInstalledVersion();
+  const current = currentInfo.version;
 
-  let latest: string;
+  let latestInfo: { name: string; version: string };
   let checkedAt: string;
 
   if (!options?.skipCache) {
     const cached = readCache();
     if (cached) {
-      latest = cached.latest;
+      latestInfo = {
+        name: PKG,
+        version: cached.latest,
+      };
       checkedAt = cached.checkedAt;
     } else {
-      latest = getLatestVersion();
+      latestInfo = getLatestVersion();
       checkedAt = new Date().toISOString();
-      writeCache({ latest, checkedAt, registry: REGISTRY });
+      writeCache({
+        latest: latestInfo.version,
+        checkedAt,
+        registry: REGISTRY,
+      });
     }
   } else {
-    latest = getLatestVersion();
+    latestInfo = getLatestVersion();
     checkedAt = new Date().toISOString();
-    writeCache({ latest, checkedAt, registry: REGISTRY });
+    writeCache({
+      latest: latestInfo.version,
+      checkedAt,
+      registry: REGISTRY,
+    });
   }
 
   return {
     current,
-    latest,
-    updateAvailable: !!(current && latest && semverLt(current, latest)),
+    currentPackage: currentInfo.name || PKG,
+    latest: latestInfo.version,
+    targetPackage: latestInfo.name || PKG,
+    updateAvailable: !!(current && latestInfo.version && semverLt(current, latestInfo.version)),
     checkedAt,
     registry: REGISTRY,
   };
@@ -224,6 +251,8 @@ export function checkForUpdate(options?: { skipCache?: boolean }): UpdateCheckRe
 export function formatUpdateNotice(result: UpdateCheckResult): string {
   if (!result.updateAvailable) return '';
 
+  const installCommand = getInstallCommand(result);
+
   const lines = [
     '',
     '╭─────────────────────────────────────────────────╮',
@@ -231,7 +260,7 @@ export function formatUpdateNotice(result: UpdateCheckResult): string {
     `│   Update available: ${result.current} → ${result.latest}`.padEnd(50) + '│',
     '│                                                 │',
     '│   Run:  bash tools/install.sh                   │',
-    '│   Or:   npm i -g @mosaic/cli@latest             │',
+    `│   Or:   ${installCommand}`.padEnd(50) + '│',
     '│                                                 │',
     '╰─────────────────────────────────────────────────╯',
     '',