@foldspace_npm/harness 0.1.2 → 0.1.4

package/src/cli-registry.mjs

@@ -0,0 +1,310 @@
+import { diagnosticCatalogue } from "./diagnostics.mjs";
+import { HARNESS_PROTOCOL_VERSION } from "./protocol.mjs";
+
+export const CLI_SCHEMA_VERSION = 1;
+
+const flag = (name, description, details = {}) =>
+  Object.freeze({ name, kind: "flag", description, ...details });
+const value = (name, valueName, description, details = {}) =>
+  Object.freeze({
+    name,
+    kind: "value",
+    value: valueName,
+    description,
+    ...details,
+  });
+
+export const CLI_COMMANDS = Object.freeze([
+  Object.freeze({
+    name: "init",
+    entry: null,
+    group: "start",
+    summary: "Create a configured Foldspace actions project",
+    usage:
+      "foldspace init [<directory>] [--product-id <id>] [--agent-key <key>] [--domain <host>] [--name <display-name>]",
+    risk: "local-write",
+    environment: "node",
+    environmentVariables: [],
+    capabilities: ["project.scaffold"],
+    positionals: [
+      {
+        name: "directory",
+        required: "non-interactive",
+        description: "New project directory",
+      },
+    ],
+    options: [
+      value("--product-id", "id", "Bare Foldspace product ID", {
+        required: "non-interactive",
+      }),
+      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",
+      }),
+      value("--name", "display-name", "Display name", {
+        default: "directory name",
+      }),
+    ],
+    prerequisites: [
+      "Node 20 or newer",
+      "A target directory that does not already exist",
+      "Non-interactive use requires directory, product ID, Agent Key, and domain",
+    ],
+    effects: ["Creates a new local project; never initializes Git"],
+    next: [
+      "Install dependencies",
+      "Run foldspace build",
+      "Run foldspace inject",
+      "Run foldspace attach",
+    ],
+  }),
+  Object.freeze({
+    name: "build",
+    entry: "build-cli.mjs",
+    group: "develop",
+    summary: "Bundle agent actions to dist/index.js",
+    usage: "foldspace build [--watch]",
+    risk: "local-write",
+    environment: "node",
+    environmentVariables: ["FOLDSPACE_PROJECT_DIR"],
+    capabilities: ["artifact.build"],
+    positionals: [],
+    options: [flag("--watch", "Rebuild when action source changes")],
+    prerequisites: ["agent/actions/index.ts"],
+    effects: ["Writes dist/index.js"],
+    next: ["Run foldspace inject", "Run foldspace attach"],
+  }),
+  Object.freeze({
+    name: "inject",
+    entry: "inject.mjs",
+    group: "verify",
+    summary: "Launch an isolated Chrome profile for local verification",
+    usage: "foldspace inject [options]",
+    risk: "browser-session",
+    environment: "local-chrome",
+    environmentVariables: ["FOLDSPACE_PROJECT_DIR", "CHROME_PATH"],
+    capabilities: ["browser.launch", "browser.cdp"],
+    positionals: [],
+    options: [
+      value("--target", "name", "Use a target from foldspace.dev.json"),
+      value("--url", "url", "Override the target start URL"),
+      value("--product", "id", "Override the local-session product ID"),
+      value("--agent", "api-name", "Override the local-session agent"),
+      value("--hosts", "a,b", "Override allowed host patterns"),
+      value(
+        "--key",
+        "sdk-key",
+        "Override the SDK key used later by attach/bootstrap",
+      ),
+      flag("--embedded", "Use EMBEDDED mode for the local session"),
+      value("--port", "number", "Chrome debugging port", {
+        default: "9222",
+      }),
+      flag(
+        "--print",
+        "Resolve and print the target without writing or launching",
+      ),
+    ],
+    prerequisites: [
+      "foldspace.dev.json",
+      "Local Chrome unless --print",
+      "Using --url without --target also requires --product and --agent",
+    ],
+    effects: [
+      "With --print, writes nothing and launches nothing",
+      "Otherwise creates an isolated profile and writes .foldspace-dev/state.json",
+      "Does not load the SDK or action artifact",
+    ],
+    next: ["Sign in to the target application", "Run foldspace attach"],
+  }),
+  Object.freeze({
+    name: "attach",
+    entry: "attach.mjs",
+    group: "verify",
+    summary:
+      "Load local actions over CDP and observe the normal agent experience",
+    usage:
+      "foldspace attach [--bootstrap | --replace] [--target <name>] [--port <number>] [--agent <api-name>] [--no-test-mode] [--no-badge]",
+    risk: "browser-session",
+    environment: "local-chrome",
+    environmentVariables: [
+      "FOLDSPACE_PROJECT_DIR",
+      "CDP_PORT",
+      "AGENT_API_NAME",
+    ],
+    capabilities: [
+      "browser.cdp",
+      "artifact.load",
+      "page.evaluate",
+      "page.mutate",
+    ],
+    positionals: [],
+    modes: [
+      {
+        name: "swap",
+        flag: null,
+        description:
+          "Default; page already has the configured product and agent",
+      },
+      {
+        name: "bootstrap",
+        flag: "--bootstrap",
+        description: "Page has no Foldspace SDK",
+      },
+      {
+        name: "replace",
+        flag: "--replace",
+        description: "Page has a different product or agent",
+      },
+    ],
+    options: [
+      flag("--bootstrap", "Prepare a page that has no Foldspace SDK"),
+      flag(
+        "--replace",
+        "Temporarily replace a different page product or agent",
+      ),
+      value("--target", "name", "Use a target from foldspace.dev.json"),
+      value(
+        "--port",
+        "number",
+        "CDP port: CLI, CDP_PORT, saved launch state, then 9222",
+      ),
+      value("--agent", "api-name", "Override the configured agent API name"),
+      flag(
+        "--no-test-mode",
+        "Do not mark conversations as test traffic; use deliberately",
+      ),
+      flag("--no-badge", "Hide the visible Foldspace development badge"),
+    ],
+    prerequisites: [
+      "foldspace.dev.json",
+      "dist/index.js",
+      "A Chrome CDP endpoint, normally created by foldspace inject",
+      "sdkUrl in foldspace.dev.json when using --bootstrap",
+    ],
+    effects: [
+      "May reload and instrument matching target pages",
+      "Test mode is enabled unless --no-test-mode is passed",
+      "Never directly invokes an action handler",
+      "Restores prepared pages when detached cleanly",
+    ],
+    next: [
+      "Exercise the visible agent normally",
+      "Confirm [lifecycle] inspect_registration:registration_ok",
+      "Confirm execute/render observations",
+      "Detach with Ctrl-C",
+    ],
+  }),
+  Object.freeze({
+    name: "deploy",
+    entry: "deploy.mjs",
+    group: "publish",
+    summary: "Publish dist/index.js to remote Foldspace action storage",
+    usage:
+      "foldspace deploy [--target <name>] [--env <dev|prod>]",
+    risk: "remote-publish",
+    environment: "local-cloud-credentials",
+    environmentVariables: ["FOLDSPACE_PROJECT_DIR"],
+    capabilities: ["artifact.publish"],
+    positionals: [],
+    options: [
+      value(
+        "--target",
+        "name",
+        "Target from foldspace.dev.json",
+        { default: "defaultTarget" },
+      ),
+      value("--env", "dev|prod", "Remote environment", { default: "dev" }),
+    ],
+    prerequisites: [
+      "foldspace.dev.json",
+      "dist/index.js",
+      "A Git commit",
+      "Authenticated gsutil/gcloud",
+    ],
+    effects: [
+      "Uploads versioned and latest JavaScript objects",
+      "Updates DEPLOYMENTS.md",
+      "Skips when the current Git SHA already exists remotely",
+      "Does not rebuild or verify that dist/index.js matches the current Git SHA",
+    ],
+    next: ["Verify the remote artifact before production use"],
+  }),
+]);
+
+export const CAPABILITY_CATALOGUE = Object.freeze([
+  ["project.scaffold", "Create a new configured project on local disk"],
+  ["artifact.build", "Build the portable dist/index.js action artifact"],
+  ["browser.launch", "Launch an isolated local Chrome profile"],
+  ["browser.cdp", "Connect to local Chrome through CDP"],
+  ["artifact.load", "Load a local action artifact into an authorized page"],
+  ["page.evaluate", "Inspect bounded SDK and registration state"],
+  ["page.mutate", "Prepare and restore a matching development page"],
+  ["artifact.publish", "Write the built artifact to remote storage"],
+]);
+
+export const RISK_CATALOGUE = Object.freeze([
+  ["local-write", "Writes only inside the consuming project"],
+  ["browser-session", "Launches or temporarily mutates a local browser session"],
+  ["remote-publish", "Writes the action artifact to remote storage"],
+]);
+
+export const ENVIRONMENT_CATALOGUE = Object.freeze([
+  ["node", "Node.js workspace; no browser required"],
+  ["local-chrome", "Local Chrome with an authorized CDP connection"],
+  [
+    "local-cloud-credentials",
+    "Local process with authenticated gsutil/gcloud",
+  ],
+]);
+
+const PUBLIC_DIAGNOSTICS = new Set([
+  "inspectSdkState",
+  "inspectRegistration",
+  "verifyWidgetVisible",
+  "inspectActionObservation",
+]);
+
+export function commandByName(name) {
+  return CLI_COMMANDS.find((command) => command.name === name) || null;
+}
+
+export function createCliRegistry({ packageName, packageVersion }) {
+  const diagnostics = diagnosticCatalogue()
+    .filter((diagnostic) => PUBLIC_DIAGNOSTICS.has(diagnostic.name))
+    .map((diagnostic) => ({
+      ...diagnostic,
+      invocation: "attach-internal",
+      cliExposed: false,
+    }));
+  return {
+    kind: "foldspace.cli.help",
+    schemaVersion: CLI_SCHEMA_VERSION,
+    package: {
+      name: packageName,
+      version: packageVersion,
+    },
+    protocolVersion: HARNESS_PROTOCOL_VERSION,
+    workflow: ["init", "build", "inject", "attach"],
+    publishWorkflow: ["deploy"],
+    capabilities: CAPABILITY_CATALOGUE.map(([id, description]) => ({
+      id,
+      description,
+    })),
+    risks: RISK_CATALOGUE.map(([id, description]) => ({ id, description })),
+    environments: ENVIRONMENT_CATALOGUE.map(([id, description]) => ({
+      id,
+      description,
+    })),
+    commands: CLI_COMMANDS.map(({ entry: _entry, ...command }) => command),
+    diagnostics,
+    notes: [
+      "Capability metadata describes current behavior; it is not hosted-environment enforcement.",
+      "Action verification is passive and agent-driven.",
+      "The harness bin alias is equivalent to foldspace.",
+    ],
+  };
+}