cadorange 0.2.0 → 0.3.0

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+//#region src/cli.d.ts
+/**
+ * `cado` CLI — run / describe / export models from the command line.
+ *
+ * Skeleton stage: only --help works; subcommands land with the M0 milestone.
+ */
+/** Entry point, exported for tests. Returns the desired process exit code. */
+export declare function main(argv: string[]): number;
+//#endregion

package/dist/cli.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+//#region src/cli.ts
+/**
+* `cado` CLI — run / describe / export models from the command line.
+*
+* Skeleton stage: only --help works; subcommands land with the M0 milestone.
+*/
+const USAGE = `cado — agent-native CAD CLI (M0 skeleton)
+
+Usage:
+  cado run <model.ts> [--render iso,top,front] [--export step,stl]
+  cado describe <model.ts> [--json]
+  cado --help
+
+Subcommands are not implemented yet. See the roadmap in the repository README.
+`;
+/** Entry point, exported for tests. Returns the desired process exit code. */
+function main(argv) {
+	const [cmd] = argv;
+	if (!cmd || cmd === "--help" || cmd === "-h") {
+		process.stdout.write(USAGE);
+		return cmd ? 0 : 1;
+	}
+	process.stderr.write(`cado: "${cmd}" is not implemented yet (M0 skeleton)\n`);
+	return 1;
+}
+if (typeof process !== "undefined" && (process.argv[1]?.endsWith("cli.ts") || process.argv[1]?.endsWith("cli.js"))) process.exitCode = main(process.argv.slice(2));
+//#endregion
+export { main };

package/dist/index-DzJsXME9.d.ts

@@ -0,0 +1,108 @@
+import { a as ShapeList, f as ShapeHandle, i as Shape, n as Edge, o as Solid, r as Face, y as Loc } from "./index-DceghC4N.js";
+import "occt.ts";
+//#region src/io/index.d.ts
+type ExportFormat = "step" | "stl" | "glb";
+declare function exportStep(s: Shape): Uint8Array;
+declare function exportStl(s: Shape, tolerance?: number): string;
+declare function exportGlb(s: Shape): Uint8Array;
+declare function importStep(data: Uint8Array | string): Promise<Solid>;
+/** Writes a shape to disk (Node). Extension picks the format. */
+declare function exportShape(s: Shape, path: string, opts?: {
+  tolerance?: number;
+}): Promise<void>;
+//#endregion
+//#region src/kernel/occt.d.ts
+interface InitOptions {
+  /** Explicit URL or path to the OCCT WASM binary (file, http(s) or data:). */
+  wasmUrl?: string;
+}
+/** Loads the OCCT WASM kernel exactly once per process (idempotent). */
+declare function init(opts?: InitOptions): Promise<void>;
+//#endregion
+//#region src/ops/index.d.ts
+declare function fuse(a: Solid, b: Shape, opts?: {
+  clean?: boolean;
+}): Solid;
+declare function cut(a: Solid, b: Shape, opts?: {
+  clean?: boolean;
+}): Solid;
+/** build123d `intersect` — OCCT `common`. */
+declare function intersect(a: Solid, b: Shape, opts?: {
+  clean?: boolean;
+}): Solid;
+/** Keep the OCCT name for code translated from CadQuery. */
+declare const common: typeof intersect;
+declare function fillet(s: Shape, edges: ShapeList<Edge> | readonly Edge[], radius: number): Solid;
+/** Equal-distance chamfer; asymmetric needs kernel support (R3). */
+declare function chamfer(s: Shape, edges: ShapeList<Edge> | readonly Edge[], distance: number): Solid;
+declare function translate(s: Shape, by: readonly [number, number, number]): Solid;
+/** M1: extrude a 2D sketch into a solid. */
+declare function extrude(_sketch: unknown, _height: number): Solid;
+/** M1: revolve a 2D sketch around an axis. */
+declare function revolve(_sketch: unknown, _axis: unknown, _angle?: number): Solid;
+//#endregion
+//#region src/primitives/index.d.ts
+declare function Box(dx: number, dy: number, dz: number, loc?: Loc): Solid;
+declare function Cylinder(opts: {
+  radius: number;
+  height: number;
+  loc?: Loc;
+}): Solid;
+declare function Sphere(opts: {
+  radius: number;
+  loc?: Loc;
+}): Solid;
+declare function Cone(opts: {
+  radius1: number;
+  radius2: number;
+  height: number;
+  loc?: Loc;
+}): Solid;
+declare function Torus(opts: {
+  radius1: number;
+  radius2: number;
+  loc?: Loc;
+}): Solid;
+//#endregion
+//#region src/record.d.ts
+/**
+ * Op recording — the day-one rule from docs/architecture.md §3.3:
+ * every mutating core operation goes through `record()`, so the runtime
+ * Session/OpLog can observe, snapshot and replay the exact same stream
+ * regardless of which API style (core algebra or workplane facade) produced it.
+ *
+ * With no subscribers installed this is a transparent pass-through.
+ */
+interface OpRecord {
+  /** Monotonic, process-wide — the id the OpLog keys snapshots by. */
+  readonly id: number;
+  readonly type: string;
+  readonly args: unknown;
+}
+type OpStatus = "done" | "error";
+interface OpEvent {
+  readonly op: OpRecord;
+  readonly status: OpStatus;
+  readonly result?: ShapeHandle;
+  readonly error?: unknown;
+}
+type OpListener = (event: OpEvent) => void;
+/** Subscribe to every recorded operation. Returns an unsubscribe function. */
+declare function onOp(listener: OpListener): () => void;
+/**
+ * Runs `run()` and records it as one op. Errors propagate unchanged after
+ * being recorded — structured error mapping (runtime) subscribes via onOp.
+ */
+declare function record<T>(type: string, args: unknown, run: () => T): T;
+//#endregion
+//#region src/selectors/index.d.ts
+type SubShape = Face | Edge;
+interface Selector {
+  /** The source string, for error messages and op-log readability. */
+  readonly source: string;
+  select(items: readonly SubShape[]): SubShape[];
+}
+/** Parses a CadQuery-style selector string into an executable selector. */
+declare function parseSelector(source: string): Selector;
+//#endregion
+export { exportStl as A, translate as C, exportGlb as D, ExportFormat as E, exportShape as O, revolve as S, init as T, cut as _, OpListener as a, fuse as b, onOp as c, Cone as d, Cylinder as f, common as g, chamfer as h, OpEvent as i, importStep as j, exportStep as k, record as l, Torus as m, SubShape as n, OpRecord as o, Sphere as p, parseSelector as r, OpStatus as s, Selector as t, Box as u, extrude as v, InitOptions as w, intersect as x, fillet as y };

package/dist/index.d.ts

@@ -1,108 +1,3 @@
 import { C as Vec3, E as v, S as Plane, T as planeFrom, _ as AxisName, a as ShapeList, b as Location, c as EdgeMeta, d as Kernel, f as ShapeHandle, g as Axis3, h as Axis, i as Shape, l as FaceMeta, m as SurfaceKind, n as Edge, o as Solid, p as ShapeMeta, r as Face, s as CurveKind, t as Describe, u as HoleMeta, v as BBox, w as axisByName, x as Mesh, y as Loc } from "./index-DceghC4N.js";
-import "occt.ts";
-//#region src/io/index.d.ts
-type ExportFormat = "step" | "stl" | "glb";
-export declare function exportStep(s: Shape): Uint8Array;
-export declare function exportStl(s: Shape, tolerance?: number): string;
-export declare function exportGlb(s: Shape): Uint8Array;
-export declare function importStep(data: Uint8Array | string): Promise<Solid>;
-/** Writes a shape to disk (Node). Extension picks the format. */
-export declare function exportShape(s: Shape, path: string, opts?: {
-  tolerance?: number;
-}): Promise<void>;
-//#endregion
-//#region src/kernel/occt.d.ts
-interface InitOptions {
-  /** Explicit URL or path to the OCCT WASM binary (file, http(s) or data:). */
-  wasmUrl?: string;
-}
-/** Loads the OCCT WASM kernel exactly once per process (idempotent). */
-export declare function init(opts?: InitOptions): Promise<void>;
-//#endregion
-//#region src/ops/index.d.ts
-export declare function fuse(a: Solid, b: Shape, opts?: {
-  clean?: boolean;
-}): Solid;
-export declare function cut(a: Solid, b: Shape, opts?: {
-  clean?: boolean;
-}): Solid;
-/** build123d `intersect` — OCCT `common`. */
-export declare function intersect(a: Solid, b: Shape, opts?: {
-  clean?: boolean;
-}): Solid;
-/** Keep the OCCT name for code translated from CadQuery. */
-export declare const common: typeof intersect;
-export declare function fillet(s: Shape, edges: ShapeList<Edge> | readonly Edge[], radius: number): Solid;
-/** Equal-distance chamfer; asymmetric needs kernel support (R3). */
-export declare function chamfer(s: Shape, edges: ShapeList<Edge> | readonly Edge[], distance: number): Solid;
-export declare function translate(s: Shape, by: readonly [number, number, number]): Solid;
-/** M1: extrude a 2D sketch into a solid. */
-export declare function extrude(_sketch: unknown, _height: number): Solid;
-/** M1: revolve a 2D sketch around an axis. */
-export declare function revolve(_sketch: unknown, _axis: unknown, _angle?: number): Solid;
-//#endregion
-//#region src/primitives/index.d.ts
-export declare function Box(dx: number, dy: number, dz: number, loc?: Loc): Solid;
-export declare function Cylinder(opts: {
-  radius: number;
-  height: number;
-  loc?: Loc;
-}): Solid;
-export declare function Sphere(opts: {
-  radius: number;
-  loc?: Loc;
-}): Solid;
-export declare function Cone(opts: {
-  radius1: number;
-  radius2: number;
-  height: number;
-  loc?: Loc;
-}): Solid;
-export declare function Torus(opts: {
-  radius1: number;
-  radius2: number;
-  loc?: Loc;
-}): Solid;
-//#endregion
-//#region src/record.d.ts
-/**
- * Op recording — the day-one rule from docs/architecture.md §3.3:
- * every mutating core operation goes through `record()`, so the runtime
- * Session/OpLog can observe, snapshot and replay the exact same stream
- * regardless of which API style (core algebra or workplane facade) produced it.
- *
- * With no subscribers installed this is a transparent pass-through.
- */
-interface OpRecord {
-  /** Monotonic, process-wide — the id the OpLog keys snapshots by. */
-  readonly id: number;
-  readonly type: string;
-  readonly args: unknown;
-}
-type OpStatus = "done" | "error";
-interface OpEvent {
-  readonly op: OpRecord;
-  readonly status: OpStatus;
-  readonly result?: ShapeHandle;
-  readonly error?: unknown;
-}
-type OpListener = (event: OpEvent) => void;
-/** Subscribe to every recorded operation. Returns an unsubscribe function. */
-export declare function onOp(listener: OpListener): () => void;
-/**
- * Runs `run()` and records it as one op. Errors propagate unchanged after
- * being recorded — structured error mapping (runtime) subscribes via onOp.
- */
-export declare function record<T>(type: string, args: unknown, run: () => T): T;
-//#endregion
-//#region src/selectors/index.d.ts
-type SubShape = Face | Edge;
-interface Selector {
-  /** The source string, for error messages and op-log readability. */
-  readonly source: string;
-  select(items: readonly SubShape[]): SubShape[];
-}
-/** Parses a CadQuery-style selector string into an executable selector. */
-export declare function parseSelector(source: string): Selector;
-//#endregion
-export { Axis, type Axis3, type AxisName, type BBox, type CurveKind, type Describe, Edge, type EdgeMeta, type ExportFormat, Face, type FaceMeta, type HoleMeta, type InitOptions, type Kernel, type Loc, type Location, type Mesh, type OpEvent, type OpListener, type OpRecord, type OpStatus, type Plane, type Selector, Shape, type ShapeHandle, ShapeList, type ShapeMeta, Solid, type SubShape, type SurfaceKind, type Vec3, axisByName, planeFrom, v };
+import { A as exportStl, C as translate, D as exportGlb, E as ExportFormat, O as exportShape, S as revolve, T as init, _ as cut, a as OpListener, b as fuse, c as onOp, d as Cone, f as Cylinder, g as common, h as chamfer, i as OpEvent, j as importStep, k as exportStep, l as record, m as Torus, n as SubShape, o as OpRecord, p as Sphere, r as parseSelector, s as OpStatus, t as Selector, u as Box, v as extrude, w as InitOptions, x as intersect, y as fillet } from "./index-DzJsXME9.js";
+export { Axis, type Axis3, type AxisName, type BBox, Box, Cone, type CurveKind, Cylinder, type Describe, Edge, type EdgeMeta, type ExportFormat, Face, type FaceMeta, type HoleMeta, type InitOptions, type Kernel, type Loc, type Location, type Mesh, type OpEvent, type OpListener, type OpRecord, type OpStatus, type Plane, type Selector, Shape, type ShapeHandle, ShapeList, type ShapeMeta, Solid, Sphere, type SubShape, type SurfaceKind, Torus, type Vec3, axisByName, chamfer, common, cut, exportGlb, exportShape, exportStep, exportStl, extrude, fillet, fuse, importStep, init, intersect, onOp, parseSelector, planeFrom, record, revolve, translate, v };

package/dist/index.js

@@ -1,18 +1,6 @@
 import { a as importStep, i as exportStl, n as exportShape, r as exportStep, t as exportGlb } from "./io-DD2D1UYF.js";
 import { _ as Axis, a as Sphere, b as v, c as Face, d as Solid, g as init, i as Cylinder, l as Shape, m as record, n as Box, o as Torus, p as onOp, r as Cone, s as Edge, t as parseSelector, u as ShapeList, v as axisByName, y as planeFrom } from "./selectors-C0-da9aQ.js";
-//#region src/util.ts
-/** Thrown by every skeleton stub until the real M0 implementation lands. */
-var NotImplementedError = class extends Error {
-	constructor(what) {
-		super(`${what} is not implemented yet — this is the M0 repository skeleton.`);
-		this.name = "NotImplementedError";
-	}
-};
-/** Stub body helper: keeps signatures real while bodies wait for M0. */
-function todo(what) {
-	throw new NotImplementedError(what);
-}
-//#endregion
+import { t as todo } from "./util-DeKC5Om9.js";
 //#region src/ops/index.ts
 function fuse(a, b, opts) {
 	return a.fuse(b, opts);

package/dist/mcp/index.d.ts

@@ -0,0 +1,14 @@
+//#region src/mcp/index.d.ts
+export interface McpServerOptions {
+  name?: string;
+  version?: string;
+  /** stdio is the only transport planned for M0. */
+  transport?: "stdio";
+}
+/** Starts the cadorange MCP server (tools: run, describe, render, export). */
+export declare function startMcpServer(_opts?: McpServerOptions): Promise<void>;
+/** Thrown by every skeleton stub until the real M0 implementation lands. */
+export declare class NotImplementedError extends Error {
+  constructor(what: string);
+}
+//#endregion

package/dist/mcp/index.js

@@ -0,0 +1,17 @@
+//#region src/mcp/index.ts
+/** Starts the cadorange MCP server (tools: run, describe, render, export). */
+async function startMcpServer(_opts = {}) {
+	todo("startMcpServer");
+}
+/** Thrown by every skeleton stub until the real M0 implementation lands. */
+var NotImplementedError = class extends Error {
+	constructor(what) {
+		super(`${what} is not implemented yet — this is the M0 repository skeleton.`);
+		this.name = "NotImplementedError";
+	}
+};
+function todo(what) {
+	throw new NotImplementedError(what);
+}
+//#endregion
+export { NotImplementedError, startMcpServer };

package/dist/render/index.d.ts

@@ -0,0 +1,21 @@
+import { i as Shape } from "../index-DceghC4N.js";
+import "../index-DzJsXME9.js";
+//#region src/render/index.d.ts
+export type View = "iso" | "top" | "front" | "back" | "left" | "right" | "bottom";
+export interface RenderOptions {
+  views?: View[];
+  /** Square output size in pixels (default 512). */
+  size?: number;
+  format?: "png" | "svg";
+}
+export interface Rendered {
+  view: View;
+  format: "png" | "svg";
+  data: Uint8Array;
+}
+/**
+ * Renders a shape from multiple views without a GPU or a browser window,
+ * so vision models can check their own work.
+ */
+export declare function render(shape: Shape, opts?: RenderOptions): Promise<Rendered[]>;
+//#endregion

package/dist/render/index.js

@@ -0,0 +1,11 @@
+import { t as todo } from "../util-DeKC5Om9.js";
+//#region src/render/index.ts
+/**
+* Renders a shape from multiple views without a GPU or a browser window,
+* so vision models can check their own work.
+*/
+async function render(shape, opts = {}) {
+	todo("render");
+}
+//#endregion
+export { render };

package/dist/runtime/index.d.ts

@@ -0,0 +1,83 @@
+import { t as Describe } from "../index-DceghC4N.js";
+import "../index-DzJsXME9.js";
+//#region src/runtime/types.d.ts
+type Op = {
+  id: number;
+  type: string;
+  args: Record<string, unknown>;
+  inputs: number[];
+};
+interface OpLog {
+  ops: Op[];
+  append(op: Op): number;
+  slice(to: number): OpLog;
+}
+interface Snapshot {
+  id: string;
+  opIndex: number;
+  hash: string;
+}
+/** Enumerable error codes — exhaustiveness matters for eval/RL statistics. */
+type ErrorCode = "NOT_IMPLEMENTED" | "FILLET_RADIUS_TOO_LARGE" | "BOOLEAN_FAILED" | "INVALID_SHAPE" | "INVALID_OP" | "TIMEOUT" | "OUT_OF_MEMORY" | "OP_LIMIT_EXCEEDED" | "UNKNOWN";
+interface OpError {
+  code: ErrorCode;
+  op?: Op;
+  message: string;
+  /** Executable fix suggestion, aimed at agents. */
+  hint?: string;
+  context?: {
+    maxRadius?: number;
+    failingEdges?: number[];
+  };
+}
+type RunResult = {
+  ok: true;
+  snapshot: Snapshot;
+  describe: Describe;
+  warnings: string[];
+} | {
+  ok: false;
+  error: OpError;
+  lastGood: Snapshot;
+};
+interface Limits {
+  timeoutMs?: number;
+  memoryMB?: number;
+  maxOps?: number;
+}
+interface SessionOptions {
+  limits?: Limits;
+  seed?: number;
+}
+//#endregion
+//#region src/runtime/index.d.ts
+export interface RenderOpts {
+  views?: string[];
+  size?: number;
+  format?: "png" | "svg";
+}
+export type ExportFormat = "step" | "stl" | "glb" | "brep";
+/**
+ * An agent-facing modeling session.
+ *
+ * `run` and `apply` both write into the same OpLog; every core op funnels
+ * through a single record() entry point so the log is always complete.
+ * That invariant is fixed from day one — retrofitting it later is painful.
+ */
+export declare class Session {
+  static create(_opts?: SessionOptions): Promise<Session>;
+  /** Runs TypeScript modeling code in the sandbox. */
+  run(_code: string): Promise<RunResult>;
+  /** Applies one structured action (same log, no code). */
+  apply(_op: Op): Promise<RunResult>;
+  /** Cheap: op index plus cached shape hashes, no geometry copy. */
+  snapshot(): Snapshot;
+  fork(_snap?: Snapshot): Session;
+  rollback(_snap: Snapshot): void;
+  describe(): Describe;
+  render(_opts: RenderOpts): Promise<Uint8Array[]>;
+  export(_fmt: ExportFormat): Promise<Uint8Array>;
+  get limits(): Limits;
+}
+//#endregion
+export type { ErrorCode, Limits, Op, OpError, OpLog, RunResult, SessionOptions, Snapshot };

package/dist/runtime/index.js

@@ -0,0 +1,46 @@
+import { t as todo } from "../util-DeKC5Om9.js";
+//#region src/runtime/index.ts
+/**
+* An agent-facing modeling session.
+*
+* `run` and `apply` both write into the same OpLog; every core op funnels
+* through a single record() entry point so the log is always complete.
+* That invariant is fixed from day one — retrofitting it later is painful.
+*/
+var Session = class {
+	static async create(_opts = {}) {
+		todo("Session.create");
+	}
+	/** Runs TypeScript modeling code in the sandbox. */
+	async run(_code) {
+		todo("Session.run");
+	}
+	/** Applies one structured action (same log, no code). */
+	async apply(_op) {
+		todo("Session.apply");
+	}
+	/** Cheap: op index plus cached shape hashes, no geometry copy. */
+	snapshot() {
+		todo("Session.snapshot");
+	}
+	fork(_snap) {
+		todo("Session.fork");
+	}
+	rollback(_snap) {
+		todo("Session.rollback");
+	}
+	describe() {
+		todo("Session.describe");
+	}
+	async render(_opts) {
+		todo("Session.render");
+	}
+	async export(_fmt) {
+		todo("Session.export");
+	}
+	get limits() {
+		return todo("Session.limits");
+	}
+};
+//#endregion
+export { Session };

package/dist/util-DeKC5Om9.js

@@ -0,0 +1,14 @@
+//#region src/util.ts
+/** Thrown by every skeleton stub until the real M0 implementation lands. */
+var NotImplementedError = class extends Error {
+	constructor(what) {
+		super(`${what} is not implemented yet — this is the M0 repository skeleton.`);
+		this.name = "NotImplementedError";
+	}
+};
+/** Stub body helper: keeps signatures real while bodies wait for M0. */
+function todo(what) {
+	throw new NotImplementedError(what);
+}
+//#endregion
+export { todo as t };

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "cadorange",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Agent-native CAD runtime in TypeScript, powered by occt.ts (OCCT/WASM). Core modeling API: shapes, selectors, booleans, features, import/export.",
   "type": "module",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/LAU-MARS/cadorange.git",
-    "directory": "packages/cadorange"
+    "url": "git+https://github.com/LAU-MARS/cadorange.git"
   },
   "sideEffects": false,
+  "bin": {
+    "cado": "./dist/cli.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -18,6 +20,18 @@
     "./workplane": {
       "types": "./dist/workplane/index.d.ts",
       "default": "./dist/workplane/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "default": "./dist/runtime/index.js"
+    },
+    "./render": {
+      "types": "./dist/render/index.d.ts",
+      "default": "./dist/render/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/index.d.ts",
+      "default": "./dist/mcp/index.js"
     }
   },
   "files": [