@sasjs/cli 6.30.1 → 6.32.0

package/build/commands/build/internal/mockSite/assets/api-index.html

@@ -0,0 +1,83 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>API console - browser demo</title>
+    <meta name="sasjs-mock-version" content="__MOCK_VERSION__" />
+    <!--
+      The API console for a browser-hosted build.
+
+      Static, and deliberately so: no bundler, no framework, no network of its
+      own beyond the API it is documenting. It is served from <base>/api-console/ and
+      every request it makes is the same request an application makes, so the
+      service worker answers it and the answer is the mock's real answer.
+
+      Nothing is inline: a project that sets `default-src 'self'` without
+      'unsafe-inline' would refuse an inline script or style, and this page
+      cannot add a hash to a policy it does not own.
+    -->
+    <link rel="stylesheet" href="console.css" />
+  </head>
+  <body>
+    <header class="bar">
+      <h1>API console</h1>
+      <span class="badge">browser demo</span>
+      <span class="spacer"></span>
+      <span id="who" class="who" title="The account this host answers as"
+        >connected</span
+      >
+    </header>
+
+    <main class="layout">
+      <aside class="list">
+        <input
+          id="filter"
+          type="search"
+          placeholder="Filter routes (user, group, drive...)"
+          autocomplete="off"
+        />
+        <div id="routes" class="routes"></div>
+      </aside>
+
+      <section class="detail">
+        <div id="empty" class="empty">
+          <p>
+            This is a <strong>browser-hosted</strong> SASjs server: the API you
+            are about to call runs in a service worker in this tab, and its
+            drive lives in this browser.
+          </p>
+          <p>
+            Pick a route on the left. Writes are allowed on purpose, and they
+            survive a refresh - add <code>?reset=1</code> to this page's URL to
+            clear the drive and start again from the shipped state.
+          </p>
+        </div>
+
+        <!-- outside #empty: the accounts are most needed while a route is open,
+             and #empty is hidden as soon as one is selected -->
+        <div id="accounts"></div>
+
+        <div id="route" hidden>
+          <h2 id="title"></h2>
+          <p id="summary" class="summary"></p>
+          <form id="form" class="form"></form>
+          <div class="actions">
+            <button id="send" type="button">Send</button>
+            <span id="timing" class="timing"></span>
+          </div>
+          <div id="response" class="response" hidden>
+            <div class="responsebar">
+              <span id="status" class="status"></span>
+              <span class="spacer"></span>
+              <button id="copy" type="button" class="link">Copy</button>
+            </div>
+            <pre id="body"></pre>
+          </div>
+        </div>
+      </section>
+    </main>
+
+    <script src="console.js"></script>
+  </body>
+</html>

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

@@ -1764,10 +1764,11 @@ self.addEventListener('fetch', (event) => {
   // listing is the server's web route, and an interface that lists apps asks for
   // it on every visit.
   //
-  // `/api` and `/api/` on their own are the API's documentation page - a file
-  // the build copies into the site - so the worker stays out of the way there
-  // and the static host answers it. Every other `/api/...` is an API call on the
-  // short spelling, which routeRequest canonicalises to `/SASjsApi`.
+  // `/api` and `/api/` on their own are left to the static host: a site's own
+  // application can answer that route (this framework's server interface does),
+  // and the worker has no business putting an API answer in front of it. Every
+  // other `/api/...` is an API call on the short spelling, which routeRequest
+  // canonicalises to `/SASjsApi`.
   if (/^\/api\/?$/i.test(path)) return
 
   if (!/^\/(SASjsApi|SASLogon|AppStream|api|app)(\/|$)/i.test(path)) return

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

@@ -14,6 +14,8 @@ export interface MockSiteResult {
      * large folder or file. Zero when the site ships no snapshot.
      */
     snapshotShards: number;
+    /** True when the site carries the API console at <base>/api-console/. */
+    apiConsole: boolean;
     /** True when a recorded SAS session was shipped, for .sas runs to answer. */
     sasTranscript: boolean;
     /**

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

@@ -1008,6 +1008,75 @@ var patchIndexHtml = function (html, version, basePath, outputFolder) {
     }
     return { patched: patched, warnings: warnings };
 };
+/**
+ * The folder the console lives in, under the site root.
+ *
+ * Not `api`: an application can answer `/api` itself - this framework's own server
+ * interface does - and a page there would collide with its route, so a site
+ * refresh on that screen would land on the console instead of the application.
+ */
+var API_CONSOLE_DIR = 'api-console';
+/** The files the console consists of, under `<output>/api-console`. */
+var API_CONSOLE_FILES = [
+    'index.html',
+    'console.js',
+    'console.css',
+    'operations.json'
+];
+/**
+ * The API console: a page at `<base>/api-console/` that lists every operation the API
+ * document declares and sends them against this host.
+ *
+ * The route table is the same one the worker answers from (`ROUTES` from
+ * @sasjs/api), so the console cannot drift from the API: a route the package
+ * adds appears here on the next build, with the parameters it declares.
+ *
+ * Three files and the data, all static. It is a developer surface rather than a
+ * screen of the app, so nothing in the page links to it and nothing preloads it -
+ * a visit costs the demo nothing until someone types the URL.
+ */
+var writeApiConsole = function (outputFolder, version) {
+    var folder = path_1.default.join(outputFolder, API_CONSOLE_DIR);
+    // `<base>/api-console/` is this build's, not the project's: a site that ships its own
+    // files there would have them replaced without a word, so it keeps them and
+    // the console is left out
+    var taken = API_CONSOLE_FILES.filter(function (file) {
+        return fs_1.default.existsSync(path_1.default.join(folder, file));
+    });
+    if (taken.length)
+        return {
+            written: false,
+            operations: 0,
+            warning: "The site already carries ".concat(taken
+                .map(function (file) { return API_CONSOLE_DIR + '/' + file; })
+                .join(', '), ", so the API console was not written. ") +
+                'Move those files, or set streamConfig.mockApi to false to silence this.'
+        };
+    fs_1.default.mkdirSync(folder, { recursive: true });
+    // The console starts the host itself, so it has to ask for the same worker the
+    // app's loader asks for: a registration is identified by its script URL, and a
+    // bare `sw.js` here would replace the versioned one on every visit to either
+    // page - an install nobody asked for, which is what the version exists to avoid.
+    fs_1.default.writeFileSync(path_1.default.join(folder, 'index.html'), fs_1.default
+        .readFileSync(path_1.default.join(ASSETS_FOLDER, 'api-index.html'), 'utf8')
+        .replace('__MOCK_VERSION__', version));
+    fs_1.default.copyFileSync(path_1.default.join(ASSETS_FOLDER, 'api-console.js'), path_1.default.join(folder, 'console.js'));
+    fs_1.default.copyFileSync(path_1.default.join(ASSETS_FOLDER, 'api-console.css'), path_1.default.join(folder, 'console.css'));
+    var operations = api_1.ROUTES.map(function (route) { return ({
+        id: route.id,
+        method: route.method,
+        path: route.path,
+        tag: route.tag,
+        summary: route.summary,
+        params: route.params,
+        requestBodies: route.requestBodies,
+        responses: route.responses,
+        implemented: route.implemented,
+        reason: route.reason
+    }); });
+    fs_1.default.writeFileSync(path_1.default.join(folder, 'operations.json'), JSON.stringify(operations, null, 2));
+    return { written: true, operations: operations.length };
+};
 /**
  * Builds a static site that runs the project's JS services (its mocks) in the
  * browser, so a frontend can be tested with no server and no SAS.
@@ -1024,11 +1093,11 @@ var patchIndexHtml = function (html, version, basePath, outputFolder) {
  */
 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, identity, webFileCount, hostFolder, _b, _c, asset, hostVersion, buildStamp, swPath, snapshotSource, hasSnapshot, snapshotShards, capture, files, split, _d, _e, shard, transcriptSource, hasTranscript, indexPath, _f, patched, warnings;
+        var projectDir, appLocRaw, appLoc, buildFolder, basePath, webSourceRaw, webFolder, outputFolder, streamConfig, excluded, _a, seed, skipped, jsPrograms, sasPrograms, driveEntries, identity, webFileCount, hostFolder, _b, _c, asset, hostVersion, buildStamp, swPath, snapshotSource, hasSnapshot, snapshotShards, capture, files, split, _d, _e, shard, transcriptSource, hasTranscript, apiConsole, written, indexPath, _f, patched, warnings;
         var e_11, _g, e_12, _h;
-        var _j, _k, _l, _m, _o, _p;
-        return __generator(this, function (_q) {
-            switch (_q.label) {
+        var _j, _k, _l, _m, _o, _p, _q, _r;
+        return __generator(this, function (_s) {
+            switch (_s.label) {
                 case 0:
                     projectDir = process.projectDir || process.cwd();
                     appLocRaw = target.appLoc;
@@ -1040,7 +1109,7 @@ function buildMockSite(target) {
                         path_1.default.join(projectDir, 'sasjsbuild');
                     return [4 /*yield*/, (0, utils_1.folderExists)(buildFolder)];
                 case 1:
-                    if (!(_q.sent())) {
+                    if (!(_s.sent())) {
                         throw new Error("Build folder not found: ".concat(buildFolder, ". Run `sasjs compile` first."));
                     }
                     basePath = normaliseBasePath((_j = target.streamConfig) === null || _j === void 0 ? void 0 : _j.mockWebBasePath);
@@ -1051,7 +1120,7 @@ function buildMockSite(target) {
                     webFolder = path_1.default.resolve(projectDir, webSourceRaw);
                     return [4 /*yield*/, (0, utils_1.folderExists)(webFolder)];
                 case 2:
-                    if (!(_q.sent())) {
+                    if (!(_s.sent())) {
                         throw new Error("Web source folder not found: ".concat(webFolder, ". Check streamConfig.webSourcePath - build the frontend first."));
                     }
                     if (!fs_1.default.existsSync(path_1.default.join(webFolder, 'index.html'))) {
@@ -1146,7 +1215,7 @@ function buildMockSite(target) {
                 case 3:
                     // 2. the linter, bundled from the installed packages so the code routes answer
                     // with the rules this CLI resolved rather than a second implementation
-                    _q.sent();
+                    _s.sent();
                     // sw.js sits at the site root: a worker can only control the folder it is
                     // served from, and the app has to be controlled from /
                     fs_1.default.copyFileSync(path_1.default.join(ASSETS_FOLDER, 'sw.js'), path_1.default.join(outputFolder, 'sw.js'));
@@ -1250,6 +1319,13 @@ function buildMockSite(target) {
                         buildStamp: buildStamp,
                         builtAt: new Date().toISOString()
                     }, null, 2));
+                    apiConsole = false;
+                    if (((_q = target.streamConfig) === null || _q === void 0 ? void 0 : _q.mockApi) !== false) {
+                        written = writeApiConsole(outputFolder, hostVersion);
+                        apiConsole = written.written;
+                        if (written.warning)
+                            (_r = process.logger) === null || _r === void 0 ? void 0 : _r.warn(written.warning);
+                    }
                     indexPath = path_1.default.join(outputFolder, 'index.html');
                     _f = patchIndexHtml(fs_1.default.readFileSync(indexPath, 'utf8'), hostVersion, basePath, outputFolder), patched = _f.patched, warnings = _f.warnings;
                     fs_1.default.writeFileSync(indexPath, patched);
@@ -1262,6 +1338,7 @@ function buildMockSite(target) {
                             webFileCount: webFileCount,
                             snapshot: hasSnapshot,
                             snapshotShards: snapshotShards,
+                            apiConsole: apiConsole,
                             sasTranscript: hasTranscript,
                             identitySource: identity.source
                         }];

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

@@ -0,0 +1 @@
+export {};