buildwithtrace 0.1.1

package/README.md

@@ -0,0 +1,83 @@
+# buildwithtrace
+
+AI-powered PCB design CLI. Design, review, convert, and manufacture circuit boards from your terminal.
+
+## Installation
+
+```bash
+# Via npm (recommended)
+npx buildwithtrace
+
+# Or install globally
+npm install -g buildwithtrace
+
+# Or via pip
+pip install buildwithtrace
+
+# Or via standalone installer
+curl -fsSL https://buildwithtrace.com/install.sh | sh
+```
+
+## Requirements
+
+- **Node.js 18+** (for the npm wrapper)
+- **Python 3.10+** (automatically detected and used to create a virtual environment)
+
+## Usage
+
+```bash
+# Sign in
+buildwithtrace auth login
+
+# Ask the AI about your design (read-only)
+buildwithtrace ask "What decoupling caps do I need for this STM32?"
+
+# Generate a symbol or footprint
+buildwithtrace generate symbol "STM32F401"
+
+# Run electrical / design rule checks (local engine)
+buildwithtrace erc ./my-project.kicad_sch
+buildwithtrace drc ./my-project.kicad_pcb
+
+# Convert an Altium schematic to KiCad
+buildwithtrace convert schematic ./design.SchDoc
+
+# Check the design against a manufacturer's capabilities
+buildwithtrace dfm check ./my-project/ -m pcbway
+```
+
+> The command is `buildwithtrace`. We don't ship a `trace` binary (it collides with the macOS system `/usr/bin/trace`); add `alias trace=buildwithtrace` yourself if you want a shorter name.
+
+## Commands
+
+| Command       | Description                                      |
+| ------------- | ------------------------------------------------ |
+| `ask`         | Ask the AI about a design (read-only)            |
+| `chat`        | Interactive AI design session                    |
+| `agent`/`plan`| Execute edits / multi-step plan mode             |
+| `generate`    | Generate symbols and footprints                  |
+| `erc`/`drc`   | Local electrical / design rule checks            |
+| `gerbers`/`export` | Manufacturing + PDF/SVG/STEP export         |
+| `convert`     | Altium ↔ KiCad ↔ Trace JSON conversion           |
+| `dfm`/`order` | DFM checks and manufacturing orders              |
+| `review`      | AI-powered design review                         |
+| `auth`        | Authenticate with your Trace account             |
+
+## How It Works
+
+The npm package is a lightweight wrapper that:
+
+1. Detects Python 3.10+ on your system
+2. Creates an isolated virtual environment
+3. Downloads and installs the `buildwithtrace` Python wheel
+4. Proxies all commands to the Python CLI
+
+If Python isn't available, it falls back to a system-installed `buildwithtrace` binary.
+
+## Documentation
+
+Full documentation: [docs.buildwithtrace.com](https://docs.buildwithtrace.com)
+
+## License
+
+See [LICENSE](https://github.com/buildwithtrace/cli/blob/main/LICENSE) for details.

package/bin/buildwithtrace.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawnSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const VENV_DIR = path.join(
+  __dirname,
+  "..",
+  "node_modules",
+  ".cache",
+  "buildwithtrace",
+  "venv"
+);
+
+function getVenvPython() {
+  if (process.platform === "win32") {
+    return path.join(VENV_DIR, "Scripts", "python.exe");
+  }
+  return path.join(VENV_DIR, "bin", "python3");
+}
+
+function run() {
+  const args = process.argv.slice(2);
+  const venvPython = getVenvPython();
+
+  if (fs.existsSync(venvPython)) {
+    const result = spawnSync(venvPython, ["-m", "buildwithtrace", ...args], {
+      stdio: "inherit",
+      env: { ...process.env },
+    });
+    process.exit(result.status ?? 1);
+  }
+
+  // Fallback: try system-installed buildwithtrace
+  const cmd = process.platform === "win32" ? "buildwithtrace.exe" : "buildwithtrace";
+  const result = spawnSync(cmd, args, {
+    stdio: "inherit",
+    env: { ...process.env },
+  });
+
+  if (result.error) {
+    console.error(
+      "[buildwithtrace] CLI not found. Run `npx buildwithtrace` to trigger installation,\n" +
+        "or install directly: pip install buildwithtrace"
+    );
+    process.exit(1);
+  }
+
+  process.exit(result.status ?? 1);
+}
+
+run();

package/install.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+"use strict";
+
+const { execSync, execFileSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const { pipeline } = require("stream/promises");
+
+// Derive the wheel name from package.json so a version bump (release.yml runs
+// `npm version` before publishing) downloads the matching release asset instead of a
+// stale, hardcoded one. `latest/download/<file>` resolves to the newest release's asset.
+const PKG_VERSION = require("./package.json").version;
+const WHEEL_NAME = `buildwithtrace-${PKG_VERSION}-py3-none-any.whl`;
+const WHEEL_URL = `https://github.com/buildwithtrace/cli/releases/latest/download/${WHEEL_NAME}`;
+const VENV_DIR = path.join(
+  __dirname,
+  "node_modules",
+  ".cache",
+  "buildwithtrace",
+  "venv"
+);
+const MAX_RETRIES = 3;
+const MIN_PYTHON_VERSION = [3, 10];
+
+function log(msg) {
+  console.log(`[buildwithtrace] ${msg}`);
+}
+
+function warn(msg) {
+  console.warn(`[buildwithtrace] ⚠ ${msg}`);
+}
+
+function findPython() {
+  const candidates =
+    process.platform === "win32"
+      ? ["python3", "python", "py -3"]
+      : ["python3", "python"];
+
+  for (const cmd of candidates) {
+    try {
+      const parts = cmd.split(" ");
+      const result = execFileSync(parts[0], [...parts.slice(1), "--version"], {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+      const match = result.match(/Python (\d+)\.(\d+)\.(\d+)/);
+      if (match) {
+        const major = parseInt(match[1], 10);
+        const minor = parseInt(match[2], 10);
+        if (
+          major > MIN_PYTHON_VERSION[0] ||
+          (major === MIN_PYTHON_VERSION[0] && minor >= MIN_PYTHON_VERSION[1])
+        ) {
+          log(`Found Python ${match[1]}.${match[2]}.${match[3]} (${cmd})`);
+          return cmd;
+        }
+      }
+    } catch {
+      // Not found, try next
+    }
+  }
+  return null;
+}
+
+function getPythonBin() {
+  if (process.platform === "win32") {
+    return path.join(VENV_DIR, "Scripts", "python.exe");
+  }
+  return path.join(VENV_DIR, "bin", "python3");
+}
+
+function getPipBin() {
+  if (process.platform === "win32") {
+    return path.join(VENV_DIR, "Scripts", "pip.exe");
+  }
+  return path.join(VENV_DIR, "bin", "pip");
+}
+
+async function downloadWithRetry(url, destPath) {
+  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      log(
+        `Downloading wheel (attempt ${attempt}/${MAX_RETRIES})...`
+      );
+
+      const response = await fetch(url, { redirect: "follow" });
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+
+      const fileStream = fs.createWriteStream(destPath);
+      await pipeline(response.body, fileStream);
+
+      const stats = fs.statSync(destPath);
+      if (stats.size === 0) {
+        throw new Error("Downloaded file is empty");
+      }
+
+      log(`Downloaded ${(stats.size / 1024 / 1024).toFixed(1)} MB`);
+      return;
+    } catch (err) {
+      if (attempt < MAX_RETRIES) {
+        const delay = attempt * 2000;
+        warn(`Download failed: ${err.message}. Retrying in ${delay / 1000}s...`);
+        await new Promise((r) => setTimeout(r, delay));
+      } else {
+        throw new Error(
+          `Failed to download after ${MAX_RETRIES} attempts: ${err.message}`
+        );
+      }
+    }
+  }
+}
+
+async function main() {
+  log("Setting up buildwithtrace CLI...");
+
+  const python = findPython();
+  if (!python) {
+    console.error(`
+╔══════════════════════════════════════════════════════════════════╗
+║  buildwithtrace requires Python 3.10 or later                   ║
+╠══════════════════════════════════════════════════════════════════╣
+║                                                                  ║
+║  Python was not found on your system. Install options:           ║
+║                                                                  ║
+║  1. Install Python: https://www.python.org/downloads/            ║
+║                                                                  ║
+║  2. Install directly via pip (if Python is available elsewhere): ║
+║     pip install buildwithtrace                                   ║
+║                                                                  ║
+║  3. Use the standalone installer:                                ║
+║     curl -fsSL https://buildwithtrace.com/install.sh | sh        ║
+║                                                                  ║
+║  After installing Python, run: npx buildwithtrace                ║
+╚══════════════════════════════════════════════════════════════════╝
+`);
+    process.exit(0); // Exit 0 so npm install doesn't fail
+  }
+
+  // Create venv
+  log("Creating virtual environment...");
+  fs.mkdirSync(path.dirname(VENV_DIR), { recursive: true });
+
+  const pythonParts = python.split(" ");
+  try {
+    execFileSync(pythonParts[0], [...pythonParts.slice(1), "-m", "venv", VENV_DIR], {
+      stdio: "pipe",
+    });
+  } catch (err) {
+    warn(`Failed to create venv: ${err.message}`);
+    warn("The CLI will fall back to system-installed buildwithtrace.");
+    process.exit(0);
+  }
+
+  // Download wheel
+  const wheelDir = path.join(VENV_DIR, ".wheels");
+  fs.mkdirSync(wheelDir, { recursive: true });
+  const wheelPath = path.join(wheelDir, WHEEL_NAME);
+
+  try {
+    await downloadWithRetry(WHEEL_URL, wheelPath);
+  } catch (err) {
+    warn(`${err.message}`);
+    warn("The CLI will fall back to system-installed buildwithtrace.");
+    process.exit(0);
+  }
+
+  // Install wheel into venv
+  log("Installing buildwithtrace into virtual environment...");
+  const pip = getPipBin();
+  try {
+    execFileSync(pip, ["install", "--quiet", "--no-cache-dir", wheelPath], {
+      stdio: "pipe",
+    });
+  } catch (err) {
+    warn(`pip install failed: ${err.message}`);
+    warn("The CLI will fall back to system-installed buildwithtrace.");
+    process.exit(0);
+  }
+
+  log("Installation complete! Run `buildwithtrace --help` to get started.");
+}
+
+main().catch((err) => {
+  warn(`Unexpected error: ${err.message}`);
+  process.exit(0);
+});

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "buildwithtrace",
+  "version": "0.1.1",
+  "description": "AI-powered PCB design CLI. Design, review, convert, and manufacture circuit boards from your terminal.",
+  "bin": {
+    "buildwithtrace": "./bin/buildwithtrace.js"
+  },
+  "keywords": [
+    "pcb",
+    "eda",
+    "kicad",
+    "altium",
+    "electronics",
+    "hardware",
+    "circuit"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/buildwithtrace/cli"
+  },
+  "homepage": "https://buildwithtrace.com",
+  "bugs": {
+    "url": "https://github.com/buildwithtrace/cli/issues"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "files": [
+    "bin/",
+    "install.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "postinstall": "node install.js"
+  }
+}