@orchestraworks/cli 0.8.0 → 0.9.0

package/README.md

@@ -20,7 +20,7 @@ The full guide to every construct, secrets, connections and troubleshooting is [
 ```bash
 npm install -g @orchestraworks/cli         # the CLI, on your path as `orchestra`
 npm install @orchestraworks/cli            # the current release
-npm install @orchestraworks/cli@0.8.0      # this exact release
+npm install @orchestraworks/cli@0.9.0      # this exact release
 ```
 
 Then `import { Factory, Agent, … } from "@orchestraworks/cli"` normally — the package `exports` entry resolves

package/dist/artifacts/prelude.js

@@ -2,13 +2,13 @@
  * The runtime a published artifact page gets. It is served with the page on the artifacts host and by
  * `orchestra artifacts preview` from the same file, so a page behaves identically in both.
  *
- * The page never holds a credential and never calls the API. Everything goes to the console frame that
- * embeds it, over postMessage, and the console calls the API with the viewer's own session. A page opened
- * at its own address has no console to talk to, so it is read only: `sf.viewer` is null, the comments
- * overlay is not drawn, and every `sf.data` call rejects.
+ * The page never calls the API; it holds no credential but the short-lived links to what it loads, each to bytes
+ * its viewer may read. It talks over postMessage to the console frame embedding it, which calls
+ * the API with the viewer's session. Opened at its own address, it is read only: `sf.viewer` is null, no comments
+ * overlay is drawn, every `sf.data` call rejects, and a link to a library file follows its own address.
  *
- * All three `sf.data` calls answer a promise, including `subscribe`, which resolves to the function that
- * stops the subscription. Uniform on purpose: outside the console all three reject the same way.
+ * All three `sf.data` calls answer a promise, `subscribe` too, resolving to the function that stops it, so
+ * outside the console all three reject the same way.
  */
 (function () {
   "use strict";
@@ -24,13 +24,27 @@
   var QUOTE_LIMIT = 512;
   var CONTEXT_LIMIT = 64;
   var SELECTOR_LIMIT = 1024;
+  var ELEMENT_ID_LIMIT = 1024;
+  var AGREEMENT_FLOOR = 32;
+  var EDIT_CONTEXT_FLOOR = 16;
+  var EDIT_SPAN_LIMIT = 512;
+  var REDRAW_INTERVAL_MS = 200;
+  // Struck copies of removed blocks, and the bar listing them, repeat what the page used to say: their text
+  // is never the page's, whatever their style.
+  var NOT_PAGE_TEXT = ".sf-removed, #sf-render-changes-bar";
+  var VISIBILITY = { visibilityProperty: true, checkVisibilityCSS: true };
 
   var pending = {};
   var callCounter = 0;
   var dataListeners = [];
   var comments = [];
+  var shownVersion = null;
   var commentMode = false;
   var overlay = null;
+  var drawn = {};
+  var lastReport = null;
+  var lastDraw = 0;
+  var redrawTimer = null;
 
   function call(name, args) {
     if (!insideConsole) {
@@ -106,40 +120,148 @@
 
   function selectorAnchorAt(element, clientX, clientY) {
     var box = element.getBoundingClientRect();
-    return {
+    var anchor = {
       kind: "selector",
       path: selectorOf(element),
       x: box.width > 0 ? percentage(((clientX - box.left) / box.width) * 100) : 0,
       y: box.height > 0 ? percentage(((clientY - box.top) / box.height) * 100) : 0
     };
+    var id = element.getAttribute("id") || "";
+    if (/\S/.test(id) && id.length <= ELEMENT_ID_LIMIT && elementsCarrying(id).length === 1) {
+      anchor.elementId = id;
+    }
+    var whole = document.createRange();
+    whole.selectNodeContents(element);
+    var text = textAnchorOfRange(whole);
+    if (text) {
+      anchor.quote = text.quote;
+      anchor.prefix = text.prefix;
+      anchor.suffix = text.suffix;
+    }
+    return anchor;
+  }
+
+  function elementsCarrying(id) {
+    return Array.prototype.filter.call(document.querySelectorAll("[id]"), function (element) {
+      return element.getAttribute("id") === id;
+    });
   }
 
   function percentage(value) {
     return Math.max(0, Math.min(100, Math.round(value * 100) / 100));
   }
 
-  /** How far into the page's text one boundary of a range sits. */
-  function offsetOf(container, offset) {
-    var upTo = document.createRange();
-    upTo.selectNodeContents(document.body);
-    upTo.setEnd(container, offset);
-    return upTo.toString().length;
+  function eachPageTextNode(root, visit) {
+    if (root.nodeType === 3) {
+      visit(root);
+      return;
+    }
+    var walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT, {
+      acceptNode: function (node) {
+        if (node.nodeType === 3) {
+          return NodeFilter.FILTER_ACCEPT;
+        }
+        return node.matches(NOT_PAGE_TEXT) ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_SKIP;
+      }
+    });
+    while (walker.nextNode()) {
+      visit(walker.currentNode);
+    }
+  }
+
+  /** Whether an element shows. A browser that cannot say counts everything as shown. */
+  function isShown(element) {
+    if (!element) {
+      return false;
+    }
+    return typeof element.checkVisibility !== "function" || element.checkVisibility(VISIBILITY);
+  }
+
+  function hasArea(box) {
+    return box.width > 0 && box.height > 0;
+  }
+
+  function pageTexts() {
+    var all = { text: "", nodes: [] };
+    var visible = { text: "", nodes: [] };
+    if (document.body) {
+      var shownParents = new Map();
+      eachPageTextNode(document.body, function (node) {
+        var value = node.nodeValue || "";
+        var parent = node.parentElement;
+        if (!shownParents.has(parent)) {
+          shownParents.set(parent, isShown(parent));
+        }
+        var shown = shownParents.get(parent);
+        append(all, node, value, shown);
+        if (shown) {
+          append(visible, node, value, true);
+        }
+      });
+    }
+    return { all: all, visible: visible };
+  }
+
+  function append(strand, node, value, shown) {
+    var from = strand.text.length;
+    strand.nodes.push({ node: node, from: from, to: from + value.length, shown: shown });
+    strand.text += value;
+  }
+
+  /** How far into the visible text one boundary of a range sits: the visible characters before it. */
+  function visibleOffset(visible, container, offset) {
+    var point = document.createRange();
+    point.setStart(container, offset);
+    for (var index = 0; index < visible.nodes.length; index += 1) {
+      var entry = visible.nodes[index];
+      if (entry.node === container) {
+        return entry.from + offset;
+      }
+      if (point.comparePoint(entry.node, 0) >= 0) {
+        return entry.from;
+      }
+    }
+    return visible.text.length;
+  }
+
+  // Walks the selection's common ancestor rather than building the page's text, because this runs on each
+  // change of the selection.
+  function selectionHasWords(range) {
+    var root = range.commonAncestorContainer;
+    var element = root.nodeType === 1 ? root : root.parentElement;
+    if (!element || element.closest(NOT_PAGE_TEXT)) {
+      return false;
+    }
+    var found = false;
+    eachPageTextNode(root, function (node) {
+      if (found || !range.intersectsNode(node) || !isShown(node.parentElement)) {
+        return;
+      }
+      var value = node.nodeValue || "";
+      var from = node === range.startContainer ? range.startOffset : 0;
+      var to = node === range.endContainer ? range.endOffset : value.length;
+      found = /\S/.test(value.slice(from, to));
+    });
+    return found;
   }
 
-  /**
-   * The quote plus a little of the text on each side of THAT SPAN, which is what lets the console find the
-   * same passage again — a page saying "wrong" four times has four of them, and the context is what names
-   * which. The one string this works in is the page's own `textContent`, the text nodes in reading order,
-   * which is what the resolver below walks.
-   */
   function textAnchorOfSelection(selection) {
     if (!document.body || selection.rangeCount === 0) {
       return null;
     }
-    var range = selection.getRangeAt(0);
-    var text = document.body.textContent || "";
-    var from = offsetOf(range.startContainer, range.startOffset);
-    var selected = text.slice(from, offsetOf(range.endContainer, range.endOffset));
+    return textAnchorOfRange(selection.getRangeAt(0));
+  }
+
+  /**
+   * The quote plus a little of the text on each side of THAT SPAN, which is what lets the console find the
+   * same passage again — a page saying "wrong" four times has four of them, and the context is what names
+   * which.
+   */
+  function textAnchorOfRange(range) {
+    var visible = pageTexts().visible;
+    var text = visible.text;
+    var from = visibleOffset(visible, range.startContainer, range.startOffset);
+    var selected = text.slice(from, visibleOffset(visible, range.endContainer, range.endOffset));
     var quote = selected.trim().slice(0, QUOTE_LIMIT);
     if (quote === "") {
       return null;
@@ -274,6 +396,49 @@
     }
   }
 
+  /**
+   * A link the platform marked with a library path opens that file or folder in the console, since inside this frame
+   * its address names nothing. A Ctrl, Cmd or Shift click, or a middle click, asks the console for a new tab. An Alt
+   * click, another button, or a click the page's own script handled goes to the browser.
+   *
+   * The platform marks every relative link that names a library file or folder the viewer may read, so an unmarked
+   * one to another path names nothing this host serves, and following it would blank the frame: a primary click on it
+   * does nothing. A link with a scheme, a `//` host, a fragment or a query alone goes to the browser.
+   */
+  function onLinkClick(event) {
+    // A middle click arrives as `auxclick` alone in current browsers, so `click` takes the primary button only.
+    var middle = event.type === "auxclick";
+    if (event.defaultPrevented || event.altKey || event.button !== (middle ? 1 : 0)) {
+      return;
+    }
+    var link = event.target && event.target.closest ? event.target.closest("a") : null;
+    if (!link) {
+      return;
+    }
+    var path = link.getAttribute("data-sf-path");
+    if (path === null) {
+      if (!middle && leavesThePagePath(link.getAttribute("href"))) {
+        event.preventDefault();
+      }
+      return;
+    }
+    event.preventDefault();
+    window.parent.postMessage(
+      {
+        sf: 1,
+        event: "open",
+        path: path,
+        newTab: middle || event.metaKey || event.ctrlKey || event.shiftKey
+      },
+      consoleOrigin
+    );
+  }
+
+  function leavesThePagePath(href) {
+    var reference = href === null ? "" : href.trim();
+    return reference !== "" && !/^(?:[a-zA-Z][a-zA-Z0-9+.-]*:|\/\/|[#?])/.test(reference);
+  }
+
   function onSelectionChange() {
     if (!overlay || readOnly) {
       return;
@@ -283,8 +448,9 @@
       overlay.selectionToolbar.hidden = true;
       return;
     }
-    var box = selection.getRangeAt(0).getBoundingClientRect();
-    if (box.width === 0 && box.height === 0) {
+    var range = selection.getRangeAt(0);
+    var box = range.getBoundingClientRect();
+    if ((box.width === 0 && box.height === 0) || !selectionHasWords(range)) {
       overlay.selectionToolbar.hidden = true;
       return;
     }
@@ -307,57 +473,164 @@
   function refreshComments() {
     return call("comments.list", {}).then(function (result) {
       comments = (result && result.comments) || [];
+      shownVersion = result && typeof result.versionNumber === "number" ? result.versionNumber : null;
       drawPins();
       return comments;
     });
   }
 
+  function requestDraw() {
+    if (redrawTimer !== null) {
+      return;
+    }
+    redrawTimer = setTimeout(drawPins, Math.max(0, lastDraw + REDRAW_INTERVAL_MS - Date.now()));
+  }
+
   function drawPins() {
     if (!overlay) {
       return;
     }
-    overlay.pins.textContent = "";
+    if (redrawTimer !== null) {
+      clearTimeout(redrawTimer);
+      redrawTimer = null;
+    }
+    lastDraw = Date.now();
+    if (document.body && !overlay.host.isConnected) {
+      document.body.appendChild(overlay.host);
+    }
+    var texts = null;
+    var textsOnce = function () {
+      texts = texts || pageTexts();
+      return texts;
+    };
+    var kept = {};
+    var lost = [];
+    var changed = [];
     comments.forEach(function (comment, index) {
-      var position = positionOf(comment.anchor);
+      var position = positionOf(comment, textsOnce);
       if (!position) {
+        if (comment.anchor && (comment.anchor.kind === "selector" || comment.anchor.kind === "text")) {
+          lost.push(comment.id);
+        }
         return;
       }
-      var pin = document.createElement("button");
-      pin.className = "pin";
-      pin.type = "button";
+      if (position.changed) {
+        changed.push(comment.id);
+      }
+      // A pin still drawn keeps its button, so a press and its release on a changing page reach one button.
+      var pin = drawn[comment.id] ? drawn[comment.id].button : newPin(comment.id);
+      kept[comment.id] = { button: pin, comment: comment };
       pin.textContent = String(index + 1);
       pin.setAttribute("data-status", comment.status || "OPEN");
       pin.style.left = position.left + "px";
       pin.style.top = position.top + "px";
-      pin.addEventListener("click", function () {
-        openPanel(comment);
-      });
-      overlay.pins.appendChild(pin);
     });
+    Object.keys(drawn).forEach(function (commentId) {
+      if (!kept[commentId]) {
+        drawn[commentId].button.remove();
+      }
+    });
+    drawn = kept;
+    report(lost, changed);
   }
 
-  /** Document coordinates, so a scroll needs no repositioning; only a resize does. */
-  function positionOf(anchor) {
+  function newPin(commentId) {
+    var pin = document.createElement("button");
+    pin.className = "pin";
+    pin.type = "button";
+    pin.addEventListener("click", function () {
+      if (drawn[commentId]) {
+        openPanel(drawn[commentId].comment);
+      }
+    });
+    overlay.pins.appendChild(pin);
+    return pin;
+  }
+
+  function report(lost, changed) {
+    var message = { sf: 1, event: "pins", lost: lost, changed: changed };
+    var said = JSON.stringify(message);
+    if (said === lastReport) {
+      return;
+    }
+    lastReport = said;
+    window.parent.postMessage(message, consoleOrigin);
+  }
+
+  function fromAnotherVersion(comment) {
+    return (
+      typeof comment.versionNumber === "number" &&
+      typeof shownVersion === "number" &&
+      comment.versionNumber !== shownVersion
+    );
+  }
+
+  /** Document coordinates, so a scroll needs no repositioning. */
+  function positionOf(comment, textsOnce) {
+    var anchor = comment.anchor;
     if (!anchor) {
       return null;
     }
     if (anchor.kind === "selector") {
-      var element = queryFirst(anchor.path);
-      if (!element) {
+      var found = fromAnotherVersion(comment)
+        ? elementElsewhere(anchor, textsOnce())
+        : { element: queryFirst(anchor.path), changed: false };
+      if (!found || !shownWithBox(found.element)) {
         return null;
       }
-      var box = element.getBoundingClientRect();
+      var box = found.element.getBoundingClientRect();
       return {
         left: box.left + window.scrollX + (box.width * (anchor.x || 0)) / 100,
-        top: box.top + window.scrollY + (box.height * (anchor.y || 0)) / 100
+        top: box.top + window.scrollY + (box.height * (anchor.y || 0)) / 100,
+        changed: found.changed
       };
     }
     if (anchor.kind === "text") {
-      return positionOfQuote(anchor);
+      var match = rangeOfAnchor(anchor, fromAnotherVersion(comment), textsOnce());
+      if (!match) {
+        return null;
+      }
+      var quoted = match.range.getBoundingClientRect();
+      return {
+        left: quoted.left + window.scrollX,
+        top: quoted.top + window.scrollY,
+        changed: match.changed
+      };
     }
     return null;
   }
 
+  function shownWithBox(element) {
+    return isShown(element) && hasArea(element.getBoundingClientRect());
+  }
+
+  function elementElsewhere(anchor, texts) {
+    var carriers = anchor.elementId ? elementsCarrying(anchor.elementId) : [];
+    if (
+      carriers.length === 1 &&
+      shownWithBox(carriers[0]) &&
+      (!anchor.quote || visibleTextOf(carriers[0], texts.visible).indexOf(anchor.quote) >= 0)
+    ) {
+      return { element: carriers[0], changed: false };
+    }
+    var match = rangeOfAnchor(anchor, true, texts);
+    if (!match) {
+      return null;
+    }
+    var holder = match.range.commonAncestorContainer;
+    return { element: holder.nodeType === 1 ? holder : holder.parentElement, changed: match.changed };
+  }
+
+  function visibleTextOf(element, visible) {
+    var text = "";
+    visible.nodes.forEach(function (entry) {
+      if (element.contains(entry.node)) {
+        text += visible.text.slice(entry.from, entry.to);
+      }
+    });
+    return text;
+  }
+
   function queryFirst(path) {
     if (!path) {
       return null;
@@ -370,70 +643,98 @@
     }
   }
 
-  function positionOfQuote(anchor) {
-    var range = rangeOfAnchor(anchor);
-    if (!range) {
+  function rangeOfAnchor(anchor, anotherVersion, texts) {
+    if (!anchor || !anchor.quote) {
       return null;
     }
-    var box = range.getBoundingClientRect();
-    return { left: box.left + window.scrollX, top: box.top + window.scrollY };
+    var length = anchor.quote.length;
+    if (anotherVersion) {
+      var whole = length + (anchor.prefix || "").length + (anchor.suffix || "").length;
+      var floor = Math.min(AGREEMENT_FLOOR, whole);
+      var ranked = rankedOccurrences(texts.visible.text, anchor);
+      for (var index = 0; index < ranked.length && length + ranked[index].agreed >= floor; index += 1) {
+        var candidate = spanOf(texts.visible, ranked[index].at, length);
+        if (candidate && hasArea(candidate.range.getBoundingClientRect())) {
+          return { range: candidate.range, changed: false };
+        }
+      }
+      return betweenContext(texts.visible, anchor);
+    }
+    var strand = texts.all;
+    var best = rankedOccurrences(strand.text, anchor)[0];
+    // A quote missing from all the text came from a selection across hidden text, which only the visible
+    // text holds.
+    if (!best) {
+      strand = texts.visible;
+      best = rankedOccurrences(strand.text, anchor)[0];
+    }
+    if (!best) {
+      return betweenContext(texts.visible, anchor);
+    }
+    var span = spanOf(strand, best.at, length);
+    if (!span || !span.first.shown || !span.last.shown) {
+      return null;
+    }
+    return hasArea(span.range.getBoundingClientRect()) ? { range: span.range, changed: false } : null;
   }
 
-  /**
-   * The anchored passage as a range over the page, found across whatever elements it runs through: a
-   * selection picks up formatting on the way, so "Hello world" can be two text nodes with a <strong>
-   * between them and no single node holds the whole quote. The walk concatenates the text in reading order
-   * and maps the match back onto the nodes it spans.
-   */
-  function rangeOfAnchor(anchor) {
-    if (!anchor || !anchor.quote || !document.body) {
+  function betweenContext(strand, anchor) {
+    var prefix = anchor.prefix || "";
+    var suffix = anchor.suffix || "";
+    if (wordLength(prefix) < EDIT_CONTEXT_FLOOR || wordLength(suffix) < EDIT_CONTEXT_FLOOR) {
       return null;
     }
-    var walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT, null);
-    var nodes = [];
-    var text = "";
-    while (walker.nextNode()) {
-      nodes.push({ node: walker.currentNode, from: text.length });
-      text += walker.currentNode.nodeValue || "";
-    }
-    var at = occurrenceOf(text, anchor);
-    if (at < 0) {
-      return null;
+    var text = strand.text;
+    for (var at = text.indexOf(prefix); at >= 0; at = text.indexOf(prefix, at + 1)) {
+      var start = at + prefix.length;
+      var end = text.slice(start, start + EDIT_SPAN_LIMIT + suffix.length).indexOf(suffix);
+      if (end < 0) {
+        continue;
+      }
+      var between = text.slice(start, start + end);
+      var trimmed = between.trim();
+      if (trimmed === "") {
+        continue;
+      }
+      var lead = between.length - between.replace(/^\s+/, "").length;
+      var span = spanOf(strand, start + lead, trimmed.length);
+      if (span && hasArea(span.range.getBoundingClientRect())) {
+        return { range: span.range, changed: true };
+      }
     }
-    var end = at + anchor.quote.length;
+    return null;
+  }
+
+  function wordLength(value) {
+    return value.replace(/\s/g, "").length;
+  }
+
+  function spanOf(strand, at, length) {
+    var end = at + length;
     var range = document.createRange();
-    var started = false;
-    for (var index = 0; index < nodes.length; index += 1) {
-      var entry = nodes[index];
-      var to = entry.from + (entry.node.nodeValue || "").length;
-      if (!started && at < to) {
+    var first = null;
+    for (var index = 0; index < strand.nodes.length; index += 1) {
+      var entry = strand.nodes[index];
+      if (first === null && at < entry.to) {
         range.setStart(entry.node, at - entry.from);
-        started = true;
+        first = entry;
       }
-      if (started && end <= to) {
+      if (first !== null && end <= entry.to) {
         range.setEnd(entry.node, end - entry.from);
-        return range;
+        return { range: range, first: first, last: entry };
       }
     }
     return null;
   }
 
-  /**
-   * Which occurrence of the quote this anchor meant: the one whose neighbouring text agrees with the
-   * recorded context for the most characters, and the earliest of those on a tie — which is also the answer
-   * for an anchor carrying no context, and for a page that has changed until no context matches.
-   */
-  function occurrenceOf(text, anchor) {
-    var best = -1;
-    var bestAgreement = -1;
+  function rankedOccurrences(text, anchor) {
+    var found = [];
     for (var at = text.indexOf(anchor.quote); at >= 0; at = text.indexOf(anchor.quote, at + 1)) {
-      var agreed = agreement(text, at, anchor);
-      if (agreed > bestAgreement) {
-        best = at;
-        bestAgreement = agreed;
-      }
+      found.push({ at: at, agreed: agreement(text, at, anchor) });
     }
-    return best;
+    return found.sort(function (one, other) {
+      return other.agreed - one.agreed || one.at - other.at;
+    });
   }
 
   /** How many characters of the anchor's context the text around this occurrence actually matches. */
@@ -514,13 +815,40 @@
     }
   }
 
+  function watchForChanges() {
+    window.addEventListener("resize", requestDraw);
+    window.addEventListener("load", requestDraw);
+    if (typeof ResizeObserver === "function") {
+      new ResizeObserver(requestDraw).observe(document.documentElement);
+    }
+    if (typeof MutationObserver === "function") {
+      // Without a shadow root the pins live in the host; their changes must not ask for another draw.
+      new MutationObserver(function (records) {
+        for (var index = 0; index < records.length; index += 1) {
+          if (!overlay.host.contains(records[index].target)) {
+            requestDraw();
+            return;
+          }
+        }
+      }).observe(document.documentElement, {
+        childList: true,
+        subtree: true,
+        characterData: true,
+        attributes: true
+      });
+    }
+  }
+
   function startOverlay() {
     overlay = buildOverlay();
     overlay.selectionButton.addEventListener("click", onSelectionComment);
     document.addEventListener("click", onDocumentClick, true);
+    // In the bubbling phase, so a click comment mode takes in the capturing phase never opens a link.
+    document.addEventListener("click", onLinkClick);
+    document.addEventListener("auxclick", onLinkClick);
     document.addEventListener("keydown", onKeyDown);
     document.addEventListener("selectionchange", onSelectionChange);
-    window.addEventListener("resize", drawPins);
+    watchForChanges();
     refreshComments();
   }
 

package/dist/cli/api/execute.d.ts

@@ -4,11 +4,6 @@ import type { ErrorContext } from "../core/errors.js";
 import { type CliIo } from "../core/output.js";
 import { type ResponseSchema } from "../core/redaction.js";
 import type { Profile } from "../core/profile.js";
-/**
- * The schema the reader and the redactor are both handed — `orchestra api` included, so the raw caller and the
- * typed command cannot disagree about which responses are the bare content.
- */
-export declare function responseSchemaOf(row: CommandRow | undefined): ResponseSchema | undefined;
 /** Named so the error mapper prints the sentence and nothing else — no platform framing, no stack. */
 export declare class CommandUsageError extends Error {
     constructor(message: string);
@@ -23,6 +18,8 @@ export interface ConventionValues {
     outputFile?: string;
     /** A local path whose bytes this create stores first and then names. */
     file?: string;
+    /** Asks for the content as Markdown, on a read whose response declares it. */
+    markdown?: boolean;
     /** An exact alias of level `never`. */
     approveSecrets?: boolean;
     requireApproval?: string;