feat: Initial Arduino API for VS Code extensions

Signed-off-by: dankeboy36 <dankeboy36@gmail.com>

.eslintrc.json

@@ -0,0 +1,24 @@
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": 6,
+    "sourceType": "module"
+  },
+  "extends": [
+    "plugin:@typescript-eslint/recommended",
+    "plugin:prettier/recommended",
+    "prettier"
+  ],
+  "plugins": ["@typescript-eslint", "prettier"],
+  "rules": {
+    "@typescript-eslint/naming-convention": "off",
+    "@typescript-eslint/semi": "warn",
+    "curly": "warn",
+    "eqeqeq": "warn",
+    "no-throw-literal": "warn",
+    "semi": "off",
+    "prettier/prettier": "warn"
+  },
+  "ignorePatterns": ["out", "dist", "**/*.d.ts"]
+}

.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: Tests
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    name: test (${{ matrix.os }}, node-${{ matrix.node }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, ubuntu-latest, macos-latest]
+        node: [16.x, 18.x]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.config.node }}
+      - uses: coactions/setup-xvfb@v1
+        with:
+          run: npm ci && npm test

.gitignore

@@ -0,0 +1,5 @@
+out
+dist
+node_modules
+.vscode-test/
+*.vsix

.prettierignore

@@ -0,0 +1,3 @@
+out
+dist
+.vscode-test

.prettierrc.json

@@ -0,0 +1,15 @@
+{
+  "singleQuote": true,
+  "tabWidth": 2,
+  "useTabs": false,
+  "printWidth": 80,
+  "endOfLine": "auto",
+  "overrides": [
+    {
+      "files": "*.json",
+      "options": {
+        "tabWidth": 2
+      }
+    }
+  ]
+}

.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+  "recommendations": [
+    "dbaeumer.vscode-eslint",
+    "amodio.tsl-problem-matcher",
+    "streetsidesoftware.code-spell-checker"
+  ]
+}

.vscode/launch.json

@@ -0,0 +1,27 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Run Extension",
+      "type": "extensionHost",
+      "request": "launch",
+      "args": ["--extensionDevelopmentPath=${workspaceFolder}"],
+      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
+      "preLaunchTask": "${defaultBuildTask}"
+    },
+    {
+      "name": "Extension Tests",
+      "type": "extensionHost",
+      "request": "launch",
+      "args": [
+        "--extensionDevelopmentPath=${workspaceFolder}",
+        "--extensionTestsPath=${workspaceFolder}/out/test/suite/index"
+      ],
+      "outFiles": [
+        "${workspaceFolder}/out/**/*.js",
+        "${workspaceFolder}/dist/**/*.js"
+      ],
+      "preLaunchTask": "tasks: watch-tests"
+    }
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,15 @@
+{
+  "files.exclude": {
+    "out": false,
+    "dist": false
+  },
+  "search.exclude": {
+    "out": true,
+    "dist": true
+  },
+  "typescript.tsc.autoDetect": "off",
+  "typescript.tsdk": "./node_modules/typescript/lib",
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": true
+  }
+}

.vscode/tasks.json

@@ -0,0 +1,35 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "type": "npm",
+      "script": "watch",
+      "problemMatcher": "$ts-webpack-watch",
+      "isBackground": true,
+      "presentation": {
+        "reveal": "never",
+        "group": "watchers"
+      },
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      }
+    },
+    {
+      "type": "npm",
+      "script": "watch-tests",
+      "problemMatcher": "$tsc-watch",
+      "isBackground": true,
+      "presentation": {
+        "reveal": "never",
+        "group": "watchers"
+      },
+      "group": "build"
+    },
+    {
+      "label": "tasks: watch-tests",
+      "dependsOn": ["npm: watch", "npm: watch-tests"],
+      "problemMatcher": []
+    }
+  ]
+}

.vscodeignore

@@ -0,0 +1,13 @@
+.vscode/**
+.vscode-test/**
+out/**
+node_modules/**
+src/**
+.gitignore
+.yarnrc
+webpack.config.js
+vsc-extension-quickstart.md
+**/tsconfig.json
+**/.eslintrc.json
+**/*.map
+**/*.ts

CHANGELOG.md

@@ -0,0 +1,9 @@
+# Change Log
+
+All notable changes to the "vscode-arduino-api" extension will be documented in this file.
+
+Check [Keep a Changelog](http://keepachangelog.com/) for recommendations on how to structure this file.
+
+## [Unreleased]
+
+- Initial release

README.md

@@ -0,0 +1,69 @@
+# vscode-arduino-api
+
+Arduino API for [Arduino IDE](https://github.com/arduino/arduino-ide) external tools developers using VS Code extensions.
+
+This VS Code extensions does not provide any functionality, but a bridge between the Arduino IDE and external tools implemented as a VS Code extension. Please reference [arduino/arduino-ide#58](https://github.com/arduino/arduino-ide/issues/58) why this VSIX has been created. This extension has nothing to do with the [Visual Studio Code extension for Arduino](https://marketplace.visualstudio.com/items?itemName=vsciot-vscode.vscode-arduino). This extension does not work in VS Code.
+
+## Features
+
+Exposes the Arduino context for VS Code extensions:
+
+| Name           | Description                                                                                                                                                                                                                                                                                                                         | Type                                                                      | Note        |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ----------- |
+| `sketchPath`   | Absolute filesystem path of the sketch folder.                                                                                                                                                                                                                                                                                      | `string`                                                                  |
+| `buildPath`    | The absolute filesystem path to the build folder of the sketch. When the `sketchPath` is available but the sketch has not been verified (compiled), the `buildPath` can be `undefined`.                                                                                                                                             | `string`                                                                  | ⚠️ `@alpha` |
+| `fqbn`         | The Fully Qualified Board Name (FQBN) of the currently selected board in the Arduino IDE.                                                                                                                                                                                                                                           | `string`                                                                  |
+| `boardDetails` | Lightweight representation of the board's detail. This information is [provided by the Arduino CLI](https://arduino.github.io/arduino-cli/latest/rpc/commands/#cc.arduino.cli.commands.v1.BoardDetailsResponse) for the currently selected board. It can be `undefined` if the `fqbn` is defined but the platform is not installed. | `BoardDetails`                                                            | ⚠️ `@alpha` |
+| `port`         | The currently selected port in the Arduino IDE.                                                                                                                                                                                                                                                                                     | [`Port`](https://arduino.github.io/arduino-cli/latest/rpc/commands/#port) |
+| `userDirPath`  | Filesystem path to the [`directories.user`](https://arduino.github.io/arduino-cli/latest/configuration/#configuration-keys) location. This is the sketchbook path.                                                                                                                                                                  | `string`                                                                  |
+| `dataDirPath`  | Filesystem path to the [`directories.data`](https://arduino.github.io/arduino-cli/latest/configuration/#configuration-keys) location                                                                                                                                                                                                | `string`                                                                  |
+
+## How to Use
+
+If you're developing an external tool for the Arduino IDE, this extension will be available at runtime from the IDE.
+
+If you want to use the Arduino APIs, you have to do the followings:
+
+1.  Install the [Arduino API types](https://www.npmjs.com/package/vscode-arduino-api) from `npm`:
+    ```shell
+    npm i -S vscode-arduino-api
+    ```
+1.  Add this VSIX as an `extensionDependencies` in your `package.json`:
+
+    ```jsonc
+    {
+      "extensionDependencies": [
+        "dankeboy36.vscode-arduino-api",
+        // other dependencies
+      ],
+    }
+    ```
+1.  Consume the `ArduinoContext` extension API in your VS Code extension:
+
+    ```ts
+    import * as vscode from 'vscode';
+    import type { ArduinoContext } from 'vscode-arduino-api';
+
+    function activate(context: vscode.ExtensionContext) {
+      const arduinoContext: ArduinoContext = vscode.extensions.getExtension(
+        'dankeboy36.vscode-arduino-api'
+      )?.exports;
+      if (!arduinoContext) {
+        // failed to load the Arduino API
+        return;
+      }
+      // use the Arduino API in your VS Code extension...
+    }
+    ```
+
+## FAQs
+
+---
+
+- Q: Why do I have to install `vscode-arduino-api` from `npm`.
+- A: `vscode-arduino-api` only contains types for the API. The actual code wil be part of the VS Code extension.
+
+---
+
+- Q: I cannot find the `dankeboy36.vscode-arduino-api` extension in the [VS Code Marketplace](https://marketplace.visualstudio.com/vscode).
+- A: Correct. This solution targets the [Arduino IDE](https://github.com/arduino/arduino-ide). I will publish the VSIX later, when it works in VS Code. By the way, the VSIX is signed with a verified published.