@foldspace_npm/harness 0.1.1 → 0.1.2

package/README.md

@@ -26,8 +26,8 @@ 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.
-- `foldspace-build` — esbuild → `dist/index.js`
-- `foldspace-deploy` — publish to `agent/actions/<env>/<productId>/<agentApiName>`
+- `foldspace build` — esbuild → `dist/index.js`
+- `foldspace deploy` — publish to `agent/actions/<env>/<productId>/<agentApiName>`
 - fixtures and tests
 - **the verb interface** below
 
@@ -60,10 +60,16 @@ dead weight, against a contract that cannot drift.
 ### Create a project
 
 Create a configured actions project from the template bundled with the installed
-harness version:
+harness version. Missing values are prompted when stdin is a terminal:
 
 ```bash
-npm exec --package=@foldspace_npm/harness -- foldspace init my-agent \
+npx --yes @foldspace_npm/harness init
+```
+
+Non-interactive / CI form:
+
+```bash
+npx --yes @foldspace_npm/harness init my-agent \
   --product-id FR8JUQZAQRZB \
   --agent-api-name my-agent \
   --domain app.example.com \
@@ -79,24 +85,17 @@ node bin/cli.mjs init ../my-agent \
   --domain app.example.com
 ```
 
-Until `@foldspace_npm/harness` is published, install the local checkout in the
-generated project instead of running the standard install step:
-
-```bash
-cd ../my-agent
-npm install --ignore-scripts --save-dev /absolute/path/to/harness
-```
-
 `--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
 HTTP(S) URL without a port or path.
 
 For safety, `init` requires a target path that does not exist. It does not
-install dependencies, initialize Git, or overwrite files. After creation:
+initialize Git or overwrite files. On a TTY it can offer
+`npm install --ignore-scripts` after scaffolding. After creation:
 
 ```bash
 cd my-agent
-npm install --ignore-scripts
+npm install --ignore-scripts   # if you skipped the install prompt
 npm run build
 npm run inject
 npm run attach
@@ -113,21 +112,21 @@ npm i -D @foldspace_npm/harness
 
 ```json
 { "scripts": {
-    "dev":    "foldspace-build --watch",
-    "build":  "foldspace-build",
-    "inject": "foldspace-inject",
-    "attach": "foldspace-attach",
-    "deploy": "foldspace-deploy"
+    "dev":    "foldspace build --watch",
+    "build":  "foldspace build",
+    "inject": "foldspace inject",
+    "attach": "foldspace attach",
+    "deploy": "foldspace deploy"
 } }
 ```
 
 | Command | A | B |
 |---|:--:|:--:|
 | `foldspace init` | ✅ | ✅ |
-| `foldspace-build` | ✅ | ✅ |
-| `foldspace-deploy` | ✅ | ✅ — it *is* the delivery mechanism |
-| `foldspace-inject` | ✅ | — no browser to launch |
-| `foldspace-attach` | ✅ | replaced by the extension bridge |
+| `foldspace build` | ✅ | ✅ |
+| `foldspace deploy` | ✅ | ✅ — it *is* the delivery mechanism |
+| `foldspace inject` | ✅ | — no browser to launch |
+| `foldspace attach` | ✅ | replaced by the extension bridge |
 
 Every command resolves the **consuming** repo — `process.cwd()`, or
 `FOLDSPACE_PROJECT_DIR` so a hosted builder can point it at a workspace it

package/bin/cli.mjs

@@ -1,12 +1,42 @@
 #!/usr/bin/env node
 
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { initUsage, runInit } from "../src/init.mjs";
 
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+const commands = {
+  init: "Create a configured Foldspace actions project",
+  build: "Bundle agent actions to dist/index.js",
+  inject: "Launch the dedicated Chrome profile",
+  attach: "Load the SDK and local actions over CDP",
+  deploy: "Publish the built bundle",
+  "package-extension": "Package the browser extension",
+};
+
+const scriptByCommand = {
+  build: "build-cli.mjs",
+  inject: "inject.mjs",
+  attach: "attach.mjs",
+  deploy: "deploy.mjs",
+  "package-extension": "packageExtension.mjs",
+};
+
 const usage = `Usage:
+  foldspace <command> [args]
   ${initUsage}
+  foldspace build [--watch]
+  foldspace inject [options]
+  foldspace attach [options]
+  foldspace deploy [options]
+  foldspace package-extension
 
 Commands:
-  init  Create a configured Foldspace actions project
+${Object.entries(commands)
+  .map(([name, description]) => `  ${name.padEnd(18)} ${description}`)
+  .join("\n")}
 `;
 
 function fail(message) {
@@ -14,6 +44,20 @@ function fail(message) {
   process.exitCode = 1;
 }
 
+function runScript(scriptName, args) {
+  const child = spawn(process.execPath, [path.join(here, scriptName), ...args], {
+    stdio: "inherit",
+    env: process.env,
+  });
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 0);
+  });
+}
+
 const [command, ...args] = process.argv.slice(2);
 
 if (!command || command === "--help" || command === "-h") {
@@ -22,11 +66,17 @@ if (!command || command === "--help" || command === "-h") {
   if (args.includes("--help") || args.includes("-h")) {
     console.log(`Usage: ${initUsage}`);
   } else {
-    try {
-      runInit(args);
-    } catch (error) {
-      fail(error instanceof Error ? error.message : String(error));
-    }
+    Promise.resolve()
+      .then(() => runInit(args))
+      .catch((error) => {
+        fail(error instanceof Error ? error.message : String(error));
+      });
+  }
+} else if (scriptByCommand[command]) {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(`Usage: foldspace ${command} [options]`);
+  } else {
+    runScript(scriptByCommand[command], args);
   }
 } else {
   fail(`unknown command '${command}'\n\n${usage}`);

package/package.json

@@ -1,15 +1,11 @@
 {
   "name": "@foldspace_npm/harness",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Build, inject and verify Foldspace agent experiences against a live app.",
   "type": "module",
   "bin": {
     "foldspace": "bin/cli.mjs",
-    "foldspace-build": "bin/build-cli.mjs",
-    "foldspace-inject": "bin/inject.mjs",
-    "foldspace-attach": "bin/attach.mjs",
-    "foldspace-deploy": "bin/deploy.mjs",
-    "foldspace-package-extension": "bin/packageExtension.mjs"
+    "harness": "bin/cli.mjs"
   },
   "files": [
     "bin",

package/src/init.mjs

@@ -1,14 +1,18 @@
+import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
 import { fileURLToPath } from "node:url";
 
 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 tokenPattern = /\{\{([A-Z0-9_]+)\}\}/g;
+const defaultDirectory = "my-agent";
 
 export const initUsage =
-  "foldspace init <directory> --product-id <id> --agent-api-name <name> --domain <host> [--name <display-name>]";
+  "foldspace init [<directory>] [--product-id <id>] [--agent-api-name <name>] [--domain <host>] [--name <display-name>]";
 
 function assertSupportedNode() {
   const major = Number.parseInt(process.versions.node.split(".", 1)[0], 10);
@@ -17,6 +21,13 @@ function assertSupportedNode() {
   }
 }
 
+function isInteractive(options = {}) {
+  if (typeof options.interactive === "boolean") {
+    return options.interactive;
+  }
+  return Boolean(options.stdin?.isTTY ?? input.isTTY);
+}
+
 function readFlag(argv, index) {
   const argument = argv[index];
   const equalsIndex = argument.indexOf("=");
@@ -61,25 +72,28 @@ export function parseInitArgs(argv) {
     index += 1;
   }
 
-  if (positional.length !== 1) {
+  if (positional.length > 1) {
     throw new Error(`Usage: ${initUsage}`);
   }
 
-  for (const required of ["product-id", "agent-api-name", "domain"]) {
-    if (!flags[required]) {
-      throw new Error(`Missing required option: --${required}\nUsage: ${initUsage}`);
-    }
-  }
-
   return {
-    targetDir: path.resolve(positional[0]),
-    displayName: flags.name || path.basename(path.resolve(positional[0])),
-    productId: flags["product-id"],
-    agentApiName: flags["agent-api-name"],
-    domain: flags.domain,
+    directory: positional[0] || null,
+    displayName: flags.name || null,
+    productId: flags["product-id"] || null,
+    agentApiName: flags["agent-api-name"] || null,
+    domain: flags.domain || null,
   };
 }
 
+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.domain) missing.push("domain");
+  return missing;
+}
+
 function toPackageName(value) {
   return value
     .trim()
@@ -142,6 +156,111 @@ function normalizeTarget(value) {
   };
 }
 
+async function ask(question, options = {}) {
+  if (typeof options.ask === "function") {
+    return options.ask(question);
+  }
+
+  const rl = readline.createInterface({
+    input: options.stdin || input,
+    output: options.stdout || output,
+  });
+  try {
+    return (await rl.question(question)).trim();
+  } finally {
+    rl.close();
+  }
+}
+
+async function askRequired(label, options = {}) {
+  while (true) {
+    const value = await ask(`${label}: `, options);
+    if (value) {
+      return value;
+    }
+    (options.log || console.log)(`${label} is required.`);
+  }
+}
+
+async function askUntilValid(label, validate, options = {}) {
+  while (true) {
+    const value = await askRequired(label, options);
+    try {
+      return validate(value);
+    } catch (error) {
+      (options.log || console.log)(error instanceof Error ? error.message : String(error));
+    }
+  }
+}
+
+async function promptForMissingFields(parsed, options = {}) {
+  const next = { ...parsed };
+  const log = options.log || console.log;
+
+  if (!next.directory) {
+    const value = await ask(`Project directory [${defaultDirectory}]: `, options);
+    next.directory = value || defaultDirectory;
+  }
+
+  if (!next.productId) {
+    next.productId = await askUntilValid("Product ID", validateProductId, options);
+  }
+
+  if (!next.agentApiName) {
+    next.agentApiName = await askUntilValid(
+      "Agent API name",
+      (value) => validateIdentifier(value, "Agent API name"),
+      options,
+    );
+  }
+
+  if (!next.domain) {
+    next.domain = await askUntilValid(
+      "Domain",
+      (value) => {
+        normalizeTarget(value);
+        return value.trim();
+      },
+      options,
+    );
+  }
+
+  if (!next.displayName) {
+    const defaultName = path.basename(path.resolve(next.directory));
+    const value = await ask(`Display name [${defaultName}]: `, options);
+    next.displayName = value || defaultName;
+  }
+
+  log("");
+  return next;
+}
+
+function finalizeInitConfig(parsed) {
+  const directory = parsed.directory;
+  if (!directory) {
+    throw new Error(`Missing required option: directory\nUsage: ${initUsage}`);
+  }
+
+  for (const [key, label] of [
+    ["productId", "product-id"],
+    ["agentApiName", "agent-api-name"],
+    ["domain", "domain"],
+  ]) {
+    if (!parsed[key]) {
+      throw new Error(`Missing required option: --${label}\nUsage: ${initUsage}`);
+    }
+  }
+
+  const targetDir = path.resolve(directory);
+  return {
+    targetDir,
+    displayName: parsed.displayName || path.basename(targetDir),
+    productId: parsed.productId,
+    agentApiName: parsed.agentApiName,
+    domain: parsed.domain,
+  };
+}
+
 function readHarnessVersion(root) {
   const manifestPath = path.join(root, "package.json");
   const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
@@ -281,21 +400,76 @@ export function scaffoldProject(config, options = {}) {
   };
 }
 
-export function runInit(argv, options = {}) {
+function runInstall(targetDir, options = {}) {
+  const install = options.install || ((cwd) => {
+    execFileSync("npm", ["install", "--ignore-scripts"], {
+      cwd,
+      stdio: "inherit",
+      env: process.env,
+    });
+  });
+  install(targetDir);
+}
+
+function isAffirmative(value) {
+  const normalized = value.trim().toLowerCase();
+  return normalized === "" || normalized === "y" || normalized === "yes";
+}
+
+async function maybeInstallDependencies(targetDir, options = {}) {
+  if (!isInteractive(options)) {
+    return false;
+  }
+
+  if (options.autoInstall === true) {
+    runInstall(targetDir, options);
+    return true;
+  }
+
+  if (options.autoInstall === false) {
+    return false;
+  }
+
+  const answer = await ask("Run npm install --ignore-scripts now? [Y/n] ", options);
+  if (!isAffirmative(answer)) {
+    return false;
+  }
+
+  runInstall(targetDir, options);
+  return true;
+}
+
+export async function runInit(argv, options = {}) {
   assertSupportedNode();
-  const config = parseInitArgs(argv);
+  let parsed = parseInitArgs(argv);
+  const missing = missingInitFields(parsed);
+
+  if (missing.length > 0) {
+    if (!isInteractive(options)) {
+      const label = missing[0] === "directory" ? "directory" : `--${missing[0]}`;
+      throw new Error(`Missing required option: ${label}\nUsage: ${initUsage}`);
+    }
+    parsed = await promptForMissingFields(parsed, options);
+  } else if (!parsed.displayName) {
+    parsed.displayName = path.basename(path.resolve(parsed.directory));
+  }
+
+  const config = finalizeInitConfig(parsed);
   const result = scaffoldProject(config, options);
   const log = options.log || console.log;
+  const installed = await maybeInstallDependencies(result.targetDir, options);
 
   log(`Created Foldspace project at ${result.targetDir}`);
   log(`Using @foldspace_npm/harness ${result.harnessVersion}`);
   log("");
   log("Next steps:");
   log(`  cd ${result.targetDir}`);
-  log("  npm install --ignore-scripts");
+  if (!installed) {
+    log("  npm install --ignore-scripts");
+  }
   log("  npm run build");
   log("  npm run inject");
   log("  npm run attach");
 
-  return result;
+  return { ...result, installed };
 }

package/templates/agent-starter/package.json

@@ -5,10 +5,10 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "foldspace-build --watch",
-    "build": "foldspace-build",
-    "inject": "foldspace-inject",
-    "attach": "foldspace-attach"
+    "dev": "foldspace build --watch",
+    "build": "foldspace build",
+    "inject": "foldspace inject",
+    "attach": "foldspace attach"
   },
   "devDependencies": {
     "@foldspace_npm/harness": "{{HARNESS_VERSION}}",