archlang

ArchLang — author floor plans as code

ArchLang turns a small .arch text file into a professional floor-plan drawing. It is built for agents: deterministic, self-correcting (errors carry a machine code, a prose fix, and often a machine-applicable fix archlang fix can apply), and verifiable without ever looking at an image (archlang describe).

Setup (zero-install)

The CLI runs straight from npm — no clone, no build:

npx -y @chanmeng666/archlang --help

Or npm i -g @chanmeng666/archlang for a global archlang command. Every call below is written archlang <cmd>; without the global install, write npx -y @chanmeng666/archlang <cmd>. Never run a bare arch: the package installs it as an alias, but on Linux, macOS and Git Bash coreutils owns that name, so the shell runs the wrong program.

The loop (always follow this)

1. Learn the language first. Run archlang spec and read it — the entire language in one page. (archlang context prints everything: spec + this workflow + CLI reference + error catalog.) Do this before writing any .arch.
2. Write the plan to a .arch file (or pipe via stdin with -), preferring the placement sugar below so you never hand-compute a coordinate.
3. Render it: archlang compile plan.arch -o plan.svg --json. The JSON is { ok, diagnostics, summary }.
4. Auto-fix the mechanical faults: if ok is false, run archlang fix plan.arch --dry-run --json to preview the machine-applicable edits (off-wall opening → attachment form, out-of-range position clamped, …), then re-run without --dry-run to apply. Anything fix can't resolve stays in diagnostics[].fix for you to edit by hand. Exit code 2 means a deterministic user error — fix it, don't blindly retry (1 = IO/internal, 3 = bad usage).
5. See the plan without an image: archlang compile plan.arch -f txt (or archlang preview plan.arch --ascii) prints a zero-dependency ASCII floor plan you can read straight from stdout.
6. Verify intent: archlang describe plan.arch --json returns the rooms (areas, adjacency), what each door connects, and totals. Confirm the room count, labels, and areas match what was asked. Each room reports two areas: area_m2 on wall centrelines and net_area_m2, the floor no wall stands on (the room less every wall band inside it, computed exactly, or absent when it cannot be, and then so is the net total); totals sums both. Quote net_area_m2 as floor area, and name which figure you report.
7. Gate on soundness — don't ship a flagged plan. archlang validate plan.arch --strict --json (parse + resolve + lint). --strict makes every advisory warning fail (exit 2) — the gate a generation pipeline runs before it ships. Add --graph g.json to also assert the intended room-to-room adjacency ({ "living": ["kitchen","hall"], … }); a mismatch fails. Read each diagnostics[].fix, edit, and re-run until it passes — or, if a warning is deliberate, say so.
8. Check the plan against the brief. Write the user's brief as an intent.json — its checkable expectations as data (room count, per-room concepts with area/window bands, total area, optional adjacency/reachability). Two disciplines keep it brief-grounded: assert an area band only where the brief gives a number ("about/~N" → ±10%; "at least N" → min only; qualitative words → nothing), and assert the top-level room count only when the brief enumerates the rooms. Gate with archlang validate plan.arch --intent intent.json --feedback --json: a gating miss (room count/existence/area/total-area/window) fails (exit 2) with a per-violation correction prompt — iterate on the feedback and re-run. Adjacency/reachability are advisory (reported, never fail the gate). Use archlang score plan.arch --brief intent.json --json as a continuous satisfaction meter (always exit 0) to watch the plan approach the brief across edits. See /intent.schema.json.
9. Fix furniture geometry: archlang repair plan.arch -o fixed.arch pushes furniture out of walls/doorways/swing arcs (the geometric corrector; distinct from fix). It rewrites a piece in the form you wrote it (an at point, or the inset of an in <room> anchor … placement) — and always read unresolved: a piece it may not rewrite (one for/component statement drawing several pieces, expression coordinates, an against wall anchor) is reported there with the fault and why, never silently skipped. changed: false with a non-empty unresolved means you edit the source.
10. Finish the drawing: once lint is clean, run archlang finish plan.arch --dry-run --json, then without --dry-run to apply. It first furnishes each rectangular room that holds no furniture, by the room's use (single-storey plans; a furnished room is never touched — a partly furnished one is named in unresolved with the categories it lacks, not topped up), then adds the sheet statements the plan lacks — paper, scale, dims auto, title, schedule rooms, legend — on the smallest sheet the drawing fits. It fills only what is missing and deletes nothing. Read unresolved: a room it left empty or a statement it left out is named there with the reason (--only furnish/--only sheet runs one step; --reissue lets it replace a paper/scale the drawing does not fit).
11. Show the user: archlang preview plan.arch -o plan.png renders a PNG (--install fetches the optional renderer if missing). To hand the user the plan itself, rendered and with nothing to install, run archlang link plan.arch (or npx -y @chanmeng666/archlang link plan.arch): it prints a playground URL that opens the plan; --json adds the embed URL.