@foldspace_npm/harness 0.1.32 → 0.1.34

package/src/customer-subdomain.mjs

@@ -0,0 +1,149 @@
+// A product that gives each customer their own subdomain - acme.example.com,
+// globex.example.com - must never ship one customer's address: the agent is
+// built signed in to one customer, and every user of every customer would get
+// the code. This module is the one place that decides what "looks like one
+// customer's subdomain" means, for `observe` (which asks the builder) and for
+// lint (which refuses the fixed address). Pure: no network, no filesystem.
+
+import { siteOf } from "./observe-core.mjs";
+
+export const SUBDOMAIN_PLACEHOLDER = "{subdomain}";
+
+// First parts of an address that name a part of the product, a region or an
+// environment - not a customer. Wrong in either direction costs little: a
+// miss here only means the builder is asked one question too many.
+const GENERIC_LABELS = new Set([
+  "app", "apps", "api", "apis", "www", "web", "my", "portal", "dashboard", "admin", "console",
+  "secure", "login", "auth", "accounts", "account", "id", "sso", "oauth", "cloud", "platform",
+  "go", "dev", "develop", "staging", "stage", "test", "qa", "uat", "sandbox", "demo", "beta",
+  "preview", "prod", "production", "live", "global", "m", "mobile", "mail", "help", "support",
+  "docs", "status", "cdn", "static", "assets", "media", "files", "home", "client", "clients",
+  "members", "manage", "manager", "internal", "backoffice", "ops", "studio", "hub", "workspace",
+  "office", "online", "service", "services", "gateway", "data", "reports", "reporting",
+  "analytics", "insights", "billing", "pay", "payments", "shop", "store", "events", "connect",
+]);
+
+// app2, app-eu1, api-staging, eu, us-east-1, na3 ...
+const GENERIC_PATTERN =
+  /^(?:app|api|web|www|eu|us|na|ap|uk|au|ca|de|fr|jp|in|sg|emea|apac|latam)(?:[-_]?[a-z]*\d+|(?:[-_][a-z]+)+(?:[-_]?\d+)?)?$/;
+
+export function isGenericLabel(label) {
+  const value = String(label || "").toLowerCase();
+  return GENERIC_LABELS.has(value) || GENERIC_PATTERN.test(value);
+}
+
+function hostOf(value) {
+  const text = String(value || "").trim().toLowerCase();
+  if (!text) return "";
+  try {
+    return new URL(/^[a-z][a-z0-9+.-]*:\/\//.test(text) ? text : `https://${text}`).hostname.replace(/\.$/, "");
+  } catch {
+    return "";
+  }
+}
+
+/** The first part of a host in front of the product's own domain (`acme` in acme.example.com), or null. A leading `www.` is skipped. */
+export function leftmostLabel(hostOrUrl) {
+  const host = hostOf(hostOrUrl);
+  if (!host || /^[\d.]+$/.test(host) || host === "localhost" || host.endsWith(".localhost")) return null;
+  const labels = host.split(".");
+  if (labels[0] === "www") labels.shift();
+  const siteLabels = siteOf(labels.join(".")).split(".").length;
+  return labels.length > siteLabels ? labels[0] : null;
+}
+
+/**
+ * The customer label to watch for in addresses, given the app's own host and
+ * what the project says (`PER_CUSTOMER_SUBDOMAIN`): `false` - none; `true` -
+ * the first part of the host, whatever it is; undecided - the first part only
+ * when it does not read as a part of the product, a region or an environment.
+ */
+export function customerLabel(appHost, decided) {
+  if (decided === false) return null;
+  const label = leftmostLabel(appHost);
+  if (!label) return null;
+  if (decided === true) return label;
+  return isGenericLabel(label) ? null : label;
+}
+
+/** Whether an address names that customer: a part of its host, or a segment of its path. `{subdomain}` never counts. */
+export function addressNamesLabel(url, label) {
+  if (!label) return false;
+  const want = label.toLowerCase();
+  let parsed;
+  try {
+    parsed = new URL(String(url).replace(/\{subdomain\}/g, "x-subdomain-x"));
+  } catch {
+    return false;
+  }
+  const parts = (text) => text.toLowerCase().split(/[./]/).filter(Boolean);
+  const named = (part) => part === want || part.split(/[-_]/).includes(want);
+  return parts(parsed.hostname).some(named) || parts(decodeURIComponent(parsed.pathname)).some(named);
+}
+
+/**
+ * What API_BASE should say instead of a fixed address that names one
+ * customer: the path alone when the backend is on the app's own host,
+ * otherwise the address with `{subdomain}` where the customer was.
+ */
+export function suggestedApiBase(url, appHost, label) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return `/api`;
+  }
+  const path = parsed.pathname.replace(/\/$/, "");
+  if (parsed.hostname.toLowerCase() === hostOf(appHost)) return path || "/";
+  const swap = (part) =>
+    part.toLowerCase() === label.toLowerCase()
+      ? SUBDOMAIN_PLACEHOLDER
+      : part
+          .split("-")
+          .map((piece) => (piece.toLowerCase() === label.toLowerCase() ? SUBDOMAIN_PLACEHOLDER : piece))
+          .join("-");
+  const host = parsed.hostname.split(".").map(swap).join(".");
+  const swappedPath = path.split("/").map(swap).join("/");
+  return `${parsed.protocol}//${host}${parsed.port ? `:${parsed.port}` : ""}${swappedPath}`;
+}
+
+/** `PER_CUSTOMER_SUBDOMAIN` as written in agent/constants.ts: true, false, or undefined while undecided. */
+export function readCustomerSubdomainSetting(constantsText) {
+  const match = /export\s+const\s+PER_CUSTOMER_SUBDOMAIN\b[^=]*=\s*(true|false)\b/.exec(String(constantsText || ""));
+  return match ? match[1] === "true" : undefined;
+}
+
+/**
+ * For `observe`: when the page's address looks like one customer's own
+ * subdomain and the project has not settled it, say so and what to ask.
+ * `requestUrls` are the calls the page made; one that names the same
+ * customer is the strongest sign, and is reported.
+ */
+export function customerSubdomainHint(pageUrl, requestUrls = [], decided) {
+  if (decided !== undefined) return null;
+  const pageHost = hostOf(pageUrl);
+  const label = customerLabel(pageHost, undefined);
+  if (!label) return null;
+  const seenIn = [];
+  for (const url of requestUrls) {
+    let host;
+    try {
+      host = new URL(url).hostname.toLowerCase();
+    } catch {
+      continue;
+    }
+    if (addressNamesLabel(url, label) && !seenIn.includes(host)) seenIn.push(host);
+    if (seenIn.length >= 4) break;
+  }
+  const site = siteOf(pageHost.replace(/^www\./, ""));
+  return {
+    label,
+    pageHost,
+    ...(seenIn.length ? { backendHosts: seenIn } : {}),
+    hint:
+      `The address starts with "${label}." - that may be one customer's own subdomain, with other customers on other.${site}. ` +
+      `Ask the human once, as a choice: does each of their customers get their own address like ${pageHost}? ` +
+      `Yes: set PER_CUSTOMER_SUBDOMAIN = true in agent/constants.ts and write API_BASE from the page's address ("/api", or "https://{subdomain}.…") - never the address you observed. ` +
+      `No: set PER_CUSTOMER_SUBDOMAIN = false.`,
+  };
+}

package/src/lint/index.mjs

@@ -1,7 +1,14 @@
 import fs from "node:fs";
 import path from "node:path";
 import { listSourceFiles, parseFile, shouldSkipActionFile } from "./ast.mjs";
-import { lintActionFile, lintViewsFile, ruleNoTestModeInBundle, ruleRegistryIntegrity } from "./rules.mjs";
+import {
+  lintActionFile,
+  lintViewsFile,
+  ruleNoTestModeInBundle,
+  ruleRegistryIntegrity,
+  ruleStartersLimit,
+} from "./rules.mjs";
+import { lintSafetyFile, readProjectFacts, ruleNoSecrets } from "./safety.mjs";
 
 export { bundleTurnsOnTestMode } from "./rules.mjs";
 
@@ -47,12 +54,25 @@ export function lintProject(projectDir) {
   }
 
   // Any file under agent/ can end up in the bundle, including code that runs
-  // as soon as the bundle loads, so this rule reads all of it - not only
+  // as soon as the bundle loads, so these rules read all of it - not only
   // actions and views.
   for (const filePath of listSourceFiles(path.join(projectDir, "agent"))) {
-    ruleNoTestModeInBundle(parseFile(filePath), path.relative(projectDir, filePath), findings);
+    const sourceFile = parseFile(filePath);
+    const relative = path.relative(projectDir, filePath);
+    ruleNoTestModeInBundle(sourceFile, relative, findings);
+    ruleStartersLimit(sourceFile, relative, findings);
   }
 
+  // Safety: every file under agent/ the project owns - not agent/runtime/,
+  // which is the harness's own copy - and, for secrets, the whole project.
+  const facts = readProjectFacts(projectDir);
+  for (const filePath of listSourceFiles(path.join(projectDir, "agent"))) {
+    const relative = path.relative(projectDir, filePath);
+    if (relative.split(path.sep)[1] === "runtime") continue;
+    lintSafetyFile(filePath, relative, findings, facts);
+  }
+  ruleNoSecrets(projectDir, findings);
+
   ruleRegistryIntegrity({
     indexFile: entry,
     indexSource: parseFile(entry),

package/src/lint/rules.mjs

@@ -22,9 +22,11 @@ import {
 import { ts } from "./ts.mjs";
 
 /*
+  Safety rules (one customer's address, the user's token, secrets, known
+  hosts) live in ./safety.mjs.
+
   Backlog, not this slice:
-  - no-hardcoded-secrets
-  - no-unsafe-return (stack / cookies / Authorization / ApiResult.detail)
+  - no-unsafe-return (stack / ApiResult.detail)
   - snake_case action keys
   - credentials: "include" on every fetch
   - _gen2 vs _v2 taskKey
@@ -804,6 +806,48 @@ export function ruleNoTestModeInBundle(sourceFile, relative, findings) {
   walk(sourceFile, undefined);
 }
 
+// The most starters one page (or the agent-wide default) shows, both groups
+// together. `setConversationStarters` also sets the panel's opening screen,
+// and a long list there buries the one that matters (a customer default had 7).
+export const MAX_STARTERS = 3;
+
+// Any object with a KNOWLEDGE or ACTION list - a setConversationStarters
+// call, a page's entry in the bottom bar's list, conversationStartersSettings
+// - is counted. Only lists written out in the file are counted: a list built
+// at run time (`.map`, a spread) is left alone.
+export function ruleStartersLimit(sourceFile, relative, findings) {
+  const bindings = collectModuleBindings(sourceFile);
+  const visit = (node) => {
+    if (ts.isObjectLiteralExpression(node)) {
+      let count = 0;
+      let counted = false;
+      for (const prop of objectProperties(node)) {
+        const name = propertyName(prop);
+        if (name !== "KNOWLEDGE" && name !== "ACTION") continue;
+        const list = resolveNode(propertyValue(prop), bindings);
+        if (!list || !ts.isArrayLiteralExpression(list)) continue;
+        counted = true;
+        count += list.elements.filter((element) => !ts.isSpreadElement(element)).length;
+      }
+      if (counted && count > MAX_STARTERS) {
+        findings.push(
+          finding({
+            rule: "starters-limit",
+            severity: "error",
+            sourceFile,
+            node,
+            file: relative,
+            message: `${count} conversation starters in one set; at most ${MAX_STARTERS}, KNOWLEDGE and ACTION together. The same list is the agent panel's opening screen.`,
+            fix: `Keep the ${MAX_STARTERS} that matter most on this page - each one something the agent can answer today.`,
+          }),
+        );
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+}
+
 // What the build checks in the bundle it wrote: minify keeps property names,
 // so a bundle that can turn test mode on still says `setTestMode`. Calls with
 // `false` (`!1` once minified) are allowed; any other mention is not - the