@factoidal/core 0.7.1 → 0.10.0

package/bin/factoidal.mjs

@@ -24,10 +24,10 @@ import {
   runtime
 } from '../store-host/index.mjs'
 import { fileUrlToPath, joinPath } from '../store-host/paths.mjs'
-import { loadEngine } from './engine.mjs'
-import { sampleStoreFacts, sampleStorePath } from '../sample-store.mjs'
+import { hexOfBytes, loadEngine } from './engine.mjs'
 import { PackError, packSupported, verifyGeneration } from './pack.mjs'
 import { denoReexec, isStackOverflow, runPack } from './pack-host.mjs'
+import { SAMPLE_TURTLE, sampleStoreFacts } from '../sample-store.mjs'
 import {
   planQueryOnWorker, queryStoreOnWorker, workerRouteAvailable
 } from './store-worker-host.mjs'
@@ -91,7 +91,8 @@ function exit (code) {
   else process.exitCode = code
 }
 
-function out (line) { console.log(line) }
+let outSilenced = false
+function out (line) { if (!outSilenced) console.log(line) }
 function err (line) { console.error(line) }
 
 // ---------------------------------------------------------------- usage
@@ -102,13 +103,18 @@ usage: factoidal <command> [options]
 
 commands:
   version                     print the package and engine versions
-  sample-store                print the path of the bundled sample store
+  sample-store [DIR]          pack a small built-in store and print its path
   inspect  STORE              report what the activated manifest commits
   query    STORE [QUERY]      evaluate a SPARQL query against a store
   pack     INPUT OUTPUT       build one immutable generation from an RDF file
   activate STORE GENERATION   make one generation the activated generation
   update   STORE [UPDATE]     apply a SPARQL Update through the delta log
   compact  STORE GENERATION   fold the delta log into a new generation
+  serve    STORE              serve SPARQL 1.1 Protocol, Graph Store and
+                              Service Description over HTTP
+  lws-serve DIR               serve Linked Web Storage 1.0 over HTTP
+  solid-serve DIR             serve the Solid Protocol over HTTP
+  solid-client OP URL         run one Solid client operation
 
 global options:
   -h, --help                  print this text, or a command's own help
@@ -118,33 +124,30 @@ global options:
 exit codes:
   0 success   1 failure   2 usage error   3 not yet wired (${ISSUE})
 
-STORE is a collection root: the directory that holds CURRENT. This package
-carries one, so the first query needs no other download:
+STORE is a collection root: the directory that holds CURRENT. Make one from
+an RDF file with pack and activate, or try a small built-in one:
 
   factoidal query "$(factoidal sample-store)" 'SELECT * WHERE { ?s ?p ?o } LIMIT 5'`
 
 const COMMAND_USAGE = {
-  version: `factoidal version - print the package and engine versions
+  'sample-store': `factoidal sample-store - pack a small built-in store, print its path
 
-usage: factoidal version [--json]
+usage: factoidal sample-store [DIR] [--json]
 
-Prints the npm package version, the Lean engine's WebAssembly digest as
-recorded by its build, and which host-I/O implementation is loaded.`,
+Packs the few triples held in sample-store.mjs (no data file ships) into a
+store under DIR, or under the OS temporary directory, activates it, and
+prints the collection root. A DIR that already holds CURRENT is reused.
 
-  'sample-store': `factoidal sample-store - print the bundled store's path
+  factoidal query "$(factoidal sample-store)" \\
+    'SELECT ?c ?l WHERE { ?c <http://www.w3.org/2004/02/skos/core#prefLabel> ?l }'`,
 
-usage: factoidal sample-store [--json]
+  version: `factoidal version - print the package and engine versions
 
-Prints the collection root of the Shardborough store this package
-carries, so a fresh install can query something at once:
+usage: factoidal version [--json]
 
-  factoidal inspect "$(factoidal sample-store)"
-  factoidal query "$(factoidal sample-store)" \\
-    'SELECT (COUNT(*) AS ?n) WHERE { ?s ?p ?o }'
+Prints the npm package version, the Lean engine's WebAssembly digest as
+recorded by its build, and which host-I/O implementation is loaded.`,
 
-The store holds five IPTC NewsCodes vocabularies (CC BY 4.0; see NOTICE)
-packed into IBK3 predicate blocks. --json adds what was recorded when it
-was packed.`,
 
   inspect: `factoidal inspect - report what a store's manifest commits
 
@@ -200,14 +203,16 @@ every later query from what it retained.
 
 formats:
   table    a human display of the engine's SPARQL Query Results JSON;
-           ASK prints true or false, CONSTRUCT prints its N-Triples
+           ASK prints true or false, CONSTRUCT and DESCRIBE print their
+           N-Triples
   json     SELECT prints the engine's SPARQL 1.1 Query Results JSON
-           document; ASK and CONSTRUCT print the operation's envelope,
-           because the operation answers those two with a boolean and a
-           serialized graph rather than with a results document
-  nquads   CONSTRUCT only: the graph the engine serialized
-  turtle   CONSTRUCT only: that graph through the engine's own Turtle
-           writer, which flattens named graphs into the default graph
+           document; ASK, CONSTRUCT and DESCRIBE print the operation's
+           envelope, because the operation answers those with a boolean
+           or a serialized graph rather than with a results document
+  nquads   CONSTRUCT and DESCRIBE only: the graph the engine serialized
+  turtle   CONSTRUCT and DESCRIBE only: that graph through the engine's
+           own Turtle writer, which flattens named graphs into the default
+           graph
 
 not available, and why:
   --base IRI         the store query operation takes no base argument;
@@ -215,8 +220,6 @@ not available, and why:
   xml, csv, tsv      the engine has no operation that writes the SPARQL
                      Results XML, CSV or TSV documents, and writing one
                      here would be a second serializer (iron rule 7)
-  DESCRIBE           the engine answers "DESCRIBE is not supported by the
-                     npm entry yet"
 
 A store carrying a non-empty delta log is not served by this path: the
 operation reads the manifest's committed artifacts only. Use the native
@@ -279,7 +282,137 @@ compacted epoch. It does not activate unless --activate is given.
 
 options:
   --activate         activate the new generation when it verifies
-  --json             emit one JSON object`
+  --json             emit one JSON object`,
+
+  serve: `factoidal serve - a SPARQL 1.1 endpoint over an activated store
+
+usage: factoidal serve STORE [--port N] [--host ADDRESS] [options]
+       factoidal serve --file DATA /DATASET [--port N] [options]
+       factoidal serve --tdb2 DIR /DATASET [--port N] [options]
+
+The second form matches fuseki-server --file DATA /DATASET: DATA is packed
+into a temporary collection (layout ibk5 unless --layout is given), served
+at /DATASET/sparql (also /DATASET/query and /DATASET/update) and
+/DATASET/data (also /DATASET/get, read only). Updates are lost on exit.
+
+The third form matches fuseki-server --loc DIR /DATASET for an Apache Jena
+TDB2 database: DIR is read in place, read only. SPARQL query and Graph Store
+GET work; an update or a Graph Store write answers 501 with a message. The
+current Data-NNNN generation is served; a database whose journal.jrnl is not
+empty (Jena has not replayed it) is refused. The Lean decoder reads the
+indexes and node table (formal/lean4/L4Factoidal/Tdb2/Read.lean); every
+quad is held in memory while the server runs.
+
+Serves the activated generation of STORE, with its delta log, over HTTP:
+
+  GET/POST /sparql   SPARQL 1.1 Protocol query and update
+                     (GET /sparql with no query string: the SPARQL 1.1
+                     Service Description of the endpoint)
+  /data, /data/...   SPARQL 1.1 Graph Store HTTP Protocol (?default,
+                     ?graph=IRI, or a path under /data naming the graph)
+
+options:
+  --port N           the port to bind; 0 takes an ephemeral one (default 3030)
+  --host ADDRESS     the address to bind (default 127.0.0.1)
+  --query-path PATH  the query and update endpoint (default /sparql)
+  --gsp-path PATH    the Graph Store endpoint (default /data)
+  --file DATA        pack and serve an RDF file (see the second form)
+  --tdb2 DIR         serve a Jena TDB2 database read only (third form)
+  --layout LAYOUT    with --file: ibk3, ibk4 or ibk5 (default ibk5)
+  --no-worker        serve on this thread instead of a worker thread with a
+                     raised call stack (large collections need the worker)
+  --quiet            print the origin only
+
+An update, or a Graph Store PUT, POST or DELETE, is appended to the
+activated generation's delta log as one batch before the response is sent,
+and is visible to the next request. An IBK3 (triples) generation accepts
+changes to the default graph only, because its delta log is replayed and
+compacted for that graph only; a change to a named graph answers 501. A
+quad generation (ibk4, ibk5) accepts every graph. Fold the log into a new
+generation with l4block-shard-compact, activate it, and restart the server.
+
+The server makes no protocol decision: the request framing, routing,
+status codes, content negotiation, evaluation and the delta-log batch are
+decided by formal/lean4/L4Factoidal/HTTP/Wire.lean and
+formal/lean4/L4Factoidal/SPARQL/StoreEndpoint.lean through the
+storeServe operations. A WebAssembly module built before those operations
+landed makes this command exit 3 and say so.
+
+Specifications: https://www.w3.org/TR/sparql11-protocol/
+https://www.w3.org/TR/sparql11-http-rdf-update/
+https://www.w3.org/TR/sparql11-service-description/`,
+
+  'lws-serve': `factoidal lws-serve - serve Linked Web Storage 1.0 over HTTP
+
+usage: factoidal lws-serve DIR [--port N] [--host ADDRESS]
+
+Starts a Node HTTP server that answers every request through the engine's
+lwsStep operation.
+
+DIR names the storage directory. The first slice keeps the resource tree
+in the engine handle, so DIR is not read or written yet; it is the place
+a later snapshot goes (design record, section 2).
+
+  --port N        the port to bind; 0 takes an ephemeral one (default 3000)
+  --host ADDRESS  the address to bind (default 127.0.0.1)
+  --base IRI      the absolute IRI the storage root maps to
+                  (default: the bound origin)
+
+The server makes no protocol decision: status codes, Link relations,
+Last-Modified and the PATCH blank-node refusal are all answered by
+formal/lean4/L4Factoidal/LWS/. A WebAssembly module built before those
+operations landed makes this command exit 3 and say so.
+
+Specification: https://w3c.github.io/lws-protocol/lws10-core/`,
+
+  'solid-serve': `factoidal solid-serve - serve the Solid Protocol over HTTP
+
+usage: factoidal solid-serve DIR [--port N] [--host ADDRESS]
+
+Starts a Node HTTP server that answers every request through the engine's
+solidStep operation.
+
+DIR names the storage directory. The first slice keeps the resource tree
+in the engine handle, so DIR is not read or written yet; it is the place
+a later snapshot goes (design record, section 2).
+
+  --port N        the port to bind; 0 takes an ephemeral one (default 3000)
+  --host ADDRESS  the address to bind (default 127.0.0.1)
+  --base IRI      the absolute IRI the storage root maps to
+                  (default: the bound origin)
+  --owner WEBID   the WebID the storage advertises as its owner
+
+The server makes no protocol decision. Storage discovery, containment
+triples, slash semantics, the Allow and Accept-* headers, the PUT/POST/
+PATCH/DELETE rules, the acl and describedby lifecycle, N3 Patch, Web
+Access Control, CORS and the LDN inbox are answered by
+formal/lean4/L4Factoidal/Solid/Server/. A WebAssembly module built before
+those operations landed makes this command exit 3 and say so.
+
+Specification: https://solidproject.org/TR/protocol`,
+
+  'solid-client': `factoidal solid-client - run one Solid client operation
+
+usage: factoidal solid-client <get|put|post|delete|discover> URL [options]
+
+Every request is built by the engine's solidClientRequest operation and
+every response is read by solidClientResponse. This command supplies a
+socket and prints what the engine answered.
+
+The five verbs are aliases for the operation kinds of the wasm ABI; the
+kind names are accepted directly as well.
+
+  get       read              put     replace          post   create
+  delete    delete            discover discoverStorage
+  (also: patch, readProfile)
+
+  --body TEXT       the request body for put, post and patch
+  --file PATH       read the request body from a file
+  --content-type M  the body's media type
+  --interpret KIND  one of storage, containment, auxiliaries, profile,
+                    wacAllow, used when the engine names none
+
+Specification: https://solidproject.org/TR/protocol`
 }
 
 // ------------------------------------------------------------- arguments
@@ -334,7 +467,11 @@ const VALUE_OPTIONS = {
   pack: new Set(['layout', 'syntax', 'chunk-bytes', 'base', 'batch-bytes']),
   activate: new Set([]),
   update: new Set(['update', 'file']),
-  compact: new Set([])
+  compact: new Set([]),
+  serve: new Set(['port', 'host', 'query-path', 'gsp-path', 'file', 'layout', 'tdb2']),
+  'lws-serve': new Set(['port', 'host', 'base']),
+  'solid-serve': new Set(['port', 'host', 'base', 'owner']),
+  'solid-client': new Set(['body', 'file', 'content-type', 'interpret'])
 }
 
 // ------------------------------------------------------------- commands
@@ -348,55 +485,115 @@ function readJsonFile (path) {
   return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes))
 }
 
-function commandVersion (options) {
+async function sha256Hex (bytes) {
+  const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes)
+  return hexOfBytes(new Uint8Array(digest))
+}
+
+// `factoidal version`: what l4-assets/version.json says (the release stamp,
+// written by tools/fetch-builds.sh --set web from the factoidal-builds
+// release that built the wasm), what the installed wasm files hash to, and
+// the loaded engine's own version(). A stamp whose sha256 differs from the
+// installed wasm is an error (exit 1): the stamp then describes another
+// build. A source checkout carries the unstamped placeholder.
+async function commandVersion (options) {
   const root = packageDirectory()
   const own = readJsonFile(joinPath(root, 'package.json'))
-  let engine = null
+  let stamp = null
   try {
-    engine = readJsonFile(joinPath(root, 'l4-assets/version.json'))
+    stamp = readJsonFile(joinPath(root, 'l4-assets/version.json'))
   } catch (_error) {
-    engine = null
+    stamp = null
+  }
+  const stamped = stamp !== null && stamp.stamped === true
+  const installed = {}
+  for (const [key, file] of [['wasm', 'l4factoidal.wasm']]) {
+    try {
+      const bytes = readWhole(joinPath(root, `l4-assets/${file}`))
+      installed[key] = { sha256: await sha256Hex(bytes), bytes: bytes.length }
+    } catch (_error) {
+      installed[key] = null
+    }
+  }
+  let engineVersion = null
+  let engineError = null
+  if (installed.wasm !== null) {
+    try {
+      engineVersion = (await loadEngine()).version()
+    } catch (error) {
+      engineError = String(error && error.message ? error.message : error)
+    }
+  }
+  const mismatches = []
+  if (stamped) {
+    for (const [key, shaKey, bytesKey] of [['wasm', 'wasmSha256', 'wasmBytes']]) {
+      if (installed[key] === null) continue
+      if (stamp[shaKey] !== installed[key].sha256 || stamp[bytesKey] !== installed[key].bytes) {
+        mismatches.push(`${key}: version.json says sha256 ${stamp[shaKey]} (${stamp[bytesKey]} bytes), ` +
+          `installed file is ${installed[key].sha256} (${installed[key].bytes} bytes)`)
+      }
+    }
+    if (engineVersion !== null && typeof stamp.engineVersion === 'string' &&
+        stamp.engineVersion !== engineVersion) {
+      mismatches.push(`engine: version.json says ${stamp.engineVersion}, the loaded wasm says ${engineVersion}`)
+    }
   }
   const report = {
     package: own.name,
     version: own.version,
     host: runtime,
-    engine: engine === null
+    stamp: stamp === null
       ? null
-      : {
-          engine: engine.engine,
-          version: engine.version,
-          gitSha: engine.gitSha,
-          leanToolchain: engine.leanToolchain,
-          wasmSha256: engine.wasmSha256,
-          wasmBytes: engine.wasmBytes
-        }
+      : stamped
+        ? {
+            stamped: true,
+            engineVersion: stamp.engineVersion,
+            gitSha: stamp.gitSha,
+            builtAt: stamp.builtAt,
+            release: stamp.release,
+            leanToolchain: stamp.leanToolchain,
+            wasmSha256: stamp.wasmSha256,
+            wasmBytes: stamp.wasmBytes
+          }
+        : { stamped: false, status: stamp.status || 'stamped at release' },
+    installed,
+    engineVersion,
+    engineError,
+    mismatches
   }
   if (options.json) {
     out(JSON.stringify(report, null, 2))
-    return EXIT_OK
-  }
-  out(`${report.package} ${report.version}`)
-  out(`host-io ${report.host}`)
-  if (report.engine !== null) {
-    out(`engine ${report.engine.engine} ${report.engine.version} (${report.engine.leanToolchain})`)
-    out(`wasm sha256 ${report.engine.wasmSha256} (${report.engine.wasmBytes} bytes)`)
   } else {
-    out('engine (no l4-assets/version.json in this install)')
+    out(`${report.package} ${report.version}`)
+    out(`host-io ${report.host}`)
+    if (stamp === null) {
+      out('stamp: no l4-assets/version.json in this install')
+    } else if (!stamped) {
+      out('stamp: not stamped (l4-assets/version.json is the source placeholder; ' +
+        'it is stamped at release by tools/fetch-builds.sh --set web)')
+    } else {
+      out(`stamp: built from ${stamp.gitSha} at ${stamp.builtAt}` +
+        (stamp.release ? ` (${stamp.release})` : ''))
+      out(`stamp: engine ${stamp.engineVersion} (${stamp.leanToolchain})`)
+      out(`stamp: wasm sha256 ${stamp.wasmSha256} (${stamp.wasmBytes} bytes)`)
+    }
+    for (const [key, label] of [['wasm', 'wasm']]) {
+      out(installed[key] === null
+        ? `installed ${label}: absent`
+        : `installed ${label} sha256 ${installed[key].sha256} (${installed[key].bytes} bytes)`)
+    }
+    out(engineVersion !== null
+      ? `engine version() ${engineVersion}`
+      : `engine version() unavailable${engineError ? ': ' + engineError : ''}`)
   }
-  return EXIT_OK
-}
-
-function commandSampleStore (options) {
-  const path = sampleStorePath()
-  if (options.json === true) {
-    out(JSON.stringify({ path, ...sampleStoreFacts }, null, 2))
-    return EXIT_OK
+  if (mismatches.length > 0) {
+    for (const m of mismatches) err(`factoidal version: STAMP MISMATCH ${m}`)
+    return EXIT_FAILURE
   }
-  out(path)
   return EXIT_OK
 }
 
+
 // ------------------------------------------------------------ rendering
 
 /**
@@ -674,7 +871,7 @@ function renderQueryResult (engine, result, format, limit, quiet) {
       return EXIT_OK
     }
     if (format !== 'table') {
-      err(`factoidal query: --format ${format} needs a CONSTRUCT query; this one is a SELECT`)
+      err(`factoidal query: --format ${format} needs a CONSTRUCT or DESCRIBE query; this one is a SELECT`)
       return EXIT_FAILURE
     }
     const shown = limit === null ? bindings : bindings.slice(0, limit)
@@ -694,13 +891,13 @@ function renderQueryResult (engine, result, format, limit, quiet) {
       return EXIT_OK
     }
     if (format !== 'table') {
-      err(`factoidal query: --format ${format} needs a CONSTRUCT query; this one is an ASK`)
+      err(`factoidal query: --format ${format} needs a CONSTRUCT or DESCRIBE query; this one is an ASK`)
       return EXIT_FAILURE
     }
     out(result.boolean ? 'true' : 'false')
     return EXIT_OK
   }
-  if (result.kind === 'construct') {
+  if (result.kind === 'construct' || result.kind === 'describe') {
     if (format === 'json') {
       out(JSON.stringify(result, null, 2))
       return EXIT_OK
@@ -835,6 +1032,34 @@ async function commandPack (positional, options) {
   return EXIT_OK
 }
 
+async function commandSampleStore (positional, options) {
+  if (positional.length > 1) throw new UsageError('sample-store takes at most one DIR')
+  const { mkdtempSync, writeFileSync, existsSync } = await import('node:fs')
+  const { tmpdir } = await import('node:os')
+  const root = positional.length === 1
+    ? positional[0]
+    : mkdtempSync(joinPath(tmpdir(), 'factoidal-sample-store-'))
+  if (!existsSync(joinPath(root, 'CURRENT'))) {
+    makeDirectory(joinPath(root, 'gen-1'))
+    const source = joinPath(root, 'sample.ttl')
+    writeFileSync(source, SAMPLE_TURTLE)
+    outSilenced = true
+    try {
+      let code = await commandPack([source, joinPath(root, 'gen-1')], { quiet: true })
+      if (code === EXIT_OK) code = await commandActivate([root, 'gen-1'], { quiet: true })
+      if (code !== EXIT_OK) return code
+    } finally {
+      outSilenced = false
+    }
+  }
+  if (options.json === true) {
+    out(JSON.stringify({ path: root, ...sampleStoreFacts }, null, 2))
+  } else {
+    out(root)
+  }
+  return EXIT_OK
+}
+
 async function commandActivate (positional, options) {
   if (positional.length !== 2) throw new UsageError('activate needs STORE and GENERATION')
   const [root, generation] = positional
@@ -906,15 +1131,236 @@ function commandCompact (positional, _options) {
   return notWired('compact', 'Compaction is stage 4 of the milestone.')
 }
 
+// ------------------------------------------------- the protocol servers
+// These commands hand a socket to a host module and print where it is
+// listening. They decide nothing about the protocol they serve; see
+// npm/factoidal/lws/README.md and npm/factoidal/solid/*/README.md.
+// https://github.com/danbri/factoidal/issues/659
+
+function servePort (options, fallback) {
+  if (options.port === undefined) return fallback
+  const port = Number(options.port)
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new UsageError(`--port must be an integer from 0 to 65535, not "${options.port}"`)
+  }
+  return port
+}
+
+function serveHost (options) {
+  if (options.host === undefined) return '127.0.0.1'
+  if (typeof options.host !== 'string' || options.host.length === 0) {
+    throw new UsageError('--host needs an address')
+  }
+  return options.host
+}
+
+/** Keep the process alive until the runtime is interrupted. */
+function untilInterrupted (running, quiet) {
+  return new Promise((resolve) => {
+    const stop = async () => {
+      if (!quiet) err('')
+      await running.close()
+      resolve(EXIT_OK)
+    }
+    if (isDeno) {
+      globalThis.Deno.addSignalListener('SIGINT', stop)
+    } else {
+      process.on('SIGINT', stop)
+      process.on('SIGTERM', stop)
+    }
+  })
+}
+
+async function commandServe (positional, options) {
+  const quiet = options.quiet === true
+  // The Apache Jena Fuseki form: `serve --file DATA /ds`. The file is
+  // packed into a new collection in a temporary directory (ibk5 unless
+  // --layout says otherwise, so every graph accepts writes), activated, and
+  // served at /ds/sparql and /ds/data; /ds/query, /ds/update and /ds/get
+  // are answered too (StoreEndpoint.datasetPrefix). Updates go to that
+  // temporary collection and are lost when the process ends, as with
+  // fuseki-server --file. docs/fuseki-replacement.md.
+  if (typeof options.file === 'string') {
+    if (positional.length !== 1 || !positional[0].startsWith('/')) {
+      throw new UsageError('serve --file DATA needs one dataset name, such as /ds')
+    }
+    const dsName = positional[0].replace(/\/+$/, '')
+    const { mkdtempSync } = await import('node:fs')
+    const { tmpdir } = await import('node:os')
+    const { join } = await import('node:path')
+    const root = mkdtempSync(join(tmpdir(), 'factoidal-serve-'))
+    const packOptions = { quiet: true, layout: typeof options.layout === 'string' ? options.layout : 'ibk5' }
+    let rc = await commandPack([options.file, join(root, 'gen-1')], packOptions)
+    if (rc !== 0) return rc
+    rc = await commandActivate([root, 'gen-1'], { quiet: true })
+    if (rc !== 0) return rc
+    if (!quiet) err(`serve: packed ${options.file} into ${root} (temporary; updates are lost on exit)`)
+    positional = [root]
+    options = { ...options, 'query-path': `${dsName}/sparql`, 'gsp-path': `${dsName}/data` }
+  }
+  // The Apache Jena Fuseki form: `serve --tdb2 DIR /ds`, a TDB2 database
+  // read in place and read only (https://github.com/danbri/factoidal/issues/834).
+  const tdb2 = typeof options.tdb2 === 'string'
+  if (tdb2) {
+    if (positional.length !== 1 || !positional[0].startsWith('/')) {
+      throw new UsageError('serve --tdb2 DIR needs one dataset name, such as /ds')
+    }
+    const dsName = positional[0].replace(/\/+$/, '')
+    positional = [options.tdb2]
+    options = { ...options, 'query-path': `${dsName}/sparql`, 'gsp-path': `${dsName}/data` }
+  }
+  if (positional.length !== 1) throw new UsageError('serve needs one STORE')
+  const { listen, listenOnWorker, ServeHostError } = await import('./serve.mjs')
+  const serveOptions = {
+    port: servePort(options, 3030),
+    host: serveHost(options),
+    ...(tdb2 ? { tdb2: true } : {}),
+    ...(typeof options['query-path'] === 'string' ? { queryPath: options['query-path'] } : {}),
+    ...(typeof options['gsp-path'] === 'string' ? { gspPath: options['gsp-path'] } : {})
+  }
+  const onWorker = options['no-worker'] !== true && workerRouteAvailable()
+  let running
+  try {
+    running = onWorker
+      ? await listenOnWorker(positional[0], serveOptions)
+      : await listen(positional[0], serveOptions)
+  } catch (error) {
+    if (error instanceof ServeHostError && error.unknownOp) {
+      return notWired('serve', error.message)
+    }
+    if (error instanceof Error && typeof error.message === 'string') {
+      err(`factoidal serve: ${error.message.replace(/^l4factoidal:\s*/, '')}`)
+      return EXIT_FAILURE
+    }
+    throw error
+  }
+  const info = onWorker ? running.info : running.served.info
+  if (!quiet) {
+    err(`serve: listening on ${running.origin} for ${positional[0]} ` +
+      `(layout ${info.layout}, ${plural(info.rows, 'row')}, ` +
+      `delta batches replayed: ${info.deltaBatches}, write scope ${info.writeScope})`)
+    err(`serve: query ${running.origin}${info.queryPath}, graph store ${running.origin}${info.gspPath}`)
+  }
+  out(running.origin)
+  return untilInterrupted(running, quiet)
+}
+
+async function commandLwsServe (positional, options) {
+  if (positional.length !== 1) throw new UsageError('lws-serve needs one DIR')
+  const quiet = options.quiet === true
+  const { listen, LwsHostError } = await import('../lws/server.mjs')
+  let running
+  try {
+    running = await listen({
+      port: servePort(options, 3000),
+      host: serveHost(options),
+      ...(typeof options.base === 'string' ? { baseIri: options.base } : {}),
+      realClock: true
+    })
+  } catch (error) {
+    if (error instanceof LwsHostError && error.unknownOp) {
+      return notWired('lws-serve', error.message)
+    }
+    throw error
+  }
+  if (!quiet) err(`lws-serve: listening on ${running.origin} for ${positional[0]}`)
+  out(running.origin)
+  return untilInterrupted(running, quiet)
+}
+
+async function commandSolidServe (positional, options) {
+  if (positional.length !== 1) throw new UsageError('solid-serve needs one DIR')
+  const quiet = options.quiet === true
+  const { listen, SolidServerHostError } = await import('../solid/server/index.mjs')
+  let running
+  try {
+    running = await listen({
+      port: servePort(options, 3000),
+      host: serveHost(options),
+      ...(typeof options.base === 'string' ? { baseIri: options.base } : {}),
+      ...(typeof options.owner === 'string' ? { owner: options.owner } : {}),
+      realClock: true
+    })
+  } catch (error) {
+    if (error instanceof SolidServerHostError && error.unknownOp) {
+      return notWired('solid-serve', error.message)
+    }
+    throw error
+  }
+  if (!quiet) err(`solid-serve: listening on ${running.origin} for ${positional[0]}`)
+  out(running.origin)
+  return untilInterrupted(running, quiet)
+}
+
+// The command's verbs, as aliases for the wasm ABI's request kinds. A
+// kind name is accepted directly too, so this table adds a spelling and
+// hides nothing.
+const SOLID_CLIENT_ALIASES = {
+  get: 'read',
+  put: 'replace',
+  post: 'create',
+  delete: 'delete',
+  discover: 'discoverStorage'
+}
+
+async function commandSolidClient (positional, options) {
+  if (positional.length !== 2) {
+    throw new UsageError('solid-client needs an operation and a URL')
+  }
+  const [verb, target] = positional
+  const { createSolidClient, SolidClientHostError, SOLID_REQUEST_KINDS } =
+    await import('../solid/client/index.mjs')
+  const kind = Object.prototype.hasOwnProperty.call(SOLID_CLIENT_ALIASES, verb)
+    ? SOLID_CLIENT_ALIASES[verb]
+    : verb
+  if (!SOLID_REQUEST_KINDS.includes(kind)) {
+    throw new UsageError(
+      `unknown operation "${verb}"; one of ` +
+      `${Object.keys(SOLID_CLIENT_ALIASES).join(', ')} or ` +
+      `${SOLID_REQUEST_KINDS.join(', ')}`)
+  }
+  const args = { target }
+  if (typeof options.file === 'string') {
+    args.body = new TextDecoder('utf-8', { fatal: true }).decode(readWhole(options.file))
+  } else if (typeof options.body === 'string') {
+    args.body = options.body
+  }
+  if (typeof options['content-type'] === 'string') {
+    args.contentType = options['content-type']
+  }
+  if (['create', 'replace', 'patch'].includes(kind) && args.body === undefined) {
+    throw new UsageError(`${verb} needs --body or --file`)
+  }
+  const extra = typeof options.interpret === 'string'
+    ? { interpret: options.interpret }
+    : {}
+  let answer
+  try {
+    const client = await createSolidClient()
+    answer = await client.run(kind, args, extra)
+  } catch (error) {
+    if (error instanceof SolidClientHostError && error.unknownOp) {
+      return notWired('solid-client', error.message)
+    }
+    throw error
+  }
+  out(JSON.stringify(answer, null, 2))
+  return EXIT_OK
+}
+
 const COMMANDS = {
   version: (positional, options) => commandVersion(options),
-  'sample-store': (positional, options) => commandSampleStore(options),
+  'sample-store': (positional, options) => commandSampleStore(positional, options),
   inspect: commandInspect,
   query: commandQuery,
   pack: commandPack,
   activate: commandActivate,
   update: commandUpdate,
-  compact: commandCompact
+  compact: commandCompact,
+  serve: commandServe,
+  'lws-serve': commandLwsServe,
+  'solid-serve': commandSolidServe,
+  'solid-client': commandSolidClient
 }
 
 // ----------------------------------------------------------------- main