@cantinasecurity/apex-cli 0.1.36 → 0.1.38

package/dist/session.js

@@ -98,9 +98,16 @@ function selectBindingForWorkspaceName(flags, binding, workspaceName) {
 }
 function getSourceMode(flags) {
     const value = getFlagString(flags, "source-mode");
-    return value === "remote" || value === "local" ? value : "auto";
+    if (value === null || value === "auto")
+        return "auto";
+    if (value === "remote" || value === "local")
+        return value;
+    throw new Error("--source-mode must be auto, remote, or local.");
 }
 function buildFallbackLocalArchivePlan(source, sourceMode) {
+    if (!source.absolutePath) {
+        throw new Error("A remote repository URL cannot use a local snapshot. Connect its provider or clone it locally, then retry.");
+    }
     const reason = sourceMode === "local"
         ? "user_requested_local_snapshot"
         : source.kind === "directory_candidate"
@@ -136,6 +143,11 @@ function buildFallbackLocalArchivePlan(source, sourceMode) {
 }
 function ensurePlannedSources(selection, resolve) {
     if (resolve.plannedSources.length > 0) {
+        for (const source of selection.sources) {
+            if (!source.absolutePath && !resolve.plannedSources.some((plan) => plan.path === source.path && plan.sourceKind === "remote_repo")) {
+                throw new Error("The remote repository is not accessible. Connect its provider or clone it locally, then retry.");
+            }
+        }
         return resolve;
     }
     if (selection.sourceMode === "remote") {
@@ -172,6 +184,9 @@ export async function ensureAuthenticated(client, flags) {
     if (isClaimProofAvailable(credentials)) {
         throw new Error("Your guest trial session is no longer available, but its claim proof is stored on this machine. Run `apex claim` to keep the trial results.");
     }
+    if (!canPromptInteractively(flags)) {
+        throw new Error("Apex is not authenticated. Run `apex login` explicitly, then retry this command.");
+    }
     return login(client, {
         noOpen: flags["no-open"] === true,
         quiet: isJsonMode(flags),
@@ -182,16 +197,21 @@ export async function resolveWorkspace(client, cwd, me, flags) {
     return resolveWorkspaceSelection(client, selection);
 }
 export async function selectWorkspaceTarget(cwd, me, flags) {
+    const sourceMode = getSourceMode(flags);
     const loadedBinding = await loadWorkspaceBinding(cwd);
     const company = await chooseCompany(me, flags, loadedBinding);
-    const workspaceNameSelection = await chooseWorkspaceName(cwd, flags, loadedBinding);
+    const companyBinding = loadedBinding?.companyId === company.id ? loadedBinding : null;
+    const workspaceNameSelection = await chooseWorkspaceName(cwd, flags, companyBinding);
     const workspaceName = workspaceNameSelection.workspaceName;
-    const binding = selectBindingForWorkspaceName(flags, loadedBinding, workspaceName);
+    const binding = selectBindingForWorkspaceName(flags, companyBinding, workspaceName);
     const sourceSelection = getFlagList(flags, "repo");
     const discovered = await discoverSources(cwd, sourceSelection);
     if (discovered.sources.length === 0) {
         throw new Error("No local sources were found.");
     }
+    if (sourceMode === "local" && discovered.sources.some((source) => source.absolutePath === null)) {
+        throw new Error("Remote repository URLs cannot use --source-mode local. Clone the repository locally first.");
+    }
     return {
         company,
         workspaceName,
@@ -199,7 +219,7 @@ export async function selectWorkspaceTarget(cwd, me, flags) {
         binding,
         sources: discovered.sources,
         legacyRepositories: extractLegacyRepositories(discovered.sources),
-        sourceMode: getSourceMode(flags),
+        sourceMode,
     };
 }
 export async function resolveWorkspaceSelection(client, selection) {

package/dist/shell.js

@@ -1,6 +1,6 @@
 import { commandStartThreatModel, hasAuditSetupBeta } from "./threat-model.js";
 import { shellHelpText } from "./help.js";
-import { commandCancelScan, commandClaim, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingTickets, commandFindingLinkTicket, commandFindingSend, commandFindingFeedback, commandFindingFixReview, commandFindings, commandWorkspaceFindings, commandLogout, commandScan, commandScans, commandStatus, commandTelemetry, commandUpdate, commandWorkspace, commandWorkspaceUse, commandWorkspaces, initializeInteractiveSession, openCurrentApexView, } from "./commands.js";
+import { commandCancelScan, commandClaim, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingStatus, commandFindingTickets, commandFindingLinkTicket, commandFindingSend, commandFindingFeedback, commandFindingFixReview, commandFindings, commandWorkspaceFindings, commandLogout, commandScan, commandScans, commandStatus, commandTelemetry, commandUpdate, commandWorkspace, commandWorkspaceUse, commandWorkspaces, initializeInteractiveSession, openCurrentApexView, } from "./commands.js";
 import { withFlag } from "./args.js";
 import { printCompanyDetails, printInteractiveSessionSummary, printSourceList, printWorkspaceDetails, } from "./output.js";
 import { readLine } from "./prompt.js";
@@ -13,7 +13,7 @@ const SHELL_COMPLETIONS = [
     { command: "scans" },
     {
         command: "findings",
-        args: ["workspace", "comment", "feedback", "fix-review", "tickets", "link-ticket", "send"],
+        args: ["workspace", "status", "comment", "feedback", "fix-review", "tickets", "link-ticket", "send"],
     },
     { command: "export" },
     { command: "workspaces" },
@@ -206,11 +206,8 @@ async function runShellCommand(client, cwd, parsed, shellFlags, session) {
             await commandClaim(client, cwd, shellFlags);
             return false;
         case "scan": {
-            const mode = parsed.args[0];
-            if (mode && !["standard", "audit", "ultra", "lite", "pr"].includes(mode)) {
-                process.stderr.write("Usage: /scan [standard|audit|ultra|lite|pr] [pr-number]\n");
-                return {};
-            }
+            const first = parsed.args[0];
+            const mode = first && ["standard", "audit", "ultra", "lite", "pr"].includes(first) ? first : null;
             const prNumber = mode === "pr" ? parsed.args[1] : null;
             if (mode === "pr" && !prNumber) {
                 process.stderr.write("Usage: /scan pr <pr-number>\n");
@@ -220,11 +217,15 @@ async function runShellCommand(client, cwd, parsed, shellFlags, session) {
                 process.stderr.write("Usage: /scan pr <pr-number>\n");
                 return {};
             }
-            const commandFlags = mode === "pr" && prNumber
+            let commandFlags = mode === "pr" && prNumber
                 ? withFlag(withFlag(shellFlags, "mode", mode), "pr", [prNumber])
                 : mode
                     ? withFlag(shellFlags, "mode", mode)
                     : shellFlags;
+            const targets = parsed.args.slice(mode ? 1 : 0);
+            if (mode !== "pr" && targets.length > 0) {
+                commandFlags = withFlag(commandFlags, "repo", targets);
+            }
             if (commandFlags.setup !== undefined) {
                 await commandStartThreatModel(client, cwd, commandFlags);
                 return {};
@@ -253,6 +254,12 @@ async function runShellCommand(client, cwd, parsed, shellFlags, session) {
             await commandScans(client, cwd, shellFlags);
             return {};
         case "findings": {
+            if (parsed.args[0] === "status") {
+                if (parsed.args.length < 3)
+                    throw new Error("Usage: /findings status <finding-ref> <open|fixed|acknowledged|in_review|pending_merge|false_positive|wont_fix|skipped> [note]");
+                await commandFindingStatus(client, cwd, shellFlags, parsed.args[1], parsed.args[2], parsed.args.slice(3).join(" ") || undefined);
+                return {};
+            }
             if (parsed.args[0] === "send") {
                 if (parsed.args.length !== 3)
                     throw new Error("Usage: /findings send <finding-ref> <linear|jira>");

package/dist/telemetry.js

@@ -283,7 +283,7 @@ function sanitizeShellArgs(parsed) {
                     commentLengthBucket: bucketLength(parsed.args.slice(feedbackStatus === "invalid" ? 4 : 3).join(" ")),
                 };
             }
-            if (["fix-review", "tickets", "link-ticket", "send"].includes(action)) {
+            if (["status", "fix-review", "tickets", "link-ticket", "send"].includes(action)) {
                 return {
                     findingRefProvided: Boolean(parsed.args[1]),
                 };
@@ -331,7 +331,7 @@ function safeCliSubcommand(parsed) {
         case "export":
             return safeEnum(subcommand, ["findings"]);
         case "findings":
-            return safeEnum(subcommand, ["comment", "feedback", "fix-review", "tickets", "link-ticket", "send"]);
+            return safeEnum(subcommand, ["comment", "feedback", "status", "fix-review", "tickets", "link-ticket", "send"]);
         case "setup":
             return safeEnum(subcommand, ["all", "codex", "claude", "copilot"]);
         case "service-key":

package/dist/threat-model.js

@@ -314,7 +314,18 @@ async function interactiveAnswers(state) {
     };
 }
 export async function commandThreatModel(client, cwd, flags, action, supplied, emit = true) {
-    const draftId = uuid.parse(required(flags, "draft"));
+    const selectedDraft = getFlagString(flags, "draft");
+    if (!selectedDraft) {
+        const binding = await loadWorkspaceBinding(cwd);
+        const setupCommand = binding
+            ? "apex scan --mode standard --setup guided"
+            : "apex workspaces";
+        throw new ThreatModelUsageError(`Select --draft <id> from the setup response. To create a draft, run ${setupCommand}${binding ? "" : ", bind the intended workspace with apex workspace use <ref>, then run apex scan --mode standard --setup guided"}. Setup uses the workspace's saved repositories and context, not local file selections.`);
+    }
+    const parsedDraft = uuid.safeParse(selectedDraft);
+    if (!parsedDraft.success)
+        throw new ThreatModelUsageError("--draft must be a valid draft ID from the setup response.");
+    const draftId = parsedDraft.data;
     requireAuditSetupBeta(await requireAccount(client));
     let state;
     if (action === "status" || action === "next") {
@@ -368,8 +379,15 @@ export async function commandThreatModel(client, cwd, flags, action, supplied, e
     return state;
 }
 export async function commandStartThreatModel(client, cwd, flags, emit = true) {
-    const setup = z.enum(["guided", "auto"]).parse(required(flags, "setup"));
-    const mode = z.enum(["standard", "audit"]).parse(required(flags, "mode"));
+    const setup = getFlagString(flags, "setup");
+    if (setup !== "guided" && setup !== "auto") {
+        throw new ThreatModelUsageError("--setup must be guided or auto.");
+    }
+    const requestedMode = getFlagString(flags, "mode");
+    const mode = requestedMode === "ultra" ? "audit" : requestedMode;
+    if (mode !== "standard" && mode !== "audit") {
+        throw new ThreatModelUsageError("Audit Setup supports --mode standard or --mode audit. Lite and PR scans do not use --setup; remove it and retry the intended scan mode.");
+    }
     if (["repo", "pr", "pr-path", "source-mode", "force", "workspace-name"].some((key) => flags[key] !== undefined))
         throw new ThreatModelUsageError("Audit Setup uses the configured workspace repositories and context; local source and force flags are not supported");
     const me = await requireAccount(client);

package/dist/types.js

@@ -1 +1,4 @@
-export {};
+export const FINDING_LIFECYCLE_STATUSES = [
+    "open", "fixed", "acknowledged", "in_review", "pending_merge",
+    "false_positive", "wont_fix", "skipped",
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cantinasecurity/apex-cli",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "description": "Standalone CLI and MCP server for Apex.",
   "private": false,
   "type": "module",
@@ -27,18 +27,19 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "ignore": "^7.0.5",
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "ignore": "^7.0.12",
     "proper-lockfile": "^4.1.2",
-    "tar": "^7.4.3",
-    "zod": "^4.3.6"
+    "tar": "^7.5.22",
+    "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@types/node": "^22.18.6",
+    "@types/node": "^22.20.5",
     "@types/proper-lockfile": "^4.1.4",
-    "tsx": "^4.21.0",
+    "tsx": "^4.23.15",
     "typescript": "^5.9.3",
-    "vitest": "^2.1.9"
+    "vite": "^6.4.4",
+    "vitest": "^4.1.11"
   },
   "scripts": {
     "apex": "tsx src/apex.ts",

package/skills/apex-cli/SKILL.md

@@ -9,7 +9,7 @@ This skill is bundled with Apex CLI and can be installed into Codex with `apex s
 
 Prefer the Apex MCP tools over running `apex` in the shell when the server is available. The tools installed by `apex setup` use the local stdio server and device login.
 
-For a production MCP client that does not need local filesystem access, use the hosted Streamable HTTP endpoint at `https://ai.cantina.xyz/mcp`. Read the organization service key from `APEX_SERVICE_KEY` and supply it only as `Authorization: Bearer <TOKEN>`; never put the raw key in a tool argument, result, prompt, source file, or log. The hosted tools are `apex-credits`, `apex-workspaces`, `apex-scan`, `apex-black-start`, `apex-status`, `apex-cancel-scan`, `apex-findings`, `apex-workspace-findings`, `apex-finding-tickets`, `apex-finding-link-ticket`, and `apex-finding-send`.
+For a production MCP client that does not need local filesystem access, use the hosted Streamable HTTP endpoint at `https://ai.cantina.xyz/mcp`. Read the organization service key from `APEX_SERVICE_KEY` and supply it only as `Authorization: Bearer <TOKEN>`; never put the raw key in a tool argument, result, prompt, source file, or log. The hosted tools are `apex-credits`, `apex-workspaces`, `apex-scan`, `apex-black-start`, `apex-status`, `apex-cancel-scan`, `apex-findings`, `apex-workspace-findings`, `apex-finding-tickets`, `apex-finding-link-ticket`, `apex-finding-send`, and `apex-finding-status`.
 
 OAuth-capable clients may instead use the hosted endpoint’s OAuth discovery and Cantina manager-consent flow. Let the client manage OAuth credentials; never pass them to tools, the REST API, or local CLI. Local stdio MCP continues to use device login.
 
@@ -153,3 +153,19 @@ Keep `policy.version` at `3.1`. Supply a name, instructions, and all eight metri
 allowed value and nonempty guidance for each allowed value. Omit disallowed
 values. If Audit Setup or another workspace update is active, wait for it to
 finish before saving again.
+
+Scan target and recovery rules:
+- CLI `apex scan [target...]` and repeatable `--repo` accept exact files, directories, or HTTPS GitHub/GitLab repository URLs; local MCP uses `repoPaths` for the same selections. No target means `cwd`.
+- A file selection scans only that file, respecting ignore rules. Local snapshots exclude `.apex/` state. Remote URLs use the default branch and cannot fall back to uploading `cwd`; clone locally to choose a branch or commit.
+- Use Standard for local changes, files, plain directories, and public repositories without provider access. Lite and Audit still require connected provider sources; do not silently substitute another mode.
+- Unauthenticated headless CLI commands fail with explicit login guidance; they never start device login. Use the MCP auth tools for explicit MCP login. Retry transient refresh failures without clearing credentials.
+- Audit Setup is an explicit Standard/Audit beta flow using saved workspace repositories and context. It does not preserve local targets. Never automatically substitute setup after `AUDIT_SETUP_REQUIRED`; use the error's selected-workspace command only when that saved scope is intended. Draft operations require the ID returned by preparation; eligible accounts receive setup commands in CLI help. Lite and PR do not use `--setup`.
+
+Finding lifecycle:
+- Close resolved issues with `apex-finding-status` and `status: "fixed"`; reopen with `status: "open"`.
+- Local MCP takes `findingRef`, optional `cwd`/`scanId`, `note`, and `expectedUpdatedAt`, using device login. Hosted MCP takes `findingId` (UUID), no local paths, and requires explicit `findings:write`.
+- The scripted equivalent is `apex findings status <finding-ref> <open|fixed> --note "rationale" --json`. Other statuses: acknowledged, in_review, pending_merge, false_positive, wont_fix, skipped.
+- Status changes preserve scanner validity, severity, feedback, and linked ticket state. Invalid or duplicate findings cannot be reopened into the open queue until their classification is reviewed.
+- Read `remediationStatus` in workspace finding lists for the current lifecycle; `status` remains the scanner verdict. `open` and `acknowledged` stay distinct even though both use the `accepted` review state.
+- Use the finding updatedAt as expectedUpdatedAt when working from a prior snapshot. On FINDING_STATUS_CONFLICT, reload and review before retrying.
+- Linear sync is Linear-to-Apex: started becomes acknowledged, completed becomes fixed. Do not promise Apex-to-Linear status updates or automatic Linear reopening.