@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/server/lib/updates/changelog.ts

@@ -0,0 +1,163 @@
+/**
+ * The "What's new" range: every Kabmo release between the version installed
+ * on disk and the newest one npm serves, newest first, ready to render.
+ *
+ * The range is the whole point of the popup. A user three releases behind must
+ * see three sections, not just the newest one — and the sections come from the
+ * repository's `CHANGELOG.md` (see ./changelog-file), which is the same prose the
+ * GitHub release bodies carry. Nothing here re-parses the changelog for the
+ * current/latest pair or trusts a client-supplied `from`/`to`: the installed
+ * version is read from disk and the newest one from npm, so a caller cannot ask
+ * for a range the install does not actually have.
+ *
+ * Two caps bound the response, because `omp`-style repositories can publish
+ * dozens of releases and one of them (measured on a sibling project) carries a
+ * 43 KB body. The NEWEST releases are always kept; the trim takes the oldest,
+ * which is what "showing 12 of 29" means.
+ */
+
+import { isMockMode } from '@/server/mock.server';
+import { fetchChangelogNotes } from '@/server/lib/updates/changelog-file';
+import { isManualMethod, manualUpdateCommand } from '@/server/lib/updates/install-method';
+import { resolveInstallContext, resolveKabmoVersion } from '@/server/lib/updates/install';
+import { releaseTagUrl } from '@/server/lib/updates/release-url';
+import { compareVersions, isNewer, normalizeVersion } from '@/shared/lib/updates/semver';
+import type { ReleaseNote, UpdateChangelog, UpdateInstallInfo } from '@/shared/types/updates';
+
+/** Most release sections the popup will render. */
+export const MAX_VERSIONS = 20;
+/** Byte budget for the joined bodies; the oldest sections go first. */
+export const MAX_NOTES_BYTES = 120_000;
+
+/** Releases above `current` and up to `latest`, newest first. */
+export function selectReleaseRange(releases: ReleaseNote[], current: string | null, latest: string | null): ReleaseNote[] {
+  if (!latest) return [];
+  return releases
+    .filter((release) => {
+      const version = normalizeVersion(release.version);
+      if (!version || isNewer(version, latest)) return false;
+      // With no readable installed version there is nothing to be "above", so
+      // the range is the newest release alone rather than the whole history.
+      return current ? isNewer(version, current) : version === normalizeVersion(latest);
+    })
+    .sort((a, b) => compareVersions(normalizeVersion(b.version), normalizeVersion(a.version)));
+}
+
+/**
+ * Apply both caps, keeping the newest sections. `truncated` is what lets the
+ * popup say "showing 12 of 29" instead of silently dropping the oldest releases.
+ */
+export function capReleaseNotes(notes: ReleaseNote[]): { versions: ReleaseNote[]; truncated: boolean } {
+  const versions = notes.slice(0, MAX_VERSIONS);
+  let truncated = versions.length < notes.length;
+
+  let bytes = versions.reduce((total, note) => total + note.body.length, 0);
+  while (versions.length > 1 && bytes > MAX_NOTES_BYTES) {
+    bytes -= versions[versions.length - 1]!.body.length;
+    versions.pop();
+    truncated = true;
+  }
+
+  return { versions, truncated };
+}
+
+function resolveInstall(latest: string | null, packageName: string | null): UpdateInstallInfo {
+  const context = resolveInstallContext();
+  return {
+    method: context.method,
+    reason: context.reason,
+    manual: isManualMethod(context.method),
+    command: manualUpdateCommand(context.method, latest, packageName ?? undefined),
+  };
+}
+
+/** The demo range: every render shape the popup has, without a network read. */
+function mockChangelog(): UpdateChangelog {
+  const note = (version: string, date: string, body: string): ReleaseNote => ({
+    version,
+    date,
+    url: releaseTagUrl(version),
+    body,
+  });
+
+  return {
+    current: '3.6.0',
+    latest: '3.8.0',
+    versions: [
+      note('3.8.0', '2026-09-29', '### Added\n\n* **wiki:** add a right-panel wiki reader for GitHub and GitLab wikis\n* **wiki:** move the Wiki view beside Source Control in both bars\n\n### Fixed\n\n* **skills:** load newly created skills into live sessions\n'),
+      note('3.7.1', '2026-09-29', '### Fixed\n\n* **about:** point social links at the real project and refresh the row set\n'),
+      note('3.7.0', '2026-09-29', '### Added\n\n* **auth:** add opt-in UI password protection with TLS and session revocation\n* **sidebar:** keep the desktop session and folder actions on screen\n\n### Fixed\n\n* **git:** make the Source Control dot follow the repo the panel is on\n'),
+    ],
+    total: 3,
+    truncated: false,
+    releaseUrl: releaseTagUrl('3.8.0'),
+    // Only the release RANGE is faked. How this copy updates itself is a fact
+    // about the running install, and a mock that invented it would show a
+    // button the real apply path refuses.
+    install: resolveInstall('3.8.0', null),
+    error: null,
+  };
+}
+
+/**
+ * Build the popup's payload. Never throws: every failure is a field, because the
+ * popup is opened from a version check that already succeeded and an exception
+ * here would surface as an empty dialog with no explanation.
+ */
+export async function buildUpdateChangelog(): Promise<UpdateChangelog> {
+  if (isMockMode()) return mockChangelog();
+
+  const { current, latest, error, package: packageName, renamed } = await resolveKabmoVersion();
+  const install = resolveInstall(latest, packageName);
+  const base = {
+    current,
+    latest,
+    versions: [] as ReleaseNote[],
+    total: 0,
+    truncated: false,
+    releaseUrl: latest ? releaseTagUrl(latest) : null,
+    install,
+  };
+
+  if (!latest) return { ...base, error: error ?? 'No Kabmo release could be resolved' };
+  // The version restarts at 0.0.1, so there is no release RANGE to show: every
+  // changelog entry belongs to the old lineage. One synthetic note explains the
+  // switch, and the apply path installs the resolved package.
+  if (renamed) {
+    return {
+      ...base,
+      versions: [
+        {
+          version: latest,
+          date: null,
+          url: releaseTagUrl(latest),
+          body: `This release renames the app package from \`ompchamber\` to \`${packageName}\`. Updating installs \`${packageName}@${latest}\`; your data is moved to \`~/.kabmo\` and kept.`,
+        },
+      ],
+      total: 1,
+      truncated: false,
+      error: null,
+    };
+  }
+  if (!current) return { ...base, error: 'The installed Kabmo version could not be read' };
+  // Nothing to announce. The client only opens the popup when a check reported an
+  // update, so this is the race where the install moved between the two reads.
+  if (!isNewer(latest, current)) return { ...base, error: null };
+
+  const notes = await fetchChangelogNotes();
+  const range = selectReleaseRange(notes, current, latest);
+  // The installed version is not always IN the list — a dev build, a version
+  // published before this page, or a local edit — and an empty range with a
+  // known `latest` would otherwise render nothing. Fall back to the newest
+  // release's own notes, which is what the user is being offered.
+  const selected = range.length > 0 ? range : notes.filter((note) => normalizeVersion(note.version) === normalizeVersion(latest));
+
+  const { versions, truncated } = capReleaseNotes(selected);
+  return {
+    ...base,
+    versions,
+    total: selected.length,
+    truncated,
+    error: versions.length === 0 ? 'Release notes could not be fetched' : null,
+  };
+}

package/src/server/lib/updates/check.ts

@@ -0,0 +1,71 @@
+/**
+ * Orchestrates the "Check for updates" flow: Kabmo and oh-my-pi (`omp`).
+ * Both probes read npm — the registry each install comes from — and run
+ * concurrently, and neither is allowed to reject, so the endpoint always returns
+ * a complete UpdateCheckResult.
+ *
+ * MOCK mode answers a fixed pair that says an update is available. The real
+ * probe reads the version installed on THIS machine, which on a development
+ * checkout is usually the newest published one — so the demo would never show
+ * the update UI it exists to exercise, and the popup's own gate would never open.
+ */
+
+import { isMockMode } from '@/server/mock.server';
+import { resolveKabmoVersion } from '@/server/lib/updates/install';
+import { releaseTagUrl } from '@/server/lib/updates/release-url';
+import { checkOmpUpdate } from '@/server/lib/updates/omp';
+import type { UpdateCheckResult, UpdateTargetInfo } from '@/shared/types/updates';
+
+/** The demo range's endpoints; `buildUpdateChangelog` serves the matching notes. */
+export const MOCK_CURRENT_VERSION = '3.6.0';
+export const MOCK_LATEST_VERSION = '3.8.0';
+
+function mockTargets(): UpdateCheckResult {
+  return {
+    kabmo: {
+      current: MOCK_CURRENT_VERSION,
+      latest: MOCK_LATEST_VERSION,
+      updateAvailable: true,
+      installed: true,
+      error: null,
+      releaseName: `v${MOCK_LATEST_VERSION}`,
+      releaseUrl: releaseTagUrl(MOCK_LATEST_VERSION),
+    },
+    omp: { current: '18.3.0', latest: '18.4.0', updateAvailable: true, installed: true, error: null },
+    checkedAt: new Date().toISOString(),
+  };
+}
+
+async function checkKabmo(): Promise<UpdateTargetInfo> {
+  try {
+    // Reads the version on disk, so a completed update stops showing as
+    // available even before the server is restarted.
+    const info = await resolveKabmoVersion();
+    return {
+      current: info.current,
+      latest: info.latest,
+      updateAvailable: info.updateAvailable,
+      installed: true,
+      error: info.error,
+      releaseName: info.latest ? `v${info.latest}` : null,
+      releaseUrl: info.latest ? releaseTagUrl(info.latest) : null,
+    };
+  } catch (err) {
+    return {
+      current: null,
+      latest: null,
+      updateAvailable: false,
+      installed: true,
+      error: err instanceof Error ? err.message : 'Failed to check Kabmo updates',
+      releaseName: null,
+      releaseUrl: null,
+    };
+  }
+}
+
+export async function checkAllUpdates(): Promise<UpdateCheckResult> {
+  if (isMockMode()) return mockTargets();
+
+  const [kabmo, omp] = await Promise.all([checkKabmo(), checkOmpUpdate()]);
+  return { kabmo, omp, checkedAt: new Date().toISOString() };
+}

package/src/server/lib/updates/install-method.ts

@@ -0,0 +1,86 @@
+/**
+ * How this Kabmo copy was put on disk, and therefore how it can replace
+ * itself. Detection is pure path/flag inspection so the branch table stays
+ * unit-testable: the caller supplies the one fact that needs a subprocess
+ * (whether `pkgRoot` is a git work tree, and where its `origin` points).
+ */
+
+import { KABMO_PACKAGE } from '@/server/lib/updates/npm';
+
+/** Where the running copy came from. */
+export type InstallMethod = 'bun-global' | 'git' | 'npm' | 'unmanaged';
+
+export interface InstallMethodInfo {
+  method: InstallMethod;
+  /** Why this method was chosen — surfaced in CLI/JSON diagnostics. */
+  reason: string;
+}
+
+export interface DetectInstallInput {
+  /** Package root: the directory holding the `package.json` being executed. */
+  pkgRoot: string;
+  /** `git -C <pkgRoot> rev-parse --is-inside-work-tree` returned `true`. */
+  gitWorkTree: boolean;
+  /** `git -C <pkgRoot> remote get-url origin`, or null when there is no origin. */
+  gitRemote?: string | null;
+}
+
+/** Kabmo's own repository — only its checkout can fast-forward to a release tag. */
+export const REPO_URL = 'https://github.com/kabmo-labs/kabmo.git';
+
+/** The pre-rename repository; a checkout of either is recognized as updatable. */
+export const LEGACY_REPO_URL = 'https://github.com/rajebdev/ompchamber.git';
+
+// Bun's global install layout, independent of where BUN_INSTALL points.
+const BUN_GLOBAL = /(^|\/)install\/global\/node_modules\//;
+// Any other package-manager layout: npm/pnpm/yarn global, or a project dependency.
+const NODE_MODULES = /(^|\/)node_modules\//;
+// A remote that IS the repository (https, git@host:owner/name, trailing .git).
+// Both spellings are accepted: a checkout created before the rename keeps the
+// old remote URL (GitHub redirects it), and it must stay fast-forwardable.
+const REPO_REMOTE = /(^|[/:])(ompchamber|kabmo)(\.git)?$/;
+
+export function detectInstallMethod({ pkgRoot, gitWorkTree, gitRemote }: DetectInstallInput): InstallMethodInfo {
+  // Windows separators are normalized so one branch table covers both platforms.
+  const root = String(pkgRoot ?? '').replace(/\\/g, '/');
+
+  if (BUN_GLOBAL.test(root)) {
+    return { method: 'bun-global', reason: 'bun global install' };
+  }
+
+  if (NODE_MODULES.test(root)) {
+    return { method: 'npm', reason: 'package-manager install under node_modules' };
+  }
+
+  if (gitWorkTree && REPO_REMOTE.test(String(gitRemote ?? '').replace(/\\/g, '/'))) {
+    return { method: 'git', reason: 'git checkout of Kabmo repository' };
+  }
+
+  if (gitWorkTree) {
+    return { method: 'unmanaged', reason: `git checkout tracking ${gitRemote ?? 'no origin'}` };
+  }
+
+  return { method: 'unmanaged', reason: 'source copy with no git metadata' };
+}
+
+/**
+ * True when the CLI/server cannot replace the files itself: a package-manager
+ * install is owned by its manager, and an unmanaged copy has no update source.
+ */
+export function isManualMethod(method: InstallMethod): boolean {
+  return method === 'npm' || method === 'unmanaged';
+}
+
+/**
+ * The exact command a user must run when the update cannot be automatic.
+ *
+ * Both branches use `bun add -g`: Kabmo is a Bun package and the repo's own
+ * toolchain contract is Bun-only (see AGENTS.md — npm/npx/yarn/pnpm are never
+ * used here), so a copy under `node_modules` is still replaced with `bun`, not
+ * with the package manager that happened to install it. The method is reported
+ * separately for diagnostics; it does not change the command.
+ */
+export function manualUpdateCommand(method: InstallMethod, version: string | null, packageName = KABMO_PACKAGE): string | null {
+  if (method === 'unmanaged' || method === 'npm') return `bun add -g ${packageName}@${version ?? 'latest'}`;
+  return null;
+}

package/src/server/lib/updates/install.test.ts

@@ -0,0 +1,135 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { planUpdateSteps, resolveKabmoVersion } from '@/server/lib/updates/install';
+import { detectInstallMethod, manualUpdateCommand } from '@/server/lib/updates/install-method';
+
+const checkout = {
+  pkgRoot: '/Users/dev/kabmo',
+  gitWorkTree: true,
+  gitRemote: 'https://github.com/kabmo-labs/kabmo.git',
+};
+
+describe('detectInstallMethod', () => {
+  test('recognizes a bun global install', () => {
+    const info = detectInstallMethod({
+      pkgRoot: '/Users/dev/.bun/install/global/node_modules/kabmo',
+      gitWorkTree: false,
+      gitRemote: null,
+    });
+    expect(info.method).toBe('bun-global');
+  });
+
+  test('recognizes the bun global layout behind windows separators', () => {
+    const info = detectInstallMethod({
+      pkgRoot: 'C:\\Users\\dev\\.bun\\install\\global\\node_modules\\kabmo',
+      gitWorkTree: false,
+      gitRemote: null,
+    });
+    expect(info.method).toBe('bun-global');
+  });
+
+  test('leaves a package-manager install manual', () => {
+    const info = detectInstallMethod({ pkgRoot: '/usr/local/lib/node_modules/kabmo', gitWorkTree: false, gitRemote: null });
+    expect(info.method).toBe('npm');
+    // The command is bun's in both manual branches: Kabmo is a Bun package.
+    expect(manualUpdateCommand(info.method, '0.3.0')).toBe('bun add -g @kabmo-labs/kabmo@0.3.0');
+    // The resolved target is the package an update actually installs; after the
+    // rename that is `kabmo`, and a copy on the old name must still be told so.
+    expect(manualUpdateCommand(info.method, '5.0.0', '@kabmo-labs/kabmo')).toBe('bun add -g @kabmo-labs/kabmo@5.0.0');
+  });
+
+  test('treats a checkout of the repository as updatable over git', () => {
+    expect(detectInstallMethod(checkout).method).toBe('git');
+    expect(detectInstallMethod({ ...checkout, gitRemote: 'git@github.com:kabmo-labs/kabmo.git' }).method).toBe('git');
+  });
+
+  test('recognizes the renamed repository in both spellings', () => {
+    expect(detectInstallMethod({ ...checkout, gitRemote: 'https://github.com/kabmo-labs/kabmo.git' }).method).toBe('git');
+    expect(detectInstallMethod({ ...checkout, gitRemote: 'git@github.com:kabmo-labs/kabmo.git' }).method).toBe('git');
+  });
+
+  test('leaves a checkout tracking another remote manual', () => {
+    const info = detectInstallMethod({ ...checkout, gitRemote: 'https://github.com/kabmo-labs/kabmo-fork.git' });
+    expect(info.method).toBe('unmanaged');
+    expect(manualUpdateCommand(info.method, '0.3.0')).toBe('bun add -g @kabmo-labs/kabmo@0.3.0');
+  });
+
+  test('leaves a source copy without git metadata manual', () => {
+    const info = detectInstallMethod({ pkgRoot: '/opt/src/kabmo', gitWorkTree: false, gitRemote: null });
+    expect(info.method).toBe('unmanaged');
+    expect(manualUpdateCommand(info.method, null)).toBe('bun add -g @kabmo-labs/kabmo@latest');
+  });
+});
+
+describe('planUpdateSteps', () => {
+  const params = { version: '0.3.0', pkgRoot: '/Users/dev/kabmo', bunBin: '/Users/dev/.bun/bin/bun' };
+
+  test('installs the release version for a bun global install', () => {
+    const steps = planUpdateSteps({ ...params, method: 'bun-global' });
+    expect(steps.map((step) => step.cmd.join(' '))).toEqual(['/Users/dev/.bun/bin/bun add -g @kabmo-labs/kabmo@0.3.0']);
+  });
+
+  test('installs the renamed package when the resolved target says so', () => {
+    const steps = planUpdateSteps({ ...params, method: 'bun-global', packageName: '@kabmo-labs/kabmo' });
+    expect(steps.map((step) => step.cmd.join(' '))).toEqual(['/Users/dev/.bun/bin/bun add -g @kabmo-labs/kabmo@0.3.0']);
+  });
+
+  test('fast-forwards a checkout to the release tag and rebuilds, without discarding local work', () => {
+    const steps = planUpdateSteps({ ...params, method: 'git' });
+    const commands = steps.map((step) => step.cmd.join(' '));
+
+    expect(commands).toContain('git -C /Users/dev/kabmo fetch --tags origin');
+    expect(commands).toContain('git -C /Users/dev/kabmo merge --ff-only v0.3.0');
+    expect(commands).toContain('/Users/dev/.bun/bin/bun install');
+    expect(commands).toContain('/Users/dev/.bun/bin/bun run build');
+    expect(commands.some((command) => /(push|reset|checkout|stash|clean)\b/.test(command))).toBe(false);
+    expect(steps.every((step) => step.cwd === '/Users/dev/kabmo')).toBe(true);
+  });
+});
+
+describe('resolveKabmoVersion', () => {
+  const runnerFetch = Bun.fetch;
+  let dir = '';
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'kabmo-version-'));
+    // A pre-rename install: the package on disk is still `ompchamber`, which is
+    // what makes the resolved `kabmo` a RENAME rather than a version bump.
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'ompchamber', version: '4.23.0' }));
+  });
+
+  afterEach(() => {
+    globalThis.fetch = runnerFetch;
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('a package rename is an update even when its version is lower', async () => {
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.endsWith('/@kabmo-labs%2fkabmo/latest')) return new Response(JSON.stringify({ version: '1.0.0' }), { status: 200 });
+      return new Response('{}', { status: 404 });
+    }) as typeof fetch;
+
+    const info = await resolveKabmoVersion(dir);
+    expect(info.package).toBe('@kabmo-labs/kabmo');
+    expect(info.renamed).toBe(true);
+    // 1.0.0 is LOWER than 4.23.0, and semver alone would offer nothing.
+    expect(info.updateAvailable).toBe(true);
+  });
+
+  test('the same package keeps the semver comparison', async () => {
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: '@kabmo-labs/kabmo', version: '1.0.0' }));
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.endsWith('/@kabmo-labs%2fkabmo/latest')) return new Response(JSON.stringify({ version: '1.0.0' }), { status: 200 });
+      return new Response('{}', { status: 404 });
+    }) as typeof fetch;
+
+    const info = await resolveKabmoVersion(dir);
+    expect(info.renamed).toBe(false);
+    expect(info.updateAvailable).toBe(false);
+  });
+});