@bevel-software/platform-core-backend 0.25.2 → 0.27.0

package/src/modules/workspace/__tests__/escape-sequences.routes.test.ts

@@ -21,7 +21,8 @@ import type { IAccessControl } from '../../access/access-control.interface.js';
 import { createMcpRoutes } from '../../mcp/mcp.routes.js';
 import { McpService } from '../../mcp/mcp.service.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
-import { sharedFileRules, sharedFileRulesSection, sharedRulesPointer } from '../../agent-instructions/shared-file-rules.js';
+import { sharedFileRules, sharedFileRulesSection } from '../../agent-instructions/shared-file-rules.js';
+import { GUIDE_FIRST_SENTENCE } from '../../tool-registry/guide-first.js';
 
 /**
  * Who decodes escape sequences in written content a second time — settled on
@@ -386,9 +387,9 @@ describe('what the write tools tell an agent about escape sequences', () => {
       .filter(([, d]) => d.includes('decode escape sequences in arguments before sending') || d.includes('some clients decode them in arguments'))
       .map(([n]) => n);
     expect(carrying).toEqual([]);
-    // Each of the three still points at where the warning is.
+    // Each of the three still opens by sending the agent to the guide, where the warning is.
     for (const name of ['write_file', 'write_files', 'edit_file']) {
-      expect(served[name], name).toContain(sharedRulesPointer(testKbContext().layout).trim());
+      expect(served[name]!.startsWith(GUIDE_FIRST_SENTENCE), name).toBe(true);
     }
   });
 });

package/src/modules/workspace/__tests__/first-run.test.ts

@@ -0,0 +1,234 @@
+import { mkdir, mkdtemp, rm, stat, symlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
+import { defaultKbTemplateDir } from '../../../assets.js';
+import { agentGuideSections } from '../../agent-guide/index.js';
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import {
+  FIRST_RUN_SECTION_ID,
+  FOLDER_BUDGET,
+  STARTER_GUIDE_FILE,
+  firstRunNote,
+  knowledgeFolderIsNew,
+  type MayRead,
+} from '../first-run.js';
+
+/**
+ * What makes a knowledge base "new" for the `firstRun` note: nothing in its
+ * knowledge folder but the starter guide the template seeds. Pinned here on a
+ * real checkout; the route that returns the note is exercised in
+ * workspace.tools.test.ts.
+ */
+describe('knowledgeFolderIsNew', () => {
+  const disk = new NodeFs();
+  const KNOWLEDGE = 'KnowledgeBase';
+  /** The checkout, and its knowledge folder. */
+  let repo = '';
+  let dir = '';
+  const isNew = (starter?: ReadonlyMap<string, string>, mayRead?: MayRead) =>
+    knowledgeFolderIsNew(disk, repo, KNOWLEDGE, starter, mayRead);
+  const everyone: MayRead = async (rels) => new Map(rels.map((rel) => [rel, true]));
+
+  beforeEach(async () => {
+    repo = await mkdtemp(join(tmpdir(), 'bevel-first-run-unit-'));
+    dir = join(repo, KNOWLEDGE);
+    await mkdir(dir);
+    await writeFile(join(dir, STARTER_GUIDE_FILE), '# How to get started\n');
+  });
+
+  afterEach(async () => {
+    await rm(repo, { recursive: true, force: true });
+  });
+
+  it('is new with only the starter guide', async () => {
+    expect(await isNew()).toBe(true);
+  });
+
+  it('is new with nothing at all: a starter guide someone deleted leaves an empty knowledge base', async () => {
+    await rm(join(dir, STARTER_GUIDE_FILE));
+    expect(await isNew()).toBe(true);
+  });
+
+  it('passes over empty folders, their placeholders, dot-files and access rules', async () => {
+    await mkdir(join(dir, 'Customers', 'Archive'), { recursive: true });
+    await writeFile(join(dir, 'Customers', '.gitkeep'), '');
+    await writeFile(join(dir, 'Customers', 'access.md'), '# Access\n');
+    await writeFile(join(dir, '.DS_Store'), '');
+    expect(await isNew()).toBe(true);
+  });
+
+  it('is not new once a page sits beside the starter guide', async () => {
+    await writeFile(join(dir, 'Glossary.md'), '# Glossary\n');
+    expect(await isNew()).toBe(false);
+  });
+
+  it('is not new once a page sits in a folder, of any kind', async () => {
+    await mkdir(join(dir, 'Products'), { recursive: true });
+    await writeFile(join(dir, 'Products', 'Pricing.pdf'), 'bytes');
+    expect(await isNew()).toBe(false);
+  });
+
+  it('counts a file named like the starter guide below the top as a page', async () => {
+    await mkdir(join(dir, 'Team'), { recursive: true });
+    await writeFile(join(dir, 'Team', STARTER_GUIDE_FILE), '# Our own onboarding\n');
+    expect(await isNew()).toBe(false);
+  });
+
+  it('is not new when the folder is not there: a shape the template never made is not greeted', async () => {
+    expect(await knowledgeFolderIsNew(disk, repo, 'missing')).toBe(false);
+  });
+
+  it('passes over a starter pack page that still holds what the pack wrote, line endings aside', async () => {
+    await mkdir(join(dir, 'Team'), { recursive: true });
+    await writeFile(join(dir, 'About us.md'), '# About us\r\n\r\nAsk your agent: _Draft this_\r\n');
+    await writeFile(join(dir, 'Team', 'Glossary.md'), '# Glossary\n');
+    const starter = new Map([
+      ['About us.md', '# About us\n\nAsk your agent: _Draft this_\n'],
+      ['Team/Glossary.md', '# Glossary\n'],
+    ]);
+    expect(await isNew(starter)).toBe(true);
+    // The same pages count without the pack to recognise them by.
+    expect(await isNew()).toBe(false);
+  });
+
+  it('is not new once someone fills a starter page in', async () => {
+    await writeFile(join(dir, 'About us.md'), '# About us\n\nWe make bicycles.\n');
+    expect(await isNew(new Map([['About us.md', '# About us\n']]))).toBe(false);
+  });
+
+  it('sees what the explorer sees: a page a `.bevelignore` hides, in the folder or at the repository root, is not there', async () => {
+    await mkdir(join(dir, 'Drafts'), { recursive: true });
+    await writeFile(join(dir, 'Drafts', 'Plan.md'), '# Plan\n');
+    await writeFile(join(dir, '.bevelignore'), 'Drafts/\n');
+    expect(await isNew()).toBe(true);
+    // The rules above the folder apply on the way down as well.
+    await rm(join(dir, '.bevelignore'));
+    expect(await isNew()).toBe(false);
+    await writeFile(join(repo, '.bevelignore'), 'Drafts/\n');
+    expect(await isNew()).toBe(true);
+    // A knowledge folder the root's rules hide is one the explorer never enters: not greeted.
+    await writeFile(join(repo, '.bevelignore'), `${KNOWLEDGE}/\n`);
+    expect(await isNew()).toBe(false);
+  });
+
+  it("answers for the caller when asked to: a page they may not read does not make the folder old for them", async () => {
+    await mkdir(join(dir, 'Leadership'), { recursive: true });
+    await writeFile(join(dir, 'Leadership', 'Plan.md'), '# Plan\n');
+    const seen: string[][] = [];
+    const nobody: MayRead = async (rels) => {
+      seen.push(rels);
+      return new Map(rels.map((rel) => [rel, false]));
+    };
+    expect(await isNew(undefined, nobody)).toBe(true);
+    // Asked about the page, and only the page: folders are entered, not judged.
+    expect(seen).toEqual([['Leadership/Plan.md']]);
+
+    expect(await isNew(undefined, everyone)).toBe(false);
+    // Without anyone to ask, a page is a page.
+    expect(await isNew()).toBe(false);
+  });
+
+  it("enters every folder, as the agent's listing shows every folder: a page a deeper rule opens counts", async () => {
+    await mkdir(join(dir, 'Leadership', 'Shared'), { recursive: true });
+    await writeFile(join(dir, 'Leadership', 'Plan.md'), '# Plan\n');
+    await writeFile(join(dir, 'Leadership', 'Shared', 'Note.md'), '# Note\n');
+    const asked: string[][] = [];
+    const sharedOnly: MayRead = async (rels) => {
+      asked.push(rels);
+      return new Map(rels.map((rel) => [rel, rel === 'Leadership/Shared/Note.md']));
+    };
+    expect(await isNew(undefined, sharedOnly)).toBe(false);
+    // Each folder's pages in turn; the readable one ends the walk.
+    expect(asked).toEqual([['Leadership/Plan.md'], ['Leadership/Shared/Note.md']]);
+  });
+
+  it('counts nothing the caller may not read, however much of it there is', async () => {
+    const many = 1001;
+    await Promise.all(Array.from({ length: many }, (_, i) => writeFile(join(dir, `Secret-${i}.md`), '# Secret\n')));
+    const asked: number[] = [];
+    const nobody: MayRead = async (rels) => {
+      asked.push(rels.length);
+      return new Map(rels.map((rel) => [rel, false]));
+    };
+    expect(await isNew(undefined, nobody)).toBe(true);
+    // Judged in chunks, every one of them.
+    expect(asked.reduce((n, k) => n + k, 0)).toBe(many);
+    expect(Math.max(...asked)).toBeLessThanOrEqual(200);
+    // One the caller may read, anywhere among them, and the folder is old.
+    const justOne: MayRead = async (rels) => new Map(rels.map((rel) => [rel, rel === `Secret-${many - 1}.md`]));
+    expect(await isNew(undefined, justOne)).toBe(false);
+  });
+
+  it('stops at its folder budget: that many folders and no page is not a new knowledge base', async () => {
+    // The knowledge folder itself counts, so this many below it is one over.
+    await Promise.all(Array.from({ length: FOLDER_BUDGET }, (_, i) => mkdir(join(dir, `Team-${i}`), { recursive: true })));
+    expect(await isNew()).toBe(false);
+    // Nobody is asked about a folder: with no page in sight the budget alone answers.
+    const asked: string[][] = [];
+    const nobody: MayRead = async (rels) => {
+      asked.push(rels);
+      return new Map(rels.map((rel) => [rel, false]));
+    };
+    expect(await isNew(undefined, nobody)).toBe(false);
+    expect(asked).toEqual([]);
+    // One fewer, and the walk lists them all.
+    await rm(join(dir, 'Team-0'), { recursive: true });
+    expect(await isNew()).toBe(true);
+  });
+
+  it('passes a link over by kind: not a page, never read through, never asked about', async () => {
+    try {
+      await symlink(join(tmpdir(), 'elsewhere.md'), join(dir, 'Alias.md'));
+    } catch {
+      return; // no symlinks on this machine: nothing to pass over
+    }
+    const asked: string[][] = [];
+    const everyoneAsked: MayRead = async (rels) => {
+      asked.push(rels);
+      return new Map(rels.map((rel) => [rel, true]));
+    };
+    expect(await isNew(undefined, everyoneAsked)).toBe(true);
+    expect(asked).toEqual([]);
+    expect(await isNew()).toBe(true);
+  });
+});
+
+describe('the firstRun note', () => {
+  it('names the starter guide the template really seeds', async () => {
+    const seeded = await stat(join(defaultKbTemplateDir(), 'KnowledgeBase', STARTER_GUIDE_FILE));
+    expect(seeded.isFile()).toBe(true);
+  });
+
+  it('points at a section the guide has, which says what to do', async () => {
+    const sections = await agentGuideSections(DEFAULT_KB_LAYOUT, undefined, { kbDirName: 'kb-checkout' });
+    const section = sections.find((s) => s.id === FIRST_RUN_SECTION_ID);
+    expect(section, `the guide has no "${FIRST_RUN_SECTION_ID}" section`).toBeDefined();
+    expect(section!.body).toContain('`firstRun`');
+    // The folder spelled as the note spells it: the checkout-prefixed form the file tools report.
+    const folder = `kb-checkout/${DEFAULT_KB_LAYOUT.knowledgeBaseDir}`;
+    expect(section!.body).toContain(`\`${folder}/\``);
+    expect(firstRunNote(folder)).toContain(`\`${folder}/\``);
+    expect(section!.body).toMatch(/once per conversation/i);
+  });
+
+  it('says what to offer and that the person\'s own request comes first', () => {
+    const note = firstRunNote('knowledge-base/KnowledgeBase');
+    expect(note).toContain('`knowledge-base/KnowledgeBase/`');
+    // True whether the starter guide is still there or someone deleted it.
+    expect(note).toContain('has no pages yet');
+    expect(note).toMatch(/offer to draft/);
+    expect(note).toMatch(/answer that first/);
+    expect(note).toContain(`\`${FIRST_RUN_SECTION_ID}\``);
+  });
+
+  it("after a starter pack, names the team's pages and says they are placeholders", () => {
+    const note = firstRunNote('knowledge-base/KnowledgeBase', { name: 'Sales', suggestedPages: ['About us', 'Customers'] });
+    expect(note).toContain('the Sales starter pages');
+    expect(note).toMatch(/placeholders/);
+    expect(note).toContain('offer to draft its first pages (About us, Customers)');
+    expect(note).toMatch(/answer that first/);
+    expect(note).toContain(`\`${FIRST_RUN_SECTION_ID}\``);
+  });
+});

package/src/modules/workspace/__tests__/git-internals.security.test.ts

@@ -189,6 +189,7 @@ const allowAll = {
   canWriteBatch: async (_w: string, _u: string, paths: string[]) => new Map(paths.map((p) => [p, true])),
   canWriteBatchAtRef: async (_w: string, _r: string, _u: string, paths: string[]) => new Map(paths.map((p) => [p, true])),
   canDownload: async () => true,
+  canDownloadBatch: async (_w: string, _u: string, paths: string[]) => new Map(paths.map((p) => [p, true])),
   canOwner: async () => true,
   eligibleWritersAtRef: async () => [],
 } as unknown as IAccessControl;
@@ -584,7 +585,7 @@ describe('WorkspaceService refuses the git folder on its own', () => {
     ['moveEntry (source)', (p) => service.moveEntry(WS, p, `${KB}/Notes/moved`)],
     ['moveEntry (destination)', (p) => service.moveEntry(WS, `${KB}/Notes/a.md`, p)],
     ['createDirectory', (p) => service.createDirectory(WS, `${p}/new`)],
-    ['createFolderZip', (p) => service.createFolderZip(WS, p.replace(/\/config$/, ''))],
+    ['createFolderZip', (p) => service.createFolderZip(WS, p.replace(/\/config$/, ''), async (paths) => new Set(paths))],
     ['unzipFile (archive)', (p) => service.unzipFile(WS, `${p}.zip`)],
     ['unzipFile (destination)', (p) => service.unzipFile(WS, `${KB}/archive.zip`, p)],
   ];
@@ -649,7 +650,9 @@ describe('WorkspaceService refuses the git folder on its own', () => {
     await mkdir(join(workspaceDir, KB, 'Notes', '.git.'), { recursive: true });
     await writeFile(join(workspaceDir, KB, 'Notes', '.git.', 'HEAD'), 'ref\n');
 
-    const names = new AdmZip(await service.createFolderZip(WS, `${KB}/Notes`)).getEntries().map((e) => e.entryName);
+    const names = new AdmZip(await service.createFolderZip(WS, `${KB}/Notes`, async (paths) => new Set(paths)))
+      .getEntries()
+      .map((e) => e.entryName);
     expect(names).toEqual(['Notes/a.md']);
   });
 

package/src/modules/workspace/__tests__/md-links.test.ts

@@ -0,0 +1,353 @@
+import { describe, expect, it } from 'vitest';
+import {
+  htmlLinksAffectedByMove,
+  resolveMdLink,
+  rewriteMdLinks,
+  scanMarkdownHtmlLinks,
+  scanMarkdownLinks,
+} from '@bevel-software/platform-shared';
+
+/**
+ * The link grammar `move_file` rewrites with (platform-shared `md-links`):
+ * every link form, kept in its form, with code and every other byte untouched.
+ */
+
+const KB = 'knowledge-base';
+
+/** A move of `src` to `dest`, as the plan hands it to the rewriter. */
+function moveOf(src: string, dest: string) {
+  return (p: string): string | null =>
+    p === src ? dest : p.startsWith(`${src}/`) ? dest + p.slice(src.length) : null;
+}
+
+/** Rewrite `text` sitting at `oldPath` (moving to `newPath`) for a move of `src` to `dest`. */
+function rewrite(text: string, oldPath: string, src: string, dest: string, newPath = oldPath) {
+  return rewriteMdLinks(text, { oldPath, newPath, mapPath: moveOf(src, dest), kbDirName: KB, branch: 'main' });
+}
+
+const OUTSIDE = `${KB}/Pages/Index.md`;
+const PLAN = `${KB}/Old/Plan.md`;
+const NEW_PLAN = `${KB}/New/Deep/Plan.md`;
+
+describe('md-links — the forms a link to a moved file is written in', () => {
+  it('a relative link keeps its anchor and title', () => {
+    const { text, edits } = rewrite('See [Plan](../Old/Plan.md#risks "Risks").\n', OUTSIDE, PLAN, NEW_PLAN);
+    expect(text).toBe('See [Plan](../New/Deep/Plan.md#risks "Risks").\n');
+    expect(edits).toEqual([{ from: '../Old/Plan.md#risks', to: '../New/Deep/Plan.md#risks' }]);
+  });
+
+  it('a `./` relative link keeps its `./`', () => {
+    const { text } = rewrite('[a](./Old/Plan.md)\n', `${KB}/Index.md`, PLAN, `${KB}/Other/Plan.md`);
+    expect(text).toBe('[a](./Other/Plan.md)\n');
+  });
+
+  it('a root-anchored /knowledge-base/ link stays root-anchored', () => {
+    const { text } = rewrite(`[p](/${PLAN})\n`, OUTSIDE, PLAN, NEW_PLAN);
+    expect(text).toBe(`[p](/${NEW_PLAN})\n`);
+  });
+
+  it('an app URL /workspace/<branch>/… keeps its branch segment, and one naming another branch is left', () => {
+    const { text } = rewrite(
+      `[p](/workspace/main/${PLAN}#x) [q](/workspace/other/${PLAN})\n`,
+      OUTSIDE,
+      PLAN,
+      NEW_PLAN,
+    );
+    expect(text).toBe(`[p](/workspace/main/${NEW_PLAN}#x) [q](/workspace/other/${PLAN})\n`);
+  });
+
+  it('an angle-bracket destination stays in angle brackets, spaces unencoded', () => {
+    const { text } = rewrite('[p](<../Old Folder/My Plan.md> "t")\n', OUTSIDE, `${KB}/Old Folder`, `${KB}/New Folder`);
+    expect(text).toBe('[p](<../New Folder/My Plan.md> "t")\n');
+  });
+
+  it('a percent-encoded destination stays encoded', () => {
+    const { text } = rewrite('[p](../Old%20Folder/My%20Plan.md)\n', OUTSIDE, `${KB}/Old Folder`, `${KB}/New Folder`);
+    expect(text).toBe('[p](../New%20Folder/My%20Plan.md)\n');
+  });
+
+  it('a bare destination gaining a space has the space encoded, so the link still parses', () => {
+    const { text } = rewrite('[p](../Old/Plan.md)\n', OUTSIDE, PLAN, `${KB}/New Folder/Plan.md`);
+    expect(text).toBe('[p](../New%20Folder/Plan.md)\n');
+  });
+
+  it('an image to any file type', () => {
+    const { text } = rewrite('![shot](../Old/shot.png "Shot")\n', OUTSIDE, `${KB}/Old`, `${KB}/Assets`);
+    expect(text).toBe('![shot](../Assets/shot.png "Shot")\n');
+  });
+
+  it('a reference definition, angle and bare, with its title', () => {
+    const { text } = rewrite(
+      '[x][plan]\n\n[plan]: ../Old/Plan.md "Plan"\n[pdf]: <../Old/Spec v2.pdf>\n',
+      OUTSIDE,
+      `${KB}/Old`,
+      `${KB}/Archive`,
+    );
+    expect(text).toBe('[x][plan]\n\n[plan]: ../Archive/Plan.md "Plan"\n[pdf]: <../Archive/Spec v2.pdf>\n');
+  });
+
+  it('a link to a moved FOLDER, trailing slash kept', () => {
+    const { text } = rewrite('[all](../Old/) [one](../Old)\n', OUTSIDE, `${KB}/Old`, `${KB}/Archive/Old`);
+    expect(text).toBe('[all](../Archive/Old/) [one](../Archive/Old)\n');
+  });
+
+  it('a link wrapping an image: both destinations', () => {
+    const { text } = rewrite('[![a](../Old/a.png)](../Old/Plan.md)\n', OUTSIDE, `${KB}/Old`, `${KB}/New`);
+    expect(text).toBe('[![a](../New/a.png)](../New/Plan.md)\n');
+  });
+
+  it('a destination with balanced parentheses', () => {
+    const { text } = rewrite('[p](../Old/Plan(v2).md)\n', OUTSIDE, `${KB}/Old`, `${KB}/New`);
+    expect(text).toBe('[p](../New/Plan(v2).md)\n');
+  });
+});
+
+describe('md-links — what a move never changes', () => {
+  it('fenced code and inline code are untouched', () => {
+    const input = [
+      'Real [p](../Old/Plan.md).',
+      '',
+      '```md',
+      '[p](../Old/Plan.md)',
+      '```',
+      '',
+      '~~~~',
+      '[p](../Old/Plan.md)',
+      '```',
+      '~~~~',
+      '',
+      '- item',
+      '  ```',
+      '  [p](../Old/Plan.md)',
+      '  ```',
+      '',
+      'Inline `[p](../Old/Plan.md)` and ``a ` [p](../Old/Plan.md) ``.',
+      '',
+    ].join('\n');
+    const { text, edits } = rewrite(input, OUTSIDE, PLAN, NEW_PLAN);
+    expect(edits).toHaveLength(1);
+    expect(text).toBe(input.replace('Real [p](../Old/Plan.md).', 'Real [p](../New/Deep/Plan.md).'));
+  });
+
+  it('indented code blocks are untouched, at the margin and inside a list item', () => {
+    const input = [
+      'Real [p](../Old/Plan.md).',
+      '',
+      '    [p](../Old/Plan.md)',
+      '',
+      '    still code [p](../Old/Plan.md)',
+      '',
+      '- item',
+      '',
+      '    list paragraph [p](../Old/Plan.md)',
+      '',
+      '        [p](../Old/Plan.md)',
+      '',
+      'para',
+      '    lazy [p](../Old/Plan.md)',
+      '',
+    ].join('\n');
+    const { text, edits } = rewrite(input, OUTSIDE, PLAN, NEW_PLAN);
+    expect(edits).toHaveLength(3);
+    const changed = text.split('\n').filter((l, i) => l !== input.split('\n')[i]);
+    expect(changed).toEqual([
+      'Real [p](../New/Deep/Plan.md).',
+      '    list paragraph [p](../New/Deep/Plan.md)',
+      '    lazy [p](../New/Deep/Plan.md)',
+    ]);
+  });
+
+  it('id-links, external URLs, same-page anchors and escaped brackets are left alone', () => {
+    const input = '[a](project-hexis) [b](plan#risks) [c](https://x.y/Old/Plan.md) [d](#risks) \\[e](../Old/Plan.md)\n';
+    expect(rewrite(input, OUTSIDE, PLAN, NEW_PLAN).text).toBe(input);
+  });
+
+  it('frontmatter: the nodeType link is rewritten and every other line stays byte-identical (CRLF too)', () => {
+    const fm = [
+      '---',
+      'nodeType: "[Task](../NodeTypes/Task.md)"',
+      'id: task-a',
+      'tags: [a, b]   ',
+      'read: "[[Sales]]"',
+      '---',
+      '',
+      '# Name',
+      'A task linking [Task](../NodeTypes/Task.md).',
+      '',
+    ].join('\r\n');
+    const { text } = rewrite(fm, `${KB}/Tasks/A.md`, `${KB}/Tasks/A.md`, `${KB}/Tasks/Deep/A.md`, `${KB}/Tasks/Deep/A.md`);
+    expect(text).toBe(fm.split('../NodeTypes/Task.md').join('../../NodeTypes/Task.md'));
+    const before = fm.split('\r\n');
+    const after = text.split('\r\n');
+    expect(after.filter((l, i) => l !== before[i])).toEqual([
+      'nodeType: "[Task](../../NodeTypes/Task.md)"',
+      'A task linking [Task](../../NodeTypes/Task.md).',
+    ]);
+  });
+
+  it('a file whose links all still resolve comes back unchanged, as the same string', () => {
+    const input = `[p](/${KB}/Elsewhere.md) [q](Sibling.md)\n`;
+    const out = rewrite(input, `${KB}/A/B.md`, `${KB}/Unrelated.md`, `${KB}/Other.md`);
+    expect(out.edits).toEqual([]);
+    expect(out.text).toBe(input);
+  });
+});
+
+describe('md-links — the four placements of a link and a moved file', () => {
+  const src = `${KB}/Projects/A`;
+  const dest = `${KB}/Topics/Deep/A`;
+
+  it('inside the moved set, outbound: a link out of a moved file follows its target', () => {
+    const { text } = rewrite('[t](../../NodeTypes/Task.md)\n', `${src}/One.md`, src, dest, `${dest}/One.md`);
+    expect(text).toBe('[t](../../../NodeTypes/Task.md)\n');
+  });
+
+  it('between two moved files: the relative link already holds, untouched', () => {
+    const out = rewrite('[two](Two.md) [up](../A/Two.md)\n', `${src}/One.md`, src, dest, `${dest}/One.md`);
+    expect(out.edits).toEqual([]);
+  });
+
+  it('between two moved files, root-anchored: rewritten to the new place', () => {
+    const { text } = rewrite(`[two](/${src}/Two.md)\n`, `${src}/One.md`, src, dest, `${dest}/One.md`);
+    expect(text).toBe(`[two](/${dest}/Two.md)\n`);
+  });
+
+  it('inbound from outside: points at the new place', () => {
+    const { text } = rewrite('[one](../Projects/A/One.md)\n', `${KB}/Pages/Index.md`, src, dest);
+    expect(text).toBe('[one](../Topics/Deep/A/One.md)\n');
+  });
+});
+
+describe('md-links — scanning', () => {
+  it('finds every destination with its offsets and kind', () => {
+    const text = '---\nnodeType: "[T](../T.md)"\n---\n[a](a.md) ![b](b.png)\n\n[c]: c.md\n[^1]: not a definition\n';
+    const spans = scanMarkdownLinks(text);
+    expect(spans.map((s) => [s.kind, s.destination, s.inFrontmatter])).toEqual([
+      ['link', '../T.md', true],
+      ['link', 'a.md', false],
+      ['image', 'b.png', false],
+      ['definition', 'c.md', false],
+    ]);
+    for (const s of spans) expect(text.slice(s.start, s.end)).toBe(s.destination);
+  });
+
+  it('resolves the forms the app resolves', () => {
+    const base = `${KB}/A/B.md`;
+    expect(resolveMdLink('../C.md#x', { basePath: base, kbDirName: KB })).toEqual({ form: 'relative', branch: null, path: `${KB}/C.md`, hash: '#x' });
+    expect(resolveMdLink(`/${KB}/C.md`, { basePath: base, kbDirName: KB })?.path).toBe(`${KB}/C.md`);
+    expect(resolveMdLink(`/workspace/main/${KB}/My%20C.md`, { basePath: base, kbDirName: KB })).toEqual({ form: 'workspace', branch: 'main', path: `${KB}/My C.md`, hash: '' });
+    expect(resolveMdLink('project-hexis', { basePath: base, kbDirName: KB })).toBeNull();
+    expect(resolveMdLink('mailto:a@b', { basePath: base, kbDirName: KB })).toBeNull();
+  });
+
+  it('HTML pages: the links a move would break are reported', () => {
+    const html = '<a href="../Old/Plan.md">p</a><img src=\'x.png\'><a href="https://x.y">x</a>';
+    expect(htmlLinksAffectedByMove(html, { oldPath: OUTSIDE, newPath: OUTSIDE, mapPath: moveOf(PLAN, NEW_PLAN), kbDirName: KB, branch: 'main' }))
+      .toEqual(['../Old/Plan.md']);
+  });
+
+  it('HTML pages: unquoted attribute values are reported too', () => {
+    const html = '<a href=../Old/Plan.md>p</a> <a class=x href = ../Old/Plan.md#r>q</a>';
+    expect(htmlLinksAffectedByMove(html, { oldPath: OUTSIDE, newPath: OUTSIDE, mapPath: moveOf(PLAN, NEW_PLAN), kbDirName: KB, branch: 'main' }))
+      .toEqual(['../Old/Plan.md', '../Old/Plan.md#r']);
+  });
+
+  it('a markdown page: only the raw HTML tags that are live — not in code, not escaped, not a bare href= in prose', () => {
+    const page =
+      '---\nnodeType: "[T](../NodeTypes/T.md)"\nsrc: in-frontmatter.md\n---\n\n' +
+      'Prose with `<a href="in-span.md">` and an escaped \\<a href="in-escape.md"> tag, and src = in-prose.md.\n\n' +
+      '```html\n<a href="in-fence.md">f</a>\n```\n\n' +
+      '    <img src="in-indent.md">\n\n' +
+      '> [def]: in-def.md\n\nLive <a href="live.md">x</a> and <img src=\'pic.png\' alt="p"/> and <a href=bare.md>b</a>\n' +
+      // A `>` inside a quoted attribute does not end the tag; a backslash
+      // inside a raw tag is not an escape, so the value keeps it.
+      '<a title="a > b" href="quoted.md">q</a> <a href="Plan\\_v2.md">e</a>\n';
+    const live = ['live.md', 'pic.png', 'bare.md', 'quoted.md', 'Plan\\_v2.md'];
+    expect(scanMarkdownHtmlLinks(page).map((t) => t.destination)).toEqual(live);
+    // Which attribute each came from travels with it: a `src` is a picture.
+    expect(scanMarkdownHtmlLinks(page).map((t) => t.image)).toEqual([false, true, false, false, false]);
+    // Escaped backticks are literal text, not a code span around the tag;
+    // `data-href` is not a link; `href=` inside another attribute's value is a value.
+    const found = (text: string) => scanMarkdownHtmlLinks(text).map((t) => t.destination);
+    expect(found('a \\` b <a href="between.md">x</a> c \\` d\n')).toEqual(['between.md']);
+    expect(found('<div data-href="not.md" title="href=nor.md"><a href="yes.md">x</a></div>\n')).toEqual(['yes.md']);
+    // A tag inside an HTML comment is not rendered, so it is not a link.
+    expect(found('<!-- <a href="hidden.md">x</a> -->\n<a href="shown.md">y</a>\n')).toEqual(['shown.md']);
+    expect(htmlLinksAffectedByMove(page, { oldPath: OUTSIDE, newPath: `${KB}/Moved/Index.md`, mapPath: () => null, kbDirName: KB, branch: 'main' }, scanMarkdownHtmlLinks(page)))
+      .toEqual(live);
+  });
+});
+
+describe('md-links — container and frontmatter edges', () => {
+  it('a fence-looking line four columns in, inside a paragraph, opens no fence', () => {
+    const input = ['para', '    ~~~', '    [p](../Old/Plan.md)', '    ~~~', ''].join('\n');
+    expect(rewrite(input, OUTSIDE, PLAN, NEW_PLAN).text).toBe(input.replace('../Old/Plan.md', '../New/Deep/Plan.md'));
+    // With backticks the two runs are one inline code span: code, left alone.
+    const ticks = input.split('~~~').join('```');
+    expect(rewrite(ticks, OUTSIDE, PLAN, NEW_PLAN).text).toBe(ticks);
+  });
+
+  it('a fence-looking line four columns in does not close a fence', () => {
+    const input = ['```', '    ```', '[p](../Old/Plan.md)', '```', '[q](../Old/Plan.md)', ''].join('\n');
+    expect(rewrite(input, OUTSIDE, PLAN, NEW_PLAN).text).toBe(['```', '    ```', '[p](../Old/Plan.md)', '```', '[q](../New/Deep/Plan.md)', ''].join('\n'));
+  });
+
+  it('a fence inside a list item still opens and closes at the item’s indent', () => {
+    const input = ['- item', '', '  ```', '  [p](../Old/Plan.md)', '  ```', '', '[q](../Old/Plan.md)', ''].join('\n');
+    expect(rewrite(input, OUTSIDE, PLAN, NEW_PLAN).text).toBe(input.replace('[q](../Old/Plan.md)', '[q](../New/Deep/Plan.md)'));
+  });
+
+  it('a reference definition inside a blockquote is rewritten', () => {
+    const input = '> [ref]: ../Old/Plan.md "t"\n> > [deep]: <../Old/Plan.md>\n';
+    expect(rewrite(input, OUTSIDE, PLAN, NEW_PLAN).text).toBe('> [ref]: ../New/Deep/Plan.md "t"\n> > [deep]: <../New/Deep/Plan.md>\n');
+  });
+
+  it('an indented code block inside a blockquote is untouched, and the quoted prose beside it is rewritten', () => {
+    const input = '> intro\n>\n>     [p](../Old/Plan.md)\n>\n> [q](../Old/Plan.md)\n';
+    expect(rewrite(input, OUTSIDE, PLAN, NEW_PLAN).text).toBe(
+      '> intro\n>\n>     [p](../Old/Plan.md)\n>\n> [q](../New/Deep/Plan.md)\n',
+    );
+  });
+
+  it('frontmatter: only a value that is one whole link is rewritten; a link in a prose value is left', () => {
+    const fm = [
+      '---',
+      'nodeType: "[Task](../Old/Plan.md)"',
+      "parent: '[P](../Old/Plan.md)'",
+      // Not valid YAML (a flow sequence), so the panel shows no link; still a
+      // whole-value link to a line-based reader such as the graph parser.
+      'owner: [P](../Old/Plan.md)',
+      'description: "See [P](../Old/Plan.md) for context"',
+      'commented: "[P](../Old/Plan.md)"  # YAML drops this [c](../Old/Plan.md)',
+      "bare: '[P](../Old/Plan.md)' # so does this",
+      'inside: "[P](../Old/Plan.md) # not a comment"',
+      'two: "[a](../Old/Plan.md) [b](../Old/Plan.md)"',
+      '---',
+      '',
+    ].join('\n');
+    const { text } = rewrite(fm, OUTSIDE, PLAN, NEW_PLAN);
+    expect(text.split('\n')).toEqual([
+      '---',
+      'nodeType: "[Task](../New/Deep/Plan.md)"',
+      "parent: '[P](../New/Deep/Plan.md)'",
+      'owner: [P](../New/Deep/Plan.md)',
+      'description: "See [P](../Old/Plan.md) for context"',
+      'commented: "[P](../New/Deep/Plan.md)"  # YAML drops this [c](../Old/Plan.md)',
+      "bare: '[P](../New/Deep/Plan.md)' # so does this",
+      'inside: "[P](../Old/Plan.md) # not a comment"',
+      'two: "[a](../Old/Plan.md) [b](../Old/Plan.md)"',
+      '---',
+      '',
+    ]);
+  });
+
+  it('an image under another branch’s app URL is rewritten — the app serves it from this branch — while a link there is left', () => {
+    const { text } = rewrite(
+      `![i](/workspace/other/${PLAN}) [q](/workspace/other/${PLAN})\n`,
+      OUTSIDE,
+      PLAN,
+      NEW_PLAN,
+    );
+    expect(text).toBe(`![i](/workspace/other/${NEW_PLAN}) [q](/workspace/other/${PLAN})\n`);
+  });
+});