@wirecat/cli-core 0.369.0 → 0.370.0

package/CHANGELOG.md

@@ -7,6 +7,21 @@ shape of this file.
 
 ## Unreleased
 
+## 0.370.0 — 20.10.2026
+
+### Changed — may break callers
+
+- **`checkGuide` finds a scenario step a shell would change**, so a tool's guide test that passed may now fail. It
+  splits each step as a POSIX shell does and reports `>`, `<`, `|`, `&`, `;`, `` ` ``, `$(` and the globs `*`, `?`,
+  `[` left outside quotes (`` ` `` and `$(` also inside double quotes), and a quote never closed. `max review
+  date>1d` passed before, though a shell writes a file named `1d` and drops the filter. Quote the word:
+  `'date>1d'`. `shellProblems(run)` gives the same check for one step.
+
+### Added
+
+- **`MEMO_SCENARIOS` holds the titles of memo's cross-tool scenarios** (`personBrief`, `decisionTrail`), so every
+  tool's "Works with" list takes them from one place instead of typing its own copy.
+
 ## 0.369.0 — 20.10.2026
 
 ### Fixed

package/dist/cli/guide.d.ts

@@ -18,6 +18,19 @@ export interface GuideReference {
     name: string;
     title: string;
 }
+/** memo's cross-tool scenarios: the one source of the titles every tool lists, and memo's files must carry. */
+export declare const MEMO_SCENARIOS: {
+    readonly personBrief: {
+        readonly tool: "memo";
+        readonly name: "person-brief";
+        readonly title: "One person across every tool";
+    };
+    readonly decisionTrail: {
+        readonly tool: "memo";
+        readonly name: "decision-trail";
+        readonly title: "What did we decide about X, across every source";
+    };
+};
 export interface GuideOptions {
     /** Absolute path of the tool's scenario files: `fileURLToPath(new URL("../scenarios", import.meta.url))`. */
     directory: string;
@@ -40,6 +53,8 @@ export declare const loadScenarios: (directory: string) => Promise<{
  * program is built. `checkGuide` validates them in the tool's CI.
  */
 export declare const guideCommand: (app: Pick<AppIdentity, "command">, options: GuideOptions) => Command;
+/** Characters in a step that a shell would act on: the person who copies it would run something else. */
+export declare const shellProblems: (run: string) => string[];
 /** What is wrong with one step on this program: the path, each option and its value, the arguments. Never runs it. */
 export declare const checkStep: (program: Command, run: string) => string[];
 /**

package/dist/cli/guide.js

@@ -7,6 +7,11 @@ import { environmentOf, outputFor } from "./context.js";
 import { NO_EFFECTS } from "./effects.js";
 import { itemOf, listOf, renderAnswer } from "./envelope.js";
 import { PROFILE_FREE } from "./profile.js";
+/** memo's cross-tool scenarios: the one source of the titles every tool lists, and memo's files must carry. */
+export const MEMO_SCENARIOS = {
+    personBrief: { tool: "memo", name: "person-brief", title: "One person across every tool" },
+    decisionTrail: { tool: "memo", name: "decision-trail", title: "What did we decide about X, across every source" },
+};
 const FRONT_MATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
 const FIELDS = new Set(["title", "goal", "steps", "look"]);
 const NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -157,17 +162,49 @@ export const guideCommand = (app, options) => {
     guides.set(command, options);
     return command;
 };
-/** A step's words, split as a shell would on spaces, with "…" and '…' kept together. */
-const words = (line) => {
+const OPERATORS = {
+    ">": "redirects output to a file",
+    "<": "reads input from a file",
+    "|": "pipes into another command",
+    "&": "runs the command in the background",
+    ";": "ends the command there",
+    "`": "runs it as a command",
+    "$(": "runs it as a command",
+    "*": "expands it to file names",
+    "?": "expands it to file names",
+    "[": "expands it to file names",
+};
+/**
+ * A step split into words as a POSIX shell would — '…' literal, "…" with \ escapes, \ outside quotes — and the
+ * characters a shell would act on instead of passing them to the tool. `` ` `` and `$(` still act inside "…".
+ */
+const scan = (line) => {
     const found = [];
+    const live = new Set();
     let word;
     let quote;
-    for (const char of line) {
-        if (quote) {
-            if (char === quote)
+    for (let index = 0; index < line.length; index++) {
+        const char = line[index];
+        const next = line[index + 1];
+        if (quote === "'") {
+            if (char === "'")
                 quote = undefined;
             else
-                word = (word ?? "") + char;
+                word += char;
+            continue;
+        }
+        if (char === "\\" && next !== undefined && (quote === undefined || '$`"\\'.includes(next))) {
+            word = (word ?? "") + next;
+            index++;
+            continue;
+        }
+        if (char === "`" || (char === "$" && next === "("))
+            live.add(char === "`" ? "`" : "$(");
+        if (quote === '"') {
+            if (char === '"')
+                quote = undefined;
+            else
+                word += char;
         }
         else if (char === '"' || char === "'") {
             quote = char;
@@ -178,12 +215,24 @@ const words = (line) => {
                 found.push(word);
             word = undefined;
         }
-        else
+        else {
+            if (OPERATORS[char])
+                live.add(char);
             word = (word ?? "") + char;
+        }
     }
     if (word !== undefined)
         found.push(word);
-    return found;
+    return { words: found, live: [...live], open: quote !== undefined };
+};
+const words = (line) => scan(line).words;
+/** Characters in a step that a shell would act on: the person who copies it would run something else. */
+export const shellProblems = (run) => {
+    const { live, open } = scan(run);
+    return [
+        ...live.map((char) => `a shell acts on ${char}: it ${OPERATORS[char]}; put the word in single quotes`),
+        ...(open ? ["a quote is never closed"] : []),
+    ];
 };
 const silent = (command) => command.exitOverride().configureOutput({ writeOut: () => { }, writeErr: () => { }, outputError: () => { } });
 const ownerOf = (chain, flag) => {
@@ -295,7 +344,7 @@ export const checkGuide = async (build, { packageRoot } = {}) => {
     const { scenarios, problems } = await loadScenarios(options.directory);
     for (const scenario of scenarios)
         scenario.steps.forEach((step, index) => {
-            for (const problem of checkStep(build(), step.run))
+            for (const problem of [...shellProblems(step.run), ...checkStep(build(), step.run)])
                 problems.push(`${scenario.name}.md step ${index + 1} (${step.run}): ${problem}`);
         });
     for (const reference of options.worksWith ?? [])

package/dist/cli/index.d.ts

@@ -56,7 +56,7 @@ export { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
 export { changesAuthority, destroysNothing, FETCH, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, REMOTE_READ, REMOTE_WRITE, reachesOtherService, refuseUnderReadOnly, } from "./effects.js";
 export { type AnswerOutput, answerSchema, type Body, type ItemBody, itemAnswer, itemOf, jsonlRecords, judgedAnswer, type ListBody, type ListInput, listOf, metaNow, printItem, renderAnswer, sealed, snakeKeys, snakeKeysKeeping, } from "./envelope.js";
 export { withAbort } from "./execution.js";
-export { checkGuide, checkStep, type GuideOptions, type GuideReference, type GuideStep, guideCommand, loadScenarios, type Scenario, } from "./guide.js";
+export { checkGuide, checkStep, type GuideOptions, type GuideReference, type GuideStep, guideCommand, loadScenarios, MEMO_SCENARIOS, type Scenario, shellProblems, } from "./guide.js";
 export { type CommandHelp, commandHelp, commandHelpMarkdown, commandHelpText, exampleReport, type NextChoice, nextUsually, } from "./help/command-help.js";
 export { commandsText } from "./help/commands-text.js";
 export { type FirstScreen, type FirstScreenLine, firstScreen, installHelp, WIRECAT_TOOLS, } from "./help/first-screen.js";

package/dist/cli/index.js

@@ -51,7 +51,7 @@ export { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
 export { changesAuthority, destroysNothing, FETCH, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, REMOTE_READ, REMOTE_WRITE, reachesOtherService, refuseUnderReadOnly, } from "./effects.js";
 export { answerSchema, itemAnswer, itemOf, jsonlRecords, judgedAnswer, listOf, metaNow, printItem, renderAnswer, sealed, snakeKeys, snakeKeysKeeping, } from "./envelope.js";
 export { withAbort } from "./execution.js";
-export { checkGuide, checkStep, guideCommand, loadScenarios, } from "./guide.js";
+export { checkGuide, checkStep, guideCommand, loadScenarios, MEMO_SCENARIOS, shellProblems, } from "./guide.js";
 export { commandHelp, commandHelpMarkdown, commandHelpText, exampleReport, nextUsually, } from "./help/command-help.js";
 export { commandsText } from "./help/commands-text.js";
 export { firstScreen, installHelp, WIRECAT_TOOLS, } from "./help/first-screen.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.369.0",
+  "version": "0.370.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",