@miclivs/cadcli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Liv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+# cadcli
+
+Agent-friendly CAD inspection, search, viewing, and editing for DWG/DXF files.
+
+```bash
+npm install -g @miclivs/cadcli
+```
+
+Common inspection/search commands use a pure TypeScript parser by default. Native LibreDWG tools are only needed for high-fidelity `view` and jq-backed `edit`.
+
+## Why cadcli
+
+CAD files are hard to inspect from scripts. `cadcli` gives agents and developers a predictable interface over DWG/DXF drawings: structured JSON for automation, concise human output in the terminal, SVG previews for visual checks, and safe copy-first editing.
+
+```bash
+cadcli info floorplan.dwg --json
+cadcli overview floorplan.dwg
+cadcli search floorplan.dwg "conference" --layer A-TEXT --json
+cadcli view floorplan.dwg -o preview.svg
+cadcli edit floorplan.dwg --jq '.OBJECTS[]' -o edited.dwg
+```
+
+## Workflow
+
+```txt
+info → overview → layers/blocks/entities → search → view → edit
+```
+
+Start with `info` to understand the drawing, use `overview` to see the searchable vocabulary, narrow down with `layers`, `blocks`, `entities`, and `search`, render an SVG with `view`, then write edits to a new file with `edit -o`.
+
+## Commands
+
+```bash
+cadcli info <file>                       # metadata, version, counts, bounds
+cadcli overview <file>                   # search vocabulary by layer/type/block/text
+  --keywords 12 --samples 8
+cadcli layers <file> [--total]           # layers and entity counts
+cadcli blocks <file> [--total]           # block names and entity counts
+cadcli entities <file>                   # entities, optionally filtered
+  --type LINE --layer A-WALL --limit 20 --total
+
+cadcli search <file> [query]             # search IDs, types, layers, text, raw fields
+  --query "door" --type TEXT --layer A-TEXT --limit 10 --score --no-snippets
+
+cadcli view <file> [-o preview.svg]      # high-fidelity SVG preview
+cadcli edit <file> --jq <expr> -o out.dwg
+cadcli json <file> [-o drawing.json]     # normalized JSON
+cadcli svg <file> [-o sketch.svg]        # best-effort SVG from normalized JSON
+cadcli thumbnail <file> [-o thumb.png]   # embedded thumbnail when available
+```
+
+All commands support `--json` for structured output and `-q, --quiet` where useful. Primary data goes to stdout; diagnostics and errors go to stderr.
+
+## Overview
+
+`cadcli overview` is the map before the search. It shows the drawing's useful vocabulary broken down by layer, entity type, block, text keyword, and search hint so agents do not have to guess what to query.
+
+```txt
+WORKFLOW: overview (you are here) → search/entities → view/edit
+
+SUMMARY
+  DWG · 1906 entities · 33 layers · 42 blocks
+
+LAYERS
+A-TEXT
+  entities: 88
+  types: TEXT, MTEXT
+  keywords: conference room, office, lobby
+
+SEARCH HINTS
+  conference room, office, A-TEXT, DOOR_SINGLE, TEXT
+```
+
+
+## Viewing vs SVG export
+
+`cadcli view` is the high-fidelity SVG path.
+
+`cadcli svg` renders a lightweight SVG from cadcli’s normalized JSON model. It is useful for quick agent previews and debugging, but it is not a replacement for `view`.
+
+## Editing
+
+Editing is intentionally copy-first:
+
+```bash
+cadcli edit drawing.dwg --jq '.OBJECTS[]' -o edited.dwg
+```
+
+In-place edits are refused unless you explicitly pass `--overwrite`:
+
+```bash
+cadcli edit drawing.dwg --jq '.OBJECTS[]' --overwrite
+```
+
+## SDK
+
+```ts
+import { Dwg } from "@miclivs/cadcli";
+
+const drawing = Dwg.open("floorplan.dwg");
+
+console.log(await drawing.info());
+console.log(await drawing.layers());
+console.log(await drawing.search({ query: "conference", layer: "A-TEXT" }));
+
+const preview = drawing.view();
+console.log(preview.svg);
+```
+
+The public SDK is intentionally small: `Dwg` plus stable CAD/result types. Native tool details stay behind the SDK methods.
+
+## Cache
+
+Search indexes are cached automatically in the platform-standard cache directory:
+
+```txt
+macOS    ~/Library/Caches/cadcli
+Linux    $XDG_CACHE_HOME/cadcli or ~/.cache/cadcli
+Windows  %LOCALAPPDATA%\cadcli\Cache
+```
+
+Set `CADCLI_CACHE_DIR` to override this location.
+
+## Requirements
+
+Inspection, overview, layers, blocks, entities, search, JSON, and lightweight SVG export work through the default pure TypeScript parser.
+
+Install native LibreDWG tools for advanced workflows: `dwgread` for high-fidelity `view`, and `dwgfilter` for edits.
+
+## License
+
+MIT

package/dist/commands/blocks.d.ts

@@ -0,0 +1,4 @@
+import { type DrawingCommandOptions } from "./shared.js";
+export declare function blocks(file: string, options: DrawingCommandOptions & {
+    total?: boolean;
+}): Promise<void>;

package/dist/commands/blocks.js

@@ -0,0 +1,22 @@
+import { dim, output } from "../utils/output.js";
+import { drawingFor, handleCommandError, } from "./shared.js";
+export async function blocks(file, options) {
+    try {
+        const items = await drawingFor(file, options).blocks();
+        output(options, {
+            json: () => options.total
+                ? { total: items.length, blocks: items }
+                : { blocks: items },
+            human: () => {
+                if (options.total)
+                    console.log(String(items.length));
+                else
+                    for (const block of items)
+                        console.log(`${block.name} ${dim(`${block.entityCount} entities`)}`);
+            },
+        });
+    }
+    catch (err) {
+        handleCommandError(err);
+    }
+}

package/dist/commands/edit.d.ts

@@ -0,0 +1,8 @@
+import type { OutputOptions } from "../utils/output.js";
+export interface EditOptions extends OutputOptions {
+    jq?: string;
+    output?: string;
+    overwrite?: boolean;
+    toolDir?: string;
+}
+export declare function edit(file: string, options: EditOptions): Promise<void>;

package/dist/commands/edit.js

@@ -0,0 +1,24 @@
+import { editWithLibreDwgFilter } from "../core/libredwg.js";
+import { output, success } from "../utils/output.js";
+import { handleCommandError, userError } from "./shared.js";
+export async function edit(file, options) {
+    try {
+        if (!options.jq) {
+            throw userError("No edit expression specified. Use --jq <expression>.", "MISSING_EDIT_EXPRESSION");
+        }
+        const result = editWithLibreDwgFilter({
+            input: file,
+            output: options.output ?? file,
+            expression: options.jq,
+            overwrite: options.overwrite,
+            toolDir: options.toolDir,
+        });
+        output(options, {
+            json: () => ({ success: true, ...result }),
+            human: () => success(`Edited ${result.output} with LibreDWG dwgfilter`),
+        });
+    }
+    catch (err) {
+        handleCommandError(err);
+    }
+}

package/dist/commands/entities.d.ts

@@ -0,0 +1,7 @@
+import { type DrawingCommandOptions } from "./shared.js";
+export declare function entities(file: string, options: DrawingCommandOptions & {
+    type?: string;
+    layer?: string;
+    limit?: string;
+    total?: boolean;
+}): Promise<void>;

package/dist/commands/entities.js

@@ -0,0 +1,26 @@
+import { dim, output } from "../utils/output.js";
+import { drawingFor, handleCommandError, parseLimit, } from "./shared.js";
+export async function entities(file, options) {
+    try {
+        const items = await drawingFor(file, options).entities({
+            type: options.type,
+            layer: options.layer,
+            limit: parseLimit(options.limit),
+        });
+        output(options, {
+            json: () => options.total
+                ? { total: items.length, entities: items }
+                : { entities: items },
+            human: () => {
+                if (options.total)
+                    console.log(String(items.length));
+                else
+                    for (const entity of items)
+                        console.log(`${entity.id} ${entity.type}${entity.layer ? ` ${dim(entity.layer)}` : ""}`);
+            },
+        });
+    }
+    catch (err) {
+        handleCommandError(err);
+    }
+}

package/dist/commands/info.d.ts

@@ -0,0 +1,2 @@
+import { type DrawingCommandOptions } from "./shared.js";
+export declare function info(file: string, options: DrawingCommandOptions): Promise<void>;

package/dist/commands/info.js

@@ -0,0 +1,22 @@
+import { bold, dim, output } from "../utils/output.js";
+import { drawingFor, handleCommandError, } from "./shared.js";
+export async function info(file, options) {
+    try {
+        const summary = await drawingFor(file, options).info();
+        output(options, {
+            json: () => summary,
+            human: () => {
+                console.log(`${bold(summary.file)} ${dim(summary.format)}${summary.version ? ` ${dim(summary.version)}` : ""}`);
+                console.log(`  entities  ${summary.counts.entities}`);
+                console.log(`  layers    ${summary.counts.layers}`);
+                console.log(`  blocks    ${summary.counts.blocks}`);
+                console.log(`  unsupported ${summary.counts.unsupported}`);
+                if (summary.bounds)
+                    console.log(`  bounds    ${summary.bounds.minX},${summary.bounds.minY} → ${summary.bounds.maxX},${summary.bounds.maxY}`);
+            },
+        });
+    }
+    catch (err) {
+        handleCommandError(err);
+    }
+}

package/dist/commands/json.d.ts

@@ -0,0 +1,2 @@
+import { type DrawingCommandOptions, type OutputFileOptions } from "./shared.js";
+export declare function json(file: string, options: DrawingCommandOptions & OutputFileOptions): Promise<void>;

package/dist/commands/json.js

@@ -0,0 +1,20 @@
+import { toJson } from "../core/drawing.js";
+import { stringifyJson } from "../utils/output.js";
+import { handleCommandError, writeCommandOutput, } from "./shared.js";
+export async function json(file, options) {
+    try {
+        const doc = await toJson(file, {
+            reader: options.reader,
+            toolDir: options.toolDir,
+        });
+        const content = `${stringifyJson(doc)}\n`;
+        if (options.output) {
+            writeCommandOutput(options, content, () => ({ success: true, file: options.output }), `Wrote ${options.output}`);
+            return;
+        }
+        console.log(content.trimEnd());
+    }
+    catch (err) {
+        handleCommandError(err);
+    }
+}

package/dist/commands/layers.d.ts

@@ -0,0 +1,4 @@
+import { type DrawingCommandOptions } from "./shared.js";
+export declare function layers(file: string, options: DrawingCommandOptions & {
+    total?: boolean;
+}): Promise<void>;

package/dist/commands/layers.js

@@ -0,0 +1,22 @@
+import { dim, output } from "../utils/output.js";
+import { drawingFor, handleCommandError, } from "./shared.js";
+export async function layers(file, options) {
+    try {
+        const items = await drawingFor(file, options).layers();
+        output(options, {
+            json: () => options.total
+                ? { total: items.length, layers: items }
+                : { layers: items },
+            human: () => {
+                if (options.total)
+                    console.log(String(items.length));
+                else
+                    for (const layer of items)
+                        console.log(`${layer.name} ${dim(`${layer.entityCount} entities`)}`);
+            },
+        });
+    }
+    catch (err) {
+        handleCommandError(err);
+    }
+}

package/dist/commands/overview.d.ts

@@ -0,0 +1,5 @@
+import { type DrawingCommandOptions } from "./shared.js";
+export declare function overview(file: string, options: DrawingCommandOptions & {
+    keywords?: string;
+    samples?: string;
+}): Promise<void>;

package/dist/commands/overview.js

@@ -0,0 +1,59 @@
+import { bold, dim, output } from "../utils/output.js";
+import { drawingFor, handleCommandError, parseLimit, } from "./shared.js";
+export async function overview(file, options) {
+    try {
+        const result = await drawingFor(file, options).overview({
+            keywords: parseLimit(options.keywords),
+            samples: parseLimit(options.samples),
+        });
+        output(options, {
+            json: () => result,
+            human: () => {
+                console.log(dim("WORKFLOW: overview (you are here) → search/entities → view/edit"));
+                console.log("");
+                console.log(bold("SUMMARY"));
+                console.log(`  ${result.summary.format} · ${result.summary.counts.entities} entities · ${result.summary.counts.layers} layers · ${result.summary.counts.blocks} blocks`);
+                console.log("");
+                if (result.layers.length > 0) {
+                    console.log(bold("LAYERS"));
+                    for (const layer of result.layers) {
+                        console.log(layer.name);
+                        console.log(`  ${dim("entities:")} ${layer.entities}`);
+                        if (layer.types.length > 0) {
+                            console.log(`  ${dim("types:")} ${layer.types.join(", ")}`);
+                        }
+                        if (layer.keywords.length > 0) {
+                            console.log(`  ${dim("keywords:")} ${layer.keywords.join(", ")}`);
+                        }
+                    }
+                    console.log("");
+                }
+                if (result.blocks.length > 0) {
+                    console.log(bold("BLOCKS"));
+                    console.log(`  ${result.blocks
+                        .slice(0, 12)
+                        .map((block) => block.name)
+                        .join(", ")}`);
+                    console.log("");
+                }
+                if (result.text.keywords.length > 0) {
+                    console.log(bold("TEXT"));
+                    console.log(`  ${dim("keywords:")} ${result.text.keywords.join(", ")}`);
+                    if (result.text.samples.length > 0) {
+                        console.log(`  ${dim("samples:")} ${result.text.samples.join(" · ")}`);
+                    }
+                    console.log("");
+                }
+                if (result.searchHints.length > 0) {
+                    console.log(bold("SEARCH HINTS"));
+                    console.log(`  ${result.searchHints.join(", ")}`);
+                    console.log("");
+                }
+                console.log(dim("HINT: Use cadcli search <file> <query> or cadcli entities <file> --layer <name> to drill in."));
+            },
+        });
+    }
+    catch (err) {
+        handleCommandError(err);
+    }
+}

package/dist/commands/search.d.ts

@@ -0,0 +1,11 @@
+import { type DrawingCommandOptions } from "./shared.js";
+export interface SearchOptions extends DrawingCommandOptions {
+    query?: string;
+    type?: string;
+    layer?: string;
+    limit?: string;
+    total?: boolean;
+    score?: boolean;
+    snippets?: boolean;
+}
+export declare function search(file: string, options: SearchOptions): Promise<void>;

package/dist/commands/search.js

@@ -0,0 +1,45 @@
+import { bold, dim, output } from "../utils/output.js";
+import { drawingFor, handleCommandError, parseLimit, } from "./shared.js";
+export async function search(file, options) {
+    try {
+        const results = await drawingFor(file, options).search({
+            query: options.query,
+            type: options.type,
+            layer: options.layer,
+            limit: parseLimit(options.limit),
+            snippets: options.snippets,
+        });
+        output(options, {
+            json: () => {
+                if (options.total)
+                    return { total: results.length };
+                return {
+                    results: results.map((result) => {
+                        const { score, matches, ...rest } = result;
+                        return {
+                            ...rest,
+                            ...(options.score ? { score } : {}),
+                            ...(options.snippets === false ? {} : { matches }),
+                        };
+                    }),
+                };
+            },
+            human: () => {
+                if (options.total) {
+                    console.log(String(results.length));
+                    return;
+                }
+                for (const result of results) {
+                    console.log(`${bold(result.entityId)} ${result.type}${result.layer ? ` ${dim(result.layer)}` : ""}${options.score ? ` ${dim(`score: ${result.score}`)}` : ""}`);
+                    if (options.snippets !== false) {
+                        for (const match of result.matches)
+                            console.log(`  ${dim(match)}`);
+                    }
+                }
+            },
+        });
+    }
+    catch (err) {
+        handleCommandError(err);
+    }
+}

package/dist/commands/shared.d.ts

@@ -0,0 +1,16 @@
+import { DwgCliError } from "../core/errors.js";
+import { Dwg } from "../sdk.js";
+import type { DrawingReader } from "../types.js";
+import type { OutputOptions } from "../utils/output.js";
+export interface DrawingCommandOptions extends OutputOptions {
+    reader?: DrawingReader;
+    toolDir?: string;
+}
+export interface OutputFileOptions extends OutputOptions {
+    output?: string;
+}
+export declare function drawingFor(file: string, options: DrawingCommandOptions): Dwg;
+export declare function userError(message: string, code?: string): DwgCliError;
+export declare function handleCommandError(err: unknown): never;
+export declare function parseLimit(value?: string): number | undefined;
+export declare function writeCommandOutput(options: OutputFileOptions, content: string | Uint8Array, jsonPayload: () => unknown, humanMessage: string): void;

package/dist/commands/shared.js

@@ -0,0 +1,40 @@
+import { DwgCliError } from "../core/errors.js";
+import { writeOutput } from "../core/files.js";
+import { Dwg } from "../sdk.js";
+import { EXIT_USER_ERROR } from "../utils/exit-codes.js";
+import { error, output, success } from "../utils/output.js";
+export function drawingFor(file, options) {
+    return Dwg.open(file, {
+        reader: options.reader,
+        toolDir: options.toolDir,
+    });
+}
+export function userError(message, code = "USER_ERROR") {
+    return new DwgCliError(message, code, EXIT_USER_ERROR);
+}
+export function handleCommandError(err) {
+    if (err instanceof DwgCliError) {
+        error(err.message);
+        process.exit(err.exitCode);
+    }
+    error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+}
+export function parseLimit(value) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        throw userError(`Invalid limit: ${value}`, "INVALID_LIMIT");
+    }
+    return parsed;
+}
+export function writeCommandOutput(options, content, jsonPayload, humanMessage) {
+    if (!options.output)
+        return;
+    writeOutput(options.output, content);
+    output(options, {
+        json: jsonPayload,
+        human: () => success(humanMessage),
+    });
+}

package/dist/commands/svg.d.ts

@@ -0,0 +1,2 @@
+import { type DrawingCommandOptions, type OutputFileOptions } from "./shared.js";
+export declare function svg(file: string, options: DrawingCommandOptions & OutputFileOptions): Promise<void>;

package/dist/commands/svg.js

@@ -0,0 +1,27 @@
+import { toSvg } from "../core/drawing.js";
+import { handleCommandError, writeCommandOutput, } from "./shared.js";
+export async function svg(file, options) {
+    try {
+        const result = await toSvg(file, {
+            reader: options.reader,
+            toolDir: options.toolDir,
+        });
+        if (options.output) {
+            writeCommandOutput(options, result.svg, () => ({
+                success: true,
+                file: options.output,
+                rendered: result.rendered,
+                unsupported: result.unsupported,
+            }), `Wrote ${options.output} (${result.rendered} rendered, ${result.unsupported} unsupported)`);
+        }
+        else if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(result.svg.trimEnd());
+        }
+    }
+    catch (err) {
+        handleCommandError(err);
+    }
+}

package/dist/commands/thumbnail.d.ts

@@ -0,0 +1,2 @@
+import { type DrawingCommandOptions, type OutputFileOptions } from "./shared.js";
+export declare function thumbnail(file: string, options: DrawingCommandOptions & OutputFileOptions): Promise<void>;

package/dist/commands/thumbnail.js

@@ -0,0 +1,31 @@
+import { getThumbnail } from "../core/drawing.js";
+import { output, success } from "../utils/output.js";
+import { handleCommandError, writeCommandOutput, } from "./shared.js";
+export async function thumbnail(file, options) {
+    try {
+        const result = await getThumbnail(file, {
+            reader: options.reader,
+            toolDir: options.toolDir,
+        });
+        if (!options.output) {
+            output(options, {
+                json: () => ({
+                    mimeType: result.mimeType,
+                    extension: result.extension,
+                    bytes: result.data.length,
+                }),
+                human: () => success(`Thumbnail available (${result.mimeType}, ${result.data.length} bytes). Use -o to write it.`),
+            });
+            return;
+        }
+        writeCommandOutput(options, result.data, () => ({
+            success: true,
+            file: options.output,
+            mimeType: result.mimeType,
+            bytes: result.data.length,
+        }), `Wrote ${options.output}`);
+    }
+    catch (err) {
+        handleCommandError(err);
+    }
+}

package/dist/commands/view.d.ts

@@ -0,0 +1,6 @@
+import type { OutputOptions } from "../utils/output.js";
+export interface ViewOptions extends OutputOptions {
+    output?: string;
+    toolDir?: string;
+}
+export declare function view(file: string, options: ViewOptions): Promise<void>;

package/dist/commands/view.js

@@ -0,0 +1,27 @@
+import { renderSvgWithLibreDwg } from "../core/libredwg.js";
+import { handleCommandError, writeCommandOutput } from "./shared.js";
+export async function view(file, options) {
+    try {
+        const result = renderSvgWithLibreDwg(file, { toolDir: options.toolDir });
+        const svg = result.svg;
+        const tool = result.tool;
+        if (options.output) {
+            writeCommandOutput(options, svg, () => ({
+                success: true,
+                file: options.output,
+                backend: "LibreDWG",
+                tool,
+            }), `Wrote ${options.output} with ${tool}`);
+            return;
+        }
+        if (options.json) {
+            console.log(JSON.stringify({ backend: "LibreDWG", tool, svg }, null, 2));
+        }
+        else {
+            console.log(svg.trimEnd());
+        }
+    }
+    catch (err) {
+        handleCommandError(err);
+    }
+}

package/dist/core/adapter.d.ts

@@ -0,0 +1,14 @@
+import type { CadDocument } from "@node-projects/acad-ts";
+import type { DrawingReader, DwgFormat, ThumbnailResult } from "../types.js";
+export declare function arrayBufferFor(bytes: Uint8Array): ArrayBuffer;
+export declare function normalizeAcadDocument(doc: CadDocument): unknown;
+export declare class AcadTsReader implements DrawingReader {
+    parse(_file: string, bytes: Uint8Array, format: DwgFormat): Promise<unknown>;
+    thumbnail(): Promise<ThumbnailResult | null>;
+}
+export declare class NativeLibreDwgReader implements DrawingReader {
+    private readonly toolDir?;
+    constructor(toolDir?: string | undefined);
+    parse(file: string, _bytes: Uint8Array, _format: DwgFormat): Promise<unknown>;
+    thumbnail(): Promise<ThumbnailResult | null>;
+}