@foldspace_npm/harness 0.1.7 → 0.1.9

package/src/lint/rules.mjs

@@ -0,0 +1,464 @@
+import path from "node:path";
+import {
+  callbackParamName,
+  collectConstBindings,
+  collectModuleBindings,
+  finding,
+  forEachCallNamed,
+  forEachNamedFunction,
+  forEachReturn,
+  forEachStringLiteral,
+  isFunctionLike,
+  normalizeKey,
+  objectProperties,
+  parseFile,
+  propertyName,
+  propertyValue,
+  resolveModulePath,
+  resolveNode,
+  shouldSkipActionFile,
+  stringText,
+} from "./ast.mjs";
+import { ts } from "./ts.mjs";
+
+/*
+  Backlog, not this slice:
+  - no-hardcoded-secrets
+  - no-unsafe-return (stack / cookies / Authorization / ApiResult.detail)
+  - snake_case action keys
+  - credentials: "include" on every fetch
+  - _gen2 vs _v2 taskKey
+*/
+
+const BANNED_PROMPT_KEYS = new Set([
+  "directive",
+  "instructions",
+  "guidance",
+  "systemprompt",
+  "agentinstructions",
+  "nextprompt",
+]);
+
+const RUNTASK_PROMPT_KEYS = new Set(["prompt", "instructions", "systemprompt"]);
+
+const IMPERATIVE_PATTERNS = [
+  /\btell the user\b/i,
+  /\bask the user\b/i,
+  /\bask if they(?:'d| would)\b/i,
+  /\bdo not (?:repeat|call|summarize)\b/i,
+  /\bdon't (?:repeat|call|summarize)\b/i,
+  /\bsummarize the following\b/i,
+  /\brun the [\w-]+ action\b/i,
+  /\bwalk the user through\b/i,
+  /\bproceed to the next step\b/i,
+  /\blet the user know\b/i,
+];
+
+const EMOJI_PATTERN = /\p{Extended_Pictographic}/u;
+
+const PROMPT_FIX =
+  "Put the wording in the action or agent instructions via MCP or Agent Studio; return data only.";
+
+function mergeBindings(fn, sourceFile) {
+  return new Map([
+    ...collectModuleBindings(sourceFile),
+    ...collectConstBindings(fn),
+  ]);
+}
+
+function inspectReturnedObject(obj, bindings, sourceFile, relative, findings, origin) {
+  if (!obj || !ts.isObjectLiteralExpression(obj)) return;
+
+  for (const prop of objectProperties(obj)) {
+    const name = propertyName(prop);
+    const normalized = normalizeKey(name);
+    const valueNode = resolveNode(propertyValue(prop), bindings);
+    const at = prop.name || prop;
+
+    if (BANNED_PROMPT_KEYS.has(normalized)) {
+      findings.push(
+        finding({
+          rule: "no-static-agent-prompt",
+          severity: "error",
+          sourceFile,
+          node: at,
+          file: relative,
+          message: `Do not return '${name}' — that is a second instruction channel besides Agent Studio.`,
+          fix: PROMPT_FIX,
+        }),
+      );
+    }
+
+    const text = stringText(valueNode);
+    if (text && IMPERATIVE_PATTERNS.some((pattern) => pattern.test(text))) {
+      findings.push(
+        finding({
+          rule: "no-static-agent-prompt",
+          severity: "error",
+          sourceFile,
+          node: at,
+          file: relative,
+          message: `${origin} sends the copilot operating instructions ('${text.slice(0, 80)}').`,
+          fix: PROMPT_FIX,
+        }),
+      );
+    }
+
+    if (valueNode && ts.isObjectLiteralExpression(valueNode)) {
+      inspectReturnedObject(valueNode, bindings, sourceFile, relative, findings, origin);
+    }
+  }
+}
+
+export function ruleNoStaticAgentPrompt(sourceFile, relative, findings) {
+  forEachNamedFunction(sourceFile, ["execute", "render", "callback"], (fn, name) => {
+    const bindings = mergeBindings(fn, sourceFile);
+
+    if (name === "execute" || name === "callback") {
+      forEachReturn(fn, (expression) => {
+        inspectReturnedObject(
+          resolveNode(expression, bindings),
+          bindings,
+          sourceFile,
+          relative,
+          findings,
+          name,
+        );
+      });
+    }
+
+    if (name === "render") {
+      const cbName = callbackParamName(fn);
+      forEachCallNamed(fn, cbName, (call) => {
+        const arg = call.arguments[0];
+        if (!arg) return;
+        inspectReturnedObject(
+          resolveNode(arg, bindings),
+          bindings,
+          sourceFile,
+          relative,
+          findings,
+          "callback",
+        );
+      });
+    }
+  });
+}
+
+function inspectRunTaskData(dataNode, bindings, sourceFile, relative, findings, call) {
+  const resolved = resolveNode(dataNode, bindings);
+  if (!resolved || !ts.isObjectLiteralExpression(resolved)) return;
+
+  for (const prop of objectProperties(resolved)) {
+    const name = propertyName(prop);
+    if (!RUNTASK_PROMPT_KEYS.has(normalizeKey(name))) continue;
+    const value = resolveNode(propertyValue(prop), bindings);
+    if (stringText(value) === null) continue;
+    findings.push(
+      finding({
+        rule: "no-runtask-prompt",
+        severity: "error",
+        sourceFile,
+        node: prop.name || call,
+        file: relative,
+        message: `runTask data.${name} is a prompt. Task-agent instructions belong in Agent Studio.`,
+        fix: "Keep task-agent instructions in Agent Studio; pass only extracted facts in data.",
+      }),
+    );
+  }
+}
+
+export function ruleNoRunTaskPrompt(sourceFile, relative, findings) {
+  const moduleBindings = collectModuleBindings(sourceFile);
+
+  function walk(node, fnBindings) {
+    if (isFunctionLike(node) && node !== sourceFile) {
+      const nested = mergeBindings(node, sourceFile);
+      ts.forEachChild(node, (child) => walk(child, nested));
+      return;
+    }
+
+    if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+      if (node.expression.name.text === "runTask") {
+        const arg = node.arguments[0];
+        const bindings = fnBindings || moduleBindings;
+        const config = resolveNode(arg, bindings);
+        if (config && ts.isObjectLiteralExpression(config)) {
+          for (const prop of objectProperties(config)) {
+            if (propertyName(prop) !== "data") continue;
+            inspectRunTaskData(propertyValue(prop), bindings, sourceFile, relative, findings, node);
+          }
+        }
+      }
+    }
+
+    ts.forEachChild(node, (child) => walk(child, fnBindings));
+  }
+
+  walk(sourceFile, moduleBindings);
+}
+
+function reportEmoji(node, sourceFile, relative, findings) {
+  const text = stringText(node);
+  if (!text || !EMOJI_PATTERN.test(text)) return;
+  findings.push(
+    finding({
+      rule: "no-emoji",
+      severity: "warning",
+      sourceFile,
+      node,
+      file: relative,
+      message: "Emoji in handler or widget copy reads as off-brand in a product UI that has none.",
+      fix: "Strip the glyph from handler/render copy. Put “no emoji” in the agent's Behavior instructions; the MCP cannot write that field, so each new action's Studio instructions must carry the line too.",
+    }),
+  );
+}
+
+export function ruleNoEmoji(sourceFile, relative, findings, { wholeFile = false } = {}) {
+  if (wholeFile) {
+    forEachStringLiteral(sourceFile, (node) => {
+      if (ts.isImportDeclaration(node.parent) || ts.isExportDeclaration(node.parent)) return;
+      reportEmoji(node, sourceFile, relative, findings);
+    });
+    return;
+  }
+
+  forEachNamedFunction(sourceFile, ["execute", "render", "callback"], (fn) => {
+    const bindings = mergeBindings(fn, sourceFile);
+    forEachStringLiteral(
+      fn,
+      (node) => reportEmoji(node, sourceFile, relative, findings),
+      { skipNestedFunctions: true, root: fn },
+    );
+
+    function walk(current) {
+      if (current !== fn && isFunctionLike(current)) return;
+      if (ts.isIdentifier(current)) {
+        const resolved = resolveNode(current, bindings);
+        if (
+          resolved &&
+          resolved !== current &&
+          (resolved.getStart(sourceFile) < fn.getStart(sourceFile) ||
+            resolved.getEnd() > fn.getEnd())
+        ) {
+          reportEmoji(resolved, sourceFile, relative, findings);
+        }
+      }
+      ts.forEachChild(current, walk);
+    }
+    walk(fn);
+  });
+}
+
+function exportedBindings(sourceFile) {
+  const exports = [];
+
+  function objectHasExecute(node) {
+    if (!node || !ts.isObjectLiteralExpression(node)) return false;
+    return objectProperties(node).some((prop) => propertyName(prop) === "execute");
+  }
+
+  for (const stmt of sourceFile.statements) {
+    if (ts.isVariableStatement(stmt) && stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) {
+      for (const decl of stmt.declarationList.declarations) {
+        if (!ts.isIdentifier(decl.name)) continue;
+        const init = decl.initializer;
+        exports.push({
+          name: decl.name.text,
+          node: decl.name,
+          hasExecute: objectHasExecute(init),
+          isFunction: isFunctionLike(init),
+        });
+      }
+    }
+    if (ts.isFunctionDeclaration(stmt) && stmt.name && stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) {
+      exports.push({
+        name: stmt.name.text,
+        node: stmt.name,
+        hasExecute: false,
+        isFunction: true,
+      });
+    }
+  }
+  return exports;
+}
+
+function collectImports(sourceFile, filePath) {
+  const map = new Map();
+  for (const stmt of sourceFile.statements) {
+    if (!ts.isImportDeclaration(stmt) || !stmt.importClause) continue;
+    if (!ts.isStringLiteral(stmt.moduleSpecifier)) continue;
+    const resolved = resolveModulePath(filePath, stmt.moduleSpecifier.text);
+    if (!resolved) continue;
+    const clause = stmt.importClause;
+    if (clause.namedBindings && ts.isNamedImports(clause.namedBindings)) {
+      for (const spec of clause.namedBindings.elements) {
+        const imported = (spec.propertyName || spec.name).text;
+        map.set(spec.name.text, { file: resolved, imported });
+      }
+    }
+    if (clause.name) {
+      map.set(clause.name.text, { file: resolved, imported: "default" });
+    }
+  }
+  return map;
+}
+
+function findRegistryObject(sourceFile) {
+  let found = null;
+
+  function consider(node) {
+    if (node && ts.isObjectLiteralExpression(node)) found = found || node;
+  }
+
+  function walk(node) {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === "actions") {
+      consider(node.initializer);
+    }
+    if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
+      const left = node.left.getText(sourceFile);
+      if (left.includes("__FOLDSPACE_REMOTE_ACTIONS__") || left.endsWith(".actions")) {
+        if (ts.isIdentifier(node.right) && node.right.text === "actions") {
+          // resolved via variable declaration
+        } else {
+          consider(node.right);
+        }
+      }
+    }
+    ts.forEachChild(node, walk);
+  }
+
+  walk(sourceFile);
+  return found;
+}
+
+export function ruleRegistryIntegrity({ indexFile, indexSource, actionFiles, projectDir, findings }) {
+  const relativeIndex = path.relative(projectDir, indexFile);
+  const registry = findRegistryObject(indexSource);
+  const imports = collectImports(indexSource, indexFile);
+  const seenKeys = new Map();
+  const registeredNames = new Set();
+
+  if (registry) {
+    for (const prop of objectProperties(registry)) {
+      const key = propertyName(prop);
+      if (!key) continue;
+      if (seenKeys.has(key)) {
+        findings.push(
+          finding({
+            rule: "registry-integrity",
+            severity: "warning",
+            sourceFile: indexSource,
+            node: prop.name || prop,
+            file: relativeIndex,
+            message: `Duplicate registry key '${key}'. The second entry silently wins.`,
+            fix: "Give each registered action a unique key that matches Agent Studio.",
+          }),
+        );
+      }
+      seenKeys.set(key, prop);
+
+      const value = propertyValue(prop);
+      if (isFunctionLike(value)) {
+        findings.push(
+          finding({
+            rule: "registry-integrity",
+            severity: "warning",
+            sourceFile: indexSource,
+            node: prop.name || prop,
+            file: relativeIndex,
+            message: `Registry entry '${key}' is a function. The SDK expects { execute }.`,
+            fix: "Register an object with an execute function.",
+          }),
+        );
+        continue;
+      }
+      if (ts.isObjectLiteralExpression(value)) {
+        const hasExecute = objectProperties(value).some((entry) => propertyName(entry) === "execute");
+        if (!hasExecute) {
+          findings.push(
+            finding({
+              rule: "registry-integrity",
+              severity: "warning",
+              sourceFile: indexSource,
+              node: prop.name || prop,
+              file: relativeIndex,
+              message: `Registry entry '${key}' is an object without execute.`,
+              fix: "Register an object with an execute function.",
+            }),
+          );
+        }
+        continue;
+      }
+      if (ts.isIdentifier(value)) {
+        registeredNames.add(value.text);
+        const imported = imports.get(value.text);
+        if (imported) {
+          const exported = exportedBindings(parseFile(imported.file)).find(
+            (item) => item.name === imported.imported || item.name === value.text,
+          );
+          if (exported?.isFunction && !exported.hasExecute) {
+            findings.push(
+              finding({
+                rule: "registry-integrity",
+                severity: "warning",
+                sourceFile: indexSource,
+                node: prop.name || prop,
+                file: relativeIndex,
+                message: `Registry entry '${key}' points at a bare function, not { execute }.`,
+                fix: "Export and register an object with an execute function.",
+              }),
+            );
+          } else if (exported && !exported.hasExecute && !exported.isFunction) {
+            findings.push(
+              finding({
+                rule: "registry-integrity",
+                severity: "warning",
+                sourceFile: indexSource,
+                node: prop.name || prop,
+                file: relativeIndex,
+                message: `Registry entry '${key}' points at an object without execute.`,
+                fix: "Export and register an object with an execute function.",
+              }),
+            );
+          }
+        }
+      }
+    }
+  }
+
+  for (const filePath of actionFiles) {
+    if (filePath === indexFile) continue;
+    if (shouldSkipActionFile(filePath)) continue;
+    const sourceFile = parseFile(filePath);
+    const relative = path.relative(projectDir, filePath);
+    for (const exported of exportedBindings(sourceFile)) {
+      if (!exported.hasExecute) continue;
+      if (registeredNames.has(exported.name) || seenKeys.has(exported.name)) continue;
+      findings.push(
+        finding({
+          rule: "registry-integrity",
+          severity: "warning",
+          sourceFile,
+          node: exported.node,
+          file: relative,
+          message: `'${exported.name}' exports { execute } but is not registered in agent/actions/index.ts.`,
+          fix: "Import it and add it to the actions object. An unregistered handler never fires.",
+        }),
+      );
+    }
+  }
+}
+
+export function lintActionFile(filePath, relative, findings) {
+  if (shouldSkipActionFile(filePath)) return;
+  const sourceFile = parseFile(filePath);
+  ruleNoStaticAgentPrompt(sourceFile, relative, findings);
+  ruleNoRunTaskPrompt(sourceFile, relative, findings);
+  ruleNoEmoji(sourceFile, relative, findings);
+}
+
+export function lintViewsFile(filePath, relative, findings) {
+  const sourceFile = parseFile(filePath);
+  ruleNoEmoji(sourceFile, relative, findings, { wholeFile: true });
+}

package/src/lint/ts.mjs

@@ -0,0 +1,6 @@
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+
+/** TypeScript compiler API, resolved from this package — not the tenant. */
+export const ts = require("typescript");

package/src/runtime/agent.ts

@@ -0,0 +1,66 @@
+import { getConfig } from "./config";
+
+let cached: any | null = null;
+
+/**
+ * Foldspace SDK handle for this agent's **overlay** instance.
+ *
+ * Takes no `mode` on purpose: `foldspace.agent({ apiName })` returns the overlay
+ * handle. On an app that embeds the copilot in-page that is not the instance
+ * serving the chat, so arming only it succeeds and leaves real conversations
+ * untagged. For a specific instance, enumerate `window.foldspace.agentIds()`
+ * (`"<mode>-<apiName>"`) and call `foldspace.agent({ apiName, mode })`.
+ *
+ * This is a thin wrapper around the SDK, not a second agent implementation.
+ * Cached after the first successful lookup.
+ *
+ * @returns The overlay agent, or `null` if the SDK is not on the page
+ */
+export function getAgent(): any | null {
+  if (cached) return cached;
+  cached =
+    (window as any).foldspace?.agent({ apiName: getConfig().agentApiName }) ??
+    null;
+  return cached;
+}
+
+/**
+ * Arm every Foldspace instance on the page for test mode and remote actions.
+ *
+ * Calls SDK `setTestMode` and `setConfiguration({ remoteActionsSettings })`.
+ * Local `foldspace attach` already injects test-mode arming without putting it
+ * in `dist/index.js`. Prefer that. Importing this helper from an action can
+ * ship those calls into the production CDN bundle.
+ *
+ * Do not call from `execute`. Partial `setConfiguration` has collapsed the
+ * widget to 0×0 in a real build.
+ *
+ * @param testMode - When true, mark conversations as test traffic
+ * @returns Instance ids that armed vs failed
+ */
+export function armAllInstances(testMode = true): {
+  armed: string[];
+  failed: string[];
+} {
+  const fs = (window as any).foldspace;
+  const armed: string[] = [];
+  const failed: string[] = [];
+  if (!fs || typeof fs.agentIds !== "function") return { armed, failed };
+
+  for (const id of fs.agentIds() as string[]) {
+    const cut = id.indexOf("-");
+    if (cut < 1) continue;
+    try {
+      const inst = fs.agent({
+        apiName: id.slice(cut + 1),
+        mode: id.slice(0, cut).toUpperCase(),
+      });
+      inst.setTestMode(testMode);
+      inst.setConfiguration({ remoteActionsSettings: { enabled: true } });
+      armed.push(id);
+    } catch {
+      failed.push(id);
+    }
+  }
+  return { armed, failed };
+}

package/src/runtime/config.ts

@@ -0,0 +1,78 @@
+/**
+ * Tenant-specific facts for the page runtime. Set once from `agent/utils.ts`.
+ *
+ * This module cannot import the client's `constants.ts`, so the client pushes
+ * values in with {@link configure}. Nothing here is a Foldspace cloud setting.
+ */
+
+/**
+ * Where the customer app keeps its own session token — not a Foldspace token.
+ *
+ * Custom headers (not Bearer) are out of scope: override `apiFetch` in
+ * `agent/utils.ts` instead of adding a third `kind`.
+ */
+export interface AuthSource {
+  /** Where the live page stores the token. */
+  kind: "localStorage" | "cookie";
+  /** The localStorage key or cookie name observed on the page. */
+  name: string;
+}
+
+/**
+ * Values {@link configure} stores for the rest of the runtime.
+ *
+ * Stamp `apiBase` and `authSource` empty until you capture a real XHR. A
+ * guessed host or Bearer vs cookie looks like success and publishes to the
+ * wrong place.
+ */
+export interface RuntimeConfig {
+  /** Foldspace agent apiName, e.g. `joist-agent`. */
+  agentApiName: string;
+  /**
+   * Prefix for `apiFetch` / `apiFetchBinary`. Include an explicit port if the
+   * app uses one — omitting `:443` can fail CORS.
+   */
+  apiBase?: string;
+  /**
+   * Prefix for `publicFetch` when the caller does not pass an origin.
+   * Marketing / unauthenticated hosts only.
+   */
+  publicOrigin?: string;
+  /** Session location for `getAuthToken`. Omit until observed. */
+  authSource?: AuthSource;
+  /** `fetch` timeout in ms. Defaults to 15_000 in `configure`. */
+  timeoutMs?: number;
+}
+
+let config: RuntimeConfig | null = null;
+
+/**
+ * Store tenant config for this page bundle. Call once from `agent/utils.ts`
+ * at module load — not from an action `execute`.
+ *
+ * Replaces the previous object; it does not merge. A second call clobbers the
+ * first. `timeoutMs` defaults to 15_000 if omitted.
+ *
+ * @param next - Tenant ids and observed API/auth facts
+ */
+export function configure(next: RuntimeConfig): void {
+  config = { timeoutMs: 15_000, ...next };
+}
+
+/**
+ * Read the config {@link configure} stored.
+ *
+ * Throws if `configure` never ran (imported the runtime without going through
+ * `agent/utils.ts`). Empty `apiBase` / `authSource` after configure is valid;
+ * `apiFetch` returns `{ ok: false }` for those instead of throwing.
+ *
+ * @returns The singleton config for this bundle
+ */
+export function getConfig(): RuntimeConfig {
+  if (!config) {
+    throw new Error(
+      "harness runtime is not configured — call configure() from agent/utils.ts",
+    );
+  }
+  return config;
+}