@foldspace_npm/harness 0.1.3 → 0.1.4

package/README.md

@@ -95,7 +95,7 @@ Non-interactive / CI form:
 ```bash
 npx --yes @foldspace_npm/harness init my-agent \
   --product-id FR8JUQZAQRZB \
-  --agent-api-name my-agent \
+  --agent-key my-agent \
   --domain app.example.com \
   --name "My Agent"
 ```
@@ -105,12 +105,14 @@ When running directly from a harness checkout during development:
 ```bash
 node bin/cli.mjs init ../my-agent \
   --product-id FR8JUQZAQRZB \
-  --agent-api-name my-agent \
+  --agent-key my-agent \
   --domain app.example.com
 ```
 
-`--name` is optional and defaults to the target directory name. The product ID
-must be the bare ID, not an `EU-…` SDK key. The domain may be a hostname or an
+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.
 
 For safety, `init` requires a target path that does not exist. It does not

package/bin/cli.mjs

@@ -62,9 +62,13 @@ function printHelp(topic, json) {
 }
 
 function normalizeCommandArgs(command, args) {
-  const options = new Map(
-    command.options.map((option) => [option.name, option]),
-  );
+  const options = new Map();
+  for (const option of command.options) {
+    options.set(option.name, { option, canonicalName: option.name });
+    for (const alias of option.deprecatedAliases || []) {
+      options.set(alias, { option, canonicalName: option.name });
+    }
+  }
   const seen = new Set();
   const normalized = [];
   let positionals = 0;
@@ -81,14 +85,17 @@ function normalizeCommandArgs(command, args) {
 
     const separator = token.indexOf("=");
     const name = separator > -1 ? token.slice(0, separator) : token;
-    const option = options.get(name);
-    if (!option) throw new Error(`unknown option '${name}'`);
-    if (seen.has(name)) throw new Error(`option '${name}' was provided twice`);
-    seen.add(name);
+    const match = options.get(name);
+    if (!match) throw new Error(`unknown option '${name}'`);
+    const { option, canonicalName } = match;
+    if (seen.has(canonicalName)) {
+      throw new Error(`option '${canonicalName}' was provided twice`);
+    }
+    seen.add(canonicalName);
 
     if (option.kind === "flag") {
       if (separator > -1) throw new Error(`option '${name}' takes no value`);
-      normalized.push(name);
+      normalized.push(canonicalName);
       continue;
     }
 
@@ -97,7 +104,7 @@ function normalizeCommandArgs(command, args) {
     if (!optionValue || optionValue.startsWith("--")) {
       throw new Error(`option '${name}' requires a value`);
     }
-    normalized.push(name, optionValue);
+    normalized.push(canonicalName, optionValue);
   }
   return normalized;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldspace_npm/harness",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Build and verify portable Foldspace action artifacts against a live app.",
   "type": "module",
   "bin": {

package/src/cli-help.mjs

@@ -74,6 +74,10 @@ export function renderCommandHelp(registry, name) {
       `${option.name}${option.value ? ` <${option.value}>` : ""}`,
       `${option.description}${
         option.default ? ` (default: ${option.default})` : ""
+      }${
+        option.deprecatedAliases?.length
+          ? ` (deprecated alias: ${option.deprecatedAliases.join(", ")})`
+          : ""
       }`,
     ]);
     sections.push("", "Options:", rows(optionRows));

package/src/cli-registry.mjs

@@ -21,7 +21,7 @@ export const CLI_COMMANDS = Object.freeze([
     group: "start",
     summary: "Create a configured Foldspace actions project",
     usage:
-      "foldspace init [<directory>] [--product-id <id>] [--agent-api-name <name>] [--domain <host>] [--name <display-name>]",
+      "foldspace init [<directory>] [--product-id <id>] [--agent-key <key>] [--domain <host>] [--name <display-name>]",
     risk: "local-write",
     environment: "node",
     environmentVariables: [],
@@ -37,8 +37,9 @@ export const CLI_COMMANDS = Object.freeze([
       value("--product-id", "id", "Bare Foldspace product ID", {
         required: "non-interactive",
       }),
-      value("--agent-api-name", "name", "Agent API name", {
+      value("--agent-key", "key", "Agent Key shown in Agent Studio", {
         required: "non-interactive",
+        deprecatedAliases: ["--agent-api-name"],
       }),
       value("--domain", "host", "Target hostname or HTTP(S) URL", {
         required: "non-interactive",
@@ -50,7 +51,7 @@ export const CLI_COMMANDS = Object.freeze([
     prerequisites: [
       "Node 20 or newer",
       "A target directory that does not already exist",
-      "Non-interactive use requires directory, product ID, agent name, and domain",
+      "Non-interactive use requires directory, product ID, Agent Key, and domain",
     ],
     effects: ["Creates a new local project; never initializes Git"],
     next: [

package/src/init.mjs

@@ -8,7 +8,13 @@ import { commandByName } from "./cli-registry.mjs";
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const defaultTemplateRoot = path.join(packageRoot, "templates", "agent-starter");
-const allowedFlags = new Set(["name", "product-id", "agent-api-name", "domain"]);
+const allowedFlags = new Set([
+  "name",
+  "product-id",
+  "agent-key",
+  "agent-api-name",
+  "domain",
+]);
 const tokenPattern = /\{\{([A-Z0-9_]+)\}\}/g;
 const defaultDirectory = "my-agent";
 
@@ -75,12 +81,17 @@ export function parseInitArgs(argv) {
   if (positional.length > 1) {
     throw new Error(`Usage: ${initUsage}`);
   }
+  if (flags["agent-key"] && flags["agent-api-name"]) {
+    throw new Error(
+      "Use --agent-key only; --agent-api-name is its deprecated alias.",
+    );
+  }
 
   return {
     directory: positional[0] || null,
     displayName: flags.name || null,
     productId: flags["product-id"] || null,
-    agentApiName: flags["agent-api-name"] || null,
+    agentApiName: flags["agent-key"] || flags["agent-api-name"] || null,
     domain: flags.domain || null,
   };
 }
@@ -89,7 +100,7 @@ function missingInitFields(parsed) {
   const missing = [];
   if (!parsed.directory) missing.push("directory");
   if (!parsed.productId) missing.push("product-id");
-  if (!parsed.agentApiName) missing.push("agent-api-name");
+  if (!parsed.agentApiName) missing.push("agent-key");
   if (!parsed.domain) missing.push("domain");
   return missing;
 }
@@ -208,8 +219,8 @@ async function promptForMissingFields(parsed, options = {}) {
 
   if (!next.agentApiName) {
     next.agentApiName = await askUntilValid(
-      "Agent API name",
-      (value) => validateIdentifier(value, "Agent API name"),
+      "Agent Key",
+      (value) => validateIdentifier(value, "Agent Key"),
       options,
     );
   }
@@ -243,7 +254,7 @@ function finalizeInitConfig(parsed) {
 
   for (const [key, label] of [
     ["productId", "product-id"],
-    ["agentApiName", "agent-api-name"],
+    ["agentApiName", "agent-key"],
     ["domain", "domain"],
   ]) {
     if (!parsed[key]) {
@@ -282,7 +293,7 @@ function createTemplateValues(config, harnessVersion) {
   }
 
   const productId = validateProductId(config.productId);
-  const agentApiName = validateIdentifier(config.agentApiName, "Agent API name");
+  const agentApiName = validateIdentifier(config.agentApiName, "Agent Key");
   const target = normalizeTarget(config.domain);
   const hosts =
     target.domain === "localhost" || /^\d+(?:\.\d+){3}$/.test(target.domain)