@sasjs/cli 6.21.0 → 6.23.0

package/build/cli.d.ts

@@ -1,2 +1,20 @@
+/**
+ * The line printed when the arguments name no command the CLI registers.
+ *
+ * Kept apart from the printing so it can be asserted without standing up a
+ * logger, and so the two cases - a typo, and no argument at all - stay
+ * distinguishable in a script's output.
+ *
+ * @param name - the command as typed, empty when none was given
+ */
+export declare const unknownCommandMessage: (name: string) => string;
+/**
+ * The registered command nearest to what was typed, when one is close enough to
+ * be worth naming - so `sasjs lc` finds `logcheck` rather than only saying no.
+ *
+ * @param name - the command as typed
+ * @returns the suggestion, or `undefined` when nothing is close
+ */
+export declare const closestCommand: (name: string) => string | undefined;
 export declare function cli(args: string[]): Promise<void>;
 export declare function instantiateLogger(): Promise<void>;

package/build/cli.js

@@ -36,29 +36,103 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
     }
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.closestCommand = exports.unknownCommandMessage = void 0;
 exports.cli = cli;
 exports.instantiateLogger = instantiateLogger;
 var logger_1 = require("@sasjs/utils/logger");
 var utils_1 = require("./utils");
 var parse_1 = require("./types/command/parse");
+var help_1 = require("./commands/help/help");
+var command_1 = require("./types/command");
+/**
+ * The line printed when the arguments name no command the CLI registers.
+ *
+ * Kept apart from the printing so it can be asserted without standing up a
+ * logger, and so the two cases - a typo, and no argument at all - stay
+ * distinguishable in a script's output.
+ *
+ * @param name - the command as typed, empty when none was given
+ */
+var unknownCommandMessage = function (name) {
+    return name
+        ? "Invalid SASjs command: ".concat(name, ".")
+        : 'No command given - here is what this CLI can do.';
+};
+exports.unknownCommandMessage = unknownCommandMessage;
+/**
+ * The registered command nearest to what was typed, when one is close enough to
+ * be worth naming - so `sasjs lc` finds `logcheck` rather than only saying no.
+ *
+ * @param name - the command as typed
+ * @returns the suggestion, or `undefined` when nothing is close
+ */
+var closestCommand = function (name) {
+    var _a;
+    var typed = name.toLowerCase();
+    var names = (0, parse_1.commandNames)();
+    return (_a = names
+        .map(function (candidate) { return ({
+        candidate: candidate,
+        // A prefix is what the user was reaching for, so it outranks a short
+        // edit distance: `logc` means `logcheck`, not `doc`.
+        prefix: candidate.toLowerCase().startsWith(typed),
+        distance: editDistance(typed, candidate.toLowerCase())
+    }); })
+        .filter(function (_a) {
+        var prefix = _a.prefix, distance = _a.distance;
+        return prefix || distance <= 2;
+    })
+        .sort(function (a, b) { return Number(b.prefix) - Number(a.prefix) || a.distance - b.distance; })[0]) === null || _a === void 0 ? void 0 : _a.candidate;
+};
+exports.closestCommand = closestCommand;
+var editDistance = function (a, b) {
+    var rows = Array.from({ length: a.length + 1 }, function (_, i) { return [i]; });
+    for (var j = 1; j <= b.length; j++)
+        rows[0][j] = j;
+    for (var i = 1; i <= a.length; i++) {
+        for (var j = 1; j <= b.length; j++) {
+            rows[i][j] = Math.min(rows[i - 1][j] + 1, rows[i][j - 1] + 1, rows[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+    }
+    return rows[a.length][b.length];
+};
 function cli(args) {
     return __awaiter(this, void 0, void 0, function () {
-        var command, returnCode;
-        return __generator(this, function (_a) {
-            switch (_a.label) {
+        var command, name_1, suggestion, returnCode;
+        var _a, _b, _c, _d;
+        return __generator(this, function (_e) {
+            switch (_e.label) {
                 case 0: return [4 /*yield*/, (0, utils_1.setProjectDir)(args)];
                 case 1:
-                    _a.sent();
+                    _e.sent();
                     return [4 /*yield*/, instantiateLogger()];
                 case 2:
-                    _a.sent();
+                    _e.sent();
                     return [4 /*yield*/, (0, utils_1.loadProjectEnvVariables)()];
                 case 3:
-                    _a.sent();
+                    _e.sent();
                     command = (0, parse_1.parse)(args);
-                    return [4 /*yield*/, command.execute()];
+                    if (!!command) return [3 /*break*/, 6];
+                    name_1 = (0, parse_1.requestedCommandName)(args);
+                    (_a = process.logger) === null || _a === void 0 ? void 0 : _a.error((0, exports.unknownCommandMessage)(name_1));
+                    if (!!name_1) return [3 /*break*/, 5];
+                    return [4 /*yield*/, (0, help_1.printHelpText)()];
                 case 4:
-                    returnCode = _a.sent();
+                    _e.sent();
+                    process.exit(command_1.ReturnCode.InvalidCommand);
+                    return [2 /*return*/];
+                case 5:
+                    suggestion = (0, exports.closestCommand)(name_1);
+                    if (suggestion) {
+                        (_b = process.logger) === null || _b === void 0 ? void 0 : _b.info("Did you mean `sasjs ".concat(suggestion, "`?"));
+                    }
+                    (_c = process.logger) === null || _c === void 0 ? void 0 : _c.info("Commands: ".concat((0, parse_1.commandNames)().sort().join(', ')));
+                    (_d = process.logger) === null || _d === void 0 ? void 0 : _d.info('Run `sasjs help` for the full text, or `sasjs <command> --help` for one command.');
+                    process.exit(command_1.ReturnCode.InvalidCommand);
+                    return [2 /*return*/];
+                case 6: return [4 /*yield*/, command.execute()];
+                case 7:
+                    returnCode = _e.sent();
                     process.exit(returnCode);
                     return [2 /*return*/];
             }

package/build/cli.spec.js

@@ -89,6 +89,7 @@ var test_1 = require("./utils/test");
 var envVariablesModule = __importStar(require("./utils/loadEnvVariables"));
 var projectDirModule = __importStar(require("./utils/setProjectDir"));
 var parseModule = __importStar(require("./types/command/parse"));
+var helpModule = __importStar(require("./commands/help/help"));
 var utils_1 = require("@sasjs/utils");
 var commandBase_1 = require("./types/command/commandBase");
 var command_1 = require("./types/command");
@@ -163,6 +164,81 @@ describe('CLI command parsing', function () {
             }
         });
     }); });
+    describe('when the arguments name no command', function () {
+        var helpSpy = function () {
+            return jest
+                .spyOn(helpModule, 'printHelpText')
+                .mockImplementation(function () {
+                return Promise.resolve({ outputCommands: '', outputAliases: '' });
+            });
+        };
+        it('should print the whole help when no command is given', function () { return __awaiter(void 0, void 0, void 0, function () {
+            var help;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        jest.spyOn(parseModule, 'parse').mockImplementation(function () { return undefined; });
+                        jest
+                            .spyOn(parseModule, 'requestedCommandName')
+                            .mockImplementation(function () { return ''; });
+                        jest.spyOn(parseModule, 'commandNames').mockImplementation(function () { return ['run']; });
+                        help = helpSpy();
+                        return [4 /*yield*/, (0, cli_1.cli)(['node', 'sasjs'])];
+                    case 1:
+                        _a.sent();
+                        expect(help).toHaveBeenCalledTimes(1);
+                        expect(process.exit).toHaveBeenCalledWith(command_1.ReturnCode.InvalidCommand);
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        it('should list the commands when the name is unknown', function () { return __awaiter(void 0, void 0, void 0, function () {
+            var help;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        jest.spyOn(parseModule, 'parse').mockImplementation(function () { return undefined; });
+                        jest
+                            .spyOn(parseModule, 'requestedCommandName')
+                            .mockImplementation(function () { return 'frobnicate'; });
+                        jest
+                            .spyOn(parseModule, 'commandNames')
+                            .mockImplementation(function () { return ['run', 'lint']; });
+                        help = helpSpy();
+                        return [4 /*yield*/, (0, cli_1.cli)(['node', 'sasjs', 'frobnicate'])
+                            // The full text is for `sasjs` on its own; a typo gets the list, which is
+                            // the part that answers it, rather than two hundred lines.
+                        ];
+                    case 1:
+                        _a.sent();
+                        // The full text is for `sasjs` on its own; a typo gets the list, which is
+                        // the part that answers it, rather than two hundred lines.
+                        expect(help).not.toHaveBeenCalled();
+                        expect(parseModule.commandNames).toHaveBeenCalled();
+                        expect(process.exit).toHaveBeenCalledWith(command_1.ReturnCode.InvalidCommand);
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        it('should not execute anything', function () { return __awaiter(void 0, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        jest.spyOn(parseModule, 'parse').mockImplementation(function () { return undefined; });
+                        jest
+                            .spyOn(parseModule, 'requestedCommandName')
+                            .mockImplementation(function () { return 'x'; });
+                        jest.spyOn(parseModule, 'commandNames').mockImplementation(function () { return []; });
+                        helpSpy();
+                        return [4 /*yield*/, (0, cli_1.cli)(['node', 'sasjs', 'x'])];
+                    case 1:
+                        _a.sent();
+                        expect(mockCommand.execute).not.toHaveBeenCalled();
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+    });
     it('should return with the correct exit code on errors', function () { return __awaiter(void 0, void 0, void 0, function () {
         return __generator(this, function (_a) {
             switch (_a.label) {
@@ -179,6 +255,25 @@ describe('CLI command parsing', function () {
         });
     }); });
 });
+describe('closestCommand', function () {
+    it('suggests a command one letter away', function () {
+        expect((0, cli_1.closestCommand)('logchek')).toEqual('logcheck');
+    });
+    it('suggests the command a prefix belongs to', function () {
+        expect((0, cli_1.closestCommand)('logc')).toEqual('logcheck');
+    });
+    it('suggests nothing when the name is unrelated', function () {
+        expect((0, cli_1.closestCommand)('frobnicate')).toBeUndefined();
+    });
+});
+describe('unknownCommandMessage', function () {
+    it('names the command that was typed', function () {
+        expect((0, cli_1.unknownCommandMessage)('frobnicate')).toEqual('Invalid SASjs command: frobnicate.');
+    });
+    it('says no command was given when there is none', function () {
+        expect((0, cli_1.unknownCommandMessage)('')).toEqual('No command given - here is what this CLI can do.');
+    });
+});
 var setupMocks = function () {
     jest.resetAllMocks();
     (0, test_1.mockProcessExit)();
@@ -191,5 +286,13 @@ var setupMocks = function () {
         .spyOn(projectDirModule, 'setProjectDir')
         .mockImplementation(function () { return Promise.resolve(); });
     jest.spyOn(parseModule, 'parse').mockImplementation(function () { return mockCommand; });
+    jest
+        .spyOn(parseModule, 'requestedCommandName')
+        .mockImplementation(function () { return 'mock'; });
+    jest
+        .spyOn(helpModule, 'printHelpText')
+        .mockImplementation(function () {
+        return Promise.resolve({ outputCommands: '', outputAliases: '' });
+    });
     jest.spyOn(mockCommand, 'execute');
 };

package/build/commands/build/internal/mockSite/assets/runtime-core.js

@@ -1525,6 +1525,9 @@ const api = {
     bytes: [...FILES.keys()].reduce((total, abs) => total + entrySizeAt(abs), 0)
   }),
   run: (payload) => runProgram(payload),
+  // the file a program names, so the host can tell a .sas program from a .js one
+  // and refuse the former instead of compiling SAS source as JavaScript
+  resolveProgram: (program) => resolveProgram(program),
   // the drive's bytes, for @sasjs/api's services: the rules that decide a
   // status are the package's, so this host hands over storage and nothing else
   driveStore,

package/build/commands/build/internal/mockSite/assets/sw.js

@@ -181,19 +181,21 @@ const SEEDED_HEADER_LINE = String(R.HEADERS_SEED)
  * it.
  */
 const artifactOf = (result, debug) => {
-  if (debug)
+  if (debug) {
+    // webout SEP log SEP [listing] - the framing @sasjs/adapter and the Studio's
+    // parser both split on, so a recorded session reads the same as a real one.
+    const framed = [result.webout, LOGS_SEPARATOR, result.log, LOGS_SEPARATOR]
+
+    if (result.print) framed.push(result.print)
+
     return {
-      contents: [
-        result.webout,
-        LOGS_SEPARATOR,
-        result.log,
-        LOGS_SEPARATOR
-      ].join('\n'),
+      contents: framed.join('\n'),
       // the frame is text, and the service's own type and disposition are not
       // applied to it - a download there would put the frame in the file
       headers: { 'content-type': 'text/plain' },
       log: result.log
     }
+  }
 
   const headers = parseHeaders(result.headers)
   let contents = result.webout
@@ -231,6 +233,66 @@ const persistChanges = async () => {
     await broadcast({ type: 'sasjs-persist', files })
 }
 
+// ----------------------------------------------------------- the SAS transcript
+/**
+ * A recorded SAS session, for a project that ships one.
+ *
+ * A browser has no SAS binary. Rather than let a Run on a .sas program be a
+ * surprise, a project may record a session once and commit it as
+ * `sas-transcript.json`: the build copies it into the site and this answers a
+ * run of a program it names with that session's log, listing and webout. The
+ * recording is the demo's own data, so nothing here is invented for a project
+ * that does not ship one - those runs reach the runner and are refused exactly
+ * as before.
+ *
+ * Shape: `{ "<program path>": {"log": "...", "print": "...", "webout": "..."} }`,
+ * all three strings. The path is matched as written apart from the
+ * `/sasjs/drive/files` prefix and the `.sas` suffix, so a recording keeps the
+ * path a person sees; a bare file name is not enough, because that would answer
+ * every file of that name in the drive.
+ */
+const SAS_TRANSCRIPT = 'host/sas-transcript.json'
+let TRANSCRIPT = null
+
+const transcript = async () => {
+  if (TRANSCRIPT) return TRANSCRIPT
+  try {
+    const response = await fetch(SAS_TRANSCRIPT, { cache: 'no-cache' })
+    TRANSCRIPT = response.ok ? await response.json() : {}
+  } catch (e) {
+    TRANSCRIPT = {}
+  }
+  return TRANSCRIPT
+}
+
+/**
+ * The drive path without its mount prefix or extension.
+ *
+ * A recording is written with the path a person sees (`/sasjs/drive/files/...`,
+ * ending in `.sas`); the route hands the request the path relative to the app,
+ * and Studio asks for it without the extension. Comparing the logical path makes
+ * those the same program without widening the match to the file name alone,
+ * which would answer every `report.sas` in the drive with a session recorded for
+ * some other file.
+ */
+const logicalPath = (value) =>
+  String(value || '')
+    .replace(/^\/sasjs\/drive\/files/i, '')
+    .replace(/\.sas$/i, '')
+
+/** The recording naming this program, if the project shipped one. */
+const transcriptFor = async (programPath) => {
+  const requested = logicalPath(programPath)
+  if (!requested) return undefined
+
+  const recorded = await transcript()
+
+  for (const key of Object.keys(recorded))
+    if (logicalPath(key) === requested) return recorded[key]
+
+  return undefined
+}
+
 // ---------------------------------------------------------------- the runner
 /**
  * The work a run does, over the browser's drive.
@@ -250,6 +312,19 @@ class BrowserRuntime extends API.MemorySessionHost {
   async run(request) {
     const program = request.program || {}
     const params = Object.assign({}, request.vars || {})
+
+    // A SAS program the recording does not name. This host has no SAS binary, so
+    // the answer is the refusal a client already understands - not a JavaScript
+    // SyntaxError quoting the SAS source, which is what handing it to the runner
+    // would produce. The file is resolved because the request may name the
+    // program without its extension.
+    if (program.code === undefined) {
+      const resolved = R.resolveProgram(program.path)
+
+      if (resolved && /\.sas$/i.test(resolved))
+        throw runFailure('"runTime" must be one of [js]')
+    }
+
     const payload = { params, tables: tablesOf(request.files) }
     if (program.code !== undefined) payload.code = program.code
     else payload.program = program.path
@@ -516,8 +591,10 @@ const SERVICES = {
   identity: IDENTITY,
   records: RECORDS,
   runtime: API.createRuntimeService(IDENTITY_STORE, RUNTIME, {
-    // the one run time a browser holds; a stored program asks for another and
-    // is refused with the package's own message
+    // The one run time this host executes. A recorded SAS session is answered
+    // before the runner (see SAS_TRANSCRIPT below), not by claiming a `sas` run
+    // time - a .sas program with no recording must still be refused, and a route
+    // that accepted `sas` would compile SAS source as JavaScript instead.
     runTimes: ['js']
   }),
   session: API.createSessionService(IDENTITY_STORE, RUNTIME),
@@ -860,6 +937,33 @@ const runRoute = async (routeId, payload, subject) => {
     runRequest.program = query._program || body._program
   }
 
+  // A recorded SAS session is answered here, ahead of the run time check: a
+  // transcript is data, not a run time, and this host holds only `js`. Accepting
+  // `sas` instead would make the package compile SAS source as JavaScript and
+  // hand back a SyntaxError where every other .sas program gets a refusal.
+  // Neither a code run nor a trigger: a trigger has to answer with the session
+  // record the route builds, which a client parses as JSON, so a recording is not
+  // an answer there.
+  if (!code && !trigger) {
+    const recording = await transcriptFor(runRequest.program)
+
+    if (recording)
+      return artifactResponse(
+        artifactOf(
+          {
+            webout: recording.webout || '',
+            log: recording.log || '',
+            print: recording.print || '',
+            // the seed every session starts with, so a run without `_debug`
+            // answers text/html rather than leaving the type to the browser -
+            // the same rule runtime-core applies to a service that declares none
+            headers: SEEDED_HEADER_LINE
+          },
+          vars._debug !== undefined
+        )
+      )
+  }
+
   if (trigger) {
     runRequest.expiresAfterMins =
       query.expiresAfterMins !== undefined

package/build/commands/build/internal/mockSite/mockSite.d.ts

@@ -9,6 +9,8 @@ export interface MockSiteResult {
     webFileCount: number;
     /** True when a captured drive snapshot was shipped with the site. */
     snapshot: boolean;
+    /** True when a recorded SAS session was shipped, for .sas runs to answer. */
+    sasTranscript: boolean;
 }
 /**
  * The webout() block is the one @sasjs/utils generates for the server, emitted

package/build/commands/build/internal/mockSite/mockSite.js

@@ -683,7 +683,7 @@ var patchIndexHtml = function (html, version, basePath) {
  */
 function buildMockSite(target) {
     return __awaiter(this, void 0, void 0, function () {
-        var projectDir, appLocRaw, appLoc, buildFolder, basePath, webSourceRaw, webFolder, outputFolder, streamConfig, excluded, _a, seed, skipped, jsPrograms, sasPrograms, driveEntries, webFileCount, hostFolder, _b, _c, asset, hostVersion, buildStamp, swPath, snapshotSource, hasSnapshot, indexPath, _d, patched, warnings;
+        var projectDir, appLocRaw, appLoc, buildFolder, basePath, webSourceRaw, webFolder, outputFolder, streamConfig, excluded, _a, seed, skipped, jsPrograms, sasPrograms, driveEntries, webFileCount, hostFolder, _b, _c, asset, hostVersion, buildStamp, swPath, snapshotSource, hasSnapshot, transcriptSource, hasTranscript, indexPath, _d, patched, warnings;
         var e_8, _e;
         var _f, _g, _h, _j, _k, _l;
         return __generator(this, function (_m) {
@@ -854,6 +854,10 @@ function buildMockSite(target) {
                     if (hasSnapshot) {
                         fs_1.default.copyFileSync(snapshotSource, path_1.default.join(hostFolder, 'vfs-snapshot.json'));
                     }
+                    transcriptSource = path_1.default.join(buildFolder, 'sas-transcript.json');
+                    hasTranscript = fs_1.default.existsSync(transcriptSource);
+                    if (hasTranscript)
+                        fs_1.default.copyFileSync(transcriptSource, path_1.default.join(hostFolder, 'sas-transcript.json'));
                     // 3. the drive, laid out from the compile output
                     fs_1.default.writeFileSync(path_1.default.join(hostFolder, 'vfs-seed.json'), JSON.stringify({ format: exports.DRIVE_FORMAT, files: seed }));
                     fs_1.default.writeFileSync(path_1.default.join(hostFolder, 'mock-config.json'), JSON.stringify({
@@ -863,6 +867,7 @@ function buildMockSite(target) {
                         jsPrograms: jsPrograms,
                         programFolders: PROGRAM_FOLDERS,
                         snapshot: hasSnapshot,
+                        sasTranscript: hasTranscript,
                         buildStamp: buildStamp,
                         builtAt: new Date().toISOString()
                     }, null, 2));
@@ -876,7 +881,8 @@ function buildMockSite(target) {
                             driveEntries: driveEntries,
                             jsPrograms: jsPrograms,
                             webFileCount: webFileCount,
-                            snapshot: hasSnapshot
+                            snapshot: hasSnapshot,
+                            sasTranscript: hasTranscript
                         }];
             }
         });

package/build/commands/build/internal/mockSite/spec/mockSite.spec.js

@@ -642,6 +642,43 @@ describe('browser-hosted build', function () {
             }
         });
     }); });
+    it('ships a recorded SAS session when the project has one', function () { return __awaiter(void 0, void 0, void 0, function () {
+        var recording, result;
+        var _a;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0:
+                    recording = (_a = {},
+                        _a["/sasjs/drive/files".concat(appLoc, "/services/public/report.sas")] = {
+                            log: 'NOTE: Copyright (c) 2016 by SAS Institute Inc., Cary, NC, USA.',
+                            print: 'The SAS System',
+                            webout: '{"SYSSITE":"00000000"}'
+                        },
+                        _a);
+                    write(path_1.default.join(root, 'sasjsbuild', 'sas-transcript.json'), JSON.stringify(recording));
+                    return [4 /*yield*/, (0, mockSite_1.buildMockSite)(target())];
+                case 1:
+                    result = _b.sent();
+                    expect(result.sasTranscript).toBe(true);
+                    expect(JSON.parse(fs_1.default.readFileSync(path_1.default.join(out(), 'host', 'sas-transcript.json'), 'utf8'))).toEqual(recording);
+                    expect(readConfig().sasTranscript).toBe(true);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    it('ships no recording when the project has none', function () { return __awaiter(void 0, void 0, void 0, function () {
+        var result;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, (0, mockSite_1.buildMockSite)(target())];
+                case 1:
+                    result = _a.sent();
+                    expect(result.sasTranscript).toBe(false);
+                    expect(fs_1.default.existsSync(path_1.default.join(out(), 'host', 'sas-transcript.json'))).toBe(false);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
     it('ships no snapshot when the project has none', function () { return __awaiter(void 0, void 0, void 0, function () {
         var result;
         return __generator(this, function (_a) {

package/build/commands/build/internal/mockSite/spec/sw.spec.js

@@ -163,7 +163,7 @@ var loadWorker = function (base) {
     };
     require('../assets/sw.js');
     global.fetch = jest.fn(function (input) { return __awaiter(void 0, void 0, void 0, function () {
-        var target;
+        var target, fixture;
         var _a;
         return __generator(this, function (_b) {
             target = typeof input === 'string' ? input : (input && input.url) || String(input);
@@ -175,6 +175,10 @@ var loadWorker = function (base) {
                     })];
             if (target.includes('index.html'))
                 return [2 /*return*/, new Response('<!doctype html><html><head><title>App</title></head><body>home</body></html>', { status: 200, headers: { 'content-type': 'text/html' } })];
+            if (target.includes('sas-transcript')) {
+                fixture = global.__sasTranscript;
+                return [2 /*return*/, fixture ? jsonResponse(fixture) : new Response('', { status: 404 })];
+            }
             return [2 /*return*/, target.includes('vfs-seed')
                     ? jsonResponse({
                         files: (_a = {},
@@ -286,6 +290,104 @@ describe('service worker host', function () {
             }
         });
     }); });
+    it('answers a recorded SAS session with its log, listing and webout', function () { return __awaiter(void 0, void 0, void 0, function () {
+        var worker, response, body;
+        var _a, _b;
+        return __generator(this, function (_c) {
+            switch (_c.label) {
+                case 0:
+                    // A browser has no SAS binary. A project may ship the transcript of one real
+                    // session, and a program it names is answered with it - framed the way the
+                    // adapter and the Studio split the three parts: webout SEP log SEP listing.
+                    ;
+                    global.__sasTranscript = (_a = {},
+                        _a["".concat(appLoc, "/services/public/report.sas")] = {
+                            webout: '{"SYSSITE":"00000000"}',
+                            log: 'NOTE: Copyright (c) 2016 by SAS Institute Inc., Cary, NC, USA.',
+                            print: 'The SAS System\n\n  Obs    customer\n    1    Northwind Ltd'
+                        },
+                        _a);
+                    worker = loadWorker();
+                    worker.runtime.load((_b = {},
+                        _b[drivePath('services/public/report.sas')] = 'data work.class; run;',
+                        _b));
+                    return [4 /*yield*/, worker.dispatch('/SASjsApi/stp/execute?_program=' +
+                            encodeURIComponent("".concat(appLoc, "/services/public/report")) +
+                            '&_debug=131')];
+                case 1:
+                    response = _c.sent();
+                    expect(response.status).toBe(200);
+                    return [4 /*yield*/, response.text()];
+                case 2:
+                    body = _c.sent();
+                    expect(body).toContain('NOTE: Copyright');
+                    expect(body).toContain('Northwind Ltd');
+                    expect(body).toContain('"SYSSITE":"00000000"');
+                    delete global.__sasTranscript;
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    it('gives a recorded run the seeded content type when not debugging', function () { return __awaiter(void 0, void 0, void 0, function () {
+        var worker, response, _a;
+        var _b, _c;
+        return __generator(this, function (_d) {
+            switch (_d.label) {
+                case 0:
+                    // Without `_debug` the body is the webout alone, and it still has to carry
+                    // the type a session is seeded with - an empty header set leaves the choice
+                    // to the browser, which is the case the seed exists to prevent.
+                    ;
+                    global.__sasTranscript = (_b = {},
+                        _b["".concat(appLoc, "/services/public/report.sas")] = {
+                            webout: '{"SYSSITE":"00000000"}',
+                            log: 'NOTE: recorded',
+                            print: 'The SAS System'
+                        },
+                        _b);
+                    worker = loadWorker();
+                    worker.runtime.load((_c = {},
+                        _c[drivePath('services/public/report.sas')] = 'data work.class; run;',
+                        _c));
+                    return [4 /*yield*/, worker.dispatch('/SASjsApi/stp/execute?_program=' +
+                            encodeURIComponent("".concat(appLoc, "/services/public/report")))];
+                case 1:
+                    response = _d.sent();
+                    expect(response.status).toBe(200);
+                    expect(response.headers.get('content-type')).toContain('text/html');
+                    _a = expect;
+                    return [4 /*yield*/, response.text()];
+                case 2:
+                    _a.apply(void 0, [_d.sent()]).toBe('{"SYSSITE":"00000000"}');
+                    delete global.__sasTranscript;
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    it('refuses a .sas program no recording names, as it always did', function () { return __awaiter(void 0, void 0, void 0, function () {
+        var worker, response, body;
+        var _a;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0:
+                    worker = loadWorker();
+                    worker.runtime.load((_a = {},
+                        _a[drivePath('services/public/other.sas')] = 'data work.class; run;',
+                        _a));
+                    return [4 /*yield*/, worker.dispatch('/SASjsApi/stp/execute?_program=' +
+                            encodeURIComponent("".concat(appLoc, "/services/public/other")))];
+                case 1:
+                    response = _b.sent();
+                    expect(response.status).toBe(400);
+                    return [4 /*yield*/, response.text()];
+                case 2:
+                    body = _b.sent();
+                    expect(body).toContain('runTime');
+                    expect(body).not.toContain('SyntaxError');
+                    return [2 /*return*/];
+            }
+        });
+    }); });
     /**
      * A worker whose drive holds one service that answers with a download, the
      * way a streaming service does on the server: the body goes to the webout
@@ -1059,6 +1161,41 @@ describe('service worker host', function () {
                 }
             });
         }); });
+        it('keeps a trigger a JSON answer, not the recorded transcript', function () { return __awaiter(void 0, void 0, void 0, function () {
+            var worker, response, body;
+            var _a, _b;
+            return __generator(this, function (_c) {
+                switch (_c.label) {
+                    case 0:
+                        // A recording answers a run, not a trigger: the trigger route answers with
+                        // the session record a client parses as JSON, so returning the framed
+                        // webout there would break triggerProgram and the Studio.
+                        ;
+                        global.__sasTranscript = (_a = {},
+                            _a["".concat(appLoc, "/services/public/report.sas")] = {
+                                webout: '{"SYSSITE":"00000000"}',
+                                log: 'NOTE: recorded',
+                                print: 'The SAS System'
+                            },
+                            _a);
+                        worker = loadWorker();
+                        worker.runtime.load((_b = {},
+                            _b[drivePath('services/public/report.sas')] = 'data work.class; run;',
+                            _b));
+                        return [4 /*yield*/, worker.dispatch('/SASjsApi/stp/trigger?_program=' +
+                                encodeURIComponent("".concat(appLoc, "/services/public/report")), runRequest({ params: {} }))];
+                    case 1:
+                        response = _c.sent();
+                        expect(response.headers.get('content-type')).toContain('application/json');
+                        return [4 /*yield*/, response.json()];
+                    case 2:
+                        body = _c.sent();
+                        expect(body).not.toHaveProperty('webout');
+                        delete global.__sasTranscript;
+                        return [2 /*return*/];
+                }
+            });
+        }); });
         it('refuses a deploy upload with no archive, and one that is not a zip', function () { return __awaiter(void 0, void 0, void 0, function () {
             var dispatch, empty, _a, form, notZip, _b;
             return __generator(this, function (_c) {

package/build/commands/help/help.js

@@ -209,6 +209,8 @@ function printHelpText() {
                     description: [
                         "lets the user add a build target to either the local project configuration, or to the global .sasjsrc file.",
                         "",
+                        "[2spaces]NOTE: Providing insecure flag (--insecure or -i) is optional. It allows the command to bypass the HTTPS requirement, and is not recommended.",
+                        "",
                         "NOTE: This command requires the user to input all the required parameters. More information available in the online documentation: ".concat(chalk_1.default.cyanBright('https://sasjs.io/sasjs-cli-add'))
                     ]
                 },
@@ -220,6 +222,9 @@ function printHelpText() {
                         "With the 'login' sub command (SASVIYA targets only), authentication is performed with a SAS username and password - no OAuth client/secret required - and the resulting tokens are saved.",
                         "Without a sub command, behaves like 'sasjs add cred' (client/secret based authentication).",
                         "",
+                        "[2spaces]NOTE: Providing insecure flag (--insecure or -i) is optional. It allows the command to bypass the HTTPS requirement, and is not recommended.",
+                        "[2spaces]NOTE: Providing password-stdin flag (--passwordStdin) is optional. The password is read from stdin instead of being prompted for, which is how a pipeline passes it without a terminal.",
+                        "",
                         "NOTE: This command requires the user to input all the required parameters. More information available in the online documentation: ".concat(chalk_1.default.cyanBright('https://cli.sasjs.io/auth/'))
                     ]
                 },
@@ -231,7 +236,8 @@ function printHelpText() {
                         "The target can exist either in the local project configuration or in the global .sasjsrc file.",
                         "Providing log flag (--log or -l) is optional. If not present, the log is stored locally with a timestamp. If present, CLI will fetch and save the log to the specified location. If a relative location, it will be relative to the directory in which the command is invoked.",
                         "Providing source flag (--source or -s) is optional. It should point to a JSON file with the following structure:  {\"macroVars\": {\"var1\": \"val1\", \"var2\": \"val2\"}}. These will be parsed into SAS \"%let\" statements and pre-append to the SAS code being run.",
-                        "Providing compile flag (--compile or -c) is optional. It is used to compile the program prior to execution. Useful for including dependent macros and includes. More info here: https://cli.sasjs.io/compile"
+                        "Providing compile flag (--compile or -c) is optional. It is used to compile the program prior to execution. Useful for including dependent macros and includes. More info here: https://cli.sasjs.io/compile",
+                        "Providing logcheck flag (--logcheck or --no-logcheck) is optional. It checks the log this run returned and fails when the logCheck setting in sasjsconfig.json says so. --no-logcheck switches both the report and the verdict off for this run."
                     ]
                 },
                 {
@@ -243,7 +249,9 @@ function printHelpText() {
                         "The target can exist either in the local project configuration or in the global .sasjsrc file.",
                         "<sasProgramPath> - if this has a leading slash (eg /Public/app/folder/servicename) then it must be the full path. If it is a relative path (eg path/servicename) then it will be pre-pended with the appLoc - which must then be defined in the sasjs config.",
                         "<path/to/log> - Location in which to store the log file. If not provided AND current directory is a sasjs project, it will be saved in sasjsresults else in the current directory",
-                        "<path/to/output> - Location to store the output file. If not provided AND current directory is a sasjs project, an output file  will be saved in the sasjsresults folder else in current directory."
+                        "<path/to/output> - Location to store the output file. If not provided AND current directory is a sasjs project, an output file  will be saved in the sasjsresults folder else in current directory.",
+                        "<path/to/datafile> - (--data or -d) the json file holding the input data passed to the request. --config (-c) takes the json config for the execution itself.",
+                        "Providing logcheck flag (--logcheck or --no-logcheck) is optional. It checks the log this request returned and fails when the logCheck setting in sasjsconfig.json says so."
                     ]
                 },
                 {
@@ -274,7 +282,8 @@ function printHelpText() {
                         "* ".concat(chalk_1.default.cyanBright('compile'), " - Compiles a SAS program with the contents of a local directory."),
                         "[2spaces]command example: sasjs fs compile /Public/folder --output ./outputProgram",
                         "",
-                        "[2spaces]NOTE: If output flag (-o or --output) is not provided, output will be stored in './fs-compile/{timestamp}' directory relative to working directory."
+                        "[2spaces]NOTE: If output flag (-o or --output) is not provided, output will be stored in './fs-compile/{timestamp}' directory relative to working directory.",
+                        "[2spaces]NOTE: Providing logcheck flag (--logcheck or --no-logcheck) is optional. It checks the log the compile returned, and fails when the logCheck setting in sasjsconfig.json says so."
                     ]
                 },
                 {
@@ -290,7 +299,12 @@ function printHelpText() {
                         "[2spaces]NOTE: Providing output flag (--output or -o) is optional. If present, CLI will immediately print out the response JSON. If value is provided, it will be treated as file path to save the response JSON.",
                         "[2spaces]NOTE: Providing log flag (--log or -l) is optional. If present, CLI will fetch and save job log to local file.",
                         "[2spaces]NOTE: Providing ignore warnings (--ignoreWarnings or -i) flag is optional. If present, CLI will return status '0', when the job state is warning.",
-                        "[2spaces]NOTE: Providing verbose (--verbose or -v) flag is optional. If present, CLI will log summary of every HTTP response. If set to 'bleached', CLI will log summary of every HTTP response without extra colors."
+                        "[2spaces]NOTE: Providing verbose (--verbose or -v) flag is optional. If present, CLI will log summary of every HTTP response. If set to 'bleached', CLI will log summary of every HTTP response without extra colors.",
+                        "[2spaces]NOTE: Providing source flag (--source or -s) is optional. It points to a JSON file of job variables, of the form {\"macroVars\": {\"var1\": \"val1\"}}.",
+                        "[2spaces]NOTE: Providing returnStatusOnly (--returnStatusOnly or -r) is deprecated and has no effect: passing it prints a deprecation warning. The job status is returned with --verbose.",
+                        "[2spaces]NOTE: Providing statusFile flag (--statusFile) is optional. The job status is fetched and saved to the given path; with no path it is printed to the console.",
+                        "[2spaces]NOTE: Providing streamLog flag (--streamLog) is optional. As the job runs, its log is streamed into the local file given here, rather than fetched once at the end.",
+                        "[2spaces]NOTE: Providing logcheck flag (--logcheck or --no-logcheck) is optional. It checks the log the job returned, and fails when the logCheck setting in sasjsconfig.json says so."
                     ]
                 },
                 {
@@ -299,7 +313,10 @@ function printHelpText() {
                     description: [
                         "Performs operations on flows of jobs.",
                         "[2spaces]* ".concat(chalk_1.default.cyanBright('execute'), " - triggers flow for execution."),
-                        "[2spaces]command example: sasjs flow execute --source /local/flow.json --logFolder /local/log/folder --csvFile /local/some.csv"
+                        "[2spaces]command example: sasjs flow execute --source /local/flow.json --logFolder /local/log/folder --csvFile /local/some.csv",
+                        "",
+                        "[2spaces]NOTE: Providing streamLog flag (--streamLog) is optional. As each job in the flow runs, its log is streamed into the log folder, rather than fetched once the job finishes.",
+                        "[2spaces]NOTE: Providing logcheck flag (--logcheck or --no-logcheck) is optional. It checks the log of every job in the flow, and fails when the logCheck setting in sasjsconfig.json says so. A log streamed with --streamLog goes straight to its file and is not checked."
                     ]
                 },
                 {
@@ -333,7 +350,11 @@ function printHelpText() {
                     description: [
                         "Checks SAS logs for the messages SAS printed - ERRORs, WARNINGs and the notes that flag a problem - and fails when the failure policy is broken.",
                         "[2spaces]With no path, the project's results folder is checked. No target, no login and no project are needed, so a log produced elsewhere checks the same way.",
-                        "[2spaces]command example: sasjs logcheck --fail-on warning --format json"
+                        "[2spaces]command example: sasjs logcheck --fail-on warning --format json",
+                        "",
+                        "[2spaces]Flags: --fail-on error|warning|note|never (defaults to logCheck.failOn in sasjsconfig.json, else error), --max-warnings <n>, --ignore-code <49-169>, --ignore-path <path segment|glob>, --format human|json|annotations, --json, --verbose.",
+                        "[2spaces]The same settings live in the logCheck section of sasjsconfig.json: --ignore-code and --ignore-path add to what the file lists, while --fail-on and --max-warnings replace the file's value when they are given.",
+                        "[2spaces]The exit code is 5 when the policy is broken, which is distinct from lint's 3, so a pipeline can tell a run SAS complained about from code-quality failures."
                     ]
                 },
                 {

package/build/commands/logcheck/logcheckCommand.js

@@ -115,7 +115,7 @@ var LogCheckCommand = /** @class */ (function (_super) {
                 },
                 'ignore-path': {
                     type: 'array',
-                    description: 'Log path to leave out, as a substring or a glob. Repeatable.'
+                    description: 'Log path to leave out, as a path segment or a glob. A non-glob entry matches whole segments only, so `test` covers `test/run.log` but not `latest.log`. Repeatable.'
                 },
                 format: {
                     type: 'string',

package/build/commands/logcheck/types.d.ts

@@ -32,8 +32,10 @@ export interface LogCheckConfig {
      */
     ignoreCodes: string[];
     /**
-     * Log paths to leave out, as a plain substring (`sasjsresults/legacy`) or a
+     * Log paths to leave out, as a path segment (`sasjsresults/legacy`) or a
      * glob (`**/build*.log`). Matched against the path shown in the report.
+     * A non-glob entry matches whole segments, so `test` covers `test/run.log`
+     * and not `latest.log`.
      */
     ignorePaths: string[];
     /**

package/build/types/command/parse.d.ts

@@ -1,8 +1,29 @@
 import { CommandBase } from './commandBase';
 /**
- * Rewrites a version flag in the command position to the `version` command.
+ * Rewrites a version or help flag in the command position to the command it
+ * stands for.
  *
- * @param args - the process arguments, as `[node, sasjs, ...]`.
+ * @param args - the process arguments, as `[node, sasjs, ...]`
  */
 export declare const normaliseArgs: (args: string[]) => string[];
-export declare const parse: (args: string[]) => CommandBase;
+/**
+ * Resolves the arguments to the command that will run them.
+ *
+ * @param args - the process arguments, as `[node, sasjs, ...]`
+ * @returns the command, or `undefined` when the arguments name no command the
+ * CLI registers. Printing the help and choosing the exit code is the caller's
+ * job, so this stays a pure lookup.
+ */
+export declare const parse: (args: string[]) => CommandBase | undefined;
+/**
+ * The command name the arguments asked for, as typed - so a message can repeat
+ * it back. Empty when no command was given at all.
+ *
+ * @param args - the process arguments, as `[node, sasjs, ...]`
+ */
+export declare const requestedCommandName: (args: string[]) => string;
+/**
+ * Every command the CLI registers, so a misspelling can be answered with the
+ * list rather than a pointer to another command.
+ */
+export declare const commandNames: () => string[];

package/build/types/command/parse.js

@@ -25,33 +25,61 @@ var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
     return to.concat(ar || Array.prototype.slice.call(from));
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parse = exports.normaliseArgs = void 0;
+exports.commandNames = exports.requestedCommandName = exports.parse = exports.normaliseArgs = void 0;
 var getBaseCommand_1 = require("../../utils/getBaseCommand");
 var commandFactory_1 = require("./commandFactory");
 // `sasjs version`, `sasjs v`, `sasjs -v` and `sasjs --version` all mean the
 // same thing. yargs reads a leading `-v`/`--version` as an option rather than
 // a command, and its own version handling is switched off, so the token is
-// rewritten to the command name before dispatch.
+// rewritten to the command name before dispatch. The help flags get the same
+// treatment: `sasjs --help` is the first thing most people try, and letting it
+// fall through made the root answer "Invalid SASjs command: --help".
 var versionFlags = ['-v', '--version'];
+var helpFlags = ['-h', '--help'];
 /**
- * Rewrites a version flag in the command position to the `version` command.
+ * Rewrites a version or help flag in the command position to the command it
+ * stands for.
  *
- * @param args - the process arguments, as `[node, sasjs, ...]`.
+ * @param args - the process arguments, as `[node, sasjs, ...]`
  */
 var normaliseArgs = function (args) {
     var _a = __read(args, 3), command = _a[2];
-    return versionFlags.includes(command)
-        ? __spreadArray(__spreadArray(__spreadArray([], __read(args.slice(0, 2)), false), ['version'], false), __read(args.slice(3)), false) : args;
+    if (versionFlags.includes(command)) {
+        return __spreadArray(__spreadArray(__spreadArray([], __read(args.slice(0, 2)), false), ['version'], false), __read(args.slice(3)), false);
+    }
+    if (helpFlags.includes(command)) {
+        return __spreadArray(__spreadArray(__spreadArray([], __read(args.slice(0, 2)), false), ['help'], false), __read(args.slice(3)), false);
+    }
+    return args;
 };
 exports.normaliseArgs = normaliseArgs;
+/**
+ * Resolves the arguments to the command that will run them.
+ *
+ * @param args - the process arguments, as `[node, sasjs, ...]`
+ * @returns the command, or `undefined` when the arguments name no command the
+ * CLI registers. Printing the help and choosing the exit code is the caller's
+ * job, so this stays a pure lookup.
+ */
 var parse = function (args) {
-    var _a;
     var commandArgs = (0, exports.normaliseArgs)(args);
     var baseCommand = (0, getBaseCommand_1.getBaseCommand)(commandArgs);
-    if (!Array.from(commandFactory_1.commandFactory.keys()).includes(baseCommand.name)) {
-        (_a = process.logger) === null || _a === void 0 ? void 0 : _a.error('Invalid SASjs command! Run `sasjs help` for a full list of available commands.');
-        process.exit(1);
-    }
-    return commandFactory_1.commandFactory.get(baseCommand.name)(commandArgs);
+    return commandFactory_1.commandFactory.has(baseCommand.name)
+        ? commandFactory_1.commandFactory.get(baseCommand.name)(commandArgs)
+        : undefined;
 };
 exports.parse = parse;
+/**
+ * The command name the arguments asked for, as typed - so a message can repeat
+ * it back. Empty when no command was given at all.
+ *
+ * @param args - the process arguments, as `[node, sasjs, ...]`
+ */
+var requestedCommandName = function (args) { var _a; return (_a = (0, exports.normaliseArgs)(args)[2]) !== null && _a !== void 0 ? _a : ''; };
+exports.requestedCommandName = requestedCommandName;
+/**
+ * Every command the CLI registers, so a misspelling can be answered with the
+ * list rather than a pointer to another command.
+ */
+var commandNames = function () { return Array.from(commandFactory_1.commandFactory.keys()); };
+exports.commandNames = commandNames;

package/build/types/command/spec/parse.spec.js

@@ -8,10 +8,31 @@ describe('parse', function () {
         expect(command).toBeInstanceOf(versionCommand_1.VersionCommand);
         expect(command.name).toEqual('version');
     });
+    it.each(['help', '-h', '--help'])('resolves `sasjs %s` to the help command', function (token) {
+        var command = (0, parse_1.parse)(['node', 'sasjs', token]);
+        expect(command.name).toEqual('help');
+    });
     it('leaves another command as it is', function () {
         var command = (0, parse_1.parse)(['node', 'sasjs', 'help']);
         expect(command.name).toEqual('help');
     });
+    it('returns undefined for a command it does not register', function () {
+        expect((0, parse_1.parse)(['node', 'sasjs', 'frobnicate'])).toBeUndefined();
+    });
+    it('returns undefined when no command is given', function () {
+        expect((0, parse_1.parse)(['node', 'sasjs'])).toBeUndefined();
+    });
+});
+describe('requestedCommandName', function () {
+    it('reports the command as typed', function () {
+        expect((0, parse_1.requestedCommandName)(['node', 'sasjs', 'frobnicate'])).toEqual('frobnicate');
+    });
+    it('reports the version command for a version flag', function () {
+        expect((0, parse_1.requestedCommandName)(['node', 'sasjs', '--version'])).toEqual('version');
+    });
+    it('reports an empty name when there is no command', function () {
+        expect((0, parse_1.requestedCommandName)(['node', 'sasjs'])).toEqual('');
+    });
 });
 describe('normaliseArgs', function () {
     it.each(['-v', '--version'])('rewrites %s in the command position', function (flag) {
@@ -21,6 +42,13 @@ describe('normaliseArgs', function () {
             'version'
         ]);
     });
+    it.each(['-h', '--help'])('rewrites %s in the command position to the help command', function (flag) {
+        expect((0, parse_1.normaliseArgs)(['node', 'sasjs', flag])).toEqual([
+            'node',
+            'sasjs',
+            'help'
+        ]);
+    });
     it('keeps the arguments that follow the flag', function () {
         expect((0, parse_1.normaliseArgs)(['node', 'sasjs', '--version', 'extra'])).toEqual([
             'node',

package/package.json

@@ -125,5 +125,5 @@
     "ws": "8.21.0",
     "nanoid": "3.3.18"
   },
-  "version": "6.21.0"
+  "version": "6.23.0"
 }