Skip to content

See how your app actually fits together. An interactive, plain-English map of your codebase, drawn by Claude or Codex.

9.2 KB
Raw Blame
// Changing a blueprint from the map: the Ask bar's Change mode sends a request to the agent (a stand-in
// here, fixtures/fake-cli), which replies with the whole updated plan. serve.mjs checks it with plan.mjs and
// build.mjs, saves it, redraws the map with the changes highlighted, and can undo it.
import { test, after } from 'node:test';
import assert from 'node:assert/strict';
import fs from 'node:fs';
import path from 'node:path';
import { spawn } from 'node:child_process';
import { REPO, makeProject, shopApp, run, readGraph, readJson, writeJson, routeKeys, cleanup } from './helpers.mjs';

const FIXTURE = path.join(REPO, 'tests', 'fixtures', 'blueprint');
const FAKE = path.join(REPO, 'tests', 'fixtures', 'fake-cli', 'fake-claude.mjs');
const servers = [], roots = [];
after(async () => {
  await Promise.all(servers.filter((s) => s.exitCode === null).map((s) => new Promise((resolve) => { s.once('exit', resolve); s.kill(); })));
  for (const r of roots) cleanup(r);
});

/** The sample blueprint, drawn, with its map server answering through the stand-in agent's `replies`. */
async function served(replies, root) {
  if (!root) {
    root = makeProject({});
    fs.cpSync(FIXTURE, root, { recursive: true });
    run('plan.mjs', root);
    run('build.mjs', root, '--no-claude-md', '--agent', 'claude');
  }
  roots.push(root);
  const changes = path.join(root, 'replies.json');
  writeJson(changes, replies);
  const log = path.join(root, 'fake.log');
  const port = 20000 + Math.floor(Math.random() * 20000);
  const server = spawn(process.execPath, [path.join(root, 'floorplan', 'serve.mjs'), '--port', String(port), '--no-open'], {
    cwd: root, env: { ...process.env, FLOORPLAN_NO_PROMPTS: '1', FLOORPLAN_ENGINE: '', FLOORPLAN_CLAUDE: FAKE, FAKE_LOG: log, FAKE_CHANGES: changes }, stdio: ['ignore', 'pipe', 'pipe'],
  });
  servers.push(server);
  const base = await new Promise((resolve, reject) => {
    let out = '';
    const timer = setTimeout(() => reject(new Error(`server didn't start: ${out}`)), 20000);
    server.stdout.on('data', (d) => { out += d; const m = /Floorplan: (http:\/\/\S+)/.exec(out); if (m) { clearTimeout(timer); resolve(m[1]); } });
    server.on('exit', (code) => reject(new Error(`server exited (${code}): ${out}`)));
  });
  const page = JSON.parse(/window\.FLOORPLAN_SERVER=(\{.*?\});/.exec(await (await fetch(base + '/')).text())[1]);
  const token = page.token;
  // the stand-in is Claude Code, which holds its answers to a schema, so the map offers Change
  assert.equal(page.change, true);
  const post = (p, body) => fetch(base + p, { method: 'POST', headers: { 'content-type': 'application/json', 'x-floorplan-token': token }, body: JSON.stringify(body || {}) });
  return {
    root,
    async change(question) {
      const text = await (await post('/api/ask', { question, mode: 'change' })).text();
      return text.split('\n\n').filter(Boolean).map((b) => ({ event: /^event: (\w+)/.exec(b)[1], data: JSON.parse(/^data: (.*)$/m.exec(b)[1]) }));
    },
    undo: async () => (await post('/api/plan/undo')).json(),
    calls: () => fs.readFileSync(log, 'utf8').trim().split('\n').map((l) => JSON.parse(l)),
  };
}
const pick = (events, name) => events.filter((e) => e.event === name).map((e) => e.data);

/** The sample plan with refunds added: a new endpoint file, its endpoint, and the "My walks" page calling it. */
function withRefunds(change = (p) => p) {
  const plan = readJson(path.join(FIXTURE, 'floorplan', 'plan.json'));
  plan.files.push({ path: 'api/src/routes/refunds.ts', name: 'Refund endpoints', description: 'Refunds a cancelled walk to the owner’s card.', uses: ['api/src/services/payments.ts', 'api/src/db/bookings.ts'] });
  plan.files.find((f) => f.path === 'web/app/bookings/page.tsx').calls.push('POST /api/refunds');
  plan.endpoints.push({ method: 'POST', path: '/api/refunds', file: 'api/src/routes/refunds.ts', name: 'Refund a walk', description: 'Sends the money back for a cancelled walk.', access: 'signed-in', who: 'the owner who booked it' });
  change(plan);
  return {
    title: 'Planned out refunds',
    summary: 'Added a **refund** endpoint that the My walks page calls when a walk is cancelled.',
    plan: JSON.stringify(plan),
    architecture: fs.readFileSync(path.join(FIXTURE, 'floorplan', 'architecture.json'), 'utf8'),
    changes: [
      { ref: 'api/src/routes/refunds.ts', change: 'new', note: 'Where refunds are handled.' },
      { ref: 'POST /api/refunds', change: 'new', note: 'The request that refunds a walk.' },
      { ref: 'web/app/bookings/page.tsx', change: 'changed', note: 'Now asks for a refund when a walk is cancelled.' },
    ],
    followups: ['Email the owner when the refund goes through'],
  };
}

test('a change is checked, saved and drawn, with what changed highlighted', async () => {
  const s = await served([withRefunds()]);
  const events = await s.change('also plan out refunds');
  assert.deepEqual(pick(events, 'failure'), []);
  assert.deepEqual(pick(events, 'progress').map((p) => p.text), ['Reading floorplan/plan.json', 'Checking the updated plan']);
  const [answer] = pick(events, 'answer');
  assert.equal(answer.title, 'Planned out refunds');
  assert.equal(answer.changes, 3);
  assert.deepEqual(answer.followups, ['Email the owner when the refund goes through']);
  assert.match(answer.undo, /^[0-9a-z]+$/);

  const g = readGraph(s.root);
  assert.ok(routeKeys(g).includes('POST /api/refunds'));
  assert.ok(g.links.some((l) => l.a === 'f:web/app/bookings/page.tsx' && l.b === 'f:api/src/routes/refunds.ts' && l.labels.includes('POST /api/refunds')));
  assert.equal(g.recent.tasks[0].title, 'Planned out refunds');
  assert.equal(g.recent.tasks[0].request, 'also plan out refunds');
  assert.deepEqual(g.recent.items.map((x) => `${x.change} ${x.id}`).sort(), ['changed f:web/app/bookings/page.tsx', 'new f:api/src/routes/refunds.ts', `new r:${g.routes.findIndex((r) => r.p === '/api/refunds')}`].sort());
  assert.equal(readJson(path.join(s.root, 'floorplan', 'plan.json')).endpoints.at(-1).who, 'the owner who booked it');

  // the agent only read: no editing tools, and it was asked for the change schema
  const [call] = s.calls();
  assert.ok(!call.args.join(' ').match(/\b(Edit|Write)\b/), 'the agent gets no editing tools');
  assert.match(call.args[call.args.indexOf('--append-system-prompt') + 1], /You change a blueprint/);
  assert.equal(call.input, 'also plan out refunds');

  // undo puts the plan and the map back
  assert.deepEqual(await s.undo(), { ok: true, left: 0 });
  assert.ok(!routeKeys(readGraph(s.root)).includes('POST /api/refunds'));
  assert.deepEqual(await s.undo(), { ok: false, error: 'Nothing to undo.' });
});

test('a plan that fails the checks goes back to the agent once, with the problems', async () => {
  const broken = withRefunds((p) => { p.endpoints.at(-1).file = 'api/src/routes/refund.ts'; });
  const s = await served([broken, withRefunds()]);
  const events = await s.change('also plan out refunds');
  assert.ok(pick(events, 'progress').some((p) => p.text === 'Fixing a problem the checks found'));
  assert.equal(pick(events, 'answer')[0].title, 'Planned out refunds');
  const [, retry] = s.calls();
  assert.match(retry.input, /didn't pass the checks/);
  assert.match(retry.input, /"api\/src\/routes\/refund\.ts" is not one of the planned files/);
  assert.equal(retry.args[retry.args.indexOf('--resume') + 1], 'test-session');
});

test('new files outside every part are sent back once, so the agent adds a glob', async () => {
  const stray = withRefunds((p) => { p.files.push({ path: 'admin/app/page.tsx', name: 'Admin home', description: 'Our own admin page.' }); });
  const fixed = { ...stray, architecture: JSON.stringify({ ...readJson(path.join(FIXTURE, 'floorplan', 'architecture.json')), nodes: [...readJson(path.join(FIXTURE, 'floorplan', 'architecture.json')).nodes, { id: 'admin', label: 'Admin page', kind: 'ui', summary: 'Our own admin page.', paths: ['admin/**'] }] }) };
  const s = await served([stray, fixed]);
  const events = await s.change('add an admin page');
  assert.match(s.calls()[1].input, /1 planned file\(s\) fall under no node's paths/);
  assert.equal(pick(events, 'answer').length, 1);
  assert.equal(readGraph(s.root).files.filter((f) => f.n === 'unassigned').length, 0);
});

test('when the second try fails too, nothing changes', async () => {
  const broken = withRefunds((p) => { p.endpoints.at(-1).access = 'owners'; });
  const s = await served([broken]);
  const before = fs.readFileSync(path.join(s.root, 'floorplan', 'plan.json'), 'utf8');
  const events = await s.change('also plan out refunds');
  const [failure] = pick(events, 'failure');
  assert.equal(failure.code, 'change_invalid');
  assert.match(failure.message, /access "owners" must be one of/);
  assert.equal(fs.readFileSync(path.join(s.root, 'floorplan', 'plan.json'), 'utf8'), before);
  assert.ok(!routeKeys(readGraph(s.root)).includes('POST /api/refunds'));
  assert.equal(s.calls().length, 2);
});

test('a map of real code cannot be changed this way', async () => {
  const root = shopApp();
  run('scan.mjs', root);
  run('build.mjs', root, '--no-claude-md', '--agent', 'claude');
  const s = await served([withRefunds()], root);
  const [failure] = pick(await s.change('add refunds'), 'failure');
  assert.match(failure.message, /Only a blueprint can be changed from the map/);
});