@rulecad/cad 0.1.1 → 0.1.3

package/AGENTS.md

@@ -0,0 +1,56 @@
+# Designing with rulecad: notes for AI agents
+
+This project designs physical things with the `cad` command (rulecad). Every measurement is a variable, and every
+variable says which rule it comes from. Follow these steps; they're what makes a design traceable and printable.
+(`npx cad help` lists the commands; the full guide is @rulecad/cad's README.)
+
+## A new part
+1. **Rules first.** Find the facts the part depends on: standards, the thing it fits, the printer. Put shared ones in
+   `rules/<set>.json` with `kind`, `source` and `checked`. Research them, don't guess. Ask the person to measure what
+   can't be looked up, and record it as `"kind": "measured"`; something nobody has published goes in as
+   `"kind": "estimate"`, and the check will flag it.
+2. `npx cad new <project>/<object>`, then write the variables in the .json and the shape in the .js. No numbers in
+   the .js other than 0, 1 and 2: `cad check` fails on any other.
+3. `npx cad check`, then `npx cad preview`, and **look at the preview image** before saying it's done. Check the views
+   from below for anything that fits onto something else.
+4. Mark the variables that matter to the person `show` (six at most, short `label`s), and the ones other parts depend
+   on `interface` (versions follow them). Give sensible `tweak` ranges to the ones they may want to change.
+5. `npx cad export` for printing; `npx cad link --md` for a link to share.
+
+## Changing a design
+1. `npx cad history <project>/<object>` first: read the print log. A failed print is the reason for most changes:
+   fix the rule or variable it points at (a measured fit beats a community rule).
+2. Change, then check, preview and look, as for a new part.
+3. `npx cad release <project>/<object> -m "what changed, for the person" --dry-run` shows the bump and why. If it's
+   major, tell the person which interface values changed: earlier prints may no longer fit.
+4. Release only when the person agrees. Don't use `--force` without asking.
+
+## Shapes
+- Z is up, the bed is z = 0: model the part in its print orientation, and describe it in `orientation`.
+- Walls are whole numbers of print lines (`x1c.line * 3`, or your printer's set), heights whole numbers of layers.
+- Holes and slots get the printer's hole compensation; parts that slide together get its fit clearance. Chamfer
+  bottom edges.
+- An overhang warning means supports: say so in `orientation`, or change the shape or orientation.
+- Something printed under the part and removed afterwards is a named `support` part (`return { cap, pillar }`, both
+  described in the .json's `parts`), not part of the shape. Look at `cad preview --explode` too.
+
+## Alternatives, layouts, colours
+- To try an alternative, add a **variant** (named inputs in the .json) rather than a copy of the object; `cad compare`
+  shows two side by side. Remove trial variants before a release.
+- What differs key by key on a keyboard belongs in a **layout file**, read through `per`. `cad import-kle` brings
+  one in from keyboard-layout-editor.com.
+- A part in another colour is a part with a `filament` from `project.json`: the 3MF puts it on its own AMS slot.
+- Fine detail a screen doesn't need goes in `display` settings (fewer segments, no legends).
+
+## Fits
+- To check how parts go together, make a `fit` assembly with the thing it fits as a `reference` object, and `fits`
+  with ranges from rules. An overlap or gap outside its range is a finding: report it with the numbers, and never
+  widen a range to make it pass without saying why.
+- Build bigger things from checked assemblies used as items, rather than placing their objects again.
+
+## Talking to the person
+- Give links as one labelled line (`npx cad link <project>/<object> --md`), never a raw URL. If it says
+  "(not a release)", say so.
+- Say what the checks found, with numbers. Ask before anything that leaves the computer: releases with `--push`,
+  ordering boards, publishing.
+- Designs are code: only run designs you or the person trust. Links and rule files are data and never run.

package/README.md

@@ -35,6 +35,7 @@ npx cad rules bathroom/soap-tray                 # every variable, its rule and
 npx cad check bathroom/soap-tray --set width=60   # change variables that have a tweak range
 npx cad variants keyboard/keycap                 # named sets of inputs: keyboard/keycap:legend-f
 npx cad compare keyboard/keycap dsa legend-f     # two variants (or releases) side by side
+npx cad import-kle layout.json keyboard/mine     # a layout from keyboard-layout-editor.com, into layouts/
 ```
 
 The keyboard examples below come from the project rulecad grew out of: a keycap, a switch plate, a case and their

package/bin/cad.mjs

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { fmt, loadRuleSet } from '../lib/rules.mjs';
 import { WS, TOOL, paths, config, printerOf } from '../lib/workspace.mjs';
+import { fromKLE } from '@rulecad/keyboard-layout';
 import { target, hasTarget } from '../lib/targets.mjs';
 import { locate, build, pick, lint, readObject, printer, pcbEngine } from '../lib/design.mjs';
 import { git, tags, bump, bigger, newer, compare, snapshot, materialise, files, prints, printsFile, engineId } from '../lib/versions.mjs';
@@ -34,6 +35,8 @@ const VIEW = process.env.CAD_VIEW_URL || config.viewUrl;
 const HELP = `cad: JSCAD designs you can trace, check, share and print (rulecad)
 
   cad new <project>/<object>        start a design from the template (makes the project if needed)
+  cad import-kle <file> <project>/<name>   a keyboard layout from keyboard-layout-editor.com, into layouts/
+  cad agents                        AGENTS.md: how an AI agent should design in this workspace
   cad rules <project>/<object>      every variable: value, the rule behind it, its source
   cad check <project>/<object>      raw numbers in the design, then printability (exit 1 on a failure)
   cad preview <project>/<object>    four views as a PNG in .preview/ (prints the path)
@@ -96,6 +99,26 @@ async function main() {
     return console.log(`made projects/${project}/objects/${name}.{js,json}`);
   }
 
+  if (cmd === 'agents') { // the notes for AI agents, into this workspace (AGENTS.md, and CLAUDE.md pointing at it)
+    const to = path.join(WS, 'AGENTS.md');
+    fs.copyFileSync(path.join(TOOL, 'AGENTS.md'), to);
+    const claude = path.join(WS, 'CLAUDE.md');
+    if (!fs.existsSync(claude)) fs.writeFileSync(claude, '@AGENTS.md\n');
+    else if (!fs.readFileSync(claude, 'utf8').includes('@AGENTS.md')) fs.appendFileSync(claude, '\n@AGENTS.md\n');
+    return console.log(`wrote ${path.relative(process.cwd(), to) || 'AGENTS.md'}: how an AI agent should design here (CLAUDE.md includes it)`);
+  }
+  if (cmd === 'import-kle') { // a layout from keyboard-layout-editor.com into a project's layouts/
+    const [project, name] = String(args[2] || '').split('/');
+    if (!ref || !fs.existsSync(ref) || !project || !/^[a-z][a-z0-9-]*$/.test(name || '')) throw new Error('usage: cad import-kle <layout.json> <project>/<name> (the JSON download, or a file with its Raw data)');
+    const { layout, notes } = fromKLE(fs.readFileSync(ref, 'utf8'));
+    const to = path.join(paths.project(project), 'layouts', `${name}.json`);
+    if (fs.existsSync(to) && !opt('force')) throw new Error(`${path.relative(WS, to)} already exists (--force to replace it)`);
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    fs.writeFileSync(to, `${JSON.stringify({ title: layout.title || name, ...layout }, null, 1)}\n`);
+    console.log(`made ${path.relative(WS, to)}: ${layout.rows.length} rows, ${layout.rows.flat().filter((k) => !k.gap).length} keys`);
+    for (const n of notes) console.log(`  note: ${n}`);
+    return;
+  }
   if (cmd === 'status') return status(ref);
   if (!ref) throw new Error(`usage: cad ${cmd} <project>/<object>`);
   if (cmd === 'release') return ref.includes('/') ? releaseObject(locate(ref)) : opt('all') ? releaseAll(ref) : releaseProject(ref);

package/lib/versions.mjs

@@ -65,15 +65,16 @@ export function materialise(d, version) {
 // ---------- what changed: compare() is @rulecad/versions' (exported above) ----------
 
 // The board engine's identity: its code and the tscircuit it runs on. A board's release tag records it ("engine: …").
-// A package's version, from the package.json above its entry point (some packages don't export their package.json)
-export function packageVersion(name) {
-  for (let dir = path.dirname(createRequire(import.meta.url).resolve(name)); dir !== path.dirname(dir); dir = path.dirname(dir)) {
+// A package's version, from the package.json above its entry point (some packages don't export their package.json).
+// from: where to look from (a file URL), when it's another package's dependency, as tscircuit is the board engine's
+export function packageVersion(name, from = import.meta.url) {
+  for (let dir = path.dirname(createRequire(from).resolve(name)); dir !== path.dirname(dir); dir = path.dirname(dir)) {
     const f = path.join(dir, 'package.json');
     if (fs.existsSync(f)) { const pj = JSON.parse(fs.readFileSync(f, 'utf8')); if (pj.name === name) return pj.version; }
   }
   return '';
 }
-const tscircuitVersion = () => packageVersion('tscircuit');
+const tscircuitVersion = () => packageVersion('tscircuit', import.meta.resolve('@rulecad/pcb'));
 const engineHash = (code) => crypto.createHash('sha256').update(`${code.trimEnd()}\n${tscircuitVersion()}`).digest('hex').slice(0, 16);
 export const engineId = () => engineHash(fs.readFileSync(new URL(import.meta.resolve('@rulecad/pcb')), 'utf8'));
 // From a tag's message, or for releases before tags recorded it, from the engine's code in the repo at the tag

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulecad/cad",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "The cad command: JSCAD designs from traceable rules, checked for printing and fit, versioned by what fits, shared as links and exported as Bambu 3MF.",
   "type": "module",
   "bin": {
@@ -22,7 +22,8 @@
     "lib",
     "templates",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "AGENTS.md"
   ],
   "license": "MIT",
   "keywords": [
@@ -43,7 +44,7 @@
   },
   "dependencies": {
     "@rulecad/variables": "^0.1.0",
-    "@rulecad/keyboard-layout": "^0.1.0",
+    "@rulecad/keyboard-layout": "^0.1.2",
     "@rulecad/printcheck": "^0.1.0",
     "@rulecad/fit": "^0.1.0",
     "@rulecad/model-link": "^0.1.0",