@pcbjs/cli 0.0.0 → 0.0.1-next.9029beb783788cfbb471cc9d57e1b47864c6eaa6

package/dist/check.d.ts

@@ -0,0 +1,83 @@
+import { type Logger, type LogLevel, type ViteDevServer } from 'vite';
+import type { ResolvedConfig } from './config.js';
+import type { PluginState } from './plugin.js';
+import { type Compiled } from './project.js';
+import { type BoardSlot } from './boards.js';
+import { counts, type Finding } from '@pcbjs/export/findings';
+import { countModels } from '@pcbjs/core/model-source';
+export interface OutputOptions {
+    /** summary lines and findings only */
+    quiet?: boolean;
+    /** Vite's own logging and the stack of a compile error */
+    verbose?: boolean;
+    json?: string;
+}
+/** Silent unless --verbose or the project config asks for one. */
+export declare function logLevelFor(cfg: ResolvedConfig, verbose?: boolean): 'info' | 'warn' | 'error' | 'silent';
+/** Without Vite's report of a module that fails to evaluate: pcbjs prints the one line, the stack with --verbose. */
+export declare function quietLogger(level: LogLevel): Logger;
+/** No HTTP, no HMR socket, no file watcher unless `watch`. */
+export declare function compileServer(cfg: ResolvedConfig, state: PluginState, o?: {
+    verbose?: boolean;
+    watch?: boolean;
+}): Promise<ViteDevServer>;
+/** One line, then with --verbose the code frame and the stack below it. */
+export declare function errorText(e: any, verbose?: boolean, root?: string): {
+    line: string;
+    detail: string[];
+};
+/** Keeps on after a failure; the error of a failed one goes in `slot.error`. */
+export declare function compileSlots(server: ViteDevServer, cfg: ResolvedConfig, slots: BoardSlot[], errors: Map<BoardSlot, unknown>): Promise<void>;
+/** One per target of a board with variants. */
+export interface ReportBoard {
+    name: string;
+    target: string | null;
+    entry: string;
+    status: 'ok' | 'fail' | 'error';
+    stats: Compiled['board']['stats'] | null;
+    /** phase timings in ms when the compiler records them */
+    timings: unknown;
+    /** absent on a board without automatic routes */
+    routing?: Compiled['board']['routing'];
+    ms: number | null;
+    counts: ReturnType<typeof counts> | null;
+    /** see docs/schematic-graphic.md */
+    schematic?: import('@pcbjs/core/sch-model').SchStats;
+    /** parts by where their 3D body comes from */
+    models?: ReturnType<typeof countModels>;
+    drc: Finding[];
+    erc: Finding[];
+    fab: {
+        dir: string;
+        zip: string;
+    } | null;
+    pages: string[];
+    error?: string;
+}
+export interface Report {
+    boards: ReportBoard[];
+}
+export declare function reportOf(cfg: ResolvedConfig, s: BoardSlot, e: unknown, extra?: {
+    fab?: (c: Compiled) => ReportBoard['fab'];
+    pages?: string[];
+}): ReportBoard[];
+export declare function writeReport(cfg: ResolvedConfig, file: string, report: Report): string;
+/** A line per target, then the findings of every target merged, at most `cap` lines per rule; every one with `verbose`. */
+export declare function slotLines(s: BoardSlot, e: unknown, o: {
+    root: string;
+    cap: number;
+    verbose?: boolean;
+    more?: string;
+}): string[];
+/** Every board's counts added up. */
+export declare function totalLine(slots: BoardSlot[]): string;
+export declare const slotsFailed: (slots: BoardSlot[]) => boolean;
+/** Mark a failed entry's outputs stale: its board JSON gets `stale: true` and the error, each fab directory a STALE file. */
+export declare function markStale(cfg: ResolvedConfig, entry: string, error: string): string[];
+export declare const CHECK_CAP = 10;
+/** No fab files and no site. With `watch`, recompile on every change and print the diff. */
+export declare function check(opts: OutputOptions & {
+    cfg: ResolvedConfig;
+    state: PluginState;
+    watch?: boolean;
+}): Promise<number>;

package/dist/check.js

@@ -0,0 +1,261 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { createLogger, createServer } from 'vite';
+import { viteConfig } from './vite.js';
+import { compileEntry } from './project.js';
+import { markConflicts } from './boards.js';
+import { boardFindings, boardLine, counts, routingLines, diffFindings, diffLine, failing, findingLine, formatFindings, orderFindings } from '@pcbjs/export/findings';
+import { variantSlug } from '@pcbjs/core/variants';
+import { countModels } from '@pcbjs/core/model-source';
+import { typecheck, typeErrorLine } from './typecheck.js';
+/** Silent unless --verbose or the project config asks for one. */
+export function logLevelFor(cfg, verbose) {
+    if (verbose)
+        return 'info';
+    return cfg.vite?.logLevel ?? 'silent';
+}
+/** Without Vite's report of a module that fails to evaluate: pcbjs prints the one line, the stack with --verbose. */
+export function quietLogger(level) {
+    const logger = createLogger(level, { allowClearScreen: false });
+    const error = logger.error.bind(logger);
+    logger.error = (msg, o) => { if (!strip(msg).includes('Error when evaluating SSR module'))
+        error(msg, o); };
+    return logger;
+}
+/** No HTTP, no HMR socket, no file watcher unless `watch`. */
+export async function compileServer(cfg, state, o = {}) {
+    const vc = viteConfig(cfg, state, 'build');
+    return createServer({
+        ...vc, logLevel: logLevelFor(cfg, o.verbose), customLogger: quietLogger(logLevelFor(cfg, o.verbose)),
+        server: { ...vc.server, middlewareMode: true, ws: false, hmr: false, watch: o.watch ? {} : null },
+        optimizeDeps: { noDiscovery: true, include: [] }, appType: 'custom', mode: 'production',
+    });
+}
+const strip = (t) => t.replace(/\x1b\[[0-9;]*m/g, '');
+/** One line, then with --verbose the code frame and the stack below it. */
+export function errorText(e, verbose, root) {
+    const msg = strip(String(e?.message ?? e));
+    const first = msg.split('\n').find(l => l.trim()) ?? msg;
+    const rel = (f) => (root && f.startsWith(root + '/') ? f.slice(root.length + 1) : f);
+    // Vite's location of a syntax error, else the first frame of the stack in the project
+    let loc = e?.loc?.file ? `${rel(e.loc.file)}:${e.loc.line}:${e.loc.column}: ` : '';
+    if (!loc && root && !/\.(m?[jt]sx?):\d+:\d+/.test(first)) {
+        for (const l of strip(String(e?.stack ?? '')).split('\n')) {
+            const m = /^\s+at (?:.*\()?(?:file:\/\/)?(\/[^()]+?):(\d+):(\d+)\)?$/.exec(l);
+            if (m && m[1].startsWith(root + '/') && !m[1].includes('/node_modules/')) {
+                loc = `${rel(m[1])}:${m[2]}:${m[3]}: `;
+                break;
+            }
+        }
+    }
+    const detail = [];
+    if (verbose) {
+        const rest = msg.split('\n').slice(msg.split('\n').indexOf(first) + 1).filter(l => l.trim());
+        detail.push(...rest);
+        if (e?.frame)
+            detail.push(...strip(String(e.frame)).split('\n'));
+        const stack = strip(String(e?.stack ?? '')).split('\n').filter(l => /^\s+at /.test(l));
+        detail.push(...stack);
+    }
+    return { line: `${loc}${first}`, detail };
+}
+/** Keeps on after a failure; the error of a failed one goes in `slot.error`. */
+export async function compileSlots(server, cfg, slots, errors) {
+    for (const s of slots) {
+        try {
+            s.compiled = await compileEntry(server, cfg, s.entry, false);
+            s.error = null;
+            errors.delete(s);
+        }
+        catch (e) {
+            s.error = strip(String(e?.message ?? e));
+            s.compiled = null;
+            errors.set(s, e);
+        }
+    }
+    markConflicts(slots);
+}
+export function reportOf(cfg, s, e, extra = {}) {
+    const rel = (p) => relative(cfg.root, p) || '.';
+    if (!s.compiled || s.conflict) {
+        const err = s.conflict ?? errorText(e, false, cfg.root).line;
+        return [{ name: s.entry.rel, target: null, entry: s.entry.rel, status: 'error', stats: null, timings: null, ms: null, counts: null, drc: [], erc: [], fab: null, pages: [], error: err }];
+    }
+    return s.compiled.map(c => {
+        const b = c.board;
+        const f = boardFindings(b, cfg.root);
+        const slug = b.variant ? variantSlug(b.variant.name) : null;
+        const pages = (extra.pages ?? []).filter(p => p === `board/${b.name}` || (slug ? p === `board/${b.name}/${slug}` : false));
+        const fab = extra.fab?.(c) ?? null;
+        return {
+            name: b.name, target: b.variant?.name ?? null, entry: c.entry.rel, status: failing(b) ? 'fail' : 'ok',
+            stats: b.stats, timings: b.timings ?? null, ...(b.routing ? { routing: b.routing } : {}), ms: Math.round(c.ms), counts: counts(b), ...(b.schematic.drawing ? { schematic: b.schematic.drawing.stats } : {}), models: countModels(c.site.footprints),
+            drc: orderFindings(f.filter(x => x.kind === 'drc')), erc: orderFindings(f.filter(x => x.kind === 'erc')),
+            fab: fab ? { dir: rel(fab.dir), zip: rel(fab.zip) } : null, pages,
+        };
+    });
+}
+export function writeReport(cfg, file, report) {
+    const abs = resolve(cfg.root, file);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, JSON.stringify(report, null, 2) + '\n');
+    return relative(cfg.root, abs) || abs;
+}
+/** A line per target, then the findings of every target merged, at most `cap` lines per rule; every one with `verbose`. */
+export function slotLines(s, e, o) {
+    if (s.conflict)
+        return [`${s.entry.rel}  error: ${s.conflict}`];
+    if (!s.compiled) {
+        const t = errorText(e, o.verbose, o.root);
+        return [`${s.entry.rel}  compile error: ${t.line}`, ...t.detail.map(l => `  ${l}`)];
+    }
+    const out = s.compiled.map(c => boardLine(c.board, c.entry.rel, c.ms));
+    out.push(...routingLines(s.compiled.map(c => c.board)));
+    const targets = s.compiled.map(c => ({ target: c.board.variant?.name, findings: boardFindings(c.board, o.root) }));
+    out.push(...formatFindings(targets, { cap: o.cap, more: o.more, all: o.verbose }));
+    return out;
+}
+/** Every board's counts added up. */
+export function totalLine(slots) {
+    let de = 0, dw = 0, un = 0, ee = 0, ew = 0, bad = 0, failed = 0;
+    for (const s of slots) {
+        if (!s.compiled || s.conflict) {
+            failed++;
+            continue;
+        }
+        for (const c of s.compiled) {
+            const k = counts(c.board);
+            de += k.drcErrors;
+            dw += k.drcWarnings;
+            un += k.unconnected;
+            ee += k.ercErrors;
+            ew += k.ercWarnings;
+            if (failing(c.board))
+                bad++;
+        }
+    }
+    const ok = !bad && !failed;
+    const n = (k, w) => `${k} ${w}${k === 1 ? '' : 's'}`;
+    return `${ok ? 'ok  ' : 'FAIL'}  DRC ${n(de, 'error')}, ${n(dw, 'warning')}, ${un} unconnected  ERC ${n(ee, 'error')}, ${n(ew, 'warning')}${failed ? `  ${failed} entr${failed === 1 ? 'y' : 'ies'} failed to compile` : ''}`;
+}
+export const slotsFailed = (slots) => slots.some(s => !s.compiled || s.conflict || s.compiled.some(c => failing(c.board)));
+/** Mark a failed entry's outputs stale: its board JSON gets `stale: true` and the error, each fab directory a STALE file. */
+export function markStale(cfg, entry, error) {
+    const index = join(cfg.outDir, 'boards.json');
+    if (!existsSync(index))
+        return [];
+    let boards = [];
+    try {
+        boards = JSON.parse(readFileSync(index, 'utf8')).boards ?? [];
+    }
+    catch {
+        return [];
+    }
+    const marked = [];
+    const note = `STALE: the last compile of ${entry} failed, these files are from an earlier build.\n${error}\n`;
+    for (const b of boards.filter(b => b.entry === entry)) {
+        const file = join(cfg.outDir, ...b.file.split('/').map(decodeURIComponent));
+        if (existsSync(file)) {
+            try {
+                const data = JSON.parse(readFileSync(file, 'utf8'));
+                writeFileSync(file, JSON.stringify({ ...data, stale: true, staleError: error }));
+                marked.push(relative(cfg.root, file));
+            }
+            catch { /* not ours */ }
+        }
+        const segs = [b.name, ...(b.variant ? [variantSlug(b.variant)] : [])];
+        for (const dir of [join(cfg.fabDir, ...segs), join(cfg.outDir, 'fab', ...segs)]) {
+            if (!existsSync(dir))
+                continue;
+            writeFileSync(join(dir, 'STALE'), note);
+            marked.push(relative(cfg.root, join(dir, 'STALE')));
+        }
+    }
+    return marked;
+}
+export const CHECK_CAP = 10;
+/** No fab files and no site. With `watch`, recompile on every change and print the diff. */
+export async function check(opts) {
+    const { cfg, state } = opts;
+    const server = await compileServer(cfg, state, { verbose: opts.verbose, watch: opts.watch });
+    const errors = new Map();
+    const run = async () => {
+        await compileSlots(server, cfg, state.slots, errors);
+        const now = new Map();
+        for (const s of state.slots)
+            if (s.compiled && !s.conflict)
+                for (const c of s.compiled)
+                    now.set(`${c.board.name}|${c.board.variant?.name ?? ''}`, boardFindings(c.board, cfg.root));
+        return now;
+    };
+    const print = () => {
+        for (const s of state.slots)
+            for (const l of slotLines(s, errors.get(s), { root: cfg.root, cap: CHECK_CAP, verbose: opts.verbose, more: opts.json ? `all in ${opts.json}` : 'all with --verbose or --json <file>' }))
+                console.log(l);
+        console.log(totalLine(state.slots));
+        if (opts.json)
+            console.log(`json   ${writeReport(cfg, opts.json, { boards: state.slots.flatMap(s => reportOf(cfg, s, errors.get(s))) })}`);
+    };
+    try {
+        let last = await run();
+        print();
+        // cached per file, see typecheck.ts
+        const tc = typecheck(cfg.root, cfg.entries.map(e => e.file));
+        if (tc) {
+            console.log(`typecheck  ${tc.errors.length ? `${tc.errors.length} error${tc.errors.length === 1 ? '' : 's'}` : 'ok'}  ${Math.round(tc.ms)} ms${tc.cached ? ', cached' : ''}`);
+            for (const e of tc.errors.slice(0, 20))
+                console.log(typeErrorLine(e, opts.verbose));
+            if (tc.errors.length > 20)
+                console.log(`  and ${tc.errors.length - 20} more, all with npx tsc --noEmit`);
+        }
+        if (!opts.watch)
+            return slotsFailed(state.slots) || tc?.errors.length ? 1 : 0;
+        console.log(`watching ${cfg.root} for changes, Ctrl-C to stop`);
+        const graph = server.environments.ssr.moduleGraph;
+        let timer = null, busy = null;
+        const again = async () => {
+            graph.invalidateAll();
+            const t0 = performance.now();
+            const now = await run();
+            const lines = [];
+            for (const s of state.slots) {
+                if (!s.compiled || s.conflict) {
+                    lines.push(...slotLines(s, errors.get(s), { root: cfg.root, cap: 10, verbose: opts.verbose }));
+                    continue;
+                }
+                for (const c of s.compiled) {
+                    const key = `${c.board.name}|${c.board.variant?.name ?? ''}`;
+                    const d = diffFindings(last.get(key) ?? [], now.get(key) ?? []);
+                    lines.push(`${boardLine(c.board, c.entry.rel, c.ms)}  ${diffLine(d)}`);
+                    for (const f of d.added)
+                        lines.push(`  new  ${findingLine(f)}`);
+                }
+            }
+            last = now;
+            console.log(`\n${new Date().toLocaleTimeString()}  recompiled in ${Math.round(performance.now() - t0)} ms`);
+            for (const l of lines)
+                console.log(l);
+            console.log(totalLine(state.slots));
+            if (opts.json)
+                writeReport(cfg, opts.json, { boards: state.slots.flatMap(s => reportOf(cfg, s, errors.get(s))) });
+        };
+        const inProject = (f) => f.startsWith(cfg.root) && !f.includes('/.pcbjs/') && !f.includes('/node_modules/') && /\.(m?[jt]sx?|json)$/.test(f);
+        const changed = (f) => {
+            if (!inProject(f))
+                return;
+            if (timer)
+                clearTimeout(timer);
+            timer = setTimeout(() => { timer = null; busy = (busy ?? Promise.resolve()).then(again).catch(e => console.error(`pcbjs: ${e?.message ?? e}`)); }, 80);
+        };
+        server.watcher.add(cfg.root);
+        server.watcher.on('change', changed);
+        server.watcher.on('add', changed);
+        server.watcher.on('unlink', changed);
+        await new Promise(done => { for (const sig of ['SIGINT', 'SIGTERM'])
+            process.once(sig, () => done()); });
+        return 0;
+    }
+    finally {
+        await server.close();
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+import type { InspectRequest } from './dev-reuse.js';
+/** The first argument is the entry when it names a module; a bare `--lengths` makes each query a filter, or adds the whole table. */
+export declare function inspectRequests(args: string[], lengths: unknown, layers?: string[]): {
+    entry?: string;
+    requests: InspectRequest[];
+};
+export declare function run(argv?: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,278 @@
+import { cac } from 'cac';
+import { dev } from './server.js';
+import { devWorkspace } from './workspace.js';
+import { build, preview } from './build.js';
+import { ideInstall, ideStatus } from './ide.js';
+import { create } from './create.js';
+import { check } from './check.js';
+import { inspect } from './inspect.js';
+import { modelAdd, modelAlign, modelCheck, modelFetch } from './model.js';
+import { docs } from './docs.js';
+import { skills } from './skills.js';
+import { importCommand } from './import.js';
+import { parseSize, shot } from './shot.js';
+import { resolveConfig } from './config.js';
+import { pluginState } from './plugin.js';
+import { cliVersion, doctor, warnVersionSkew } from './doctor.js';
+import { versionLine } from './version.js';
+import { fabDate } from '@pcbjs/export/fab';
+const cli = cac('pcbjs');
+cli.usage('<build|check|dev|preview> [entry...] [options]\n       pcbjs dev --workspace <folder>... [options]\n       pcbjs inspect [entry] [ref|net|REF.PAD|references|sch...] [--lengths [net|pair|group]] [--layer <name>] [--json]\n       pcbjs model add <file-or-url|lcsc:C123> [--ref [<board>/]<REF> | --footprint <name>] [--entry <board>] [--as <name>] [--write]\n       pcbjs model add --ref <REF> [--write], the model of its MPN:LCSC number\n       pcbjs model align [entry] [<board>/]<ref> [--file <model>]\n       pcbjs model check [entry...]\n       pcbjs model fetch [entry...]\n       pcbjs shot [entry...] [-o <dir>] [-p <port>] [--view 2d|3d|sch|both|all] [--select <ref>...] [--layer <name>...] [--side top|bottom] [--size WxH]\n       pcbjs import footprint <Lib:Name|file.kicad_mod> [-o lib/<name>.tsx] [--force]\n       pcbjs import board <file.kicad_pcb> [-o pcb.tsx] [--force]\n       pcbjs docs [topic] [--grep <word|regex>]\n       pcbjs ide <install|status>\n       pcbjs skills <install [--to <dir>]|list|path>\n       pcbjs doctor\n       pcbjs create <dir> [--template board]\n\n  The entries are `entries` in pcb.config.ts, paths relative to it, globs allowed; entries on the command line win for that run.\n  Each entry is a .tsx or .ts module that default-exports <PCB>. Several entries make a multi-board site.\n  The current directory is the project root. The config is pcb.config.ts, .mts, .js or .mjs in it; pcbjs.config.* still loads with a warning.');
+cli.command('dev [...entries]', 'dev server: compiles the boards, updates the viewer on every change, serves fab files on demand; --workspace serves every project under the folders')
+    .option('--workspace [folder]', 'serve every directory with a pcb.config.* under the folders, given here or as the arguments; each loads on first use')
+    .option('-c, --config <file>', 'config file (default: pcb.config.ts, .mts, .js or .mjs)')
+    .option('-p, --port <port>', 'port (default 5173)')
+    .option('--host [host]', 'listen on all addresses or the given one')
+    .option('--open', 'open the browser')
+    .option('--ide <url>', 'dial an editor host, ws://127.0.0.1:<port>/<token>, for the hosted IDE mode')
+    .option('--ide-allow-remote', 'let --ide dial a host other than 127.0.0.1, localhost or [::1]')
+    .option('--verbose', 'keep the stack of a compile error')
+    .action(async (entries, o) => {
+    if (o.ide === true || o.ide === '')
+        usageError('--ide needs a URL, for example --ide=ws://127.0.0.1:5220/<token>');
+    warnVersionSkew();
+    const common = { port: portOf(o.port), host: o.host, open: o.open, ide: o.ide, ideAllowRemote: !!o.ideAllowRemote, verbose: !!o.verbose };
+    if (o.workspace !== undefined && o.workspace !== false) {
+        if (o.config)
+            usageError('--config names one project; with --workspace each project uses its own pcb.config.*');
+        const given = (Array.isArray(o.workspace) ? o.workspace : [o.workspace]).filter((f) => typeof f === 'string' && f);
+        const folders = [...given, ...entries].map(String);
+        await devWorkspace({ folders: folders.length ? folders : ['.'], ...common });
+        return;
+    }
+    await dev({ entries, config: o.config, ...common });
+});
+cli.command('build [...entries]', 'compile the boards, write the fab files and the static site; exit 1 on DRC or ERC errors')
+    .option('-c, --config <file>', 'config file (default: pcb.config.ts, .mts, .js or .mjs)')
+    .option('--out-dir <dir>', 'site output (default .pcbjs/dist)')
+    .option('-q, --quiet', 'print only the board lines, the findings and the total')
+    .option('--verbose', "print every finding, Vite's output, the prerendered pages and the stack of a compile error")
+    .option('--json <file>', 'write every board, its findings with stable ids, its fab set and pages to <file>')
+    .option('--date <iso>', 'the date every fab file carries, such as 2026-01-31T12:00:00Z, so two builds of one tree are byte identical (default SOURCE_DATE_EPOCH, else now)')
+    .action(async (entries, o) => {
+    if (o.date === true || o.date === '')
+        usageError('--date needs a date, for example --date 2026-01-31T12:00:00Z');
+    if (o.date !== undefined)
+        try {
+            fabDate(String(o.date));
+        }
+        catch (e) {
+            usageError(`--date: ${e.message}`);
+        }
+    warnVersionSkew();
+    await build({ entries, config: o.config, outDir: o.outDir, quiet: !!o.quiet, verbose: !!o.verbose, json: jsonFile(o.json), date: o.date === undefined ? undefined : String(o.date) });
+});
+cli.command('check [...entries]', 'compile and run DRC and ERC only: no fab files, no site; exit 1 on errors')
+    .option('-c, --config <file>', 'config file (default: pcb.config.ts, .mts, .js or .mjs)')
+    .option('-w, --watch', 'recompile on every change and print what is new, fixed and unchanged')
+    .option('-q, --quiet', 'the same output as without it; accepted for symmetry with build')
+    .option('--verbose', "print every finding, unfolded and uncapped, Vite's output and the stack of a compile error")
+    .option('--json <file>', 'write every board and its findings with stable ids to <file>')
+    .option('--fab', 'also write the fab set in memory and read its copper and outline Gerbers back, as build does: a difference is a fab-mismatch error')
+    .action(async (entries, o) => {
+    warnVersionSkew();
+    const cfg = await resolveConfig(entries, 'build', o.config);
+    if (o.fab)
+        cfg.fabCheck = true;
+    process.exitCode = await check({ cfg, state: pluginState(cfg), watch: !!o.watch, quiet: !!o.quiet, verbose: !!o.verbose, json: jsonFile(o.json) });
+});
+cli.command('inspect [...queries]', 'compile one board and print its frame and footprints, or each query: a ref with its pads, a net with its pads, vias and routes, a pad as REF.PAD; --lengths prints the route table; one compile answers them all')
+    .option('-c, --config <file>', 'config file (default: pcb.config.ts, .mts, .js or .mjs)')
+    .option('-t, --target <name>', 'the target of a board with variants, by name or slug (default the first)')
+    .option('--json', 'print JSON instead of text')
+    .option('--lengths [filter]', 'print every route with its length, target, match group, status and source, or those of one net, pair or match group; repeat it for several')
+    .option('--layer <name>', 'print every item on the layer, by id or alias, with its bounds, text, ref and source: strokes and glyphs of text, drawings, tracks, pours, pads; a query filters it by part or net; repeatable')
+    .option('--fresh', 'compile here even when a running dev server of the project holds a current board')
+    .option('--verbose', "show Vite's output and the stack of a compile error")
+    .action(async (args, o) => {
+    const layers = (o.layer === undefined ? [] : Array.isArray(o.layer) ? o.layer : [o.layer]).map(String);
+    if (layers.some(l => l === 'true' || l === ''))
+        usageError('--layer needs a layer, for example --layer F.SilkS');
+    const { entry, requests } = inspectRequests(args.map(String), o.lengths, layers);
+    process.exitCode = await inspect({ entry, requests, config: o.config, json: !!o.json, target: o.target, verbose: !!o.verbose, fresh: !!o.fresh });
+});
+cli.command('shot [...entries]', 'PNG screenshots of the viewer with a headless Chrome: one per board, target and view, to .pcbjs/shots/<board>-<view>[-<options>].png')
+    .option('-c, --config <file>', 'config file (default: pcb.config.ts, .mts, .js or .mjs)')
+    .option('-o, --out <dir>', 'output directory (default .pcbjs/shots)')
+    .option('-p, --port <port>', 'port of the dev server the shots are taken from (default a free port)')
+    .option('--view <view>', '2d, 3d, sch, both or all (default both, 2d and 3d; all adds the schematic)')
+    .option('--explode <amount>', 'the exploded 3D view, 0 to 1 of the largest layer separation')
+    .option('--layer <name>', 'show one layer alone in 2D, by id or alias, the outline kept; repeat it for one shot per layer')
+    .option('--select <ref>', 'select a part and zoom to it: its courtyard in 2D, the camera on it in 3D; repeat it for one shot per part')
+    .option('--fresh', 'compile here even when a running dev server of the project holds current boards')
+    .option('--size <WxH>', 'page size in CSS pixels (default 1600x1000)')
+    .option('--theme <theme>', 'light or dark (default the system theme of the headless browser, light)')
+    .option('--side <side>', 'top or bottom: bottom views the board from below, the 2D view flipped to the back and the 3D camera under the board (default top)')
+    .option('--flip', 'the same as --side bottom')
+    .option('--verbose', "show Vite's output")
+    .action(async (entries, o) => {
+    const view = o.view === undefined ? 'both' : String(o.view).toLowerCase();
+    if (!['2d', '3d', 'sch', 'both', 'all'].includes(view))
+        usageError(`bad --view: ${o.view}, use 2d, 3d, sch, both or all`);
+    const explode = o.explode === undefined ? undefined : Number(o.explode);
+    if (explode !== undefined && !(explode >= 0 && explode <= 1))
+        usageError(`bad --explode: ${o.explode}, use a number from 0 to 1`);
+    const size = o.size === undefined ? undefined : parseSize(String(o.size));
+    if (size === null)
+        usageError(`bad --size: ${o.size}, use WxH such as 1600x1000`);
+    const theme = o.theme === undefined ? undefined : String(o.theme).toLowerCase();
+    if (theme !== undefined && theme !== 'light' && theme !== 'dark')
+        usageError(`bad --theme: ${o.theme}, use light or dark`);
+    const side = o.side === undefined ? (o.flip ? 'bottom' : undefined) : String(o.side).toLowerCase();
+    if (side !== undefined && side !== 'top' && side !== 'bottom')
+        usageError(`bad --side: ${o.side}, use top or bottom`);
+    if (o.flip && side === 'top')
+        usageError('--flip views the bottom; give it or --side top, not both');
+    const many = (v) => (v === undefined ? undefined : (Array.isArray(v) ? v : [v]).map(String));
+    for (const k of ['out', 'layer', 'select'])
+        if (many(o[k])?.some(v => v === 'true' || v === ''))
+            usageError(`--${k} needs a value`);
+    if (Array.isArray(o.out))
+        usageError('give --out once');
+    process.exitCode = await shot({ entries, config: o.config, outDir: o.out, view: view, explode, layer: many(o.layer), select: many(o.select), size, theme: theme, side: side, verbose: !!o.verbose, port: portOf(o.port), fresh: !!o.fresh });
+});
+cli.command('model <action> [...args]', 'model files: `add <file-or-url|lcsc:C123>` copies or downloads one into models/ and fits it with --ref, and with --ref alone fetches the part\'s MPN:LCSC model; `align [entry] <ref>` prints the transform that puts a model on its pads; `check [entry...]` lists every model and flags missing, unread and misplaced ones; `fetch [entry...]` downloads the models the parts name, KiCad library, LCSC or URL, into .pcbjs/models/fetched')
+    .option('-c, --config <file>', 'config file (default: pcb.config.ts, .mts, .js or .mjs)')
+    .option('--ref <ref>', 'add: fit the model to this placed part and print its model option; `<board>/<ref>`, such as Sense/SW1, names its board')
+    .option('--entry <entry>', 'add, align: the board the ref is on, by entry file, board name or folder; needed when the ref is on several boards')
+    .option('--footprint <name>', 'add: fit the model to the first part with this footprint id, such as RJ45_JK0654219NL, and write it on the <footprint> element')
+    .option('--as <name>', 'add: the file name in models/, the extension added when missing')
+    .option('--write', 'add: write the model option into the code, the path relative to the file it is written in')
+    .option('--force', 'add: replace a file of the same name with other content')
+    .option('--file <model>', 'align: fit this file instead of the one the part uses')
+    .option('--verbose', "show Vite's output and the stack of a compile error")
+    .action(async (action, args, o) => {
+    const str = (v) => (v === undefined || v === true || v === '' ? undefined : String(v));
+    for (const k of ['ref', 'footprint', 'as', 'file', 'entry'])
+        if (o[k] === true || o[k] === '')
+            usageError(`--${k} needs a value`);
+    const common = { config: o.config, verbose: !!o.verbose };
+    if (action === 'add') {
+        if (args.length > 1 || (!args.length && !o.ref))
+            usageError('model add takes one file, URL or lcsc:<C-number>, or --ref alone for a part with an MPN:LCSC number: pcbjs model add <file-or-url> [--ref J1]');
+        if (o.ref && o.footprint)
+            usageError('give --ref or --footprint, not both');
+        if (o.write && !o.ref && !o.footprint)
+            usageError('--write needs --ref or --footprint');
+        process.exitCode = await modelAdd({ source: args.length ? String(args[0]) : undefined, ref: str(o.ref), entry: str(o.entry), footprint: str(o.footprint), as: str(o.as), write: !!o.write, force: !!o.force, ...common });
+    }
+    else if (action === 'align') {
+        if (args.length < 1 || args.length > 2)
+            usageError('model align takes a ref, and an entry first when the config lists several: pcbjs model align [entry] <ref>');
+        const [entry, ref] = args.length === 2 ? args.map(String) : [str(o.entry), String(args[0])];
+        if (args.length === 2 && o.entry !== undefined)
+            usageError('give the entry once, as the first argument or with --entry');
+        process.exitCode = await modelAlign({ entry, ref, file: str(o.file), ...common });
+    }
+    else if (action === 'check')
+        process.exitCode = await modelCheck({ entries: args.map(String), ...common });
+    else if (action === 'fetch')
+        process.exitCode = await modelFetch({ entries: args.map(String), ...common });
+    else
+        usageError(`unknown model action: ${action}, use add, align, check or fetch`);
+});
+cli.command('import <kind> <source>', 'KiCad files as code: `import footprint <Lib:Name|file.kicad_mod>` writes a defineFootprint module, `import board <file.kicad_pcb>` a board skeleton with its schematic, copper, footprints and rules')
+    .option('-o, --out <file>', 'footprint: the module to write (default lib/<name>.tsx); board: the board file (default pcb.tsx), the others beside it')
+    .option('--force', 'replace files that exist')
+    .action(async (kind, source, o) => {
+    if (o.out === true || o.out === '')
+        usageError('--out needs a file');
+    process.exitCode = await importCommand({ kind: String(kind), source: String(source), out: o.out === undefined ? undefined : String(o.out), force: !!o.force });
+});
+cli.command('preview [...entries]', 'serve the built site')
+    .option('-c, --config <file>', 'config file (default: pcb.config.ts, .mts, .js or .mjs)')
+    .option('-p, --port <port>', 'port (default 4173)')
+    .option('--host [host]', 'listen on all addresses')
+    .option('--out-dir <dir>', 'site to serve (default .pcbjs/dist)')
+    .action(async (entries, o) => { await preview({ entries, config: o.config, outDir: o.outDir, port: portOf(o.port), host: o.host }); });
+cli.command('ide <action>', 'the bundled VS Code extension: `ide install` installs it with the code CLI, `ide status` compares it with the installed one')
+    .action(async (action) => {
+    if (action === 'install')
+        process.exitCode = await ideInstall();
+    else if (action === 'status')
+        process.exitCode = await ideStatus();
+    else
+        usageError(`unknown ide action: ${action}, use install or status`);
+});
+cli.command('skills <action>', 'the agent skills of @pcbjs/skills: `skills install` copies them into .claude/skills or --to <dir>, `skills list` names each, `skills path` prints where they ship')
+    .option('--to <dir>', 'install: the skills folder to copy into (default .claude/skills)')
+    .action(async (action, o) => {
+    if (o.to !== undefined && action !== 'install')
+        usageError('--to goes with skills install');
+    process.exitCode = await skills(action, { to: o.to === undefined ? undefined : String(o.to) });
+});
+cli.command('docs [topic]', 'print the docs: the topic list, one topic such as routing, or with --grep every line that matches')
+    .option('--grep <word>', 'print the lines of every topic, or of the one given, that mention <word>; anything but letters, digits, spaces and dashes is a regular expression, such as neck|escape')
+    .action((topic, o) => {
+    if (o.grep === true || o.grep === '')
+        usageError('--grep needs a word, for example --grep keepout');
+    process.exitCode = docs({ topic: topic === undefined ? undefined : String(topic), grep: o.grep === undefined ? undefined : String(o.grep) });
+});
+cli.command('doctor', 'print the installed @pcbjs versions, Node, Chrome, the step converter, the file format versions and the config; exit 1 when the packages disagree on major.minor')
+    .option('-c, --config <file>', 'config file (default: pcb.config.ts, .mts, .js or .mjs)')
+    .action(async (o) => { process.exitCode = await doctor({ config: o.config }); });
+cli.command('create <dir>', 'start a new project in <dir> from a template: a board in pcb.tsx, pcb.config.ts listing it, package.json and tsconfig.json')
+    .option('-t, --template <name>', 'template (default board)')
+    .action((dir, o) => { create({ dir, template: o.template }); });
+cli.help(sections => [{ body: versionLine() }, ...sections.slice(1)]);
+cli.version(cliVersion());
+cli.outputVersion = () => console.log(versionLine());
+/** 0 asks the system for a free port */
+function portOf(v) {
+    if (v === undefined || v === null || v === '' || v === true)
+        return undefined;
+    const n = Number(v);
+    if (!Number.isInteger(n) || n < 0 || n > 65535)
+        usageError(`bad port: ${v}`);
+    return n;
+}
+/** a bare --json would read the next entry as its file */
+function jsonFile(v) {
+    if (v === undefined || v === false)
+        return undefined;
+    if (v === true || v === '')
+        usageError('--json needs a file, for example --json .pcbjs/report.json');
+    return String(v);
+}
+/** The first argument is the entry when it names a module; a bare `--lengths` makes each query a filter, or adds the whole table. */
+export function inspectRequests(args, lengths, layers = []) {
+    const entry = args.length && looksLikeEntry(args[0]) ? args[0] : undefined;
+    const queries = entry === undefined ? args : args.slice(1);
+    // --layer filters by each query; --lengths beside it adds its route tables
+    if (layers.length) {
+        const lengthFlags = (Array.isArray(lengths) ? lengths : [lengths]).filter(v => v !== undefined && v !== false);
+        const tables = lengthFlags.map(v => (typeof v === 'string' && v !== '' ? { query: v, lengths: true } : { lengths: true }));
+        return { entry, requests: [...layers.flatMap(layer => (queries.length ? queries.map(q => ({ query: q, layer })) : [{ layer }])), ...tables] };
+    }
+    const flags = (Array.isArray(lengths) ? lengths : [lengths]).filter(v => v !== undefined && v !== false);
+    const filters = flags.filter(v => typeof v === 'string' || typeof v === 'number').map(String);
+    const bare = flags.some(v => v === true || v === '');
+    if (bare && !filters.length)
+        return { entry, requests: queries.length ? queries.map(q => ({ query: q, lengths: true })) : [{ lengths: true }] };
+    const requests = [...queries.map(q => ({ query: q })), ...filters.map(q => ({ query: q, lengths: true })), ...(bare ? [{ lengths: true }] : [])];
+    return { entry, requests: requests.length ? requests : [{}] };
+}
+/** A module ends in .ts, .tsx, .js, .mts and the like; anything else is a ref, net or pad. */
+const looksLikeEntry = (a) => /\.[cm]?[jt]sx?$/i.test(a);
+function usageError(message) {
+    cli.unsetMatchedCommand();
+    cli.outputHelp();
+    console.error(`pcbjs: ${message}`);
+    process.exit(1);
+}
+export async function run(argv = process.argv) {
+    try {
+        cli.parse(argv, { run: false });
+        if (!cli.matchedCommand && !cli.options.help && !cli.options.version)
+            usageError(cli.args[0] ? `unknown command: ${cli.args[0]}` : 'no command given');
+        await cli.runMatchedCommand();
+    }
+    catch (e) {
+        // the stack only when asked for
+        const msg = String(e?.message ?? e).replace(/\x1b\[[0-9;]*m/g, '');
+        console.error(`pcbjs: ${msg.split('\n')[0]}`);
+        if (cli.options.verbose || process.env.DEBUG)
+            console.error(String(e?.stack ?? '').split('\n').filter(l => /^\s+at /.test(l)).join('\n'));
+        process.exit(1);
+    }
+}