@macaw-ai/client 0.0.0-stage → 0.9.11

package/bin/install.js

@@ -0,0 +1,422 @@
+#!/usr/bin/env node
+// Set up MACAW for a Python project: pick an interpreter we have a wheel for,
+// install the client and the adapters into it, get a key, and leave the
+// examples somewhere the user can run them.
+//
+// Everything lands in one directory the user chooses, config included, so a
+// second install elsewhere is a second workspace rather than a collision.
+// That is also why MACAW_HOME is mentioned at the end: the client searches
+// $MACAW_HOME, then the current directory, then home - so from inside the
+// install directory it already works, and the variable is only for running
+// from somewhere else.
+
+import { spawnSync } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const PKG = path.join(HERE, "..");
+const API = process.env.MACAW_API_URL || "https://api.macawsecurity.ai";
+
+const C = process.stdout.isTTY
+  ? { dim: "\x1b[2m", b: "\x1b[1m", g: "\x1b[32m", y: "\x1b[33m", r: "\x1b[31m", c: "\x1b[36m", x: "\x1b[0m" }
+  : { dim: "", b: "", g: "", y: "", r: "", c: "", x: "" };
+
+const ok = (s) => console.log(`  ${C.g}✓${C.x} ${s}`);
+const no = (s) => console.log(`  ${C.r}✗${C.x} ${s}`);
+const info = (s) => console.log(`  ${C.c}→${C.x} ${s}`);
+
+// ---------------------------------------------------------------- wheels ---
+
+// The matrix is whatever shipped in this package, so the installer never
+// offers a Python we stopped building or misses one we added.
+function bundledWheels() {
+  const dir = path.join(PKG, "wheels");
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((f) => f.startsWith("macaw_client-") && f.endsWith(".whl"))
+    .map((f) => {
+      const m = f.match(/-(cp\d+)-\1-(.+)\.whl$/);
+      return m ? { file: path.join(dir, f), tag: m[1], platform: m[2] } : null;
+    })
+    .filter(Boolean);
+}
+
+function platformTag() {
+  if (process.platform === "darwin") return process.arch === "arm64" ? "macosx_11_0_arm64" : "macosx_10_9_x86_64";
+  if (process.platform === "linux") return "manylinux_2_17_x86_64";
+  if (process.platform === "win32") return "win_amd64";
+  return null;
+}
+
+// cp314 -> "3.14", for both display and the interpreter name we look for.
+const version = (tag) => `${tag.slice(2, 3)}.${tag.slice(3)}`;
+
+// Newest first. Not parseFloat: that reads 3.9 as larger than 3.14 and would
+// hand a machine with both the older interpreter.
+const byVersionDesc = (a, b) => {
+  const [am, an] = a.split(".").map(Number);
+  const [bm, bn] = b.split(".").map(Number);
+  return bm - am || bn - an;
+};
+
+// ---------------------------------------------------------------- python ---
+
+// An interpreter is a command plus leading arguments, because the reliable way
+// to name a version on Windows is the launcher: `py -3.14`. Everything that
+// runs Python here goes through this shape.
+const interp = (cmd, ...pre) => ({ cmd, pre, display: [cmd, ...pre].join(" ") });
+
+function pythonVersionOf(py) {
+  const r = spawnSync(py.cmd, [...py.pre, "-c", "import sys;print('%d.%d' % sys.version_info[:2])"],
+                      { encoding: "utf8" });
+  return r.status === 0 ? r.stdout.trim() : null;
+}
+
+// How to ask for a specific version, per platform. Unix names the binary;
+// Windows has no python3.14 on PATH and uses the launcher instead, with bare
+// `python` as the fallback - `python3` there is often a Store alias that is
+// absent or stubbed.
+function candidatesFor(v) {
+  const minor = v.split(".")[1];
+  return process.platform === "win32"
+    ? [interp("py", `-${v}`), interp(`python${v}`), interp("python")]
+    : [interp(`python${v}`), interp(`python3.${minor}`)];
+}
+
+const defaultInterp = () => (process.platform === "win32" ? interp("python") : interp("python3"));
+
+// Newest first, so a machine with several gets the one we would rather it use.
+//
+// MACAW_PYTHON names an interpreter outright, arguments included, so
+// MACAW_PYTHON="py -3.12" works. That is the way out of the mismatch this
+// preference can cause: on a machine where the default is 3.12 and 3.14 also
+// exists, the library lands where `python3 foo.py` cannot import it.
+function findPython(wheels) {
+  const wanted = [...new Set(wheels.map((w) => version(w.tag)))].sort(byVersionDesc);
+
+  const named = process.env.MACAW_PYTHON;
+  if (named) {
+    const py = interp(...named.trim().split(/\s+/));
+    const v = pythonVersionOf(py);
+    if (!v) return { error: `MACAW_PYTHON=${named} will not run.` };
+    if (!wanted.includes(v)) {
+      return { error: `MACAW_PYTHON=${named} is Python ${v}. We ship ${wanted.join(", ")}.` };
+    }
+    return { ...py, version: v };
+  }
+
+  for (const v of wanted) {
+    for (const py of candidatesFor(v)) {
+      if (pythonVersionOf(py) === v) return { ...py, version: v };
+    }
+  }
+  // Whatever the bare interpreter is may still be one we ship for.
+  const d = defaultInterp();
+  const v = pythonVersionOf(d);
+  if (v && wanted.includes(v)) return { ...d, version: v };
+  return null;
+}
+
+// --------------------------------------------------------------- the pip ---
+
+// This is a client to a service the whole machine talks to, so it should be
+// importable from anywhere, not pinned inside one project. No venv is created:
+// one the user did not ask for is worse than none, and it would put the library
+// where their own code cannot see it.
+//
+// Homebrew and Debian mark their interpreters externally managed and refuse a
+// plain install. Their own message says what to do - --break-system-packages,
+// and "STRONGLY recommend that you additionally pass --user". The pair is the
+// point: --user writes to ~/.local and never into the managed prefix, which is
+// the thing the error exists to protect.
+function pipInstall(py, files) {
+  const base = ["-m", "pip", "install", "--disable-pip-version-check", "-q"];
+  const run = (args) =>
+    spawnSync(py.cmd, [...py.pre, ...base, ...args, ...files],
+              { stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" });
+
+  const inVenv = spawnSync(py.cmd, [...py.pre, "-c", "import sys;print(sys.prefix!=sys.base_prefix)"],
+                           { encoding: "utf8" }).stdout?.trim() === "True";
+
+  // Windows has no externally-managed interpreters and no ~/.local; --user
+  // there writes to %APPDATA%\Python, which is what we want and is the default
+  // behaviour, so the wording follows the platform.
+  const userDir = process.platform === "win32" ? "your user site-packages" : "~/.local";
+
+  let r = run(inVenv ? [] : ["--user"]);
+  if (r.status === 0) return { ok: true, where: inVenv ? "the active virtualenv" : userDir };
+
+  if (/externally-managed-environment/i.test(r.stderr || "")) {
+    info(`this Python is externally managed - installing to ${userDir}, which leaves it untouched`);
+    r = run(["--user", "--break-system-packages"]);
+    if (r.status === 0) return { ok: true, where: userDir };
+  }
+  return { ok: false, err: (r.stderr || r.stdout || "").trim() };
+}
+
+// ------------------------------------------------------------------ key ---
+
+// Read from four places, write to one. The last two are read and never
+// written: a key already on the machine joins that workspace instead of
+// minting a second, and a config kept in ~/.macaw by hand stays as it is.
+//
+// The current directory is in the list because the coding-agents installer
+// writes $PWD/.macaw/config.json, so `npx macaw-ai install` choosing both
+// surfaces activates once rather than twice.
+function existingKey(dir) {
+  // --activate asks for a new workspace outright. Without it the only way to
+  // re-key was to delete this install's config, which the next run refills
+  // from $HOME or the current directory - so the instruction looped and anyone
+  // who had ever used MACAW could not reach activation. Nothing is deleted
+  // here; the existing files are simply not read.
+  if (process.argv.includes("--activate")) return null;
+
+  // Handed to us rather than discovered, so there is nothing to confirm. This
+  // is how `macaw-ai install` choosing both surfaces passes the key the first
+  // installer just created, instead of asking for it a second time.
+  const fromEnv = process.env.MACAW_API_KEY;
+  if (fromEnv) {
+    return {
+      key: fromEnv.trim(),
+      from: "MACAW_API_KEY",
+      workspace: process.env.MACAW_WORKSPACE || "",
+      explicit: true,
+    };
+  }
+
+  const places = [
+    process.env.MACAW_HOME && path.join(process.env.MACAW_HOME, ".macaw", "config.json"),
+    path.join(dir, ".macaw", "config.json"),
+    path.join(process.cwd(), ".macaw", "config.json"),
+    path.join(os.homedir(), ".macaw", "config.json"),
+  ].filter(Boolean);
+
+  for (const p of places) {
+    try {
+      const cfg = JSON.parse(fs.readFileSync(p, "utf8"));
+      if (typeof cfg?.api_key === "string" && cfg.api_key.startsWith("mw_")) {
+        return { key: cfg.api_key, from: p, workspace: cfg.workspace || "" };
+      }
+    } catch {
+      // Unreadable or not JSON. Try the next one.
+    }
+  }
+  return null;
+}
+
+// ------------------------------------------------------------ activation ---
+
+async function activate() {
+  const start = await fetch(`${API}/api/device/code`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    // 'default' is the regular console. secCC sends 'seccc' and gets its own
+    // view; a Python SDK install has no business landing there.
+    body: JSON.stringify({ device_name: `${os.hostname()} (client)`, platform: "default" }),
+  }).then((r) => r.json()).catch(() => null);
+
+  if (!start?.device_code) {
+    no(`Could not reach ${API}`);
+    return null;
+  }
+
+  // One clickable link, whatever the plane returned. A control plane older
+  // than verification_uri_complete still gives us both halves, so compose it
+  // rather than falling back to "here is a URL, now type this code".
+  const url = start.verification_uri_complete
+    || (start.verification_uri && start.user_code
+        && `${start.verification_uri}?user_code=${encodeURIComponent(start.user_code)}`)
+    || start.verification_uri;
+  console.log("");
+  console.log(`   Approve here:  ${C.c}${url}${C.x}`);
+  // The code is in the link. Worth printing separately only when it is not -
+  // an older control plane, or someone reading it off another machine.
+  if (!url.includes("user_code=")) console.log(`   Code  ${C.b}${start.user_code}${C.x}`);
+  console.log("");
+  console.log("   Waiting for approval...");
+
+  const deadline = Date.now() + (start.expires_in ?? 600) * 1000;
+  const every = (start.interval ?? 5) * 1000;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, every));
+    const poll = await fetch(`${API}/api/device/poll?device_code=${encodeURIComponent(start.device_code)}`)
+      .then((r) => r.json()).catch(() => null);
+    if (poll?.status === "complete") return { key: poll.api_key, workspace: poll.workspace };
+    if (poll?.status === "expired") { no("That code expired. Run this again."); return null; }
+  }
+  no("Timed out waiting for approval");
+  return null;
+}
+
+// ------------------------------------------------------------------ main ---
+
+async function main() {
+  console.log("");
+  console.log(`${C.b}  MACAW${C.x}`);
+  console.log("");
+
+  const wheels = bundledWheels();
+  const plat = platformTag();
+  const usable = wheels.filter((w) => w.platform === plat);
+
+  if (!usable.length) {
+    no(`No build for ${process.platform}/${process.arch}.`);
+    info("Builds we ship:");
+    for (const w of wheels) console.log(`      Python ${version(w.tag)}  ${w.platform}`);
+    process.exit(1);
+  }
+
+  // --check answers "would this work here, and with what" and changes nothing.
+  // Useful before installing, and the first thing to ask when it did not work.
+  if (process.argv.includes("--check")) {
+    const py = findPython(usable);
+    const d = defaultInterp();
+    const dflt = pythonVersionOf(d);
+    console.log(`  platform   ${process.platform}/${process.arch} → ${plat}`);
+    const shipped = [...new Set(usable.map((w) => version(w.tag)))].sort(byVersionDesc);
+    console.log(`  we ship    ${shipped.map((v) => "Python " + v).join(", ")}`);
+    console.log(`  ${d.display.padEnd(9)}  ${dflt || "not found"}`);
+    console.log(py?.error ? `  would use  ${py.error}`
+              : py ? `  would use  ${py.display} (${py.version})`
+              : `  would use  nothing we have a build for`);
+    if (py && !py.error && dflt && dflt !== py.version) {
+      console.log(`  ${C.y}⚠${C.x}          your ${d.display} cannot import what that installs.`);
+      console.log(`             MACAW_PYTHON=${d.display} to install into it instead`);
+    }
+    const haveKey = existingKey(path.resolve("./macaw"));
+    console.log(`  key        ${haveKey ? "reusing " + haveKey.from : "none found; would activate"}`);
+    console.log(`  endpoint   ${API}`);
+    process.exit(py && !py.error ? 0 : 1);
+  }
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const ask = async (q, dflt) => {
+    if (!process.stdin.isTTY) return dflt;           // nobody to answer
+    const a = (await rl.question(q)).trim();
+    return a === "" ? dflt : a;
+  };
+
+  // 1 — where
+  const chosen = await ask(`  Where should MACAW go? ${C.dim}[./macaw]${C.x} `, "./macaw");
+  const dir = path.resolve(chosen.replace(/^~(?=$|\/)/, os.homedir()));
+  fs.mkdirSync(dir, { recursive: true });
+  ok(dir);
+
+  // 2 — python
+  const py = findPython(usable);
+  if (!py || py.error) {
+    no(py?.error || "No Python here that we have a build for.");
+    info(`On ${plat} we ship: ${[...new Set(usable.map((w) => version(w.tag)))].sort(byVersionDesc).join(", ")}`);
+    rl.close();
+    process.exit(1);
+  }
+  ok(`Python ${py.version} (${py.display})`);
+
+  // We prefer the newest interpreter we have a wheel for, which is not always
+  // the one a bare `python3` resolves to. When they differ the install succeeds
+  // and the user's default interpreter still cannot import the library, so say
+  // so here rather than letting them find out from a traceback.
+  const dflt = defaultInterp();
+  const dfltVersion = pythonVersionOf(dflt);
+  if (dfltVersion && dfltVersion !== py.version) {
+    console.log(`  ${C.y}⚠${C.x} Your ${dflt.display} is ${dfltVersion}; this installs into Python ${py.version}.`);
+    console.log(`    Run MACAW code with ${C.b}${py.display}${C.x}, or install into ${dflt.display} instead:`);
+    console.log(`      ${C.c}MACAW_PYTHON=${dflt.display} npx @macaw-ai/client install${C.x}`);
+  }
+
+  // 3 — a key, or a workspace
+  console.log("");
+  const found = existingKey(dir);
+  let workspace = found?.workspace || "";
+  let key;
+
+  if (found?.explicit) {
+    key = found.key;
+    ok(found.workspace ? `Same workspace: ${found.workspace}` : "Using the key passed in");
+  } else if (found) {
+    info(`A key is already on this machine: ${found.from}`);
+    key = await ask(`  API Key ${C.dim}[Enter joins that workspace]${C.x} `, found.key);
+  } else if (!process.stdin.isTTY) {
+    // Without this the default is "", which starts a device activation,
+    // prints a link nobody is watching, and blocks for ten minutes.
+    no("No key found, and nothing is attached to approve a new workspace.");
+    info("Run this in a terminal, or pass a key: MACAW_API_KEY=mw_... npx @macaw-ai/client install");
+    rl.close();
+    process.exit(1);
+  } else {
+    key = await ask(`  API Key ${C.dim}[Enter creates a new workspace]${C.x} `, "");
+  }
+
+  if (key === "") {
+    const got = await activate();
+    if (!got) { rl.close(); process.exit(1); }
+    key = got.key;
+    workspace = got.workspace || "";
+    ok(`Activated in workspace ${workspace}`);
+  } else if (!key.startsWith("mw_")) {
+    no("An API key starts with 'mw_'");
+    rl.close();
+    process.exit(1);
+  }
+  rl.close();
+
+  // 4 — install
+  console.log("");
+  const wheel = usable.find((w) => version(w.tag) === py.version);
+  const adapters = fs.existsSync(path.join(PKG, "wheels"))
+    ? fs.readdirSync(path.join(PKG, "wheels")).filter((f) => f.startsWith("macaw_adapters-"))
+        .map((f) => path.join(PKG, "wheels", f))
+    : [];
+  const r = pipInstall(py, [wheel.file, ...adapters]);
+  if (!r.ok) { no("pip install failed"); console.log(r.err); process.exit(1); }
+
+  // pip exiting 0 does not mean the library is importable: a --user install
+  // whose site directory is not on this interpreter's sys.path passes, and so
+  // does one shadowed by an older copy earlier on the path. Ask the question
+  // the user will ask.
+  const imported = spawnSync(py.cmd, [...py.pre, "-c", "import macaw_client, macaw_adapters"],
+                             { encoding: "utf8" });
+  if (imported.status !== 0) {
+    no(`pip reported success, but ${py.display} cannot import what it installed.`);
+    console.log((imported.stderr || imported.stdout || "").trim());
+    process.exit(1);
+  }
+  ok(`macaw-client and macaw-adapters installed into ${r.where}, importable by ${py.display}`);
+
+  // 5 — the tree, and the config beside it
+  // Whatever build.sh assembled, verbatim. A list here would be a second
+  // place to keep in step, and it already fell out of step once.
+  const payload = path.join(PKG, "payload");
+  if (fs.existsSync(payload)) fs.cpSync(payload, dir, { recursive: true });
+  const cfgDir = path.join(dir, ".macaw");
+  fs.mkdirSync(cfgDir, { recursive: true, mode: 0o700 });
+  // The config holds an API key and the install directory may be inside a
+  // repository.
+  fs.writeFileSync(path.join(cfgDir, ".gitignore"), "*\n!.gitignore\n");
+  fs.writeFileSync(path.join(cfgDir, "config.json"), JSON.stringify({
+    transport: "http",
+    http_enabled: true,
+    macaw_endpoint: `${API}/rpc`,
+    api_key: key,
+    workspace,
+    multi_tenancy_enabled: true,
+  }, null, 2) + "\n", { mode: 0o600 });
+  ok("examples, demos and config written");
+
+  // 6 — what to do with it
+  console.log("");
+  console.log(`${C.b}  Check it${C.x}`);
+  console.log(`      cd ${dir}`);
+  console.log(`      ${py.display} secureAI/test_harness_quick.py`);
+  console.log("");
+  console.log(`  ${C.dim}To use MACAW from other directories, point MACAW_HOME at${C.x}`);
+  console.log(`  ${C.dim}this directory in your shell:${C.x}`);
+  console.log(`      MACAW_HOME=${dir}`);
+  console.log("");
+}
+
+main().catch((e) => { no(e.message); process.exit(1); });

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@macaw-ai/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.9.11",
+  "description": "Set up the MACAW client for a Python project: installs the SDK and adapters, creates a workspace, leaves the examples ready to run.",
+  "type": "module",
+  "bin": {
+    "macaw-client-install": "bin/install.js"
+  },
+  "files": [
+    "bin/install.js",
+    "wheels",
+    "payload",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "SEE LICENSE IN LICENSE.md",
+  "homepage": "https://macawsecurity.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mohanua/macaw-client-distro.git"
+  },
+  "keywords": [
+    "macaw",
+    "agent",
+    "policy",
+    "security",
+    "governance",
+    "openai",
+    "anthropic",
+    "langchain",
+    "mcp"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/payload/README.md

@@ -0,0 +1,56 @@
+# MACAW
+
+Installed here by `npx @macaw-ai/client install`.
+
+```
+  secureAI/         the open-source half, Apache-2.0
+    examples/       one per framework - openai, anthropic, langchain, mcp,
+                    litellm, pydantic_ai, attestations, phishing-resistance
+    demos/          three tutorials: policy controls, RBAC, intent
+    macaw_adapters/ the adapter source, to read
+  .macaw/           your key and endpoint. Treat it like a credential.
+```
+
+## Check it works
+
+```bash
+python secureAI/test_harness_quick.py
+```
+
+Runs the MCP examples and 1a. No API keys needed for the MCP path.
+
+## What is installed where
+
+The adapter directory above is **source, for reading**. What actually runs is
+the wheel pip installed into your Python:
+
+```bash
+python -c "import macaw_client, macaw_adapters; print(macaw_client.__file__)"
+```
+
+Both are importable from anywhere on this machine. The directory you are in
+holds what you *run*; Python holds what you *import*.
+
+## Using it from somewhere else
+
+The client looks for its config in `$MACAW_HOME`, then the current directory,
+then your home directory. So from here it already works. To use it from another
+directory, point `MACAW_HOME` at this one in your shell.
+
+## The adapters
+
+```python
+from macaw_adapters.openai import SecureOpenAI
+from macaw_adapters.mcp import SecureMCP
+```
+
+Imports are lazy — `macaw_adapters.mcp` works without `openai` installed, and
+the reverse. You need whichever framework SDK you are actually adapting, which
+you will already have.
+
+Source, issues and new adapters: https://github.com/macawsecurity/secureAI
+
+## A different workspace
+
+Run the installer again with an API key from your admin to join theirs, or
+delete `.macaw/config.json` and run it again to create a new one.