agentera 0.0.0 → 0.0.2

package/README.md

@@ -12,6 +12,29 @@ npx agentera prime
 npm install -g agentera
 ```
 
+## v3 hint
+
+While the Python CLI remains on `@latest`, every 0.x shim invocation emits a
+three-line deprecation hint to **stderr** telling the user the v3 TypeScript
+CLI is ready on the `@next` tag:
+
+```
+agentera 2.x (Python) is in maintenance; the v3 TypeScript CLI is ready on the @next tag:
+  npx -y agentera@next prime
+Set AGENTERA_NO_V3_HINT=1 to suppress this message.
+```
+
+The hint never appears on `--version`/`-V` and never touches stdout, so
+`--json` and pipe consumers stay clean. `--help`/`-h` also lists the `@next`
+pointer, and the install-help failure path (no backend available) leads with
+the `@next` line.
+
+Suppress the hint for non-interactive CI or scripted invocations:
+
+```bash
+AGENTERA_NO_V3_HINT=1 npx agentera prime
+```
+
 ## Delegation order
 
 When you run `agentera`, the shim forwards to the existing Python CLI using the first match:
@@ -41,8 +64,8 @@ npx agentera@0.0.0 --version
 ## Development
 
 ```bash
-node packages/cli/bin/agentera.mjs --version
-node packages/cli/bin/agentera.mjs --help
+node packages/cli/shim/bin/agentera.mjs --version
+node packages/cli/shim/bin/agentera.mjs --help
 ```
 
 Suite version pin lives in `package.json` under `agentera.suiteVersion` / `agentera.gitRef`; npm `version` stays on the `0.0.x` line until 3.0.

package/bin/agentera.mjs

@@ -35,6 +35,9 @@ if (userArgs[0] === "--help" || userArgs[0] === "-h") {
   console.log("  2. scripts/agentera in a parent repo (uv run)");
   console.log("  3. uvx --from git+https://github.com/jgabor/agentera@<tag> agentera");
   console.log("");
+  console.log("v3 (TypeScript) is available now on the @next tag:");
+  console.log("  npx -y agentera@next prime");
+  console.log("");
   console.log("https://github.com/jgabor/agentera");
   process.exit(0);
 }

package/lib/exec.mjs

@@ -1,36 +1,68 @@
 import { spawnSync } from "node:child_process";
-import path from "node:path";
 
 import { resolveBackend } from "./resolve.mjs";
 
+const V3_NEXT_COMMAND = "npx -y agentera@next prime";
+
+/**
+ * Print the v3 deprecation hint to stderr unless the user opted out via
+ * AGENTERA_NO_V3_HINT=1. Called once per dispatch (after the --version
+ * early-return) so every v2 invocation surfaces the @next pointer while the
+ * Python CLI remains on @latest.
+ *
+ * @param {{ logStderr?: (message: string) => void }} [options]
+ * @returns {void}
+ */
+export function printV3Hint(options = {}) {
+  if (process.env.AGENTERA_NO_V3_HINT === "1") {
+    return;
+  }
+  const log = options.logStderr ?? ((msg) => console.error(msg));
+  log("agentera 2.x (Python) is in maintenance; the v3 TypeScript CLI is ready on the @next tag:");
+  log(`  ${V3_NEXT_COMMAND}`);
+  log("Set AGENTERA_NO_V3_HINT=1 to suppress this message.");
+}
+
+/**
+ * @typedef {object} RunBackendResult
+ * @property {number} exitCode
+ * @property {boolean} fallthrough true when the backend is unusable and dispatch should try the next strategy
+ */
+
 /**
  * @param {import('./resolve.mjs').ResolveResult} backend
  * @param {string[]} args
- * @param {{ gitRef?: string; gitRepo?: string }} [meta]
- * @returns {number}
+ * @param {{ gitRef?: string; gitRepo?: string; cwd?: string }} [meta]
+ * @returns {RunBackendResult}
  */
 export function runBackend(backend, args, meta = {}) {
   if (backend.kind === "app-home" && backend.scriptPath) {
-    const appRoot = path.dirname(path.dirname(backend.scriptPath));
-    return spawnChecked("uv", ["run", backend.scriptPath, ...args], {
-      cwd: appRoot,
+    const exitCode = spawnChecked("uv", ["run", backend.scriptPath, ...args], {
+      cwd: meta.cwd,
     });
+    return { exitCode, fallthrough: exitCode !== 0 };
   }
 
   if (backend.kind === "repo" && backend.repoRoot) {
-    return spawnChecked("uv", ["run", "scripts/agentera", ...args], {
-      cwd: backend.repoRoot,
-    });
+    return {
+      exitCode: spawnChecked("uv", ["run", "scripts/agentera", ...args], {
+        cwd: backend.repoRoot,
+      }),
+      fallthrough: false,
+    };
   }
 
   if (backend.kind === "uvx") {
-    const gitRef = backend.gitRef ?? meta.gitRef ?? "v2.7.6";
+    const gitRef = backend.gitRef ?? meta.gitRef ?? "v2.7.7";
     const gitRepo = backend.gitRepo ?? meta.gitRepo ?? "https://github.com/jgabor/agentera";
     const from = `git+${gitRepo}@${gitRef}`;
-    return spawnChecked("uvx", ["--from", from, "agentera", ...args], {});
+    return {
+      exitCode: spawnChecked("uvx", ["--from", from, "agentera", ...args], {}),
+      fallthrough: false,
+    };
   }
 
-  return 1;
+  return { exitCode: 1, fallthrough: false };
 }
 
 /**
@@ -63,6 +95,7 @@ function spawnChecked(command, args, options) {
  * @param {string} [options.gitRef]
  * @param {string} [options.gitRepo]
  * @param {(message: string) => void} [options.printInstallHelp]
+ * @param {(message: string) => void} [options.logStderr]
  * @returns {number}
  */
 export function dispatch(argv, options = {}) {
@@ -71,13 +104,37 @@ export function dispatch(argv, options = {}) {
     return 0;
   }
 
-  const backend = resolveBackend({
+  printV3Hint({ logStderr: options.logStderr });
+
+  let backend = resolveBackend({
     cwd: options.cwd,
     env: options.env,
     gitRef: options.gitRef,
     gitRepo: options.gitRepo,
+    logStderr: options.logStderr,
   });
 
+  if (backend.kind === "app-home") {
+    const result = runBackend(backend, userArgs, {
+      gitRef: options.gitRef,
+      gitRepo: options.gitRepo,
+      cwd: options.cwd,
+    });
+    if (!result.fallthrough) {
+      return result.exitCode;
+    }
+    console.error(
+      `agentera: app-home backend crashed (exit ${result.exitCode}); falling through to next resolution strategy`,
+    );
+    backend = resolveBackend({
+      cwd: options.cwd,
+      env: options.env,
+      gitRef: options.gitRef,
+      gitRepo: options.gitRepo,
+      excludeAppHome: true,
+    });
+  }
+
   if (backend.kind === "none") {
     const print = options.printInstallHelp ?? printInstallHelp;
     print(backend.reason ?? "no backend available");
@@ -87,7 +144,8 @@ export function dispatch(argv, options = {}) {
   return runBackend(backend, userArgs, {
     gitRef: options.gitRef,
     gitRepo: options.gitRepo,
-  });
+    cwd: options.cwd,
+  }).exitCode;
 }
 
 /**
@@ -97,6 +155,11 @@ export function printInstallHelp(reason) {
   const lines = [
     "agentera: npm CLI shim (0.x) — native TypeScript CLI ships in Agentera 3.0.",
     reason ? `agentera: ${reason}` : "",
+  ];
+  if (process.env.AGENTERA_NO_V3_HINT !== "1") {
+    lines.push("", "The v3 TypeScript CLI is ready now on the @next tag:", `  ${V3_NEXT_COMMAND}`);
+  }
+  lines.push(
     "",
     "Install Agentera for your runtime:",
     "  npx skills add jgabor/agentera -g -a claude-code --skill agentera -y",
@@ -109,8 +172,8 @@ export function printInstallHelp(reason) {
     "  uv run scripts/agentera prime",
     "",
     "https://github.com/jgabor/agentera#install",
-  ].filter(Boolean);
-  for (const line of lines) {
+  );
+  for (const line of lines.filter(Boolean)) {
     console.error(line);
   }
 }

package/lib/resolve.mjs

@@ -5,6 +5,9 @@ const DEFAULT_GIT_REPO = "https://github.com/jgabor/agentera";
 const APP_SCRIPT_REL = path.join("app", "scripts", "agentera");
 const REPO_SCRIPT_REL = path.join("scripts", "agentera");
 
+const HEAD_READ_BYTES = 2048;
+const APP_HOME_MISMATCH_PREFIX = "agentera: app-home backend unavailable: shebang/content mismatch";
+
 /**
  * @typedef {'app-home' | 'repo' | 'uvx' | 'none'} BackendKind
  */
@@ -19,6 +22,16 @@ const REPO_SCRIPT_REL = path.join("scripts", "agentera");
  * @property {string} [reason]
  */
 
+/**
+ * @typedef {object} ResolveOptions
+ * @property {string} [cwd]
+ * @property {NodeJS.ProcessEnv} [env]
+ * @property {string} [gitRef]
+ * @property {string} [gitRepo]
+ * @property {boolean} [excludeAppHome]
+ * @property {(message: string) => void} [logStderr]
+ */
+
 /**
  * @param {string | undefined} command
  * @returns {boolean}
@@ -56,6 +69,110 @@ export function isRunnableFile(filePath) {
   }
 }
 
+/**
+ * @param {string} filePath
+ * @returns {string | null}
+ */
+function readHead(filePath) {
+  let fd;
+  try {
+    fd = fs.openSync(filePath, "r");
+    const buf = Buffer.alloc(HEAD_READ_BYTES);
+    const bytes = fs.readSync(fd, buf, 0, HEAD_READ_BYTES, 0);
+    return buf.slice(0, bytes).toString("utf8");
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // ignore
+      }
+    }
+  }
+}
+
+/**
+ * @param {string} shebang
+ * @returns {'js' | 'python' | 'unknown'}
+ */
+function shebangRuntime(shebang) {
+  if (/\bnode\b/.test(shebang)) {
+    return "js";
+  }
+  if (/\bpython\d*\b/.test(shebang) || /\buv\b[^\n]*\brun\b/.test(shebang)) {
+    return "python";
+  }
+  return "unknown";
+}
+
+/**
+ * @param {string} body
+ * @returns {'js' | 'python' | 'unknown'}
+ */
+function contentLanguage(body) {
+  if (body.includes("# /// script")) {
+    return "python";
+  }
+  if (/\brequire\s*\(/.test(body) || /\bmodule\.exports\b/.test(body)) {
+    return "js";
+  }
+  if (/^\s*import\s+[^'"\n]+\s+from\s+['"]/m.test(body)) {
+    return "js";
+  }
+  if (/^\s*import\s+['"]/m.test(body)) {
+    return "js";
+  }
+  const lines = body.split("\n").slice(0, 30);
+  for (const raw of lines) {
+    const t = raw.trimStart();
+    if (
+      /^import\s+\w+\s*$/.test(t) ||
+      t.startsWith("from ") ||
+      t.startsWith("def ") ||
+      t.startsWith("class ")
+    ) {
+      return "python";
+    }
+    if (
+      t.startsWith("const ") ||
+      t.startsWith("let ") ||
+      t.startsWith("var ") ||
+      t.startsWith("export ")
+    ) {
+      return "js";
+    }
+  }
+  return "unknown";
+}
+
+/**
+ * @param {string} filePath
+ * @returns {string | null}
+ */
+export function detectShebangContentMismatch(filePath) {
+  const head = readHead(filePath);
+  if (head === null) {
+    return null;
+  }
+  const nl = head.indexOf("\n");
+  const shebang = (nl >= 0 ? head.slice(0, nl) : head).trim();
+  if (!shebang.startsWith("#!")) {
+    return null;
+  }
+  const body = nl >= 0 ? head.slice(nl + 1) : "";
+  const expected = shebangRuntime(shebang);
+  const actual = contentLanguage(body);
+  if (expected === "unknown" || actual === "unknown") {
+    return null;
+  }
+  if (expected !== actual) {
+    return `shebang=${expected} content=${actual}`;
+  }
+  return null;
+}
+
 /**
  * @param {string} startDir
  * @returns {string | null}
@@ -77,33 +194,43 @@ export function findRepoRoot(startDir) {
 
 /**
  * @param {string | undefined} agenteraHome
+ * @param {{ logStderr?: (message: string) => void }} [options]
  * @returns {string | null}
  */
-export function findAppHomeScript(agenteraHome) {
+export function findAppHomeScript(agenteraHome, options = {}) {
   if (!agenteraHome) {
     return null;
   }
   const scriptPath = path.join(path.resolve(agenteraHome), APP_SCRIPT_REL);
-  return isRunnableFile(scriptPath) ? scriptPath : null;
+  if (!isRunnableFile(scriptPath)) {
+    return null;
+  }
+  const mismatch = detectShebangContentMismatch(scriptPath);
+  if (mismatch) {
+    const log = options.logStderr ?? ((msg) => console.error(msg));
+    log(`${APP_HOME_MISMATCH_PREFIX} (${mismatch}) at ${scriptPath}`);
+    return null;
+  }
+  return scriptPath;
 }
 
 /**
- * @param {object} options
- * @param {string} [options.cwd]
- * @param {NodeJS.ProcessEnv} [options.env]
- * @param {string} [options.gitRef]
- * @param {string} [options.gitRepo]
+ * @param {ResolveOptions} [options]
  * @returns {ResolveResult}
  */
 export function resolveBackend({
   cwd = process.cwd(),
   env = process.env,
-  gitRef = "v2.7.6",
+  gitRef = "v2.7.7",
   gitRepo = DEFAULT_GIT_REPO,
+  excludeAppHome = false,
+  logStderr,
 } = {}) {
-  const scriptPath = findAppHomeScript(env.AGENTERA_HOME);
-  if (scriptPath) {
-    return { kind: "app-home", scriptPath };
+  if (!excludeAppHome) {
+    const scriptPath = findAppHomeScript(env.AGENTERA_HOME, { logStderr });
+    if (scriptPath) {
+      return { kind: "app-home", scriptPath };
+    }
   }
 
   const repoRoot = findRepoRoot(cwd);

package/package.json

@@ -1,24 +1,20 @@
 {
   "name": "agentera",
-  "version": "0.0.0",
+  "version": "0.0.2",
   "description": "npm shim for Agentera — delegates to the Python CLI until the 3.0 TypeScript release",
-  "type": "module",
-  "license": "Apache-2.0",
-  "author": "Jonathan Gabor",
-  "homepage": "https://github.com/jgabor/agentera",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/jgabor/agentera.git",
-    "directory": "packages/cli"
-  },
   "keywords": [
     "agentera",
     "agents",
     "cli",
     "orchestration"
   ],
-  "engines": {
-    "node": ">=22"
+  "homepage": "https://github.com/jgabor/agentera",
+  "license": "Apache-2.0",
+  "author": "Jonathan Gabor",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jgabor/agentera.git",
+    "directory": "packages/cli"
   },
   "bin": {
     "agentera": "./bin/agentera.mjs"
@@ -29,8 +25,16 @@
     "README.md",
     "LICENSE"
   ],
+  "type": "module",
+  "scripts": {
+    "test": "pnpm -C .. test test/shim/ && node --test test/*.test.mjs",
+    "publish:stable": "node ./scripts/publish-stable.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
   "agentera": {
-    "suiteVersion": "2.7.6",
-    "gitRef": "v2.7.6"
+    "suiteVersion": "2.7.7",
+    "gitRef": "ce4a7054a8438b8b0aac013bac4b86ba1a9de3dd"
   }
 }