bare-stow 0.1.9 → 0.3.0

package/README.md

@@ -1,8 +1,6 @@
 # bare-stow
 
-Module bundling and harness generation for Bare. Built on top of `bare-pack` (<https://github.com/holepunchto/bare-pack>), `bare-stow` produces a bundle for a target runtime together with a small harness that boots it from the host environment.
-
-A [CLI](#cli) is also included and provides support for stowing a module graph from the command line.
+Module bundling and harness generation for Bare. `bare-stow` packs a module graph into a bundle with <https://github.com/holepunchto/bare-pack> and generates a harness package that boots the bundle from a host application written in JavaScript, Kotlin, Python, or Swift.
 
 ```
 npm i [-g] bare-stow
@@ -10,7 +8,7 @@ npm i [-g] bare-stow
 
 ## Usage
 
-Given an entry module `core.js` that exports a `start` function receiving the IPC stream and an optional `ready` callback. The function may optionally return (or resolve to) a function that runs before the bundle exits:
+The entry module exports a `start()` function that receives the IPC stream and an optional `ready` callback. It may return a function to run before the bundle exits:
 
 ```js
 module.exports = async function start(ipc, ready) {
@@ -18,8 +16,7 @@ module.exports = async function start(ipc, ready) {
     // Handle messages from the host.
   })
 
-  // Optionally call `ready()` to signal readiness early. Otherwise it is
-  // signaled automatically when `start()` resolves.
+  // Signal readiness early. Otherwise, it's signaled when `start()` resolves.
   ready()
 
   return async function stop() {
@@ -28,155 +25,137 @@ module.exports = async function start(ipc, ready) {
 }
 ```
 
-The `ipc` argument is a duplex byte stream. Anything written to it is delivered to the host, and `'data'` events fire when the host writes back.
+If a `server` is requested, `start()` instead receives `{ rpc, ipc }`, with `rpc` bound to the IPC stream. Its handlers are registered in `start()`, before the bundle signals ready:
+
+```js
+module.exports = function start({ rpc }) {
+  rpc.respond(1, (req, data) => data)
+}
+```
 
-Stow it for the `bare-sidecar` target:
+Stow it for a target:
 
 ```js
 const stow = require('bare-stow')
 
-const entry = new URL('file:///app/core.js')
-const out = new URL('file:///app/out/index.js')
+const entry = 'file:///app/core.js'
+const out = 'file:///app/core-harness/'
 
 for await (const artifact of stow(entry, 'bare-sidecar', out)) {
   console.log(artifact.url.href)
 }
 ```
 
-Or equivalently from the command line:
+Or from the command line:
 
 ```console
-$ bare-stow --target bare-sidecar --out ./out/index.js ./core.js
+$ bare-stow pack --target bare-sidecar --out ./core-harness ./core.js
 ```
 
-This writes the harness to `out` and the bundle alongside it. The harness can then be required from the host and booted with `start()`. The harness awaits the worker's `ready` signal before resolving, so by the time `start()` returns the bundle is up:
+This writes a package to `out` with the harness, the bundle, and a manifest declaring the dependencies of the harness. `stow()` yields each file once written, and the bundle along with its `base`, the directory that its modules are named relative to. It's the `base` option if given, and otherwise the closest directory containing every module. Add the package as a dependency of the host and boot the bundle with `start()`, which resolves once the bundle is ready:
 
 ```js
-const harness = require('/app/out/index.js')
+import * as harness from 'core-harness'
 
 const { ipc } = await harness.start()
 
 ipc.write(Buffer.from('hello from the host'))
 
-ipc.on('exit', (code) => {
-  console.log('bundle exited with', code)
-})
-
-// Request a graceful shutdown.
-ipc.destroy()
+// Request a graceful shutdown, which resolves with the exit code.
+const code = await ipc.terminate()
 ```
 
-The harness imports its runtime by name, `bare-stow/host` along with `bare-sidecar` or `bare-worker` depending on the target, so the package that the harness is written into must depend on both. Relying on another package to bring them in only works while a package manager happens to hoist them, and not at all under an isolated layout such as that of pnpm. `stow()` resolves every import of the harness from `out` before writing anything and throws if one of them can't be found.
+The bundle imports `bare-stow-runtime`, and the RPC library if a `server` is requested, so the package containing the entry must depend on them.
 
-For the `bare-sidecar` target, `start()` accepts the options of `bare-sidecar`. The sidecar inherits the standard streams of the host unless `stdio` says otherwise.
+`start()` accepts `timeout`, how long to wait in milliseconds for the bundle to signal ready, and `grace`, how long a terminating bundle gets to run `stop()` and exit before it's killed. `timeout` defaults to waiting indefinitely and `grace` to 5 seconds. On Windows, a sidecar is killed along with its host, so `stop()` only runs when the host terminates it.
 
-`start()` also accepts `timeout`, the number of milliseconds to wait for the worker to signal ready before rejecting and terminating it, and `grace`, the number of milliseconds a terminating worker gets to run `stop()` and exit before it is killed. `timeout` defaults to waiting indefinitely and `grace` to 5 seconds. The worker holds itself to the same `grace` whenever it shuts down, including when it receives `SIGTERM` or the host goes away without terminating it. On Windows, a sidecar is killed along with its host instead, so `stop()` only runs when the host terminates it.
+`stow()` and `link()` read the module graph from disk by default. To read it from elsewhere, such as modules that aren't written to disk, pass `readModule`, `listPrefix`, and `resolveModule`. Generated files are still written to disk. A `readModule` that changes the type of a module also passes `aliases`, as for <https://github.com/holepunchto/bare-pack>, such as `{ '.mjs': '.js' }` to have ES modules converted to CommonJS loaded as such. They're merged over the aliases that `bare-stow` uses for TypeScript.
 
-## Protocol
-
-The harness multiplexes a control channel and a user data channel over the underlying binary duplex stream. The `ipc` returned from `start()` is itself a duplex stream carrying the user data; control frames ride alongside it on the same handle. RPC libraries (such as `bare-rpc`) bind to `ipc` just like a raw stream.
-
-Control frames signal lifecycle events:
+## Targets
 
-| Direction      | Type        | Payload              |
-| :------------- | :---------- | :------------------- |
-| Worker -> Host | `ready`     | -                    |
-| Worker -> Host | `exit`      | `{ code }`           |
-| Worker -> Host | `error`     | `{ message, stack }` |
-| Host -> Worker | `terminate` | -                    |
+- `bare-sidecar` runs the bundle in a separate process using <https://github.com/holepunchto/bare-sidecar>, with the `javascript`, `python`, and `swift` languages on desktop. In JavaScript and Python, `start()` also accepts the options of `bare-sidecar`.
+- `bare-worker` runs the bundle in a thread of a Bare host using <https://github.com/holepunchto/bare-worker>, with the `javascript` language.
+- `bare-kit` runs the bundle in a worklet using <https://github.com/holepunchto/bare-kit>, with the `swift` language on macOS and iOS and the `kotlin` language on Android and the JVM. `start()` also accepts the options of the worklet and returns it alongside `ipc`, and on Android takes the `Context` first. In Kotlin, the worklet is closed once it exits, so it needs no closing of its own, and in Swift it's released with its last reference. Native addons are linked with <https://github.com/holepunchto/bare-link> and declared in the manifest, and assets are written next to the bundle. With the target option `linking` set to `'app'`, both are left to `link()` instead. On the JVM, addons and assets are written next to the bundle as files, which `start()` extracts along with the bundle to a temporary directory, so `linking` must be `'package'`.
 
-An incoming `error` frame destroys the local `ipc` with the carried error, surfacing it as a normal stream `error` event. Other control frames emit a regular event named after the type.
+## Linking
 
-The `ipc` handle exposes the lifecycle as events and methods on the same duplex:
+A target may leave addons and assets to the application, so that bundles sharing them don't each bring a copy. For `bare-kit`, stow each bundle with the target option `linking` set to `'app'`:
 
-- `ipc.ready`: A promise that resolves once the worker has signaled ready. Rejects if the worker errors before ready.
-- `ipc.on('exit', code)`: Emitted when the worker signals exit. `code` carries the exit code.
-- `ipc.on('error', err)`: Emitted when the worker reports a fault, when it exits without saying why, such as through `Bare.exit()`, a signal, or a crash, or when the underlying transport errors. Either way the `ipc` is destroyed. For a worker that exited without saying why, `err.exitCode` and `err.signalCode` carry the reason.
-- `ipc.on('close')`: Emitted when the underlying transport closes.
-- `ipc.destroy()`: Standard stream destroy. Sends a `terminate` control frame to the worker and waits for the underlying transport to close.
-- `ipc.terminate()`: Like `destroy()` but resolves with the worker's exit code.
+```console
+$ bare-stow pack --target bare-kit --target-option linking=app --language swift --out ./ios/Core ./core.js
+```
 
-The framing layer is also exported directly for embedders that bring their own transport:
+`link()` then links the addons and assets of all bundles once, into a package the application depends on:
 
 ```js
-const protocol = require('bare-stow/protocol')
-
-const ipc = protocol.attach(stream) // Any duplex byte stream
-ipc.write(Buffer.from('payload')) // User data
-ipc.send('ready') // Control frame
-ipc.on('exit', () => {
-  /* ... */
-})
+const entries = [new URL('file:///app/core.js'), new URL('file:///app/push.js')]
+const out = new URL('file:///app/ios/BareKitAddons/')
+
+for await (const artifact of stow.link(entries, 'bare-kit', out, { language: 'swift' })) {
+  console.log(artifact.url.href)
+}
 ```
 
-The host helper layers the lifecycle promise and `terminate` method on top of the protocol:
+The language lays out the package and the target adds what loads the addons. For `bare-kit`, that's `bare-kit-swift` or `bare-kit-kotlin`. The assets go in a folder named by `stow.resources`, listed in a file of the same name with the `.assets` extension, which a Swift application copies into its bundle. `link()` takes the same options as `stow()`, except `client` and `base`.
 
-```js
-const { wrap } = require('bare-stow/host')
+## Languages
+
+The harness is generated in one of these languages, selected with `language` and configured with `languageOptions`:
+
+- `javascript` writes an npm package. The `module` option is either `'esm'`, the default, or `'cjs'`.
+- `kotlin` writes a Gradle module. The `package` option names the package of the generated code and is required. The `platform` option is either `'android'`, the default, for an Android library module, or `'jvm'` for a Kotlin/JVM library module on Linux, macOS, and Windows. The dependencies are published to JitPack (<https://jitpack.io>), so add it to the repositories of the application.
+- `python` writes a Python package.
+- `swift` writes a Swift package.
+
+For example, with an RPC client and server:
 
-const ipc = wrap(stream) // Any duplex byte stream
-await ipc.ready
+```console
+$ bare-stow pack --target bare-sidecar --language python --client bare-rpc --server bare-rpc --out ./my-core ./core.js
 ```
 
-## Targets and RPC providers
+```python
+import asyncio
 
-The harness and RPC code generators are decoupled from the bundler: `target`, `client`, and `server` each accept a provider object directly, so generators can live outside `bare-stow`. Passing a name instead resolves it through `resolveTarget` / `resolveRPC`, which default to the built-in registries.
+import my_core
 
-Both kinds of provider return an ordered array of artifacts. An artifact is `{ extension?, source }`:
 
-```js
-artifacts = [
-  { source }, // The primary output.
-  { extension, source } // A companion, named after the primary plus this extension.
-]
-```
+async def main():
+    ipc, rpc = await my_core.start(
+        handlers=lambda router: router.on_request(2, lambda req: b"hello")
+    )
 
-A target provider describes the runtime profile it owns and generates the harness that boots the bundle from the host:
+    await rpc.request(1, b"ping")
+    await ipc.terminate()
 
-```js
-target = {
-  name, // The target's name, used in diagnostics.
-  linked, // Whether assets and addons are linked into the bundle.
-  offload, // Whether (and which) assets and addons are offloaded to a `<bundle>.d` directory next to the bundle.
-  format, // The bundle encoding: 'bundle', 'bundle.cjs', 'bundle.mjs', or 'bundle.json'.
-  encoding, // The string encoding for encoded formats, or null for raw bytes.
-  extension, // The bundle file extension, e.g. '.bundle'.
-  module, // Optional. Pins the harness module system to 'esm' or 'cjs'.
-  hosts, // The host triples the target supports.
-  generate({ bundleSpecifier, ipc, rpc, module, client }) {
-    // Return an array of harness artifacts.
-  }
-}
+
+asyncio.run(main())
 ```
 
-For a target, each artifact is a file. The first has no `extension` and is written to `out`; each remaining artifact is written next to `out` with its own `extension` substituted for the harness extension (e.g. `{ extension: '.d.ts' }` becomes `index.d.ts`). The built-in targets emit two artifacts: The harness and its TypeScript declaration.
+With an RPC client, `start()` takes the handlers for the requests and events of the bundle, so that they are registered before the bundle can send any.
 
-`generate()` receives `bundleSpecifier`, the relative specifier from the harness to the bundle artifact; `ipc`, the identifier the harness should bind the IPC stream to; `rpc`, the identifier the RPC client setup binds its instance to; `module`, the harness module system (`'esm'` or `'cjs'`) so the harness can emit the matching module and import forms; and `client`, the resolved RPC client (or `null` when no client is requested). When present, `client` is `{ source, type }`: `source` is the runtime setup to splice into the harness (referencing `ipc` and binding `rpc`), and `type` is the TypeScript type of the bound instance to splice into the declaration. The target owns `linked`, `offload`, `format`, `encoding`, and `extension`; they are not overridable through `opts`.
+## Protocol
 
-The harness `module` system is derived from the output path: `out` ending in `.mjs` is ESM and `.cjs` is CommonJS, while an ambiguous `.js` (or other) extension follows the `type` of the closest enclosing `package.json` (`"module"` is ESM, otherwise CommonJS). A target may set its own `module` to pin the harness to one system regardless of the output path.
+The harness and the bundle multiplex a control channel and the user data over a single duplex stream. The `ipc` returned from `start()` is a duplex stream of the user data, so RPC libraries such as `bare-rpc` bind to it like any other stream. Embedders bringing their own transport can use the protocol directly:
 
-An RPC provider generates the wiring that binds an RPC instance to the IPC stream, used on both the client (harness) and server (shim) side:
+- <https://github.com/holepunchto/bare-stow-protocol> implements the framing.
+- <https://github.com/holepunchto/bare-stow-host> implements the host side and documents `ipc`, with <https://github.com/holepunchto/bare-stow-host-kotlin>, <https://github.com/holepunchto/bare-stow-host-python>, and <https://github.com/holepunchto/bare-stow-host-swift> for the other languages.
+- <https://github.com/holepunchto/bare-stow-runtime> implements the bundle side.
 
-```js
-rpc = {
-  name, // The library's name, used in diagnostics.
-  generate({ ipc, rpc, module, role }) {
-    // Return an array of RPC artifacts.
-  }
-}
-```
+## Providers
 
-For an RPC provider, each artifact is a fragment contributed to the harness file with the matching extension. The artifact with no `extension` is the runtime setup (reading `ipc`, binding `rpc`); the `{ extension: '.d.ts' }` artifact is the TypeScript type of the bound instance. `generate()` receives `ipc`, the identifier of the IPC stream in scope; `rpc`, the identifier to bind the RPC instance to; `module`, the surrounding module system (`'esm'` or `'cjs'`) so the runtime fragment can emit the matching import form; and `role`, either `'client'` or `'server'`. The bundler owns the `ipc` and `rpc` binding names and threads them to both the target and the RPC provider so neither has to assume them. It renders the client in the harness `module` and the server as `'esm'` (the shim is always an ES module), splicing the runtime fragment and, for the client, the type fragment into the target's artifacts. The shim is not a typed, host-facing module, so the server's type fragment is unused.
+Languages, targets, and RPC libraries are providers that may live outside `bare-stow`. `stow()` and `link()` accept a provider object in place of a name, and names other than the built-in ones are resolved through `resolveLanguage`, `resolveTarget`, and `resolveRPC`. For example, <https://github.com/holepunchto/bare-stow-target-react-native> is a target for React Native. Targets and RPC libraries generate code for each language they list under `languages`, and providers without an entry for the language of the harness are rejected. Targets may also take options, given as `targetOptions`. The server side of an RPC library is always generated as JavaScript, as the bundle runs in Bare. See `index.d.ts` for the interfaces.
 
 ## CLI
 
-#### `bare-stow [flags] <entry>`
+#### `bare-stow pack [flags] <entry>`
 
-Stow the module graph rooted at `<entry>`, writing the harness and bundle to the path given by `--out`.
+Stow the module graph rooted at `<entry>` into the directory given by `--out`.
 
 ```console
---version|-v
 --target <name>
+--target-option <key=value>
+--language <name>
+--language-option <key=value>
 --client <name>
 --server <name>
 --base <path>
@@ -188,25 +167,27 @@ Stow the module graph rooted at `<entry>`, writing the harness and bundle to the
 --help|-h
 ```
 
-##### `--target <name>`
-
-The target runtime. Required. The built-in `bare-sidecar` and `bare-worker` are resolved directly; any other `<name>` is loaded from its `bare-stow-target-<name>` package, or from `<name>` itself as a full module specifier, resolved from the working directory.
-
-##### `--client <name>` and `--server <name>`
-
-The RPC library to wire into the harness (`--client`) or the bundle entry shim (`--server`). The built-in `bare-rpc` is resolved directly; any other `<name>` is loaded from its `bare-stow-rpc-<name>` package, or from `<name>` itself as a full module specifier, resolved from the working directory.
-
-##### `--builtins <path>` and `--imports <path>`
+#### `bare-stow link [flags] <entry...>`
 
-Paths to JavaScript or JSON files exporting a list of builtin module names and a map of global import overrides respectively. Forwarded to `bare-pack`.
+Link the addons and assets of the module graphs rooted at each `<entry>` into the package given by `--out`.
 
-##### `--defer <specifier>`
-
-A module specifier whose resolution should be deferred. May be passed multiple times.
+```console
+--target <name>
+--target-option <key=value>
+--language <name>
+--language-option <key=value>
+--server <name>
+--out|-o <path>
+--builtins <path>
+--imports <path>
+--defer <specifier>
+--host <name>
+--help|-h
+```
 
-##### `--host <name>`
+`--target`, `--language`, `--client`, and `--server` take a built-in name, the name of a `bare-stow-target-<name>`, `bare-stow-language-<name>`, or `bare-stow-rpc-<name>` package, or a module specifier, resolved from the working directory. `--target-option`, `--language-option`, `--defer`, and `--host` may be passed multiple times. `--host` must name hosts the target supports, and defaults to all of them.
 
-A host triple to build for. Must be a subset of the host triples supported by the target. May be passed multiple times. Defaults to all host triples supported by the target.
+`--builtins` and `--imports` are paths to JavaScript or JSON files exporting a list of builtin modules and a map of import overrides, which are forwarded to `bare-pack`.
 
 ## License
 

package/bin.js

@@ -1,79 +1,116 @@
 #!/usr/bin/env node
 const path = require('path')
 const { pathToFileURL } = require('url')
-const { command, flag, arg, summary } = require('paparam')
+const { command, flag, arg, rest, summary } = require('paparam')
 const pkg = require('./package')
 const stow = require('.')
 
-const cmd = command(
-  pkg.name,
-  summary(pkg.description),
+const flags = {
+  target: () =>
+    flag(
+      '--target <name>',
+      'The target runtime (bare-kit, bare-sidecar, bare-worker, or a bare-stow-target-<name> package)'
+    ),
+  targetOption: () => flag('--target-option <key=value>', 'An option for the target').multiple(),
+  language: () =>
+    flag(
+      '--language <name>',
+      'The language of the harness (javascript, kotlin, python, swift, or a bare-stow-language-<name> package; defaults to javascript)'
+    ),
+  languageOption: () =>
+    flag(
+      '--language-option <key=value>',
+      'An option for the language, such as module=cjs for javascript'
+    ).multiple(),
+  server: () =>
+    flag(
+      '--server <name>',
+      'The RPC server to include (bare-rpc, or a bare-stow-rpc-<name> package)'
+    ),
+  builtins: () => flag('--builtins <path>', 'A list of builtin modules'),
+  imports: () => flag('--imports <path>', 'A map of global import overrides'),
+  defer: () => flag('--defer <specifier>', 'A module specifier to defer resolution of').multiple(),
+  host: () =>
+    flag('--host <name>', 'A host triple to include (must be a subset of the target)').multiple()
+}
+
+const link = command(
+  'link',
+  summary('Link the addons and assets of the module graphs of an application'),
+  rest('<entry...>', 'The entry points of the module graphs'),
+  flags.target(),
+  flags.targetOption(),
+  flags.language(),
+  flags.languageOption(),
+  flags.server(),
+  flag('--out|-o <path>', 'The directory to write the package of linked addons and assets to'),
+  flags.builtins(),
+  flags.imports(),
+  flags.defer(),
+  flags.host(),
+  async (cmd) => {
+    const entries = cmd.rest || []
+    const { target, language, server, out, defer, host: hosts } = cmd.flags
+
+    if (!target) throw new Error('--target is required')
+    if (!out) throw new Error('--out is required')
+    if (entries.length === 0) throw new Error('<entry...> is required')
+
+    for await (const _ of stow.link(
+      entries.map((entry) => pathToFileURL(entry)),
+      target,
+      pathToFileURL(out),
+      {
+        ...common(cmd.flags),
+        language,
+        server,
+        hosts,
+        defer
+      }
+    )) {
+      //
+    }
+  }
+)
+
+const pack = command(
+  'pack',
+  summary('Stow a module graph as a bundle and the harness that boots it'),
   arg('<entry>', 'The entry point of the module graph'),
-  flag('--version|-v', 'Print the current version'),
-  flag(
-    '--target <name>',
-    'The target runtime (bare-sidecar, or a bare-stow-target-<name> package)'
-  ),
+  flags.target(),
+  flags.targetOption(),
+  flags.language(),
+  flags.languageOption(),
   flag(
     '--client <name>',
     'The RPC client to include (bare-rpc, or a bare-stow-rpc-<name> package)'
   ),
-  flag(
-    '--server <name>',
-    'The RPC server to include (bare-rpc, or a bare-stow-rpc-<name> package)'
-  ),
+  flags.server(),
   flag(
     '--base <path>',
     'The base path of the bundle (defaults to the closest directory containing every bundled module)'
   ),
-  flag('--out|-o <path>', 'The output path of the harness'),
-  flag('--builtins <path>', 'A list of builtin modules'),
-  flag('--imports <path>', 'A map of global import overrides'),
-  flag('--defer <specifier>', 'A module specifier to defer resolution of').multiple(),
-  flag('--host <name>', 'A host triple to include (must be a subset of the target)').multiple(),
+  flag('--out|-o <path>', 'The directory to write the harness package to'),
+  flags.builtins(),
+  flags.imports(),
+  flags.defer(),
+  flags.host(),
   async (cmd) => {
     const { entry } = cmd.args
-    let {
-      version,
-      target,
-      client,
-      server,
-      base,
-      out,
-      builtins,
-      imports,
-      defer,
-      host: hosts
-    } = cmd.flags
-
-    if (version) return console.log(`v${pkg.version}`)
+    let { target, language, client, server, base, out, defer, host: hosts } = cmd.flags
 
     if (!target) throw new Error('--target is required')
     if (!out) throw new Error('--out is required')
 
-    if (builtins) {
-      builtins = require(path.resolve(builtins))
-
-      if ('default' in builtins) builtins = builtins.default
-    }
-
-    if (imports) {
-      imports = require(path.resolve(imports))
-
-      if ('default' in imports) imports = imports.default
-    }
-
     if (base) base = pathToFileURL(path.resolve(base) + '/')
 
     for await (const _ of stow(pathToFileURL(entry), target, pathToFileURL(out), {
+      ...common(cmd.flags),
+      language,
       client,
       server,
       base,
       hosts,
-      resolveTarget,
-      resolveRPC,
-      builtins,
-      imports,
       defer
     })) {
       //
@@ -81,19 +118,59 @@ const cmd = command(
   }
 )
 
+// The options shared by pack and link.
+function common(flags) {
+  return {
+    languageOptions: keyValues('--language-option', flags.languageOption),
+    targetOptions: keyValues('--target-option', flags.targetOption),
+    builtins: load(flags.builtins),
+    imports: load(flags.imports),
+    resolveTarget,
+    resolveRPC,
+    resolveLanguage
+  }
+}
+
+function keyValues(name, options = []) {
+  const result = {}
+
+  for (const option of options) {
+    const i = option.indexOf('=')
+
+    if (i === -1) throw new Error(`${name} must be <key>=<value>, got '${option}'`)
+
+    result[option.slice(0, i)] = option.slice(i + 1)
+  }
+
+  return result
+}
+
+function load(file) {
+  if (!file) return undefined
+
+  const value = require(path.resolve(file))
+
+  return 'default' in value ? value.default : value
+}
+
 // Built-in names are resolved by bare-stow itself; any other name is loaded
-// from its `bare-stow-target-<name>` / `bare-stow-rpc-<name>` package, or as a
-// full module specifier, resolved from the working directory.
+// from its `bare-stow-target-<name>`, `bare-stow-rpc-<name>`, or
+// `bare-stow-language-<name>` package, or as a full module specifier, resolved
+// from the working directory.
 
 function resolveTarget(name) {
-  return load('bare-stow-target', name)
+  return resolveProvider('bare-stow-target', name)
 }
 
 function resolveRPC(name) {
-  return load('bare-stow-rpc', name)
+  return resolveProvider('bare-stow-rpc', name)
 }
 
-function load(prefix, name) {
+function resolveLanguage(name) {
+  return resolveProvider('bare-stow-language', name)
+}
+
+function resolveProvider(prefix, name) {
   for (const specifier of [`${prefix}-${name}`, name]) {
     try {
       return require(require.resolve(specifier, { paths: [process.cwd()] }))
@@ -105,4 +182,16 @@ function load(prefix, name) {
   throw new Error(`Cannot resolve '${name}'`)
 }
 
+const cmd = command(
+  pkg.name,
+  summary(pkg.description),
+  flag('--version|-v', 'Print the current version'),
+  pack,
+  link,
+  ({ flags }) => {
+    if (flags.version) console.log(`v${pkg.version}`)
+    else console.log(cmd.help())
+  }
+)
+
 cmd.parse()