@invisra/printspec 0.1.0 → 0.1.2

package/README.md

@@ -2,7 +2,7 @@
 
 TypeScript package for printspec JSON Schemas, offline validation, BOM helpers, browser form metadata helpers, CLI commands, deterministic bundle export, and starter OpenSCAD/CadQuery source generation.
 
-**Status: v0.1.0 experimental.** The package is prepared for npm publication. If it is not yet published, install from the repository workspace instead of assuming registry availability.
+**Status: npm package v0.1.1 / schema v0.1.0 experimental.** Version 0.1.1 is a packaging-only patch that includes built `dist/` artifacts; schemas and `printspecVersion` remain 0.1.0.
 
 ## Installation
 
@@ -63,7 +63,7 @@ writeBundleToDirectory(bundle, "bundle", { overwrite: true });
 
 ## Package exports and bundled schemas
 
-The package exports the main ESM API from `@invisra/printspec` and package schema files through `@invisra/printspec/schemas/*`. Schema files are bundled in the npm package under `schemas/`.
+The package exports the main ESM API from `@invisra/printspec` and package schema files through `@invisra/printspec/schemas/*`. Published npm packages must include built TypeScript artifacts under `dist/` (`dist/index.js`, `dist/index.d.ts`, and `dist/cli.js`) and schema files under `schemas/`.
 
 Validation resolves bundled schemas offline. It does not fetch hosted schema URLs during normal validation.
 

package/dist/bom.d.ts

@@ -0,0 +1,5 @@
+import type { BomItem, PrintSpec } from './types.js';
+export declare function extractBom(spec: PrintSpec): BomItem[];
+export declare function bomToMarkdown(bom: BomItem[]): string;
+export declare function bomToCsv(bom: BomItem[]): string;
+export declare function bomToSupplierOrderList(bom: BomItem[]): string;

package/dist/bom.js

@@ -0,0 +1,30 @@
+function supplier(s) { const x = (s ?? '').toLowerCase().replace(/\s+/g, ''); return ['mcmaster', 'mcmaster-carr'].includes(x) ? 'mcmaster' : (s ?? '').toLowerCase(); }
+function norm(item, mult = 1) { return { ...item, quantity: Math.max(1, Math.trunc((item.quantity || 1) * mult)), supplierReferences: (item.supplierReferences ?? []).map(r => ({ ...r, supplier: supplier(r.supplier) })) }; }
+function key(i) { const r = i.supplierReferences?.[0]; return [i.kind, i.standard ?? '', i.size ?? '', r?.supplier ?? '', r?.partNumber ?? '', i.role ?? ''].join('|'); }
+function collect(spec, mult = 1, out = []) { for (const h of spec.hardware ?? [])
+    out.push(norm(h, mult)); if (spec.part)
+    for (const h of spec.part.hardware ?? [])
+        out.push(norm(h, mult)); if (spec.project) {
+    for (const h of spec.project.hardware ?? [])
+        out.push(norm(h, mult));
+    for (const p of spec.project.parts ?? [])
+        if (p.spec)
+            collect(p.spec, mult * (p.quantity ?? 1), out);
+} return out; }
+export function extractBom(spec) { const map = new Map(); for (const i of collect(spec)) {
+    const k = key(i);
+    const cur = map.get(k);
+    if (cur)
+        cur.quantity += i.quantity;
+    else
+        map.set(k, { ...i });
+} return [...map.values()]; }
+export function bomToMarkdown(bom) { return ['| ID | Kind | Size | Qty | Supplier | Part Number |', '| --- | --- | --- | ---: | --- | --- |', ...bom.map(i => `| ${i.id} | ${i.kind} | ${i.size ?? ''} | ${i.quantity} | ${i.supplierReferences?.[0]?.supplier ?? ''} | ${i.supplierReferences?.[0]?.partNumber ?? ''} |`)].join('\n'); }
+function csv(v) { const s = String(v ?? ''); return /[",\n]/.test(s) ? `"${s.replaceAll('"', '""')}"` : s; }
+export function bomToCsv(bom) { return ['id,kind,standard,size,quantity,role,supplier,partNumber,url,description', ...bom.map(i => { const r = i.supplierReferences?.[0] ?? {}; return [i.id, i.kind, i.standard ?? '', i.size ?? '', i.quantity, i.role ?? '', r.supplier ?? '', r.partNumber ?? '', r.url ?? '', r.description ?? ''].map(csv).join(','); })].join('\n'); }
+export function bomToSupplierOrderList(bom) { const by = new Map(); for (const i of bom)
+    for (const r of i.supplierReferences ?? []) {
+        const s = supplier(r.supplier);
+        const line = `${r.partNumber} x ${i.quantity}${r.url ? ` (${r.url})` : ''}`;
+        by.set(s, [...(by.get(s) ?? []), line]);
+    } return [...by.entries()].map(([s, lines]) => `${s}\n${lines.map(l => `- ${l}`).join('\n')}`).join('\n\n'); }

package/dist/bundle.d.ts

@@ -0,0 +1,27 @@
+export type BundleFile = {
+    path: string;
+    content: string;
+    mediaType: string;
+};
+export type BundleWarning = {
+    path?: string;
+    message: string;
+};
+export type BundleResult = {
+    supported: boolean;
+    files: BundleFile[];
+    warnings: BundleWarning[];
+    message?: string;
+};
+export type BundleOptions = {
+    includeOpenScad?: boolean;
+    includeCadQuery?: boolean;
+    includeBom?: boolean;
+    includePartCad?: boolean;
+    prettyJson?: boolean;
+};
+export type WriteBundleOptions = {
+    overwrite?: boolean;
+};
+export declare function createBundle(input: unknown, options?: BundleOptions): BundleResult;
+export declare function writeBundleToDirectory(bundle: BundleResult, outputDir: string, options?: WriteBundleOptions): void;

package/dist/bundle.js

@@ -0,0 +1,99 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { validatePrintSpec } from './validate.js';
+import { normalizePrintSpec } from './normalize.js';
+import { generateOpenScad } from './generators/openscad.js';
+import { generateCadQuery } from './generators/cadquery.js';
+import { extractBom, bomToMarkdown, bomToCsv, bomToSupplierOrderList } from './bom.js';
+const VERSION = '0.1.0';
+const jsonMedia = 'application/json';
+function j(spec, pretty) { return JSON.stringify(spec, null, pretty ? 2 : 0) + '\n'; }
+function add(files, path, content, mediaType, role) { files.push({ path, content, mediaType, role }); }
+function warn(warnings, message, path) { warnings.push(path ? { path, message } : { message }); }
+function safePartId(id) { return id.replace(/[^A-Za-z0-9._-]/g, '-'); }
+function bomFiles(files, base, bom) { if (!bom.length)
+    return; add(files, `${base}bom.md`, bomToMarkdown(bom) + '\n', 'text/markdown', 'bom-markdown'); add(files, `${base}bom.csv`, bomToCsv(bom) + '\n', 'text/csv', 'bom-csv'); add(files, `${base}supplier-order-list.txt`, bomToSupplierOrderList(bom) + '\n', 'text/plain', 'supplier-order-list'); }
+function cadForPart(spec, base, files, warnings, opts) { if (opts.includeOpenScad) {
+    const g = generateOpenScad(spec);
+    if (g.supported) {
+        add(files, `${base}cad/model.scad`, g.code, 'text/plain', 'openscad-source');
+        for (const m of g.warnings ?? [])
+            warn(warnings, m, `${base}cad/model.scad`);
+    }
+    else
+        warn(warnings, g.message ?? 'OpenSCAD generator unsupported', `${base}cad/model.scad`);
+} if (opts.includeCadQuery) {
+    const g = generateCadQuery(spec);
+    if (g.supported) {
+        add(files, `${base}cad/model.py`, g.code, 'text/x-python', 'cadquery-source');
+        for (const m of g.warnings ?? [])
+            warn(warnings, m, `${base}cad/model.py`);
+    }
+    else
+        warn(warnings, g.message ?? 'CadQuery generator unsupported', `${base}cad/model.py`);
+} }
+function readme(kind, spec, files, warnings, bomCount) { const lines = []; lines.push(`# ${kind === 'project' ? (spec.project?.label ?? 'printspec project') : (spec.part?.label ?? 'printspec part')}`, ''); if (kind === 'part')
+    lines.push(`Part type: ${spec.part?.type ?? 'unknown'}`);
+else {
+    if (spec.project?.description)
+        lines.push(spec.project.description, '');
+    lines.push('## Parts', ...(spec.project?.parts ?? []).map((p) => `- ${p.id}: ${p.label ?? p.id} (quantity ${p.quantity ?? 1})`), '');
+} lines.push(`printspec version: ${spec.printspecVersion ?? VERSION}`, '', '## Generated files', ...files.map(f => `- ${f.path} (${f.role})`), ''); lines.push('## BOM', bomCount ? `${bomCount} BOM item(s) included.` : 'No hardware/BOM items were found.', ''); lines.push('## Warnings', ...(warnings.length ? warnings.map(w => `- ${w.path ? `${w.path}: ` : ''}${w.message}`) : ['- None']), ''); lines.push('Generated CAD source should be reviewed before manufacturing.'); return lines.join('\n') + '\n'; }
+function partcad(spec, files) { const cq = files.filter(f => f.role === 'cadquery-source').sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0); const name = spec.project?.partcad?.packageName ?? 'printspec-project'; const lines = ['package:', `  name: ${name}`, `  version: ${spec.project?.partcad?.packageVersion ?? VERSION}`, '  description: Experimental compatibility stub generated from printspec.', '', 'parts:']; for (const f of cq) {
+    const m = f.path.match(/^parts\/([^/]+)\//);
+    lines.push(`  - name: ${m?.[1] ?? 'model'}`, '    type: cadquery', `    path: ${f.path}`);
+} if (!cq.length)
+    lines.push('  []'); return lines.join('\n') + '\n'; }
+function manifest(kind, files, warnings, spec) { const entries = files.map(f => ({ path: f.path, mediaType: f.mediaType, role: f.role })).sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0); entries.push({ path: 'bundle-manifest.json', mediaType: jsonMedia, role: 'bundle-manifest' }); entries.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0); return j({ bundleVersion: VERSION, createdBy: 'printspec', printspecVersion: spec.printspecVersion ?? VERSION, kind, files: entries, warnings }, true); }
+export function createBundle(input, options = {}) {
+    const r = validatePrintSpec(input);
+    if (!r.valid)
+        return { supported: false, files: [], warnings: [], message: `Validation failed: ${r.errors.slice(0, 3).join('; ')}` };
+    const spec = normalizePrintSpec(input);
+    const opts = { includeOpenScad: options.includeOpenScad !== false, includeCadQuery: options.includeCadQuery !== false, includeBom: options.includeBom !== false, includePartCad: options.includePartCad === true, prettyJson: options.prettyJson !== false };
+    const files = [];
+    const warnings = [];
+    const kind = spec.project ? 'project' : 'part';
+    add(files, 'printspec.json', j(spec, opts.prettyJson), jsonMedia, 'source-spec');
+    if (kind === 'part') {
+        cadForPart(spec, '', files, warnings, opts);
+        if (opts.includeBom)
+            bomFiles(files, 'bom/', extractBom(spec));
+    }
+    else {
+        for (const p of spec.project.parts ?? []) {
+            const id = safePartId(p.id);
+            if (p.spec) {
+                const ps = normalizePrintSpec(p.spec);
+                add(files, `parts/${id}/printspec.json`, j(ps, opts.prettyJson), jsonMedia, 'part-source-spec');
+                cadForPart(ps, `parts/${id}/`, files, warnings, opts);
+            }
+            else if (p.specPath)
+                warn(warnings, `External specPath references are not bundled yet: ${p.specPath}`, `parts/${id}/printspec.json`);
+        }
+        if (opts.includeBom)
+            bomFiles(files, 'bom/', extractBom(spec));
+        if (opts.includePartCad)
+            add(files, 'partcad.yaml', partcad(spec, files), 'text/yaml', 'partcad-stub');
+    }
+    const bomCount = extractBom(spec).length;
+    add(files, 'README.md', readme(kind, spec, files, warnings, bomCount), 'text/markdown', 'readme');
+    add(files, 'bundle-manifest.json', manifest(kind, files, warnings, spec), jsonMedia, 'bundle-manifest');
+    files.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    return { supported: true, files: files.map(({ role, ...f }) => f), warnings };
+}
+function assertSafe(p) { if (!p || path.isAbsolute(p) || p.split(/[\\/]+/).includes('..'))
+    throw new Error(`Unsafe bundle path: ${p}`); }
+export function writeBundleToDirectory(bundle, outputDir, options = {}) { if (!bundle.supported)
+    throw new Error(bundle.message ?? 'Unsupported bundle'); if (fs.existsSync(outputDir) && !options.overwrite)
+    throw new Error(`Output directory already exists: ${outputDir}`); fs.mkdirSync(outputDir, { recursive: true }); for (const f of bundle.files) {
+    assertSafe(f.path);
+    const dest = path.resolve(outputDir, f.path);
+    const root = path.resolve(outputDir);
+    if (dest !== root && !dest.startsWith(root + path.sep))
+        throw new Error(`Unsafe bundle path: ${f.path}`);
+    if (fs.existsSync(dest) && !options.overwrite)
+        throw new Error(`Output file already exists: ${dest}`);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, f.content, 'utf8');
+} }

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { validatePrintSpec, generateOpenScad, generateCadQuery, extractBom, bomToMarkdown, bomToCsv, bomToSupplierOrderList, getPartFamilyFormMetadata, listPartFamilies, createBundle, writeBundleToDirectory } from './index.js';
+function fail(msg) { console.error(msg); return 1; }
+function packageVersion() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    for (const candidate of [path.join(here, '..', 'package.json'), path.join(here, '..', '..', 'package.json'), path.join(here, '..', '..', '..', 'package.json')]) {
+        if (fs.existsSync(candidate))
+            return JSON.parse(fs.readFileSync(candidate, 'utf8')).version;
+    }
+    return '0.1.0';
+}
+function usage() { return 'usage: printspec <validate|to-openscad|to-cadquery|bom|bundle|form-metadata|list-part-families|version> [args] [--output file]\ncommands: validate, to-openscad, to-cadquery, bom, bundle, form-metadata, list-part-families, version'; }
+function load(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        if (e?.code && e.code !== 'SyntaxError')
+            throw new Error(`${file}: read error: ${e.message}`);
+        if (e instanceof SyntaxError)
+            throw new Error(`${file}: parse error: ${e.message}`);
+        throw new Error(`${file}: parse error: ${e.message}`);
+    }
+}
+function opt(args, name) { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; }
+function write(text, out) { if (out)
+    fs.writeFileSync(out, text);
+else
+    console.log(text); }
+function main(argv = process.argv.slice(2)) {
+    const [cmd, file, ...rest] = argv;
+    if (cmd === '--version' || cmd === 'version') {
+        console.log(`printspec ${packageVersion()}`);
+        return 0;
+    }
+    if (cmd === '--help' || cmd === '-h') {
+        console.log(usage());
+        return 0;
+    }
+    if (!cmd)
+        return fail(usage());
+    if (cmd === 'list-part-families') {
+        write(JSON.stringify(listPartFamilies(), null, rest.includes('--pretty') ? 2 : 0));
+        return 0;
+    }
+    if (cmd === 'form-metadata') {
+        if (!file)
+            return fail(usage());
+        try {
+            write(JSON.stringify(getPartFamilyFormMetadata(file), null, rest.includes('--pretty') ? 2 : 0));
+            return 0;
+        }
+        catch (e) {
+            return fail(`error: ${e.message}`);
+        }
+    }
+    if (!['validate', 'to-openscad', 'to-cadquery', 'bom', 'bundle'].includes(cmd))
+        return fail(`error: unknown command ${cmd}`);
+    if (!file)
+        return fail(usage());
+    let spec;
+    try {
+        spec = load(file);
+    }
+    catch (e) {
+        return fail(`error: unable to read JSON: ${e.message}`);
+    }
+    if (cmd === 'validate') {
+        const r = validatePrintSpec(spec);
+        if (r.valid) {
+            console.log('valid');
+            return 0;
+        }
+        console.error('invalid');
+        for (const e of r.errors)
+            console.error(`- ${e}`);
+        return 1;
+    }
+    if (cmd === 'to-openscad' || cmd === 'to-cadquery') {
+        const r = validatePrintSpec(spec);
+        if (!r.valid)
+            return fail(`error: ${r.errors.slice(0, 3).join('; ')}`);
+        const g = cmd === 'to-openscad' ? generateOpenScad(spec) : generateCadQuery(spec);
+        if (!g.supported)
+            return fail(`error: ${g.message ?? 'unsupported'}`);
+        for (const w of g.warnings ?? [])
+            console.error(`warning: ${w}`);
+        write(g.code, opt(rest, '--output'));
+        return 0;
+    }
+    if (cmd === 'bom') {
+        const fmt = opt(rest, '--format') ?? 'markdown';
+        const bom = extractBom(spec);
+        const fn = { markdown: bomToMarkdown, csv: bomToCsv, 'supplier-list': bomToSupplierOrderList }[fmt];
+        if (!fn)
+            return fail('error: unsupported BOM format');
+        write(fn(bom), opt(rest, '--output'));
+        return 0;
+    }
+    if (cmd === 'bundle') {
+        const out = opt(rest, '--output');
+        if (!out)
+            return fail('error: bundle requires --output <directory>');
+        const b = createBundle(spec, { includeOpenScad: !rest.includes('--no-openscad'), includeCadQuery: !rest.includes('--no-cadquery'), includeBom: !rest.includes('--no-bom'), includePartCad: rest.includes('--partcad') });
+        if (!b.supported)
+            return fail(`error: ${b.message ?? 'unsupported bundle'}`);
+        try {
+            writeBundleToDirectory(b, out, { overwrite: rest.includes('--overwrite') });
+        }
+        catch (e) {
+            return fail(`error: ${e.message}`);
+        }
+        console.log(`wrote ${b.files.length} files to ${out}`);
+        console.log(`warnings: ${b.warnings.length}`);
+        return 0;
+    }
+    return fail(`error: unknown command ${cmd}`);
+}
+process.exitCode = main();

package/dist/forms.d.ts

@@ -0,0 +1,37 @@
+export type FormGroup = {
+    id: string;
+    title: string;
+    fields: string[];
+};
+export type FormField = {
+    name: string;
+    title: string;
+    description?: string;
+    required: boolean;
+    type: string;
+    control?: string;
+    unit?: string;
+    step?: number;
+    minimum?: number;
+    exclusiveMinimum?: number;
+    maximum?: number;
+    default?: unknown;
+    examples?: unknown[];
+    priority?: 'primary' | 'advanced';
+};
+export type FormMetadata = {
+    partType: string;
+    title: string;
+    description?: string;
+    fields: FormField[];
+    groups: FormGroup[];
+};
+export type PartFamilySummary = {
+    type: string;
+    title: string;
+    description?: string;
+    schemaFilename: string;
+    generatorSupported?: boolean;
+};
+export declare function listPartFamilies(): PartFamilySummary[];
+export declare function getPartFamilyFormMetadata(partType: string): FormMetadata;

package/dist/forms.js

@@ -0,0 +1,68 @@
+import { schemas } from './schemas.js';
+const generatorSupported = new Set(['rounded_rectangular_plate', 'spacer_block', 'round_spacer', 'electronics_standoff']);
+function partFamilyEntries() {
+    return Object.entries(schemas)
+        .map(([filename, schema]) => ({ filename, schema, type: schema?.properties?.type?.const }))
+        .filter((entry) => typeof entry.type === 'string' && !!entry.schema?.properties?.parameters)
+        .sort((a, b) => a.type.localeCompare(b.type));
+}
+function schemaType(field) {
+    if (typeof field?.type === 'string')
+        return field.type;
+    if (field?.$ref)
+        return 'object';
+    if (Array.isArray(field?.type))
+        return field.type.join('|');
+    return 'unknown';
+}
+export function listPartFamilies() {
+    return partFamilyEntries().map(({ type, filename, schema }) => ({
+        type,
+        title: schema.title ?? type,
+        description: schema.description,
+        schemaFilename: filename,
+        generatorSupported: generatorSupported.has(type),
+    }));
+}
+export function getPartFamilyFormMetadata(partType) {
+    const entry = partFamilyEntries().find((candidate) => candidate.type === partType);
+    if (!entry)
+        throw new Error(`Unsupported printspec part family: ${partType}`);
+    const parameters = entry.schema?.properties?.parameters;
+    const properties = parameters?.properties ?? {};
+    const required = new Set(parameters?.required ?? []);
+    const metadata = parameters?.['x-printspec-ui'] ?? {};
+    const known = new Set(Object.keys(properties));
+    const ordered = Array.isArray(metadata.order) ? metadata.order.filter((name) => known.has(name)) : Object.keys(properties).sort();
+    for (const name of Object.keys(properties).sort())
+        if (!ordered.includes(name))
+            ordered.push(name);
+    const groups = Array.isArray(metadata.groups) && metadata.groups.length
+        ? metadata.groups.map((group) => ({ id: String(group.id), title: String(group.title ?? group.id), fields: (group.fields ?? []).filter((name) => known.has(name)) }))
+        : [{ id: 'parameters', title: parameters?.title ?? 'Parameters', fields: ordered }];
+    return {
+        partType,
+        title: entry.schema.title ?? partType,
+        description: entry.schema.description,
+        fields: ordered.map((name) => {
+            const field = properties[name] ?? {};
+            return {
+                name,
+                title: field.title ?? name,
+                description: field.description,
+                required: required.has(name),
+                type: schemaType(field),
+                control: field['x-printspec-control'],
+                unit: field['x-printspec-unit'],
+                step: field['x-printspec-step'],
+                minimum: field.minimum,
+                exclusiveMinimum: field.exclusiveMinimum,
+                maximum: field.maximum,
+                default: field.default,
+                examples: field.examples,
+                priority: field['x-printspec-priority'],
+            };
+        }),
+        groups,
+    };
+}

package/dist/generators/cadquery.d.ts

@@ -0,0 +1,2 @@
+import type { GeneratorResult, PrintSpec } from '../types.js';
+export declare function generateCadQuery(spec: PrintSpec): GeneratorResult;

package/dist/generators/cadquery.js

@@ -0,0 +1,29 @@
+import { validatePrintSpec } from '../validate.js';
+function invalid(spec) { const r = validatePrintSpec(spec); return r.valid ? null : { supported: false, code: '', message: `Validation failed: ${r.errors.slice(0, 3).join('; ')}`, warnings: [] }; }
+const header = '# Generated by printspec 0.1.0\n# Review generated CAD before manufacturing.\nimport cadquery as cq\n\n';
+function warnings(a) { const w = []; if (a.chamfer != null)
+    w.push('chamfer requested but not implemented'); if (a.fillet != null)
+    w.push('fillet requested but not implemented'); return w; }
+function holeLines(hs = []) { return hs.map(h => `part = part.faces(">Z").workplane().pushPoints([(${h.x}, ${h.y})]).hole(${h.diameter})`).join('\n'); }
+export function generateCadQuery(spec) {
+    const bad = invalid(spec);
+    if (bad)
+        return bad;
+    const p = spec.part;
+    if (!p)
+        return { supported: false, code: '', message: 'Only part specs are supported.', warnings: [] };
+    const a = p.parameters;
+    if (p.type === 'rounded_rectangular_plate')
+        return { supported: true, warnings: [], code: `${header}length = ${a.length}\nwidth = ${a.width}\nheight = ${a.thickness}\ncorner_radius = ${a.cornerRadius}\n\npart = cq.Workplane("XY").rounded_rect(length, width, corner_radius).extrude(height)\n${holeLines(a.holes)}\n` };
+    if (p.type === 'spacer_block')
+        return { supported: true, warnings: [], code: `${header}length = ${a.length}\nwidth = ${a.width}\nheight = ${a.height}\n\npart = cq.Workplane("XY").box(length, width, height, centered=(True, True, False))\n${holeLines(a.holes)}\n` };
+    if (p.type === 'round_spacer') {
+        const w = warnings(a);
+        return { supported: true, warnings: w, code: `${header}outer_diameter = ${a.outerDiameter}\nheight = ${a.height}${a.innerDiameter != null ? `\ninner_diameter = ${a.innerDiameter}` : ''}\n\npart = cq.Workplane("XY").circle(outer_diameter / 2).extrude(height)${a.innerDiameter != null ? '\npart = part.faces(">Z").workplane().hole(inner_diameter)' : ''}\n` };
+    }
+    if (p.type === 'electronics_standoff') {
+        const hasBase = a.baseDiameter != null && a.baseHeight != null;
+        return { supported: true, warnings: [], code: `${header}outer_diameter = ${a.outerDiameter}\nheight = ${a.height}\nhole_diameter = ${a.holeDiameter}${hasBase ? `\nbase_diameter = ${a.baseDiameter}\nbase_height = ${a.baseHeight}` : ''}\n\n${hasBase ? `base = cq.Workplane("XY").circle(base_diameter / 2).extrude(base_height)\nstandoff = cq.Workplane("XY").workplane(offset=base_height).circle(outer_diameter / 2).extrude(height)\npart = base.union(standoff)` : `part = cq.Workplane("XY").circle(outer_diameter / 2).extrude(height)`}\npart = part.faces(">Z").workplane().hole(hole_diameter)\n` };
+    }
+    return { supported: false, code: '', message: `Unsupported part family: ${p.type}`, warnings: [] };
+}

package/dist/generators/openscad.d.ts

@@ -0,0 +1,2 @@
+import type { GeneratorResult, PrintSpec } from '../types.js';
+export declare function generateOpenScad(spec: PrintSpec): GeneratorResult;

package/dist/generators/openscad.js

@@ -0,0 +1,30 @@
+import { validatePrintSpec } from '../validate.js';
+function invalid(spec) { const r = validatePrintSpec(spec); return r.valid ? null : { supported: false, code: '', message: `Validation failed: ${r.errors.slice(0, 3).join('; ')}`, warnings: [] }; }
+const header = '// Generated by printspec 0.1.0\n// Review generated CAD before manufacturing.\n';
+function warnings(a) { const w = []; if (a.chamfer != null)
+    w.push('chamfer requested but not implemented'); if (a.fillet != null)
+    w.push('fillet requested but not implemented'); return w; }
+function holes(hs = []) { return hs.map(h => `  translate([${h.x}, ${h.y}, -0.1]) cylinder(h = height + 0.2, d = ${h.diameter}, $fn = 48);`).join('\n'); }
+export function generateOpenScad(spec) {
+    const bad = invalid(spec);
+    if (bad)
+        return bad;
+    const p = spec.part;
+    if (!p)
+        return { supported: false, code: '', message: 'Only part specs are supported.', warnings: [] };
+    const a = p.parameters;
+    if (p.type === 'rounded_rectangular_plate')
+        return { supported: true, warnings: [], code: `${header}length = ${a.length};\nwidth = ${a.width};\nheight = ${a.thickness};\ncorner_radius = ${a.cornerRadius};\n\nmodule rounded_plate() {\n  hull() {\n    for (x = [-length/2 + corner_radius, length/2 - corner_radius])\n      for (y = [-width/2 + corner_radius, width/2 - corner_radius])\n        translate([x, y, 0]) cylinder(h = height, r = corner_radius, $fn = 32);\n  }\n}\n\ndifference() {\n  rounded_plate();\n${holes(a.holes)}\n}\n` };
+    if (p.type === 'spacer_block')
+        return { supported: true, warnings: [], code: `${header}length = ${a.length};\nwidth = ${a.width};\nheight = ${a.height};\n\ndifference() {\n  translate([-length/2, -width/2, 0]) cube([length, width, height]);\n${holes(a.holes)}\n}\n` };
+    if (p.type === 'round_spacer') {
+        const w = warnings(a);
+        const inner = a.innerDiameter != null ? `\n  translate([0, 0, -0.1]) cylinder(h = height + 0.2, d = inner_diameter, $fn = 64);` : '';
+        return { supported: true, warnings: w, code: `${header}outer_diameter = ${a.outerDiameter};\nheight = ${a.height};${a.innerDiameter != null ? `\ninner_diameter = ${a.innerDiameter};` : ''}\n\ndifference() {\n  cylinder(h = height, d = outer_diameter, $fn = 64);${inner}\n}\n` };
+    }
+    if (p.type === 'electronics_standoff') {
+        const hasBase = a.baseDiameter != null && a.baseHeight != null;
+        return { supported: true, warnings: [], code: `${header}outer_diameter = ${a.outerDiameter};\nheight = ${a.height};\nhole_diameter = ${a.holeDiameter};${hasBase ? `\nbase_diameter = ${a.baseDiameter};\nbase_height = ${a.baseHeight};` : ''}\n\ndifference() {\n  ${hasBase ? `union() {\n    cylinder(h = base_height, d = base_diameter, $fn = 64);\n    translate([0, 0, base_height]) cylinder(h = height, d = outer_diameter, $fn = 64);\n  }` : `cylinder(h = height, d = outer_diameter, $fn = 64);`}\n  translate([0, 0, -0.1]) cylinder(h = ${hasBase ? 'base_height + height' : 'height'} + 0.2, d = hole_diameter, $fn = 64);\n}\n` };
+    }
+    return { supported: false, code: '', message: `Unsupported part family: ${p.type}`, warnings: [] };
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from './types.js';
+export * from './validate.js';
+export * from './normalize.js';
+export * from './bom.js';
+export * from './safety.js';
+export * from './generators/openscad.js';
+export * from './generators/cadquery.js';
+export * from './forms.js';
+export * from './bundle.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+export * from './types.js';
+export * from './validate.js';
+export * from './normalize.js';
+export * from './bom.js';
+export * from './safety.js';
+export * from './generators/openscad.js';
+export * from './generators/cadquery.js';
+export * from './forms.js';
+export * from './bundle.js';

package/dist/normalize.d.ts

@@ -0,0 +1,2 @@
+import type { PrintSpec } from './types.js';
+export declare function normalizePrintSpec(spec: PrintSpec): PrintSpec;

package/dist/normalize.js

@@ -0,0 +1,15 @@
+function normSupplier(s) { const x = s.toLowerCase().replace(/\s+/g, ''); return ['mcmaster', 'mcmaster-carr'].includes(x) ? 'mcmaster' : s.toLowerCase(); }
+function walk(v) { if (Array.isArray(v))
+    return v.map(walk); if (v && typeof v === 'object') {
+    const o = {};
+    for (const [k, val] of Object.entries(v))
+        o[k] = walk(val);
+    if ('diameter' in o && 'x' in o && 'y' in o) {
+        o.axis ??= 'z';
+        o.depth ??= 'through';
+    }
+    if (o.supplier)
+        o.supplier = normSupplier(o.supplier);
+    return o;
+} return v; }
+export function normalizePrintSpec(spec) { const out = walk(JSON.parse(JSON.stringify(spec))); out.units ??= 'mm'; return out; }

package/dist/safety.d.ts

@@ -0,0 +1,6 @@
+export declare const isPotentiallyUnsafeLabel: (text: string) => boolean;
+export declare const hasDisallowedSupplierRole: (text: string) => boolean;
+export declare function validateSafeMetadata(spec: any): {
+    valid: boolean;
+    errors: string[];
+};

package/dist/safety.js

@@ -0,0 +1,4 @@
+const bad = ['weapon', 'firearm', 'ammunition', 'explosive', 'suppressor', 'silencer', 'lockpick', 'bypass', 'implant', 'pressure vessel', 'flight-critical', 'high-voltage'];
+export const isPotentiallyUnsafeLabel = (text) => bad.some(w => text.toLowerCase().includes(w));
+export const hasDisallowedSupplierRole = isPotentiallyUnsafeLabel;
+export function validateSafeMetadata(spec) { const text = JSON.stringify(spec.metadata ?? {}) + ' ' + (spec.part?.label ?? spec.project?.label ?? ''); return { valid: !isPotentiallyUnsafeLabel(text), errors: isPotentiallyUnsafeLabel(text) ? ['Metadata or label may describe a disallowed/safety-critical use.'] : [] }; }

package/dist/schemas.d.ts

@@ -0,0 +1,6 @@
+import { Ajv2020 } from 'ajv/dist/2020.js';
+export declare const schemaDir: string;
+export declare const schemaFiles: any;
+export declare function loadSchemas(): Record<string, any>;
+export declare const schemas: Record<string, any>;
+export declare function createAjv(): Ajv2020;

package/dist/schemas.js

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+const schemaBaseUri = 'https://schemas.invisra.ai/printspec/0.1.0/';
+function isDirectory(candidate) {
+    return fs.existsSync(candidate) && fs.statSync(candidate).isDirectory();
+}
+function findSchemaDir() {
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    const packageLocalCandidate = path.resolve(moduleDir, '..', 'schemas');
+    if (isDirectory(packageLocalCandidate))
+        return packageLocalCandidate;
+    // Source checkout fallback: walk upward to the repository-level schemas
+    // directory so development builds can still validate fully offline.
+    for (let dir = moduleDir;; dir = path.dirname(dir)) {
+        const candidate = path.join(dir, 'schemas');
+        if (isDirectory(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+    }
+    throw new Error('Unable to locate bundled printspec schemas. Run npm run sync:schemas before building, or reinstall the package.');
+}
+export const schemaDir = findSchemaDir();
+export const schemaFiles = fs.readdirSync(schemaDir).filter((f) => f.endsWith('.schema.json')).sort();
+export function loadSchemas() {
+    const files = fs.readdirSync(schemaDir).filter((f) => f.endsWith('.schema.json')).sort();
+    return Object.fromEntries(files.map((file) => [file, JSON.parse(fs.readFileSync(path.join(schemaDir, file), 'utf8'))]));
+}
+export const schemas = loadSchemas();
+export function createAjv() {
+    const ajv = new Ajv2020({ allErrors: true, strict: false, loadSchema: undefined });
+    addFormats(ajv);
+    const registered = new Set();
+    for (const [filename, schema] of Object.entries(schemas)) {
+        const primaryId = schema.$id ?? `${schemaBaseUri}${filename}`;
+        ajv.addSchema(schema, primaryId);
+        registered.add(primaryId);
+    }
+    for (const [filename, schema] of Object.entries(schemas)) {
+        const aliasSchema = { ...schema };
+        delete aliasSchema.$id;
+        for (const alias of [filename, `${schemaBaseUri}${filename}`]) {
+            if (!registered.has(alias)) {
+                ajv.addSchema(aliasSchema, alias);
+                registered.add(alias);
+            }
+        }
+    }
+    return ajv;
+}

package/dist/semantic.d.ts

@@ -0,0 +1 @@
+export declare function validateSemantic(spec: any): string[];

package/dist/semantic.js

@@ -0,0 +1,80 @@
+function pathOf(p) { return p || '$'; }
+function dup(values, label) { const seen = new Set(); const e = []; for (const v of values) {
+    if (seen.has(v))
+        e.push(`duplicate ${label} id: ${v}`);
+    seen.add(v);
+} return e; }
+function params(part) { return part?.parameters ?? {}; }
+function checkPart(part, prefix = 'part') { const e = []; const p = params(part); if (part?.type === 'rounded_rectangular_plate' && p.cornerRadius > Math.min(p.length, p.width) / 2)
+    e.push(`${prefix}.parameters.cornerRadius exceeds half of min(length,width)`); if (part?.type === 'simple_box' && p.wallThickness >= Math.min(p.outerLength, p.outerWidth) / 2)
+    e.push(`${prefix}.parameters.wallThickness must be less than half of outer dimensions`); if (part?.type === 'round_spacer' && p.innerDiameter != null && p.innerDiameter >= p.outerDiameter)
+    e.push(`${prefix}.parameters.innerDiameter must be less than outerDiameter`); if (part?.type === 'electronics_standoff') {
+    if (p.holeDiameter >= p.outerDiameter)
+        e.push(`${prefix}.parameters.holeDiameter must be less than outerDiameter`);
+    if ((p.baseDiameter == null) !== (p.baseHeight == null))
+        e.push(`${prefix}.parameters.baseDiameter and baseHeight must be provided together`);
+    if (p.baseDiameter != null && p.baseDiameter < p.outerDiameter)
+        e.push(`${prefix}.parameters.baseDiameter must be greater than or equal to outerDiameter`);
+} const maxW = p.width ?? p.outerWidth ?? p.outerDiameter; for (const h of p.holes ?? []) {
+    if (h.diameter > maxW)
+        e.push(`${prefix}.parameters.holes diameter exceeds target width`);
+} return e; }
+export function validateSemantic(spec) {
+    const e = [];
+    const checkHw = (items, label) => { e.push(...dup((items ?? []).map(h => h.id).filter(Boolean), `${label} hardware`)); for (const h of items ?? []) {
+        if (!Number.isInteger(h.quantity) || h.quantity < 1)
+            e.push(`${label}.hardware quantity must be integer >= 1`);
+        for (const r of h.supplierReferences ?? []) {
+            if (!r.partNumber)
+                e.push(`${label}.supplierReference partNumber is required`);
+            if (r.url) {
+                try {
+                    new URL(r.url);
+                }
+                catch {
+                    e.push(`${label}.supplierReference url is invalid`);
+                }
+            }
+        }
+    } };
+    checkHw(spec?.hardware, 'top-level');
+    if (spec?.part) {
+        if (spec.part.type === 'composable_part') {
+            const ids = (spec.part.components ?? []).map((c) => c.id);
+            e.push(...dup(ids, 'component'));
+            const set = new Set(ids);
+            e.push(...dup((spec.part.features ?? []).map((f) => f.id).filter(Boolean), 'feature'));
+            for (const f of spec.part.features ?? [])
+                if (f.target && !set.has(f.target))
+                    e.push(`feature ${f.id ?? ''} target does not exist: ${f.target}`);
+            for (const c of spec.part.components ?? []) {
+                const t = c.relation?.target;
+                if (['mirrored_from', 'attached_to_face', 'on_top_of'].includes(c.relation?.type) && t && !set.has(t))
+                    e.push(`component ${c.id} relation target does not exist: ${t}`);
+            }
+        }
+        else
+            e.push(...checkPart(spec.part));
+        checkHw(spec.part.hardware, 'part');
+    }
+    if (spec?.project) {
+        const partIds = (spec.project.parts ?? []).map((p) => p.id);
+        const partSet = new Set(partIds);
+        const hwIds = (spec.project.hardware ?? []).map((h) => h.id);
+        const hwSet = new Set(hwIds);
+        e.push(...dup(partIds, 'project part'), ...dup(hwIds, 'project hardware'));
+        for (const r of spec.project.relationships ?? []) {
+            if (r.partA && !partSet.has(r.partA))
+                e.push(`relationship partA missing: ${r.partA}`);
+            if (r.partB && !partSet.has(r.partB))
+                e.push(`relationship partB missing: ${r.partB}`);
+            if (r.hardware && !hwSet.has(r.hardware))
+                e.push(`relationship hardware missing: ${r.hardware}`);
+        }
+        for (const p of spec.project.parts ?? [])
+            if (p.spec)
+                e.push(...validateSemantic(p.spec).map(x => `project.parts.${p.id}: ${x}`));
+        checkHw(spec.project.hardware, 'project');
+    }
+    return e;
+}

package/dist/types.d.ts

@@ -0,0 +1,71 @@
+export type SupplierReference = {
+    supplier: string;
+    partNumber: string;
+    url?: string;
+    description?: string;
+};
+export type HardwareItem = {
+    id: string;
+    kind: string;
+    standard?: string;
+    size?: string;
+    quantity: number;
+    role?: string;
+    supplierReferences?: SupplierReference[];
+};
+export type BomItem = HardwareItem;
+export type ValidationResult = {
+    valid: boolean;
+    errors: string[];
+};
+export type PartFamilySpec = {
+    type: string;
+    label: string;
+    parameters: Record<string, unknown>;
+    hardware?: HardwareItem[];
+};
+export type Component = {
+    id: string;
+    kind: string;
+    operation: 'add' | 'subtract';
+    dimensions: Record<string, number>;
+};
+export type Feature = {
+    id: string;
+    kind: string;
+    target: string;
+    parameters?: Record<string, unknown>;
+};
+export type ComposablePartSpec = {
+    type: 'composable_part';
+    label: string;
+    components: Component[];
+    features?: Feature[];
+    hardware?: HardwareItem[];
+};
+export type ProjectSpec = {
+    type: 'project';
+    label: string;
+    parts: {
+        id: string;
+        label: string;
+        spec?: PrintSpec;
+        specPath?: string;
+        quantity?: number;
+    }[];
+    hardware?: HardwareItem[];
+};
+export type PrintSpec = {
+    printspecVersion: string;
+    units: 'mm';
+    part?: PartFamilySpec | ComposablePartSpec;
+    project?: ProjectSpec;
+    hardware?: HardwareItem[];
+    metadata?: Record<string, unknown>;
+};
+export type GeneratorResult = {
+    supported: boolean;
+    code: string;
+    message?: string;
+    warnings?: string[];
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validate.d.ts

@@ -0,0 +1,9 @@
+import type { ValidationResult } from './types.js';
+type ValidationOptions = {
+    semantic?: boolean;
+};
+export declare function validatePartFamilySpec(part: unknown, _options?: ValidationOptions): ValidationResult;
+export declare function validateComposablePartSpec(part: unknown, _options?: ValidationOptions): ValidationResult;
+export declare function validateProjectSpec(project: unknown, _options?: ValidationOptions): ValidationResult;
+export declare function validatePrintSpec(spec: unknown, options?: ValidationOptions): ValidationResult;
+export {};

package/dist/validate.js

@@ -0,0 +1,45 @@
+import { validateSemantic } from './semantic.js';
+import { createAjv, schemas } from './schemas.js';
+const ajv = createAjv();
+const validators = new Map();
+function validatorFor(schemaName) {
+    const existing = validators.get(schemaName);
+    if (existing)
+        return existing;
+    const schema = schemas[schemaName];
+    if (!schema)
+        throw new Error(`Missing local schema: ${schemaName}`);
+    const compiled = ajv.compile(schema);
+    validators.set(schemaName, compiled);
+    return compiled;
+}
+function formatPath(instancePath) {
+    return instancePath && instancePath.length > 0 ? instancePath : '/';
+}
+function formatAjvErrors(validate) {
+    return (validate.errors ?? []).map((error) => {
+        const keyword = error.keyword ? ` [${error.keyword}]` : '';
+        const message = error.message ?? 'failed schema validation';
+        return `${formatPath(error.instancePath)}: ${message}${keyword}`;
+    });
+}
+function validateWithSchema(schemaName, value, semantic = false) {
+    const validate = validatorFor(schemaName);
+    const ok = validate(value);
+    const errors = ok ? [] : formatAjvErrors(validate);
+    if (errors.length === 0 && semantic)
+        errors.push(...validateSemantic(value));
+    return { valid: errors.length === 0, errors };
+}
+export function validatePartFamilySpec(part, _options = {}) {
+    return validateWithSchema('part-family.schema.json', part, false);
+}
+export function validateComposablePartSpec(part, _options = {}) {
+    return validateWithSchema('composable-part.schema.json', part, false);
+}
+export function validateProjectSpec(project, _options = {}) {
+    return validateWithSchema('project.schema.json', project, false);
+}
+export function validatePrintSpec(spec, options = {}) {
+    return validateWithSchema('printspec.schema.json', spec, options.semantic !== false);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisra/printspec",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "JSON schemas, validators, BOM helpers, CLI commands, and starter generators for practical parametric 3D-printable parts.",
   "license": "Apache-2.0",
   "author": "Invisra",
@@ -45,7 +45,9 @@
   "scripts": {
     "build": "tsc",
     "test": "npm run build && node --test ../../tests/typescript/*.test.js",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run build && test -f dist/index.js && test -f dist/index.d.ts && test -f dist/cli.js"
   },
   "dependencies": {
     "ajv": "^8.17.1",