textrun-shell 0.3.0 → 0.4.0

package/README.md

@@ -3,55 +3,79 @@
 This package provides [Text-Runner](https://github.com/kevgo/text-runner)
 actions for documenting console commands to be executed by the reader.
 
-### Setup
+## Setup
 
-To add this package as a Text-Runner plugin, run <code type="npm/install">npm i
--D textrun-shell</code>.
+To add this package as a Text-Runner plugin:
+
+<pre type="npm/install">
+npm i -D textrun-shell
+</pre>
 
 <!-- TODO: verify this somehow -->
 
-You can define the absolute path of documented binaries in a
-**textrun-shell.js** file in the root directory of your documentation. Here is
-an example:
+You can define the absolute path of binaries that your documentation tests call
+by creating a file **textrun-shell.js** file in the root directory of your
+documentation. Here is an example:
 
 ```js
+import * as path from "path"
+import * as url from "url"
+
+const __dirname = url.fileURLToPath(new URL(".", import.meta.url))
+const foo_path = path.join(__dirname, "bin", "foo")
+// console.log(`calling "foo" in the documentation now runs ${foo_path}`)
+
 export default {
-  binaries: {
-    "text-runner": path.join(__dirname, "node_modules", ".bin", "text-runner")
+  globals: {
+    "foo": foo_path
   }
 }
 ```
 
-### Run shell commands
+## shell/command
 
 The <b type="action/name-full">shell/command</b> action runs a shell command and
-waits until it finishes. As an example, here is a little hypothetical Shell
-tutorial:
-
-> The "echo" command prints text on the command line. For example, let's run:
->
-> ```
-> $ echo Hello world!
-> ```
->
-> It welcomes us with a nice greeting:
->
-> ```
-> Hello world!
-> ```
-
-The source code of this Shell tutorial when executed and verified by Text-Runner
-looks like this:
+waits until it finishes. The <b type="action/name-full">shell/command-output</b>
+action verifies the output of the most recently executed shell command.
+
+As an example, here is a hypothetical tutorial for how to use the Linux shell:
 
 <a type="extension/runnable-region">
 
-```md
+```html
 The "echo" command prints text on the command line. For example, let's run:
 
 <pre type="shell/command">
 echo Hello world!
 </pre>
+```
+
+</a>
+
+Some tutorials print a dollar sign at the beginning of the command to execute,
+indicating an interactive command prompt. These dollar signs are ignored.
+
+### allow-error attribute
+
+By default, this step fails if the subshell command exits with a non-zero exit
+code. To allow errors, add the `allow-error` attribute, like so:
+
+```html
+<pre type="shell/command" allow-error>
+echo Hello world!
+</pre>
+```
+
+## shell/command-output
+
+The <b type="action/name-full">shell/command-output</b> action verifies the
+output of the most recently executed shell command.
+
+Here is the next paragraph of our hypothetical tutorial for the Linux shell:
+
+<a type="extension/runnable-region">
 
+```md
 It welcomes us with a nice greeting:
 
 <pre type="shell/command-output">
@@ -61,11 +85,10 @@ Hello world!
 
 </a>
 
-Dollar signs at the beginning of lines indicate a shell prompt and are ignored.
-The <b type="action/name-full">shell/command-output</b> action documents output
-of the last shell command run.
+Some tutorials print a dollar sign at the beginning of the command to execute,
+indicating an interactive command prompt. These dollar signs are ignored.
 
-### User input
+## shell/command-with-input
 
 You can run a shell command and enter text into it with the
 <b type="action/name-full">shell/command-with-input</b> action.
@@ -115,7 +138,7 @@ and provide user input with an HTML table:
   </tr>
   <tr>
     <td>which day is today</td>
-    <td>Friday</td>
+    <td>Monday</td>
   </tr>
 </table>
 
@@ -124,22 +147,23 @@ and provide user input with an HTML table:
 It prints:
 
 <pre type="shell/command-output">
-Hello Text-Runner, happy Friday!
-</pre>.
+Hello Text-Runner, happy Monday!
+</pre>
 
 If the table contains multiple columns, the first column contains output to wait
 for, and the last one text to enter once the output from the first column has
 appeared. Middle columns are ignored. `<th>` elements are considered
 descriptions and are also ignored.
 
-### Long-running processes
+## shell/server
 
 Long-running processes, for example web or database servers, keep running while
 Text-Runner continues executing other actions.
 
 <a type="workspace/new-file">
 
-As an example, let's say we have a server called **server.js**:
+As an example, let's say we write a tutorial about developing a web server, have
+just created an implementation in file **server.js**:
 
 ```js
 console.log("server is running")
@@ -148,11 +172,9 @@ setTimeout(() => {}, 100_000)
 
 </a>
 
-Start this long-running server to run in parallel with Text-Runner with the
-<b type="action/name-full">shell/server</b> action. Wait for output using the
-<b type="action/name-full">shell/server-output</b> action. Stop the server with
-the <b type="action/name-full">shell/stop-server</b> action. Here is an example
-that shows them in action:
+Our tutorial instructs the user to start this long-running server to run in
+parallel with Text-Runner with the
+<b type="action/name-full">shell/server</b> action:
 
 <a type="extension/runnable-region">
 
@@ -162,16 +184,46 @@ Start the server:
 <pre type="shell/server">
 node server.js
 </pre>
+```
+
+</a>
+
+## shell/server-output
 
-Wait until it is fully booted up:
+After we started a long-running server through
+<em type="action/name-full">shell/server</em> above, we can await specific
+output from it using the
+<b type="action/name-full">shell/server-output</b> action.
+
+Here is the next paragraph of our hypothetic server tutorial:
+
+<a type="extension/runnable-region">
+
+```html
+Wait until the server is fully booted up:
 
 <pre type="shell/server-output">
 server is running
 </pre>
-
-Now you can interact with the server. When you are done, stop the server:
-<a type="shell/stop-server">shell/stop-server</a>
 ```
 
 </a>
+
+## shell/stop-server
+
+Stop a long-running process with the
+<b type="action/name-full">shell/stop-server</b> action.
+
+Here is the final part of our hypothetical server tutorial:
+
+<a type="extension/runnable-region">
+
+```html
+When you are done, stop the server:
+
+<pre type="shell/stop-server">
+killall node
+</pre>
 ```
+
+</a>

package/dist/actions/command-with-input.js

@@ -1,4 +1,4 @@
-import * as color from "colorette";
+import { styleText } from "node:util";
 import * as observableProcess from "observable-process";
 import { callArgs } from "textrun-extension";
 import { CurrentCommand } from "../helpers/current-command.js";
@@ -18,7 +18,7 @@ export async function commandWithInput(action) {
     if (commandsToRun === "") {
         throw new Error(`the <${action.region[0].tag} ${action.configuration.regionMarker}="exec-with-input"> region contains no commands to run`);
     }
-    action.name(`running console command: ${color.cyan(commandsToRun)}`);
+    action.name(`running console command: ${styleText("cyan", commandsToRun)}`);
     let input = [];
     if (action.region.hasNodeOfType("table")) {
         input = getInput(action.region);

package/dist/actions/command.js

@@ -1,4 +1,4 @@
-import * as color from "colorette";
+import { styleText } from "node:util";
 import * as observableProcess from "observable-process";
 import * as trExt from "textrun-extension";
 import { Configuration } from "../helpers/configuration.js";
@@ -6,6 +6,7 @@ import { CurrentCommand } from "../helpers/current-command.js";
 import { trimDollar } from "../helpers/trim-dollar.js";
 /** Runs the given commands synchronously on the console. */
 export async function command(action) {
+    action.name("run shell command");
     const configPath = action.configuration.sourceDir.joinStr("textrun-shell.js");
     const config = await Configuration.load(configPath);
     const commandsToRun = action.region
@@ -19,7 +20,8 @@ export async function command(action) {
     if (commandsToRun === "") {
         throw new Error(`the <${action.region[0].tag} ${action.configuration.regionMarker}="shell/command"> region contains no commands to run`);
     }
-    action.name(`running console command: ${color.cyan(commandsToRun)}`);
+    const allowError = action.region[0].attributes["allow-error"] !== undefined;
+    action.name(`running console command: ${styleText("cyan", commandsToRun)}`);
     const processor = observableProcess.start(trExt.callArgs(commandsToRun, process.platform), {
         cwd: action.configuration.workspace.platformified()
     });
@@ -27,7 +29,7 @@ export async function command(action) {
     const finished = (await processor.waitForEnd());
     action.log(finished.combinedText);
     CurrentCommand.set(finished);
-    if (finished.exitCode !== 0) {
+    if (finished.exitCode !== 0 && !allowError) {
         throw new Error(`command "${commandsToRun}" failed with exit code ${finished.exitCode}`);
     }
 }

package/dist/actions/server.js

@@ -1,4 +1,4 @@
-import * as color from "colorette";
+import { styleText } from "node:util";
 import * as observableProcess from "observable-process";
 import * as trExt from "textrun-extension";
 import { CurrentServer } from "../helpers/current-server.js";
@@ -15,7 +15,7 @@ export function server(action) {
         .filter((line) => line.length > 0)
         .map(trimDollar)
         .join(" && ");
-    action.name(`starting a server process: ${color.bold(color.cyan(commandsToRun))}`);
+    action.name(`starting a server process: ${styleText(["bold", "cyan"], commandsToRun)}`);
     CurrentServer.instance().set(observableProcess.start(trExt.callArgs(commandsToRun, process.platform), {
         cwd: action.configuration.workspace.platformified()
     }));

package/dist/helpers/configuration.js

@@ -1,4 +1,6 @@
+import Debug from "debug";
 import { PathMapper } from "./path-mapper.js";
+const debug = Debug("shell");
 /** Configuration represents the configuration options for the textrun-shell library. */
 export class Configuration {
     constructor(file) {
@@ -13,10 +15,12 @@ export class Configuration {
     static async load(filePath) {
         try {
             const content = await import(filePath);
+            debug(`found path mapping in ${filePath}`);
             const config = content.default;
             return new Configuration(config);
         }
         catch (e) {
+            debug(`found no path mapping in ${filePath}`);
             return Configuration.default();
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "textrun-shell",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "ISC",
   "type": "module",
   "exports": "./dist/index.js",
@@ -9,29 +9,29 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig-build.json",
-    "clean": "rm -rf dist",
     "cuke": "cucumber-js --format=progress",
     "doc": "text-runner",
-    "fix": "eslint --fix --ignore-pattern=dist/ . && dprint fmt && sort-package-json --quiet",
+    "fix": "eslint --fix --ignore-pattern=dist/ . && dprint fmt && sort-package-json --quiet && ../tools/rta ghokin fmt replace features",
     "lint": "dprint check && sort-package-json --check --quiet && eslint --ignore-pattern=dist/ . && depcheck --config=../.depcheckrc",
+    "reset": "rm -rf dist && yarn run build",
     "unit": "node --test --import tsx 'src/**/*.test.ts'"
   },
   "dependencies": {
-    "assert-no-diff": "3.0.6",
-    "colorette": "2.0.20",
-    "end-child-processes": "1.0.3",
-    "observable-process": "8.0.0-pre4",
-    "strip-ansi": "7.1.0",
-    "text-runner-engine": "7.1.0",
-    "textrun-extension": "0.3.0"
+    "assert-no-diff": "4.1.0",
+    "debug": "4.4.3",
+    "end-child-processes": "2.0.3",
+    "observable-process": "8.0.0",
+    "strip-ansi": "7.1.2",
+    "text-runner-engine": "7.2.0",
+    "textrun-extension": "0.4.0"
   },
   "devDependencies": {
     "shared-cucumber-steps": "*",
-    "text-runner": "7.1.0",
-    "textrun-action": "0.3.0",
-    "textrun-extension": "0.3.0",
-    "textrun-workspace": "0.3.0",
-    "tsx": "4.19.3"
+    "text-runner": "7.2.0",
+    "textrun-action": "0.4.0",
+    "textrun-extension": "0.4.0",
+    "textrun-workspace": "0.4.0",
+    "tsx": "4.20.6"
   },
-  "gitHead": "bdf119a8e549f679af14f88952f7353648b50759"
+  "gitHead": "aecf7efd5e22e88535fe97ad7341b1a057520268"
 }