@foldspace_npm/harness 0.1.7 → 0.1.9

package/README.md

@@ -27,6 +27,7 @@ constraint this package exists to protect.
 
 - `agent/actions/*` and `agent/api/*` — a handler is `fetch` plus `runTask`,
   nothing more. The actions built for Figma run unmodified in either track.
+- `agent/utils.ts` — configures and re-exports `@foldspace_npm/harness/runtime`
 - `foldspace build` — esbuild → `dist/index.js`
 - `foldspace deploy` — publish to `agent/actions/<env>/<productId>/<agentApiName>`
 - fixtures and tests
@@ -93,7 +94,7 @@ npx --yes @foldspace_npm/harness init
 Non-interactive / CI form:
 
 ```bash
-npx --yes @foldspace_npm/harness init my-agent \
+npx --yes @foldspace_npm/harness init foldspace-agent \
   --product-id FR8JUQZAQRZB \
   --agent-key my-agent \
   --domain app.example.com \
@@ -103,24 +104,25 @@ npx --yes @foldspace_npm/harness init my-agent \
 When running directly from a harness checkout during development:
 
 ```bash
-node bin/cli.mjs init ../my-agent \
+node bin/cli.mjs init ../foldspace-agent \
   --product-id FR8JUQZAQRZB \
   --agent-key my-agent \
   --domain app.example.com
 ```
 
-The Agent Key is the value shown in Agent Studio, such as `my-agent`.
-`--agent-api-name` remains a deprecated alias for `--agent-key`. `--name` is
-optional and defaults to the target directory name. The product ID must be the
-bare ID, not the `EU-…-1-1` SDK loader key. The domain may be a hostname or an
-HTTP(S) URL without a port or path.
+The Agent Key is the value shown in Agent Studio, such as `my-agent`. It is
+not the sidecar directory name. `--agent-api-name` remains a deprecated alias
+for `--agent-key`. `--name` is optional and defaults to the target directory
+name (`foldspace-agent` unless you pass a directory). The product ID must be
+the bare ID, not the `EU-…-1-1` SDK loader key. The domain may be a hostname
+or an HTTP(S) URL without a port or path.
 
 For safety, `init` requires a target path that does not exist. It does not
 initialize Git or overwrite files. On a TTY it can offer
 `npm install --ignore-scripts` after scaffolding. After creation:
 
 ```bash
-cd my-agent
+cd foldspace-agent
 npm install --ignore-scripts   # if you skipped the install prompt
 npm run build
 npm run inject
@@ -130,6 +132,34 @@ npm run attach
 The generated npm scripts intentionally remain the normal project interface;
 `foldspace init` is the one-time project creation command.
 
+### Lint handlers before they ship
+
+`foldspace build` runs `foldspace lint` first. Errors skip bundling; warnings
+print and still produce `dist/index.js`.
+
+```bash
+foldspace lint
+foldspace lint --json
+```
+
+v1 flags:
+
+- **error** `no-static-agent-prompt` — `execute` / chatterblock `callback` returning copilot instructions (`directive`, “tell the user”, …)
+- **error** `no-runtask-prompt` — `runTask({ data: { prompt } })` and the same keys; a customer API field named `prompt` is allowed
+- **warning** `no-emoji` — emoji in handler or `agent/views` string literals
+- **warning** `registry-integrity` — duplicate keys, `{ execute }` not registered, registry value missing `execute`
+
+Put action instructions in Agent Studio or MCP. `foldspace lint` cannot see that copy.
+
+### Runtime helpers
+
+Tenant actions import from `agent/utils.ts`, which configures and re-exports
+`@foldspace_npm/harness/runtime`. That code is bundled into `dist/index.js` and
+runs in the customer's page — it is not a CLI command.
+
+`API_BASE` and `AUTH_SOURCE` stamp empty. Fill them from a captured XHR, not a
+guess. Custom auth headers stay a tenant override of one function in `utils.ts`.
+
 ### Choose an attach mode
 
 - **Swap (default):** the page already uses the configured product and agent.

package/bin/build.ts

@@ -2,6 +2,7 @@ import * as esbuild from "esbuild";
 import * as fs from "fs";
 import * as path from "path";
 import { fileURLToPath } from "url";
+import { lintProject, printLint } from "../src/lint/index.mjs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const projectDir = process.env.FOLDSPACE_PROJECT_DIR || process.cwd();
@@ -10,6 +11,14 @@ const agentActionsEntry = path.join(projectDir, "agent", "actions", "index.ts");
 
 const watchMode = process.argv.includes("--watch");
 
+function gateLint(): void {
+  const result = lintProject(projectDir);
+  printLint(result);
+  if (result.errorCount > 0) {
+    process.exit(1);
+  }
+}
+
 function buildOptions(): esbuild.BuildOptions {
   return {
     entryPoints: [agentActionsEntry],
@@ -27,6 +36,13 @@ function rebuildPlugin(): esbuild.Plugin {
   return {
     name: "rebuild-notify",
     setup(build) {
+      build.onStart(() => {
+        const result = lintProject(projectDir);
+        printLint(result);
+        if (result.errorCount > 0) {
+          throw new Error("foldspace lint failed");
+        }
+      });
       build.onEnd((result) => {
         const time = new Date().toLocaleTimeString();
         if (result.errors.length === 0) {
@@ -47,6 +63,10 @@ async function build() {
     process.exit(1);
   }
 
+  if (!watchMode) {
+    gateLint();
+  }
+
   if (!fs.existsSync(distDir)) {
     fs.mkdirSync(distDir, { recursive: true });
   }

package/bin/lint.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { lintProject, printLint } from "../src/lint/index.mjs";
+
+const projectDir = process.env.FOLDSPACE_PROJECT_DIR || process.cwd();
+const json = process.argv.includes("--json");
+const result = lintProject(projectDir);
+printLint(result, { json });
+process.exit(result.errorCount > 0 ? 1 : 0);

package/package.json

@@ -1,12 +1,19 @@
 {
   "name": "@foldspace_npm/harness",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Build and verify portable Foldspace action artifacts against a live app.",
   "type": "module",
   "bin": {
     "foldspace": "bin/cli.mjs",
     "harness": "bin/cli.mjs"
   },
+  "exports": {
+    "./runtime": {
+      "types": "./src/runtime/index.ts",
+      "default": "./src/runtime/index.ts"
+    },
+    "./package.json": "./package.json"
+  },
   "scripts": {
     "test": "node --test test/*.test.mjs"
   },
@@ -18,7 +25,8 @@
   ],
   "dependencies": {
     "esbuild": "^0.20.0",
-    "tsx": "^4.7.0"
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3"
   },
   "engines": {
     "node": ">=20"

package/src/cli-registry.mjs

@@ -74,9 +74,33 @@ export const CLI_COMMANDS = Object.freeze([
     positionals: [],
     options: [flag("--watch", "Rebuild when action source changes")],
     prerequisites: ["agent/actions/index.ts"],
-    effects: ["Writes dist/index.js"],
+    effects: [
+      "Runs foldspace lint first; errors skip bundling",
+      "Writes dist/index.js when lint has no errors",
+    ],
     next: ["Run foldspace inject", "Run foldspace attach"],
   }),
+  Object.freeze({
+    name: "lint",
+    entry: "lint.mjs",
+    group: "develop",
+    summary: "Check action handlers for prompt, registry, and copy issues",
+    usage: "foldspace lint [--json]",
+    risk: "local-write",
+    environment: "node",
+    environmentVariables: ["FOLDSPACE_PROJECT_DIR"],
+    capabilities: ["artifact.build"],
+    positionals: [],
+    options: [
+      flag("--json", "Print findings as machine-readable JSON"),
+    ],
+    prerequisites: ["agent/actions/index.ts"],
+    effects: [
+      "Reads agent/actions (and agent/views when present); writes nothing",
+      "Errors fail the process; warnings print and still exit 0",
+    ],
+    next: ["Fix reported findings", "Run foldspace build"],
+  }),
   Object.freeze({
     name: "inject",
     entry: "inject.mjs",

package/src/init.mjs

@@ -16,7 +16,7 @@ const allowedFlags = new Set([
   "domain",
 ]);
 const tokenPattern = /\{\{([A-Z0-9_]+)\}\}/g;
-const defaultDirectory = "my-agent";
+const defaultDirectory = "foldspace-agent";
 
 export const initUsage = commandByName("init").usage;
 
@@ -306,7 +306,9 @@ function createTemplateValues(config, harnessVersion) {
     PACKAGE_DESCRIPTION_JSON: JSON.stringify(`Foldspace browser actions for ${displayName}.`),
     PRODUCT_ID_JSON: JSON.stringify(productId),
     AGENT_API_NAME_JSON: JSON.stringify(agentApiName),
+    APP_DOMAIN: target.domain,
     APP_DOMAIN_JSON: JSON.stringify(target.domain),
+    START_URL: target.startUrl,
     START_URL_JSON: JSON.stringify(target.startUrl),
     HOSTS_JSON: JSON.stringify(hosts),
     HARNESS_VERSION: harnessVersion,

package/src/lint/ast.mjs

@@ -0,0 +1,237 @@
+import fs from "node:fs";
+import path from "node:path";
+import { ts } from "./ts.mjs";
+
+export function listSourceFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...listSourceFiles(full));
+      continue;
+    }
+    if (entry.isFile() && /\.(ts|js)$/.test(entry.name) && !entry.name.endsWith(".d.ts")) {
+      out.push(full);
+    }
+  }
+  return out.sort();
+}
+
+export function shouldSkipActionFile(filePath) {
+  const base = path.basename(filePath);
+  return base.startsWith("_example") || /\.test\./.test(base);
+}
+
+export function parseFile(filePath) {
+  const text = fs.readFileSync(filePath, "utf8");
+  const kind = filePath.endsWith(".ts") ? ts.ScriptKind.TS : ts.ScriptKind.JS;
+  return ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true, kind);
+}
+
+export function loc(sourceFile, node) {
+  const start = node.getStart(sourceFile);
+  const { line, character } = sourceFile.getLineAndCharacterOfPosition(start);
+  return { line: line + 1, column: character + 1 };
+}
+
+export function propertyName(node) {
+  if (!node?.name) return null;
+  if (ts.isIdentifier(node.name) || ts.isPrivateIdentifier(node.name)) {
+    return node.name.text;
+  }
+  if (ts.isStringLiteral(node.name) || ts.isNumericLiteral(node.name)) {
+    return node.name.text;
+  }
+  return null;
+}
+
+export function normalizeKey(name) {
+  return String(name || "")
+    .replace(/_/g, "")
+    .toLowerCase();
+}
+
+export function isFunctionLike(node) {
+  return (
+    node &&
+    (ts.isFunctionDeclaration(node) ||
+      ts.isFunctionExpression(node) ||
+      ts.isArrowFunction(node) ||
+      ts.isMethodDeclaration(node) ||
+      ts.isConstructorDeclaration(node))
+  );
+}
+
+function initializerOf(node) {
+  if (ts.isPropertyAssignment(node)) return node.initializer;
+  if (ts.isMethodDeclaration(node)) return node;
+  if (ts.isPropertyDeclaration(node)) return node.initializer;
+  return null;
+}
+
+/**
+ * Call `visit(fn, name)` for execute / render / callback function-likes.
+ */
+export function forEachNamedFunction(sourceFile, names, visit) {
+  const wanted = names instanceof Set ? names : new Set(names);
+
+  function walk(node) {
+    if (
+      ts.isPropertyAssignment(node) ||
+      ts.isMethodDeclaration(node) ||
+      ts.isPropertyDeclaration(node)
+    ) {
+      const name = propertyName(node);
+      if (name && wanted.has(name)) {
+        const target = initializerOf(node);
+        if (isFunctionLike(target)) visit(target, name, node);
+      }
+    }
+    ts.forEachChild(node, walk);
+  }
+
+  walk(sourceFile);
+}
+
+export function callbackParamName(fn) {
+  const params = fn.parameters || [];
+  if (params.length >= 4 && ts.isIdentifier(params[3].name)) {
+    return params[3].name.text;
+  }
+  return "callback";
+}
+
+export function collectConstBindings(scopeNode) {
+  const map = new Map();
+
+  function visit(node) {
+    if (node !== scopeNode && isFunctionLike(node)) return;
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
+      map.set(node.name.text, node.initializer);
+    }
+    ts.forEachChild(node, visit);
+  }
+
+  visit(scopeNode);
+  return map;
+}
+
+export function collectModuleBindings(sourceFile) {
+  const map = new Map();
+  for (const stmt of sourceFile.statements) {
+    if (!ts.isVariableStatement(stmt)) continue;
+    for (const decl of stmt.declarationList.declarations) {
+      if (ts.isIdentifier(decl.name) && decl.initializer) {
+        map.set(decl.name.text, decl.initializer);
+      }
+    }
+  }
+  return map;
+}
+
+export function resolveNode(node, bindings, depth = 0) {
+  if (!node || depth > 8) return node;
+  if (ts.isIdentifier(node)) {
+    const next = bindings.get(node.text);
+    if (!next) return node;
+    return resolveNode(next, bindings, depth + 1);
+  }
+  if (ts.isAsExpression(node) || ts.isParenthesizedExpression(node) || ts.isSatisfiesExpression(node)) {
+    return resolveNode(node.expression, bindings, depth + 1);
+  }
+  return node;
+}
+
+export function stringText(node) {
+  if (!node) return null;
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+    return node.text;
+  }
+  if (ts.isTemplateExpression(node)) {
+    return [
+      node.head.text,
+      ...node.templateSpans.map((span) => span.literal.text),
+    ].join("");
+  }
+  return null;
+}
+
+export function forEachStringLiteral(node, visit, { skipNestedFunctions = false, root = node } = {}) {
+  function walk(current) {
+    if (skipNestedFunctions && current !== root && isFunctionLike(current)) return;
+    if (
+      ts.isStringLiteral(current) ||
+      ts.isNoSubstitutionTemplateLiteral(current) ||
+      ts.isTemplateExpression(current)
+    ) {
+      visit(current);
+    }
+    ts.forEachChild(current, walk);
+  }
+  walk(node);
+}
+
+export function forEachReturn(fn, visit) {
+  if (ts.isArrowFunction(fn) && fn.body && !ts.isBlock(fn.body)) {
+    visit(fn.body, fn);
+    return;
+  }
+  function walk(node) {
+    if (node !== fn && isFunctionLike(node)) return;
+    if (ts.isReturnStatement(node) && node.expression) visit(node.expression, node);
+    ts.forEachChild(node, walk);
+  }
+  walk(fn);
+}
+
+export function forEachCallNamed(fn, name, visit) {
+  function walk(node) {
+    if (node !== fn && isFunctionLike(node)) return;
+    if (ts.isCallExpression(node)) {
+      if (ts.isIdentifier(node.expression) && node.expression.text === name) {
+        visit(node);
+      }
+    }
+    ts.forEachChild(node, walk);
+  }
+  walk(fn);
+}
+
+export function objectProperties(obj) {
+  if (!obj || !ts.isObjectLiteralExpression(obj)) return [];
+  return obj.properties.filter(
+    (prop) => ts.isPropertyAssignment(prop) || ts.isShorthandPropertyAssignment(prop),
+  );
+}
+
+export function propertyValue(prop) {
+  if (ts.isShorthandPropertyAssignment(prop)) return prop.name;
+  return prop.initializer;
+}
+
+export function resolveModulePath(fromFile, specifier) {
+  if (!specifier || !specifier.startsWith(".")) return null;
+  const base = path.resolve(path.dirname(fromFile), specifier);
+  const candidates = [
+    base,
+    `${base}.ts`,
+    `${base}.js`,
+    path.join(base, "index.ts"),
+    path.join(base, "index.js"),
+  ];
+  return candidates.find((candidate) => fs.existsSync(candidate) && fs.statSync(candidate).isFile()) || null;
+}
+
+export function finding({ rule, severity, sourceFile, node, message, fix, file }) {
+  const position = loc(sourceFile, node);
+  return {
+    rule,
+    severity,
+    file,
+    line: position.line,
+    column: position.column,
+    message,
+    fix,
+  };
+}

package/src/lint/index.mjs

@@ -0,0 +1,101 @@
+import fs from "node:fs";
+import path from "node:path";
+import { listSourceFiles, parseFile, shouldSkipActionFile } from "./ast.mjs";
+import { lintActionFile, lintViewsFile, ruleRegistryIntegrity } from "./rules.mjs";
+
+export const LINT_SCHEMA_VERSION = 1;
+
+export function lintProject(projectDir) {
+  const actionsDir = path.join(projectDir, "agent", "actions");
+  const indexFile = path.join(actionsDir, "index.ts");
+  const indexJs = path.join(actionsDir, "index.js");
+  const entry = fs.existsSync(indexFile) ? indexFile : fs.existsSync(indexJs) ? indexJs : null;
+
+  if (!entry) {
+    return {
+      ok: false,
+      errorCount: 1,
+      warningCount: 0,
+      findings: [
+        {
+          rule: "registry-integrity",
+          severity: "error",
+          file: "agent/actions/index.ts",
+          line: 1,
+          column: 1,
+          message: "Entry point not found: agent/actions/index.ts",
+          fix: "Create agent/actions/index.ts and register handlers there.",
+        },
+      ],
+    };
+  }
+
+  const findings = [];
+  const actionFiles = listSourceFiles(actionsDir);
+
+  for (const filePath of actionFiles) {
+    lintActionFile(filePath, path.relative(projectDir, filePath), findings);
+  }
+
+  const viewsDir = path.join(projectDir, "agent", "views");
+  if (fs.existsSync(viewsDir)) {
+    for (const filePath of listSourceFiles(viewsDir)) {
+      lintViewsFile(filePath, path.relative(projectDir, filePath), findings);
+    }
+  }
+
+  ruleRegistryIntegrity({
+    indexFile: entry,
+    indexSource: parseFile(entry),
+    actionFiles,
+    projectDir,
+    findings,
+  });
+
+  const errorCount = findings.filter((item) => item.severity === "error").length;
+  const warningCount = findings.filter((item) => item.severity === "warning").length;
+  return {
+    ok: errorCount === 0,
+    errorCount,
+    warningCount,
+    findings,
+  };
+}
+
+function formatFinding(item) {
+  return `${item.file}:${item.line}:${item.column}  ${item.severity}  ${item.rule}  ${item.message}\n  Fix: ${item.fix}`;
+}
+
+export function renderLintText(result) {
+  if (!result.findings.length) {
+    return "foldspace lint: no issues";
+  }
+  const body = result.findings.map(formatFinding).join("\n");
+  const summary = `${result.errorCount} error${result.errorCount === 1 ? "" : "s"}, ${result.warningCount} warning${result.warningCount === 1 ? "" : "s"}`;
+  return `${body}\n\n${summary}`;
+}
+
+export function renderLintJson(result) {
+  return {
+    kind: "foldspace.lint",
+    schemaVersion: LINT_SCHEMA_VERSION,
+    ok: result.ok,
+    errorCount: result.errorCount,
+    warningCount: result.warningCount,
+    findings: result.findings,
+  };
+}
+
+export function printLint(result, { json = false, stdout = console.log, stderr = console.error } = {}) {
+  if (json) {
+    stdout(JSON.stringify(renderLintJson(result), null, 2));
+    return;
+  }
+  const text = renderLintText(result);
+  if (result.errorCount > 0) stderr(text);
+  else stdout(text);
+}
+
+export function shouldSkipFile(filePath) {
+  return shouldSkipActionFile(filePath);
+}