@swipt/cli 0.1.0-nightly.39 → 0.1.0-nightly.41

package/connection.mjs

@@ -7,7 +7,8 @@ import { setTimeout as sleep } from "node:timers/promises";
 import Bonjour from "bonjour-service";
 
 import { Code, RpcError, UsageError, open } from "./client.mjs";
-import { columns } from "./output.mjs";
+import { columns, enumText } from "./output.mjs";
+import { DeviceConnectionProblem, DeviceConnectionProblemSchema, DeviceConnectionStateSchema } from "./proto/common_pb.js";
 
 const browseLimit = 1500;
 const browseRequery = 300;
@@ -128,7 +129,7 @@ async function discover(signal, stored, until) {
   return found;
 }
 
-const requiresToken = found => `${found.name} requires a token: swipt connect ${withToken(found.url)}`;
+const requiresToken = found => `${found.name} requires a token: swipt device add ${withToken(found.url)}`;
 
 export async function attach(context) {
   const given = context.options.device ?? process.env.SWIPT_DEVICE;
@@ -142,7 +143,7 @@ export async function attach(context) {
     if (known === undefined) {
       const found = (await discover(context.signal, stored, services => services.some(it => sameName(it.name, name)))).find(it => sameName(it.name, name));
       if (!found) {
-        throw new Error(`there is no device ${name}; "swipt devices" lists them`);
+        throw new Error(`there is no device ${name}; "swipt device list" lists them`);
       }
       if (found.authenticates) {
         throw new Error(requiresToken(found));
@@ -161,7 +162,7 @@ export async function attach(context) {
       if (locked.length > 0) {
         throw new Error(locked.map(requiresToken).join("\n"));
       }
-      throw new Error('there is no device; turn on Swipt › Developer › Local Network, or connect one with "swipt connect URL"');
+      throw new Error('there is no device; turn on Swipt › Developer › Local Network, or connect one with "swipt device add URL"');
     }
     if (names.length > 1) {
       throw new Error(`there is more than one device: ${names.join(", ")}; choose one with -d or SWIPT_DEVICE`);
@@ -172,35 +173,42 @@ export async function attach(context) {
   return open(device);
 }
 
-async function reachable(device, signal) {
+function connectionText(connection) {
+  let text = enumText(DeviceConnectionStateSchema, connection?.state ?? 0, "DEVICE_CONNECTION_STATE_");
+  if (connection && connection.problem !== DeviceConnectionProblem.UNSPECIFIED) {
+    text += `, ${enumText(DeviceConnectionProblemSchema, connection.problem, "DEVICE_CONNECTION_PROBLEM_")}`;
+  }
+  if (connection?.message) {
+    text += `: ${connection.message}`;
+  }
+  return text;
+}
+
+async function probe(url, signal) {
   try {
-    await open(device).system.getInfo({}, { signal });
-    return true;
+    const info = await open(parseURL(url)).system.getInfo({}, { signal });
+    return [`${info.appVersion} (${info.appBuild})`, connectionText(info.deviceConnection)];
   } catch (error) {
-    return error instanceof RpcError && error.code === Code.Unauthenticated;
+    return [error instanceof RpcError && error.code === Code.Unauthenticated ? "requires a token" : "offline"];
   }
 }
 
-export async function devices({ signal }) {
+export async function list({ signal }) {
   const stored = load();
   const deadline = AbortSignal.any([signal, AbortSignal.timeout(browseLimit)]);
-  const probes = new Map(Object.entries(stored).map(([name, url]) => [name, reachable(parseURL(url), deadline)]));
-  const found = await discover(signal, stored);
+  const probes = new Map(Object.values(stored).map(url => [url, probe(url, deadline)]));
+  await discover(signal, stored);
   const names = Object.keys(stored).sort((a, b) => a.localeCompare(b));
   if (names.length === 0) {
-    console.error('no device publishes Swipt on the local network; turn on Swipt › Developer › Local Network, or connect one with "swipt connect URL"');
+    console.error('no device publishes Swipt on the local network; turn on Swipt › Developer › Local Network, or connect one with "swipt device add URL"');
     return;
   }
-  const rows = [];
-  for (const name of names) {
-    const { url } = parseURL(stored[name]);
-    const online = found.some(it => sameName(it.name, name) && it.url === url) || (probes.has(name) && (await probes.get(name)));
-    rows.push([name, url, online ? "" : "offline"]);
-  }
+  const late = AbortSignal.any([signal, AbortSignal.timeout(browseLimit)]);
+  const rows = await Promise.all(names.map(async name => [name, parseURL(stored[name]).url, ...(await (probes.get(stored[name]) ?? probe(stored[name], late)))]));
   console.log(columns(rows));
 }
 
-export async function connect(context) {
+export async function add(context) {
   const device = parseURL(context.args[0]);
   context.target.url = device.url;
   const info = await open(device).system.getInfo({}, { signal: context.signal });
@@ -212,10 +220,10 @@ export async function connect(context) {
   }
   stored[name] = context.args[0];
   save(stored);
-  console.log("connected", name);
+  console.log("added", name);
 }
 
-export function disconnect({ args }) {
+export function remove({ args }) {
   const stored = load();
   const name = storedName(stored, label(args[0]));
   if (name === undefined) {
@@ -223,5 +231,5 @@ export function disconnect({ args }) {
   }
   delete stored[name];
   save(stored);
-  console.log("disconnected", name);
+  console.log("removed", name);
 }

package/device.mjs

@@ -13,9 +13,8 @@ import { attach } from "./connection.mjs";
 import { Ignorer, relativePath } from "./ignore.mjs";
 import { columns, dateTime, enumText, printLog, printScriptError, serviceText } from "./output.mjs";
 import { buildProject, loadProject } from "./project.mjs";
-import { DeviceConnectionProblem, DeviceConnectionProblemSchema, DeviceConnectionStateSchema, LogLevel } from "./proto/common_pb.js";
+import { LogLevel } from "./proto/common_pb.js";
 import { ServiceStatus, ServiceStatusSchema } from "./proto/swiplets_pb.js";
-import { sources } from "./sourcemap.mjs";
 
 const uploadChunk = 256 << 10;
 const rebuildDelay = 300;
@@ -45,27 +44,6 @@ export function printVersion() {
   console.log("swipt", version, `node ${process.versions.node}`, `${process.platform}/${process.arch}`);
 }
 
-export const info = context =>
-  session(context, async client => {
-    const found = await client.system.getInfo({}, { signal: context.signal });
-    const connection = found.deviceConnection;
-    let state = enumText(DeviceConnectionStateSchema, connection?.state ?? 0, "DEVICE_CONNECTION_STATE_");
-    if (connection && connection.problem !== DeviceConnectionProblem.UNSPECIFIED) {
-      state += `, ${enumText(DeviceConnectionProblemSchema, connection.problem, "DEVICE_CONNECTION_PROBLEM_")}`;
-    }
-    if (connection?.message) {
-      state += `: ${connection.message}`;
-    }
-    console.log(
-      columns([
-        ["device:", found.deviceName],
-        ["udid:", found.udid],
-        ["server:", found.serverVersion],
-        ["connection:", state],
-      ]),
-    );
-  });
-
 export const logs = context =>
   session(context, async client => {
     const { options } = context;
@@ -111,25 +89,27 @@ const serviceStatus = state => (state.status === ServiceStatus.UNSPECIFIED ? "st
 
 const notInstalled = id => new Error(`there is no swiplet ${JSON.stringify(id)}`);
 
-export const swiplets = context =>
+export const list = context =>
   session(context, async client => {
     const { swiplets } = await client.swiplets.listSwiplets({}, { signal: context.signal });
-    if (context.args.length === 0) {
-      const rows = swiplets.map(swiplet => {
-        let service = "";
-        let status = "";
-        if (swiplet.service) {
-          service = swiplet.service.enabled ? "enabled" : "disabled";
-          status = serviceStatus(swiplet.service);
-          if (swiplet.service.error) {
-            status += `: ${swiplet.service.error.name}: ${swiplet.service.error.message}`;
-          }
+    const rows = swiplets.map(swiplet => {
+      let service = "";
+      let status = "";
+      if (swiplet.service) {
+        service = swiplet.service.enabled ? "enabled" : "disabled";
+        status = serviceStatus(swiplet.service);
+        if (swiplet.service.error) {
+          status += `: ${swiplet.service.error.name}: ${swiplet.service.error.message}`;
         }
-        return [swiplet.id, swiplet.title, swiplet.version, swiplet.actions.map(action => action.name).join(","), service, status];
-      });
-      console.log(columns([["ID", "TITLE", "VERSION", "ACTIONS", "SERVICE", "STATUS"], ...rows]));
-      return;
-    }
+      }
+      return [swiplet.id, swiplet.title, swiplet.version, swiplet.actions.map(action => action.name).join(","), service, status];
+    });
+    console.log(columns([["ID", "TITLE", "VERSION", "ACTIONS", "SERVICE", "STATUS"], ...rows]));
+  });
+
+export const show = context =>
+  session(context, async client => {
+    const { swiplets } = await client.swiplets.listSwiplets({}, { signal: context.signal });
     const swiplet = swiplets.find(it => it.id === context.args[0]);
     if (!swiplet) {
       throw notInstalled(context.args[0]);
@@ -139,7 +119,7 @@ export const swiplets = context =>
       console.log("ui: yes");
     }
     if (swiplet.service) {
-      console.log(`service: ${serviceText(swiplet.id, swiplet.service, sources.frame.bind(sources))}`);
+      console.log(`service: ${serviceText(swiplet.id, swiplet.service)}`);
     }
     for (const action of swiplet.actions) {
       console.log();
@@ -173,14 +153,14 @@ export const call = context =>
       return;
     }
     if (result?.outcome.case === "error") {
-      throw printScriptError(result.outcome.value, sources.frame(id));
+      throw printScriptError(result.outcome.value);
     }
     throw new Error("the server sent no result");
   });
 
 async function watchServices(client, id, signal) {
   for await (const response of client.swiplets.watchServices({ swipletId: id }, { signal })) {
-    console.log(`${response.swipletId}: ${serviceText(response.swipletId, response.service, sources.frame.bind(sources))}`);
+    console.log(`${response.swipletId}: ${serviceText(response.swipletId, response.service)}`);
   }
 }
 
@@ -192,7 +172,7 @@ export const setService = enabled => context =>
       await watchServices(client, id, context.signal);
       return;
     }
-    console.log(`${id}: ${serviceText(id, response.service, sources.frame.bind(sources))}`);
+    console.log(`${id}: ${serviceText(id, response.service)}`);
   });
 
 export const serviceWatch = context => session(context, client => watchServices(client, context.args[0] ?? "", context.signal));
@@ -203,16 +183,6 @@ export const remove = context =>
     console.log("removed", context.args[0]);
   });
 
-export const filesList = context =>
-  session(context, async client => {
-    const [id, directory = ""] = context.args;
-    const { files } = await client.swiplets.listDataFiles({ swipletId: id, path: directory, recursive: context.options.recursive }, { signal: context.signal });
-    const rows = files.map(file => [file.directory ? "-" : String(file.size), dateTime(file.modified), file.directory ? `${file.path}/` : file.path]);
-    if (rows.length > 0) {
-      console.log(columns(rows));
-    }
-  });
-
 const isLocal = name => {
   const normalized = path.posix.normalize(name);
   return !path.posix.isAbsolute(normalized) && normalized !== ".." && !normalized.startsWith("../");
@@ -265,97 +235,131 @@ class FileSink {
 
 const printSaved = (target, count) => console.error(`saved ${count} file(s) to ${target}`);
 
-export const filesRead = context =>
-  session(context, async client => {
-    const [id, given] = context.args;
-    const output = context.options.output ?? "";
-    const requested = path.posix.normalize(`/${given}`).replace(/^\/+|\/+$/g, "");
-    const printing = output === "" || output === "-";
-    const directory = () =>
-      new UsageError(
-        requested === ""
-          ? `${JSON.stringify(given)} names the data directory of ${id}; save it with --output DIRECTORY`
-          : `${JSON.stringify(requested)} is a directory in the data directory of ${id}; save it with --output DIRECTORY`,
-      );
-    const relativeTo = name => name.slice(requested.length).replace(/^\//, "");
-    let sink;
-    let single;
-    const contents = [];
-    try {
-      for await (const response of client.swiplets.readDataFile({ swipletId: id, path: given }, { signal: context.signal })) {
-        if (response.part.case === "file") {
-          const file = response.part.value;
-          if (file.path === requested && !file.directory) {
-            single = file;
-            continue;
-          }
-          if (!sink) {
-            if (printing) {
-              throw directory();
+const dataCommands = target => ({
+  list: context =>
+    session(context, async client => {
+      const {
+        id,
+        args: [directory = ""],
+      } = target(context.args);
+      const { files } = await client.swiplets.listDataFiles({ swipletId: id, path: directory, recursive: context.options.recursive }, { signal: context.signal });
+      const rows = files.map(file => [file.directory ? "-" : String(file.size), dateTime(file.modified), file.directory ? `${file.path}/` : file.path]);
+      if (rows.length > 0) {
+        console.log(columns(rows));
+      }
+    }),
+  read: context =>
+    session(context, async client => {
+      const {
+        id,
+        where,
+        args: [given],
+      } = target(context.args);
+      const output = context.options.output ?? "";
+      const requested = path.posix.normalize(`/${given}`).replace(/^\/+|\/+$/g, "");
+      const printing = output === "" || output === "-";
+      const directory = () =>
+        new UsageError(
+          requested === ""
+            ? `${JSON.stringify(given)} names ${where}; save it with --output DIRECTORY`
+            : `${JSON.stringify(requested)} is a directory in ${where}; save it with --output DIRECTORY`,
+        );
+      const relativeTo = name => name.slice(requested.length).replace(/^\//, "");
+      let sink;
+      let single;
+      const contents = [];
+      try {
+        for await (const response of client.swiplets.readDataFile({ swipletId: id, path: given }, { signal: context.signal })) {
+          if (response.part.case === "file") {
+            const file = response.part.value;
+            if (file.path === requested && !file.directory) {
+              single = file;
+              continue;
             }
-            sink = new FileSink(output);
-          }
-          sink.begin(relativeTo(file.path), file.directory);
-        } else if (response.part.case === "chunk") {
-          const chunk = response.part.value;
-          if (single && chunk.path === single.path) {
-            contents.push(chunk.data);
-            continue;
-          }
-          if (!sink) {
-            throw new Error(`the server sent data for ${chunk.path} before announcing it`);
+            if (!sink) {
+              if (printing) {
+                throw directory();
+              }
+              sink = new FileSink(output);
+            }
+            sink.begin(relativeTo(file.path), file.directory);
+          } else if (response.part.case === "chunk") {
+            const chunk = response.part.value;
+            if (single && chunk.path === single.path) {
+              contents.push(chunk.data);
+              continue;
+            }
+            if (!sink) {
+              throw new Error(`the server sent data for ${chunk.path} before announcing it`);
+            }
+            sink.write(relativeTo(chunk.path), chunk.offset, chunk.data);
           }
-          sink.write(relativeTo(chunk.path), chunk.offset, chunk.data);
         }
+      } finally {
+        sink?.close();
       }
-    } finally {
-      sink?.close();
-    }
-    if (sink) {
-      printSaved(sink.root, sink.saved);
-      return;
-    }
-    if (!single) {
+      if (sink) {
+        printSaved(sink.root, sink.saved);
+        return;
+      }
+      if (!single) {
+        if (printing) {
+          throw directory();
+        }
+        fs.mkdirSync(output, { recursive: true });
+        printSaved(output, 0);
+        return;
+      }
+      const data = Buffer.concat(contents);
       if (printing) {
-        throw directory();
+        process.stdout.write(data);
+        return;
       }
-      fs.mkdirSync(output, { recursive: true });
-      printSaved(output, 0);
-      return;
-    }
-    const data = Buffer.concat(contents);
-    if (printing) {
-      process.stdout.write(data);
-      return;
-    }
-    let target = output;
-    if (fs.existsSync(target) && fs.statSync(target).isDirectory()) {
-      target = path.join(target, path.posix.basename(single.path));
-    }
-    fs.writeFileSync(target, data);
-    printSaved(target, 1);
-  });
+      let destination = output;
+      if (fs.existsSync(destination) && fs.statSync(destination).isDirectory()) {
+        destination = path.join(destination, path.posix.basename(single.path));
+      }
+      fs.writeFileSync(destination, data);
+      printSaved(destination, 1);
+    }),
+  write: context =>
+    session(context, async client => {
+      const {
+        id,
+        args: [name, file],
+      } = target(context.args);
+      const data = file === undefined || file === "-" ? readStdin() : fs.readFileSync(file);
+      await client.swiplets.writeDataFile(
+        (async function* () {
+          yield { part: { case: "header", value: { swipletId: id, path: name } } };
+          for (let offset = 0; offset < data.length; offset += uploadChunk) {
+            yield { part: { case: "data", value: data.subarray(offset, offset + uploadChunk) } };
+          }
+        })(),
+        { signal: context.signal },
+      );
+    }),
+  remove: context =>
+    session(context, async client => {
+      const {
+        id,
+        args: [name],
+      } = target(context.args);
+      await client.swiplets.removeDataFile({ swipletId: id, path: name, recursive: context.options.recursive }, { signal: context.signal });
+    }),
+  clear: context =>
+    session(context, async client => {
+      const { id } = target(context.args);
+      const { files } = await client.swiplets.listDataFiles({ swipletId: id }, { signal: context.signal });
+      for (const file of files) {
+        await client.swiplets.removeDataFile({ swipletId: id, path: file.path, recursive: true }, { signal: context.signal });
+      }
+    }),
+});
 
-export const filesWrite = context =>
-  session(context, async client => {
-    const [id, name, file] = context.args;
-    const data = file === undefined || file === "-" ? readStdin() : fs.readFileSync(file);
-    await client.swiplets.writeDataFile(
-      (async function* () {
-        yield { part: { case: "header", value: { swipletId: id, path: name } } };
-        for (let offset = 0; offset < data.length; offset += uploadChunk) {
-          yield { part: { case: "data", value: data.subarray(offset, offset + uploadChunk) } };
-        }
-      })(),
-      { signal: context.signal },
-    );
-  });
+export const swipletData = dataCommands(([id, ...args]) => ({ id, where: `the data directory of ${id}`, args }));
 
-export const filesRemove = context =>
-  session(context, async client => {
-    const [id, name] = context.args;
-    await client.swiplets.removeDataFile({ swipletId: id, path: name, recursive: context.options.recursive }, { signal: context.signal });
-  });
+export const replData = dataCommands(args => ({ id: "@repl", where: "the data directory of the REPL", args }));
 
 async function deploy(client, archive, signal) {
   const data = fs.readFileSync(archive);
@@ -371,20 +375,19 @@ async function deploy(client, archive, signal) {
 
 const printDeployed = (deployed, toStdout) => (toStdout ? console.log : console.error)(deployed.replaced ? "replaced" : "installed", deployed.swiplet.id, deployed.swiplet.version);
 
-export async function deployCommand(context) {
-  const [given] = context.args;
-  let archive;
-  if (given !== undefined && (given.endsWith(".swiplet") || given.endsWith(".zip"))) {
-    if (!fs.existsSync(given)) {
-      throw new Error(`there is no archive at ${given}`);
-    }
-    archive = given;
-  } else {
-    ({ archive } = await buildProject(path.resolve(given ?? ".")));
+export async function install(context) {
+  const [archive] = context.args;
+  if (!fs.existsSync(archive)) {
+    throw new Error(`there is no archive at ${archive}`);
   }
   await session(context, async client => printDeployed(await deploy(client, archive, context.signal), true));
 }
 
+export async function deployProject(context) {
+  const { archive } = await buildProject(path.resolve(context.args[0] ?? "."));
+  await session(context, async client => printDeployed(await deploy(client, archive, context.signal), true));
+}
+
 async function follow(signal, fatal, run) {
   while (!signal.aborted) {
     try {
@@ -407,7 +410,6 @@ export async function develop(context) {
   const { signal, printError } = context;
   const project = loadProject(path.resolve(context.args[0] ?? "."));
   const root = project.root;
-  sources.root = root;
   const client = await attach(context);
   const controller = new AbortController();
   const inner = AbortSignal.any([signal, controller.signal]);
@@ -418,7 +420,7 @@ export async function develop(context) {
   follow(inner, fatalReject, async () => {
     for await (const response of client.swiplets.watchServices({}, { signal: inner })) {
       if (response.swipletId === project.config.id && response.service?.status === ServiceStatus.FAILED) {
-        console.error(`${response.swipletId}: ${serviceText(response.swipletId, response.service, sources.frame.bind(sources))}`);
+        console.error(`${response.swipletId}: ${serviceText(response.swipletId, response.service)}`);
       }
     }
   });
@@ -441,7 +443,6 @@ export async function develop(context) {
       }
       return;
     }
-    sources.forget(built.id);
     if (built.digest === deployed) {
       console.error(`built in ${elapsed(started)}; it came out as deployed, so nothing was deployed`);
       return;
@@ -506,20 +507,27 @@ export async function develop(context) {
   }
 }
 
-function readScript(args, options) {
-  if (args.length === 1 && options.file !== undefined) {
-    throw new UsageError("give CODE or --file, not both");
+const isFile = name => {
+  try {
+    return fs.statSync(name).isFile();
+  } catch {
+    return false;
   }
-  if (options.file !== undefined) {
-    return { code: fs.readFileSync(options.file, "utf8"), run: true };
+};
+
+export const isProgram = first => first === "-" || isFile(first);
+
+function readScript([first, ...args]) {
+  if (first === undefined || first === "-") {
+    return { code: readStdin().toString(), args, program: true, file: "input.js" };
   }
-  if (args.length === 1 && args[0] !== "-") {
-    return { code: args[0], run: true };
+  if (isFile(first)) {
+    return { code: fs.readFileSync(first, "utf8"), args, program: true, file: first };
   }
-  if (args.length === 0 && options.reset) {
-    return { code: "", run: false };
+  if (args.length > 0) {
+    throw new UsageError(`${JSON.stringify(first)} is not a file, and CODE takes no ARG`);
   }
-  return { code: readStdin().toString(), run: true };
+  return { code: first, args, program: false, file: "input.js" };
 }
 
 class ImageSink {
@@ -535,7 +543,7 @@ class ImageSink {
         this.directory = path.resolve(this.output);
         fs.mkdirSync(this.directory, { recursive: true });
       } else {
-        this.directory = fs.mkdtempSync(path.join(os.tmpdir(), "swipt-js-"));
+        this.directory = fs.mkdtempSync(path.join(os.tmpdir(), "swipt-repl-"));
       }
     }
     const name = path.join(this.directory, `image-${crypto.randomBytes(5).toString("hex")}.png`);
@@ -544,29 +552,20 @@ class ImageSink {
   }
 }
 
-export async function js(context) {
+export const api = context =>
+  session(context, async client => {
+    process.stdout.write((await client.repl.getDeclarations({}, { signal: context.signal })).typescript);
+  });
+
+export const reset = context => session(context, client => client.repl.reset({}, { signal: context.signal }));
+
+export async function run(context) {
   const { args, options, signal } = context;
-  if (options.api) {
-    if (args.length > 0 || options.file !== undefined || options.reset) {
-      throw new UsageError("--api takes no script and no --reset");
-    }
-    await session(context, async client => {
-      process.stdout.write((await client.repl.getDeclarations({}, { signal: context.signal })).typescript);
-    });
-    return;
-  }
-  const { code, run } = readScript(args, options);
+  const script = readScript(args);
   await session(context, async client => {
-    if (options.reset) {
-      await client.repl.reset({}, { signal });
-    }
-    if (!run) {
-      return;
-    }
-    const script = options.file ?? "input.js";
     const images = new ImageSink(options.output);
     let failure;
-    for await (const response of client.repl.execute({ code }, { signal })) {
+    for await (const response of client.repl.execute({ code: script.code, args: script.args, program: script.program }, { signal })) {
       switch (response.part.case) {
         case "console": {
           const output = response.part.value;
@@ -585,7 +584,7 @@ export async function js(context) {
       }
     }
     if (failure) {
-      throw printScriptError(failure, frame => (frame.file === "input.js" ? { ...frame, file: script } : frame));
+      throw printScriptError({ ...failure, stack: failure.stack.map(frame => (frame.file === "input.js" ? { ...frame, file: script.file } : frame)) });
     }
   });
 }

package/output.mjs

@@ -36,10 +36,10 @@ const frameText = frame => {
   return frame.function === "" ? position : `${frame.function} (${position})`;
 };
 
-export const failureText = (failure, frames) => [`${failure.name}: ${failure.message}`, ...failure.stack.map(frame => `    at ${frameText(frames(frame))}`)].join("\n");
+export const failureText = failure => [`${failure.name}: ${failure.message}`, ...failure.stack.map(frame => `    at ${frameText(frame)}`)].join("\n");
 
-export function printScriptError(failure, frames) {
-  console.error(`error: ${failureText(failure, frames)}`);
+export function printScriptError(failure) {
+  console.error(`error: ${failureText(failure)}`);
   return new FalseResult();
 }
 
@@ -48,14 +48,14 @@ export function printLog(entry, toStdout) {
   (toStdout ? console.log : console.error)(clockTime(entry.time), levelName(entry.level).toUpperCase(), message);
 }
 
-export function serviceText(id, state, frames) {
+export function serviceText(id, state) {
   let text = state?.enabled ? "enabled" : "disabled";
   text += `, ${state && state.status !== ServiceStatus.UNSPECIFIED ? enumText(ServiceStatusSchema, state.status, "SERVICE_STATUS_") : "stopped"}`;
   if (state?.since) {
     text += ` since ${clockTime(state.since)}`;
   }
   if (state?.error) {
-    text += `: ${failureText(state.error, frames(id))}`;
+    text += `: ${failureText(state.error)}`;
   }
   return text;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swipt/cli",
-  "version": "0.1.0-nightly.39",
+  "version": "0.1.0-nightly.41",
   "license": "GPL-3.0-or-later",
   "repository": {
     "type": "git",
@@ -23,7 +23,6 @@
     "@babel/runtime": "^7.29.10",
     "@bufbuild/protobuf": "^2.16.0",
     "@expo/env": "^2.5.3",
-    "@jridgewell/trace-mapping": "^0.3.31",
     "babel-preset-expo": "~58.0.22",
     "bonjour-service": "^1.4.4",
     "esbuild": "^0.28.2",
@@ -31,7 +30,7 @@
     "react-native-worklets": "0.13.0"
   },
   "peerDependencies": {
-    "@swipt/api": "0.1.0-nightly.39"
+    "@swipt/api": "0.1.0-nightly.41"
   },
   "devDependencies": {
     "@bufbuild/protoc-gen-es": "^2.16.0"

package/project.mjs

@@ -26,6 +26,7 @@ const appModules = [
   "@swipt/api",
   "@swipt/api/swiplet",
   "@swipt/api/file-system",
+  "expo-sqlite",
 ];
 const extensionModules = [
   "@swipt/api",
@@ -37,6 +38,7 @@ const extensionModules = [
   "@swipt/api/screen",
   "@swipt/api/image",
   "expo-localization",
+  "expo-sqlite",
 ];
 
 const idPattern = /^[a-z0-9][a-z0-9._-]{0,127}$/;
@@ -84,9 +86,10 @@ async function bundle(project) {
   const out = { app: "", extension: "", extensionMap: "", assets: new Map() };
   loadEnvironment(project.root);
   if (project.extension) {
+    const outfile = path.join(project.root, "dist", project.config.id, "src", "extension.js");
     const result = await build({
       entryPoints: [project.extension],
-      outfile: path.join(project.root, "dist", project.config.id, "src", "extension.js"),
+      outfile,
       bundle: true,
       format: "cjs",
       platform: "neutral",
@@ -100,7 +103,9 @@ async function bundle(project) {
       plugins: [metro(project.root, { sourcemap: true })],
     });
     out.extension = result.outputFiles.find(file => file.path.endsWith(".js")).text;
-    out.extensionMap = result.outputFiles.find(file => file.path.endsWith(".map")).text;
+    const map = JSON.parse(result.outputFiles.find(file => file.path.endsWith(".map")).text);
+    const sources = map.sources.map(source => path.relative(project.root, path.resolve(path.dirname(outfile), map.sourceRoot ?? "", source)).split(path.sep).join("/"));
+    out.extensionMap = JSON.stringify({ ...map, sourceRoot: undefined, sources });
   }
   if (project.app) {
     const result = await build({
@@ -163,6 +168,14 @@ function describeExtension(source) {
     "@swipt/api/screen": loading("screen"),
     "@swipt/api/image": loading("image"),
     "expo-localization": { getLocales: () => [{ languageTag: "en", languageCode: "en" }], getCalendars: () => [] },
+    "expo-sqlite": {
+      openDatabaseSync: () => loading("the database"),
+      openDatabaseAsync: () => Promise.resolve(loading("the database")),
+      deleteDatabaseSync: () => {},
+      deleteDatabaseAsync: () => Promise.resolve(),
+      addDatabaseChangeListener: () => ({ remove: () => {} }),
+      defaultDatabaseDirectory: "",
+    },
   };
   const ignored = () => 0;
   const context = vm.createContext({
@@ -273,7 +286,7 @@ export async function buildProject(root) {
   const archive = path.join(dist, `${manifest.id}.swiplet`);
   fs.rmSync(archive, { force: true });
   fs.rmSync(path.join(dist, `${manifest.id}.zip`), { force: true });
-  execFileSync("zip", ["-qr", "-n", storedSuffixes, archive, ...fs.readdirSync(folder), "-x", "*.map"], { cwd: folder });
+  execFileSync("zip", ["-qr", "-n", storedSuffixes, archive, ...fs.readdirSync(folder)], { cwd: folder });
   return { id: manifest.id, archive, digest: folderDigest(folder) };
 }
 
@@ -284,7 +297,7 @@ function folderDigest(folder) {
       const name = path.join(directory, entry.name);
       if (entry.isDirectory()) {
         walk(name);
-      } else if (!entry.name.endsWith(".map")) {
+      } else {
         hash.update(`${path.relative(folder, name)}\0`);
         hash.update(fs.readFileSync(name));
         hash.update("\0");
@@ -414,7 +427,7 @@ const templates = {
           app: "./src/App.tsx",
           extension: "./src/extension.ts",
         },
-        scripts: { build: "swipt build", check: "tsc" },
+        scripts: { build: "swipt project build", check: "tsc" },
         dependencies: { zod: "^4.6.7" },
         devDependencies: {
           "@swipt/api": version,

package/proto/repl_pb.js

@@ -10,7 +10,7 @@ import { file_common } from "./common_pb.js";
  * Describes the file repl.proto.
  */
 export const file_repl = /*@__PURE__*/
-  fileDesc("CgpyZXBsLnByb3RvEgVzd2lwdCIyCg5FeGVjdXRlUmVxdWVzdBIMCgRjb2RlGAEgASgJEhIKCnRpbWVvdXRfbXMYAiABKA0iPQoNQ29uc29sZU91dHB1dBIeCgVsZXZlbBgBIAEoDjIPLnN3aXB0LkxvZ0xldmVsEgwKBHRleHQYAiABKAkiKQoLU2NyaXB0VmFsdWUSDAoEanNvbhgBIAEoCRIMCgR0ZXh0GAIgASgJIp0BCg9FeGVjdXRlUmVzcG9uc2USJwoHY29uc29sZRgBIAEoCzIULnN3aXB0LkNvbnNvbGVPdXRwdXRIABIjCgV2YWx1ZRgCIAEoCzISLnN3aXB0LlNjcmlwdFZhbHVlSAASDwoFaW1hZ2UYAyABKAxIABIjCgVlcnJvchgEIAEoCzISLnN3aXB0LlNjcmlwdEVycm9ySABCBgoEcGFydCItChdHZXREZWNsYXJhdGlvbnNSZXNwb25zZRISCgp0eXBlc2NyaXB0GAEgASgJMs0BCgtSRVBMU2VydmljZRI6CgdFeGVjdXRlEhUuc3dpcHQuRXhlY3V0ZVJlcXVlc3QaFi5zd2lwdC5FeGVjdXRlUmVzcG9uc2UwARI3CgVSZXNldBIWLmdvb2dsZS5wcm90b2J1Zi5FbXB0eRoWLmdvb2dsZS5wcm90b2J1Zi5FbXB0eRJJCg9HZXREZWNsYXJhdGlvbnMSFi5nb29nbGUucHJvdG9idWYuRW1wdHkaHi5zd2lwdC5HZXREZWNsYXJhdGlvbnNSZXNwb25zZUIyWjBnaXRodWIuY29tL3N3aXB0LWF1dG9tYXRpb24vc3dpcHQvaW50ZXJuYWwvcHJvdG9iBnByb3RvMw", [file_google_protobuf_empty, file_common]);
+  fileDesc("CgpyZXBsLnByb3RvEgVzd2lwdCJRCg5FeGVjdXRlUmVxdWVzdBIMCgRjb2RlGAEgASgJEhIKCnRpbWVvdXRfbXMYAiABKA0SDAoEYXJncxgDIAMoCRIPCgdwcm9ncmFtGAQgASgIIj0KDUNvbnNvbGVPdXRwdXQSHgoFbGV2ZWwYASABKA4yDy5zd2lwdC5Mb2dMZXZlbBIMCgR0ZXh0GAIgASgJIikKC1NjcmlwdFZhbHVlEgwKBGpzb24YASABKAkSDAoEdGV4dBgCIAEoCSKdAQoPRXhlY3V0ZVJlc3BvbnNlEicKB2NvbnNvbGUYASABKAsyFC5zd2lwdC5Db25zb2xlT3V0cHV0SAASIwoFdmFsdWUYAiABKAsyEi5zd2lwdC5TY3JpcHRWYWx1ZUgAEg8KBWltYWdlGAMgASgMSAASIwoFZXJyb3IYBCABKAsyEi5zd2lwdC5TY3JpcHRFcnJvckgAQgYKBHBhcnQiLQoXR2V0RGVjbGFyYXRpb25zUmVzcG9uc2USEgoKdHlwZXNjcmlwdBgBIAEoCTLNAQoLUkVQTFNlcnZpY2USOgoHRXhlY3V0ZRIVLnN3aXB0LkV4ZWN1dGVSZXF1ZXN0GhYuc3dpcHQuRXhlY3V0ZVJlc3BvbnNlMAESNwoFUmVzZXQSFi5nb29nbGUucHJvdG9idWYuRW1wdHkaFi5nb29nbGUucHJvdG9idWYuRW1wdHkSSQoPR2V0RGVjbGFyYXRpb25zEhYuZ29vZ2xlLnByb3RvYnVmLkVtcHR5Gh4uc3dpcHQuR2V0RGVjbGFyYXRpb25zUmVzcG9uc2VCMlowZ2l0aHViLmNvbS9zd2lwdC1hdXRvbWF0aW9uL3N3aXB0L2ludGVybmFsL3Byb3RvYgZwcm90bzM", [file_google_protobuf_empty, file_common]);
 
 /**
  * Describes the message swipt.ExecuteRequest.

package/proto/system_pb.js

@@ -10,7 +10,7 @@ import { file_common } from "./common_pb.js";
  * Describes the file system.proto.
  */
 export const file_system = /*@__PURE__*/
-  fileDesc("CgxzeXN0ZW0ucHJvdG8SBXN3aXB0IoABCg9HZXRJbmZvUmVzcG9uc2USFgoOc2VydmVyX3ZlcnNpb24YASABKAkSEwoLZGV2aWNlX25hbWUYAiABKAkSDAoEdWRpZBgDIAEoCRIyChFkZXZpY2VfY29ubmVjdGlvbhgEIAEoCzIXLnN3aXB0LkRldmljZUNvbm5lY3Rpb24ySgoNU3lzdGVtU2VydmljZRI5CgdHZXRJbmZvEhYuZ29vZ2xlLnByb3RvYnVmLkVtcHR5GhYuc3dpcHQuR2V0SW5mb1Jlc3BvbnNlQjJaMGdpdGh1Yi5jb20vc3dpcHQtYXV0b21hdGlvbi9zd2lwdC9pbnRlcm5hbC9wcm90b2IGcHJvdG8z", [file_google_protobuf_empty, file_common]);
+  fileDesc("CgxzeXN0ZW0ucHJvdG8SBXN3aXB0IqgBCg9HZXRJbmZvUmVzcG9uc2USFgoOc2VydmVyX3ZlcnNpb24YASABKAkSEwoLZGV2aWNlX25hbWUYAiABKAkSDAoEdWRpZBgDIAEoCRIyChFkZXZpY2VfY29ubmVjdGlvbhgEIAEoCzIXLnN3aXB0LkRldmljZUNvbm5lY3Rpb24SEwoLYXBwX3ZlcnNpb24YBSABKAkSEQoJYXBwX2J1aWxkGAYgASgJMkoKDVN5c3RlbVNlcnZpY2USOQoHR2V0SW5mbxIWLmdvb2dsZS5wcm90b2J1Zi5FbXB0eRoWLnN3aXB0LkdldEluZm9SZXNwb25zZUIyWjBnaXRodWIuY29tL3N3aXB0LWF1dG9tYXRpb24vc3dpcHQvaW50ZXJuYWwvcHJvdG9iBnByb3RvMw", [file_google_protobuf_empty, file_common]);
 
 /**
  * Describes the message swipt.GetInfoResponse.

package/swipt.mjs

@@ -7,14 +7,12 @@ import * as connection from "./connection.mjs";
 import * as device from "./device.mjs";
 import { FalseResult } from "./output.mjs";
 import { buildProject, createCommand, sourceCommand } from "./project.mjs";
-import { sources } from "./sourcemap.mjs";
 
 const globalOptions = {
-  device: { type: "string", short: "d", value: "NAME|URL", help: "the device to use (SWIPT_DEVICE)" },
   help: { type: "boolean", short: "h", help: "help" },
 };
 
-const projectOption = { project: { type: "string", value: "DIRECTORY", help: "swiplet project for source maps" } };
+const deviceOption = { device: { type: "string", short: "d", value: "NAME|URL", help: "the device to use (SWIPT_DEVICE)" } };
 
 const durationUnits = { ns: 1e-6, us: 1e-3, "µs": 1e-3, ms: 1, s: 1000, m: 60_000, h: 3_600_000 };
 
@@ -48,101 +46,143 @@ function parseCount(text, option) {
   return Number(text);
 }
 
+const dataCommands = (operand, files) => {
+  const before = operand === "" ? 0 : 1;
+  return {
+    name: "data",
+    short: `Manage the files in the data directory of ${operand === "" ? "the REPL" : "a swiplet"}`,
+    commands: [
+      { name: "list", use: `list ${operand}[PATH]`, short: "List data files", args: [before, before + 1], options: { recursive: { type: "boolean", help: "include subdirectories" } }, run: files.list },
+      { name: "read", use: `read ${operand}PATH`, short: "Read a data file or directory", args: [before + 1, before + 1], options: { output: { type: "string", value: "PATH", help: "destination" } }, run: files.read },
+      { name: "write", use: `write ${operand}PATH [FILE | -]`, short: "Write a data file", args: [before + 1, before + 2], run: files.write },
+      { name: "remove", use: `remove ${operand}PATH`, short: "Remove a data file", args: [before + 1, before + 1], options: { recursive: { type: "boolean", help: "include directory contents" } }, run: files.remove },
+      { name: "clear", use: `clear ${operand}`.trimEnd(), short: "Remove every data file, keeping the data directory", args: [before, before], run: files.clear },
+    ],
+  };
+};
+
 const commands = [
   {
-    name: "create",
-    use: "create DIRECTORY",
-    short: "Make a swiplet project in a new or empty directory",
-    args: [1, 1],
-    run: ({ args }) => createCommand(args[0]),
-  },
-  {
-    name: "build",
-    short: "Bundle the project in this directory into dist/<swiplet.id>.swiplet",
-    args: [0, 0],
-    run: async () => {
-      const { archive } = await buildProject(process.cwd());
-      console.log(path.relative(process.cwd(), archive));
-    },
-  },
-  {
-    name: "source",
-    use: "source [SWIPLET...]",
-    short: 'Gather the built swiplets of this directory\'s workspaces, or the given ones, into dist/ with a swiplets.json described by "source" in package.json',
-    args: [0, Infinity],
-    run: ({ args }) => sourceCommand(process.cwd(), args),
-  },
-  { name: "devices", short: "List the devices, adding the ones found on the local network", args: [0, 0], run: connection.devices },
-  { name: "connect", use: "connect URL", short: "Add a device by its URL; needed when it is remote or requires a token", args: [1, 1], run: connection.connect },
-  { name: "disconnect", use: "disconnect NAME", short: "Forget a device", args: [1, 1], run: connection.disconnect },
-  { name: "info", short: "Show the device and its connection", args: [0, 0], run: device.info },
-  { name: "version", short: "Print the version", args: [0, 0], run: device.printVersion },
-  { name: "swiplets", use: "swiplets [ID]", short: "List the swiplets or show one", args: [0, 1], options: projectOption, run: device.swiplets },
-  {
-    name: "call",
-    use: "call ID ACTION",
-    short: "Call a swiplet action",
-    args: [2, 2],
-    options: { input: { type: "string", value: "JSON", help: "input JSON, @FILE or -" }, ...projectOption },
-    run: device.call,
-  },
-  {
-    name: "service",
-    short: "Manage swiplet services",
-    options: projectOption,
+    name: "project",
+    short: "Make, build and deploy swiplet projects",
     commands: [
-      { name: "enable", use: "enable ID", short: "Turn on a swiplet service", args: [1, 1], options: { watch: { type: "boolean", help: "watch the state" } }, run: device.setService(true) },
-      { name: "disable", use: "disable ID", short: "Turn off a swiplet service", args: [1, 1], options: { watch: { type: "boolean", help: "watch the state" } }, run: device.setService(false) },
-      { name: "watch", use: "watch [ID]", short: "Watch swiplet services", args: [0, 1], run: device.serviceWatch },
+      {
+        name: "create",
+        use: "create DIRECTORY",
+        short: "Make a swiplet project in a new or empty directory",
+        args: [1, 1],
+        run: ({ args }) => createCommand(args[0]),
+      },
+      {
+        name: "build",
+        use: "build [PROJECT]",
+        short: "Bundle the project into dist/<swiplet.id>.swiplet",
+        args: [0, 1],
+        run: async ({ args }) => {
+          const { archive } = await buildProject(path.resolve(args[0] ?? "."));
+          console.log(path.relative(process.cwd(), archive));
+        },
+      },
+      {
+        name: "source",
+        use: "source [SWIPLET...]",
+        short: 'Gather the built swiplets of this directory\'s workspaces, or the given ones, into dist/ with a swiplets.json described by "source" in package.json',
+        args: [0, Infinity],
+        run: ({ args }) => sourceCommand(process.cwd(), args),
+      },
+      { name: "deploy", use: "deploy [PROJECT]", short: "Build the project and install it on the device", args: [0, 1], options: deviceOption, run: device.deployProject },
+      {
+        name: "develop",
+        use: "develop [PROJECT]",
+        short: "Build, install and follow a swiplet project as it changes",
+        args: [0, 1],
+        options: { ...deviceOption, "no-logs": { type: "boolean", help: "without logs" } },
+        run: device.develop,
+      },
     ],
   },
-  { name: "remove", use: "remove ID", short: "Remove a swiplet", args: [1, 1], run: device.remove },
   {
-    name: "files",
-    short: "Manage swiplet data files",
+    name: "device",
+    short: "Manage the devices and read their logs",
     commands: [
-      { name: "list", use: "list ID [PATH]", short: "List data files", args: [1, 2], options: { recursive: { type: "boolean", help: "include subdirectories" } }, run: device.filesList },
-      { name: "read", use: "read ID PATH", short: "Read a data file or directory", args: [2, 2], options: { output: { type: "string", value: "PATH", help: "destination" } }, run: device.filesRead },
-      { name: "write", use: "write ID PATH [FILE | -]", short: "Write a data file", args: [2, 3], run: device.filesWrite },
-      { name: "remove", use: "remove ID PATH", short: "Remove a data file", args: [2, 2], options: { recursive: { type: "boolean", help: "include directory contents" } }, run: device.filesRemove },
+      { name: "list", short: "List the devices, adding the ones found on the local network", args: [0, 0], run: connection.list },
+      { name: "add", use: "add URL", short: "Add a device by its URL; needed when it is remote or requires a token", args: [1, 1], run: connection.add },
+      { name: "remove", use: "remove NAME", short: "Forget a device", args: [1, 1], run: connection.remove },
+      {
+        name: "logs",
+        short: "Print the logs",
+        args: [0, 0],
+        options: {
+          ...deviceOption,
+          follow: { type: "boolean", help: "follow new entries" },
+          tail: { type: "string", value: "COUNT", help: "number of past entries (default 100)" },
+          since: { type: "string", value: "DURATION", help: "maximum age" },
+          level: { type: "string", value: "LEVEL", help: "minimum level (default info)" },
+          swiplet: { type: "string", value: "ID", help: "swiplet ID" },
+        },
+        parse: options => ({ ...options, tail: parseCount(options.tail, "--tail"), since: parseDuration(options.since, "--since"), level: options.level ?? "info" }),
+        run: device.logs,
+      },
     ],
   },
-  { name: "deploy", use: "deploy [ARCHIVE | PROJECT]", short: "Build and install a swiplet", args: [0, 1], run: device.deployCommand },
-  {
-    name: "develop",
-    use: "develop [PROJECT]",
-    short: "Build, install and follow a swiplet project as it changes",
-    args: [0, 1],
-    options: { "no-logs": { type: "boolean", help: "without logs" } },
-    run: device.develop,
-  },
   {
-    name: "logs",
-    short: "Print the logs",
-    args: [0, 0],
-    options: {
-      follow: { type: "boolean", help: "follow new entries" },
-      tail: { type: "string", value: "COUNT", help: "number of past entries (default 100)" },
-      since: { type: "string", value: "DURATION", help: "maximum age" },
-      level: { type: "string", value: "LEVEL", help: "minimum level (default info)" },
-      swiplet: { type: "string", value: "ID", help: "swiplet ID" },
-    },
-    parse: options => ({ ...options, tail: parseCount(options.tail, "--tail"), since: parseDuration(options.since, "--since"), level: options.level ?? "info" }),
-    run: device.logs,
+    name: "swiplet",
+    short: "Manage the swiplets on the device",
+    options: deviceOption,
+    commands: [
+      { name: "list", short: "List the swiplets", args: [0, 0], run: device.list },
+      { name: "show", use: "show ID", short: "Show a swiplet", args: [1, 1], run: device.show },
+      { name: "install", use: "install ARCHIVE", short: "Install a swiplet archive", args: [1, 1], run: device.install },
+      { name: "remove", use: "remove ID", short: "Remove a swiplet", args: [1, 1], run: device.remove },
+      {
+        name: "call",
+        use: "call ID ACTION",
+        short: "Call a swiplet action",
+        args: [2, 2],
+        options: { input: { type: "string", value: "JSON", help: "input JSON, @FILE or -" } },
+        run: device.call,
+      },
+      {
+        name: "service",
+        short: "Manage swiplet services",
+        commands: [
+          { name: "enable", use: "enable ID", short: "Turn on a swiplet service", args: [1, 1], options: { watch: { type: "boolean", help: "watch the state" } }, run: device.setService(true) },
+          { name: "disable", use: "disable ID", short: "Turn off a swiplet service", args: [1, 1], options: { watch: { type: "boolean", help: "watch the state" } }, run: device.setService(false) },
+          { name: "watch", use: "watch [ID]", short: "Watch swiplet services", args: [0, 1], run: device.serviceWatch },
+        ],
+      },
+      dataCommands("ID ", device.swipletData),
+    ],
   },
   {
-    name: "js",
-    use: "js [CODE | -]",
-    short: "Run JavaScript on the device",
-    args: [0, 1],
-    options: {
-      file: { type: "string", value: "FILE", help: "script file" },
-      reset: { type: "boolean", help: "reset the session first" },
-      api: { type: "boolean", help: "TypeScript declarations" },
-      output: { type: "string", value: "DIRECTORY", help: "image directory" },
-    },
-    run: device.js,
+    name: "repl",
+    short: "Run JavaScript in the REPL session on the device",
+    options: deviceOption,
+    commands: [
+      {
+        name: "run",
+        use: "run [CODE | FILE [ARG...] | - [ARG...]]",
+        short: "Run a JavaScript expression or program on the device",
+        description: [
+          "The first argument is FILE when it names an existing file and CODE otherwise; options go before FILE or -, and every argument after it is an ARG, verbatim.",
+          "CODE is an expression; its completion value, awaited if it is a promise, is printed in inspect format: strings quoted, and values with their own toString, which include accessibility snapshots and screen recordings, as that string.",
+          "FILE, or standard input given as - or no argument, is a program; only its console output and thrown error are printed, and the global args holds its ARGs.",
+          'Top-level await is available, and top-level bindings persist across runs until "swipt repl reset".',
+          "An image given to show(), or as the completion value of CODE, is saved as a PNG file and printed as its path.",
+          'There is no module system, so import is unavailable; the globals are accessibility, input, device, screen, image, dialog, dataDirectory, show and sleep, declared by "swipt repl api".',
+          'dataDirectory is the directory that "swipt repl data" manages.',
+        ],
+        args: [0, Infinity],
+        passthrough: device.isProgram,
+        options: { output: { type: "string", value: "DIRECTORY", help: "image directory (default: a new temporary directory)" } },
+        run: device.run,
+      },
+      { name: "reset", short: "Reset the session", args: [0, 0], run: device.reset },
+      { name: "api", short: "Print the TypeScript declarations of the globals", args: [0, 0], run: device.api },
+      dataCommands("", device.replData),
+    ],
   },
+  { name: "version", short: "Print the version", args: [0, 0], run: device.printVersion },
 ];
 
 const root = { name: "swipt", short: "Operate a device through Swipt", commands };
@@ -167,6 +207,9 @@ function usage(trail) {
   } else {
     lines.push(`usage: ${trail.slice(0, -1).map(it => it.name).join(" ")} ${command.use ?? command.name}`.replace(/ +/g, " "));
   }
+  if (command.description) {
+    lines.push("", ...command.description);
+  }
   const options = { ...trail.reduce((found, it) => ({ ...found, ...it.options }), {}), ...globalOptions };
   lines.push("", "options:");
   lines.push(...columns(Object.entries(options).map(([option, it]) => [`  ${it.short ? `-${it.short}, ` : ""}--${option}${it.value ? ` ${it.value}` : ""}`, it.help])).split("\n"));
@@ -179,18 +222,19 @@ function columns(rows) {
 }
 
 function resolve(argv) {
-  const loose = parseArgs({ args: argv, options: { ...parseOptions(globalOptions), ...allOptions(root) }, allowPositionals: true, strict: false });
+  const loose = parseArgs({ args: argv, options: { ...parseOptions(globalOptions), ...allOptions(root) }, allowPositionals: true, strict: false, tokens: true });
+  const positionals = loose.tokens.filter(token => token.kind === "positional");
   const trail = [root];
   let consumed = 0;
-  let help = loose.positionals[0] === "help";
+  let help = positionals[0]?.value === "help";
   if (help) {
     consumed++;
   }
   while (trail.at(-1).commands) {
     const current = trail.at(-1);
-    const word = loose.positionals[consumed];
+    const word = positionals[consumed]?.value;
     if (word === undefined) {
-      if (help || current !== root || argv.length === 0) {
+      if (help || loose.values.help || current !== root || argv.length === 0) {
         return { trail, help: true };
       }
       throw new UsageError("a command is missing");
@@ -202,18 +246,21 @@ function resolve(argv) {
     trail.push(found);
     consumed++;
   }
+  const command = trail.at(-1);
   const options = trail.reduce((found, it) => ({ ...found, ...it.options }), {});
+  const first = positionals[consumed];
+  const verbatim = first !== undefined && command.passthrough?.(first.value) ? first.index + 1 : argv.length;
   let parsed;
   try {
-    parsed = parseArgs({ args: argv, options: { ...parseOptions(globalOptions), ...parseOptions(options) }, allowPositionals: true, strict: true });
+    parsed = parseArgs({ args: argv.slice(0, verbatim), options: { ...parseOptions(globalOptions), ...parseOptions(options) }, allowPositionals: true, strict: true });
   } catch (error) {
-    throw new UsageError(error.message);
+    const option = error.message.match(/^Unknown option '(-[^']*)'/)?.[1];
+    throw new UsageError(option === undefined ? error.message : `${option} is not an option of ${JSON.stringify(trail.map(it => it.name).join(" "))}`);
   }
   if (parsed.values.help) {
     help = true;
   }
-  const args = parsed.positionals.slice(consumed);
-  const command = trail.at(-1);
+  const args = [...parsed.positionals.slice(consumed), ...argv.slice(verbatim)];
   if (!help && (args.length < command.args[0] || args.length > command.args[1])) {
     const [least, most] = command.args;
     const expected = least === most ? `${least} arg(s)` : most === Infinity ? `at least ${least} arg(s)` : `between ${least} and ${most} arg(s)`;
@@ -234,7 +281,7 @@ function printError(error, target, operation) {
         message = `Swipt at ${target.url} is unreachable: ${message}`;
         break;
       case Code.Unauthenticated:
-        message += `; connect with the URL from Swipt › Developer: swipt connect ${connection.withToken(target.url)}`;
+        message += `; connect with the URL from Swipt › Developer: swipt device add ${connection.withToken(target.url)}`;
         break;
       case Code.Unimplemented:
         message = `Swipt at ${target.url} does not have this command; update Swipt`;
@@ -262,9 +309,6 @@ async function main() {
     }
     const command = resolved.trail.at(-1);
     const values = command.parse ? command.parse(resolved.values) : resolved.values;
-    if (values.project !== undefined) {
-      sources.root = path.resolve(values.project);
-    }
     await command.run({ args: resolved.args, options: values, target, signal: interrupt.signal, printError: (error, operation) => printError(error, target, operation) });
   } catch (error) {
     if (error instanceof FalseResult) {

package/sourcemap.mjs

@@ -1,77 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-
-import { TraceMap, originalPositionFor } from "@jridgewell/trace-mapping";
-
-import { loadProject } from "./project.mjs";
-
-const suffix = ".map";
-
-function loadSourceMap(name) {
-  const raw = JSON.parse(fs.readFileSync(name, "utf8"));
-  const directory = path.dirname(name);
-  const working = process.cwd();
-  const resolve = source => {
-    const resolved = path.join(directory, raw.sourceRoot ?? "", source);
-    const relative = path.relative(working, resolved);
-    return relative.startsWith("..") || path.isAbsolute(relative) ? resolved : relative;
-  };
-  const map = new TraceMap({ ...raw, sourceRoot: undefined });
-  return (line, column) => {
-    const found = originalPositionFor(map, { line, column: column - 1 });
-    return found.source === null ? undefined : { file: resolve(found.source), line: found.line, column: found.column + 1 };
-  };
-}
-
-export class SourceMaps {
-  root = "";
-  loaded = new Map();
-
-  forSwiplet(id) {
-    if (this.root === "") {
-      return {};
-    }
-    if (this.loaded.has(id)) {
-      return this.loaded.get(id);
-    }
-    const found = {};
-    let project;
-    try {
-      project = loadProject(this.root);
-    } catch {
-      project = undefined;
-    }
-    if (project?.config.id === id) {
-      const directory = path.join(project.root, "dist", id, "src");
-      let names = [];
-      try {
-        names = fs.readdirSync(directory).filter(name => name.endsWith(suffix));
-      } catch {
-        names = [];
-      }
-      for (const name of names) {
-        try {
-          found[name.slice(0, -suffix.length)] = loadSourceMap(path.join(directory, name));
-        } catch {
-          continue;
-        }
-      }
-    }
-    this.loaded.set(id, found);
-    return found;
-  }
-
-  forget(id) {
-    this.loaded.delete(id);
-  }
-
-  frame(id) {
-    return frame => {
-      const lookup = this.forSwiplet(id)[frame.file];
-      const mapped = lookup?.(frame.line, frame.column);
-      return mapped ? { ...frame, ...mapped } : frame;
-    };
-  }
-}
-
-export const sources = new SourceMaps();