@typecad/cuttlefish 0.1.0-alpha.1

package/dist/create/index.js

@@ -0,0 +1,8 @@
+export { scaffoldProject, normalizeProjectName, KNOWN_TARGETS, KNOWN_BOARDS, registerKnownTarget, printInitNextSteps } from './init-scaffold.js';
+export { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateGitignore, generateEslintConfig, } from './init-templates.js';
+export { runInitWizard } from './init-wizard.js';
+// Board codegen tool (`cuttlefish board add`)
+export { scaffoldBoardPackages } from './board-codegen.js';
+export { generateFrameworkChecklist } from './board-checklist.js';
+export { parseBoardSpec, safeParseBoardSpec, stripJsonc, BoardSpecSchema } from './board-spec.js';
+export * as BoardGenerators from './board-generators.js';

package/dist/create/init-scaffold.d.ts

@@ -0,0 +1,27 @@
+import type { ArchitectureIdentifier } from "../api/index.js";
+import type { InitProjectOptions } from "./init-templates.js";
+export interface KnownTarget {
+    id: string;
+    displayName: string;
+    isNative: boolean;
+    architecture?: ArchitectureIdentifier;
+    boardPackage?: string;
+    frameworkPackage: string;
+    framework: string;
+    buildTarget?: string;
+    mcu?: string;
+}
+export declare function registerKnownTarget(target: KnownTarget): void;
+export declare const KNOWN_TARGETS: ReadonlyArray<KnownTarget>;
+/** @deprecated Use KNOWN_TARGETS */
+export declare const KNOWN_BOARDS: KnownTarget[];
+/** @deprecated Use KnownTarget */
+export type KnownBoard = KnownTarget;
+export declare function normalizeProjectName(name: string): string;
+export interface ScaffoldProjectResult {
+    createdFiles: string[];
+    outDir: string;
+    options: InitProjectOptions;
+}
+export declare function scaffoldProject(options: InitProjectOptions, outDir?: string): ScaffoldProjectResult;
+export declare function printInitNextSteps(options: InitProjectOptions, outDir: string): void;

package/dist/create/init-scaffold.js

@@ -0,0 +1,150 @@
+import path from "node:path";
+import fs from "node:fs";
+import chalk from "chalk";
+import { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateGitignore, generateBoardForwardingFile, generateEslintConfig, } from "./init-templates.js";
+import { generateEslintRules } from "./eslint-rules-template.js";
+const _knownTargets = [
+    {
+        id: 'native',
+        displayName: 'Native Desktop',
+        isNative: true,
+        frameworkPackage: '@typecad/framework-native',
+        framework: 'native',
+    },
+    {
+        id: 'arduino-uno',
+        displayName: 'Arduino Uno',
+        isNative: false,
+        architecture: 'avr',
+        boardPackage: '@typecad/board-arduino-uno',
+        frameworkPackage: '@typecad/framework-arduino',
+        framework: 'arduino',
+        buildTarget: 'arduino:avr:uno',
+        mcu: 'atmega328p',
+    },
+    {
+        id: 'esp32-devkit',
+        displayName: 'ESP32 DevKit',
+        isNative: false,
+        architecture: 'esp32',
+        boardPackage: '@typecad/board-esp32-devkit',
+        frameworkPackage: '@typecad/framework-arduino',
+        framework: 'arduino',
+        buildTarget: 'esp32:esp32:esp32',
+        mcu: 'esp32',
+    },
+    {
+        id: 'esp32s3',
+        displayName: 'ESP32-S3',
+        isNative: false,
+        architecture: 'esp32s3',
+        boardPackage: '@typecad/board-esp32s3',
+        frameworkPackage: '@typecad/framework-arduino',
+        framework: 'arduino',
+        buildTarget: 'esp32:esp32:esp32s3',
+        mcu: 'esp32s3',
+    },
+    {
+        id: 'esp32c3',
+        displayName: 'ESP32-C3',
+        isNative: false,
+        architecture: 'esp32c3',
+        boardPackage: '@typecad/board-esp32c3',
+        frameworkPackage: '@typecad/framework-arduino',
+        framework: 'arduino',
+        buildTarget: 'esp32:esp32:esp32c3',
+        mcu: 'esp32c3',
+    },
+    {
+        id: 'esp32c6',
+        displayName: 'ESP32-C6',
+        isNative: false,
+        architecture: 'esp32c6',
+        boardPackage: '@typecad/board-esp32c6',
+        frameworkPackage: '@typecad/framework-arduino',
+        framework: 'arduino',
+        buildTarget: 'esp32:esp32:esp32c6',
+        mcu: 'esp32c6',
+    },
+];
+export function registerKnownTarget(target) {
+    const existing = _knownTargets.findIndex(t => t.id === target.id);
+    if (existing >= 0) {
+        _knownTargets[existing] = target;
+    }
+    else {
+        _knownTargets.push(target);
+    }
+}
+export const KNOWN_TARGETS = _knownTargets;
+/** @deprecated Use KNOWN_TARGETS */
+export const KNOWN_BOARDS = _knownTargets;
+export function normalizeProjectName(name) {
+    return name
+        .toLowerCase()
+        .replace(/[\s_]+/g, '-')
+        .replace(/[^a-z0-9-]/g, '')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+export function scaffoldProject(options, outDir) {
+    const resolvedOutDir = outDir
+        ? path.resolve(outDir)
+        : path.resolve(process.cwd(), options.projectName);
+    if (fs.existsSync(resolvedOutDir)) {
+        const contents = fs.readdirSync(resolvedOutDir);
+        if (contents.length > 0) {
+            throw new Error(`Directory '${resolvedOutDir}' already exists and is not empty. ` +
+                `Choose a different project name or use --outDir to specify a different location.`);
+        }
+    }
+    const srcDir = path.join(resolvedOutDir, 'src');
+    const cuttlefishDir = path.join(resolvedOutDir, '.cuttlefish');
+    const createdFiles = [];
+    fs.mkdirSync(srcDir, { recursive: true });
+    // .cuttlefish/ holds generated boilerplate (env.d.ts, eslint config, board.ts)
+    fs.mkdirSync(cuttlefishDir, { recursive: true });
+    function writeFile(fileName, content) {
+        const filePath = path.join(resolvedOutDir, fileName);
+        fs.writeFileSync(filePath, content, 'utf-8');
+        createdFiles.push(filePath);
+        return filePath;
+    }
+    writeFile('package.json', generateProjectPackageJson(options));
+    writeFile('tsconfig.json', generateProjectTsconfig(options));
+    writeFile('cuttlefish.config.ts', generateProjectConfig(options));
+    writeFile('.cuttlefish/cuttlefish-env.d.ts', generateProjectEnvDts(options));
+    writeFile('.cuttlefish/eslint.config.mjs', generateEslintConfig(options));
+    writeFile('.cuttlefish/eslint-transpiler-rules.mjs', generateEslintRules(options));
+    writeFile('.gitignore', generateGitignore(options));
+    if (options.boardPackage) {
+        const boardFilePath = path.join(cuttlefishDir, 'board.ts');
+        fs.writeFileSync(boardFilePath, generateBoardForwardingFile(options.boardPackage), 'utf-8');
+        createdFiles.push(boardFilePath);
+    }
+    if (options.includeSketch) {
+        const entryName = 'main.ts';
+        const sketchPath = path.join(srcDir, entryName);
+        fs.writeFileSync(sketchPath, generateStarterSketch(options), 'utf-8');
+        createdFiles.push(sketchPath);
+    }
+    return { createdFiles, outDir: resolvedOutDir, options };
+}
+export function printInitNextSteps(options, outDir) {
+    const relativeDir = path.relative(process.cwd(), outDir) || '.';
+    console.log();
+    console.log(chalk.cyan(`⤳ Cuttlefish`));
+    console.log();
+    console.log(chalk.bold.white("Next steps:"));
+    console.log(chalk.dim(`  cd ${relativeDir}`));
+    console.log(chalk.dim(`  npm install`));
+    console.log(`  ${chalk.cyan("npm run compile")}`);
+    if (!options.isNative) {
+        const portHint = process.platform === 'win32' ? 'COM4' : '/dev/ttyACM0';
+        console.log();
+        console.log(chalk.bold.white("To upload to your board:"));
+        console.log(`  ${chalk.cyan("npm run upload")}`);
+        console.log();
+        console.log(chalk.dim(`Edit ${chalk.white("package.json")} to change the serial port from ${chalk.white(portHint)} to your port.`));
+    }
+}

package/dist/create/init-templates.d.ts

@@ -0,0 +1,24 @@
+import type { ArchitectureIdentifier } from '../api/index.js';
+export interface InitProjectOptions {
+    projectName: string;
+    targetId: string;
+    targetDisplayName: string;
+    isNative: boolean;
+    architecture?: ArchitectureIdentifier;
+    boardPackage?: string;
+    frameworkPackage: string;
+    framework: string;
+    buildTarget?: string;
+    mcu?: string;
+    baudRate?: number;
+    includeSketch: boolean;
+    toolchainType?: string;
+}
+export declare function generateProjectPackageJson(options: InitProjectOptions): string;
+export declare function generateProjectTsconfig(options: InitProjectOptions): string;
+export declare function generateProjectConfig(options: InitProjectOptions): string;
+export declare function generateProjectEnvDts(options: InitProjectOptions): string;
+export declare function generateStarterSketch(options: InitProjectOptions): string;
+export declare function generateBoardForwardingFile(boardPackage: string): string;
+export declare function generateGitignore(_options: InitProjectOptions): string;
+export declare function generateEslintConfig(_options: InitProjectOptions): string;

package/dist/create/init-templates.js

@@ -0,0 +1,379 @@
+import { LINT_RULES } from '../ir/feature-registry.js';
+export function generateProjectPackageJson(options) {
+    const { projectName, frameworkPackage, boardPackage } = options;
+    const deps = {
+        "@typecad/cuttlefish": "^0.1.0-alpha.1",
+        [frameworkPackage]: "^0.1.0-alpha.1",
+    };
+    if (boardPackage) {
+        deps[boardPackage] = "^0.1.0-alpha.1";
+    }
+    const depsJson = Object.entries(deps)
+        .map(([k, v]) => `    "${k}": "${v}"`)
+        .join(',\n');
+    // The scaffolded eslint.config.mjs imports @typescript-eslint/parser and the
+    // eslint-transpiler-rules plugin (which is plain JS, no dep). Without these
+    // devDependencies `npm run lint` fails to resolve the parser/plugin in a
+    // freshly created project. Versions mirror the repo demo's package.json.
+    const devDepsJson = [
+        '    "eslint": "^10.4.1"',
+        '    "@typescript-eslint/parser": "^8.61.0"',
+        '    "@typescript-eslint/eslint-plugin": "^8.61.0"',
+    ].join(',\n');
+    if (options.isNative) {
+        return `{
+  "name": "${projectName}",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "build": "cuttlefish build",
+    "compile": "cuttlefish build --compile",
+    "lint": "eslint --config .cuttlefish/eslint.config.mjs src/"
+  },
+  "dependencies": {
+${depsJson}
+  },
+  "devDependencies": {
+${devDepsJson}
+  }
+}
+`;
+    }
+    return `{
+  "name": "${projectName}",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "build": "cuttlefish build",
+    "compile": "cuttlefish build --compile",
+    "upload": "cuttlefish build --compile --upload",
+    "monitor": "cuttlefish build --compile --upload --monitor",
+    "lint": "eslint --config .cuttlefish/eslint.config.mjs src/"
+  },
+  "dependencies": {
+${depsJson}
+  },
+  "devDependencies": {
+${devDepsJson}
+  }
+}
+`;
+}
+export function generateProjectTsconfig(options) {
+    const paths = options.boardPackage
+        ? `,
+    "paths": {
+      "@typecad/board": ["./.cuttlefish/board.ts"]
+    }`
+        : '';
+    return `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "strict": true,
+    "strictNullChecks": true,
+    "noImplicitAny": true,
+    "noImplicitThis": true,
+    "noImplicitOverride": true,
+    "exactOptionalPropertyTypes": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "allowArbitraryExtensions": true,
+    "rootDirs": ["src", "types"]${paths}
+  },
+  "include": ["src/**/*.ts", "types/**/*.ts", "cuttlefish.config.ts"${options.boardPackage ? ', ".cuttlefish/cuttlefish-env.d.ts"' : ''}]
+}
+`;
+}
+export function generateProjectConfig(options) {
+    if (options.isNative) {
+        return `// ---------------------------------------------------------------------------
+// cuttlefish.config.ts — Project configuration
+//
+// Auto-generated by 'cuttlefish create'. Edit to customise your build.
+// ---------------------------------------------------------------------------
+
+const config = {
+  // Entry point — the main TypeScript file to transpile
+  entry: './src/main.ts',
+
+  // Framework package — controls code generation strategy
+  framework: '${options.frameworkPackage}',
+
+  // Output options
+  output: {
+    optimize: 'speed',
+    outDir: './out',
+  },
+};
+
+export default config;
+`;
+    }
+    const buildTarget = options.buildTarget;
+    const resolvedToolchain = options.toolchainType ?? 'arduino-cli';
+    const buildTargetLine = buildTarget ? `\n  // Framework data\n  frameworkData: {\n    buildTarget: '${buildTarget}',\n  },` : '';
+    const mcuLine = options.mcu
+        ? `\n  // MCU package — provides silicon-level pin definitions\n  mcu: '${options.mcu.startsWith('@') ? options.mcu : `@typecad/mcu-${options.mcu}`}',\n`
+        : '';
+    const boardLine = options.boardPackage
+        ? `\n  // Board package — provides pin definitions and board constants\n  board: '${options.boardPackage}',`
+        : '';
+    const portHint = process.platform === 'win32' ? 'COM4' : '/dev/ttyACM0';
+    const baudLine = options.baudRate ? `\n\n  // Console polyfill configuration\n  console: {\n    baudRate: ${options.baudRate},\n    // Serial port for upload/monitor. Override with --port on the CLI.\n    port: '${portHint}',\n  },` : '';
+    return `// ---------------------------------------------------------------------------
+// cuttlefish.config.ts — Project configuration
+//
+// Auto-generated by 'cuttlefish create'. Edit to customise your build.
+// ---------------------------------------------------------------------------
+
+import type { CuttlefishConfig } from '@typecad/cuttlefish/api';
+
+const config: CuttlefishConfig = {
+  // Entry point — the main TypeScript file to transpile
+  entry: './src/main.ts',
+
+  // Target architecture
+  target: '${options.architecture}',${mcuLine}${boardLine}
+
+  // Framework package — controls code generation strategy
+  framework: '${options.frameworkPackage}',${buildTargetLine}
+
+  // Output / build options
+  output: {
+    framework: '${options.framework}',
+    optimize: 'size',
+    outDir: './out',
+  },
+
+  // Toolchain configuration
+  toolchain: {
+    type: '${resolvedToolchain}',
+  },${baudLine}
+};
+
+export default config;
+`;
+}
+export function generateProjectEnvDts(options) {
+    if (!options.boardPackage) {
+        return `// ---------------------------------------------------------------------------
+// cuttlefish-env.d.ts — Global type declarations
+//
+// Auto-generated by 'cuttlefish create'. Do not edit manually.
+// ---------------------------------------------------------------------------
+
+declare global {
+  type Owned<T = unknown> = T;
+  type Shared<T = unknown> = T;
+  type Mutable<T = unknown> = T;
+
+  type uint8_t = number;
+  type int8_t = number;
+  type uint16_t = number;
+  type int16_t = number;
+  type uint32_t = number;
+  type int32_t = number;
+  type size_t = number;
+  type float = number;
+  type double = number;
+
+  // console — declared here (not pulled from lib.dom) so this project does not
+  // need "dom" in tsconfig lib just to type console.log. Avoiding lib.dom also
+  // keeps DOM global type names (Node, Element, Event, ...) out of scope, so a
+  // user class named e.g. Node is not shadowed by the DOM global. The
+  // transpiler regenerates this file on build and may merge extra members
+  // (readLine/readCharacter) onto the Console interface.
+  interface Console {
+    log(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+  }
+  const console: Console;
+}
+
+export {};
+`;
+    }
+    return `// ---------------------------------------------------------------------------
+// cuttlefish-env.d.ts — Virtual module declaration for '@typecad/board'
+//
+// Auto-generated by 'cuttlefish create'. Do not edit manually.
+// To change the board, update cuttlefish.config.ts and re-run the transpiler.
+//
+// Board: ${options.targetDisplayName}
+// ---------------------------------------------------------------------------
+
+declare global {
+  type Owned<T = unknown> = T;
+  type Shared<T = unknown> = T;
+  type Mutable<T = unknown> = T;
+
+  type uint8_t = number;
+  type int8_t = number;
+  type uint16_t = number;
+  type int16_t = number;
+  type uint32_t = number;
+  type int32_t = number;
+  type size_t = number;
+  type float = number;
+  type double = number;
+
+  // console — declared here (not pulled from lib.dom) so this project does not
+  // need "dom" in tsconfig lib just to type console.log. Avoiding lib.dom also
+  // keeps DOM global type names (Node, Element, Event, ...) out of scope, so a
+  // user class named e.g. Node is not shadowed by the DOM global. The
+  // transpiler regenerates this file on build and may merge extra members
+  // (readLine/readCharacter) onto the Console interface.
+  interface Console {
+    log(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+  }
+  const console: Console;
+}
+
+declare module '@typecad/board' {
+  export * from './board.js';
+  export type Owned<T = unknown> = T;
+  export type Shared<T = unknown> = T;
+  export type Mutable<T = unknown> = T;
+}
+
+export {};
+`;
+}
+export function generateStarterSketch(options) {
+    if (options.isNative) {
+        return `// ---------------------------------------------------------------------------
+// Hello World — Native desktop application
+//
+// Compiles to a native executable via g++/clang++.
+// ---------------------------------------------------------------------------
+
+function fibonacci(n: number): number {
+  if (n <= 1) return n;
+  return fibonacci(n - 1) + fibonacci(n - 2);
+}
+
+console.log("Hello from Cuttlefish!");
+console.log("Fibonacci(10) =", fibonacci(10));
+`;
+    }
+    return `// ---------------------------------------------------------------------------
+// Blink — The classic "Hello World" of embedded
+//
+// Toggles the onboard LED every second using the recommended GPIO pattern.
+// ---------------------------------------------------------------------------
+
+import { LED, delay } from '@typecad/board';
+
+const led = LED.asOutput(false);
+
+while (true) {
+  led.toggle();
+  delay(1000);
+}
+`;
+}
+export function generateBoardForwardingFile(boardPackage) {
+    return `// ---------------------------------------------------------------------------
+// .cuttlefish/board.ts — Dynamically generated forwarding board package
+// ---------------------------------------------------------------------------
+
+export * from '${boardPackage}';
+`;
+}
+export function generateGitignore(_options) {
+    return `node_modules/
+out/
+dist/
+*.thcppmap.json
+.cuttlefish-cache.json
+
+# Generated boilerplate (regenerated on build — do not commit)
+.cuttlefish/cuttlefish-env.d.ts
+.cuttlefish/eslint.config.mjs
+.cuttlefish/eslint-transpiler-rules.mjs
+`;
+}
+export function generateEslintConfig(_options) {
+    // `no-restricted-syntax` selectors are generated from LINT_RULES
+    // (packages/cuttlefish/src/ir/feature-registry.ts), the single source of
+    // truth shared with build-time prescan diagnostics. See SUPPORT_MATRIX for
+    // the per-pattern ❌/🚫 rationale. Do not hand-edit the array below.
+    const transpilerRulesJson = JSON.stringify(LINT_RULES.map(({ selector, message }) => ({ selector, message })), null, 2).replace(/\n/g, "\n  ");
+    return `import tsparser from "@typescript-eslint/parser";
+import tseslint from "@typescript-eslint/eslint-plugin";
+import transpilerPlugin from "./eslint-transpiler-rules.mjs";
+
+// Auto-generated from feature-registry.ts LINT_RULES — do not edit by hand.
+const transpilerRules = ${transpilerRulesJson};
+
+export default [
+  {
+    ignores: ["**/dist/**", "**/node_modules/**", "**/*.d.ts", "out/**"],
+  },
+  {
+    files: ["src/**/*.ts"],
+    languageOptions: {
+      parser: tsparser,
+      parserOptions: {
+        // Type-aware parsing so @typescript-eslint/no-explicit-any resolves
+        // imported bindings to their real types instead of defaulting to any.
+        project: "./tsconfig.json",
+      },
+    },
+    plugins: {
+      "@typescript-eslint": tseslint,
+      cuttlefish: transpilerPlugin,
+    },
+    rules: {
+      "no-restricted-syntax": ["error", ...transpilerRules],
+      // Core ESLint + @typescript-eslint AOT-safety rules.
+      "@typescript-eslint/no-explicit-any": "error",
+      "no-delete-var": "error",
+      "no-eval": "error",
+      "no-sparse-arrays": "error",
+      "no-restricted-globals": [
+        "error",
+        { "name": "Proxy", "message": "[transpiler] Proxy is not supported (no AOT lowering). Avoid." },
+        { "name": "Reflect", "message": "[transpiler] Reflect is not supported (no AOT lowering). Avoid." },
+        { "name": "WeakRef", "message": "[transpiler] WeakRef depends on the GC schedule — bare metal has no GC. Avoid." },
+        { "name": "FinalizationRegistry", "message": "[transpiler] FinalizationRegistry depends on the GC schedule — bare metal has no GC. Avoid." },
+        { "name": "Symbol", "message": "[transpiler] Symbol depends on runtime symbol lookup / the iterator protocol, which has no AOT lowering. Avoid." },
+      ],
+      // Cuttlefish transpiler-compatibility plugin rules.
+      "cuttlefish/no-delete-non-map": "error",
+      "cuttlefish/no-object-static-non-map": "error",
+      "cuttlefish/no-super-outside-method": "error",
+      "cuttlefish/no-typeof-non-primitive": "error",
+      "cuttlefish/no-destructured-without-init": "error",
+      "cuttlefish/no-fractional-to-number-type": "error",
+      "cuttlefish/no-array-param-content-mutation": "error",
+      "cuttlefish/no-container-functional-methods": "error",
+      "cuttlefish/no-undefined-compare-on-get": "error",
+      "cuttlefish/no-map-struct-mutation": "error",
+      "cuttlefish/no-mutating-method-on-const-collection": "warn",
+      "cuttlefish/no-readonly-loop-variable-mutation": "warn",
+      "cuttlefish/no-undefined-compare-on-struct-field": "error",
+      "cuttlefish/no-typed-array-param-length": "error",
+      "cuttlefish/no-typed-array-return": "error",
+      "cuttlefish/no-typed-array-field": "error",
+      "cuttlefish/no-dynamic-property-access": "error",
+      "cuttlefish/no-this-in-free-function": "error",
+    },
+  },
+];
+`;
+}

package/dist/create/init-wizard.d.ts

@@ -0,0 +1,8 @@
+import type { InitProjectOptions } from "./init-templates.js";
+export declare function runInitWizard(partialOptions?: {
+    projectName?: string;
+    board?: string;
+    framework?: string;
+    baud?: number;
+    noSketch?: boolean;
+}): Promise<InitProjectOptions | null>;