See how your app actually fits together. An interactive, plain-English map of your codebase, drawn by Claude or Codex.
JavaScript ai-codingarchitecture-diagramclaudeclaude-codeclaude-code-plugincodebase-visualizationcodexcodex-plugindeveloper-toolsonboardingopenaivibe-coding
Trust: say what the plugin can do, enforce it, and let people verify their copy
Hayden Smith76a0e9328250
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 72f68db..4214d06 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,9 @@# Changelog+## Unreleased++- **Is it safe to install?** A new page lists everything Floorplan does on your computer: no hooks, MCP servers, dependencies or downloads, its one outbound request, and every program it runs. A test enforces it on every change, and each release now includes `CHECKSUMS.txt`, so you can confirm your installed copy matches it (`node tools/checksums.mjs --check <folder>`).+## 0.4.1 (2026-10-30)- **Exported copies say where they came from:** a small "Made with Floorplan" link at the bottom of an exported map leads to the project, so whoever receives one can make their own.diff --git a/CHECKSUMS.txt b/CHECKSUMS.txtnew file mode 100644index 0000000..fbdd53b--- /dev/null+++ b/CHECKSUMS.txt@@ -0,0 +1,56 @@+# Floorplan 0.4.1: SHA-256 of every file the plugin runs from.+# Check an installed copy: clone this release, then run node tools/checksums.mjs --check <installed folder>.+43adc6c187150c4b0a4841f0e7448381401be93ee65e2d212be4e7eeb67bb3e4 .agents/plugins/marketplace.json+fdce61be9c420fd16b8cbbff629baa37e8d1096094b3e90bc5ecc0fe1ffc3a78 .claude-plugin/icon.png+98cd297588a52fc7715d29ad10636f3224ee7a99bfbb94230315493dabc7147c .claude-plugin/marketplace.json+b75186f9fd13ed96086fa077fa3de40350fef017021fc6ac4ce8aad5b82d026e .claude-plugin/plugin.json+7bdb74d57875b25ca9dcd367f79f92b9089f5f4b873bffec898cc6c3f0a84a68 .codex-plugin/icon.png+99d5e5173abac3516b37a9658adf2d8065562e82ff529fdeba96f1e0901873c9 .codex-plugin/plugin.json+e1cdfc2a2f1ae41796c8eae54eed099f95d09d25f2ec521742d3ab7a8aba1337 package.json+3e6508e7708904757024b8bebef744d53e96cc37e62c86c6793ab2b44436198a skills/floorplan/SKILL.md+4dde86cace299094c246604badb73b605a10f47e01a72cc6746680788a7e20f9 skills/floorplan/agents/openai.yaml+91485d6e067e25f742939ee7903d97096e560bfebdb32b71b428294ef2c781d9 skills/floorplan/assets/favicon.png+60c5ef78ab48cb60fed2a3d712dc8b48c017245042bf7139d242844790f77f3c skills/floorplan/assets/graph-query.js+308b79d1680314b80350eaae04b8ad0c655bfb7a1fa2a2ef64b79e286469cc9b skills/floorplan/assets/logo.png+3e0cd257ebf5e6445772a6b2c8e90225b9d828b366e4f9010661cc222cf60518 skills/floorplan/assets/query-cli.mjs+838a6c66327a1e436e8c1c102e4dcb0d982364c6e08d8e394d8549e0343fdecf skills/floorplan/assets/serve.mjs+9fb61d68fec54c44ff185c3ba4af4a85c1e54dd90d77ef7bc54c82f0a3c47215 skills/floorplan/assets/ui/05-theme.js+741a145b38c7784a640cf107df2dcc09cbdef33753fe3e0088a43c7e3a343bda skills/floorplan/assets/ui/06-blueprint.js+c41b2ce2e0038cab208579eaeb541223d8175fade09ed360ba53a4c49956a9c3 skills/floorplan/assets/ui/10-glossary.js+3cc1d88d210333fb98391e27332b90d27247ce54b08f98899525757e23509529 skills/floorplan/assets/ui/20-health.js+e326a65e6e92949391fcc4960b67c0b9340e8f1cbd6cf43333b1f530503401c1 skills/floorplan/assets/ui/25-recent.js+70fe53cd05bbc25d57844a52ea6e40ccfa98757c694f96e16945086ad12a10fd skills/floorplan/assets/ui/30-screens.js+4811505dbab0b9034573aaaa33980e7e1685d5c6a1521f4578fb38c8dad37d08 skills/floorplan/assets/ui/40-tour.js+9cd14f892119ec2d448e1c647c9c539772a52319d304c9b637ef5188a3fe661c skills/floorplan/assets/ui/50-cloud.js+f62e11ba758a5cd08bd262e2c78cb2eaffb941b21d565ef8aa70d8b7534c7c95 skills/floorplan/assets/ui/60-export.js+b0745abd7f23cd91690a1587e377edbe19fd7233c783300290936720546216d4 skills/floorplan/assets/vendor/elk.bundled.js+89591d4578fb1ebd91501312a3d25f021bd865a2e436641c1cf7b1bc7e3c1617 skills/floorplan/assets/vendor/elkjs-LICENSE.md+3b0a5fca3d17942cde889069889dedbbbd075e9b599968c82a95f4d944e9b345 skills/floorplan/assets/vendor/fonts/inter-LICENSE.txt+34b9c504cab7a73e37b746343a449132e56cf7b5481af2cb81dc74dcff25c956 skills/floorplan/assets/vendor/fonts/inter-latin-ext-wght-normal.woff2+3100e775e8616cd2611beecfa23a4263d7037586789b43f035236a2e6fbd4c62 skills/floorplan/assets/vendor/fonts/inter-latin-wght-normal.woff2+403581b69dac5cff4079205e01c6b467e56af449ecbd7247693ddb1baafa005b skills/floorplan/assets/vendor/fonts/jetbrains-mono-LICENSE.txt+79bfdab9ba467e26eea4122e6f2567e188dd8a09a8c730d501fc487c4ab99c6e skills/floorplan/assets/vendor/fonts/jetbrains-mono-latin-ext-wght-normal.woff2+18be452724bfdc236c074ca94a249a7f41a86752c7d04ab258ce9ed5651f6a7e skills/floorplan/assets/vendor/fonts/jetbrains-mono-latin-wght-normal.woff2+cd7fb27a9795a9c0d8b859260200c496485e829760fb6ffc5a3417fb5d85ff9b skills/floorplan/assets/viewer.html+7972820de67d9db107295d5ff85c374fa7821248ee5cdef21ad43813c15f53f3 skills/floorplan/references/blueprint.md+ac2460a6613956209895d970213630d9d99475745ba761fd842982e2f5ccec13 skills/floorplan/references/choosing-boundaries.md+83db6fbd2e117ebcb2a21b115ccd38125a1d977a79fc19050dd0ca2f67a25730 skills/floorplan/references/schema.md+9805cbe487912b2995594fa3bd4fa7650fa963aee622558097d80b772965588a skills/floorplan/references/writing-descriptions.md+e0eef6b78b2bbec7576760eb64d12db341b579305cc7e8ead0258f81a54cee94 skills/floorplan/scripts/build.mjs+bb02ef4b60dafb05a74eb2561f22a530b5b17935783bd88731c5bea5b6d57609 skills/floorplan/scripts/describe.mjs+3f1ed916b8e3e7fb240e3db04be86a5a3d57e2cb78fe5fd6100fcedc4edf2206 skills/floorplan/scripts/lib/agent.mjs+0cd705247440591764a3387cd9ec0ddb80fe72887728dd4e4b92b6ef6077dc7e skills/floorplan/scripts/lib/blueprint.mjs+24f7805618225f401af350d8b1e960720ce3c569c07891839aa3bee66e1d898c skills/floorplan/scripts/lib/claudemd.mjs+4e0958b8642a55ae77ac19fe9fc35975cff3e541978641e9d96c25f6bb8dfb9d skills/floorplan/scripts/lib/common.mjs+1b1e784671dcc6e9362cf7434f262679c053d56c1aaf58c5e370fe98580fe2f7 skills/floorplan/scripts/lib/extract.mjs+ec4a537b17f1b64968e914c5305302501387dcba7ae84011aa7b8c4f602c597b skills/floorplan/scripts/lib/health.mjs+7076868899b30564d1754e708b9e1907137bd06804f573cf44468e43c4a76964 skills/floorplan/scripts/lib/names.mjs+aa3f0050a5b0f7a1b1dbf22d8e279427707f46b4370c998660ab39aa3e0db1f4 skills/floorplan/scripts/lib/resolve.mjs+088406c7b94ebcdaf047e25b0357c4313be6692b9391299c5f31e53a0968a8d2 skills/floorplan/scripts/lib/routes.mjs+fc593a825b6e476ab1d45b1276a27bce5168c781fc9f223798bcdce300f1b0ea skills/floorplan/scripts/lib/screens.mjs+8cfda528a516678da6e7a877246d26978e81f3f7ef9593bdb9222ecef7720a61 skills/floorplan/scripts/open.mjs+ddaf345e471fb66dee0baf9b8aba12c9ebdb0572b31a19d59a198d2b02c5a457 skills/floorplan/scripts/plan.mjs+6aa5a03af2ab58da83ef62e5d304deca4b7454733ed5cbe1bcee239fb19807d9 skills/floorplan/scripts/recent.mjs+9cce60593256835c34eda3858229183fb75e4df5c2d1c3aa87bbf949e72aa3d8 skills/floorplan/scripts/refresh.mjs+092975f35712d95813b49784ba51bec037fb29878fd54614671c8db16719c999 skills/floorplan/scripts/scan.mjs+432bfcf5b87ab34ad685373dfca2cf46bc2d316b349a9105ceb9309152e9c709 skills/floorplan/scripts/status.mjsdiff --git a/README.md b/README.mdindex 516dac4..c8aad5c 100644--- a/README.md+++ b/README.md@@ -236,7 +236,7 @@ A `floorplan/` folder holding the map. In Claude Code it also adds a short secti- The Health check never stores or shows secret values, only where they are.- No analytics or tracking. The map may ask once whether you'd like an email when Floorplan Cloud launches. Nothing is sent unless you sign up, and then only your email and "just me" or "with my team".-More in [Privacy and security](docs/privacy-and-security.md).+More in [Privacy and security](docs/privacy-and-security.md). Wondering whether a plugin is safe to install? [Is it safe to install?](docs/is-it-safe.md) lists everything Floorplan does on your computer, how a test checks that on every change, and how to verify your copy.## Documentation@@ -248,11 +248,18 @@ More in [Privacy and security](docs/privacy-and-security.md).| [How it works](docs/how-it-works.md) | The pipeline, connection matching, refreshes || [What's in your project](docs/project-files.md) | Every file Floorplan creates, and how to edit it || [Privacy and security](docs/privacy-and-security.md) | What runs where, and what leaves your machine |+| [Is it safe to install?](docs/is-it-safe.md) | No hooks, MCP servers, dependencies or downloads; every program it runs; checking your installed copy || [Troubleshooting](docs/troubleshooting.md) | Common problems and fixes || [Developing Floorplan](docs/development.md) | Repo layout, local installs, releases |## FAQ+<details>+<summary><b>Is it safe to install?</b></summary>++Floorplan has no hooks, no MCP servers and no dependencies, downloads nothing, and never runs code from the internet. Its only outside request is the opt-in waitlist. A test checks all of that on every change, and every release lists a fingerprint of each file so you can confirm your installed copy is the real thing. Everything is in [Is it safe to install?](docs/is-it-safe.md).+</details>+<details><summary><b>Does my code leave my computer?</b></summary>diff --git a/SECURITY.md b/SECURITY.mdindex 436db95..3b58533 100644--- a/SECURITY.md+++ b/SECURITY.md@@ -11,6 +11,10 @@ Helpful details:You'll get a reply within a few days. Once a fix is out, you'll be credited unless you'd rather not be.+## What the plugin can do++[Is it safe to install?](docs/is-it-safe.md) lists everything Floorplan does on your computer: its one outbound request, every program it runs, and what it never does. [`tests/supply-chain.test.mjs`](tests/supply-chain.test.mjs) enforces that on every push and pull request, and each release's `CHECKSUMS.txt` lets you confirm an installed copy matches it (`node tools/checksums.mjs --check <folder>`).+## ScopeIn scope:diff --git a/docs/README.md b/docs/README.mdindex 3e53f71..df859a1 100644--- a/docs/README.md+++ b/docs/README.md@@ -8,6 +8,7 @@| [How it works](how-it-works.md) | The pipeline from scan to map, how connections are found, how updates stay cheap, how blueprints are drawn and changed || [What's in your project](project-files.md) | Every file Floorplan creates, which ones you can edit, and how it stays out of git || [Privacy and security](privacy-and-security.md) | What runs where, what leaves your machine, and how secrets are handled |+| [Is it safe to install?](is-it-safe.md) | Everything Floorplan does on your computer, how a test enforces it, and how to verify your installed copy || [Troubleshooting](troubleshooting.md) | Common problems and how to fix them || [Developing Floorplan](development.md) | Repo layout, testing a local copy, releasing a new version |diff --git a/docs/development.md b/docs/development.mdindex fe29364..66bd971 100644--- a/docs/development.md+++ b/docs/development.md@@ -39,6 +39,8 @@ skills/floorplan/logo.png, favicon.pngvendor/ bundled layout engine (elkjs) and fonts, with their licensestests/ regression tests and the sample projects they map+tools/checksums.mjs writes CHECKSUMS.txt for a release, and checks an installed copy against it+CHECKSUMS.txt SHA-256 of every file the plugin runs from, as of the last releasedocs/ these guides```@@ -88,7 +90,8 @@ The tests use Node's built-in test runner, so there's nothing to install (`npm t| `export.test.mjs` | exporting a copy to share: what's left out by default, the extras when asked, the Export button's endpoint || `ask.test.mjs` | asking through Claude Code or Codex: which one is used, read-only, follow-ups, sign-in errors (stand-in CLIs in `fixtures/fake-cli/`) || `agents.test.mjs` | telling Claude Code from Codex, and what a map built by each records and writes |-| `release.test.mjs` | the version agrees across both plugins' `plugin.json`, the README badge and the changelog |+| `release.test.mjs` | the version agrees across both plugins' `plugin.json`, the README badge, the changelog and `CHECKSUMS.txt` |+| `supply-chain.test.mjs` | what the plugin can do stays what [Is it safe to install?](is-it-safe.md) says: no hooks, MCP servers or dependencies, one outbound request, a fixed list of programs and pre-approved scripts, no code loaded at run time, the vendored layout engine unchanged |Sample projects are written to a temp folder by `helpers.mjs` (`shopApp()`) or copied from `tests/fixtures/`. Anything secret-looking is assembled at runtime, so no real-looking key is ever committed.@@ -157,13 +160,17 @@ An engine must be read-only in a way its CLI enforces, not only because the prom```2. Bump `version` in `.claude-plugin/plugin.json` and `.codex-plugin/plugin.json`, and the version badge in `README.md`.3. Rename `## Unreleased` in `CHANGELOG.md` to `## X.Y.Z (YYYY-MM-DD)`.-4. Commit as `Floorplan X.Y.Z: <one-line headline>` and push `main`.-5. Tag and push the tag. This also checks that `plugin.json` and the marketplace entry agree:+4. Write the release's fingerprints, after the version bump:+ ```bash+ node tools/checksums.mjs+ ```+5. Commit as `Floorplan X.Y.Z: <one-line headline>` and push `main`.+6. Tag and push the tag. This also checks that `plugin.json` and the marketplace entry agree:```bashclaude plugin tag . -m "Floorplan %s" --push```-6. On GitHub, publish a release from the tag (`floorplan--vX.Y.Z`), titled `Floorplan X.Y.Z`, with that version's changelog section as its notes.-7. Reply on every issue and pull request the release fixes: what changed, the version, and how to get it (`claude plugin update floorplan@floorplan`).+7. On GitHub, publish a release from the tag (`floorplan--vX.Y.Z`), titled `Floorplan X.Y.Z`, with that version's changelog section as its notes.+8. Reply on every issue and pull request the release fixes: what changed, the version, and how to get it (`claude plugin update floorplan@floorplan`).### Issues and pull requestsdiff --git a/docs/is-it-safe.md b/docs/is-it-safe.mdnew file mode 100644index 0000000..4a8a3ec--- /dev/null+++ b/docs/is-it-safe.md@@ -0,0 +1,92 @@+# Is it safe to install?++Plugins for Claude Code and Codex can run code on your computer, so it's worth asking. Some malicious plugins look harmless when you install them, then download and run something else later (a "stage two"). Floorplan is built so it can't do that, a test checks it on every change, and you can confirm all of it yourself.++## What Floorplan never does++- **No hooks.** Hooks run code automatically on events in every session, which makes them a common hiding place. Floorplan has none.+- **No MCP servers.** Floorplan has none, so it never starts a server that downloads its newest version with `npx`.+- **No dependencies, no install scripts.** Nothing comes from npm, at install time or ever. Its `package.json` exists only to run the tests.+- **Never downloads anything, and never runs code from the internet.** No `eval`, no loading code at run time, no encoded payloads.+- **Never changes your code.** It writes only its own `floorplan/` folder and, in Claude Code, a marked section of `CLAUDE.local.md`. See [What's in your project](project-files.md).+- **No analytics or tracking.**++## Everything it does++### The network++- **The map's server** (`floorplan/serve.mjs`) listens on `127.0.0.1` only, so other machines can't reach it. It answers only to `127.0.0.1` and `localhost` at its own port, and its API needs a token that only the map page receives.+- **One outbound request: the Floorplan Cloud waitlist,** sent only if you type your email into the card on the map and click to join. It goes to `floorplan-waitlist-690500262396.us-central1.run.app` and carries your email and "just me" or "with my team". Details in [Privacy and security](privacy-and-security.md#floorplan-cloud-waitlist).+- **The map page loads nothing from the internet.** Its layout engine and fonts are built into the file. It only links to documentation, which opens when you click.++Asking questions on the map runs Claude Code or Codex, which talk to Anthropic or OpenAI the way they always do, on your account. Floorplan itself sends nothing.++### The programs it runs++| Program | When | Why |+|---|---|---|+| `git` | scan | Read-only: which files are tracked, the current branch and commit, what changed since the last map |+| `where` (Windows) or `which` | starting the map's server | Finding the Claude Code or Codex CLI |+| `claude` or `codex` | when you ask a question on the map | Answering it, read-only: `claude -p` limited to reading files and Floorplan's lookup script, or `codex exec --sandbox read-only` |+| `node` | throughout | Running Floorplan's own scripts |+| `cmd /c start`, `open` or `xdg-open` | opening the map | Opening the map's local address in your browser |++Each is started directly with its arguments, never as a command line for a shell to interpret. The one shell is Windows' `cmd /c start`, given only the map's own local address.++### What runs without asking++In Claude Code, while the skill is in use, it pre-approves one kind of command: `node` running one of its own scripts (`scripts/build.mjs`, `describe.mjs`, `open.mjs`, `plan.mjs`, `recent.mjs`, `refresh.mjs`, `scan.mjs` and `status.mjs`). That list is fixed by the tests below. Anything else Claude does asks according to your permission settings, as usual. Codex asks according to your approval settings.++### Three things worth explaining++- **`skills/floorplan/assets/vendor/elk.bundled.js`** is a 1.6 MB minified file: the layout engine that arranges the map. It's [elkjs](https://github.com/kieler/elkjs) 0.9.3, byte for byte the same as the official package on npm. Its SHA-256 is `b0745abd7f23cd91690a1587e377edbe19fd7233c783300290936720546216d4`. To check it yourself:+ ```bash+ npm pack [email protected]+ tar -xzf elkjs-0.9.3.tgz package/lib/elk.bundled.js+ ```+ Then compare `package/lib/elk.bundled.js` with Floorplan's copy, for example with `sha256sum` (macOS: `shasum -a 256`; Windows PowerShell: `Get-FileHash`).+- **One `new Function`** in `serve.mjs` loads the map's lookup code from `floorplan/query.mjs`, a file Floorplan's build wrote into your project. It never runs anything from the network.+- **Health reads the middle part of tokens it finds** (it decodes them from base64) to tell what kind of token each is, so it can skip ones that are public by design. It never stores or shows the token itself.++## Checked on every change++[`tests/supply-chain.test.mjs`](../tests/supply-chain.test.mjs) runs on every push and pull request, on Linux and Windows (and weekly on macOS). It fails if a change would:++- add a hook, an MCP server, a dependency or an install script;+- send a request anywhere other than the map's own server and the waitlist;+- start a program not in the table above, or start one through a shell;+- use `eval`, load code at run time, or hide a long encoded string in the code;+- add a script that would run without asking;+- change the bundled layout engine, or add a vendored file.++Each check was tested by planting exactly that kind of change and seeing it fail. A change to any of this has to change the test and this page together, in the open.++To run the same checks on your own copy:++```bash+node --test tests/supply-chain.test.mjs+```++## Check that your installed copy is a real release++Every release includes `CHECKSUMS.txt`: a SHA-256 fingerprint of every file the plugin runs from (the skill, the plugin manifests and the marketplace files). To compare your installed copy with the release on GitHub:++```bash+git clone --depth 1 --branch floorplan--v<version> https://github.com/haydenschmitty/floorplan floorplan-check+node floorplan-check/tools/checksums.mjs --check <installed folder>+```++`<version>` is the version you have (`claude plugin list` or `codex plugin list` shows it). The installed folder is:+- **Claude Code:** `~/.claude/plugins/cache/floorplan/floorplan/<version>`+- **Codex:** `~/.codex/plugins/cache/floorplan/floorplan/<version>`++It prints either that all files are identical, or which ones changed, are extra or are missing.++## The honest limits++- Claude Code and Codex install a plugin from its repository, and an update brings whatever the newest release contains, for this plugin as for any other. Releases are made only by the maintainer. Outside pull requests are reviewed before they're run or merged, and the checks above run on every one of them. Before you update, you can read the changes in the [changelog](../CHANGELOG.md) and verify the new version with its checksums.+- Floorplan works by having Claude or Codex read your code to describe it. That goes to Anthropic or OpenAI under your account, like any other task you give them. See [Privacy and security](privacy-and-security.md).++## Found something?++Please report it privately, as described in the [security policy](../SECURITY.md).diff --git a/docs/privacy-and-security.md b/docs/privacy-and-security.mdindex 2fc822f..0d77ec4 100644--- a/docs/privacy-and-security.md+++ b/docs/privacy-and-security.md@@ -1,5 +1,7 @@# Privacy and security+For what the plugin itself can and can't do on your computer (no hooks, MCP servers, dependencies or downloads, and how to verify your copy), see [Is it safe to install?](is-it-safe.md).+## What runs where| Part | Where it runs | What it sends |diff --git a/tests/release.test.mjs b/tests/release.test.mjsindex 5ed5b09..07eed3d 100644--- a/tests/release.test.mjs+++ b/tests/release.test.mjs@@ -50,3 +50,7 @@ test('the skill has a name and description, and every file it points to exists',for (const [, ref] of skill.matchAll(/\]\((references\/[\w.-]+\.md)/g)) assert.ok(fs.existsSync(path.join(SKILL, ref)), ref);for (const [, script] of skill.matchAll(/scripts\/(\w+\.mjs)/g)) assert.ok(fs.existsSync(path.join(SKILL, 'scripts', script)), script);});++test('CHECKSUMS.txt is for this version, so each release ships its fingerprints', () => {+ assert.match(read('CHECKSUMS.txt'), new RegExp(`^# Floorplan ${plugin.version.replaceAll('.', '\.')}:`), 'run node tools/checksums.mjs when bumping the version');+});diff --git a/tests/supply-chain.test.mjs b/tests/supply-chain.test.mjsnew file mode 100644index 0000000..d0e2b8b--- /dev/null+++ b/tests/supply-chain.test.mjs@@ -0,0 +1,180 @@+// A tripwire for what the plugin can do on someone's computer. docs/is-it-safe.md promises: no hooks, no+// MCP servers, no dependencies or install steps, nothing downloaded or run from the internet, one outbound+// network call (the opt-in waitlist), a fixed list of programs it runs, and vendored files that match their+// published versions. These tests fail if any of that changes, so a change like that can't slip in unnoticed,+// in a pull request or anywhere else. If a change is intended, update this file and docs/is-it-safe.md together.+import { test } from 'node:test';+import assert from 'node:assert/strict';+import fs from 'node:fs';+import path from 'node:path';+import crypto from 'node:crypto';+import { REPO, SKILL } from './helpers.mjs';++/** Relative paths of every file under dir, with forward slashes, leaving out git's own folder and installs. */+const allFiles = (dir) => fs.readdirSync(dir, { recursive: true, withFileTypes: true })+ .filter((e) => e.isFile())+ .map((e) => path.relative(dir, path.join(e.parentPath ?? e.path, e.name)).replace(/\\/g, '/'))+ .filter((f) => !/^(\.git|node_modules)\//.test(f));+const UPDATE = 'If this is intended, update tests/supply-chain.test.mjs and docs/is-it-safe.md together.';+const rel = (f) => path.relative(SKILL, f).replace(/\\/g, '/');+const read = (f) => fs.readFileSync(f, 'utf8');+const json = (p) => JSON.parse(read(path.join(REPO, p)));+const sha256 = (f) => crypto.createHash('sha256').update(fs.readFileSync(f)).digest('hex');++const shipped = allFiles(SKILL).map((f) => path.join(SKILL, f));+const isVendor = (f) => rel(f).startsWith('assets/vendor/');+// the code that runs: scripts, the map's server, the page and its add-ons (not the vendored layout engine)+const code = shipped.filter((f) => /\.(mjs|js|html)$/.test(f) && !isVendor(f));+/** Every match of `re` in the shipped code, as { file, text, line }, skipping comment lines. */+function find(re) {+ const out = [];+ for (const f of code) {+ read(f).split('\n').forEach((line, i) => {+ const t = line.trim();+ if (t.startsWith('//') || t.startsWith('*') || t.startsWith('/*')) return;+ for (const m of line.matchAll(new RegExp(re, 'g'))) out.push({ file: rel(f), text: m[0], line: i + 1, m });+ });+ }+ return out;+}++test('the plugin is only a skill: no hooks, MCP servers or commands that run on their own', () => {+ // .claude/ is the maintainer's own local settings, ignored by git+ const all = allFiles(REPO).filter((f) => !f.startsWith('.claude/'));+ assert.deepEqual(all.filter((f) => /(^|\/)(hooks\.json|\.mcp\.json|\.lsp\.json)$/.test(f) || /(^|\/)hooks\//.test(f)), [], `no hooks or MCP/LSP servers. ${UPDATE}`);+ assert.deepEqual(Object.keys(json('.claude-plugin/plugin.json')).sort(), ['author', 'description', 'homepage', 'keywords', 'license', 'name', 'repository', 'version'], `Claude Code manifest: nothing beyond the skill. ${UPDATE}`);+ assert.deepEqual(Object.keys(json('.codex-plugin/plugin.json')).sort(), ['author', 'description', 'homepage', 'interface', 'keywords', 'license', 'name', 'repository', 'requires_local_executor', 'skills', 'version'], `Codex manifest: nothing beyond the skill. ${UPDATE}`);+ assert.equal(json('.codex-plugin/plugin.json').skills, './skills/');+ // both marketplaces install from this repo itself, never from somewhere else+ assert.deepEqual(json('.claude-plugin/marketplace.json').plugins.map((p) => p.source), ['./']);+ for (const p of json('.agents/plugins/marketplace.json').plugins) assert.equal(typeof p.source === 'string' ? p.source : p.source?.path, './', `Codex marketplace source. ${UPDATE}`);+});++test('nothing to install: no dependencies and no install scripts', () => {+ const pkg = json('package.json');+ for (const k of ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies', 'bundledDependencies']) assert.equal(pkg[k], undefined, `package.json ${k}. ${UPDATE}`);+ assert.deepEqual(pkg.scripts, { test: 'node --test' }, `package.json scripts: only the tests. ${UPDATE}`);+ assert.ok(!allFiles(REPO).some((f) => /(^|\/)(package-lock\.json|yarn\.lock|pnpm-lock\.yaml)$/.test(f)), 'no lockfile, because nothing is installed');+});++test('the only commands pre-approved are the skill’s own scripts, and that list is fixed', () => {+ const front = /^---\n([\s\S]*?)\n---/.exec(read(path.join(SKILL, 'SKILL.md')).replace(/\r\n/g, '\n'))[1];+ assert.equal(/^allowed-tools:\s*(.*)$/m.exec(front)?.[1].trim(), 'Bash(node ${CLAUDE_SKILL_DIR}/scripts/*)', `SKILL.md allowed-tools. ${UPDATE}`);+ // every script there runs without a prompt while the skill is in use, so adding one is a deliberate change+ const scripts = fs.readdirSync(path.join(SKILL, 'scripts')).filter((n) => !fs.statSync(path.join(SKILL, 'scripts', n)).isDirectory()).sort();+ assert.deepEqual(scripts, ['build.mjs', 'describe.mjs', 'open.mjs', 'plan.mjs', 'recent.mjs', 'refresh.mjs', 'scan.mjs', 'status.mjs'], `scripts/ list. ${UPDATE}`);+});++test('it reaches the internet in one place: the waitlist, only when someone signs up', () => {+ // no network modules except the map's own local server+ const netImports = find(/from\s+['"](?:node:)?(https?|http2|net|tls|dgram|dns|undici)['"]|require\(\s*['"](?:node:)?(https?|http2|net|tls|dgram|dns|undici)['"]\s*\)/);+ assert.deepEqual(netImports.map((x) => `${x.file}: ${x.text}`), [`assets/serve.mjs: from 'node:http'`], `network modules. ${UPDATE}`);+ // the server listens on this machine only+ assert.match(read(path.join(SKILL, 'assets', 'serve.mjs')), /server\.listen\(port, '127\.0\.0\.1'\);/);+ assert.doesNotMatch(read(path.join(SKILL, 'assets', 'serve.mjs')), /\.listen\([^)]*(0\.0\.0\.0|::)/);++ // every request: to the map's own server, except the one waitlist call+ const LOCAL = /^(['"`]\/|s\.url \+)/;+ const calls = find(/\bfetch\(\s*([^,)]+)/).map((x) => ({ ...x, arg: x.m[1].trim() }));+ const outside = calls.filter((c) => !LOCAL.test(c.arg));+ assert.deepEqual(outside.map((c) => `${c.file}: fetch(${c.arg}`), ['assets/serve.mjs: fetch(WAITLIST_URL'], `requests that leave this computer. ${UPDATE}`);+ assert.match(read(path.join(SKILL, 'assets', 'serve.mjs')), /const WAITLIST_URL = process\.env\.FLOORPLAN_WAITLIST_URL \|\| 'https:\/\/floorplan-waitlist-690500262396\.us-central1\.run\.app\/';/);+ assert.deepEqual(find(/\b(WebSocket|XMLHttpRequest|sendBeacon|importScripts)\b/).map((x) => `${x.file}: ${x.text}`), [], `other ways to reach a server. ${UPDATE}`);+ assert.deepEqual(find(/new EventSource\(\s*(?!['"`]\/)/).map((x) => `${x.file}:${x.line}`), [], 'live reload only from the local server');++ // the map page loads nothing from the internet: layout engine and fonts are built in+ const page = read(path.join(SKILL, 'assets', 'viewer.html'));+ assert.doesNotMatch(page, /<script[^>]*\ssrc=/i, 'no external scripts');+ assert.doesNotMatch(page, /<link[^>]*href=["']https?:/i, 'no external stylesheets or fonts');+ assert.doesNotMatch(page, /url\(\s*["']?https?:/i, 'no external images or fonts in CSS');+});++test('it runs a fixed list of programs, and never through a shell', () => {+ const importers = find(/from\s+['"](?:node:)?child_process['"]/).map((x) => x.file).sort();+ assert.deepEqual(importers, ['assets/serve.mjs', 'scripts/lib/common.mjs', 'scripts/open.mjs', 'scripts/refresh.mjs'], `files that start programs. ${UPDATE}`);+ // only spawn and execFileSync, which take a program and its arguments (regex .exec() is text matching)+ const names = find(/import\s*\{([^}]*)\}\s*from\s+['"](?:node:)?child_process['"]/).flatMap((x) => x.m[1].split(',').map((n) => n.trim()));+ assert.deepEqual([...new Set(names)].sort(), ['execFileSync', 'spawn'], `child_process functions used. ${UPDATE}`);+ assert.deepEqual(find(/(?<![.\w])(exec|execSync|fork|spawnSync|execFile)\(/).map((x) => `${x.file}:${x.line} ${x.text}`), [], `other ways to start programs. ${UPDATE}`);+ assert.deepEqual(find(/shell:\s*true/).map((x) => `${x.file}:${x.line}`), [], 'never through a shell');+ // what each call starts: where/which, the Claude Code or Codex CLI, Node running the skill's own scripts,+ // git, and the system's "open this address in the browser" command+ const ALLOWED = new Set([+ "process.platform === 'win32' ? 'where' : 'which'",+ 'cli.cmd',+ 'process.execPath',+ 'node',+ "'git'",+ 'opener[0]',+ 'cmd',+ ]);+ const starts = find(/\b(spawn|execFileSync)\(\s*([^,]+),/).map((x) => ({ ...x, prog: x.m[2].trim() }));+ assert.ok(starts.length >= 8, 'found the calls');+ assert.deepEqual(starts.filter((s) => !ALLOWED.has(s.prog)).map((s) => `${s.file}:${s.line} ${s.prog}`), [], `programs started. ${UPDATE}`);+ assert.match(read(path.join(SKILL, 'scripts', 'refresh.mjs')), /const node = process\.execPath;/);+ // the browser openers open the map's local address and nothing else+ const openers = /\? \['cmd', \['\/c', 'start', '', u\]\] : process\.platform === 'darwin' \? \['open', \[u\]\] : \['xdg-open', \[u\]\]/;+ assert.match(read(path.join(SKILL, 'assets', 'serve.mjs')), openers);+ assert.match(read(path.join(SKILL, 'scripts', 'open.mjs')), openers);+});++test('no code is downloaded, decoded or built from text at run time', () => {+ assert.deepEqual(find(/(?<![.\w])eval\(/).map((x) => `${x.file}:${x.line}`), [], `eval. ${UPDATE}`);+ // the one exception: serve.mjs loads the map's own lookup code from floorplan/query.mjs, a file the build wrote+ assert.deepEqual(find(/new Function\(/).map((x) => x.file), ['assets/serve.mjs'], `new Function. ${UPDATE}`);+ assert.match(read(path.join(SKILL, 'assets', 'serve.mjs')), /const coreSrc = fs\.readFileSync\(path\.join\(here, 'query\.mjs'\), 'utf8'\)/);+ assert.deepEqual(find(/\bimport\s*\(/).map((x) => `${x.file}:${x.line}`), [], `dynamic import. ${UPDATE}`);+ assert.deepEqual(find(/from\s+['"](?:node:)?(vm|worker_threads|inspector|wasi)['"]|new Worker\(|WebAssembly\./).map((x) => `${x.file}: ${x.text}`), [], `other ways to run code. ${UPDATE}`);+ // decoding base64: only Health reading the middle of a token it found, to tell what kind of token it is+ assert.deepEqual(find(/\batob\(|['"]base64['"]\s*\)/).filter((x) => x.file !== 'scripts/build.mjs').map((x) => x.file), ['scripts/lib/health.mjs'], `base64 decoding. ${UPDATE}`);+ // no long opaque strings that could hide a payload (the build inlines the logo and fonts from files)+ assert.deepEqual(find(/[A-Za-z0-9+/=]{160,}/).map((x) => `${x.file}:${x.line}`), [], 'long encoded strings');+});++test('every shipped file is source, text or a known kind of image or font', () => {+ const kinds = new Set(shipped.map((f) => path.extname(f).toLowerCase()));+ assert.deepEqual([...kinds].sort(), ['.html', '.js', '.json', '.md', '.mjs', '.png', '.txt', '.woff2', '.yaml'].filter((k) => kinds.has(k)), 'kinds of file');+ for (const k of kinds) assert.ok(['.html', '.js', '.json', '.md', '.mjs', '.png', '.txt', '.woff2', '.yaml'].includes(k), `unexpected kind of file: ${k}. ${UPDATE}`);+});++test('vendored files are unchanged: the layout engine matches elkjs 0.9.3 on npm byte for byte', () => {+ const VENDOR = {+ // npm: [email protected], package/lib/elk.bundled.js+ 'elk.bundled.js': 'b0745abd7f23cd91690a1587e377edbe19fd7233c783300290936720546216d4',+ 'elkjs-LICENSE.md': null,+ 'fonts/inter-LICENSE.txt': null,+ 'fonts/inter-latin-ext-wght-normal.woff2': null,+ 'fonts/inter-latin-wght-normal.woff2': null,+ 'fonts/jetbrains-mono-LICENSE.txt': null,+ 'fonts/jetbrains-mono-latin-ext-wght-normal.woff2': null,+ 'fonts/jetbrains-mono-latin-wght-normal.woff2': null,+ };+ const dir = path.join(SKILL, 'assets', 'vendor');+ assert.deepEqual(allFiles(dir).sort(), Object.keys(VENDOR).sort(), `vendored files. ${UPDATE}`);+ assert.equal(sha256(path.join(dir, 'elk.bundled.js')), VENDOR['elk.bundled.js'], `elk.bundled.js changed. ${UPDATE}`);+});++test('checksums tell an exact copy of a release from a changed one', async () => {+ const { execFileSync } = await import('node:child_process');+ const os = await import('node:os');+ const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'floorplan-checksums-'));+ // fingerprints of this checkout (CHECKSUMS.txt itself is the last release's, so it's left alone)+ const list = path.join(tmp, 'list.txt'), copy = path.join(tmp, 'copy');+ const tool = (...args) => execFileSync(process.execPath, [path.join(REPO, 'tools', 'checksums.mjs'), ...args, '--list', list], { encoding: 'utf8' });+ const run = (dir) => { try { return { ok: true, out: tool('--check', dir) }; } catch (e) { return { ok: false, out: String(e.stdout) }; } };+ try {+ tool();+ // an exact copy of every file it lists+ const listed = read(list).split('\n').filter((l) => /^[0-9a-f]{64} /.test(l)).map((l) => l.slice(66));+ for (const f of listed) { fs.mkdirSync(path.dirname(path.join(copy, f)), { recursive: true }); fs.copyFileSync(path.join(REPO, f), path.join(copy, f)); }+ const same = run(copy);+ assert.ok(same.ok, same.out);+ assert.match(same.out, /all \d+ files are identical/);+ fs.appendFileSync(path.join(copy, 'skills', 'floorplan', 'scripts', 'build.mjs'), '\n// changed\n');+ fs.writeFileSync(path.join(copy, 'skills', 'floorplan', 'scripts', 'extra.mjs'), '');+ const diff = run(copy);+ assert.equal(diff.ok, false);+ assert.match(diff.out, /Changed:\n {2}skills\/floorplan\/scripts\/build\.mjs/);+ assert.match(diff.out, /Not in the release:\n {2}skills\/floorplan\/scripts\/extra\.mjs/);+ } finally { fs.rmSync(tmp, { recursive: true, force: true }); }+});diff --git a/tools/checksums.mjs b/tools/checksums.mjsnew file mode 100644index 0000000..42629f7--- /dev/null+++ b/tools/checksums.mjs@@ -0,0 +1,61 @@+// SHA-256 fingerprints of every file the plugin runs from, so anyone can check that an installed copy is+// exactly a release. Each release commits CHECKSUMS.txt; --check compares a folder with it.+// usage: node tools/checksums.mjs write CHECKSUMS.txt for this checkout+// node tools/checksums.mjs --check <folder> compare an installed copy with CHECKSUMS.txt+// --list <file> reads or writes another list instead of CHECKSUMS.txt (the tests use it).+import fs from 'node:fs';+import path from 'node:path';+import crypto from 'node:crypto';+import { fileURLToPath } from 'node:url';++const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+// what the plugin runs from: the skill, the plugin manifests and the marketplaces that point at them+const PARTS = ['skills', '.claude-plugin', '.codex-plugin', '.agents', 'package.json'];+const li = process.argv.indexOf('--list');+const OUT = li > 0 ? path.resolve(process.argv[li + 1]) : path.join(REPO, 'CHECKSUMS.txt');++function list(root) {+ const out = [];+ for (const part of PARTS) {+ const p = path.join(root, part);+ if (!fs.existsSync(p)) continue;+ if (fs.statSync(p).isFile()) { out.push(part); continue; }+ for (const e of fs.readdirSync(p, { recursive: true, withFileTypes: true })) {+ if (e.isFile()) out.push(path.relative(root, path.join(e.parentPath ?? e.path, e.name)).replace(/\\/g, '/'));+ }+ }+ return out.sort();+}+const hash = (root, f) => crypto.createHash('sha256').update(fs.readFileSync(path.join(root, f))).digest('hex');++const at = process.argv.indexOf('--check');+if (at < 0) {+ const version = JSON.parse(fs.readFileSync(path.join(REPO, '.claude-plugin', 'plugin.json'), 'utf8')).version;+ const lines = list(REPO).map((f) => `${hash(REPO, f)} ${f}`);+ fs.writeFileSync(OUT, [+ `# Floorplan ${version}: SHA-256 of every file the plugin runs from.`,+ `# Check an installed copy: clone this release, then run node tools/checksums.mjs --check <installed folder>.`,+ ...lines, '',+ ].join('\n'));+ console.log(`✓ wrote ${path.basename(OUT)} for Floorplan ${version} (${lines.length} files)`);+ process.exit(0);+}++const dir = process.argv[at + 1];+if (!dir || !fs.existsSync(dir)) { console.error('usage: node tools/checksums.mjs --check <installed plugin folder>'); process.exit(1); }+const text = fs.readFileSync(OUT, 'utf8');+const version = /^# Floorplan (\S+):/m.exec(text)?.[1] || '?';+const want = new Map(text.split('\n').filter((l) => /^[0-9a-f]{64} /.test(l)).map((l) => [l.slice(66), l.slice(0, 64)]));+const have = list(dir);+const changed = have.filter((f) => want.has(f) && want.get(f) !== hash(dir, f));+const extra = have.filter((f) => !want.has(f));+const missing = [...want.keys()].filter((f) => !have.includes(f));+if (!changed.length && !extra.length && !missing.length) {+ console.log(`✓ ${dir} matches Floorplan ${version}: all ${want.size} files are identical.`);+ process.exit(0);+}+console.log(`✗ ${dir} doesn't match Floorplan ${version}.`);+for (const [label, files] of [['Changed', changed], ['Not in the release', extra], ['Missing', missing]]) {+ if (files.length) console.log(`${label}:\n${files.map((f) => ` ${f}`).join('\n')}`);+}+process.exit(1);