@1agh/maude 1.2.0 → 1.3.0

package/apps/studio/http.ts

@@ -1,3 +1,4 @@
+import { validAnnotationWriteId } from './annotations-sync.ts';
 // HTTP layer for Bun.serve.
 //
 // Designed for extension — Phase 3.6 adds /ui/:slug + /_bun_hmr by appending to
@@ -102,6 +103,7 @@ import { gitShowFile } from './git/service.ts';
 import { createGitHubEndpoints } from './github/endpoints.ts';
 import type { InspectRegistry } from './inspect.ts';
 import { canvasSlug, writeLocator } from './locator.ts';
+import { prepareManagedProject } from './managed-projects.ts';
 import { BIN_DIR, DEV_SERVER_ROOT, MEDIA_DIR, STICKERS_DIR } from './paths.ts';
 import { createPhotoStore, PHOTO_EDIT_MAX_BYTES } from './photo-store.ts';
 import { probeReadiness } from './readiness.ts';
@@ -523,6 +525,8 @@ const canvasCache = new Map<string, CanvasCacheEntry>();
 // boot id in means a restart — the expected workflow after a dev-server source
 // edit (see CLAUDE.md) — changes every canvas etag, so a normal reload re-fetches
 // fresh chrome. (DDR-067.)
+/** When this server process started — anything it wrote is stamped after it. */
+const PROCESS_STARTED_AT = Date.now();
 const RUNTIME_BOOT_ID = `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
 
 // Bumped by the chrome source watchers (below) on every canvas-lib / dev-server
@@ -851,8 +855,16 @@ async function serveHistoricalCanvas(
     if (historicalMissCache.has(key)) {
       return new Response('No saved version of this canvas', { status: 404 });
     }
-    let source = await gitShowFile(ctx.paths.repoRoot, sha, repoRel);
-    if (source == null) {
+    // ACCEPTED REVISIONS: `r<revision>` names a project revision (T27), read
+    // from the project's store — immutable, so it caches like a sha.
+    const acceptedRev = /^r(\d{1,12})$/.exec(sha);
+    let source = acceptedRev
+      ? ((await ctx.syncControl
+          ?.current?.()
+          ?.acceptedVersion?.(repoRel, Number(acceptedRev[1]))
+          .catch(() => null)) ?? null)
+      : await gitShowFile(ctx.paths.repoRoot, sha, repoRel);
+    if (source == null && !acceptedRev) {
       const fromCloud = await cloudHistoryApi(ctx).historyFile(sha, repoRel);
       source = fromCloud.ok ? fromCloud.source : null;
       // ONLY AN AUTHORITATIVE ABSENCE IS REMEMBERED (security re-review of
@@ -1227,11 +1239,16 @@ export function createHttp(
   // GitHub routes: MAIN-ORIGIN ONLY (absent from CANVAS_SAFE_API +
   // startCanvasServer) and loopback-Host gated — every route either bears or
   // stores the cloud credential.
-  const cloudApi = createCloudEndpoints({
-    ...ctx,
-    // Connect and Disconnect both change WHO can answer for a past version.
-    onLinkChanged: clearHistoricalCaches,
-  });
+  // A LIVE view of ctx, never a copy: server.ts attaches `ctx.syncControl`
+  // after the route table is built, and a spread taken here froze it out —
+  // Connect then linked the project and answered "Restart Maude to start
+  // syncing" instead of starting the sync (cloud-attach E2E, since 2026-08-18).
+  const cloudApi = createCloudEndpoints(
+    Object.assign(Object.create(ctx) as Context, {
+      // Connect and Disconnect both change WHO can answer for a past version.
+      onLinkChanged: clearHistoricalCaches,
+    })
+  );
   // Figma import (DDR-216). Same dual-allowlist rule as the GitHub + cloud
   // routes: MAIN-ORIGIN ONLY, plus loopback-Host and same-origin gating on
   // every one of them — each either stores or spends the user's Figma PAT.
@@ -1729,7 +1746,16 @@ export function createHttp(
         return Response.json({ linked: false }, { headers: { 'Cache-Control': 'no-store' } });
       }
       try {
-        return Response.json(JSON.parse(readFileSync(file, 'utf8')), {
+        const status = JSON.parse(readFileSync(file, 'utf8'));
+        // The sync runtime lives in THIS process and stamps every payload it
+        // writes. A file older than the process is a previous session's last
+        // word — "offline" against a hub that may no longer be linked at all —
+        // and showing it as the current state greeted the designer with
+        // "Working offline" before anything had been tried.
+        if (!(Number(status?.updatedAt) >= PROCESS_STARTED_AT)) {
+          return Response.json({ linked: false }, { headers: { 'Cache-Control': 'no-store' } });
+        }
+        return Response.json(status, {
           headers: { 'Cache-Control': 'no-store' },
         });
       } catch {
@@ -2219,6 +2245,17 @@ export function createHttp(
           ? body.author.trim().slice(0, 120)
           : 'Claude';
       const entry = ai.start(body.file.trim(), author);
+      // T16 — the edit is ONE project action: what the agent writes until
+      // /end is published together (or held, if it fails).
+      const name =
+        body.file
+          .trim()
+          .split('/')
+          .pop()
+          ?.replace(/\.(tsx|html)$/i, '') ?? 'canvas';
+      ctx.syncControl
+        ?.current?.()
+        ?.beginAiAction?.(`edit:${body.file.trim()}`, `${author} edited ${name}`);
       return Response.json(entry, { headers: { 'Cache-Control': 'no-store' } });
     },
 
@@ -2246,17 +2283,99 @@ export function createHttp(
         return new Response('cross-origin write rejected', { status: 403 });
       if (!isTrustedRequestHost(req))
         return new Response('local request required (DNS-rebinding guard)', { status: 403 });
-      const body = await readJson<{ file?: string }>(req);
+      const body = await readJson<{ file?: string; outcome?: string }>(req);
       if (!body || typeof body.file !== 'string' || !body.file.trim()) {
         return new Response('body.file required', { status: 400 });
       }
+      // T16 — close the action BEFORE the banner clears: `done` publishes
+      // what the agent wrote as one action, `failed` keeps it unpublished for
+      // the person's decision. (No outcome = done, the pre-T16 contract.)
+      const action = await ctx.syncControl
+        ?.current?.()
+        ?.endAiAction?.(`edit:${body.file.trim()}`, body.outcome === 'failed' ? 'failed' : 'done')
+        .catch(() => null);
       const cleared = ai.end(body.file.trim());
       return Response.json(
-        { cleared },
+        { cleared, ...(action ? { action } : {}) },
         { status: cleared ? 200 : 404, headers: { 'Cache-Control': 'no-store' } }
       );
     },
 
+    '/_api/sync/offline': async (req: Request) => {
+      // T19 — "Download everything for offline": every file of the project
+      // now, instead of as the passes get to it.
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      if (!sameOriginWrite(req))
+        return new Response('cross-origin write rejected', { status: 403 });
+      if (!isTrustedRequestHost(req))
+        return new Response('local request required', { status: 403 });
+      const r = await ctx.syncControl?.current?.()?.prepareOffline?.();
+      if (!r)
+        return Response.json(
+          { ok: false, error: 'This project has no files to download.' },
+          { status: 409 }
+        );
+      return Response.json({ ok: true, ...r }, { headers: { 'Cache-Control': 'no-store' } });
+    },
+
+    '/_api/project/conflict': async (req: Request) => {
+      // T28 — a held source conflict: GET the two sides, POST the decision.
+      if (!isTrustedRequestHost(req))
+        return new Response('local request required', { status: 403 });
+      const runtime = ctx.syncControl?.current?.();
+      if (req.method === 'GET') {
+        const file = new URL(req.url).searchParams.get('file') ?? '';
+        const sides = runtime?.conflictVersions?.(file);
+        if (!sides)
+          return Response.json(
+            { ok: false, error: 'No conflict on that canvas.' },
+            { status: 404 }
+          );
+        return Response.json({ ok: true, ...sides }, { headers: { 'Cache-Control': 'no-store' } });
+      }
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      if (!sameOriginWrite(req))
+        return new Response('cross-origin write rejected', { status: 403 });
+      const body = await readJson<{ file?: string; choice?: string }>(req);
+      const choice = body?.choice === 'mine' ? 'mine' : body?.choice === 'theirs' ? 'theirs' : null;
+      if (!body?.file || !choice)
+        return Response.json({ ok: false, error: 'file and choice required' }, { status: 400 });
+      const r = await runtime?.resolveConflict?.(body.file, choice);
+      if (!r)
+        return Response.json({ ok: false, error: 'No conflict on that canvas.' }, { status: 404 });
+      return Response.json(
+        { ok: r.status !== 'rejected', ...r },
+        { headers: { 'Cache-Control': 'no-store' } }
+      );
+    },
+
+    '/_api/project/ai-action': async (req: Request) => {
+      // T16 — the person's decision on an unfinished AI edit (held stage).
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      if (!sameOriginWrite(req))
+        return new Response('cross-origin write rejected', { status: 403 });
+      if (!isTrustedRequestHost(req))
+        return new Response('local request required', { status: 403 });
+      const body = await readJson<{ choice?: string }>(req);
+      const choice =
+        body?.choice === 'discard' ? 'discard' : body?.choice === 'publish' ? 'publish' : null;
+      if (!choice)
+        return Response.json(
+          { ok: false, error: 'choice must be publish or discard' },
+          { status: 400 }
+        );
+      const r = await ctx.syncControl?.current?.()?.resolveAiAction?.(choice);
+      if (!r)
+        return Response.json(
+          { ok: false, error: 'There is no unfinished AI edit.' },
+          { status: 409 }
+        );
+      return Response.json(
+        { ok: r.status !== 'rejected', ...r },
+        { headers: { 'Cache-Control': 'no-store' } }
+      );
+    },
+
     '/_api/annotations': async (req: Request) => {
       // Phase 5 — `<designRoot>/<slug>.annotations.svg` read / overwrite.
       // GET ?file=<repo-relative-canvas-path>           → SVG text (empty if absent)
@@ -2275,14 +2394,32 @@ export function createHttp(
         });
       }
       if (req.method === 'PUT' || req.method === 'POST') {
-        const body = await readJson<{ file?: string; svg?: string }>(req, 1024 * 1024 + 1024);
+        // `base` (optional) is the SVG this edit was derived from — the hub
+        // merges a concurrent peer's strokes from it (accepted revisions).
+        const body = await readJson<{
+          file?: string;
+          svg?: string;
+          writeId?: unknown;
+          base?: unknown;
+        }>(req, 2 * 1024 * 1024 + 2048);
         if (!body || typeof body.file !== 'string' || !body.file) {
           return new Response('body must include { file, svg }', { status: 400 });
         }
         if (typeof body.svg !== 'string') {
           return new Response('body.svg must be a string', { status: 400 });
         }
-        const ok = await api.saveAnnotations(body.file, body.svg);
+        if (body.writeId !== undefined && !validAnnotationWriteId(body.writeId)) {
+          return new Response('invalid annotation writeId', { status: 400 });
+        }
+        if (body.base !== undefined && typeof body.base !== 'string') {
+          return new Response('body.base must be a string', { status: 400 });
+        }
+        const ok = await api.saveAnnotations(
+          body.file,
+          body.svg,
+          body.writeId as string | undefined,
+          body.base as string | undefined
+        );
         if (!ok) return new Response('rejected', { status: 400 });
         return new Response(null, { status: 204 });
       }
@@ -2344,7 +2481,11 @@ export function createHttp(
         64 * 1024
       );
       if (!body) return new Response('body required', { status: 400 });
-      const result = await api.createCanvas(body);
+      const duplicateOf = (body as { duplicateOf?: unknown }).duplicateOf;
+      const result =
+        duplicateOf !== undefined
+          ? await api.duplicateCanvas({ file: duplicateOf })
+          : await api.createCanvas(body);
       if (!result.ok) {
         return Response.json(
           { ok: false, error: result.error },
@@ -2371,7 +2512,10 @@ export function createHttp(
       if (!isTrustedRequestHost(req))
         return new Response('local request required (DNS-rebinding guard)', { status: 403 });
       if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
-      const body = await readJson<{ file?: unknown; toDir?: unknown }>(req, 4 * 1024);
+      const body = await readJson<{ file?: unknown; toDir?: unknown; toName?: unknown }>(
+        req,
+        4 * 1024
+      );
       if (!body) return new Response('body required', { status: 400 });
       const result = await api.moveCanvas(body);
       if (!result.ok) {
@@ -2689,6 +2833,61 @@ export function createHttp(
     // (DDR-054) and must not be able to command the desktop to re-push a whole
     // project — a canvas that could would be an amplification primitive against
     // the person's own hub, and a way to spend their rate-limit budget.
+    // ACCEPTED REVISIONS — the project's logical history (DDR-241, T27/T28).
+    // Main origin only: history names people, restore and undo are writes.
+    '/_api/project/history': async (req: Request) => {
+      if (req.method !== 'GET') return new Response('Method not allowed', { status: 405 });
+      if (!isTrustedRequestHost(req)) return new Response('Forbidden', { status: 403 });
+      const url = new URL(req.url);
+      const runtime = ctx.syncControl?.current?.();
+      const rows = runtime?.acceptedHistory
+        ? await runtime
+            .acceptedHistory({
+              limit: Number(url.searchParams.get('limit') ?? 50) || 50,
+              before: Number(url.searchParams.get('before') ?? 0) || null,
+              path: url.searchParams.get('path'),
+            })
+            .catch(() => undefined)
+        : null;
+      if (rows === undefined) {
+        return gitJson({ status: 200, json: { ok: false, reason: 'unreachable' } });
+      }
+      if (rows === null) return gitJson({ status: 200, json: { ok: false, reason: 'legacy' } });
+      return gitJson({ status: 200, json: { ok: true, history: rows } });
+    },
+    '/_api/project/restore': async (req: Request) => {
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      if (!sameOriginWrite(req) || !isTrustedRequestHost(req))
+        return new Response('Forbidden', { status: 403 });
+      const body = await readJson<{ path?: unknown; revision?: unknown }>(req, 4096);
+      const revision = Number(body?.revision);
+      if (typeof body?.path !== 'string' || !Number.isSafeInteger(revision) || revision < 0) {
+        return new Response('body must include { path, revision }', { status: 400 });
+      }
+      const r = await ctx.syncControl?.current?.()?.acceptedRestore?.(body.path, revision);
+      if (!r) return gitJson({ status: 200, json: { ok: false, reason: 'legacy' } });
+      return gitJson({
+        status: r.status === 'accepted' ? 200 : 409,
+        json: { ok: r.status === 'accepted', ...r },
+      });
+    },
+    '/_api/project/undo': async (req: Request) => {
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      if (!sameOriginWrite(req) || !isTrustedRequestHost(req))
+        return new Response('Forbidden', { status: 403 });
+      const body = await readJson<{ actionId?: unknown; redo?: unknown }>(req, 4096);
+      if (typeof body?.actionId !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(body.actionId)) {
+        return new Response('body must include { actionId }', { status: 400 });
+      }
+      const r = await ctx.syncControl
+        ?.current?.()
+        ?.acceptedUndo?.(body.actionId, body.redo === true);
+      if (!r) return gitJson({ status: 200, json: { ok: false, reason: 'legacy' } });
+      return gitJson({
+        status: r.status === 'accepted' ? 200 : 409,
+        json: { ok: r.status === 'accepted', ...r },
+      });
+    },
     '/_api/sync/resync': async (req: Request) => {
       if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
       // REFUSALS ANSWER IN JSON, WITH A REASON.
@@ -3133,6 +3332,38 @@ export function createHttp(
     // rather than a token to paste. Same gates as the link route (MAIN ORIGIN
     // only, loopback, POST CSRF) for the same reason — this handler receives a
     // PASSWORD, so the untrusted canvas origin must never be able to reach it.
+    // MANAGED PROJECTS (T21/T22): sign in / open, store the credential and
+    // describe the project, so the native shell can create its own copy.
+    // Main origin only — this mints and stores a credential.
+    '/_api/projects/prepare': async (req: Request) => {
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      if (!sameOriginWrite(req))
+        return new Response('cross-origin write rejected', { status: 403 });
+      if (!isTrustedRequestHost(req))
+        return new Response('local request required', { status: 403 });
+      const body = (await readJson<Record<string, unknown>>(req, 8 * 1024)) ?? {};
+      const kind = body.kind;
+      const str = (v: unknown) => (typeof v === 'string' ? v : '');
+      const input =
+        kind === 'cloud'
+          ? { kind, projectId: str(body.projectId) }
+          : kind === 'handoff'
+            ? { kind, code: str(body.code), claimedProject: str(body.claimedProject) || undefined }
+            : kind === 'hub'
+              ? { kind, url: str(body.url), email: str(body.email), password: str(body.password) }
+              : kind === 'known-hub'
+                ? { kind, url: str(body.url) }
+                : null;
+      if (!input) return new Response('unknown kind', { status: 400 });
+      const r = await prepareManagedProject(
+        ctx,
+        input as Parameters<typeof prepareManagedProject>[1]
+      );
+      return Response.json(r, {
+        status: r.ok ? 200 : r.status,
+        headers: { 'Cache-Control': 'no-store' },
+      });
+    },
     '/_api/workspace/sign-in': async (req: Request) => {
       if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
       if (!sameOriginWrite(req))
@@ -3192,17 +3423,22 @@ export function createHttp(
         value?: unknown;
         reset?: unknown;
         idIndex?: unknown;
+        expected?: unknown;
       }>(req, 8 * 1024);
       if (!body) return new Response('body required', { status: 400 });
       const result = await api.editCss(body);
       if (!result.ok) {
         return Response.json(
-          { ok: false, error: result.error },
+          { ok: false, error: result.error, ...(result.conflict ? { conflict: true } : {}) },
           { status: result.status, headers: { 'Cache-Control': 'no-store' } }
         );
       }
       return Response.json(
-        { ok: true, delta: result.delta },
+        {
+          ok: true,
+          delta: result.delta,
+          ...('previous' in result ? { previous: result.previous } : {}),
+        },
         { status: 200, headers: { 'Cache-Control': 'no-store' } }
       );
     },
@@ -3257,17 +3493,23 @@ export function createHttp(
         attr?: unknown;
         value?: unknown;
         reset?: unknown;
+        expected?: unknown;
       }>(req, 8 * 1024);
       if (!body) return new Response('body required', { status: 400 });
       const result = await api.editAttr(body);
       if (!result.ok) {
         return Response.json(
-          { ok: false, error: result.error },
+          { ok: false, error: result.error, ...(result.conflict ? { conflict: true } : {}) },
           { status: result.status, headers: { 'Cache-Control': 'no-store' } }
         );
       }
       return Response.json(
-        { ok: true, delta: result.delta, seq: result.seq },
+        {
+          ok: true,
+          delta: result.delta,
+          seq: result.seq,
+          ...('previous' in result ? { previous: result.previous } : {}),
+        },
         { status: 200, headers: { 'Cache-Control': 'no-store' } }
       );
     },
@@ -4049,6 +4291,35 @@ export function createHttp(
       );
     },
 
+    '/_api/set-artboard-label': async (req: Request) => {
+      // Plan T25/L08 — rename an artboard. POST { canvas, artboardId, label }
+      // → api.setArtboardLabelOp. The canvas iframe only REQUESTS this over
+      // the dgn bus (double-click the name); the shell writes it. MAIN-ORIGIN
+      // ONLY, same gate pair as set-artboard-kind.
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      if (!sameOriginWrite(req))
+        return new Response('cross-origin write rejected', { status: 403 });
+      if (!isTrustedRequestHost(req))
+        return new Response('local request required (DNS-rebinding guard)', { status: 403 });
+      const body = await readJson<{
+        canvas?: unknown;
+        artboardId?: unknown;
+        label?: unknown;
+      }>(req, 2 * 1024);
+      if (!body) return new Response('body required', { status: 400 });
+      const result = await api.setArtboardLabelOp(body);
+      if (!result.ok) {
+        return Response.json(
+          { ok: false, error: result.error },
+          { status: result.status, headers: { 'Cache-Control': 'no-store' } }
+        );
+      }
+      return Response.json(
+        { ok: true, seq: result.seq },
+        { status: 200, headers: { 'Cache-Control': 'no-store' } }
+      );
+    },
+
     '/_api/set-artboard-guides': async (req: Request) => {
       // feature-1-artboard-kinds-foundation, T5. POST { canvas, artboardId,
       // guides: {...}|null } → api.setArtboardGuidesOp. REPLACE-whole-prop

package/apps/studio/inspect.ts

@@ -114,6 +114,8 @@ export interface Inspect {
    * when the moved canvas wasn't referenced anywhere in this state.
    */
   retarget(fromFile: string, toFile: string): boolean;
+  /** Forget a deleted canvas without moving its selection onto another file. */
+  remove(file: string): boolean;
   save(): Promise<void>;
   injectInspector(html: string): string;
 }
@@ -333,6 +335,22 @@ export function createInspect(
     ctx.bus.emit('selected', state.selected, { session: sessionKey });
   }
 
+  function remove(file: string): boolean {
+    const slug = deriveCanvasSlug(file);
+    const active = state.active === file;
+    const referenced =
+      active || state.open_tabs.includes(file) || Object.hasOwn(state.selections, slug);
+    if (!referenced) return false;
+    // setActive parks the outgoing selection; remove that memory afterwards.
+    if (active) setActive('');
+    state.open_tabs = state.open_tabs.filter((tab) => tab !== file);
+    delete state.selections[slug];
+    if (active) state.active_comments = [];
+    state.last_change = new Date().toISOString();
+    scheduleSave();
+    return true;
+  }
+
   function retarget(fromFile: string, toFile: string): boolean {
     const fromSlug = deriveCanvasSlug(fromFile);
     const toSlug = deriveCanvasSlug(toFile);
@@ -396,6 +414,7 @@ export function createInspect(
     setOpenTabs,
     setSelected,
     retarget,
+    remove,
     save,
     injectInspector,
   };

package/apps/studio/managed-projects.ts

@@ -0,0 +1,150 @@
+// Preparing a MANAGED project — plan T19–T22 (DDR-241 follow-on).
+//
+// A designer who was added to a project should be able to open it without
+// choosing a folder, having Git, or pasting a token. The desktop does that in
+// two halves:
+//
+//   1. HERE (the running studio, which holds the Maude Cloud device session or
+//      takes a team-server sign-in): obtain and store the hub credential, then
+//      ask the project what it looks like (its bootstrap) — name, canvas
+//      groups — so the local copy can be declared correctly before it exists.
+//   2. The native shell (`managed_project_open`) creates the project's own
+//      copy under the app's data directory from exactly what this returns,
+//      and switches to it; the sync runtime then brings everything down.
+//
+// Nothing here writes into the folder this studio is serving.
+
+import { createCloudEndpoints } from './cloud/endpoints.ts';
+import type { Context } from './context.ts';
+import { getHubRecord, normalizeUrl } from './sync/hubs-config.ts';
+import { signInToWorkspace } from './sync/workspace-signin.ts';
+
+export type PrepareInput =
+  | { kind: 'cloud'; projectId: string }
+  | { kind: 'handoff'; code: string; claimedProject?: string }
+  | { kind: 'hub'; url: string; email: string; password: string }
+  /** A team server this machine already holds a credential for. */
+  | { kind: 'known-hub'; url: string };
+
+export interface PreparedProject {
+  ok: true;
+  serverUrl: string;
+  /** Stable id on that server — the managed copy is keyed by (server, id). */
+  projectId: string;
+  name: string;
+  role: string | null;
+  canvasGroups: string[];
+  /** The project's save mode, when the server says ('transactions' | 'legacy'). */
+  mode: string | null;
+}
+
+export type PrepareResult = PreparedProject | { ok: false; error: string; status: number };
+
+const GROUP = /^[\p{L}\p{N}][\p{L}\p{N} _-]{0,59}$/u;
+
+/** Canvas groups a project uses, from its manifest when it does not declare them. */
+export function groupsFromBootstrap(boot: {
+  canvasGroups?: unknown;
+  docs?: { path: string | null; retired?: boolean }[];
+  dirs?: string[];
+}): string[] {
+  const out = new Set<string>();
+  const add = (g: unknown) => {
+    if (typeof g === 'string' && GROUP.test(g)) out.add(g);
+  };
+  if (Array.isArray(boot.canvasGroups)) {
+    for (const g of boot.canvasGroups)
+      add(typeof g === 'string' ? g : (g as { path?: unknown })?.path);
+  }
+  for (const d of boot.docs ?? []) {
+    if (d.retired || !d.path) continue;
+    const first = d.path.split('/')[0];
+    if (d.path.includes('/')) add(first);
+  }
+  for (const dir of boot.dirs ?? []) add(dir.split('/')[0]);
+  if (out.size === 0) {
+    out.add('system');
+    out.add('ui');
+  }
+  return [...out].slice(0, 32);
+}
+
+async function bootstrapOf(url: string, token: string): Promise<Record<string, unknown> | null> {
+  try {
+    const res = await fetch(`${url}/api/projects/current/v1/bootstrap`, {
+      headers: { authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) return null;
+    return (await res.json()) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+export async function prepareManagedProject(
+  ctx: Context,
+  input: PrepareInput
+): Promise<PrepareResult> {
+  let serverUrl: string;
+  let projectId: string | null = null;
+  let role: string | null = null;
+  let name: string | null = null;
+
+  if (input.kind === 'cloud' || input.kind === 'handoff') {
+    const cloud = createCloudEndpoints(ctx);
+    const r =
+      input.kind === 'cloud'
+        ? await cloud.openManaged(input.projectId)
+        : await cloud.openManagedCode(input.code, input.claimedProject);
+    const j = r.json as {
+      ok?: boolean;
+      url?: string;
+      role?: string;
+      project?: string;
+      error?: string;
+    };
+    if (!j.ok || !j.url)
+      return { ok: false, error: j.error ?? 'The project could not be opened.', status: r.status };
+    serverUrl = j.url;
+    projectId = j.project ?? (input.kind === 'cloud' ? input.projectId : null);
+    role = j.role ?? null;
+    name = projectId;
+  } else if (input.kind === 'hub') {
+    const r = await signInToWorkspace({
+      url: input.url,
+      email: input.email,
+      password: input.password,
+    });
+    if (!r.json.ok) return { ok: false, error: r.json.error, status: r.status };
+    serverUrl = r.json.url;
+    role = r.json.user.role;
+  } else {
+    try {
+      serverUrl = normalizeUrl(input.url);
+    } catch {
+      return { ok: false, error: "That doesn't look like a workspace address.", status: 400 };
+    }
+    if (!getHubRecord(serverUrl)?.token) {
+      return { ok: false, error: 'Sign in to that workspace first.', status: 401 };
+    }
+  }
+
+  const token = getHubRecord(serverUrl)?.token;
+  if (!token)
+    return { ok: false, error: 'The sign-in could not be saved on this computer.', status: 500 };
+  const boot = await bootstrapOf(serverUrl, token);
+  if (boot && typeof boot.projectId === 'string') projectId ??= boot.projectId;
+  const host = new URL(serverUrl).host;
+  projectId ??= host;
+  if (!/^[A-Za-z0-9._-]{1,128}$/.test(projectId)) projectId = host.replace(/[^A-Za-z0-9._-]/g, '-');
+  return {
+    ok: true,
+    serverUrl,
+    projectId,
+    name: name ?? (projectId === 'local' ? host : projectId),
+    role,
+    canvasGroups: groupsFromBootstrap((boot ?? {}) as Parameters<typeof groupsFromBootstrap>[0]),
+    mode: boot && typeof boot.mode === 'string' ? boot.mode : null,
+  };
+}