OneCAD-Draft/plugins/opencad-python/PLUGIN.md

Python Scripting (opencad.python)

Sandboxing (Phase 1.5)

Audited, not assumed — and the assumption was wrong. Earlier phases claimed "no stdlib is loaded, so import os/socket/subprocess is already impossible." True for those three names, but incomplete: RustPython 0.5.0's host_env Cargo feature — on by default, and rustpython-vm = "0.5" in this crate's Cargo.toml used to pull in the full default set — bakes posix/_ctypes (and os/nt on other platforms) into every interpreter's core module registry, entirely independent of ever adding the separate rustpython-stdlib crate. Confirmed by actually running it, not by reading feature flags: with host_env on, PY_EVAL __import__('posix').getcwd() and PY_EVAL open('/etc/passwd').read() both worked — full filesystem read (and write) access from any script.

Fixed: Cargo.toml now depends on rustpython-vm with default-features = false, features = ["compiler", "gc"] — no host_env. Re-verified the full matrix after the fix, all blocked (ModuleNotFoundError or, for open(), UnsupportedOperation): os, posix, nt, subprocess, socket, ctypes, _ctypes, _socket, _subprocess, _signal, pwd, and both read and write through the built-in open() — its FileIO backing turned out to depend on host_env-gated code internally too, even though the _io module itself is always registered. Confirmed no functional regression: ocs.add_line and the full examples/example.py (including both real constraints) still run correctly with host_env off.

What's left in sys.modules after that fix, for a fresh interpreter — audited exhaustively, not just "fewer than before": _ast, _codecs, _frozen_importlib, _imp, _io, _thread, _typing, _warnings, _weakref, builtins, codecs, encodings_ascii, encodings_utf_8, ocs, sys — core language/import/codec plumbing needed to run Python at all, plus ocs. None of it reaches the filesystem, network, or another process.

One known, accepted residual gap, not silently ignored: _thread is real and functional (_thread.start_new_thread exists and is callable, verified — not a stub). It's registered unconditionally in rustpython-vm 0.5.0's stdlib/mod.rs with no feature guard at all — not host_env, not even its own threading Cargo feature — so there is no dependency-level way to remove it short of patching RustPython itself, which is out of scope here. It grants no filesystem/network/process access (everything that would matter for that is confirmed blocked above); the realistic risk is a script spawning a thread that busy-loops or otherwise misbehaves inside the plugin's own process — a resource/stability concern local to the already crash-isolated plugin process (per plugin-architecture.md's out-of-process design), not a host compromise or data exfiltration path. Deleting _thread from sys.modules after interpreter setup was considered and rejected as a fix: the module stays registered at the VM level regardless, so a script could just re-import it — the deletion would be security theater, not a real control.

Commands

Command	Description
PY_EVAL <expr>	Evaluate one Python expression and print the result (or error) to the command line. Example: PY_EVAL 1 + 1.
PY_RUN <path.py>	Run a .py file as a script (statements, not just one expression). Reports an error the same way as PY_EVAL (missing file, syntax error, exception) — never a silent no-op.

The ocs module

Pre-bound as ocs in both commands — no import needed (and for PY_EVAL, none is possible: it compiles in Mode::Eval, which only accepts a single expression, not statements). Phases 1.2 (read), 1.3 (2D write) and part of 1.4 (Run Script…) of this plugin's ROADMAP.md.

Function	Returns
ocs.selection()	List of the selected entities' handles (int), as of the last selection change — see note below.
ocs.get(handle)	Dict of {handle, kind, layer, point} for that entity, or None if it doesn't exist. point is {x, y, z} or None for non-point entities.
ocs.get_text(handle)	For single-line TEXT, returns its active alignment point, OCS normal, rotation, direction, and height; otherwise None. Reads the host's full document snapshot.
ocs.text_entities()	Lists top-level TEXT/MTEXT entities as {handle, kind, value} dictionaries from the active document.
ocs.block_references()	Lists top-level INSERT entities as {handle, name, effective_name, count, is_xref, is_dynamic, visibility} dictionaries; count includes MINSERT row × column multiplicity and unresolved visibility is None.
ocs.layers()	Lists active-document layer names, off/frozen/locked flags, and top-level entity counts.
ocs.set_entity_layer(handle, layer_name)	Moves an existing top-level entity to an existing layer, preserving its handle and layout ownership.
ocs.export_layer_dwg(layer_name, output_path)	Writes a new DWG containing one layer's top-level entities plus needed block definitions; requires an existing directory and refuses overwrite.
ocs.current_layer()	Returns the active document's current layer name (CLAYER).
ocs.layout_for_entity(handle)	Returns an entity's owning layout name, tab order, and paperspace sheet count; None when unresolved.
ocs.viewport_model_outline(handle)	Returns four XY modelspace corners and elevation for a rectangular, unclipped +Z paperspace viewport; otherwise None.
ocs.add_closed_polyline(vertices, elevation)	Adds a closed lightweight polyline from at least three finite [x, y] vertices.
ocs.text_box_vertices(handle, padding)	Returns an approximate rotated XY box for left/baseline +Z TEXT; otherwise None.
ocs.update_closed_polyline(handle, vertices, elevation)	Replaces a closed lightweight polyline's vertices/elevation, preserving its handle and common properties.
ocs.copy_model_to_paper(handles, viewport_handle)	Copies planar modelspace LINE/ARC/CIRCLE/LWPolyline geometry through a rectangular +Z viewport to its paperspace layout.
ocs.mirror_xy_entities(handles, axis_handle, erase_source)	Mirrors planar LINE/ARC/CIRCLE/LWPolyline entities across an existing XY LINE; optionally removes sources in the same undo group.
ocs.mirror_xy_about_line(handles, point, tangent, erase_source)	Mirrors planar curves across the XY line through a point in a tangent direction; supports curved-axis midpoint workflows.
ocs.break_xy_line(handle, first, second)	Removes the span between two interior XY points on a LINE, preserving its first fragment's handle and properties.
ocs.break_xy_arc(handle, first, second)	Removes the angular span between two interior XY ARC points, retaining the first fragment's handle.
ocs.break_xy_circle(handle, first, second)	Replaces an XY CIRCLE with the complementary ARC after removing the counterclockwise span from first to second.
ocs.break_xy_polyline(handle, first, second)	Removes a path interval from an open, straight, zero-width XY LWPolyline, keeping the first fragment's handle.
ocs.align_xy_entities(handles, source, destination, source_direction, target_direction, copy_mode)	Rigidly moves and rotates planar LINE/ARC/CIRCLE/LWPolyline entities in XY; copy_mode=True adds transformed copies instead of changing originals.
ocs.block_insert_point(handle)	Returns [x, y, z] for an INSERT, or None.
ocs.block_bounds_xy(handle)	Returns [xmin, ymin, xmax, ymax] for a simple unrotated single INSERT whose definition contains only LINE/ARC/CIRCLE/LWPolyline geometry; otherwise None.
ocs.block_attributes(handle)	Lists {tag, value} pairs for one INSERT, or None for another entity.
ocs.set_block_attribute(handle, tag, value)	Updates one INSERT attribute by case-insensitive tag, preserving the block's other data.
ocs.set_text_value(handle, value)	Replaces one TEXT/MTEXT entity's content, preserving other properties. Raises if the entity cannot be updated.
ocs.set_mtext_mask(handle, mode, scale)	Sets one MTEXT background mode (off, mask, or fill) and border scale; raises if invalid or not MTEXT.
ocs.move_text(handle, x, y, z)	Moves only a TEXT entity's active alignment point, preserving its other properties. Raises if it cannot update the entity.
ocs.set_text_pose(handle, x, y, z, rotation)	Moves and rotates one XY TEXT entity while preserving its other properties.
ocs.get_area(handle)	Returns {area, point} for a circle or straight, closed lightweight polyline in the world XY plane; otherwise None. point is suitable for an area-number label.
ocs.get_curve_measure(handle)	Returns {length, point, rotation, tangent} at half length for an XY line, circle, arc, or straight lightweight polyline; tangent is an XY unit vector. Otherwise None.
ocs.line_endpoints(handle)	Returns two [x, y, z] points for a nonzero XY LINE; otherwise None.
ocs.polyline_segments(handle)	Returns segment endpoint, width, length, and optional bulge-arc centre/radius dictionaries for an XY lightweight polyline; otherwise None.
ocs.write_new_text_file(path, content)	Writes a new UTF-8 report file at an explicit path during a PY_ command. Refuses to overwrite or create parent directories.
ocs.curve_samples(handle, segments)	Returns equally spaced XY sample vertices, elevation, and closure for a line, arc, or circle; otherwise None.
ocs.replace_with_polyline(handle, vertices, elevation, closed)	Replaces a line, arc, or circle in place with a lightweight polyline, preserving the handle and common drawing properties.
ocs.add_line(x1, y1, x2, y2)	Adds a 2D line (z=0, layer "0"); returns its handle.
ocs.add_circle(x, y, radius)	Adds a 2D circle (z=0, layer "0"); returns its handle.
ocs.add_arc(x, y, radius, start_deg, end_deg)	Adds a 2D arc (z=0, layer "0"), angles in degrees; returns its handle.
ocs.add_polyline(vertices, elevation)	Adds an open 2D lightweight polyline. Each vertex is [x, y, start_width, end_width]; returns its handle.
ocs.add_text_centered(value, x, y, z, height, rotation_radians)	Adds middle-center aligned single-line text; returns its handle.
ocs.add_text_left(value, x, y, z, height, rotation_radians)	Adds left/baseline single-line text at its insertion point; returns its handle.
ocs.add_mtext(value, point, height, width, rotation_radians)	Adds top-left anchored MTEXT at [x, y, z] using Standard style; returns its handle.
ocs.add_points(points)	Adds many 3D points (each [x, y, z]) in one HostApi::add_entities batch call; returns the new handles in order.
ocs.remove_entity(handle)	Deletes one entity in the script's undo group; raises if the handle cannot be removed.
ocs.add_table(rows, x, y, z, row_height, column_width)	Adds a native table from a rectangular list of string rows; returns its handle.
ocs.read_record(handle, app_name)	Returns {app_name, values} for the XDATA record app_name on handle, or None if the entity or the record doesn't exist. See "XDATA" below for the values shape.
ocs.write_record(handle, app_name, values)	Attaches an XDATA record to handle for app_name, replacing any existing record for that application. Raises if handle doesn't exist.
ocs.remove_record(handle, app_name)	Removes the XDATA record for app_name from handle, if any. Returns True if a record was actually removed.
ocs.command(cmd)	Superseded. Only the experimental-command-replay build has it (the old fire-and-forget replay). Use doc.command, doc.start_command and doc.modify from the document model (see "Running OCS commands" below).
ocs.select(handles)	Replaces the selection with exactly these handles, in order (document-model build); doc.selection = [...] is the same.
ocs.system_variable(name) / ocs.set_system_variable(name, value)	Development-only experimental-host-settings feature. Reads or sets host-managed CLAYER (text) and SNAPANG (degrees) without nested command dispatch. Requires the Felix OCS fork's plugin/host-model-api branch; absent from the portable default build.

add_line/add_circle/add_arc take plain Python numbers — ocs.add_line(0, 0, 10, 10) works with ints, not just floats. (Needed an explicit fix: a bare f64 #[pyfunction] parameter in RustPython, unlike CPython's C-function argument parsing, does not implicitly coerce an int — it raises TypeError. Using rustpython_vm::function::ArgIntoFloat instead accepts anything with __float__/__index__, matching how a script author actually writes coordinates.)

Layers: ocs.active_document.layers

The layer table, with every change validated by the host, recorded as one undo step, and refused (a RuntimeError, nothing changed) when it cannot be honoured.

L = ocs.active_document.layers
L.create("Walls", color=1, lineweight=50, description="load bearing")
L.create("Grid", color=(10, 200, 30), linetype="Continuous", off=True)
L.modify("Walls", color=5, locked=True)      # only the properties given
L.rename("Walls", "Structure")               # entities on it follow
L.set_current("Grid")
L.delete("Structure", erase_objects=True)    # refused if it holds objects otherwise
"Grid" in L, L["Grid"]["color"], L.current, L.names()

Properties: color (ACI 1-255, an (r, g, b) tuple or a Color dict), linetype (must exist in the drawing), lineweight (1/100 mm, 0-211; -1 ByLayer, -2 ByBlock, -3 Default), off, frozen, locked, plottable, transparency (percent 0-90), description. Records also carry handle, entity_count and current. Refused: an existing or invalid name (empty, over 255 characters, or containing <>/\":;?*|= or a backquote), a color of ByLayer/ByBlock/0, an unknown property, renaming or deleting layer 0 or Defpoints, deleting or freezing the current layer, deleting an externally referenced layer, and modifying with no properties. Making a layer current is a setting, not an undo step.

Text and dimension styles: doc.text_styles, doc.dim_styles

S, D = ocs.active_document.text_styles, ocs.active_document.dim_styles
S.create("Title", height=5, width_factor=0.8, oblique=15, font="romans", annotative=True)
S.modify("Title", height=6)
D.create("Metric", dimscale=2, dimtxt=3.5, dimtxsty="Title")     # DimStyle field names
D.create("Metric2", copy_from="Metric", dimtxt=4)
S.rename("Title", "Heading")      # entities, dimension styles and tables follow
S.set_current("Heading"); D.set_current("Metric")
D.delete("Metric2"); S["Heading"]["height"]; D.current["name"]; S.names()

Same guarantees as layers: host-validated, one undo step, a refusal raises RuntimeError and changes nothing (making a style current is a setting). Text properties: height (0 = each text chooses), width_factor (0-100), oblique (degrees, within 85), font, big_font, backward, upside_down, vertical, annotative; use font="arial.ttf" for a TrueType face, because the codec does not persist a separate family name. Dimension styles use the DimStyle field names (dimscale, dimtxt, dimasz, ...); records list all of them. Handles, xref_* fields and name are host-managed and refused, unknown fields and wrongly typed values are refused, dimscale and dimtxt must be positive, and dimtxsty must name an existing text style. Standard is never renamed or deleted; a style that is current or still referenced is never deleted; a case-only rename is refused. Style operations act on the active document.

Known persistence limits (cadcodec, see docs/cadcodec-reader-gaps.md): a DXF save drops the backward/upside-down flags of a text style and does not restore a dimension style's dimtxsty name (the handle link survives); DWG keeps both.

Blocks: ocs.active_document.blocks

doc = ocs.active_document
line = doc.create_entity("Line", start=..., end=...)
circle = doc.create_entity("Circle", center=..., radius=1)
B = doc.blocks
B.create("Widget", [line, circle], base_point=(1, 1, 0), description="a widget")
doc.create_entity("Insert", block_name="Widget", insert_point={"x": 10, "y": 0, "z": 0})
B.modify("Widget", explodable=False)
B.rename("Widget", "Gadget")             # every insert follows
B["Gadget"]["entities"], B["Gadget"]["insert_count"], B.names()
B.delete("Gadget")                       # refused while an insert, style or leader uses it

create copies model or paper space entities (descriptors or handles) into a new definition shifted by -base_point, so an insert at p puts the base point at p. erase_originals=True removes the sources, as the BLOCK command does; the default keeps them. No insert is placed. Refused: an empty, duplicate, invalid or *-prefixed name, no entities, a missing or repeated entity, an entity inside a block, a viewport, a non-finite base point, renaming or deleting layout, anonymous or externally referenced blocks, and a case-only rename. Deleting also removes the definition's contents. Records list user blocks only (handle, name, description, explodable, scale_uniformly, base_point, insert_count, entities as {handle, kind}). A DXF save drops the block description (cadcodec); DWG keeps it.

Block contents. Add to a definition with create_entity(kind, block="Part", ...). It is validated exactly like a model-space entity and the host sets the owner (so attribute definitions work: create_entity("AttributeDefinition", block="Part", tag=..., prompt=..., default_value=..., insertion_point=..., height=...)). Members are read, edited (entity.end = (8, 0, 0) inside doc.transaction(...)) and deleted (doc.delete_entity) with the ordinary entity API, using the handles in blocks["Part"]["entities"]. Refused: an unknown, layout, anonymous or external block, an invalid entity, a viewport, raster image, block marker or nested attribute, an entity on a locked layer, and an insert that would nest a block inside itself directly or through other blocks. Adding while the block editor is open is refused. Each add or delete is one undo step.

Linetypes and layouts: doc.linetypes, doc.layouts

doc = ocs.active_document
LT, LY = doc.linetypes, doc.layouts
LT.create("Bracket", [12, -3, 2, -3], "bracket line")   # dash 12, gap 3, dash 2, gap 3
LT.modify("Bracket", description="renamed"); LT.rename("Bracket", "Cut")
doc.layers.create("Cuts", linetype="Cut")
LT.delete("Cut")                                          # refused while a layer uses it

LY.create("Sheet1")
LY.set_page("Sheet1", paper_size=(420, 297), rotation=0, scale=(1, 50))
LY.current = "Sheet1"                                     # create_entity now draws on the sheet
doc.create_entity("Circle", center={"x": 50, "y": 50, "z": 0}, radius=5)
LY.current = "Model"
LY.rename("Sheet1", "Plan"); LY.delete("Plan")            # deletes the sheet's entities too
LY.names(), LY.current["name"], LY["Plan"]["paper_size"]

Both follow the same rules as the other tables: host-validated, one undo step (switching layout is not one), a refusal raises RuntimeError and changes nothing. A linetype pattern is signed lengths (positive dash, negative gap, zero dot; 2-12 elements with a gap and a dash or dot); text and shape linetypes can be read (complex) but not created or edited. Continuous, ByLayer and ByBlock are never changed, names of standard linetypes are taken, renaming updates the layers and entities that use it, and a linetype used by a layer, entity, dimension style or the current setting is never deleted. Layouts: Model cannot be created, renamed or deleted; deleting the current layout falls back to Model; a case-only rename is refused. set_page takes the sheet in millimetres, a rotation of 0/90/180/270 and a custom scale (numerator, denominator), and updates the layout limits. Layout operations act on the active document. Records list current, tab_order, entity_count, viewport_count, paper_size, rotation and scale. Reordering layouts and plot devices or styles are not available yet.

Running OCS commands: doc.command, doc.start_command, doc.modify

Scripts can drive OCS's own tools. The host runs the real command, so it behaves exactly as at the command line (same prompts, same geometry, same undo), and does it synchronously on the editor thread, so a step never waits on outside input.

doc = ocs.active_document
doc.command("CIRCLE 5,5 3")                 # a whole line: tokens answer the prompts, then Enter
with doc.start_command("OFFSET") as c:      # or answer prompt by prompt
    c.text(2)                               # a typed value
    c.entity(line, at=(5, 0, 0))            # an object pick
    c.point((5, 4, 0))                      # a point
    c.enter()
    print(c.outcome["status"], c.outcome["prompt"], c.outcome["added"])

M = doc.modify                              # the common tools as plain calls
M.offset(line, 2, side=(5, 5))              # returns the new entity
M.trim(target, at=(108, 0)); M.extend(target, at=(208, 0))
M.fillet(first, second, radius=2)           # radius 0 squares the corner
M.move([a, b], (0, 0, 0), (5, 5, 0)); M.copy([a], base, target)
M.rotate([a], base, 90); M.scale([a], base, 2)
M.mirror([a], p1, p2, erase_source=False); M.erase([a])
M.chamfer(first, second, 2, 3)              # distance 2 along first, 3 along second
M.array_rect([a], rows=2, columns=3, row_spacing=10, column_spacing=20)
M.array_polar([a], center, count=4, angle=360)   # counts include the original
M.explode([polyline]); M.join([line1, line2])
M.break_entity(line, first_point, second_point)
M.stretch(corner1, corner2, base, target)   # crossing window, then the displacement
M.lengthen(line, 5, at=near_the_end)        # delta; negative shortens
M.array_path([a], path_curve, count=5)      # evenly along a curve
M.array_3d([a], rows=2, columns=2, levels=2, row_spacing=10, column_spacing=20, level_spacing=30)
M.polyline_close(pl); M.polyline_open(pl); M.polyline_reverse(pl)
M.polyline_width(line_or_pl, 0.5)           # a line or arc is turned into a polyline first
M.polyline_join(pl, [line1, arc1])          # returns the merged polyline

Each step returns an outcome dict: status (completed or waiting_input), blocked_by, command, prompt, accepts (point, entity, selection, text, token, enter), options (keyword tokens), entities, added, unconsumed and error. c.point, c.text, c.token, c.entity, c.selection, c.enter and c.cancel map to those prompts; an error raises RuntimeError, and leaving the with block cancels a command that is still waiting, also closing any editor or dialog it opened. doc.command cancels and raises when the line leaves a prompt open.

Selection-based tools (move, copy, rotate, scale, mirror, erase, the arrays, explode and join) select the entities you pass first, so the command skips its own selection prompt. Pick points default to the middle of a line, arc or circle and the first vertex of a polyline; give at= for anything else. trim and extend cut or extend against every entity in the drawing. Each command is undone as the editor would undo it.

Guards: a command is refused while another is active (cancel it first) or when the line names a command that could end the session, re-enter Python or change this setting: QUIT, EXIT, CLOSE, CLOSEALL, NEW, QNEW, OPEN, SAVE, QSAVE, SAVEAS, SAVEALL, RECOVER, SCRIPT, RUNSCRIPT, SCRIPTCOMMANDS and any PY_*. The user can switch the whole facility off with the SCRIPTCOMMANDS 0 command (1 turns it back on, plain SCRIPTCOMMANDS shows it); it is a saved preference, on by default, and while it is off every doc.command, start_command and doc.modify call raises RuntimeError. Only the command line can change it, never a script. Commands run on the active document only. Commands that need an interactive surface a script cannot fill (the rich-text editor, a file dialog) report it in blocked_by and are cancelled. PEDIT's fit, spline, decurve and vertex-edit options are not wrapped (reach them with start_command("PEDIT")); polyline_* return the polyline entity, which is a new entity when the command replaced the original. Hatching has no wrapper: create it with create_entity("Hatch", ...), because the HATCH command needs an interactive boundary pick. ocs.command_step(kind, options) is the raw single step behind all of this.

Historical command-replay experiment (not in the default build)

The following records an earlier experiment and is kept for the findings, not as instructions. It used a fire-and-forget ocs.command() that replayed a line through the message loop; on OCS 2026.37 that could hang. It has been superseded by doc.command / doc.start_command (see "Running OCS commands" above), which run the real command synchronously through the host's run_command step API and were exercised against every command tried without a hang. The prompt-sequence findings below (selection prompts, ALIGN's extra Enters) still describe how the commands behave.

ocs.command() + ocs.select() together can apply a real, persistent constraint, entirely from a script — this required two host changes (HostApi::run_command and HostApi::set_selection, ocs_plugin_api v0.2.1+ built from a worktree that isn't upstream yet — see the note at the bottom of this file), not something achievable from the plugin alone. Verified end-to-end against a real running host, not just "it compiles":

ocs.select([line1_handle, line2_handle])
ocs.command("PCONSTRAINT")

run as a plain .py file via PY_RUN — no automation-API help, no manual pre-selection — ran the actual geometric solver and visibly adjusted both lines' coordinates to be genuinely parallel (checked numerically: direction-vector cross product ≈ 0 after, nonzero before). A real, persistent PCONSTRAINT object. Same result verified for TCONSTRAINT (circle-to-line tangency): center-to-line distance equals the radius exactly after. examples/example.py does both — its "parallel" lines and "tangent" circle are real constraint objects, not geometry computed once.

Why two calls, not one: constraint commands read a prior selection (a "Select objects:" prompt), not picks fed as command-line tokens the way LINE's points are — feeding ocs.command("PCONSTRAINT {h1} {h2}") with handles as trailing tokens starts the command but ends in "Command cancelled", not a constraint. ocs.select() sets that selection state first; ocs.command() then reads it.

Not every command completes cleanly this way — ALIGN is the found counterexample. ocs.command()'s point-feeding sends exactly one trailing Enter after the fed tokens, to finish the command. ALIGN needs two after its point pairs (skip the optional 3rd source/destination pair, then answer a "Scale objects? [Yes/No]" question) — so ocs.command("ALIGN 0,0 20,20 2,0 22,22") does apply the actual move/rotate transform correctly (verified: the entities land at the right transformed coordinates), but leaves that Scale prompt open instead of cleanly finishing the command. Not attempted in examples/example.py — shipping something that half-completes seemed worse than leaving it out. A general fix would need ocs.command() to accept a trailing-Enter count (or an explicit terminator convention) instead of always exactly one; not implemented.

ocs.command() cannot invoke itself or any other plugin's command — only built-ins. This call is a nested plugin→host request arriving while the plugin's own dispatch() is still running (its one runner thread is blocked waiting for this exact call to return); routing it back through normal plugin dispatch would hand that same plugin (or any plugin) a second Dispatch request it has no free thread to answer, deadlocking both sides. Found this the hard way — ocs.command("LINE 0,0 10,10") hung completely before the host-side fix. run_command skips plugin dispatch entirely, by design, not as an oversight.

Which built-in commands ocs.command() can reach

ocs.command() goes through the exact same dispatcher as the interactive command line — HostApi::run_command → the host's run_command_line_no_plugin_reentry → dispatch_command_inner(cmd, allow_suggest=false, try_plugins=false) — so almost everything typeable in OCS also works from a script, minus one deliberate carve-out.

Reachable: the full built-in command set, spread across ten dispatch families in the host's src/app/commands/ (fileops, layers, blocks, draw, dim, inquiry, view, layerprops, styleprops, display). That covers everything AutoCAD-compatible the host implements natively — drawing entities and constraints (LINE, CIRCLE, ARC, POLYLINE, MOVE, ROTATE, ALIGN, PCONSTRAINT, TCONSTRAINT, in dispatch_draw), dimensions (DIMLINEAR, DIMALIGNED, DIMSTYLE, ...), blocks (BLOCK, INSERT, WBLOCK, ATTSYNC, ...), layers/properties (LAYER, LAYISO, LAYDEL, CHPROP, PROPERTIES, ...), file ops (NEW, OPEN, SAVE, SAVEAS, EXPORT..., PLOT, ...), inquiry (LIST, DIST, AREA, DBLIST, ...), view (ZOOM, PAN, VIEW, REGEN, ...), and directly-settable system variables typed as commands (PICKBOX 5, MIRRTEXT 1, LUPREC 4, ...). Aliases still resolve too (ocs.command("L 0,0 10,10") works the same as LINE), since alias expansion happens before the plugin-skip.

Not reachable: any plugin-provided command, including this plugin's own (PYTHONSHELL, PY_EVAL, PY_RUN) — see the paragraph above for why. This is the only restriction versus the interactive command line; there is no narrower allow-list beyond it. allow_suggest=false also means no autocomplete/fuzzy-matching of partial verbs (unlike typing BAC and pressing Enter for BACKGROUND) — a script must spell out the exact command name or a real alias.

Usage notes already verified end-to-end (see the constraint example above and examples/example.py):

• Multi-point/interactive commands take their args inline on one string, exactly as if typed then Enter: ocs.command("LINE 0,0 10,10").
• A command that reads a prior selection rather than inline picks (constraint commands are the concrete case) needs ocs.select(handles) called first — ocs.command() alone can't feed a "Select objects:" prompt.
• ALIGN needs two trailing Enters (skip the optional 3rd point pair, then answer the Scale prompt); ocs.command() only ever sends one, so it applies the transform but leaves that prompt dangling — see above.

For the exhaustive, exact list rather than this summary, the source of truth is the inventory::submit!(CommandRegistration { names: &[...] }) blocks scattered across the host's src/app/commands/*.rs (105 files register at least one command as of this writing); the largest single block — everything without its own interactive command module — is src/app/commands/mod.rs's command-line autocomplete registry. Since it's the same dispatcher, OCS's own command-line autocomplete is also a live index of what ocs.command() can run.

One push_undo group per script, not per ocs.add_* call. A PY_RUN script that calls ocs.add_line ten times undoes as one step. Verified end-to-end: a two-line script undoes both lines in a single undo. Implemented via host_ctx::ensure_undo_started, called lazily by the first write in a given PY_EVAL/PY_RUN — a read-only script never touches the undo stack. Note: ocs.command() does not go through this — a built-in command manages its own undo the same way it would if typed, so ocs.command calls are not folded into the script's shared undo group.

ocs.selection() is a cache, not a live query. HostApi has no synchronous "give me the current selection" call — only a best-effort SelectionChanged / SelectionChangedV4 notification. It reflects the selection as of the last time it changed, not necessarily the instant the script calls it.

That cache is populated via BuiltinPlugin::on_notification, not by calling HostApi::try_recv_notification() from dispatch(). Found the hard way: ocs_plugin_api::runner's own V4 event loop (run_v4 in runner.rs) drains that queue itself on every iteration and forwards each notification to on_notification before a Dispatch request ever reaches dispatch() — so polling it from inside dispatch always finds it empty. This plugin overrides on_notification and stashes the latest selection in a process-wide cache (selection_cache.rs); ocs.selection() reads that. Verified end-to-end against a real host build: select an entity, then PY_EVAL ocs.selection() returns its handle.

Each PY_EVAL/PY_RUN runs in a fresh interpreter (no stdlib, no session state across calls) — REPL/session persistence is an open question for a later phase.

Typing or pasting PY_EVAL/PY_RUN directly into the interactive command line is broken for anything beyond trivial arithmetic — a host issue, not this plugin. Message::CommandInput in src/app/update/mod.rs (this repo) uppercases the entire input line on every keystroke and on paste, and auto-submits the instant it contains a space (both deliberate, for classic single-line CAD commands like LINE 0,0 10,10). That mangles case (ocs.add_line → OCS.ADD_LINE, a NameError) and truncates arguments (PY_EVAL submits before you finish typing the expression) for any multi-word, case-sensitive plugin argument — automation (ocs_execute/--mcp) bypasses this UI path entirely, which is why it never surfaced in this session's own testing until a live user tried typing it by hand. Run Script… (below) sidesteps this correctly — the host authors already solved the identical problem for file paths via ModuleEvent::PluginFileDialog, which dispatches with original case intact. There is no equivalent bypass for PY_EVAL today; typed/pasted PY_EVAL only survives if it has no spaces and no case-sensitive identifiers.

Ribbon

Two tools in the "Tools" group:

Tool	Behavior
Eval 1+1	Dispatches PY_EVAL 1 + 1 directly — a smoke test.
Run Script…	ModuleEvent::PluginFileDialog opens a native "pick a .py file" dialog; on selection the host dispatches PY_RUN <chosen path> back to the plugin. Cancel does nothing.

A real script manager UI (list/run/save scripts, or a dockable REPL console) is not possible with today's ocs_plugin_api. This was an open question in ROADMAP.md — now answered by reading ribbon.rs: CadModule exposes exactly one hook, ribbon_groups(), which returns a static set of ribbon buttons/dropdowns (RibbonItem). There is no API for a plugin to host a persistent custom panel, list dynamic content, or render arbitrary UI — the ribbon vocabulary is deliberately "plain data the host renders," not a widget toolkit. Getting a script list or REPL panel would need a new HostApi/CadModule capability, i.e. an ocs_plugin_api version bump — a host-side feature, out of scope for a plugin repo. Run Script… (above) is the most a plugin can do today: reuse the host's own native file picker via the existing PluginFileDialog event, which was already there for other plugins to import files.

AutoLISP migration

An AutoLISP-to-Python translator is a separate project and is not part of this repository: scripts written for this plugin use the ocs module and the document model described above, and a translated macro would run through PY_RUN like any other script. Nothing in the plugin depends on it.

XDATA

ocs.read_record/ocs.write_record/ocs.remove_record wrap HostApi::read_record/write_record/remove_record — already implemented by the host (unlike run_command/set_selection, these needed no host change or [patch] entry). A record is {"app_name": str, "values": [...]}; each value is {"kind": str, "value": ...}. Supported kinds and their Python value shape:

kind	Python value
String, ControlString, LayerName	str
BinaryData	bytes
Handle	int
Point3D, Position3D, Displacement3D, Direction3D	[x, y, z] (float)
Real, Distance, ScaleFactor	float
Integer16, Integer32	int

ocs.write_record(handle, "MYAPP", [
    {"kind": "String", "value": "part-042"},
    {"kind": "Integer32", "value": 7},
])
record = ocs.read_record(handle, "MYAPP")  # {"app_name": "MYAPP", "values": [...]}
ocs.remove_record(handle, "MYAPP")

This {app_name, values}/{kind, value} shape is deliberately the same one schoeller/ocs_python_repl (a separate, out-of-process PyO3-based Python plugin for OCS) uses in its ocs.doc.read_record/write_record, so a script's XDATA handling ports between the two plugins unchanged. write_record starts the script's shared undo group the same way ocs.add_* does (see below); remove_record only starts it when a record actually existed to remove.

Build note: bundled host API

Cargo.toml uses the repository-relative ocs_plugin_api crate. Packaging builds the plugin with the same compiler and CAD codec as the host and stages matching metadata beside the library. The experimental-command-replay Cargo feature keeps the old bridge code available, but the tested nested-command path can hang. Do not enable it for production.