@rulecad/cad 0.0.0-stage → 0.1.0

package/lib/preview.mjs

@@ -0,0 +1,49 @@
+// preview(parts, { title, meta, out, explode }) -> out: a 1800 × 1200 PNG of six views (front, side, 3/4, top, bottom, 3/4 below),
+// parts: [{ name, role, label, item, triangles }]; supports and references are drawn faint (lines only); explode drops
+// supports below and, in an assembly, lifts each kind of object above the one before (plate, switches, keycaps).
+// rendered by headless Chrome from lib/preview/page.html, served on this Mac only for the few seconds it takes.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import http from 'node:http';
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { TOOL } from './workspace.mjs';
+
+// Any Chrome or Chromium: $CAD_CHROME, else the usual places on macOS, Linux and Windows
+const CHROME = process.env.CAD_CHROME || [
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  '/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium', '/usr/bin/chromium-browser', '/opt/pw-browsers/chromium',
+  'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+].find((f) => fs.existsSync(f));
+const THREE = path.dirname(createRequire(import.meta.url).resolve('three')); // wherever npm put it
+
+export async function preview(parts, { title = '', meta = '', out, explode = false }) {
+  const flat = (tris) => { const positions = []; for (const t of tris) for (let i = 1; i < t.length - 1; i++) positions.push(...t[0], ...t[i], ...t[i + 1]); return positions; };
+  const data = JSON.stringify({ title, meta, explode, parts: parts.map((p) => ({ name: p.name, role: p.role, label: p.label, item: p.object || p.item, positions: flat(p.triangles) })) });
+  const server = http.createServer((req, res) => {
+    const u = new URL(req.url, 'http://x').pathname;
+    const send = (type, body) => { res.writeHead(200, { 'Content-Type': type }); res.end(body); };
+    if (u === '/') return send('text/html', fs.readFileSync(path.join(TOOL, 'lib/preview/page.html')));
+    if (u === '/data.json') return send('application/json', data);
+    const f = path.join(THREE, path.basename(u)); // only three's build files
+    if (u.startsWith('/three/') && fs.existsSync(f)) return send('text/javascript', fs.readFileSync(f));
+    res.writeHead(404); res.end();
+  });
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  const profile = fs.mkdtempSync(path.join(os.tmpdir(), 'cad-preview-'));
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  try {
+    await new Promise((resolve, reject) => {
+      if (!CHROME) return reject(new Error('no Chrome or Chromium found for previews: set CAD_CHROME to one'));
+      const p = spawn(CHROME, ['--headless=new', `--user-data-dir=${profile}`, '--no-first-run', '--hide-scrollbars', '--force-device-scale-factor=1',
+        '--window-size=1800,1200', '--virtual-time-budget=8000', `--screenshot=${out}`, `http://127.0.0.1:${server.address().port}/`], { stdio: 'ignore' });
+      const t = setTimeout(() => { p.kill(); reject(new Error('Chrome took too long to render the preview')); }, 60000);
+      p.on('exit', () => { clearTimeout(t); fs.existsSync(out) ? resolve() : reject(new Error('Chrome made no screenshot')); });
+    });
+  } finally {
+    server.close();
+    fs.rmSync(profile, { recursive: true, force: true });
+  }
+  return out;
+}

package/lib/rules.mjs

@@ -0,0 +1,25 @@
+// Rules from files: the variables and expressions of @rulecad/variables, with rule sets read from the workspace's rules/
+// (then the tool's) by name. Everything but loading is in @rulecad/variables, which needs no files and runs anywhere.
+import fs from 'node:fs';
+import path from 'node:path';
+import { RULE_DIRS, WS } from './workspace.mjs';
+import { resolve as resolveWith } from '@rulecad/variables';
+
+export { ANCHORS, isName, options, checkName, evaluate, fmt } from '@rulecad/variables';
+
+// dir: one folder (a release's own rules), else the workspace's rules, then the tool's. A rule set the tool provides
+// is copied into the workspace the first time it's used: the workspace keeps every rule its designs depend on (so a
+// release can record them in git), and your own measurements are edits to your copy.
+export function loadRuleSet(name, dir) {
+  const file = (dir ? [dir] : RULE_DIRS).map((d) => path.join(d, `${name}.json`)).find((f) => fs.existsSync(f));
+  if (!file) throw new Error(`no rule set "${name}" (rules/${name}.json)`);
+  const own = path.join(WS, 'rules', `${name}.json`);
+  if (!dir && file !== own) {
+    fs.mkdirSync(path.dirname(own), { recursive: true });
+    fs.copyFileSync(file, own);
+    console.error(`copied the ${name} rule set into rules/${name}.json: yours to keep and edit`);
+  }
+  return JSON.parse(fs.readFileSync(own, 'utf8'));
+}
+// resolve() as @rulecad/variables describes it, loading the rule sets it isn't handed
+export const resolve = (object, opts = {}) => resolveWith(object, { load: loadRuleSet, ...opts });

package/lib/targets/gist.mjs

@@ -0,0 +1,7 @@
+// Short links through a secret GitHub Gist (unlisted: only people with the link find it), made with the gh command.
+import { execFileSync } from 'node:child_process';
+
+export async function shorten(data, { desc }) {
+  const out = execFileSync('gh', ['gist', 'create', '--filename', 'model.txt', '--desc', desc, '-'], { input: data, encoding: 'utf8' }).trim();
+  return out.split('/').pop();
+}

package/lib/targets.mjs

@@ -0,0 +1,21 @@
+// Targets: optional extras the command hands work to, named in cad.config.json's "targets". A name is one of lib/targets/
+// (gist) or a module path relative to the workspace, so anyone can add their own (a smart mirror, a slicer, a printer).
+//   show:    export async function show({ title, ttl, mesh, card }) puts a model somewhere to look at.
+//              mesh: { polygons } (one solid) or { shapes, place } (each shape once, then a 3 × 4 transform per copy);
+//              card: { title, items } (short lines) to go with it
+//   shorten: export async function shorten(data, { desc }) stores a model link's data and returns an ID for #s=<id>
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { WS, config } from './workspace.mjs';
+
+export const hasTarget = (kind) => !!config.targets?.[kind];
+
+export async function target(kind) {
+  const name = config.targets?.[kind];
+  if (!name) throw new Error(`no "${kind}" target: name one in cad.config.json ("targets": { "${kind}": … })`);
+  const own = new URL(`./targets/${name}.mjs`, import.meta.url);
+  const mod = await import(fs.existsSync(own) ? own : pathToFileURL(path.resolve(WS, name)).href);
+  if (typeof mod[kind] !== 'function') throw new Error(`target ${name} has no ${kind}()`);
+  return mod[kind];
+}

package/lib/threemf.mjs

@@ -0,0 +1,7 @@
+// Print files: the 3MF writer the model page uses too (bambu3mf in @rulecad/model-link, which describes the layout), so
+// a file from `cad export` and one downloaded from the page are the same kind of file.
+//   await threemf([{ name, parts: [{ name, triangles, slot }] }], { centre }) -> Uint8Array (a zip)
+export { bambu3mf as threemf, mesh } from '@rulecad/model-link';
+
+// The AMS slot for a part, from the project's filaments ({ "base": { "slot": 1 }, "legend": { "slot": 2 } })
+export const slotOf = (filaments = {}, name) => filaments[name || 'base']?.slot || filaments.base?.slot || 1;

package/lib/versions.mjs

@@ -0,0 +1,103 @@
+// Versions: semver per object, kept as git tags (keyboard/keycap@1.2.0), so any release can be rebuilt exactly.
+//   major: an earlier print may no longer fit: an interface variable changed or went away
+//   minor: something added that doesn't break fits: a new interface variable or a new tweakable option
+//   patch: anything else (print quality, tolerances that aren't interface, the shape's code, the rules it uses)
+// A project release (keyboard@1.0.0) records which version of each object it contains.
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import crypto from 'node:crypto';
+import { resolve, loadRuleSet } from './rules.mjs';
+import { WS, paths } from './workspace.mjs';
+import { readLayout, hasLayout } from './layout.mjs';
+import { newer } from '@rulecad/versions';
+
+export const git = (...args) => execFileSync('git', args, { cwd: WS, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trimEnd();
+
+// ---------- semver: @rulecad/versions ----------
+export { parse, bump, newer, bigger, compare } from '@rulecad/versions';
+
+// ---------- tags ----------
+// tags('keyboard', 'keycap') -> releases, oldest first: { version, tag, date, kind, message }. tags('keyboard') -> project releases.
+export function tags(project, name) {
+  const prefix = name ? `${project}/${name}@` : `${project}@`;
+  let out;
+  try { out = git('for-each-ref', `refs/tags/${prefix}*`, '--format=%(refname:strip=2)%09%(creatordate:short)%09%(contents:subject)'); }
+  catch (e) { if (/not a git repository/.test(e.stderr || e.message)) return []; throw e; } // a workspace outside git: no releases yet
+  return out.split('\n').filter(Boolean).map((l) => {
+    const [tag, date, subject = ''] = l.split('\t'), [, kind, message] = subject.match(/^(major|minor|patch|first): (.*)$/) || [, '', subject];
+    return { tag, version: tag.slice(prefix.length), date, kind, message };
+  }).filter((t) => /^\d+\.\d+\.\d+$/.test(t.version)).sort((a, b) => (newer(a.version, b.version) ? 1 : -1));
+}
+
+// The layout files an object can pick (its layout variables' choices that are files), by name
+const layoutNames = (d, object) => Object.values(object.variables || {}).filter((v) => v.type === 'layout')
+  .flatMap((v) => v.choice || [v.value]).filter((n) => hasLayout(d.project, n, d.layoutsDir));
+
+// The files a design depends on, relative to the workspace (its git repo): its .js and .json, the rule sets and the layouts it uses.
+// (A board's engine is the tool's code, not the workspace's: its release records engineId() instead.)
+export function files(d, object) {
+  return [path.relative(WS, d.js), path.relative(WS, d.json), ...(object.uses || []).map((u) => `rules/${u}.json`),
+    ...layoutNames(d, object).map((n) => `projects/${d.project}/layouts/${n}.json`)];
+}
+
+// A released version's files, written under .versions/ so its imports still find node_modules. -> a design to build
+export function materialise(d, version) {
+  const tag = `${d.project}/${d.name}@${version}`;
+  try { git('rev-parse', '--verify', `refs/tags/${tag}`); } catch { throw new Error(`no release ${tag} (releases: ${tags(d.project, d.name).map((t) => t.version).join(', ') || 'none'})`); }
+  const base = paths.versions(d.project, `${d.name}@${version}`);
+  const show = (rel) => git('show', `${tag}:${rel}`);
+  const object = JSON.parse(show(path.relative(WS, d.json)));
+  fs.mkdirSync(path.join(base, 'rules'), { recursive: true });
+  const js = path.join(base, `${d.name}.js`), json = path.join(base, `${d.name}.json`);
+  fs.writeFileSync(js, show(path.relative(WS, d.js)));
+  fs.writeFileSync(json, JSON.stringify(object, null, 2));
+  for (const u of object.uses || []) fs.writeFileSync(path.join(base, 'rules', `${u}.json`), show(`rules/${u}.json`));
+  // The layouts it could pick, as they were then (only files that existed in that release)
+  fs.mkdirSync(path.join(base, 'layouts'), { recursive: true });
+  for (const v of Object.values(object.variables || {})) if (v.type === 'layout') for (const n of v.choice || [v.value]) {
+    try { fs.writeFileSync(path.join(base, 'layouts', `${n}.json`), show(`projects/${d.project}/layouts/${n}.json`)); } catch {} // a built-in (grid)
+  }
+  return { ...d, js, json, rulesDir: path.join(base, 'rules'), layoutsDir: path.join(base, 'layouts'), version, tag };
+}
+
+// ---------- 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)) {
+    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 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
+function taggedEngine(tag) {
+  const m = git('tag', '-l', '--format=%(contents)', tag).match(/^engine: (\w+)$/m);
+  if (m) return m[1];
+  try { return engineHash(git('show', `${tag}:lib/pcb.mjs`)); } catch { return ''; } // (the engine once lived in the workspace)
+}
+
+// Resolve a design as it is on disk, or as materialised from a release.
+export function snapshot(d) {
+  const object = JSON.parse(fs.readFileSync(d.json, 'utf8'));
+  const sets = d.rulesDir ? Object.fromEntries((object.uses || []).map((u) => [u, loadRuleSet(u, d.rulesDir)])) : {};
+  const layouts = Object.fromEntries(layoutNames(d, object).map((n) => [n, readLayout(d.project, n, d.layoutsDir)]));
+  // A board is also made by the board engine (footprints, the router): which engine, as recorded at the release
+  const engine = object.engine === 'pcb' ? (d.tag ? taggedEngine(d.tag) : engineId()) : null;
+  return { object, entries: resolve(object, { sets }).entries, js: fs.readFileSync(d.js, 'utf8'), layouts, ...(engine != null ? { engine } : {}) };
+}
+
+// ---------- prints log ----------
+// projects/<project>/prints.jsonl: one JSON object a line: { date, object, version, set, material, result, note }
+export const printsFile = (d) => path.join(d.dir, 'prints.jsonl');
+export function prints(d) {
+  const f = printsFile(d);
+  if (!fs.existsSync(f)) return [];
+  return fs.readFileSync(f, 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l)).filter((p) => !d.name || p.object === d.name);
+}

package/lib/workspace.mjs

@@ -0,0 +1,45 @@
+// Where things are. The tool (TOOL: this package: lib/, templates/) and the workspace (WS: your projects, your rules,
+// and what's generated) are separate folders.
+//   The workspace is $CAD_WORKSPACE, else the nearest folder at or above the current one with a cad.config.json, else
+//   the current folder.
+//   cad.config.json: { "printer": "x1c", "viewUrl": "https://…/", "targets": { "show": "targets/show.mjs", "shorten": "gist" } }
+//     printer   the rule set a print is checked against (bed, overhang, bridges); a project.json's "printer" wins
+//     viewUrl   the model page that links open (the public one by default: it reads links as data, nothing is uploaded)
+//     targets   optional extras: show (put a model on display: a module of your own) and shorten (short links: "gist")
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const TOOL = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..');
+
+function find() {
+  if (process.env.CAD_WORKSPACE) return path.resolve(process.env.CAD_WORKSPACE);
+  for (let dir = process.cwd(); ; dir = path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, 'cad.config.json'))) return dir;
+    if (dir === path.dirname(dir)) return process.cwd(); // none: where you are
+  }
+}
+
+export const WS = find();
+export const config = (() => {
+  const f = path.join(WS, 'cad.config.json');
+  return { printer: 'x1c', viewUrl: 'https://jonibach.github.io/mirror-cad-view/', targets: {}, ...(fs.existsSync(f) ? JSON.parse(fs.readFileSync(f, 'utf8')) : {}) };
+})();
+
+// Rule sets: the workspace's own first (your copies, with your measurements), then the published ones (@rulecad/rules).
+export const RULE_DIRS = [...new Set([path.join(WS, 'rules'), path.dirname(fileURLToPath(import.meta.resolve('@rulecad/rules/x1c.json')))])];
+
+export const paths = {
+  projects: path.join(WS, 'projects'),
+  project: (p) => path.join(WS, 'projects', p),
+  cache: (...p) => path.join(WS, '.cache', ...p),
+  preview: (...p) => path.join(WS, '.preview', ...p),
+  exports: (...p) => path.join(WS, 'exports', ...p),
+  versions: (...p) => path.join(WS, '.versions', ...p),
+};
+
+// The printer a project's prints are checked against
+export const printerOf = (project) => {
+  const f = project && path.join(paths.project(project), 'project.json');
+  return (f && fs.existsSync(f) && JSON.parse(fs.readFileSync(f, 'utf8')).printer) || config.printer;
+};

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@rulecad/cad",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "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": {
+    "cad": "bin/cad.mjs"
+  },
+  "exports": {
+    "./workspace": "./lib/workspace.mjs",
+    "./rules": "./lib/rules.mjs",
+    "./design": "./lib/design.mjs",
+    "./layout": "./lib/layout.mjs",
+    "./assembly": "./lib/assembly.mjs",
+    "./versions": "./lib/versions.mjs",
+    "./preview": "./lib/preview.mjs",
+    "./targets": "./lib/targets.mjs",
+    "./threemf": "./lib/threemf.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "cad",
+    "jscad",
+    "3d-printing",
+    "bambu-lab",
+    "parametric",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=20.6"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JoniBach/rulecad.git",
+    "directory": "packages/cad"
+  },
+  "dependencies": {
+    "@rulecad/variables": "^0.1.0",
+    "@rulecad/keyboard-layout": "^0.1.0",
+    "@rulecad/printcheck": "^0.1.0",
+    "@rulecad/fit": "^0.1.0",
+    "@rulecad/model-link": "^0.1.0",
+    "@rulecad/versions": "^0.1.0",
+    "@rulecad/shapes": "^0.1.0",
+    "@rulecad/rules": "^0.1.0",
+    "@jscad/modeling": "^2.12.0",
+    "fflate": "^0.8.2",
+    "three": "^0.186.1"
+  },
+  "peerDependencies": {
+    "@rulecad/pcb": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@rulecad/pcb": {
+      "optional": true
+    }
+  }
+}

package/templates/object.js

@@ -0,0 +1,9 @@
+// NAME. Every measurement is a variable in NAME.json; this file only says how they combine.
+// Z is up and the bed is z = 0: build the shape the way it will print.
+import jscad from '@jscad/modeling'
+const { cuboid } = jscad.primitives
+const { translate } = jscad.transforms
+
+export function main (v) {
+  return translate([0, 0, v.height / 2], cuboid({ size: [v.width, v.depth, v.height] }))
+}

package/templates/object.json

@@ -0,0 +1,14 @@
+{
+  "name": "NAME",
+  "title": "NAME",
+  "version": "0.1.0",
+  "uses": ["x1c"],
+  "material": "PLA",
+  "orientation": "Flat side down on the bed.",
+  "variables": {
+    "width": { "value": 40, "unit": "mm", "rule": "Overall width", "label": "Width", "show": true, "tweak": { "min": 10, "max": 200 } },
+    "depth": { "value": 30, "unit": "mm", "rule": "Overall depth", "label": "Depth", "show": true, "tweak": { "min": 10, "max": 200 } },
+    "height": { "value": "x1c.layer * 50", "unit": "mm", "rule": "Overall height: a whole number of layers", "label": "Height", "show": true },
+    "chamfer": { "value": "x1c.chamfer", "unit": "mm", "rule": "Bottom edges are chamfered, not rounded" }
+  }
+}