@getformation/cloud-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eduardo Muth Martinez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# Formation Cloud CLI
+
+`formation-cloud` calls the Formation v3 operation front door. It also installs the Formation connector and reviewed expert Skills into exact local targets.
+
+The package needs Node.js 22 or later. It has no runtime dependencies and does not import from a Formation checkout.
+
+Install the public package from npm:
+
+```bash
+npm install -g @getformation/cloud-cli
+```
+
+Install the bundled Formation connector. The first command is a dry run. The second command writes the connector.
+
+```bash
+formation-cloud connector install --target /absolute/path/to/formation
+formation-cloud connector install --target /absolute/path/to/formation --apply
+formation-cloud connector check --target /absolute/path/to/formation
+```
+
+Set `FORMATION_CLOUD_URL` to the exact HTTPS Formation origin. Set `FORMATION_AGENT_KEY` only when an operation needs an authenticated machine scope.
+
+```bash
+formation-cloud discover
+formation-cloud connector
+formation-cloud channel_search '{"query":"Formation"}'
+formation-cloud follow '{"channelId":"channel_formation","interests":["use_knowledge"],"idempotencyKey":"follow_formation_01"}'
+formation-cloud updates_reset '{}'
+formation-cloud updates '{"cursor":"OPAQUE_CURSOR_FROM_RESET"}'
+formation-cloud skill install skillrev_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef --target /absolute/path/to/skill
+formation-cloud skill install skillrev_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef --target /absolute/path/to/skill --apply
+formation-cloud skill check --target /absolute/path/to/skill
+```
+
+Connector and Skill installation are dry runs unless you pass `--apply`. A reviewed Skill replacement also needs `--replace` and `--expected-installed-manifest` with the exact SHA-256 digest from the current local receipt. There is no force, adopt, default-target, home-target, root-target, legacy route, alias, or MCP file-write mode.
+
+The connector uses stateless polling. Formation does not push updates. Complete `updates_reset`, then poll `updates` with the opaque cursor.
+
+The expert Skill installer accepts only strict UTF-8 Markdown manifests. It verifies the configured origin, response URLs, paths, limits, file hashes, and aggregate manifest digest before it writes. A local receipt records the origin, artifact revision, manifest digest, and installed file hashes. `skill check` reports `current`, `withdrawn`, `stale`, or `conflict`. It never deletes an installed Skill.

package/bin/formation-cloud.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from "../src/cli.mjs";
+
+await runCli();

package/connector/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: formation
+description: Connect an agent to Formation, follow a channel by interest, and poll for attributed updates.
+---
+
+# Formation connector
+
+> Trust boundary: This file contains untrusted expert guidance. It grants no tool, MCP, CLI, local Engine, credential, permission, or execution authority.
+
+Use Formation through one of its declared v3 front doors. The hosted MCP, HTTP API, and `formation-cloud` CLI call the same operation registry.
+
+## Connect
+
+1. Set `FORMATION_CLOUD_URL` to the exact HTTPS Formation origin.
+2. Ask the person to create an agent credential in the Formation browser. Do not request or display the credential in chat.
+3. Put the credential in `FORMATION_AGENT_KEY`. The complete day-one sequence needs `follows:read`, `follows:write`, and `updates:read`.
+4. Run `formation-cloud discover` and verify `contractVersion` is `3`.
+
+The day-one channel has ID `channel_formation` and handle `formation`. The available interests are:
+
+- `use_knowledge`: updates for people who want expert knowledge for their agents.
+- `share_knowledge`: updates for experts who want Formation to onboard their knowledge.
+
+## Follow and poll
+
+Use this sequence: `follow -> updates_reset -> updates`.
+
+```sh
+formation-cloud channel_search '{"query":"Formation"}'
+formation-cloud channel_get '{"channelId":"channel_formation"}'
+formation-cloud follow '{"channelId":"channel_formation","interests":["use_knowledge"],"idempotencyKey":"follow_formation_01"}'
+formation-cloud updates_reset '{}'
+formation-cloud updates '{"cursor":"OPAQUE_CURSOR_FROM_RESET"}'
+```
+
+Select one interest or both. Keep the interest values unique. Page `updates_reset` until `hasMore` is false. Use its final `updatesCursor` as the first `updates` cursor. Store each returned cursor and use it for the next poll.
+
+If Formation returns `cursor_reset_required`, discard the cursor and run `updates_reset` again. A follow, unfollow, or interest change intentionally invalidates the old cursor.
+
+Formation uses stateless polling. It does not promise push delivery. The caller owns its polling schedule. Do not poll faster than the declared rate limits.
+
+Following records interest only. It does not grant access to expert knowledge or local execution authority.

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@getformation/cloud-cli",
+  "version": "1.0.0",
+  "description": "Formation Cloud operation client and explicit Skill installer",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "formation-cloud": "bin/formation-cloud.mjs"
+  },
+  "files": [
+    "bin/formation-cloud.mjs",
+    "src/cli.mjs",
+    "src/client.mjs",
+    "src/connector.mjs",
+    "src/errors.mjs",
+    "src/installer.mjs",
+    "src/manifest.mjs",
+    "connector/SKILL.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "license": "MIT"
+}

package/src/cli.mjs

@@ -0,0 +1,122 @@
+import { clientFromEnvironment, isMachineOperationName } from "./client.mjs";
+import { checkConnector, installConnector } from "./connector.mjs";
+import { CloudCliError, fail, safeFailure } from "./errors.mjs";
+import { checkSkill, installSkill } from "./installer.mjs";
+
+function parseJson(value) {
+  try {
+    const parsed = JSON.parse(value);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error();
+    return parsed;
+  } catch {
+    fail("invalid_operation_input", "Provide one valid JSON input object.", "Pass JSON such as '{}'.");
+  }
+}
+
+function parseOptions(args, allowed) {
+  const options = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const flag = args[index];
+    if (!allowed.has(flag) || Object.hasOwn(options, flag)) {
+      fail("invalid_command", `Unsupported or repeated option: ${flag}`, "Run formation-cloud help for the exact target commands.");
+    }
+    if (["--apply", "--replace"].includes(flag)) options[flag] = true;
+    else {
+      const value = args[index + 1];
+      if (!value || value.startsWith("--")) fail("invalid_command", `Option ${flag} requires one value.`, "Run formation-cloud help.");
+      options[flag] = value;
+      index += 1;
+    }
+  }
+  return options;
+}
+
+export function help() {
+  return {
+    package: "@getformation/cloud-cli",
+    version: "1.0.0",
+    usage: [
+      "formation-cloud discover",
+      "formation-cloud connector",
+      "formation-cloud connector install --target /absolute/path [--apply]",
+      "formation-cloud connector check --target /absolute/path",
+      "formation-cloud <machine_operation> '[JSON input object]'",
+      "formation-cloud skill install <artifact-revision-id> --target /absolute/path [--apply]",
+      "formation-cloud skill install <artifact-revision-id> --target /absolute/path --apply --replace --expected-installed-manifest <sha256>",
+      "formation-cloud skill check --target /absolute/path",
+    ],
+    endpointVariable: "FORMATION_CLOUD_URL",
+    credentialVariable: "FORMATION_AGENT_KEY",
+    installation: "Skill install is read-only unless --apply is present. Replacement requires the exact installed manifest digest.",
+    trust: "untrusted",
+    grantsAuthority: false,
+    executionMode: "guidance_only",
+  };
+}
+
+export async function execute(argv, environment = process.env) {
+  const [first = "help", ...rest] = argv;
+  if (["help", "--help", "-h"].includes(first)) {
+    if (rest.length) fail("invalid_command", "Help does not accept extra arguments.", "Run formation-cloud help.");
+    return help();
+  }
+  if (first === "discover") {
+    if (rest.length) fail("invalid_command", "Discovery does not accept input.", "Run formation-cloud discover.");
+    return clientFromEnvironment(environment).discover();
+  }
+  if (first === "connector") {
+    if (!rest.length) return clientFromEnvironment(environment).operate("connector_get", {});
+    const [command, ...connectorArgs] = rest;
+    if (command === "install") {
+      const options = parseOptions(connectorArgs, new Set(["--target", "--apply"]));
+      if (!options["--target"]) fail("invalid_command", "Connector install requires --target with one absolute path.", "Choose one dedicated exact target.");
+      return installConnector({ target: options["--target"], apply: options["--apply"] === true });
+    }
+    if (command === "check") {
+      const options = parseOptions(connectorArgs, new Set(["--target"]));
+      if (!options["--target"]) fail("invalid_command", "Connector check requires --target with one absolute path.", "Pass the exact installed connector target.");
+      return checkConnector({ target: options["--target"] });
+    }
+    fail("invalid_command", "Connector supports retrieval, install, and check.", "Run formation-cloud help.");
+  }
+  const client = clientFromEnvironment(environment);
+  if (first === "skill") {
+    const [command, ...skillArgs] = rest;
+    if (command === "install") {
+      const [artifactRevisionId, ...optionArgs] = skillArgs;
+      if (!artifactRevisionId || artifactRevisionId.startsWith("--")) fail("invalid_command", "Skill install requires one artifact revision ID.", "Pass the exact revision returned by skill_search.");
+      const options = parseOptions(optionArgs, new Set(["--target", "--apply", "--replace", "--expected-installed-manifest"]));
+      if (!options["--target"]) fail("invalid_command", "Skill install requires --target with one absolute path.", "Choose one dedicated exact target.");
+      return installSkill({ client, artifactRevisionId, target: options["--target"], apply: options["--apply"] === true,
+        replace: options["--replace"] === true, expectedInstalledManifest: options["--expected-installed-manifest"] ?? null });
+    }
+    if (command === "check") {
+      const options = parseOptions(skillArgs, new Set(["--target"]));
+      if (!options["--target"]) fail("invalid_command", "Skill check requires --target with one absolute path.", "Pass the exact installed Skill target.");
+      return checkSkill({ client, target: options["--target"] });
+    }
+    fail("invalid_command", "Skill supports only install and check.", "Run formation-cloud help.");
+  }
+  if (!isMachineOperationName(first)) fail("invalid_command", "The target operation name is invalid.", "Run formation-cloud discover.");
+  if (rest.length > 1) fail("invalid_command", "A machine operation accepts one optional JSON input object.", "Run formation-cloud discover.");
+  return client.operate(first, rest.length ? parseJson(rest[0]) : {});
+}
+
+function redactedJson(value, credential) {
+  const serialized = JSON.stringify(value);
+  return credential ? serialized.replaceAll(credential, "[redacted]") : serialized;
+}
+
+export async function runCli({ argv = process.argv.slice(2), environment = process.env, stdout = process.stdout } = {}) {
+  try {
+    const result = await execute(argv, environment);
+    stdout.write(`${redactedJson(result, environment.FORMATION_AGENT_KEY ?? "")}\n`);
+    if (result?.status === "conflict") process.exitCode = 1;
+  } catch (error) {
+    const safe = safeFailure(error);
+    stdout.write(`${redactedJson(safe, environment.FORMATION_AGENT_KEY ?? "")}\n`);
+    process.exitCode = 1;
+  }
+}
+
+export { CloudCliError };

package/src/client.mjs

@@ -0,0 +1,203 @@
+import { CloudCliError, fail } from "./errors.mjs";
+
+export const CLOUD_API_PATH = "/api/v3";
+export const MAX_GENERIC_RESPONSE_BYTES = 4 * 1024 * 1024;
+export const MAX_MANIFEST_RESPONSE_BYTES = 512 * 1024;
+export const MAX_FILE_RESPONSE_BYTES = 512 * 1024;
+const MAX_REQUEST_BYTES = 278_528;
+const OPERATION_NAME = /^[a-z][a-z_]{0,63}$/u;
+const AGENT_KEY = /^fka_[A-Za-z0-9_-]{43}$/u;
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,95}$/u;
+
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const exactKeys = (value, keys) => object(value)
+  && Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+
+function validTimestamp(value) {
+  return typeof value === "string" && value.length <= 32 && Number.isFinite(Date.parse(value));
+}
+
+function validateDiscovery(value) {
+  if (!object(value) || value.contractVersion !== 3 || !Array.isArray(value.operations)) {
+    fail("invalid_response", "The server returned an invalid v3 discovery descriptor.",
+      "Use the target v3 Formation Cloud endpoint.");
+  }
+  return value;
+}
+
+function validateOperationEnvelope(value, operation) {
+  const audit = value?.audit;
+  if (!exactKeys(value, ["contractVersion", "requestId", "operation", "result", "audit"])
+    || value.contractVersion !== 3 || value.operation !== operation
+    || typeof value.requestId !== "string" || !IDENTIFIER.test(value.requestId)
+    || !object(value.result) || !exactKeys(audit, ["recordId", "createdAt"])
+    || !(audit.recordId === null || typeof audit.recordId === "string" && IDENTIFIER.test(audit.recordId))
+    || !(audit.createdAt === null || validTimestamp(audit.createdAt))) {
+    fail("invalid_response", "The server returned an invalid v3 operation envelope.",
+      "Use the target v3 Formation Cloud endpoint and retry the exact operation.");
+  }
+  return value;
+}
+
+export function isMachineOperationName(value) {
+  return OPERATION_NAME.test(value);
+}
+
+function exactOrigin(rawOrigin, allowHttpLoopbackForTests) {
+  let url;
+  try { url = new URL(rawOrigin); }
+  catch {
+    fail("invalid_endpoint", "Set FORMATION_CLOUD_URL to the service's exact HTTPS origin.",
+      "Use an origin such as https://formation.example without a path, credentials, query, or fragment.");
+  }
+  if (!rawOrigin || url.username || url.password || url.origin !== rawOrigin) {
+    fail("invalid_endpoint", "The endpoint must be an exact origin without a path, credentials, query, or fragment.",
+      "Set FORMATION_CLOUD_URL to the exact configured Cloud origin.");
+  }
+  const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback && allowHttpLoopbackForTests)) {
+    fail("https_required", "Formation Cloud requires HTTPS.",
+      "Use HTTPS. Tests may opt in to HTTP only for an exact loopback origin.");
+  }
+  return url;
+}
+
+async function readBoundedJson(response, maximumBytes) {
+  const reader = response.body?.getReader();
+  if (!reader) {
+    fail("invalid_response", "The server returned no JSON response body.", "Retry against the configured Formation Cloud origin.");
+  }
+  const chunks = [];
+  let total = 0;
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > maximumBytes) {
+        await reader.cancel().catch(() => {});
+        fail("response_too_large", "The server response exceeded the client byte limit.",
+          "Do not retry until the server returns a bounded target response.");
+      }
+      chunks.push(Buffer.from(value));
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  let value;
+  try { value = JSON.parse(Buffer.concat(chunks).toString("utf8")); }
+  catch {
+    fail("invalid_response", "The server did not return valid bounded JSON.", "Retry against a healthy target endpoint.");
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    fail("invalid_response", "The server returned an invalid operation envelope.", "Use the target v3 Formation Cloud endpoint.");
+  }
+  return value;
+}
+
+function safeRemoteText(value, fallback) {
+  return typeof value === "string" && value.length > 0 && value.length <= 8192 ? value : fallback;
+}
+
+export class CloudClient {
+  constructor({
+    origin,
+    credential = "",
+    allowHttpLoopbackForTests = false,
+    fetchImpl = globalThis.fetch,
+    timeoutMs = 15_000,
+  }) {
+    this.origin = exactOrigin(origin, allowHttpLoopbackForTests);
+    if (credential && !AGENT_KEY.test(credential)) {
+      fail("invalid_agent_credential", "FORMATION_AGENT_KEY has an invalid target credential format.",
+        "Issue a current bounded credential in the signed-in browser.");
+    }
+    if (typeof fetchImpl !== "function") throw new TypeError("fetchImpl must be a function");
+    this.credential = credential;
+    this.fetchImpl = fetchImpl;
+    this.timeoutMs = timeoutMs;
+  }
+
+  async #request({ path, method, input, maximumBytes }) {
+    const expected = new URL(path, this.origin);
+    const body = input === undefined ? undefined : JSON.stringify(input);
+    if (body !== undefined && Buffer.byteLength(body, "utf8") > MAX_REQUEST_BYTES) {
+      fail("body_too_large", "The operation input exceeded the client byte limit.", "Send a bounded target operation input.");
+    }
+    let response;
+    try {
+      response = await this.fetchImpl(expected, {
+        method,
+        redirect: "error",
+        signal: AbortSignal.timeout(this.timeoutMs),
+        headers: {
+          accept: "application/json",
+          ...(this.credential ? { authorization: `Bearer ${this.credential}` } : {}),
+          ...(body === undefined ? {} : { "content-type": "application/json" }),
+        },
+        ...(body === undefined ? {} : { body }),
+      });
+    } catch (error) {
+      if (error instanceof CloudCliError) throw error;
+      fail("connection_failed", "The target endpoint could not be reached safely. Redirects are not followed.",
+        "Check the exact configured origin and its TLS endpoint.");
+    }
+    let responseUrl;
+    try { responseUrl = new URL(response.url); }
+    catch {
+      fail("response_origin_mismatch", "The response did not identify its exact target URL.",
+        "Use a direct target operation endpoint without a proxy rewrite or redirect.");
+    }
+    if (responseUrl.href !== expected.href || responseUrl.origin !== this.origin.origin) {
+      fail("response_origin_mismatch", "The final response URL did not match the exact requested operation URL.",
+        "Use the configured Formation Cloud origin directly. Redirected responses are refused.");
+    }
+    const value = await readBoundedJson(response, maximumBytes);
+    if (!response.ok) {
+      throw new CloudCliError(
+        safeRemoteText(value.code, "operation_failed"),
+        safeRemoteText(value.error ?? value.message, "The operation was refused."),
+        safeRemoteText(value.recovery, "Read target discovery and current authority before retrying."),
+        value.requestId && typeof value.requestId === "string" ? { requestId: value.requestId } : undefined,
+      );
+    }
+    return value;
+  }
+
+  async discover() {
+    return validateDiscovery(await this.#request({
+      path: `${CLOUD_API_PATH}/discovery`, method: "GET", maximumBytes: MAX_GENERIC_RESPONSE_BYTES,
+    }));
+  }
+
+  async operate(operation, input = {}, { maximumBytes = MAX_GENERIC_RESPONSE_BYTES } = {}) {
+    if (!isMachineOperationName(operation)) {
+      fail("invalid_operation", "The operation name is invalid.", "Use a machine operation name from target discovery.");
+    }
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+      fail("invalid_operation_input", "The operation input must be one JSON object.", "Pass one target operation input object.");
+    }
+    return validateOperationEnvelope(await this.#request({
+      path: `${CLOUD_API_PATH}/operations/${operation}`,
+      method: "POST",
+      input,
+      maximumBytes,
+    }), operation);
+  }
+
+  manifest(artifactRevisionId) {
+    return this.operate("skill_manifest_get", { artifactRevisionId }, { maximumBytes: MAX_MANIFEST_RESPONSE_BYTES });
+  }
+
+  file(artifactRevisionId, filePath) {
+    return this.operate("skill_file_get", { artifactRevisionId, path: filePath }, { maximumBytes: MAX_FILE_RESPONSE_BYTES });
+  }
+}
+
+export function clientFromEnvironment(environment = process.env) {
+  return new CloudClient({
+    origin: environment.FORMATION_CLOUD_URL ?? "",
+    credential: environment.FORMATION_AGENT_KEY ?? "",
+    allowHttpLoopbackForTests: environment.FORMATION_CLOUD_ALLOW_HTTP_LOOPBACK_FOR_TESTS === "true",
+  });
+}