@cantinasecurity/apex-cli 0.1.0

package/dist/update.js

@@ -0,0 +1,462 @@
+import { execFile as execFileCallback, spawn } from "node:child_process";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { isJsonMode, isNonInteractive } from "./args.js";
+import { logLine, printJson } from "./output.js";
+import { confirm } from "./prompt.js";
+const CHECK_INTERVAL_MS = 6 * 60 * 60 * 1000;
+const PROMPT_COOLDOWN_MS = 12 * 60 * 60 * 1000;
+const PACKAGE_NAME = "@cantinasecurity/apex-cli";
+const REPO_SPEC = PACKAGE_NAME;
+const NPM_PACKAGE_URL = `https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME)}/latest`;
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const UPDATE_STATE_PATH = path.join(os.homedir(), ".config", "apex", "update-check.json");
+const execFile = promisify(execFileCallback);
+function quoteShellArg(value) {
+    return /[^A-Za-z0-9_./:-]/.test(value)
+        ? `'${value.replace(/'/g, `'\\''`)}'`
+        : value;
+}
+function shortSha(value) {
+    return value ? value.slice(0, 7) : null;
+}
+async function pathExists(targetPath) {
+    try {
+        await stat(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readTextFile(filePath) {
+    try {
+        return await readFile(filePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+async function readPackageVersion(packageRoot) {
+    const raw = await readTextFile(path.join(packageRoot, "package.json"));
+    if (!raw) {
+        throw new Error("Unable to read Apex CLI package.json");
+    }
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.version !== "string" || parsed.version.trim().length === 0) {
+        throw new Error("Apex CLI package.json does not include a version");
+    }
+    return parsed.version.trim();
+}
+async function execText(command, args, cwd) {
+    const result = await execFile(command, args, {
+        cwd,
+        encoding: "utf8",
+    });
+    return {
+        stdout: result.stdout.trim(),
+        stderr: result.stderr.trim(),
+    };
+}
+async function tryExecText(command, args, cwd) {
+    try {
+        return await execText(command, args, cwd);
+    }
+    catch {
+        return null;
+    }
+}
+async function detectProjectPackageManager(packageRoot) {
+    if (await pathExists(path.join(packageRoot, "pnpm-lock.yaml"))) {
+        return {
+            command: "pnpm",
+            args: ["install"],
+            label: "pnpm install",
+        };
+    }
+    if (await pathExists(path.join(packageRoot, "package-lock.json"))) {
+        return {
+            command: "npm",
+            args: ["install"],
+            label: "npm install",
+        };
+    }
+    if (await pathExists(path.join(packageRoot, "yarn.lock"))) {
+        return {
+            command: "yarn",
+            args: ["install"],
+            label: "yarn install",
+        };
+    }
+    return null;
+}
+async function detectGlobalInstaller() {
+    if (await tryExecText("pnpm", ["--version"])) {
+        return {
+            command: "pnpm",
+            args: ["add", "-g", REPO_SPEC],
+            label: `pnpm add -g ${REPO_SPEC}`,
+        };
+    }
+    if (await tryExecText("npm", ["--version"])) {
+        return {
+            command: "npm",
+            args: ["install", "-g", REPO_SPEC],
+            label: `npm install -g ${REPO_SPEC}`,
+        };
+    }
+    return {
+        command: "pnpm",
+        args: ["add", "-g", REPO_SPEC],
+        label: `pnpm add -g ${REPO_SPEC}`,
+    };
+}
+async function resolveInstallContext(packageRoot = PACKAGE_ROOT) {
+    const currentVersion = await readPackageVersion(packageRoot);
+    const gitDirExists = await pathExists(path.join(packageRoot, ".git"));
+    if (gitDirExists) {
+        const head = await tryExecText("git", ["rev-parse", "HEAD"], packageRoot);
+        if (head?.stdout) {
+            const upstream = await tryExecText("git", ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"], packageRoot);
+            const packageManager = await detectProjectPackageManager(packageRoot);
+            const updateCommands = [
+                {
+                    command: "git",
+                    args: ["pull", "--ff-only"],
+                    cwd: packageRoot,
+                },
+            ];
+            const display = [`git -C ${quoteShellArg(packageRoot)} pull --ff-only`];
+            if (packageManager) {
+                updateCommands.push({
+                    command: packageManager.command,
+                    args: packageManager.args,
+                    cwd: packageRoot,
+                });
+                display.push(packageManager.label);
+            }
+            return {
+                packageRoot,
+                currentVersion,
+                currentRevision: head.stdout,
+                installKind: "git-checkout",
+                upstreamRef: upstream?.stdout ?? null,
+                updateCommands,
+                updateCommand: display.join(" && "),
+            };
+        }
+    }
+    const installer = await detectGlobalInstaller();
+    return {
+        packageRoot,
+        currentVersion,
+        currentRevision: null,
+        installKind: "package-install",
+        upstreamRef: null,
+        updateCommands: [
+            {
+                command: installer.command,
+                args: installer.args,
+            },
+        ],
+        updateCommand: installer.label,
+    };
+}
+async function loadUpdateState() {
+    const raw = await readTextFile(UPDATE_STATE_PATH);
+    if (!raw) {
+        return { version: 1 };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return {
+            version: 1,
+            installKind: parsed.installKind,
+            upstreamRef: parsed.upstreamRef ?? null,
+            lastCheckedAt: parsed.lastCheckedAt ?? null,
+            latestRevision: parsed.latestRevision ?? null,
+            latestVersion: parsed.latestVersion ?? null,
+            lastPromptedAt: parsed.lastPromptedAt ?? null,
+            lastPromptedRevision: parsed.lastPromptedRevision ?? null,
+            lastPromptedVersion: parsed.lastPromptedVersion ?? null,
+        };
+    }
+    catch {
+        return { version: 1 };
+    }
+}
+async function saveUpdateState(state) {
+    await mkdir(path.dirname(UPDATE_STATE_PATH), { recursive: true, mode: 0o700 });
+    await writeFile(UPDATE_STATE_PATH, `${JSON.stringify(state, null, 2)}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+}
+function canReuseCachedRemote(state, context, now = Date.now()) {
+    if (!state.lastCheckedAt) {
+        return false;
+    }
+    const checkedAt = Date.parse(state.lastCheckedAt);
+    if (!Number.isFinite(checkedAt) || now - checkedAt > CHECK_INTERVAL_MS) {
+        return false;
+    }
+    return (state.installKind === context.installKind &&
+        (state.upstreamRef ?? null) === context.upstreamRef);
+}
+async function fetchLatestPublishedVersion() {
+    const response = await fetch(NPM_PACKAGE_URL, {
+        headers: {
+            "User-Agent": "apex-cli",
+            Accept: "application/json",
+        },
+    });
+    if (!response.ok) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(await response.text());
+        return typeof parsed.version === "string" && parsed.version.trim().length > 0
+            ? parsed.version.trim()
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function fetchRemoteUpdateInfo(context) {
+    if (context.installKind === "git-checkout" && context.upstreamRef) {
+        const [remoteName, ...branchParts] = context.upstreamRef.split("/");
+        const branchName = branchParts.join("/");
+        if (!remoteName || !branchName) {
+            return null;
+        }
+        const remote = await execText("git", ["ls-remote", "--exit-code", remoteName, `refs/heads/${branchName}`], context.packageRoot);
+        const latestRevision = remote.stdout.split(/\s+/)[0] ?? null;
+        return {
+            latestRevision,
+            latestVersion: null,
+            checkedAt: new Date().toISOString(),
+        };
+    }
+    const latestVersion = await fetchLatestPublishedVersion();
+    if (!latestVersion) {
+        return null;
+    }
+    return {
+        latestVersion,
+        latestRevision: null,
+        checkedAt: new Date().toISOString(),
+    };
+}
+export function compareVersions(left, right) {
+    const leftParts = left.split(".").map((part) => Number.parseInt(part, 10) || 0);
+    const rightParts = right.split(".").map((part) => Number.parseInt(part, 10) || 0);
+    const maxLength = Math.max(leftParts.length, rightParts.length);
+    for (let index = 0; index < maxLength; index += 1) {
+        const leftValue = leftParts[index] ?? 0;
+        const rightValue = rightParts[index] ?? 0;
+        if (leftValue < rightValue) {
+            return -1;
+        }
+        if (leftValue > rightValue) {
+            return 1;
+        }
+    }
+    return 0;
+}
+function hasAvailableUpdate(context, remote) {
+    if (!remote) {
+        return false;
+    }
+    if (context.currentRevision && remote.latestRevision) {
+        return context.currentRevision !== remote.latestRevision;
+    }
+    if (remote.latestVersion) {
+        return compareVersions(context.currentVersion, remote.latestVersion) < 0;
+    }
+    return false;
+}
+async function getRemoteUpdateInfo(context, forceRefresh = false) {
+    const state = await loadUpdateState();
+    if (!forceRefresh && canReuseCachedRemote(state, context)) {
+        return {
+            latestRevision: state.latestRevision ?? null,
+            latestVersion: state.latestVersion ?? null,
+            checkedAt: state.lastCheckedAt ?? new Date().toISOString(),
+        };
+    }
+    const remote = await fetchRemoteUpdateInfo(context).catch(() => null);
+    if (!remote) {
+        return null;
+    }
+    await saveUpdateState({
+        ...state,
+        version: 1,
+        installKind: context.installKind,
+        upstreamRef: context.upstreamRef,
+        lastCheckedAt: remote.checkedAt,
+        latestRevision: remote.latestRevision,
+        latestVersion: remote.latestVersion,
+    });
+    return remote;
+}
+export async function getUpdateStatus(packageRoot = PACKAGE_ROOT, forceRefresh = false) {
+    const context = await resolveInstallContext(packageRoot);
+    const remote = await getRemoteUpdateInfo(context, forceRefresh);
+    return {
+        installKind: context.installKind,
+        currentVersion: context.currentVersion,
+        currentRevision: context.currentRevision,
+        latestVersion: remote?.latestVersion ?? null,
+        latestRevision: remote?.latestRevision ?? null,
+        available: hasAvailableUpdate(context, remote),
+        updateCommand: context.updateCommand,
+        updated: false,
+    };
+}
+async function ensureCleanGitCheckout(context) {
+    if (context.installKind !== "git-checkout") {
+        return;
+    }
+    if (!context.upstreamRef) {
+        throw new Error("This Apex CLI checkout does not track a remote branch yet. Configure an upstream before running `apex update`.");
+    }
+    const status = await execText("git", ["status", "--porcelain"], context.packageRoot);
+    if (status.stdout.length > 0) {
+        throw new Error("The Apex CLI checkout has uncommitted changes. Commit or stash them before running `apex update`.");
+    }
+}
+function runInteractiveCommand(command, args, cwd) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd,
+            stdio: "inherit",
+        });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new Error(`Command failed (${code ?? "unknown"}): ${command} ${args.join(" ")}`));
+        });
+    });
+}
+function shouldPromptForUpdate(state, status, now = Date.now()) {
+    if (!status.available) {
+        return false;
+    }
+    if (!state.lastPromptedAt) {
+        return true;
+    }
+    const lastPromptedAt = Date.parse(state.lastPromptedAt);
+    if (!Number.isFinite(lastPromptedAt) || now - lastPromptedAt > PROMPT_COOLDOWN_MS) {
+        return true;
+    }
+    if (status.latestRevision && state.lastPromptedRevision !== status.latestRevision) {
+        return true;
+    }
+    if (status.latestVersion && state.lastPromptedVersion !== status.latestVersion) {
+        return true;
+    }
+    return false;
+}
+function canPromptForUpdate(flags, command) {
+    if (isJsonMode(flags) || isNonInteractive(flags)) {
+        return false;
+    }
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        return false;
+    }
+    return !["help", "update"].includes(command ?? "");
+}
+function formatUpdateSummary(status) {
+    const currentRevision = shortSha(status.currentRevision);
+    const latestRevision = shortSha(status.latestRevision);
+    if (currentRevision && latestRevision) {
+        return `${currentRevision} -> ${latestRevision}`;
+    }
+    if (status.latestVersion) {
+        return `${status.currentVersion} -> ${status.latestVersion}`;
+    }
+    return status.currentVersion;
+}
+export async function maybePromptForUpdate(flags, command) {
+    if (!canPromptForUpdate(flags, command)) {
+        return false;
+    }
+    const status = await getUpdateStatus().catch(() => null);
+    if (!status?.available || !status.updateCommand) {
+        return false;
+    }
+    const state = await loadUpdateState();
+    if (!shouldPromptForUpdate(state, status)) {
+        return false;
+    }
+    const promptText = `Apex CLI update available (${formatUpdateSummary(status)}). Install now?`;
+    const approved = await confirm(promptText, true);
+    await saveUpdateState({
+        ...state,
+        version: 1,
+        installKind: status.installKind,
+        lastPromptedAt: new Date().toISOString(),
+        lastPromptedRevision: status.latestRevision,
+        lastPromptedVersion: status.latestVersion,
+    });
+    if (!approved) {
+        if (!isJsonMode(flags)) {
+            process.stderr.write(`Update command: ${status.updateCommand}\n`);
+        }
+        return false;
+    }
+    await commandUpdate(flags);
+    return true;
+}
+export async function commandUpdate(flags, packageRoot = PACKAGE_ROOT) {
+    const context = await resolveInstallContext(packageRoot);
+    if (context.installKind === "git-checkout" && !context.upstreamRef) {
+        throw new Error("This Apex CLI checkout does not track a remote branch yet. Configure an upstream before running `apex update`.");
+    }
+    const status = await getUpdateStatus(packageRoot, true);
+    if (!status.available) {
+        if (isJsonMode(flags)) {
+            printJson(status);
+        }
+        else {
+            logLine("Apex CLI is already up to date.", flags);
+        }
+        return status;
+    }
+    if (!context.updateCommand || context.updateCommands.length === 0) {
+        throw new Error("No update command is available for this Apex CLI installation.");
+    }
+    await ensureCleanGitCheckout(context);
+    if (!isJsonMode(flags)) {
+        logLine(`Updating Apex CLI with ${context.updateCommand}`, flags);
+    }
+    for (const step of context.updateCommands) {
+        await runInteractiveCommand(step.command, step.args, step.cwd);
+    }
+    const payload = context.installKind === "git-checkout"
+        ? {
+            ...(await getUpdateStatus(packageRoot, true)),
+            updated: true,
+        }
+        : {
+            ...status,
+            currentVersion: status.latestVersion ?? status.currentVersion,
+            currentRevision: status.latestRevision ?? status.currentRevision,
+            available: false,
+            updated: true,
+        };
+    if (isJsonMode(flags)) {
+        printJson(payload);
+    }
+    else {
+        logLine("Apex CLI updated. Re-run `apex` to use the latest version. Re-run `apex setup` to refresh copied Codex or Claude skill files.", flags);
+    }
+    return payload;
+}

package/dist/version.js

@@ -0,0 +1,7 @@
+import { readFileSync } from "node:fs";
+const packageJsonUrl = new URL("../package.json", import.meta.url);
+const packageJson = JSON.parse(readFileSync(packageJsonUrl, "utf8"));
+if (typeof packageJson.version !== "string" || packageJson.version.trim().length === 0) {
+    throw new Error("Apex CLI package.json does not include a version");
+}
+export const APEX_CLI_VERSION = packageJson.version.trim();

package/dist/workspace-binding.js

@@ -0,0 +1,30 @@
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+function getWorkspaceDir(cwd) {
+    return path.join(cwd, ".apex");
+}
+function getWorkspaceBindingPath(cwd) {
+    return path.join(getWorkspaceDir(cwd), "workspace.json");
+}
+export async function loadWorkspaceBinding(cwd) {
+    try {
+        const contents = await readFile(getWorkspaceBindingPath(cwd), "utf8");
+        return JSON.parse(contents);
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveWorkspaceBinding(cwd, binding) {
+    const workspaceDir = getWorkspaceDir(cwd);
+    const bindingPath = getWorkspaceBindingPath(cwd);
+    await mkdir(workspaceDir, { recursive: true, mode: 0o700 });
+    await writeFile(bindingPath, `${JSON.stringify(binding, null, 2)}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    await chmod(bindingPath, 0o600);
+}
+export async function clearWorkspaceBinding(cwd) {
+    await rm(getWorkspaceBindingPath(cwd), { force: true });
+}

package/dist/workspaces.js

@@ -0,0 +1,50 @@
+export async function fetchCompanyCredits(client, companyId) {
+    return client.request(`/api/cli/v1/companies/${encodeURIComponent(companyId)}/credits`);
+}
+export async function fetchCompanyWorkspaces(client, companyId) {
+    return client.request(`/api/cli/v1/companies/${encodeURIComponent(companyId)}/workspaces`);
+}
+function normalizeWorkspaceRef(ref) {
+    return ref.trim().toLowerCase();
+}
+export function findWorkspaceByRef(workspaces, ref) {
+    const normalizedRef = normalizeWorkspaceRef(ref);
+    if (!normalizedRef) {
+        return null;
+    }
+    const exactMatches = workspaces.filter((workspace) => {
+        const workspaceName = normalizeWorkspaceRef(workspace.name);
+        const workspacePrefix = normalizeWorkspaceRef(workspace.prefix ?? "");
+        return (normalizeWorkspaceRef(workspace.workspaceId) === normalizedRef ||
+            workspaceName === normalizedRef ||
+            (workspacePrefix.length > 0 && workspacePrefix === normalizedRef));
+    });
+    if (exactMatches.length === 1) {
+        return exactMatches[0];
+    }
+    if (exactMatches.length > 1) {
+        return null;
+    }
+    const prefixMatches = workspaces.filter((workspace) => {
+        const workspaceName = normalizeWorkspaceRef(workspace.name);
+        const workspacePrefix = normalizeWorkspaceRef(workspace.prefix ?? "");
+        return (workspaceName.startsWith(normalizedRef) ||
+            (workspacePrefix.length > 0 && workspacePrefix.startsWith(normalizedRef)));
+    });
+    return prefixMatches.length === 1 ? prefixMatches[0] : null;
+}
+export function createWorkspaceBindingFromSummary(params) {
+    const isSameWorkspace = params.currentBinding?.workspaceId === params.workspace.workspaceId;
+    return {
+        version: 1,
+        companyId: params.companyId,
+        workspaceId: params.workspace.workspaceId,
+        workspaceName: params.workspace.name,
+        createdAt: isSameWorkspace && params.currentBinding?.createdAt
+            ? params.currentBinding.createdAt
+            : new Date().toISOString(),
+        lastSyncedAt: new Date().toISOString(),
+        lastScanId: isSameWorkspace ? params.currentBinding?.lastScanId ?? null : null,
+        lastScanUrl: isSameWorkspace ? params.currentBinding?.lastScanUrl ?? null : null,
+    };
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@cantinasecurity/apex-cli",
+  "version": "0.1.0",
+  "description": "Standalone CLI and MCP server for Apex.",
+  "private": false,
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "apex": "./pkg-bin/apex.js",
+    "apex-mcp": "./pkg-bin/apex-mcp.js"
+  },
+  "files": [
+    "dist",
+    "pkg-bin",
+    "skills",
+    ".claude/skills",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "ignore": "^7.0.5",
+    "tar": "^7.4.3",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.18.6",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.9"
+  },
+  "scripts": {
+    "apex": "tsx src/apex.ts",
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json",
+    "mcp": "tsx src/mcp-main.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/pkg-bin/apex-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/mcp-main.js";

package/pkg-bin/apex.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/apex.js";

package/skills/apex-cli/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: apex-cli
+description: Use when a user wants to start Apex scans, inspect findings, bind workspaces, check scan status, or troubleshoot Apex auth/provider setup through the Apex MCP server instead of shelling out manually.
+---
+
+# Apex CLI
+
+This skill is bundled with Apex CLI and can be installed into Codex with `apex setup codex`.
+
+Prefer the Apex MCP tools over running `apex` in the shell when the server is available.
+
+Workflow:
+
+1. Start with `apex-auth-status`.
+2. If Apex is unauthenticated, call `apex-auth-start`, ask the user to approve the device-login URL, then call `apex-auth-wait` with the returned `deviceCode`.
+3. For repository work, pass `cwd` explicitly.
+4. Call `apex-doctor` before starting a scan if workspace binding or source planning might be unclear.
+5. If the directory is not bound to the right workspace, call `apex-workspaces` and `apex-workspace-use`.
+6. Use `apex-scan`, `apex-status`, `apex-scans`, `apex-findings`, and `apex-export-findings` for the scan lifecycle.
+
+Guidelines:
+
+- Do not rely on interactive CLI prompts. The MCP tools are intentionally non-interactive.
+- `apex-doctor` reports whether Apex will use remote materialization or a local snapshot upload for each selected source.
+- Apex can scan plain local directories and dirty git worktrees without provider connections by using local snapshot uploads.
+- `apex-workspace-use` accepts a workspace name, prefix, or ID.
+- Use `sourceMode: "remote"` only when the user explicitly wants to forbid local snapshot fallbacks.
+- Use `force: true` on `apex-scan` only when the user explicitly wants to replace or overlap an active scan.
+- Prefer `apex-findings` for quick inspection and `apex-export-findings` when the user needs a file artifact.