@retasc/cli 1.7.2 → 1.9.0

package/dist/lib/launcher.js

@@ -0,0 +1,200 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+const PKG = "@retasc/cli";
+// Windows shims are .cmd files, which cannot be spawned without a shell. Everywhere
+// else a shell is an injection surface for no benefit, so it stays off.
+//
+// WINDOWS IS NOT A SUPPORTED PLATFORM. The branches below are written to npm's
+// documented layout and unit-tested for shape, but nothing here has ever been RUN on
+// Windows. Treat them as best effort: they may well work, and a Windows bug report is
+// not a regression against anything we claim. Kept rather than removed because throwing
+// on win32 would break someone for whom it currently works, for no gain.
+const WIN = process.platform === "win32";
+/**
+ * Does `command […args] --version` actually run, and print something version-shaped?
+ *
+ * Executing is the whole point. A binary can exist on disk and still be unusable (wrong
+ * arch, broken symlink, a shim whose target was removed), and the version check also
+ * guards against spawning some UNRELATED program that happens to be called `retasc`.
+ */
+export function runsOk(command, args = []) {
+    let r;
+    try {
+        r = spawnSync(command, [...args, "--version"], {
+            encoding: "utf8",
+            shell: WIN,
+            timeout: 60_000,
+        });
+    }
+    catch {
+        return null;
+    }
+    if (r.error || r.status !== 0)
+        return null;
+    const out = (r.stdout || "").trim();
+    // Our `--version` prints a bare semver (commander's .version()). Anything else is a
+    // different program, and pointing a marker at it would be worse than not writing one.
+    return /^\d+\.\d+\.\d+/.test(out) ? out : null;
+}
+/** npm's global prefix, or null when npm itself can't be run. */
+export function npmGlobalPrefix() {
+    let r;
+    try {
+        r = spawnSync("npm", ["prefix", "-g"], { encoding: "utf8", shell: WIN, timeout: 60_000 });
+    }
+    catch {
+        return null;
+    }
+    if (r.error || r.status !== 0)
+        return null;
+    const out = (r.stdout || "").trim();
+    return out || null;
+}
+/**
+ * Where npm puts the `retasc` shim for a global install.
+ *
+ * `npm bin -g` was REMOVED in npm 9, so it can't be asked directly — the prefix has to
+ * be turned into a bin path by hand, and the layout differs by platform: POSIX nests a
+ * `bin/`, Windows puts the `.cmd` shim straight in the prefix root.
+ */
+export function globalBinCandidates(prefix, win = WIN) {
+    return win
+        ? [join(prefix, "retasc.cmd"), join(prefix, "retasc")]
+        : [join(prefix, "bin", "retasc")];
+}
+/**
+ * A launcher safe to write into a SHARED file.
+ *
+ * The absolute-path form is correct for the machine that resolved it and wrong everywhere
+ * else: `./.mcp.json` is the secret-free marker the product describes as safe to commit,
+ * so a path under someone's home directory both leaks their username into a committed
+ * file and hands every teammate a command that does not exist on their machine. The bare
+ * `retasc` it replaces was at least portable. So project-scoped writes get the pinned npx
+ * form, which is slower but true on any machine.
+ */
+export function portableLauncher(r, version) {
+    if (r.how !== "absolute")
+        return r.launcher;
+    return { command: "npx", args: ["-y", `${PKG}@${version}`] };
+}
+/**
+ * How to spell "run this CLI again", for a message printed BEFORE anything has been made
+ * durable (RTSC-492).
+ *
+ * `join` can stop for reasons that have nothing to do with us — an org with no projects,
+ * a mint that failed — and every one of those has to name the command that resumes. Until
+ * `resolveLauncher` has run there may be no `retasc` on this machine at all, so telling
+ * someone to type `retasc bind …` would be telling them to type a command that does not
+ * exist. That is the same defect as a marker naming a missing binary, just aimed at the
+ * human instead of the agent.
+ *
+ * Decided from argv rather than by probing: it costs no subprocess, and it names the form
+ * they DEMONSTRABLY have — they just used it. npx unpacks the package into its own `_npx`
+ * cache and puts nothing on PATH, so a script path under that cache is proof of an npx run.
+ */
+export function selfCommand(version, argv1 = process.argv[1] ?? "") {
+    return /[\\/]_npx[\\/]/.test(argv1) ? `npx -y ${PKG}@${version}` : "retasc";
+}
+/** Install (or upgrade to) an exact version globally. Returns null on success. */
+function installGlobal(version) {
+    // A cold global install takes seconds with no output of its own. Silence here reads as
+    // a hang in the middle of a bind, so say what is happening before it starts.
+    console.log("  Installing the retasc CLI so your agent can start it…");
+    let r;
+    try {
+        r = spawnSync("npm", ["install", "-g", `${PKG}@${version}`], {
+            encoding: "utf8",
+            shell: WIN,
+            // A cold global install pulls the tarball and its deps; 60s is not always enough.
+            timeout: 180_000,
+        });
+    }
+    catch (e) {
+        return e instanceof Error ? e.message : String(e);
+    }
+    if (r.error)
+        return r.error.message;
+    if (r.status !== 0) {
+        // EACCES is by far the common one (a prefix owned by root), and its first line is
+        // the useful part — the rest is npm's log-file boilerplate.
+        const msg = (r.stderr || r.stdout || "").trim().split("\n")[0];
+        return msg || `npm exited ${r.status}`;
+    }
+    return null;
+}
+/**
+ * Decide what the marker should name, and prove it before returning it.
+ *
+ * Order matters. An already-working `retasc` is left alone (no surprise installs for
+ * someone who already manages their own). Otherwise we try to make one, and if the
+ * install lands somewhere PATH can't see, the ABSOLUTE path to that binary is used
+ * instead — verified to run, full speed, and immune to whatever is wrong with PATH.
+ *
+ * npx is last on purpose. It works, but it costs a registry round-trip on every agent
+ * start (measured ~2.4s against ~0.06s for the binary), and unpinned it would resolve
+ * `latest` each time, so an agent's MCP server could change version mid-project without
+ * anyone asking. It is pinned here for exactly that reason.
+ */
+export function resolveLauncher(opts) {
+    // 1. Already usable? Leave it alone.
+    if (runsOk("retasc")) {
+        return { launcher: { command: "retasc", args: [] }, how: "on-path", verified: true };
+    }
+    const npxLauncher = { command: "npx", args: ["-y", `${PKG}@${opts.version}`] };
+    // Last resort, so it is probed too rather than assumed — the point of this whole
+    // module is that nothing gets written into a marker on faith.
+    const npxFallback = (reason) => ({
+        launcher: npxLauncher,
+        how: "npx",
+        reason,
+        verified: runsOk("npx", npxLauncher.args) !== null,
+    });
+    if (opts.install === false)
+        return npxFallback("install not attempted");
+    // 2. Try to make `retasc` real.
+    const failure = installGlobal(opts.version);
+    // 3. Prove it, by running it. An exit code of 0 is not evidence the command resolves:
+    //    npm can install happily into a prefix whose bin directory PATH never searches.
+    if (!failure) {
+        if (runsOk("retasc")) {
+            return { launcher: { command: "retasc", args: [] }, how: "installed", verified: true };
+        }
+        // Installed, but PATH can't see it. Name the file directly — this is the case a
+        // shell one-liner can never recover from, because the shell fails before our code runs.
+        const prefix = npmGlobalPrefix();
+        for (const bin of prefix ? globalBinCandidates(prefix) : []) {
+            if (existsSync(bin) && runsOk(bin)) {
+                return { launcher: { command: bin, args: [] }, how: "absolute", binPath: bin, verified: true };
+            }
+        }
+    }
+    // 4. Nothing durable. Fall back, pinned, and let the caller say why.
+    return npxFallback(failure ?? "installed, but the binary could not be located or run");
+}
+/** What to tell the user about the outcome. One line, or none when nothing happened. */
+export function launcherNote(r) {
+    switch (r.how) {
+        case "on-path":
+            return null; // nothing changed; saying so is noise
+        case "installed":
+            return "✓ Installed `retasc` so your agent can start it directly.";
+        case "absolute":
+            return (`✓ Installed retasc at ${r.binPath}\n` +
+                "  Its folder isn't on your PATH, so your agent will use the full path above.\n" +
+                `  To type \`retasc\` yourself, add this to your shell profile:\n` +
+                `    export PATH="${r.binPath?.replace(/\/retasc$/, "")}:$PATH"`);
+        case "npx":
+            // Unverified is the one outcome where the workspace is written but NOT working.
+            // Say that outright: the whole defect this replaces was a setup that reported
+            // success and left the agent unable to start.
+            if (!r.verified) {
+                return (`! Couldn't install retasc${r.reason ? ` (${r.reason})` : ""}, and npx can't start it either.\n` +
+                    "  The marker was written, but your agent will NOT be able to start Retasc yet.\n" +
+                    "  Install the CLI, then run `retasc bind` again:  npm install -g @retasc/cli");
+            }
+            return (`! Couldn't install retasc globally${r.reason ? ` (${r.reason})` : ""}.\n` +
+                "  Your agent will start it through npx instead, which works but is slower\n" +
+                "  and needs the network. To fix it later, run:  npm install -g @retasc/cli");
+    }
+}

package/dist/lib/text.js

@@ -0,0 +1,21 @@
+/**
+ * Strip control characters from a string before printing it (RTSC-261, RTSC-492).
+ *
+ * Anything that came off the wire is untrusted output: it reaches `console.log` in a
+ * terminal that acts on escape sequences, so a value carrying `\x1b[…` can move the cursor,
+ * clear the line, or overwrite text the user is reading. That matters most where the text
+ * sits next to a decision — a name in a confirm prompt could be dressed up to look like the
+ * prompt itself.
+ *
+ * The riskiest strings in the product are the ones this exists for: an imported member's
+ * display name is chosen in ClickUp/Jira/Asana by someone who is not our user, carried
+ * across by a migration verbatim, and then shown to a human about to make an irreversible
+ * choice about it.
+ *
+ * Mirrors `sanitize` in `convex/lib/userError.ts` and the inline cleanup in `formatError`.
+ * The three are one rule; this is the copy the CLI's own printing paths share.
+ */
+export function clean(s) {
+    // eslint-disable-next-line no-control-regex
+    return String(s).replace(/[\x00-\x1f\x7f\u0085\u2028\u2029]/g, " ");
+}

package/dist/version.js

@@ -0,0 +1,11 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+// Single source of truth for the version, read from package.json at runtime relative to
+// the COMPILED file (dist/version.js -> ../package.json). A JSON import won't work:
+// tsconfig has rootDir "src", so importing ../package.json is outside it.
+//
+// It lives in its own module because two places now need it — `--version`, and the
+// pinned npx fallback the MCP marker may name (RTSC-493). A marker pinned to a version
+// this build doesn't match would spawn a different CLI than the one that wrote it.
+export const VERSION = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")).version;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.7.2",
+  "version": "1.9.0",
   "description": "Retasc CLI — sign in with GitHub, create projects, mint agent API keys, and wire your agent to the Retasc MCP server in one command.",
   "type": "module",
   "bin": {