@1agh/maude 0.48.0 → 0.49.0

package/apps/studio/test/sync-doc-name.test.ts

@@ -0,0 +1,281 @@
+// DDR-192 §5 — the `ws/<workspace-id>/<branch>/<slug>` document namespace,
+// client side: resolution (where the workspace id and branch come from), the
+// opt-in rollout rule, conformance with the hub's independent implementation,
+// and the DDR-076 fresh-doc case that makes changing doc identity safe.
+
+import { describe, expect, test } from 'bun:test';
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+// The HUB's implementation, imported across the package boundary on purpose —
+// this file is what pins the two grammars to each other (see doc-name.ts).
+import * as hub from '../../hub/src/doc-namespace.mjs';
+import { decideColdStart } from '../sync/cold-start.ts';
+import {
+  buildDocName,
+  createDocNameResolver,
+  isNamespaced,
+  parseDocName,
+  readBranch,
+  readOriginUrl,
+  resolveWorkspaceId,
+  sanitizeComponent,
+  workspaceIdFromRemote,
+} from '../sync/doc-name.ts';
+
+/** A throwaway repo skeleton: `.git/HEAD` + optionally `.git/config`. */
+function makeRepo(opts: { head?: string; origin?: string } = {}): string {
+  const root = mkdtempSync(path.join(tmpdir(), 'maude-docname-'));
+  mkdirSync(path.join(root, '.git'), { recursive: true });
+  writeFileSync(path.join(root, '.git', 'HEAD'), opts.head ?? 'ref: refs/heads/main\n');
+  if (opts.origin) {
+    writeFileSync(
+      path.join(root, '.git', 'config'),
+      `[core]\n\trepositoryformatversion = 0\n[remote "origin"]\n\turl = ${opts.origin}\n\tfetch = +refs/heads/*:refs/remotes/origin/*\n[branch "main"]\n\tremote = origin\n`
+    );
+  }
+  return root;
+}
+
+describe('doc-name — resolution inputs', () => {
+  test('readBranch reads a branch, a slash-branch, and a detached HEAD', () => {
+    const a = makeRepo({ head: 'ref: refs/heads/main\n' });
+    const b = makeRepo({ head: 'ref: refs/heads/feature/cloud-arc\n' });
+    const c = makeRepo({ head: '9f1c0a2b3c4d5e6f708192a3b4c5d6e7f8091a2b\n' });
+    const none = mkdtempSync(path.join(tmpdir(), 'maude-nogit-'));
+    try {
+      expect(readBranch(a)).toBe('main');
+      expect(readBranch(b)).toBe('feature/cloud-arc');
+      // A detached HEAD gets a STABLE name for that commit, so two peers
+      // detached at the same commit meet and neither joins a branch's doc.
+      expect(readBranch(c)).toBe('detached-9f1c0a2');
+      expect(readBranch(none)).toBe(null);
+    } finally {
+      for (const d of [a, b, c, none]) rmSync(d, { recursive: true, force: true });
+    }
+  });
+
+  test('readOriginUrl picks origin out of .git/config, ignoring other remotes', () => {
+    const root = makeRepo({ origin: 'git@github.com:1aGh/maude.git' });
+    try {
+      expect(readOriginUrl(root)).toBe('git@github.com:1aGh/maude.git');
+      writeFileSync(
+        path.join(root, '.git', 'config'),
+        '[remote "upstream"]\n\turl = https://example.com/x/y.git\n'
+      );
+      expect(readOriginUrl(root)).toBe(null);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('the same project cloned different ways yields the SAME workspace id', () => {
+    // This is the property that decides whether two peers meet at all. If SSH
+    // and HTTPS clones of one repo derived different ids, each peer would see
+    // the other's documents as simply absent.
+    const forms = [
+      'git@github.com:1aGh/maude.git',
+      'https://github.com/1aGh/maude.git',
+      'https://github.com/1aGh/maude',
+      'ssh://git@github.com/1aGh/maude.git',
+      'https://user:tok@github.com/1aGh/maude.git',
+    ];
+    const ids = new Set(forms.map(workspaceIdFromRemote));
+    expect([...ids]).toEqual(['1agh-maude']);
+  });
+
+  test('different projects yield different workspace ids', () => {
+    expect(workspaceIdFromRemote('git@github.com:1aGh/maude.git')).not.toBe(
+      workspaceIdFromRemote('git@github.com:1aGh/dugmate.git')
+    );
+    expect(workspaceIdFromRemote('git@github.com:acme/site.git')).not.toBe(
+      workspaceIdFromRemote('git@gitlab.com:other/site.git')
+    );
+  });
+
+  test('resolveWorkspaceId prefers explicit config, then origin, then nothing', () => {
+    const withOrigin = makeRepo({ origin: 'git@github.com:acme/site.git' });
+    const noOrigin = makeRepo();
+    try {
+      expect(resolveWorkspaceId({ explicit: 'cloud-abc123', repoRoot: withOrigin })).toBe(
+        'cloud-abc123'
+      );
+      expect(resolveWorkspaceId({ repoRoot: withOrigin })).toBe('acme-site');
+      // No origin and no config: null. NOT a directory-name fallback — a local
+      // path differs per machine, so deriving from it would split peers apart.
+      expect(resolveWorkspaceId({ repoRoot: noOrigin })).toBe(null);
+    } finally {
+      rmSync(withOrigin, { recursive: true, force: true });
+      rmSync(noOrigin, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('doc-name — the rollout rule', () => {
+  test('unset flag + no explicit workspace id ⇒ flat (an upgrade changes nothing)', () => {
+    const root = makeRepo({ origin: 'git@github.com:acme/site.git' });
+    try {
+      const resolve = createDocNameResolver({ repoRoot: root });
+      expect(resolve('ui-screen')).toBe('ui-screen');
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('an explicitly declared workspace id opts in', () => {
+    const root = makeRepo({ origin: 'git@github.com:acme/site.git' });
+    try {
+      const resolve = createDocNameResolver({ repoRoot: root, explicitWorkspaceId: 'acme-site' });
+      expect(resolve('ui-screen')).toBe('ws/acme-site/main/ui-screen');
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('MAUDE_HUB_NAMESPACED=0 forces flat even with an explicit id', () => {
+    const root = makeRepo({ origin: 'git@github.com:acme/site.git' });
+    try {
+      const resolve = createDocNameResolver({
+        repoRoot: root,
+        explicitWorkspaceId: 'acme-site',
+        flag: '0',
+      });
+      expect(resolve('ui-screen')).toBe('ui-screen');
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('MAUDE_HUB_NAMESPACED=1 namespaces from the origin remote', () => {
+    const root = makeRepo({
+      origin: 'git@github.com:acme/site.git',
+      head: 'ref: refs/heads/dev\n',
+    });
+    try {
+      const resolve = createDocNameResolver({ repoRoot: root, flag: '1' });
+      expect(resolve('ui-screen')).toBe('ws/acme-site/dev/ui-screen');
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('MAUDE_HUB_NAMESPACED=1 with nothing to derive from THROWS, never falls back', () => {
+    // A silent fallback here would put a project the operator asked to isolate
+    // into the shared flat namespace — the failure mode is worse than a crash.
+    const noOrigin = makeRepo();
+    const noGit = mkdtempSync(path.join(tmpdir(), 'maude-nogit-'));
+    try {
+      expect(() => createDocNameResolver({ repoRoot: noOrigin, flag: '1' })).toThrow(
+        /workspace id/i
+      );
+      expect(() =>
+        createDocNameResolver({ repoRoot: noGit, flag: '1', explicitWorkspaceId: 'acme' })
+      ).toThrow(/branch/i);
+    } finally {
+      rmSync(noOrigin, { recursive: true, force: true });
+      rmSync(noGit, { recursive: true, force: true });
+    }
+  });
+
+  test('a branch with a slash is normalized, not rejected', () => {
+    const root = makeRepo({ head: 'ref: refs/heads/feature/cloud-arc\n' });
+    try {
+      const resolve = createDocNameResolver({ repoRoot: root, explicitWorkspaceId: 'acme' });
+      expect(resolve('ui-screen')).toBe('ws/acme/feature-cloud-arc/ui-screen');
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('doc-name — conformance with the hub implementation', () => {
+  const components = [
+    'main',
+    'feature/cloud-arc',
+    'Release/2026.07',
+    '  --weird--  ',
+    '...',
+    '',
+    'x'.repeat(200),
+    'ui-screen',
+    'a/b/c',
+  ];
+
+  test('sanitizeComponent agrees byte-for-byte', () => {
+    for (const c of components) {
+      expect(sanitizeComponent(c)).toBe(hub.sanitizeComponent(c));
+    }
+  });
+
+  test('buildDocName agrees, including which inputs throw', () => {
+    for (const w of components) {
+      for (const b of ['main', '...']) {
+        const args = { workspaceId: w, branch: b, slug: 'ui-screen' };
+        let mine: string | Error;
+        let theirs: string | Error;
+        try {
+          mine = buildDocName(args);
+        } catch (e) {
+          mine = e as Error;
+        }
+        try {
+          theirs = hub.buildDocName(args);
+        } catch (e) {
+          theirs = e as Error;
+        }
+        if (mine instanceof Error || theirs instanceof Error) {
+          expect(mine instanceof Error).toBe(theirs instanceof Error);
+        } else {
+          expect(mine).toBe(theirs);
+        }
+      }
+    }
+  });
+
+  test('parseDocName agrees over namespaced, legacy, and malformed names', () => {
+    const names = [
+      'ws/acme/main/ui-screen',
+      'ui-screen',
+      '',
+      'ws/acme/main',
+      'ws/acme/main/a/b',
+      'x/acme/main/ui',
+      'ws//main/ui',
+      'ws/acme//ui',
+    ];
+    for (const n of names) {
+      expect(parseDocName(n)).toEqual(hub.parseDocName(n));
+      expect(isNamespaced(n)).toBe(hub.isNamespaced(n));
+    }
+  });
+});
+
+describe('doc-name — changing identity is safe (DDR-076)', () => {
+  test('a freshly namespaced doc is EMPTY, and empty never clobbers local files', () => {
+    const root = makeRepo({ origin: 'git@github.com:acme/site.git' });
+    try {
+      // The rename itself: the same canvas addressed under a new identity.
+      const flat = createDocNameResolver({ repoRoot: root });
+      const namespaced = createDocNameResolver({ repoRoot: root, flag: '1' });
+      expect(flat('ui-screen')).toBe('ui-screen');
+      expect(namespaced('ui-screen')).toBe('ws/acme-site/main/ui-screen');
+      expect(namespaced('ui-screen')).not.toBe(flat('ui-screen'));
+
+      // Consequence: on first connect the hub has nothing under the new name.
+      // DDR-076 — that means "not seeded yet", never "authoritatively blank".
+      const decision = decideColdStart({
+        localBody: '<main>real local work</main>',
+        docBody: '',
+        journalHash: null,
+        localMtimeMs: Date.now(),
+        docBodyEditAtMs: null,
+      });
+      expect(decision.action).toBe('seed-local-up');
+      expect(decision.winner).toBeUndefined();
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/apps/studio/test/workspace-containment.test.ts

@@ -0,0 +1,258 @@
+// Cloud Phase 3 — the containment invariant's boot-assert (DDR-193 §2).
+//
+//   > No tenant-authored TSX is ever evaluated by vendor-operated compute.
+//
+// The thing being tested is a REFUSAL. So the tests that matter are the ones
+// that prove the gate fires: a cell exposing an export route, a canvas shell, a
+// runtime bundle, or shipping Playwright must not be able to start.
+//
+// The negative case matters just as much: none of this may fire outside
+// workspace mode, or every local dev-server stops booting.
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  assertContainment,
+  checkContainment,
+  FORBIDDEN_MODULES,
+  FORBIDDEN_ROUTE_PREFIXES,
+  formatContainmentFailure,
+  isForbiddenRoute,
+  isWorkspaceMode,
+  pruneForWorkspace,
+} from '../workspace-mode.ts';
+
+const CELL = { MAUDE_WORKSPACE_MODE: '1' } as NodeJS.ProcessEnv;
+const LAPTOP = {} as NodeJS.ProcessEnv;
+
+/** The routes a cell legitimately serves: sync + git + assets, nothing else. */
+const ALLOWED_ROUTES = [
+  '/_health',
+  '/_api/asset',
+  '/_api/comments',
+  '/_api/annotations',
+  '/_api/git-committers',
+  '/_config',
+  '/_ws',
+];
+
+describe('workspace mode detection', () => {
+  test('only MAUDE_WORKSPACE_MODE=1 turns it on', () => {
+    expect(isWorkspaceMode(CELL)).toBe(true);
+    expect(isWorkspaceMode(LAPTOP)).toBe(false);
+    expect(isWorkspaceMode({ MAUDE_WORKSPACE_MODE: 'true' })).toBe(false);
+    expect(isWorkspaceMode({ MAUDE_WORKSPACE_MODE: '0' })).toBe(false);
+    expect(isWorkspaceMode({ MAUDE_WORKSPACE_MODE: '' })).toBe(false);
+  });
+});
+
+describe('checkContainment — what a cell may serve', () => {
+  test('sync + git + asset routes pass', () => {
+    const report = checkContainment(ALLOWED_ROUTES);
+    expect(report.ok).toBe(true);
+    expect(report.routes).toEqual([]);
+    expect(report.modules).toEqual([]);
+  });
+
+  test('every forbidden prefix is caught, and the reason travels with it', () => {
+    for (const { prefix, why } of FORBIDDEN_ROUTE_PREFIXES) {
+      const report = checkContainment([...ALLOWED_ROUTES, prefix]);
+      expect(report.ok).toBe(false);
+      expect(report.routes).toHaveLength(1);
+      expect(report.routes[0]?.prefix).toBe(prefix);
+      // The message has to teach, not just refuse — this is read by someone who
+      // added a route in 2027 and has never heard of this invariant.
+      expect(report.routes[0]?.why).toBe(why);
+      expect(why.length).toBeGreaterThan(20);
+    }
+  });
+
+  test('a VARIANT of a forbidden route is still forbidden', () => {
+    // The realistic way this gets reintroduced: not `/_api/export` verbatim, but
+    // a sibling that does the same thing under a new name.
+    for (const route of [
+      '/_api/export-jobs',
+      '/_api/export/png',
+      '/_canvas-shell.html',
+      '/_canvas-runtime/react.js',
+      '/_ws/acp',
+    ]) {
+      const report = checkContainment([...ALLOWED_ROUTES, route]);
+      expect(report.ok).toBe(false);
+      expect(report.routes[0]?.route).toBe(route);
+    }
+  });
+
+  test('a route that merely CONTAINS a forbidden word is not a false positive', () => {
+    // Prefix matching, not substring — `/_api/asset` must not trip on nothing,
+    // and a route about exports in its docs must not be blocked by name alone.
+    const report = checkContainment([
+      '/_api/asset',
+      '/_api/export-history-docs-link',
+      '/_api/no-export',
+      '/_api/git-export-status',
+    ]);
+    expect(report.routes.map((r) => r.route)).toEqual(['/_api/export-history-docs-link']);
+    // ...that one DOES start with /_api/export, and being caught is correct:
+    // a surface named "export-*" is exactly what needs a human to look at it.
+  });
+
+  test('a resolvable browser automation module fails the check', () => {
+    const report = checkContainment(ALLOWED_ROUTES, {
+      resolveModule: (s) => s === 'playwright',
+    });
+    expect(report.ok).toBe(false);
+    expect(report.modules).toEqual(['playwright']);
+    // All four are checked, not just the popular one.
+    const all = checkContainment(ALLOWED_ROUTES, { resolveModule: () => true });
+    expect(all.modules).toEqual([...FORBIDDEN_MODULES]);
+  });
+
+  test('no resolver supplied ⇒ modules are simply not checked (not silently passed)', () => {
+    const report = checkContainment(ALLOWED_ROUTES);
+    expect(report.modules).toEqual([]);
+  });
+});
+
+describe('assertContainment — the boot gate', () => {
+  test('OUTSIDE workspace mode it never fires, whatever is exposed', () => {
+    // A developer's laptop serves every one of these. If the gate fired here,
+    // the entire local product would stop booting.
+    expect(() =>
+      assertContainment([...ALLOWED_ROUTES, ...FORBIDDEN_ROUTE_PREFIXES.map((f) => f.prefix)], {
+        env: LAPTOP,
+        resolveModule: () => true,
+      })
+    ).not.toThrow();
+  });
+
+  test('in a cell, a clean route table starts', () => {
+    expect(() => assertContainment(ALLOWED_ROUTES, { env: CELL })).not.toThrow();
+  });
+
+  test('in a cell, an export route REFUSES TO START', () => {
+    expect(() => assertContainment([...ALLOWED_ROUTES, '/_api/export'], { env: CELL })).toThrow(
+      /REFUSING TO START/
+    );
+  });
+
+  test('in a cell, shipping Playwright REFUSES TO START even with clean routes', () => {
+    expect(() =>
+      assertContainment(ALLOWED_ROUTES, { env: CELL, resolveModule: (s) => s === 'playwright' })
+    ).toThrow(/playwright/);
+  });
+
+  test('the failure message names the surface, the reason, and the way out', () => {
+    let message = '';
+    try {
+      assertContainment([...ALLOWED_ROUTES, '/_canvas-shell.html'], { env: CELL });
+    } catch (err) {
+      message = (err as Error).message;
+    }
+    expect(message).toContain('/_canvas-shell.html');
+    expect(message).toContain('DDR-193');
+    expect(message).toContain('executes a canvas module');
+    // The escape hatch is named so the next engineer doesn't invent a flag.
+    expect(message).toContain('Direction B');
+    expect(message).toContain('HARD PREREQUISITE');
+  });
+
+  test('formatContainmentFailure reports routes and modules together', () => {
+    const report = checkContainment([...ALLOWED_ROUTES, '/_api/export'], {
+      resolveModule: (s) => s === 'puppeteer',
+    });
+    const message = formatContainmentFailure(report);
+    expect(message).toContain('/_api/export');
+    expect(message).toContain('puppeteer');
+    expect(message).toContain('Reachable routes');
+    expect(message).toContain('Modules that resolve');
+  });
+});
+
+describe('the vocabulary itself', () => {
+  test('the forbidden set covers every way a cell could evaluate tenant code', () => {
+    // Pinned deliberately: the realistic loss of this invariant is a refactor
+    // quietly dropping an entry while every other test stays green. Changing
+    // this list should require changing this test, on purpose.
+    expect(FORBIDDEN_ROUTE_PREFIXES.map((f) => f.prefix).sort()).toEqual([
+      '/_api/export',
+      '/_api/generate',
+      '/_api/photo-edit',
+      '/_canvas-runtime',
+      '/_canvas-shell',
+      '/_ws/acp',
+    ]);
+    expect([...FORBIDDEN_MODULES].sort()).toEqual([
+      'playwright',
+      'playwright-core',
+      'puppeteer',
+      'puppeteer-core',
+    ]);
+  });
+});
+
+describe('pruneForWorkspace — how a cell can boot at all', () => {
+  test('keeps the sync/git/asset surface and removes exactly the forbidden one', () => {
+    const table = {
+      '/_health': 'h',
+      '/_api/asset': 'a',
+      '/_api/comments': 'c',
+      '/_api/git-committers': 'g',
+      '/_api/export': 'x',
+      '/_api/export-jobs': 'x2',
+      '/_api/photo-edit': 'p',
+      '/_api/generate/keys': 'k',
+    };
+    const { routes, removed } = pruneForWorkspace(table);
+
+    expect(Object.keys(routes).sort()).toEqual([
+      '/_api/asset',
+      '/_api/comments',
+      '/_api/git-committers',
+      '/_health',
+    ]);
+    expect(removed).toEqual([
+      '/_api/export',
+      '/_api/export-jobs',
+      '/_api/generate/keys',
+      '/_api/photo-edit',
+    ]);
+    // Handlers are carried through by reference — pruning must not rebuild them.
+    expect(routes['/_api/asset']).toBe('a');
+  });
+
+  test('the pruned table then PASSES the boot assert — prune and assert agree', () => {
+    // This is the whole design: the assert is a post-condition on the pruning,
+    // so a prefix added to the vocabulary both prunes and is verified, and the
+    // two can never drift into disagreeing.
+    const table = Object.fromEntries(
+      [...FORBIDDEN_ROUTE_PREFIXES.map((f) => f.prefix), '/_health', '/_api/asset'].map((r) => [
+        r,
+        () => {},
+      ])
+    );
+    const { routes } = pruneForWorkspace(table);
+    expect(() => assertContainment(Object.keys(routes), { env: CELL })).not.toThrow();
+    // ...and the unpruned table would have refused.
+    expect(() => assertContainment(Object.keys(table), { env: CELL })).toThrow(/REFUSING TO START/);
+  });
+
+  test('pruning an already-clean table is a no-op', () => {
+    const table = Object.fromEntries(ALLOWED_ROUTES.map((r) => [r, () => {}]));
+    const { routes, removed } = pruneForWorkspace(table);
+    expect(removed).toEqual([]);
+    expect(Object.keys(routes).sort()).toEqual([...ALLOWED_ROUTES].sort());
+  });
+
+  test('isForbiddenRoute is the single predicate both the table and fetch use', () => {
+    // The `fetch` fall-through owns paths that are not in the route table
+    // (/_ws/acp, /_canvas-shell.html, /_canvas-runtime/*), so it gates on this
+    // same function. One predicate, so the two gates cannot disagree.
+    expect(isForbiddenRoute('/_canvas-shell.html')).toBe(true);
+    expect(isForbiddenRoute('/_canvas-runtime/react.js')).toBe(true);
+    expect(isForbiddenRoute('/_ws/acp')).toBe(true);
+    expect(isForbiddenRoute('/_ws')).toBe(false);
+    expect(isForbiddenRoute('/_health')).toBe(false);
+    expect(isForbiddenRoute('/_api/asset')).toBe(false);
+  });
+});