epismo 1.4.0 → 1.5.0

package/README.md

@@ -1,7 +1,6 @@
 # Epismo CLI
 
-The CLI for [Epismo](https://epismo.ai), implemented in Go and　distributed
-as a native executable.
+Native command-line interface for [Epismo](https://epismo.ai). It is written in Go and returns JSON, making it useful in terminals, scripts, and agent workflows.
 
 ## Install
 
@@ -17,35 +16,41 @@ Windows PowerShell:
 irm https://epismo.ai/install.ps1 | iex
 ```
 
-With Go:
+Or install with Go or npm:
 
 ```sh
 go install github.com/epismoai/cli/cmd/epismo@latest
+npm install -g epismo
 ```
 
-With npm:
+Prebuilt archives, standalone executables, and `checksums.txt` are available from [GitHub Releases](https://github.com/epismoai/cli/releases).
+
+## Updating
+
+The CLI checks GitHub Releases for a newer version at most once every 24 hours in interactive terminals. When an update is available, run:
 
 ```sh
-npm install -g epismo
+epismo update
 ```
 
-You can also download a platform archive, a raw executable, and `checksums.txt` from
-[GitHub Releases](https://github.com/epismoai/cli/releases).
+The command identifies how the active executable was installed and returns the appropriate installation command; it never modifies the executable itself. Default shell installations receive the short command shown above. A custom installation directory is included only when needed. Go and global Node installations receive a manager-specific command when the package manager can be identified. Yarn's global command is returned only for Yarn Classic because modern Yarn does not support that workflow. Set `EPISMO_UPDATE_CHECK=0` to disable automatic checks.
 
-## Usage
+The npm package contains a dependency-free JavaScript launcher and all supported native binaries. It uses no lifecycle installation scripts and performs no additional downloads during installation. The launcher selects the binary for the current platform and passes its package-manager context to the native CLI. Shell and PowerShell installers write an installation receipt next to the executable; Go installations are identified from embedded build metadata. If the method cannot be determined safely, `epismo update` links to the update instructions without modifying the executable.
+
+## Quick start
 
 ```sh
 epismo login
-epismo whoami
 epismo workspace list
+epismo workspace use WORKSPACE_ID # optional: save a default workspace
 epismo playbook search --query onboarding
-epismo case list --status open
-epismo task list
-epismo suggestion list
 ```
 
-Every successful command writes JSON to stdout. Warnings and errors are JSON on
-stderr, making the CLI suitable for both people and agents.
+Run `epismo --help` for command groups, or append `--help` to any group or command for its options.
+
+## Output and input
+
+Successful commands write JSON to stdout; warnings and errors write JSON to stderr. This keeps output easy to use from scripts and agents.
 
 ```json
 {
@@ -57,54 +62,41 @@ stderr, making the CLI suitable for both people and agents.
 }
 ```
 
-Use `epismo --help`, `epismo <group> --help`, or
-`epismo <group> <command> --help` for the complete command reference.
-
-### Structured input
-
-Commands that accept request payloads support inline JSON, files, and stdin:
+Commands that accept a request body support inline JSON, a file, or stdin:
 
 ```sh
 epismo playbook create --input @playbook.json
 epismo case record append CASE_ID --input - < record.json
 ```
 
-Explicit command-line options override fields from `--input`. Mutations generate
-an idempotency key unless `--idempotency-key` or an `idempotencyKey` in input is
-provided.
+Explicit flags override fields supplied through `--input`. Mutations create an idempotency key automatically unless you provide `--idempotency-key` or `idempotencyKey` in the input.
 
-### Authentication and configuration
+## Authentication and configuration
 
-Interactive login uses OAuth 2.0 Authorization Code with PKCE. Email login
-automatically selects organization SSO or a terminal email-code flow.
+`epismo login` opens a browser-based OAuth login. With `--email`, it automatically uses your organization SSO when available, otherwise it prompts for an email code.
 
-For CI, issue a token and set it as an environment variable:
+For CI or other non-interactive use, create a workspace-scoped token and pass it with `EPISMO_TOKEN`:
 
 ```sh
 epismo token create --workspace-id WORKSPACE_ID
 EPISMO_TOKEN=... epismo playbook search
 ```
 
-Configuration remains compatible with the original npm CLI and is stored under
-`~/.epismo`. Set `EPISMO_CONFIG_DIR` to use another location. For local API
-development, set `APP_ENV=dev`, or override endpoints directly with
-`EPISMO_API_URL` and `EPISMO_WEB_URL`.
+Configuration is stored in `~/.epismo` (compatible with the original npm CLI). Set `EPISMO_CONFIG_DIR` to use a different directory. For local API development, set `APP_ENV=dev`, or override `EPISMO_API_URL` and `EPISMO_WEB_URL`.
 
 ## API contract
 
-The versioned OpenAPI 3.1 contract used by the CLI is checked in at
-`contracts/openapi.json` as a generated snapshot of the public contract served
-at `https://api.epismo.ai/openapi.json`. After deploying an API change, refresh
-the snapshot with `sh scripts/sync-openapi.sh`; do not edit it manually. Its
-`info.version` identifies the API compatibility generation (`1.0.0` for `/v1`)
-and is independent of the CLI release version. Contract tests verify that every
-remote CLI command uses a documented operation and that its query options remain
-compatible with the API. Releases run the same compatibility checks against the
-deployed contract before publishing.
+[`contracts/openapi.json`](contracts/openapi.json) is a generated snapshot of Epismo's public OpenAPI 3.1 contract. Refresh it after an API deployment:
+
+```sh
+sh scripts/sync-openapi.sh
+```
+
+Do not edit the snapshot manually. Its `info.version` represents API compatibility (for example, `1.0.0` for `/v1`), not the CLI release version. Contract tests ensure remote commands and query options remain compatible with the API.
 
 ## Develop
 
-The runtime uses only the Go standard library.
+The CLI runtime uses only the Go standard library.
 
 ```sh
 go test -race ./...
@@ -112,11 +104,8 @@ go vet ./...
 go build ./cmd/epismo
 ```
 
-Releases are built for macOS, Linux, and Windows from semantic-version tags such
-as `v1.3.1`. The tag is the sole source of the release version: the workflow
-injects it into Go binaries and sets the npm package version immediately before
-publishing. The development `package.json` version is intentionally not bumped.
+Releases are built for macOS, Linux, and Windows from semantic-version tags such as `v1.3.1`. The tag is the release version source; the development `package.json` version is intentionally not updated.
 
 ## License
 
-Apache License 2.0.
+[Apache License 2.0](LICENSE).

package/npm/bin/epismo.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+import { launch } from "../launcher.js";
+
+try {
+  launch();
+} catch (error) {
+  console.error(`epismo: ${error.message}`);
+  process.exitCode = 1;
+}

package/npm/launcher.js

@@ -0,0 +1,104 @@
+import { spawn } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, join, parse, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+export function targetFor(platform = process.platform, architecture = process.arch) {
+  const os = { darwin: "darwin", linux: "linux", win32: "windows" }[platform];
+  const arch = { x64: "amd64", arm64: "arm64" }[architecture];
+  return os && arch ? `${os}-${arch}` : null;
+}
+
+export function binaryFor(platform = process.platform, architecture = process.arch, root = packageRoot) {
+  const target = targetFor(platform, architecture);
+  if (!target) return null;
+  return join(root, "npm", "vendor", target, platform === "win32" ? "epismo.exe" : "epismo");
+}
+
+export function detectPackageManager({
+  root = packageRoot,
+  entrypoint = process.argv[1] || "",
+  userAgent = process.env.npm_config_user_agent || "",
+  execPath = process.env.npm_execpath || ""
+} = {}) {
+  if (pnpmOwnsPackage(root, entrypoint)) return { name: "pnpm", version: versionFromUserAgent(userAgent, "pnpm") };
+  const normalizedRoot = root.toLowerCase().replaceAll("\\", "/");
+  if (/\bbun\//i.test(userAgent) || /(?:^|[\\/])bun(?:\.exe)?$/i.test(execPath) || normalizedRoot.includes("/.bun/install/global/")) {
+    return { name: "bun", version: versionFromUserAgent(userAgent, "bun") };
+  }
+  if (/\byarn\//i.test(userAgent) || /(?:^|[\\/])yarn(?:\.c?js|\.cmd)?$/i.test(execPath) || normalizedRoot.includes("/.config/yarn/global/")) {
+    return { name: "yarn", version: versionFromUserAgent(userAgent, "yarn") || "1" };
+  }
+  return { name: "npm", version: versionFromUserAgent(userAgent, "npm") };
+}
+
+export function installationScope(environment = process.env) {
+  return environment.npm_command === "exec" || environment.npm_lifecycle_event === "npx" ? "ephemeral" : "global";
+}
+
+export function launch() {
+  const binary = binaryFor();
+  if (!binary) {
+    throw new Error(`Unsupported platform: ${process.platform}-${process.arch}`);
+  }
+  if (!existsSync(binary)) {
+    throw new Error(`Epismo native binary is missing for ${process.platform}-${process.arch}. Reinstall the epismo package.`);
+  }
+  const manager = detectPackageManager();
+  const env = {
+    ...process.env,
+    EPISMO_DISTRIBUTION: "node",
+    EPISMO_NODE_MANAGER: manager.name,
+    EPISMO_NODE_MANAGER_VERSION: manager.version || "",
+    EPISMO_NODE_SCOPE: installationScope()
+  };
+  const child = spawn(binary, process.argv.slice(2), { stdio: "inherit", env });
+  const signalHandlers = new Map();
+  const removeSignalHandlers = () => {
+    for (const [signal, handler] of signalHandlers) process.off(signal, handler);
+  };
+  child.on("error", (error) => {
+    removeSignalHandlers();
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+    const handler = () => {
+      if (!child.killed) child.kill(signal);
+    };
+    signalHandlers.set(signal, handler);
+    process.on(signal, handler);
+  }
+  child.on("exit", (code, signal) => {
+    removeSignalHandlers();
+    if (signal && process.platform !== "win32") {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exitCode = code ?? 1;
+  });
+}
+
+function versionFromUserAgent(userAgent, manager) {
+  return userAgent.match(new RegExp(`(?:^|\\s)${manager}/([^\\s]+)`, "i"))?.[1] || "";
+}
+
+function pnpmOwnsPackage(root, entrypoint) {
+  for (const start of new Set([root, dirname(resolve(entrypoint || root))])) {
+    const filesystemRoot = parse(start).root;
+    for (let current = start; ; current = dirname(current)) {
+      const nodeModules = join(current, "node_modules");
+      if (existsSync(join(nodeModules, ".modules.yaml"))) {
+        try {
+          if (realpathSync(join(nodeModules, "epismo")) === realpathSync(root)) return true;
+        } catch {
+          // Keep looking for the owning pnpm node_modules directory.
+        }
+      }
+      if (current === filesystemRoot) break;
+    }
+  }
+  return false;
+}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "epismo",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Dependency-free CLI for discovering, authoring, and coordinating reusable AI Playbooks.",
   "type": "module",
   "license": "Apache-2.0",
-  "homepage": "https://github.com/epismoai/cli",
+  "homepage": "https://epismo.ai",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/epismoai/cli.git"
@@ -17,16 +17,25 @@
     "agent",
     "cli"
   ],
+  "engines": {
+    "node": ">=18"
+  },
   "bin": {
-    "epismo": "npm/bin/epismo.exe"
+    "epismo": "npm/bin/epismo.js"
   },
   "files": [
-    "npm/bin/epismo.exe",
-    "npm/install.js",
+    "npm/bin/epismo.js",
+    "npm/launcher.js",
+    "npm/vendor/darwin-amd64/epismo",
+    "npm/vendor/darwin-arm64/epismo",
+    "npm/vendor/linux-amd64/epismo",
+    "npm/vendor/linux-arm64/epismo",
+    "npm/vendor/windows-amd64/epismo.exe",
+    "npm/vendor/windows-arm64/epismo.exe",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "postinstall": "node npm/install.js"
+    "test": "node --test npm/launcher.test.js"
   }
 }

package/npm/bin/epismo.exe

@@ -1 +0,0 @@
-Epismo native binary placeholder. The npm postinstall script replaces this file.

package/npm/install.js

@@ -1,82 +0,0 @@
-import { createHash } from "node:crypto";
-import { chmod, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { get } from "node:https";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const repository = "epismoai/cli";
-const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
-const target = join(packageRoot, "npm", "bin", "epismo.exe");
-const packageJson = JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8"));
-const version = packageJson.version;
-if (version === "0.0.0-development") {
-  console.log("Skipping Epismo binary download for a development checkout.");
-  process.exit(0);
-}
-if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
-  throw new Error(`Invalid published package version: ${JSON.stringify(version)}`);
-}
-
-const platform = { darwin: "darwin", linux: "linux", win32: "windows" }[process.platform];
-const architecture = { x64: "amd64", arm64: "arm64" }[process.arch];
-if (!platform || !architecture) {
-  throw new Error(`Unsupported platform: ${process.platform}-${process.arch}`);
-}
-
-const extension = platform === "windows" ? ".exe" : "";
-const asset = `epismo_${platform}_${architecture}${extension}`;
-const releaseBase = process.env.EPISMO_RELEASE_BASE_URL || `https://github.com/${repository}/releases/download/v${version}`;
-const [binary, checksumFile] = await Promise.all([
-  download(`${releaseBase}/${asset}`),
-  download(`${releaseBase}/checksums.txt`)
-]);
-
-const expected = checksumFile
-  .toString("utf8")
-  .split(/\r?\n/)
-  .map((line) => line.trim().split(/\s+/))
-  .find((parts) => parts[1] === asset)?.[0];
-if (!expected) {
-  throw new Error(`Checksum not found for ${asset}`);
-}
-const actual = createHash("sha256").update(binary).digest("hex");
-if (actual !== expected.toLowerCase()) {
-  throw new Error(`Checksum verification failed for ${asset}`);
-}
-
-const temporary = `${target}.${process.pid}.tmp`;
-await writeFile(temporary, binary, { mode: 0o755 });
-await chmod(temporary, 0o755).catch(() => {});
-await rm(target, { force: true });
-await rename(temporary, target);
-
-function download(url, redirects = 0) {
-  if (redirects > 5) {
-    return Promise.reject(new Error(`Too many redirects while downloading ${url}`));
-  }
-  return new Promise((resolve, reject) => {
-    const request = get(url, { headers: { "user-agent": `epismo-npm/${version}` } }, (response) => {
-      if (response.statusCode && response.statusCode >= 300 && response.statusCode < 400) {
-        const location = response.headers.location;
-        response.resume();
-        if (!location) {
-          reject(new Error(`Redirect without Location from ${url}`));
-          return;
-        }
-        resolve(download(new URL(location, url).toString(), redirects + 1));
-        return;
-      }
-      if (response.statusCode !== 200) {
-        response.resume();
-        reject(new Error(`Download failed (${response.statusCode}) for ${url}`));
-        return;
-      }
-      const chunks = [];
-      response.on("data", (chunk) => chunks.push(chunk));
-      response.on("end", () => resolve(Buffer.concat(chunks)));
-      response.on("error", reject);
-    });
-    request.setTimeout(30_000, () => request.destroy(new Error(`Download timed out: ${url}`)));
-    request.on("error", reject);
-  });
-}