@kabmo-labs/kabmo 0.7.0 → 0.9.0

package/src/server/routes/fs/action-nested.test.ts

@@ -0,0 +1,184 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Nested paths at the route: a create and a rename that name SEGMENTS.
+ *
+ * The Files panel's dialogs used to accept one segment, so `lib/parse.ts` was
+ * unreachable from the UI — the user had to create `lib`, expand it, then the
+ * file. Both actions now take a relative path, and the rules that keep that
+ * inside the folder the user named are asserted here because they are the whole
+ * reason a nested path is safe:
+ *
+ * - a `..` SEGMENT is refused even when it would land back inside the root
+ *   (`a/../b.ts` resolves there), so the refusal is about the path the user
+ *   typed rather than about where it happened to land;
+ * - an ABSOLUTE path is refused, because `path.join(dir, abs)` discards the
+ *   folder the dialog showed;
+ * - a rename resolves against the LISTED root, not the workspace root — a
+ *   rename inside a nested repo used to resolve to a path outside the repo;
+ * - a rename never overwrites an existing destination, and never moves a folder
+ *   into its own subtree.
+ */
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import fs from 'node:fs';
+import path from 'node:path';
+import { action } from '@/server/routes/fs/action';
+
+/** Probes live in the repo root — the one directory the root allow-list always accepts. */
+const DIR = path.join(process.cwd(), 'tmp-nested-probe');
+
+function reset(files: Record<string, string> = {}): void {
+  fs.rmSync(DIR, { recursive: true, force: true });
+  fs.mkdirSync(DIR, { recursive: true });
+  for (const [rel, content] of Object.entries(files)) {
+    const target = path.join(DIR, rel);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content);
+  }
+}
+
+afterEach(() => {
+  fs.rmSync(DIR, { recursive: true, force: true });
+});
+
+async function post(fields: Record<string, string>) {
+  const form = new FormData();
+  form.append('root', process.cwd());
+  for (const [key, value] of Object.entries(fields)) form.append(key, value);
+  const res = await action({ request: new Request('http://localhost/api/fs/action', { method: 'POST', body: form }) } as never);
+  return { status: res.status, body: (await res.json()) as { success?: boolean; kind?: string; path?: string; previousPath?: string; error?: string } };
+}
+
+describe('fs create with a nested path', () => {
+  test('creates every directory that leads to the file', async () => {
+    reset();
+
+    const { status, body } = await post({ actionType: 'create', path: 'tmp-nested-probe', name: 'lib/deep/parse.ts' });
+
+    expect(status).toBe(200);
+    expect(body).toEqual({ success: true, kind: 'file', path: 'tmp-nested-probe/lib/deep/parse.ts' });
+    expect(fs.readFileSync(path.join(DIR, 'lib/deep/parse.ts'), 'utf8')).toBe('');
+  });
+
+  test('creates a FOLDER when asked, and reports the kind back', async () => {
+    reset();
+
+    const { status, body } = await post({ actionType: 'create', path: 'tmp-nested-probe', name: 'a/b', kind: 'folder' });
+
+    expect(status).toBe(200);
+    expect(body).toEqual({ success: true, kind: 'folder', path: 'tmp-nested-probe/a/b' });
+    expect(fs.statSync(path.join(DIR, 'a/b')).isDirectory()).toBe(true);
+  });
+
+  test('normalizes a backslash and repeated separators into one path', async () => {
+    reset();
+
+    const { body } = await post({ actionType: 'create', path: 'tmp-nested-probe', name: 'x\\\\y//z.ts' });
+
+    expect(body.path).toBe('tmp-nested-probe/x/y/z.ts');
+    expect(fs.existsSync(path.join(DIR, 'x/y/z.ts'))).toBe(true);
+  });
+
+  test('refuses a .. segment even when it would land inside the root', async () => {
+    reset({ 'keep/.gitkeep': '' });
+
+    // `keep/../escape.ts` resolves inside the probe directory, so a containment
+    // check alone would accept it — the refusal is about the path as typed.
+    const { status, body } = await post({ actionType: 'create', path: 'tmp-nested-probe', name: 'keep/../escape.ts' });
+
+    expect(status).toBe(400);
+    expect(body.error).toContain('..');
+    expect(fs.existsSync(path.join(DIR, 'escape.ts'))).toBe(false);
+  });
+
+  test('refuses an absolute path', async () => {
+    reset();
+
+    for (const name of ['/tmp/absolute.ts', 'C:/absolute.ts', 'C:relative.ts']) {
+      expect((await post({ actionType: 'create', path: 'tmp-nested-probe', name })).status).toBe(400);
+    }
+  });
+
+  test('refuses a nested path whose final entry already exists', async () => {
+    reset({ 'lib/parse.ts': 'keep me' });
+
+    const { status, body } = await post({ actionType: 'create', path: 'tmp-nested-probe', name: 'lib/parse.ts' });
+
+    expect(status).toBe(409);
+    expect(body.error).toContain('already exists');
+    expect(fs.readFileSync(path.join(DIR, 'lib/parse.ts'), 'utf8')).toBe('keep me');
+  });
+});
+
+describe('fs rename with a nested path', () => {
+  test('renames into a new nested folder, creating its parents', async () => {
+    reset({ 'a.ts': 'A' });
+
+    const { status, body } = await post({ actionType: 'rename', path: 'tmp-nested-probe/a.ts', newPath: 'tmp-nested-probe/lib/deep/a.ts' });
+
+    expect(status).toBe(200);
+    expect(body).toEqual({ success: true, path: 'tmp-nested-probe/lib/deep/a.ts', previousPath: 'tmp-nested-probe/a.ts' });
+    expect(fs.existsSync(path.join(DIR, 'a.ts'))).toBe(false);
+    expect(fs.readFileSync(path.join(DIR, 'lib/deep/a.ts'), 'utf8')).toBe('A');
+  });
+
+  test('a plain rename inside one folder keeps its siblings', async () => {
+    reset({ 'src/a.ts': 'A', 'src/b.ts': 'B' });
+
+    const { body } = await post({ actionType: 'rename', path: 'tmp-nested-probe/src/a.ts', newPath: 'tmp-nested-probe/src/c.ts' });
+
+    expect(body.path).toBe('tmp-nested-probe/src/c.ts');
+    expect(fs.existsSync(path.join(DIR, 'src/b.ts'))).toBe(true);
+  });
+
+  test('refuses an existing destination instead of clobbering it', async () => {
+    reset({ 'a.ts': 'A', 'b.ts': 'B' });
+
+    const { status, body } = await post({ actionType: 'rename', path: 'tmp-nested-probe/a.ts', newPath: 'tmp-nested-probe/b.ts' });
+
+    expect(status).toBe(409);
+    expect(body.error).toContain('already exists');
+    expect(fs.readFileSync(path.join(DIR, 'b.ts'), 'utf8')).toBe('B');
+  });
+
+  test('refuses moving a folder into its own subtree', async () => {
+    reset({ 'src/a.ts': 'A' });
+
+    const { status, body } = await post({ actionType: 'rename', path: 'tmp-nested-probe/src', newPath: 'tmp-nested-probe/src/deep' });
+
+    expect(status).toBe(400);
+    expect(body.error).toContain('inside itself');
+    expect(fs.existsSync(path.join(DIR, 'src/a.ts'))).toBe(true);
+  });
+
+  test('refuses a .. segment and an absolute destination', async () => {
+    reset({ 'a.ts': 'A' });
+
+    expect((await post({ actionType: 'rename', path: 'tmp-nested-probe/a.ts', newPath: 'tmp-nested-probe/../out.ts' })).status).toBe(400);
+    expect((await post({ actionType: 'rename', path: 'tmp-nested-probe/a.ts', newPath: '/tmp/out.ts' })).status).toBe(400);
+    expect(fs.existsSync(path.join(DIR, 'a.ts'))).toBe(true);
+  });
+
+  test('renaming to the same path is a no-op that still reports both ends', async () => {
+    reset({ 'a.ts': 'A' });
+
+    const { status, body } = await post({ actionType: 'rename', path: 'tmp-nested-probe/a.ts', newPath: 'tmp-nested-probe/a.ts' });
+
+    expect(status).toBe(200);
+    expect(body.path).toBe('tmp-nested-probe/a.ts');
+    expect(fs.readFileSync(path.join(DIR, 'a.ts'), 'utf8')).toBe('A');
+  });
+
+  test('a missing source is refused rather than creating an empty entry', async () => {
+    reset();
+
+    const { status } = await post({ actionType: 'rename', path: 'tmp-nested-probe/gone.ts', newPath: 'tmp-nested-probe/here.ts' });
+
+    expect(status).toBe(404);
+    expect(fs.existsSync(path.join(DIR, 'here.ts'))).toBe(false);
+  });
+});

package/src/server/routes/fs/action.ts

@@ -3,10 +3,11 @@ import { errorResponse } from '@/server/lib/route-adapter';
 import fs from 'fs';
 import path from 'path';
 import { isMockMode } from '@/server/mock.server';
-import { getDefaultFsRoot, resolveRoot, resolveWithinRoot } from '@/server/lib/fs/root';
+import { getDefaultFsRoot, isWithinRoot, resolveRoot, resolveWithinRoot } from '@/server/lib/fs/root';
 import { runShell } from '@/server/lib/fs/shell';
 import { revealInFileManager } from '@/server/lib/fs/reveal';
-import { duplicateEntry, nextDuplicateName, pasteEntry } from '@/server/lib/fs/transfer';
+import { duplicateEntry, nextDuplicateName, pasteEntry, toRelPath } from '@/server/lib/fs/transfer';
+import { normalizeRelativePath } from '@/server/lib/fs/relative-path';
 import { transferRefusal } from '@/shared/lib/fs/clipboard';
 import { toDiskText } from '@/shared/lib/code/line-endings';
 
@@ -104,13 +105,15 @@ export async function action({ request }: ActionFunctionArgs) {
       await Bun.write(fullPath, content);
       return json({ success: true });
     } else if (actionType === 'create') {
-      // The Files panel's "New file": an empty file beside the folder that was
-      // right-clicked. Only a NAME is accepted, never a path — a separator
-      // would let the panel write anywhere under the root, and the folder is
-      // already named by `path`.
-      const name = ((formData.get('name') as string) ?? '').trim();
-      if (!name || name === '.' || name === '..' || /[/\\\0]/.test(name)) {
-        return json({ error: 'Enter a file name without slashes' }, { status: 400 });
+      // The Files panel's "New file"/"New folder": an empty entry beside the
+      // folder that was right-clicked. The NAME may carry segments
+      // (`lib/parse.ts`), so one dialog creates a nested path and every
+      // intermediate directory with it — the grammar that keeps it inside the
+      // named folder lives in `normalizeRelativePath`, not in a slash test here.
+      const kind = formData.get('kind') === 'folder' ? 'folder' : 'file';
+      const name = normalizeRelativePath((formData.get('name') as string) ?? '');
+      if (!name) {
+        return json({ error: 'Enter a name without .. or a leading slash' }, { status: 400 });
       }
       const target = resolveWithinRoot(scopedRoot, path.join(filePath || '.', name));
       if (!target) {
@@ -122,21 +125,49 @@ export async function action({ request }: ActionFunctionArgs) {
       if ((await Bun.file(target).stat().catch(() => null)) !== null) {
         return json({ error: `${name} already exists` }, { status: 409 });
       }
-      await fs.promises.mkdir(path.dirname(target), { recursive: true });
-      await Bun.write(target, '');
+      if (kind === 'folder') await fs.promises.mkdir(target, { recursive: true });
+      else {
+        await fs.promises.mkdir(path.dirname(target), { recursive: true });
+        await Bun.write(target, '');
+      }
       // Relative to the LISTED root, which is the identity the tree renders by.
-      return json({ success: true, path: path.relative(scopedRoot, target).split(path.sep).join('/') });
+      return json({ success: true, kind, path: toRelPath(scopedRoot, target) });
     } else if (actionType === 'delete') {
       await fs.promises.rm(fullPath, { recursive: true, force: true });
       return json({ success: true });
     } else if (actionType === 'rename') {
-      const newPath = formData.get('newPath') as string;
-      const fullNewPath = path.resolve(rootDir, newPath);
-      if (fullNewPath !== rootDir && !fullNewPath.startsWith(rootDir + path.sep)) {
+      // `newPath` is relative to the LISTED root, exactly like `path` is. It
+      // used to be resolved against `rootDir`, so renaming inside a nested repo
+      // resolved to a path under the workspace root instead of the repo — a
+      // move out of the tree the row belongs to.
+      const newPath = normalizeRelativePath((formData.get('newPath') as string) ?? '');
+      if (!newPath) {
+        return json({ error: 'Enter a name without .. or a leading slash' }, { status: 400 });
+      }
+      const fullNewPath = resolveWithinRoot(scopedRoot, newPath);
+      if (!fullNewPath) {
         return json({ error: 'Invalid new path' }, { status: 403 });
       }
+      if (fullNewPath === fullPath) return json({ success: true, path: newPath, previousPath: filePath });
+      const source = await Bun.file(fullPath).stat().catch(() => null);
+      if (!source) return json({ error: 'That entry no longer exists' }, { status: 404 });
+      // A folder cannot be moved into itself: `rename(a, a/b)` fails with
+      // EINVAL on every platform, but with an errno the panel cannot explain —
+      // and the destination directory may not exist yet, so the check has to be
+      // on the PATHS rather than on the filesystem.
+      if (source.isDirectory() && isWithinRoot(fullPath, fullNewPath)) {
+        return json({ error: 'A folder cannot be moved inside itself' }, { status: 400 });
+      }
+      // `rename` clobbers silently, so an existing destination is refused: the
+      // entry the user meant to keep would otherwise disappear without a word.
+      if ((await Bun.file(fullNewPath).stat().catch(() => null)) !== null) {
+        return json({ error: `${newPath} already exists` }, { status: 409 });
+      }
+      // The destination's parents are created, which is what makes a rename
+      // INTO a new folder work — the same nested grammar the create accepts.
+      await fs.promises.mkdir(path.dirname(fullNewPath), { recursive: true });
       await fs.promises.rename(fullPath, fullNewPath);
-      return json({ success: true });
+      return json({ success: true, path: newPath, previousPath: filePath });
     } else if (actionType === 'open_explorer') {
       const isDir = (await Bun.file(fullPath).stat().catch(() => null))?.isDirectory() ?? false;
       // A file reveals its containing directory — there is no portable "select

package/src/server/routes/fs/git-merge.test.ts

@@ -19,7 +19,7 @@
  *    answers "no <op> in progress" and only `reset --merge HEAD` clears it.
  */
 
-import { afterAll, describe, expect, test } from 'bun:test';
+import { afterAll, describe, expect, setDefaultTimeout, test } from 'bun:test';
 import fs from 'node:fs';
 import path from 'node:path';
 import { action } from '@/server/routes/fs/git';
@@ -36,6 +36,16 @@ import { removeDir } from '@/test-support/remove-dir';
  * action ran against THE Kabmo REPOSITORY.
  */
 const FIXTURE_ROOT = path.join(process.cwd(), 'tmp-test-git-merge');
+
+/**
+ * Every case here builds a real repository and drives several `git` processes
+ * through it, so Bun's 5s per-test default is a budget for the RUNNER rather
+ * than for the code. Measured on a loaded CI runner: the cherry-pick case alone
+ * spent 5.0s and timed out, while the same commit passed the `Checks` job and
+ * failed the `Release` one minutes later — the same suite, two machines, one
+ * answer each. `git-actions-sync.test.ts` sets the same 30s for the same reason.
+ */
+setDefaultTimeout(30_000);
 const repos: string[] = [];
 
 function git(cwd: string, ...args: string[]): string {

package/src/server/routes/fs/read.test.ts

@@ -21,6 +21,7 @@ import fs from 'fs';
 import path from 'path';
 import { readFile } from '@/server/routes/fs/read';
 import { EDITOR_MAX_FILE_BYTES, PDF_MAX_FILE_BYTES } from '@/shared/lib/fs/file-kind';
+import { formatBytes } from '@/shared/lib/format/number';
 
 const DIR = path.join(process.cwd(), 'tmp-read-gate');
 
@@ -88,16 +89,23 @@ describe('fs read gate', () => {
 
     expect(status).toBe(415);
     expect(body.kind).toBe('too-large');
-    expect(body.error).toContain('5.00 MB');
+    // Derived from the constant, not spelled out: the sentence and the gate must
+    // name the same number, and a literal here would pass while they drifted.
+    expect(body.error).toContain(formatBytes(EDITOR_MAX_FILE_BYTES));
   });
 
   // A PDF is streamed to Chrome's own viewer through `/api/fs/raw`, so the text
-  // ceiling does not apply to it — the route must still point at the raw route
-  // for a PDF well past 5 MB rather than refusing it. Refusing it was the bug:
-  // the size test ran before the document branch, so a 6 MB PDF was answered
-  // "larger than the 5.00 MB the editor opens".
-  test('a PDF past the text ceiling is still served by the raw route', async () => {
-    write('report.pdf', new Uint8Array(EDITOR_MAX_FILE_BYTES + 1).fill(0x25));
+  // ceiling has no bearing on it — the route must point at the raw route rather
+  // than refuse it. Refusing it was the bug: the size test ran before the
+  // document branch, so a 6 MB PDF was answered "larger than the 5.00 MB the
+  // editor opens". 6 MB is the size that was over the old text ceiling and is
+  // still a perfectly ordinary PDF.
+  //
+  // It is written at 6 MB rather than at `EDITOR_MAX_FILE_BYTES + 1` because the
+  // two ceilings are independent: the text one is now ABOVE the PDF one, so
+  // "past text, under PDF" is no longer a size that exists.
+  test('a PDF past the old text ceiling is still served by the raw route', async () => {
+    write('report.pdf', new Uint8Array(6 * 1024 * 1024).fill(0x25));
     const { status, body } = await read('report.pdf');
 
     expect(status).toBe(400);
@@ -105,6 +113,15 @@ describe('fs read gate', () => {
     expect(body.kind).toBeUndefined();
   });
 
+  test('a PDF past its own ceiling is refused before the document branch', async () => {
+    write('enormous.pdf', new Uint8Array(PDF_MAX_FILE_BYTES + 1).fill(0x25));
+    const { status, body } = await read('enormous.pdf');
+
+    expect(status).toBe(415);
+    expect(body.kind).toBe('too-large');
+    expect(body.error).toContain(formatBytes(PDF_MAX_FILE_BYTES));
+  });
+
   test('a PDF past the PDF ceiling is refused for size, naming 30 MB', async () => {
     write('huge.pdf', new Uint8Array(PDF_MAX_FILE_BYTES + 1).fill(0x25));
     const { status, body } = await read('huge.pdf');

package/src/server/routes/fs/scope.test.ts

@@ -20,7 +20,8 @@ import fs from 'fs';
 import path from 'path';
 import { testPosix } from '@/test-support/platform';
 import { resolveFileScope } from '@/server/routes/fs/scope';
-import { DOCUMENT_MAX_FILE_BYTES, PDF_MAX_FILE_BYTES } from '@/shared/lib/fs/file-kind';
+import { DOCUMENT_MAX_FILE_BYTES, EDITOR_MAX_FILE_BYTES, PDF_MAX_FILE_BYTES } from '@/shared/lib/fs/file-kind';
+import { formatBytes } from '@/shared/lib/format/number';
 
 const APP = process.cwd();
 const DIR = path.join(APP, 'tmp-scope-probe');
@@ -158,14 +159,18 @@ describe('fs scope route', () => {
     expect(body.error).toContain('20.00 MB');
   });
 
-  // Plain text keeps the text ceiling: a textarea holds that buffer for the
-  // life of the tab, which is why its limit did not move with the documents'.
-  test('a text file past the text ceiling is still refused', async () => {
-    const target = write('big.log', new Uint8Array(6 * 1024 * 1024).fill(0x61));
-    const { status, body } = await scope(target);
-
-    expect(status).toBe(200);
-    expect(body.kind).toBe('too-large');
-    expect(body.error).toContain('5.00 MB');
+  // Plain text keeps the text ceiling, which is its own number: the buffer is
+  // held for the life of the tab and re-posted on every save, where a document
+  // is converted once. 6 MB used to be over it; it is a normal generated file
+  // and must open.
+  test('a text file over the text ceiling is refused, and one under it is not', async () => {
+    const ok = await scope(write('big.log', new Uint8Array(6 * 1024 * 1024).fill(0x61)));
+    expect(ok.status).toBe(200);
+    expect(ok.body.kind).toBe('text');
+
+    const over = await scope(write('huge.log', new Uint8Array(EDITOR_MAX_FILE_BYTES + 1).fill(0x61)));
+    expect(over.status).toBe(200);
+    expect(over.body.kind).toBe('too-large');
+    expect(over.body.error).toContain(formatBytes(EDITOR_MAX_FILE_BYTES));
   });
 });

package/src/server/routes/fs/scope.ts

@@ -26,25 +26,14 @@
 import { json, type LoaderFunctionArgs } from '@/server/lib/remix-compat';
 import { resolveScopeForAbsolutePath } from '@/server/lib/fs/root';
 import { BINARY_SNIFF_BYTES, classifyEditorFile, unsupportedEditorMessage } from '@/shared/lib/fs/file-kind';
+import { pathFromFileUrl } from '@/shared/lib/fs/file-url';
 import fs from 'fs';
 import path from 'path';
 
-/**
- * A `file://` URL to the path it names.
- *
- * The pathname is percent-encoded (a space is `%20`, and a Finder drop of
- * `My Notes.md` is exactly that), so decoding is not optional. `decodeURIComponent`
- * can throw on a malformed escape, which is answered as "not a path" rather
- * than surfacing as a 500.
- */
+/** A `file://` URL to the path it names; see `pathFromFileUrl` for the rules. */
 function pathFromReference(reference: string): string | null {
   if (!/^file:\/\//i.test(reference)) return reference;
-  try {
-    const url = new URL(reference);
-    return decodeURIComponent(url.pathname);
-  } catch {
-    return null;
-  }
+  return pathFromFileUrl(reference);
 }
 
 export async function resolveFileScope({ request }: LoaderFunctionArgs) {

package/src/server/routes/index.ts

@@ -12,6 +12,7 @@ import { waitingBindings } from '@/server/routes/waiting/bindings';
 import { settingsBindings } from '@/server/routes/settings';
 import { fsBindings } from '@/server/routes/fs';
 import { foldersBindings } from '@/server/routes/folders';
+import { worktreesBindings } from '@/server/routes/worktrees';
 import { filesBindings } from '@/server/routes/files';
 import { telemetryBindings } from '@/server/routes/telemetry';
 import { terminalBindings } from '@/server/routes/terminal';
@@ -42,6 +43,7 @@ const allBindings: HandlerBinding[] = [
   ...settingsBindings,
   ...fsBindings,
   ...foldersBindings,
+  ...worktreesBindings,
   ...filesBindings,
   ...telemetryBindings,
   ...terminalBindings,

package/src/server/routes/updates/android.ts

@@ -12,11 +12,16 @@ import { fetchShellRelease, type ShellRelease } from '@/server/lib/updates/shell
  *
  * A failed probe is a valid answer (`url: null`), never a 500: the sidebar's job
  * is to omit a button it cannot back with a link.
+ *
+ * PUBLIC, unlike its siblings: the Android shell asks this from native code
+ * (`AppUpdateCheck`), which has no session cookie, and its "Check for update"
+ * button is for a shell too stale to load the console. See `PUBLIC_EXACT` in
+ * `lib/auth/guard.ts`.
  */
 export async function loader() {
   const release: ShellRelease | null = await fetchShellRelease('android');
   return json(
-    release ?? { url: null, latest: null, releaseUrl: null },
+    release ?? { url: null, latest: null, releaseUrl: null, direct: false },
     { headers: NO_STORE_HEADERS },
   );
 }

package/src/server/routes/updates/desktop.ts

@@ -0,0 +1,59 @@
+import { json, NO_STORE_HEADERS } from '@/server/lib/remix-compat';
+import { fetchShellRelease, type ShellRelease } from '@/server/lib/updates/shell-release';
+import { isDesktopShellKind, type DesktopShellKind } from '@/shared/lib/updates/shell-ua';
+import { parseShellArch, type ShellArch } from '@/shared/lib/updates/shell-arch';
+
+/**
+ * GET /api/updates/desktop?kind=macos|windows|linux[&arch=arm64|x64]
+ *
+ * ONE route with an explicit `kind`, unlike the mobile pair's two routes, and
+ * the difference is deliberate. `?kind` here is REQUIRED and refused when it is
+ * missing or names no desktop shell, so no absence can silently mean a platform:
+ * the mobile pair's split exists precisely because a defaulted parameter would
+ * have made "the newest shell" mean Android without anyone saying so.
+ *
+ * ## `arch` is what makes the offer installable
+ *
+ * Only an INSTALLED desktop shell asks for this — the page reports its own
+ * version over the shell bridge (`__kabmoDesktop.shellVersion`), because a
+ * desktop app carries no User-Agent token. Without `arch` the answer is the
+ * RELEASE PAGE: every desktop artifact is per-architecture, and a console served
+ * to another machine cannot guess which one this window runs on.
+ *
+ * WITH `arch` the answer is that machine's own installer, and `direct: true`
+ * says so — which is what lets the sidebar offer an in-app update instead of a
+ * link. The shell still verifies the bytes before installing them; this route
+ * only decides WHICH file, never whether it is trusted.
+ *
+ * An `arch` that names nothing this product publishes is a REFUSAL rather than a
+ * silent fallback: a caller that asked for a build we do not make should be told,
+ * not handed the other architecture's installer.
+ *
+ * A failed probe is a valid answer (`url: null`), never a 500: the sidebar's job
+ * is to omit a button it cannot back with a link.
+ */
+export async function loader({ request }: { request: Request }) {
+  const params = new URL(request.url).searchParams;
+  const kind = params.get('kind');
+  if (!isDesktopShellKind(kind ?? '')) {
+    return json(
+      { error: 'kind must be one of macos, windows, linux' },
+      { status: 400, headers: NO_STORE_HEADERS },
+    );
+  }
+
+  const requested = params.get('arch');
+  const arch: ShellArch | null = requested ? parseShellArch(requested) : null;
+  if (requested && !arch) {
+    return json(
+      { error: 'arch must be one of arm64, x64' },
+      { status: 400, headers: NO_STORE_HEADERS },
+    );
+  }
+
+  const release: ShellRelease | null = await fetchShellRelease(kind as DesktopShellKind, fetch, arch);
+  return json(
+    release ?? { url: null, latest: null, releaseUrl: null, direct: false },
+    { headers: NO_STORE_HEADERS },
+  );
+}

package/src/server/routes/updates/index.ts

@@ -3,6 +3,7 @@ import * as updatesAndroid from '@/server/routes/updates/android';
 import * as updatesApply from '@/server/routes/updates/apply';
 import * as updatesChangelog from '@/server/routes/updates/changelog';
 import * as updatesCheck from '@/server/routes/updates/check';
+import * as updatesDesktop from '@/server/routes/updates/desktop';
 import * as updatesIos from '@/server/routes/updates/ios';
 
 export const updatesBindings: HandlerBinding[] = [
@@ -10,5 +11,6 @@ export const updatesBindings: HandlerBinding[] = [
   ...bindingsFor(updatesApply, '/api/updates/apply'),
   ...bindingsFor(updatesChangelog, '/api/updates/changelog'),
   ...bindingsFor(updatesCheck, '/api/updates/check'),
+  ...bindingsFor(updatesDesktop, '/api/updates/desktop'),
   ...bindingsFor(updatesIos, '/api/updates/ios'),
 ];

package/src/server/routes/updates/ios.ts

@@ -16,11 +16,15 @@ import { fetchShellRelease, type ShellRelease } from '@/server/lib/updates/shell
  *
  * A failed probe is a valid answer (`url: null`), never a 500: the sidebar's job
  * is to omit a button it cannot back with a link.
+ *
+ * PUBLIC, for the same reason as `/api/updates/android`: the installed shell
+ * asks it from native code with no session cookie, and the check has to work
+ * before the console can load.
  */
 export async function loader() {
   const release: ShellRelease | null = await fetchShellRelease('ios');
   return json(
-    release ?? { url: null, latest: null, releaseUrl: null },
+    release ?? { url: null, latest: null, releaseUrl: null, direct: false },
     { headers: NO_STORE_HEADERS },
   );
 }