@cantinasecurity/apex-cli 0.1.0

package/dist/findings.js

@@ -0,0 +1,50 @@
+import { fetchWorkspaceScans, getScanDisplayId, matchesScanId, } from "./scan.js";
+function parsePositiveInt(value) {
+    if (!value)
+        return null;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        return null;
+    }
+    return Math.floor(parsed);
+}
+export async function fetchScanFindings(client, scanId, limit) {
+    const params = new URLSearchParams();
+    const parsedLimit = parsePositiveInt(limit);
+    if (parsedLimit !== null) {
+        params.set("limit", String(parsedLimit));
+    }
+    const suffix = params.toString();
+    return client.request(`/api/cli/v1/scans/${encodeURIComponent(scanId)}/findings${suffix ? `?${suffix}` : ""}`);
+}
+export async function fetchScanExport(client, scanId, format) {
+    const params = new URLSearchParams();
+    if (format.trim().length > 0) {
+        params.set("format", format.trim());
+    }
+    return client.request(`/api/cli/v1/scans/${encodeURIComponent(scanId)}/export?${params.toString()}`);
+}
+export async function resolveScanSelection(params) {
+    const scans = await fetchWorkspaceScans(params.client, params.binding.workspaceId);
+    if (scans.length === 0) {
+        throw new Error("No scans are available for this workspace.");
+    }
+    const requested = params.requestedScanId?.trim() ?? "";
+    if (requested.length > 0) {
+        const matched = scans.find((scan) => matchesScanId(scan, requested));
+        if (!matched) {
+            throw new Error(`Unknown scan: ${requested}`);
+        }
+        return matched;
+    }
+    if (params.binding.lastScanId) {
+        const tracked = scans.find((scan) => matchesScanId(scan, params.binding.lastScanId ?? ""));
+        if (tracked) {
+            return tracked;
+        }
+    }
+    return scans[0];
+}
+export function describeScanSelection(scan) {
+    return scan.scanUrl ?? getScanDisplayId(scan);
+}

package/dist/help.js

@@ -0,0 +1,75 @@
+export const CLI_HELP_TEXT = `Usage:
+  apex                              Open the interactive Apex shell
+  apex credits                      Show scan credits for the active company
+  apex scan                         Create or resolve a workspace for this directory and start a scan
+  apex scans                        List scans for the current workspace binding
+  apex findings                     List findings for the latest or selected scan
+  apex export findings              Export findings for the latest or selected scan
+  apex workspaces                   List accessible workspaces for the active company
+  apex workspace                    Show the workspace currently bound to this directory
+  apex workspace use <workspace-name|workspace-prefix|workspace-id>
+                                    Bind this directory to an existing Apex workspace
+  apex cancel-scan [scan-id]        Cancel a running scan
+  apex status                       Show the latest scan progress for this directory
+  apex doctor                       Validate auth, repos, connections, and workspace binding
+  apex login                        Sign in to Apex
+  apex logout                       Sign out locally
+  apex mcp                          Start the Apex MCP server over stdio
+  apex setup [all|codex|claude]     Configure Apex for Codex and Claude Code
+  apex update                       Update the local Apex CLI install
+  apex connect github               Open the GitHub connection flow
+  apex connect gitlab               Open the GitLab connection flow
+
+Flags:
+  --company <id-or-handle>          Choose the Apex company to use
+  --workspace-name <name>           Set the Apex workspace name for this directory
+  --scan <scan-id>                  Select a specific scan for findings or export
+  --format markdown|json|gitlab-sast
+                                    Choose the export format for findings
+  --output <path>                   Write exported findings to this file path
+  --limit <count>                   Limit the number of findings returned
+  --mode standard|ultra             Choose the scan mode
+  --source-mode auto|remote|local   Control remote-vs-local source materialization
+  --force                           Start a new scan even if another scan is active
+  --repo <path>                     Include one or more explicit local source roots
+  --json                            Print machine-readable JSON output
+  --no-open                         Do not open browser flows automatically
+  --non-interactive                 Disable prompts and browser-dependent UX
+  --help                            Show this help
+
+Tips:
+  apex scan uses the current directory name as the default workspace name unless you pass --workspace-name.
+  apex workspace use accepts a workspace name, prefix, or ID.
+  Quote workspace names that contain spaces:
+    apex workspace use "Core Platform"
+`;
+export const SHELL_HELP_TEXT = `Press Tab to autocomplete commands and common arguments.
+
+Commands:
+  /credits                Show scan credits for the active company
+  /scan [standard|ultra]  Start a new Apex scan for this workspace
+  /scans                  List scans for this workspace
+  /findings [scan-id]     List findings for the latest or selected scan
+  /export [scan-id]       Export findings for the latest or selected scan
+  /workspaces             List accessible workspaces for the active company
+  /cancel-scan [scan-id]  Cancel a running or most recent scan
+  /status                 Show progress for the most recent scan
+  /doctor                 Validate auth, repos, connections, and workspace binding
+  /update                 Update the local Apex CLI install and exit the shell
+  /logout                 Sign out locally and exit the shell
+  /repos                  List detected repositories
+  /workspace              Show the current local workspace binding
+  /workspace use <ref>    Bind this directory to an existing workspace by name, prefix, or ID
+  /workspace name <name>  Update the current workspace name
+  /company [id|handle]    Show or switch the active company
+  /connect github         Connect GitHub access in the browser
+  /connect gitlab         Connect GitLab access in the browser
+  /open                   Open the latest scan or Apex home in the browser
+  /clear                  Clear the terminal
+  /help                   Show this help
+  /exit                   Exit Apex
+
+Tips:
+  /workspace use accepts a workspace name, prefix, or ID.
+  Quote workspace names that contain spaces: /workspace use "Core Platform"
+`;

package/dist/local-source-scan.js

@@ -0,0 +1,304 @@
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { createReadStream } from "node:fs";
+import { lstat, mkdtemp, readFile, readdir, readlink, rm, stat, } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import ignore from "ignore";
+import * as tar from "tar";
+const execFileAsync = promisify(execFile);
+const BUILTIN_IGNORE_PATTERNS = [
+    ".git",
+    ".git/**",
+    "node_modules",
+    "node_modules/**",
+    ".next",
+    ".next/**",
+    "dist",
+    "dist/**",
+    "build",
+    "build/**",
+    "coverage",
+    "coverage/**",
+    ".turbo",
+    ".turbo/**",
+    ".cache",
+    ".cache/**",
+    ".pnpm-store",
+    ".pnpm-store/**",
+    "tmp",
+    "tmp/**",
+];
+const FIXED_MTIME = new Date(0);
+async function runGit(cwd, args) {
+    const { stdout } = await execFileAsync("git", ["-C", cwd, ...args], {
+        encoding: "utf8",
+    });
+    return stdout;
+}
+function buildIgnoreMatcher(rootPath) {
+    const matcher = ignore().add(BUILTIN_IGNORE_PATTERNS);
+    return readFile(path.join(rootPath, ".apexignore"), "utf8")
+        .then((contents) => {
+        matcher.add(contents);
+        return matcher;
+    })
+        .catch(() => matcher);
+}
+function normalizeRelativeEntry(entryPath) {
+    return entryPath.replace(/\\/g, "/").replace(/^\/+/, "").replace(/\/+$/, "");
+}
+function ensureEntryWithinRoot(rootPath, relativePath, targetPath) {
+    if (path.isAbsolute(targetPath)) {
+        throw new Error(`Refusing to archive absolute symlink target in ${relativePath}`);
+    }
+    const resolved = path.resolve(rootPath, path.dirname(relativePath), targetPath);
+    const relative = path.relative(rootPath, resolved);
+    if (!relative || relative === ".")
+        return;
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error(`Refusing to archive path-escaping symlink in ${relativePath}`);
+    }
+}
+async function collectGitEntries(rootPath) {
+    const output = await runGit(rootPath, ["ls-files", "--cached", "--others", "--exclude-standard", "-z"]).catch(() => "");
+    return output
+        .split("\0")
+        .map((entry) => normalizeRelativeEntry(entry))
+        .filter((entry) => entry.length > 0);
+}
+async function collectDirectoryEntries(rootPath) {
+    const entries = [];
+    async function walk(currentPath) {
+        const children = await readdir(currentPath, { withFileTypes: true });
+        for (const child of children) {
+            const childPath = path.join(currentPath, child.name);
+            const relativePath = normalizeRelativeEntry(path.relative(rootPath, childPath));
+            if (!relativePath)
+                continue;
+            if (child.isDirectory()) {
+                entries.push(relativePath);
+                await walk(childPath);
+                continue;
+            }
+            entries.push(relativePath);
+        }
+    }
+    await walk(rootPath);
+    return entries;
+}
+async function collectArchiveEntries(source) {
+    const matcher = await buildIgnoreMatcher(source.absolutePath);
+    const rawEntries = source.kind === "git_candidate"
+        ? await collectGitEntries(source.absolutePath)
+        : await collectDirectoryEntries(source.absolutePath);
+    const fileEntries = new Set();
+    let uncompressedBytes = 0;
+    for (const entry of rawEntries.sort((left, right) => left.localeCompare(right))) {
+        if (!entry)
+            continue;
+        if (matcher.ignores(entry) || matcher.ignores(`${entry}/`))
+            continue;
+        const absoluteEntryPath = path.join(source.absolutePath, entry);
+        const entryStats = await lstat(absoluteEntryPath).catch(() => null);
+        if (!entryStats)
+            continue;
+        if (entryStats.isDirectory()) {
+            continue;
+        }
+        if (entryStats.isSymbolicLink()) {
+            const target = await readlink(absoluteEntryPath);
+            ensureEntryWithinRoot(source.absolutePath, entry, target);
+            fileEntries.add(entry);
+            uncompressedBytes += Buffer.byteLength(target);
+            continue;
+        }
+        if (!entryStats.isFile()) {
+            throw new Error(`Unsupported filesystem entry in source: ${entry}`);
+        }
+        fileEntries.add(entry);
+        uncompressedBytes += entryStats.size;
+    }
+    return {
+        files: Array.from(fileEntries).sort((left, right) => left.localeCompare(right)),
+        uncompressedBytes,
+    };
+}
+async function createArchiveManifest(archivePath) {
+    const hash = createHash("sha256");
+    const stream = createReadStream(archivePath);
+    await new Promise((resolve, reject) => {
+        stream.on("data", (chunk) => hash.update(chunk));
+        stream.on("error", reject);
+        stream.on("end", () => resolve());
+    });
+    const archiveStats = await stat(archivePath);
+    return {
+        sha256: hash.digest("hex"),
+        compressedBytes: archiveStats.size,
+        uncompressedBytes: 0,
+    };
+}
+async function createDeterministicArchive(params) {
+    const { files, uncompressedBytes } = await collectArchiveEntries(params.source);
+    await tar.create({
+        cwd: params.source.absolutePath,
+        file: params.archivePath,
+        gzip: true,
+        portable: true,
+        noPax: true,
+        mtime: FIXED_MTIME,
+        follow: false,
+        preservePaths: false,
+        jobs: 1,
+        sync: false,
+        noDirRecurse: false,
+        onWriteEntry(entry) {
+            entry.mtime = FIXED_MTIME;
+            entry.uid = 0;
+            entry.gid = 0;
+            entry.uname = "root";
+            entry.gname = "root";
+        },
+    }, files);
+    const manifest = await createArchiveManifest(params.archivePath);
+    return {
+        ...manifest,
+        uncompressedBytes,
+    };
+}
+export async function fetchLocalSourceScanCapabilities(client) {
+    return client.request("/api/cli/v2/capabilities");
+}
+export function requiresExplicitSourceFlow(plannedSources) {
+    return plannedSources.some((source) => source.sourceKind === "local_archive" ||
+        (source.sourceKind === "remote_repo" && source.materializationAuth === "public"));
+}
+export function supportsLegacyRemoteFlow(plannedSources) {
+    return plannedSources.every((source) => source.sourceKind === "remote_repo" &&
+        source.materializationAuth !== "public");
+}
+async function uploadArchive(archivePath, uploadUrl, headers) {
+    const response = await fetch(uploadUrl, {
+        method: "PUT",
+        headers,
+        body: createReadStream(archivePath),
+        duplex: "half",
+    });
+    if (!response.ok) {
+        const details = await response.text().catch(() => "");
+        throw new Error(details
+            ? `Archive upload failed: ${details}`
+            : `Archive upload failed with ${response.status}`);
+    }
+}
+export async function prepareExplicitScanSources(args) {
+    const capabilities = await fetchLocalSourceScanCapabilities(args.client);
+    const localSources = args.plannedSources.filter((source) => source.sourceKind === "local_archive");
+    if (args.plannedSources.length > capabilities.archive.maxSourcesPerScan) {
+        throw new Error(`This scan includes ${args.plannedSources.length} sources, but the server limit is ${capabilities.archive.maxSourcesPerScan}.`);
+    }
+    if (localSources.length === 0) {
+        return args.plannedSources.map((source) => source.sourceKind === "remote_repo"
+            ? source
+            : {
+                sourceKind: "local_archive",
+                displayName: source.displayName,
+                relativePath: source.relativePath,
+                archiveId: "",
+                sha256: "",
+                git: source.git,
+            });
+    }
+    const detectedByPath = new Map(args.detectedSources.map((source) => [source.path, source]));
+    const tempDir = await mkdtemp(path.join(tmpdir(), "apex-local-source-"));
+    try {
+        const preparedUploads = [];
+        for (const [index, source] of localSources.entries()) {
+            const detectedSource = detectedByPath.get(source.path);
+            if (!detectedSource) {
+                throw new Error(`Could not resolve local source path: ${source.path}`);
+            }
+            const archivePath = path.join(tempDir, `source-${index + 1}.tar.gz`);
+            const manifest = await createDeterministicArchive({
+                source: detectedSource,
+                archivePath,
+            });
+            if (manifest.compressedBytes > capabilities.archive.maxCompressedBytes) {
+                throw new Error(`Archive for ${source.displayName} exceeds the compressed upload limit.`);
+            }
+            if (manifest.uncompressedBytes > capabilities.archive.maxUncompressedBytes) {
+                throw new Error(`Archive for ${source.displayName} exceeds the uncompressed upload limit.`);
+            }
+            preparedUploads.push({
+                plannedSource: source,
+                archivePath,
+                upload: {
+                    displayName: source.displayName,
+                    relativePath: source.relativePath,
+                    archiveFormat: "tar.gz",
+                    sha256: manifest.sha256,
+                    compressedBytes: manifest.compressedBytes,
+                    uncompressedBytes: manifest.uncompressedBytes,
+                    git: source.git,
+                },
+            });
+        }
+        const uploadSessions = await args.client.request("/api/cli/v2/local-source-uploads", {
+            method: "POST",
+            json: {
+                workspaceId: args.workspaceId,
+                uploads: preparedUploads.map((entry) => entry.upload),
+            },
+        });
+        const archiveIdByRelativePath = new Map();
+        for (const [index, session] of uploadSessions.uploads.entries()) {
+            const prepared = preparedUploads[index];
+            if (!prepared) {
+                throw new Error("Upload session count did not match the prepared archive list.");
+            }
+            let archiveId = session.archiveId ?? "";
+            if (!session.alreadyUploaded) {
+                if (!session.upload?.putUrl) {
+                    throw new Error("Upload session did not include a signed upload URL.");
+                }
+                await uploadArchive(prepared.archivePath, session.upload.putUrl, session.upload.headers ?? {});
+                const completed = await args.client.request(`/api/cli/v2/local-source-uploads/${encodeURIComponent(session.uploadId)}/complete`, {
+                    method: "POST",
+                    json: {
+                        workspaceId: args.workspaceId,
+                    },
+                });
+                archiveId = completed.archiveId;
+            }
+            if (!archiveId) {
+                throw new Error("Upload completed without an archiveId.");
+            }
+            archiveIdByRelativePath.set(prepared.plannedSource.relativePath, {
+                archiveId,
+                sha256: prepared.upload.sha256,
+            });
+        }
+        return args.plannedSources.map((source) => {
+            if (source.sourceKind === "remote_repo") {
+                return source;
+            }
+            const uploaded = archiveIdByRelativePath.get(source.relativePath);
+            if (!uploaded) {
+                throw new Error(`Archive upload did not complete for ${source.displayName}.`);
+            }
+            return {
+                sourceKind: "local_archive",
+                displayName: source.displayName,
+                relativePath: source.relativePath,
+                archiveId: uploaded.archiveId,
+                sha256: uploaded.sha256,
+                git: source.git,
+            };
+        });
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}

package/dist/mcp-main.js

@@ -0,0 +1,10 @@
+import { formatApiError } from "./api-client.js";
+import { runMcpServer } from "./mcp.js";
+export async function runMcpMain() {
+    await runMcpServer();
+}
+export function handleMcpFatalError(error) {
+    process.stderr.write(`${formatApiError(error)}\n`);
+    process.exitCode = 1;
+}
+runMcpMain().catch(handleMcpFatalError);