dsh-remote 0.8.49 → 0.8.51

package/lib/sshconfig.js

@@ -28,7 +28,7 @@
 // The module is pure (I/O is injectable), so it is unit-testable without a real
 // home directory — see test/sshconfig.test.js.
 
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { existsSync, readFileSync, readdirSync, statSync, mkdirSync, writeFileSync, chmodSync } from 'node:fs'
 import { homedir } from 'node:os'
 import path from 'node:path'
 
@@ -362,23 +362,14 @@ export function parseProxyJump(value) {
 }
 
 /**
- * Connect target for an ssh-config alias: the shape the plugin's pool expects.
+ * Shared proxy/warning shaping for alias and literal resolutions (issue #50).
  *
  * `ProxyJump` maps onto the plugin's single jump host. A multi-hop chain cannot
  * be represented by one `proxy`, so the FIRST hop is used and `warnings` says so
  * — silently connecting through the wrong path would be worse. `ProxyCommand`
  * (an arbitrary local command) is reported but never executed.
- *
- * @param {string} alias
- * @param {object} [opts]
- * @param {string} [opts.text] - config text (else the real file is read).
- * @param {string} [opts.file]
- * @param {object} [opts.io]
- * @returns {{alias: string, matched: boolean, host: string, port: number, username: string, privateKeyPath: string, proxy: object|undefined, proxyJump: string, warnings: string[]}}
  */
-export function sshAliasTarget(alias, opts = {}) {
-  const text = opts.text !== undefined ? String(opts.text) : loadSshConfigText(opts.file || sshConfigPath(), opts.io || {})
-  const resolved = resolveSshHost(alias, text)
+function targetFromResolved(resolved, text, { defaultPort }) {
   const warnings = []
   let proxy
   const hops = parseProxyJump(resolved.proxyJump)
@@ -400,10 +391,10 @@ export function sshAliasTarget(alias, opts = {}) {
     warnings.push('ProxyCommand is not supported by dsh-remote (no jump host was applied).')
   }
   return {
-    alias,
+    alias: resolved.alias,
     matched: resolved.matched,
-    host: resolved.hostName || alias,
-    port: resolved.port || 22,
+    host: resolved.hostName || resolved.alias,
+    port: resolved.port || defaultPort,
     username: resolved.user || '',
     privateKeyPath: resolved.identityFile ? expandHome(resolved.identityFile) : '',
     proxy,
@@ -412,6 +403,72 @@ export function sshAliasTarget(alias, opts = {}) {
   }
 }
 
+/**
+ * Connect target for an ssh-config alias: the shape the plugin's pool expects.
+ *
+ * @param {string} alias
+ * @param {object} [opts]
+ * @param {string} [opts.text] - config text (else the real file is read).
+ * @param {string} [opts.file]
+ * @param {object} [opts.io]
+ * @returns {{alias: string, matched: boolean, host: string, port: number, username: string, privateKeyPath: string, proxy: object|undefined, proxyJump: string, warnings: string[]}}
+ */
+export function sshAliasTarget(alias, opts = {}) {
+  const text = opts.text !== undefined ? String(opts.text) : loadSshConfigText(opts.file || sshConfigPath(), opts.io || {})
+  return targetFromResolved(resolveSshHost(alias, text), text, { defaultPort: 22 })
+}
+
+/**
+ * Effective connect identity for a LITERAL machine (issue #50).
+ *
+ * A machine saved with literal host/user/port/key holds a COPY of what may also
+ * be written in ~/.ssh/config, and the copy goes stale the moment the file is
+ * edited. The file is the single source for any host it NAMES: when a Host
+ * block matches the machine's literal host — with at least one positive pattern
+ * that is not the bare `*` — the resolved values win per field and the record
+ * fills the gaps. A bare `Host *` block deliberately does NOT name a host:
+ * treating universal defaults as an override would hijack every saved machine
+ * at once. Group patterns (`*.corp`, `web-?`) DO name hosts, exactly as ssh
+ * itself applies them to a literal dial.
+ *
+ * `port` is 0 (not 22) when the file says nothing, so the caller falls back to
+ * the record instead of the default.
+ *
+ * @param {object} machine - a registry record with a literal `host`.
+ * @param {{text?: string, file?: string, io?: object}} [opts]
+ * @returns {null | {alias: string, matched: true, host: string, port: number, username: string, privateKeyPath: string, proxy: object|undefined, proxyJump: string, warnings: string[]}}
+ *   null when no Host block names the machine's host.
+ */
+export function resolveLiteralSshConfig(machine, opts = {}) {
+  if (!machine || machine.useSshConfig) return null
+  const name = String(machine.host || '').trim()
+  if (!name) return null
+  const text = opts.text !== undefined ? String(opts.text) : loadSshConfigText(opts.file || sshConfigPath(), opts.io || {})
+  const resolved = {
+    alias: name, matched: false, hostName: '', user: '', port: 0,
+    identityFile: '', proxyJump: '', proxyCommand: '', identitiesOnly: '',
+  }
+  for (const block of parseHostBlocks(text)) {
+    if (!hostBlockMatches(block.patterns, name)) continue
+    const positive = block.patterns.filter((p) => !p.startsWith('!'))
+    // A block whose only positive pattern is the bare `*` is a defaults block,
+    // not a block that names this host.
+    if (positive.length && positive.every((p) => p === '*')) continue
+    resolved.matched = true
+    for (const [key, value] of Object.entries(block.values)) {
+      if (key === 'hostname') { if (!resolved.hostName) resolved.hostName = String(value) }
+      else if (key === 'user') { if (!resolved.user) resolved.user = String(value) }
+      else if (key === 'port') { if (!resolved.port) resolved.port = Number(value) || 0 }
+      else if (key === 'identityfile') { if (!resolved.identityFile) resolved.identityFile = String(value) }
+      else if (key === 'proxyjump') { if (!resolved.proxyJump) resolved.proxyJump = String(value) }
+      else if (key === 'proxycommand') { if (!resolved.proxyCommand) resolved.proxyCommand = String(value) }
+      else if (key === 'identitiesonly') { if (!resolved.identitiesOnly) resolved.identitiesOnly = String(value) }
+    }
+  }
+  if (!resolved.matched) return null
+  return targetFromResolved(resolved, text, { defaultPort: 0 })
+}
+
 /**
  * Effective connect identity for a saved machine.
  *
@@ -452,3 +509,187 @@ export function resolveMachineSshConfig(machine, opts = {}) {
 function compareText(left, right) {
   return left < right ? -1 : left > right ? 1 : 0
 }
+
+// ── Writing: the managed Host block (issue #50) ─────────────────────────────
+//
+// The four connection fields (host/user/port/key) have ONE home: ~/.ssh/config.
+// When the plugin saves a literal machine it upserts a Host block tagged with
+// MANAGED_MARK, so the file and the registry can never drift — and so the
+// plugin can tell ITS OWN block apart from one the user wrote. Two rules keep
+// the file safe:
+//   • a Host block without the marker is never touched — a same-named user
+//     block is a CONFLICT, reported to the caller instead of overwritten;
+//   • inside a managed block, lines the plugin does not own (a user-added
+//     `ForwardAgent yes`, a comment) survive an update — only the four known
+//     parameters are rewritten.
+
+/** Marker comment that tags a Host block as owned by dsh-remote. */
+export const MANAGED_MARK = '# dsh-remote: managed'
+
+/** Parameters the managed block rewrites (lowercase). */
+const MANAGED_PARAMS = new Set(['hostname', 'user', 'port', 'identityfile'])
+
+/** Read the RAW config text — no Include expansion (a write targets ONE file). */
+export function readRawSshConfig(filePath = sshConfigPath()) {
+  try {
+    const text = readFileSync(filePath, 'utf8')
+    return typeof text === 'string' ? text : ''
+  } catch {
+    return ''
+  }
+}
+
+/** Quote one value for a config line when it contains whitespace. */
+function quoteCfg(value) {
+  const s = String(value)
+  return /[\s#]/.test(s) ? `"${s.replace(/"/g, '\\"')}"` : s
+}
+
+/** The values a managed block must carry for these fields ('' = omit). */
+function desiredValues(fields) {
+  const alias = String(fields.alias || '').trim()
+  const hostName = String(fields.hostName || '').trim()
+  const port = Number(fields.port) || 0
+  return {
+    hostname: hostName && hostName !== alias ? hostName : '',
+    user: String(fields.user || '').trim(),
+    port: port && port !== 22 ? port : '',
+    identityfile: String(fields.identityFile || '').trim(),
+  }
+}
+
+/** Render the owned body lines of a managed block. */
+function desiredLines(fields) {
+  const want = desiredValues(fields)
+  const out = []
+  if (want.hostname) out.push(`  HostName ${quoteCfg(want.hostname)}`)
+  if (want.user) out.push(`  User ${quoteCfg(want.user)}`)
+  if (want.port) out.push(`  Port ${want.port}`)
+  if (want.identityfile) out.push(`  IdentityFile ${quoteCfg(want.identityfile)}`)
+  return out
+}
+
+/**
+ * Locate the MANAGED Host block for `alias` in raw config lines.
+ * The marker must be the nearest non-blank line above the Host line; a block
+ * that names the alias without the marker is the user's, not ours.
+ */
+function locateManagedBlock(lines, alias) {
+  const wanted = alias.toLowerCase()
+  for (let i = 0; i < lines.length; i += 1) {
+    const m = lines[i].match(/^\s*host\s+(.+?)\s*$/i)
+    if (!m) continue
+    const names = splitValue(m[1]).map((p) => p.toLowerCase())
+    if (!names.includes(wanted)) continue
+    let j = i - 1
+    while (j >= 0 && lines[j].trim() === '') j -= 1
+    if (j < 0 || lines[j].trim().toLowerCase() !== MANAGED_MARK) continue
+    let end = lines.length
+    for (let k = i + 1; k < lines.length; k += 1) {
+      if (/^\s*(host|match)\s/i.test(lines[k])) { end = k; break }
+    }
+    return { markerLine: j, hostLine: i, end }
+  }
+  return null
+}
+
+/** Whether an UNMANAGED Host block names `alias` (exact token, case-insensitive). */
+function hasUnmanagedConflict(lines, alias) {
+  const wanted = alias.toLowerCase()
+  for (let i = 0; i < lines.length; i += 1) {
+    const m = lines[i].match(/^\s*host\s+(.+?)\s*$/i)
+    if (!m) continue
+    const names = splitValue(m[1]).map((p) => p.toLowerCase())
+    if (!names.includes(wanted)) continue
+    let j = i - 1
+    while (j >= 0 && lines[j].trim() === '') j -= 1
+    if (j >= 0 && lines[j].trim().toLowerCase() === MANAGED_MARK) continue // ours
+    return true
+  }
+  return false
+}
+
+/**
+ * Insert or refresh the managed Host block for a saved machine.
+ *
+ * @param {string} rawText - the RAW ~/.ssh/config text ('' when absent).
+ * @param {{alias: string, hostName?: string, user?: string, port?: number|string, identityFile?: string}} fields
+ * @returns {{status: 'appended'|'updated'|'unchanged'|'conflict'|'invalid', text: string}}
+ *   'conflict' — an unmanaged block already names the alias (text untouched);
+ *   'invalid' — the alias can never be a safe Host token (space/wildcard).
+ */
+export function upsertManagedHostBlock(rawText, fields) {
+  const text = String(rawText || '')
+  const alias = String((fields && fields.alias) || '').trim()
+  if (!alias || /[\s*?!,]/.test(alias)) return { status: 'invalid', text }
+  const lines = text.split('\n')
+  if (hasUnmanagedConflict(lines, alias)) return { status: 'conflict', text }
+
+  const want = desiredValues({ ...fields, alias })
+  const found = locateManagedBlock(lines, alias)
+  if (!found) {
+    const block = [MANAGED_MARK, `Host ${alias}`, ...desiredLines({ ...fields, alias })]
+    const trimmedEnd = text.replace(/\s+$/, '')
+    const prefix = trimmedEnd === '' ? '' : trimmedEnd + '\n\n'
+    return { status: 'appended', text: prefix + block.join('\n') + '\n' }
+  }
+
+  // Compare what the block HAS with what it MUST have; a rewrite that changes
+  // nothing would only cost the file's mtime.
+  const current = parseHostBlocks(lines.slice(found.hostLine, found.end).join('\n'))[0]
+  const cur = (current && current.values) || {}
+  const same = ['hostname', 'user', 'port', 'identityfile']
+    .every((k) => String(cur[k] ?? '') === String(want[k] ?? ''))
+  if (same) return { status: 'unchanged', text }
+
+  // Rewrite only the four owned parameters; user lines inside OUR block stay.
+  const body = lines.slice(found.hostLine + 1, found.end)
+  const kept = body.filter((l) => {
+    const m = l.match(/^\s*(\S+)\s/)
+    return !m || !MANAGED_PARAMS.has(m[1].toLowerCase())
+  })
+  const next = [
+    ...lines.slice(0, found.hostLine + 1),
+    ...desiredLines({ ...fields, alias }),
+    ...kept,
+    ...lines.slice(found.end),
+  ]
+  return { status: 'updated', text: next.join('\n') }
+}
+
+/**
+ * Remove the managed block for `alias` (used when a machine is RENAMED away:
+ * the old block is the plugin's own artifact of that edit). Deleting a machine
+ * deliberately does NOT call this — the Host block is the user's ssh access,
+ * not plugin state. Unmanaged blocks are never removed.
+ *
+ * @returns {{status: 'removed'|'absent', text: string}}
+ */
+export function removeManagedHostBlock(rawText, alias) {
+  const text = String(rawText || '')
+  const name = String(alias || '').trim()
+  if (!name) return { status: 'absent', text }
+  const lines = text.split('\n')
+  const found = locateManagedBlock(lines, name)
+  if (!found) return { status: 'absent', text }
+  let start = found.markerLine
+  while (start > 0 && lines[start - 1].trim() === '') start -= 1
+  const next = [...lines.slice(0, start), ...lines.slice(found.end)]
+  return { status: 'removed', text: next.join('\n') }
+}
+
+/**
+ * Persist a config text, creating ~/.ssh first. Permissions follow OpenSSH's
+ * expectations on POSIX (dir 0700, file 0600) and are a no-op elsewhere.
+ */
+export function writeSshConfig(text, filePath = sshConfigPath(), io = {}) {
+  const mkdir = io.mkdir || ((p) => mkdirSync(p, { recursive: true }))
+  const write = io.write || ((p, data) => writeFileSync(p, data, 'utf8'))
+  const chmod = io.chmod || ((p, mode) => { try { chmodSync(p, mode) } catch { /* no modes here */ } })
+  mkdir(path.dirname(filePath))
+  write(filePath, String(text))
+  if (process.platform !== 'win32') {
+    chmod(path.dirname(filePath), 0o700)
+    chmod(filePath, 0o600)
+  }
+}

package/node_modules/buildcheck/.eslintrc.js

@@ -0,0 +1,5 @@
+'use strict';
+
+module.exports = {
+  extends: '@mscdex/eslint-config',
+};

package/node_modules/buildcheck/.github/workflows/ci.yml

@@ -0,0 +1,88 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [ master ]
+
+jobs:
+  tests-linux:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [10.x, 12.x, 14.x, 16.x, 18.x, 20.x, 22.x, 24.x]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: Check Node.js version
+        run: node -pe process.versions
+      - name: Install module
+        run: npm install
+      - name: Run tests
+        run: npm test
+  tests-macos-intel:
+    runs-on: macos-15-intel
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [10.x, 12.x, 14.x, 16.x, 18.x, 20.x, 22.x, 24.x]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: Check Node.js version
+        run: node -pe process.versions
+      - name: Install module
+        run: npm install
+      - name: Run tests
+        run: npm test
+  tests-macos-arm:
+    runs-on: macos-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [16.x, 18.x, 20.x, 22.x, 24.x]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: Check Node.js version
+        run: node -pe process.versions
+      - name: Install module
+        run: npm install
+      - name: Run tests
+        run: npm test
+  tests-windows-2022:
+    runs-on: windows-2022
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [24.x]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: Check Node.js version
+        run: node -pe process.versions
+      - name: Install module
+        run: npm install
+      - name: Run tests
+        run: npm test

package/node_modules/buildcheck/.github/workflows/lint.yml

@@ -0,0 +1,27 @@
+name: lint
+
+on:
+  pull_request:
+  push:
+    branches: [ master ]
+
+env:
+  NODE_VERSION: 22.x
+
+jobs:
+  lint-js:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Use Node.js ${{ env.NODE_VERSION }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+      - name: Check Node.js version
+        run: node -pe process.versions
+      - name: Install ESLint + ESLint configs/plugins
+        run: npm install --only=dev
+      - name: Lint files
+        run: npm run lint

package/node_modules/buildcheck/.npmignore

@@ -0,0 +1,3 @@
+.eslintcache
+**/node_modules/**
+/package-lock.json

package/node_modules/buildcheck/LICENSE

@@ -0,0 +1,19 @@
+Copyright Brian White. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.

package/node_modules/buildcheck/README.md

@@ -0,0 +1,106 @@
+# Description
+
+Build environment checking for [node.js](http://nodejs.org/).
+
+This allows for autoconf-like functionality for node addons/build scripts.
+
+**Note:** Obsolete and/or exotic build environments or platforms not supported
+by node.js are not supported.
+
+## Requirements
+
+* [node.js](http://nodejs.org/) -- v10.0.0 or newer
+* Supported compilers:
+  * gcc
+  * clang
+  * MSVC 2013+ and Windows SDK 8.1+
+
+## Installation
+
+    npm install buildcheck
+
+## Examples
+
+### Check if a C function exists
+
+```js
+'use strict';
+
+const BuildEnvironment = require('buildcheck');
+
+const buildEnv = new BuildEnvironment();
+
+console.log(buildEnv.checkFunction('c', 'preadv2'));
+```
+
+### Check if a C header is usable
+
+```js
+'use strict';
+
+const BuildEnvironment = require('buildcheck');
+
+const buildEnv = new BuildEnvironment();
+
+console.log(buildEnv.checkHeader('c', 'linux/io_uring.h'));
+```
+
+### Try to compile some C code
+
+```js
+'use strict';
+
+const BuildEnvironment = require('buildcheck');
+
+const buildEnv = new BuildEnvironment();
+
+// Should be a successful compile
+console.log(buildEnv.tryCompile('c', 'int main() { return 0; }'));
+
+// Should be a failed compile
+console.log(buildEnv.tryCompile('c', 'int main() { return z; }'));
+```
+
+## API
+
+### Exports
+
+The exported value is `BuildEnvironment`, the main class for dealing with a build environment.
+
+### BuildEnvironment
+
+#### Methods
+
+* **(constructor)**([< _object_ >config]) - Creates and returns a new BuildEnvironment instance. `config` may contain:
+
+  * **compilerC** - _string_ - C compiler command to use. *Note: this is ignored on Windows.* **Default:** `process.env.CC` or `'cc'`
+
+  * **compilerCXX** - _string_ - C++ compiler command to use. *Note: this is ignored on Windows.* **Default:** `process.env.CXX` or `'c++'`
+
+  * **msvs_version** - _mixed_ - A string or number containing the year of the Visual Studio compiler to use. *Note: this is for Windows only.* **Default:** newest version installed
+
+* **checkDeclared**(< _string_ >lang, < _string_ >symbolName[, < _object_ >options]) - _boolean_ - Checks if a symbol `symbolName` is declared where `lang` is either `'c'` or `'c++'`. Returns `true` if symbol exists, `false` otherwise. `options` may contain:
+
+  * **headers** - _array_ - A list of headers to try when checking if the symbol is declared. `checkFunction()` will always first try without a library. If not supplied, a default list of common (platform-specific) headers will be used.
+
+  * **searchLibs** - _array_ - A list of library names (without the `'-l'` prefix) to try when checking if the symbol is declared. `checkDeclared()` will always first try without a library.
+
+* **checkFunction**(< _string_ >lang, < _string_ >functionName[, < _object_ >options]) - _boolean_ - Checks if a function `functionName` exists and is linkable where `lang` is either `'c'` or `'c++'`. Returns `true` if function exists, `false` otherwise. `options` may contain:
+
+  * **searchLibs** - _array_ - A list of library names (without the `'-l'` prefix) to try when checking for this function. `checkFunction()` will always first try without a library.
+
+* **checkFeature**(< _string_ >featureName) - _mixed_ - Executes a special test for a "feature" and returns the result. Supported values for `featureName`:
+
+  * `'strerror_r'` - Returns an object containing:
+
+    * `declared` - _boolean_ - Whether `strerror_r()` is declared
+
+    * `returnsCharPtr` - _boolean_ - If `strerror_r()` is declared, whether it returns `char*` (a GNU extension) or not.
+
+* **checkHeader**(< _string_ >lang, < _string_ >headerName) - _boolean_ - Checks if the header `headerName` exists and is usable where `lang` is either `'c'` or `'c++'`. Returns `true` if the header exists and is usable, `false` otherwise.
+
+* **defines**([< _string_ >lang[, < _boolean_ >rendered]]) - _array_ - Returns a list of features, functions, headers, and symbols known to be defined by this build environment instance. `lang` is either `'c'` or `'c++'` If `lang` is not set, defines for both `'c'` and `'c++'` will be returned. If `rendered` is `true` (defaults to `false`), autoconf-style defines (e.g. "HAVE_FOO=1") will be returned instead. Defines coming from features utilize base strings/names from autoconf for better compatibility.
+
+* **libs**([< _string_ >lang]) - _array_ - Returns a list of (`'-l'`-prefixed) libraries known to be required for features and functions defined by this build environment instance. `lang` is either `'c'` or `'c++'` If `lang` is not set, defines for both `'c'` and `'c++'` will be returned.
+
+* **tryCompile**(< _string_ >lang, < _string_ >code[, < _array_ >compilerParams]) - _mixed_ - Attempts to compile `code` where `lang` is either `'c'` or `'c++'`. `compilerParams` is an optional array of compiler/linker flags to include. Returns `true` on successful compilation, or an _Error_ instance with an `output` property containing the compiler error output.