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 arch fix can apply), and verifiable without ever looking at an image (arch describe).

Setup (zero-install)

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

npx @chanmeng666/archlang help

(Or npm i -g @chanmeng666/archlang to get a persistent arch binary.)

The loop (always follow this)

1. Learn the language first. Run arch spec and read it — the entire language in one page (~2k tokens). (arch 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: arch compile plan.arch -o plan.svg --json. The JSON is { ok, diagnostics, summary }.
4. Auto-fix the mechanical faults: if ok is false, run arch 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: arch compile plan.arch -f txt (or arch preview plan.arch --ascii) prints a zero-dependency ASCII floor plan you can read straight from stdout.
6. Verify intent: arch 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.
7. Gate on soundness — don't ship a flagged plan. arch 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 arch 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 arch 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: arch 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. Show the user: arch preview plan.arch -o plan.png renders a PNG (--install fetches the optional renderer if missing).