@macaw-ai/client 0.9.10 → 0.9.12

package/bin/install.js

@@ -65,24 +65,59 @@ const byVersionDesc = (a, b) => {
 
 // ---------------------------------------------------------------- python ---
 
-function pythonVersionOf(exe) {
-  const r = spawnSync(exe, ["-c", "import sys;print('%d.%d' % sys.version_info[:2])"],
+// 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 exe of [`python${v}`, `python3.${v.split(".")[1]}`]) {
-      if (pythonVersionOf(exe) === v) return { exe, version: v };
+    for (const py of candidatesFor(v)) {
+      if (pythonVersionOf(py) === v) return { ...py, version: v };
     }
   }
-  // Whatever `python3` is may still be one we ship for.
-  const v = pythonVersionOf("python3");
-  if (v && wanted.includes(v)) return { exe: "python3", 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;
 }
 
@@ -98,25 +133,81 @@ function findPython(wheels) {
 // 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(python, files) {
+function pipInstall(py, files) {
   const base = ["-m", "pip", "install", "--disable-pip-version-check", "-q"];
   const run = (args) =>
-    spawnSync(python, [...base, ...args, ...files], { stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" });
+    spawnSync(py.cmd, [...py.pre, ...base, ...args, ...files],
+              { stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" });
 
-  const inVenv = spawnSync(python, ["-c", "import sys;print(sys.prefix!=sys.base_prefix)"],
+  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" : "~/.local" };
+  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 ~/.local, which leaves it untouched");
+    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: "~/.local" };
+    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() {
@@ -163,7 +254,24 @@ async function activate() {
 
 // ------------------------------------------------------------------ main ---
 
+function usage() {
+  console.log("");
+  console.log(`${C.b}  macaw-client${C.x} - the MACAW SDK and the secureAI adapters`);
+  console.log("");
+  console.log("    macaw-client install              pick a Python, install the wheels,");
+  console.log("                                      lay down the examples");
+  console.log("    macaw-client install --activate   the same, with a new workspace");
+  console.log("    macaw-client --check              report what it would do, change nothing");
+  console.log("");
+  process.exit(1);
+}
+
 async function main() {
+  // A verb, like `macaw-sidecar install`. Bare, this used to pip install into
+  // an interpreter and write a directory with nothing asked for.
+  const argv = process.argv.slice(2);
+  if (!argv.includes("--check") && !argv.includes("install")) usage();
+
   console.log("");
   console.log(`${C.b}  MACAW${C.x}`);
   console.log("");
@@ -183,12 +291,23 @@ async function main() {
   // 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(py ? `  found      ${py.exe} (${py.version})` : `  found      nothing we have a build for`);
+    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 ? 0 : 1);
+    process.exit(py && !py.error ? 0 : 1);
   }
 
   const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -206,22 +325,76 @@ async function main() {
 
   // 2 — python
   const py = findPython(usable);
-  if (!py) {
-    no("No Python here that we have a build for.");
+  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}`);
-  const newest = usable.map((w) => version(w.tag)).sort(byVersionDesc)[0];
-  if (py.version !== newest) {
-    console.log(`  ${C.y}⚠${C.x} We are moving to Python ${newest}.`);
+  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
+  // 3 — the workspace. The same three choices, in the same words, as the
+  // coding-agents installer: the step that confused people was this one
+  // deciding for them and saying so afterwards.
   console.log("");
-  let key = await ask(`  API Key ${C.dim}[Enter creates a new workspace]${C.x} `, "");
-  let workspace = "";
+  console.log(`${C.b}  Workspace${C.x}`);
+  const found = existingKey(dir);
+  let workspace = found?.workspace || "";
+  let key;
+
+  if (found?.explicit) {
+    // Handed to us rather than discovered - nothing to confirm.
+    key = found.key;
+    ok(found.workspace ? `Same workspace: ${found.workspace}` : "Using the key passed in");
+  } else if (!process.stdin.isTTY) {
+    if (!found) {
+      no("No key found, and nothing is attached to answer.");
+      info("Pass one:  MACAW_API_KEY=mw_... npx @macaw-ai/client install");
+      rl.close();
+      process.exit(1);
+    }
+    key = found.key;
+    ok(found.from);
+  } else {
+    console.log("");
+    console.log("    1) Use a key already on this machine");
+    console.log("    2) Paste an API key");
+    console.log("    3) Create a new workspace");
+    console.log("");
+    const choice = (await ask("    Choose [1]: ", "1")) || "1";
+
+    if (choice === "1" && found) {
+      key = found.key;
+      ok(found.from);
+    } else if (choice === "1") {
+      console.log(`  ${C.y}⚠${C.x} No key found.`);
+      console.log("      Looked in: $MACAW_API_KEY, $MACAW_HOME, this directory, ~/.macaw");
+      console.log("      Creating a new workspace instead.");
+      key = "";
+    } else if (choice === "2") {
+      key = await ask("    API Key: ", "");
+      if (!key) { no("Nothing entered."); rl.close(); process.exit(1); }
+    } else if (choice === "3") {
+      key = "";
+    } else {
+      no("Not a choice.");
+      rl.close();
+      process.exit(1);
+    }
+  }
+
   if (key === "") {
     const got = await activate();
     if (!got) { rl.close(); process.exit(1); }
@@ -242,9 +415,21 @@ async function main() {
     ? fs.readdirSync(path.join(PKG, "wheels")).filter((f) => f.startsWith("macaw_adapters-"))
         .map((f) => path.join(PKG, "wheels", f))
     : [];
-  const r = pipInstall(py.exe, [wheel.file, ...adapters]);
+  const r = pipInstall(py, [wheel.file, ...adapters]);
   if (!r.ok) { no("pip install failed"); console.log(r.err); process.exit(1); }
-  ok(`macaw-client and macaw-adapters installed into ${r.where}`);
+
+  // 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
@@ -253,6 +438,9 @@ async function main() {
   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,
@@ -267,7 +455,7 @@ async function main() {
   console.log("");
   console.log(`${C.b}  Check it${C.x}`);
   console.log(`      cd ${dir}`);
-  console.log(`      ${py.exe} secureAI/test_harness_quick.py`);
+  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}`);

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@macaw-ai/client",
-  "version": "0.9.10",
+  "version": "0.9.12",
   "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"
+    "macaw-client": "bin/install.js"
   },
   "files": [
     "bin/install.js",