@bushscad/cli 0.0.0-stage → 0.3.0

package/src/dto/index.ts

@@ -0,0 +1,28 @@
+/**
+ * @author Aidan Boissonneault
+ * @file index.ts
+ * @purpose Public entry point for cli package.
+ * @last-edited October 6, 2026
+ */
+
+export { parseCompilerRequest, parseServiceRequest } from './request-parser.js';
+export type { CompilerRequestParsePolicy } from './request-parser.js';
+export {
+  parseServiceMessage,
+  parseServiceMessageLine,
+} from './message-parser.js';
+export type {
+  BufferDto,
+  CompilerEngine,
+  CompilerMetrics,
+  CompilerPoolStatus,
+  CompilerRequest,
+  CompilerRequestKind,
+  DrawingOutputMode,
+  MeshDto,
+  ServiceMessage,
+  ServicePoolMessage,
+  ServiceRequest,
+  ServiceResponse,
+  ServiceTraceMessage,
+} from './types.js';

package/src/dto/json.ts

@@ -0,0 +1,39 @@
+/**
+ * @author Aidan Boissonneault
+ * @file json.ts
+ * @purpose Provides json behavior for the dto in cli package.
+ * @last-edited October 6, 2026
+ */
+
+import type { CompileError } from '@bushscad/ir';
+
+/**
+ * Result of maybe error, including success flag and errors.
+ */
+type MaybeErrorResult = {
+  ok: boolean;
+  errors?: CompileError[];
+};
+
+/**
+ * Handles plain compile errors in the dto flow.
+ */
+function plainCompileErrors(errors: CompileError[]): CompileError[] {
+  return errors.map((error) => ({
+    message: error.message,
+    span: error.span,
+  }));
+}
+
+/**
+ * Handles stringify cli result in the dto flow.
+ */
+export function stringifyCliResult<T extends MaybeErrorResult>(
+  result: T,
+): string {
+  if (result.ok || !result.errors) return JSON.stringify(result);
+  return JSON.stringify({
+    ...result,
+    errors: plainCompileErrors(result.errors),
+  });
+}

package/src/dto/meshDto.ts

@@ -0,0 +1,26 @@
+/**
+ * @author Aidan Boissonneault
+ * @file meshDto.ts
+ * @purpose Provides mesh dto behavior for the dto in cli package.
+ * @last-edited October 6, 2026
+ */
+
+import { meshPresentationMetadata, type MeshData } from '@bushscad/ir';
+import type { MeshDto } from './types.js';
+
+/**
+ * Converts internal mesh data into a serializable DTO.
+ * Mesh data contains typed arrays which must be converted
+ * for JSON transport and service responses.
+ */
+export function meshToDto(mesh: MeshData): MeshDto {
+  return {
+    ...meshPresentationMetadata(mesh),
+    vertices: Array.from(mesh.vertices),
+    normals: Array.from(mesh.normals),
+    indices: Array.from(mesh.indices),
+    ...(mesh.isHardwareVisual
+      ? { isHardwareVisual: true, hardwareKind: mesh.hardwareKind }
+      : {}),
+  };
+}

package/src/dto/message-parser.ts

@@ -0,0 +1,158 @@
+/**
+ * @author Aidan Boissonneault
+ * @file message-parser.ts
+ * @purpose Provides message parser behavior for the dto in cli package.
+ * @last-edited October 6, 2026
+ */
+
+import type {
+  CompilerPoolStatus,
+  ServiceMessage,
+  ServicePoolMessage,
+  ServiceResponse,
+  ServiceTraceMessage,
+} from './types.js';
+
+/**
+ * Parses one compiler-service stdout line into its canonical message union.
+ *
+ * Why: hosts must reject malformed or ambiguous child-process output instead
+ * of trusting a TypeScript cast across the process boundary.
+ */
+export function parseServiceMessageLine(line: string): ServiceMessage {
+  let value: unknown;
+  try {
+    value = JSON.parse(line);
+  } catch {
+    throw new TypeError('Compiler service emitted invalid JSON.');
+  }
+  return parseServiceMessage(value);
+}
+
+/** Validates the stable envelope and discriminants of a service message. */
+export function parseServiceMessage(value: unknown): ServiceMessage {
+  const record = objectRecord(value, 'Compiler service message');
+  if (record.kind === 'pool-status') return parsePoolMessage(record);
+  if (record.kind === 'occt-trace') return parseTraceMessage(record);
+  return parseResponse(record);
+}
+
+/**
+ * Parses response from the supplied source into the dto representation.
+ */
+function parseResponse(record: Record<string, unknown>): ServiceResponse {
+  integer(record.id, 'Compiler response id');
+  responseKind(record.kind);
+  if (typeof record.ok !== 'boolean')
+    throw new TypeError('Compiler response ok must be boolean.');
+  if (!Array.isArray(record.env))
+    throw new TypeError('Compiler response env must be an array.');
+  finiteNumber(record.elapsedMs, 'Compiler response elapsedMs');
+  if (!record.ok && !Array.isArray(record.errors)) {
+    throw new TypeError('Failed compiler response must include errors.');
+  }
+  return record as ServiceResponse;
+}
+
+/**
+ * Parses trace message from the supplied source into the dto representation.
+ */
+function parseTraceMessage(
+  record: Record<string, unknown>,
+): ServiceTraceMessage {
+  integer(record.id, 'Compiler trace id');
+  const event = objectRecord(record.event, 'Compiler trace event');
+  stringValue(event.kind, 'Compiler trace event kind');
+  finiteNumber(event.timestampMs, 'Compiler trace timestampMs');
+  if (event.schemaVersion !== undefined) validateVersionedTrace(event);
+  return record as ServiceTraceMessage;
+}
+
+/**
+ * Validates versioned trace and reports any violations.
+ */
+function validateVersionedTrace(event: Record<string, unknown>): void {
+  if (event.schemaVersion !== 2)
+    throw new TypeError('Compiler trace schemaVersion must be 2.');
+  for (const key of ['buildId', 'eventId', 'engine', 'phase', 'state'])
+    stringValue(event[key], `Compiler trace ${key}`);
+  if (!['classic', 'parallel'].includes(String(event.engine)))
+    throw new TypeError('Invalid compiler trace engine.');
+}
+
+/**
+ * Parses pool message from the supplied source into the dto representation.
+ */
+function parsePoolMessage(record: Record<string, unknown>): ServicePoolMessage {
+  const status = objectRecord(record.status, 'Compiler pool status');
+  const state = status.state;
+  if (
+    !['warming', 'ready', 'busy', 'degraded', 'failed', 'stopped'].includes(
+      String(state),
+    )
+  ) {
+    throw new TypeError('Invalid compiler pool state.');
+  }
+  for (const key of [
+    'desiredWorkers',
+    'warmingWorkers',
+    'readyWorkers',
+    'busyWorkers',
+    'failedWorkers',
+    'startupMs',
+    'aggregateWorkerRssBytes',
+    'peakAggregateWorkerRssBytes',
+  ])
+    finiteNumber(status[key], `Compiler pool ${key}`);
+  return { kind: 'pool-status', status: status as CompilerPoolStatus };
+}
+
+/**
+ * Handles object record in the dto flow.
+ */
+function objectRecord(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError(`${label} must be an object.`);
+  }
+  return value as Record<string, unknown>;
+}
+
+/**
+ * Handles integer in the dto flow.
+ */
+function integer(value: unknown, label: string): number {
+  if (!Number.isSafeInteger(value))
+    throw new TypeError(`${label} must be an integer.`);
+  return value as number;
+}
+
+/**
+ * Handles finite number in the dto flow.
+ */
+function finiteNumber(value: unknown, label: string): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new TypeError(`${label} must be a finite number.`);
+  }
+  return value;
+}
+
+/**
+ * Handles string value in the dto flow.
+ */
+function stringValue(value: unknown, label: string): string {
+  if (typeof value !== 'string' || value.length === 0)
+    throw new TypeError(`${label} must be a non-empty string.`);
+  return value;
+}
+
+/**
+ * Handles response kind in the dto flow.
+ */
+function responseKind(value: unknown): ServiceResponse['kind'] {
+  if (
+    !['check', 'preview', 'export', 'exportDrawings'].includes(String(value))
+  ) {
+    throw new TypeError('Invalid compiler response kind.');
+  }
+  return value as ServiceResponse['kind'];
+}

package/src/dto/request-fields.ts

@@ -0,0 +1,174 @@
+/**
+ * @author Aidan Boissonneault
+ * @file request-fields.ts
+ * @purpose Provides request fields behavior for the dto in cli package.
+ * @last-edited October 6, 2026
+ */
+
+import type { CompilerRequestKind, DrawingOutputMode } from './types.js';
+
+/**
+ * String map limits, including entries, key, display value, and total.
+ */
+export type StringMapLimits = {
+  entries: number;
+  key: number;
+  value: number;
+  total: number;
+};
+
+/** Parses a bounded string map used for overlays and environment values. */
+export function parseStringMap(
+  value: unknown,
+  label: string,
+  limits: StringMapLimits,
+): Record<string, string> | undefined {
+  if (value === undefined) return undefined;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError(`${label} must be a string map.`);
+  }
+  const entries = Object.entries(value as Record<string, unknown>);
+  if (entries.length > limits.entries)
+    throw new TypeError(`${label} has too many entries.`);
+  const result = Object.create(null) as Record<string, string>;
+  let total = 0;
+  for (const [key, entry] of entries) {
+    if (
+      !boundedString(key, limits.key) ||
+      !boundedString(entry, limits.value)
+    ) {
+      throw new TypeError(`${label} contains an invalid entry.`);
+    }
+    total += key.length + entry.length;
+    if (total > limits.total)
+      throw new TypeError(`${label} exceeds the total size limit.`);
+    result[key] = entry;
+  }
+  return result;
+}
+
+/**
+ * Parses optional index from the supplied source into the dto representation.
+ */
+export function parseOptionalIndex(
+  value: unknown,
+  label: string,
+): number | undefined {
+  if (value === undefined) return undefined;
+  if (
+    !Number.isSafeInteger(value) ||
+    (value as number) < 0 ||
+    (value as number) > 10_000_000
+  ) {
+    throw new TypeError(`${label} must be a bounded non-negative integer.`);
+  }
+  return value as number;
+}
+
+/**
+ * Parses suppressed indices from the supplied source into the dto representation.
+ */
+export function parseSuppressedIndices(value: unknown): number[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || value.length > 10_000) {
+    throw new TypeError(
+      'Suppressed operation indices must be a bounded array.',
+    );
+  }
+  return value.map(
+    (entry) =>
+      parseOptionalIndex(entry, 'Suppressed operation index') as number,
+  );
+}
+
+/**
+ * Parses entrypoint mode from the supplied source into the dto representation.
+ */
+export function parseEntrypointMode(
+  value: unknown,
+): 'workspace' | 'requested-file' {
+  if (value === undefined || value === 'workspace') return 'workspace';
+  if (value === 'requested-file') return value;
+  throw new TypeError('Invalid compiler entrypoint mode.');
+}
+
+/**
+ * Parses format from the supplied source into the dto representation.
+ */
+export function parseFormat(
+  value: unknown,
+  kind: CompilerRequestKind,
+): 'step' | 'stl' | undefined {
+  if (value !== undefined && value !== 'step' && value !== 'stl') {
+    throw new TypeError('Invalid compiler export format.');
+  }
+  if (kind === 'export' && value === undefined)
+    throw new TypeError('Compiler export format is required.');
+  if (kind !== 'export' && value !== undefined)
+    throw new TypeError('Compiler format is only valid for export.');
+  return value as 'step' | 'stl' | undefined;
+}
+
+/**
+ * Parses optional boolean from the supplied source into the dto representation.
+ */
+export function parseOptionalBoolean(
+  value: unknown,
+  label: string,
+): boolean | undefined {
+  if (value === undefined || typeof value === 'boolean') return value;
+  throw new TypeError(`${label} must be a boolean.`);
+}
+
+/**
+ * Parses engine from the supplied source into the dto representation.
+ */
+export function parseEngine(
+  value: unknown,
+): 'classic' | 'parallel' | undefined {
+  if (value === undefined || value === 'classic' || value === 'parallel') {
+    return value;
+  }
+  throw new TypeError('Invalid compiler engine.');
+}
+
+/** Restricts host-owned drawing writes to the drawing export request. */
+export function parseDrawingOutputMode(
+  value: unknown,
+  kind: CompilerRequestKind,
+): DrawingOutputMode | undefined {
+  if (
+    value !== undefined &&
+    value !== 'write-source-paths' &&
+    value !== 'return-content'
+  )
+    throw new TypeError('Invalid drawing output mode.');
+  if (kind !== 'exportDrawings' && value !== undefined)
+    throw new TypeError(
+      'Drawing output mode is only valid for drawing export.',
+    );
+  return value as DrawingOutputMode | undefined;
+}
+
+/**
+ * Handles assert preview controls in the dto flow.
+ */
+export function assertPreviewControls(
+  kind: CompilerRequestKind,
+  controls: readonly unknown[],
+): void {
+  if (kind !== 'preview' && controls.some((value) => value !== undefined)) {
+    throw new TypeError(
+      'Preview controls are only valid for preview requests.',
+    );
+  }
+}
+
+/**
+ * Handles bounded string in the dto flow.
+ */
+function boundedString(value: unknown, maximum: number): value is string {
+  return (
+    typeof value === 'string' && value.length > 0 && value.length <= maximum
+  );
+}

package/src/dto/request-parser.ts

@@ -0,0 +1,214 @@
+/**
+ * @author Aidan Boissonneault
+ * @file request-parser.ts
+ * @purpose Provides request parser behavior for the dto in cli package.
+ * @last-edited October 6, 2026
+ */
+
+import { isAbsolute, relative, resolve } from 'node:path';
+import {
+  assertPreviewControls,
+  parseEngine,
+  parseDrawingOutputMode,
+  parseEntrypointMode,
+  parseFormat,
+  parseOptionalBoolean,
+  parseOptionalIndex,
+  parseStringMap,
+  parseSuppressedIndices,
+} from './request-fields.js';
+import type {
+  CompilerRequest,
+  CompilerRequestKind,
+  ServiceRequest,
+} from './types.js';
+
+const REQUEST_KEYS = new Set([
+  'id',
+  'kind',
+  'filePath',
+  'rootPath',
+  'entrypointMode',
+  'overlays',
+  'env',
+  'format',
+  'cursorOpIndex',
+  'suppressedOpIndices',
+  'occtTrace',
+  'engine',
+  'drawingOutputMode',
+]);
+const REQUEST_KINDS = new Set<unknown>([
+  'check',
+  'preview',
+  'export',
+  'exportDrawings',
+]);
+
+/**
+ * Compiler request parse policy, including normalize absolute path, assert path allowed, and
+ * path is within.
+ */
+export type CompilerRequestParsePolicy = {
+  normalizeAbsolutePath?: (value: unknown, label: string) => string;
+  assertPathAllowed?: (path: string) => void;
+  pathIsWithin?: (rootPath: string, candidate: string) => boolean;
+};
+
+/**
+ * Parses a host request through the canonical compiler-service contract.
+ *
+ * Why: VS Code and the CLI process must enforce identical field,
+ * size, and operation rules before native compiler work can begin.
+ */
+export function parseCompilerRequest(
+  value: unknown,
+  forcedKind?: CompilerRequestKind,
+  policy: CompilerRequestParsePolicy = {},
+): CompilerRequest {
+  const raw = requestRecord(value);
+  if (raw.kind !== undefined) requestKind(raw.kind);
+  const kind = requestKind(forcedKind ?? raw.kind);
+  const filePath = absolutePath(raw.filePath, 'Compiler file path', policy);
+  const rootPath = optionalRootPath(raw.rootPath, policy);
+  assertWithin(rootPath, filePath, 'Compiler file path', policy);
+  policy.assertPathAllowed?.(filePath);
+  if (rootPath) policy.assertPathAllowed?.(rootPath);
+
+  const overlays = parseStringMap(raw.overlays, 'Compiler overlays', {
+    entries: 1_024,
+    key: 32_767,
+    value: 32 * 1024 * 1024,
+    total: 64 * 1024 * 1024,
+  });
+  validateOverlayPaths(overlays, rootPath, policy);
+  const env = parseStringMap(raw.env, 'Compiler environment', {
+    entries: 256,
+    key: 128,
+    value: 4_096,
+    total: 256 * 4_224,
+  });
+  const format = parseFormat(raw.format, kind);
+  const cursorOpIndex = parseOptionalIndex(
+    raw.cursorOpIndex,
+    'Cursor operation index',
+  );
+  const suppressedOpIndices = parseSuppressedIndices(raw.suppressedOpIndices);
+  const occtTrace = parseOptionalBoolean(raw.occtTrace, 'OCCT trace flag');
+  const engine = parseEngine(raw.engine);
+  const drawingOutputMode = parseDrawingOutputMode(raw.drawingOutputMode, kind);
+  assertPreviewControls(kind, [cursorOpIndex, suppressedOpIndices, occtTrace]);
+
+  return {
+    kind,
+    filePath,
+    ...(rootPath ? { rootPath } : {}),
+    entrypointMode: parseEntrypointMode(raw.entrypointMode),
+    ...(overlays ? { overlays } : {}),
+    ...(env ? { env } : {}),
+    ...(format ? { format } : {}),
+    ...(cursorOpIndex !== undefined ? { cursorOpIndex } : {}),
+    ...(suppressedOpIndices ? { suppressedOpIndices } : {}),
+    ...(occtTrace !== undefined ? { occtTrace } : {}),
+    ...(engine ? { engine } : {}),
+    ...(drawingOutputMode ? { drawingOutputMode } : {}),
+  };
+}
+
+/** Parses an ID-bearing JSON-line request received by the CLI service. */
+export function parseServiceRequest(value: unknown): ServiceRequest {
+  const raw = requestRecord(value);
+  const id = parseOptionalIndex(raw.id, 'Compiler request id');
+  if (id === undefined) throw new TypeError('Compiler request id is required.');
+  return { ...parseCompilerRequest(raw), id };
+}
+
+/**
+ * Handles request record in the dto flow.
+ */
+function requestRecord(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError('Compiler request must be an object.');
+  }
+  const record = value as Record<string, unknown>;
+  for (const key of Object.keys(record)) {
+    if (!REQUEST_KEYS.has(key))
+      throw new TypeError(`Unknown compiler request field: ${key}`);
+  }
+  return record;
+}
+
+/**
+ * Handles request kind in the dto flow.
+ */
+function requestKind(value: unknown): CompilerRequestKind {
+  if (!REQUEST_KINDS.has(value))
+    throw new TypeError('Invalid compiler request kind.');
+  return value as CompilerRequestKind;
+}
+
+/**
+ * Handles absolute path in the dto flow.
+ */
+function absolutePath(
+  value: unknown,
+  label: string,
+  policy: CompilerRequestParsePolicy,
+): string {
+  if (policy.normalizeAbsolutePath)
+    return policy.normalizeAbsolutePath(value, label);
+  if (typeof value !== 'string' || !isAbsolute(value)) {
+    throw new TypeError(`${label} must be an absolute path.`);
+  }
+  return resolve(value);
+}
+
+/**
+ * Handles optional root path in the dto flow.
+ */
+function optionalRootPath(
+  value: unknown,
+  policy: CompilerRequestParsePolicy,
+): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  return absolutePath(value, 'Compiler root path', policy);
+}
+
+/**
+ * Validates overlay paths and reports any violations.
+ */
+function validateOverlayPaths(
+  overlays: Record<string, string> | undefined,
+  rootPath: string | undefined,
+  policy: CompilerRequestParsePolicy,
+): void {
+  for (const path of Object.keys(overlays ?? {})) {
+    const normalized = absolutePath(path, 'Overlay path', policy);
+    assertWithin(rootPath, normalized, 'Compiler overlay', policy);
+    policy.assertPathAllowed?.(normalized);
+  }
+}
+
+/**
+ * Handles assert within in the dto flow.
+ */
+function assertWithin(
+  rootPath: string | undefined,
+  candidate: string,
+  label: string,
+  policy: CompilerRequestParsePolicy,
+): void {
+  if (!rootPath) return;
+  const within = policy.pathIsWithin
+    ? policy.pathIsWithin(rootPath, candidate)
+    : defaultPathIsWithin(rootPath, candidate);
+  if (!within) throw new Error(`${label} is outside the requested root.`);
+}
+
+/**
+ * Returns the default path is within used by this module.
+ */
+function defaultPathIsWithin(rootPath: string, candidate: string): boolean {
+  const child = relative(rootPath, candidate);
+  return child === '' || (!child.startsWith('..') && !isAbsolute(child));
+}