Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

fix(cli): preserve JSON errors and token windows (#2593)

Michael D'Angeloc1730abab3d4
diff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.md
index 5c0738142..570ec08d9 100644
--- a/sdk/typescript/docs/cli.md
+++ b/sdk/typescript/docs/cli.md
@@ -629,7 +629,7 @@ available) or `SCAN_RESUME_UNAVAILABLE` for `scans resume`. Rerunning an importe
scan uses `SCAN_IMPORT_FAILED` if the import fails. YAML and TOON failures remain
on stderr without `--full-output`, or when retained results are unavailable.
-Scan argument errors with `--full-output` and JSON or JSONL use an `ok: false`
+Argument and execution errors with `--full-output` and JSON or JSONL use an `ok: false`
envelope with `error.code` and `error.message`. Command schema validation errors
with JSON or JSONL retain their field details and name missing or invalid
options by their CLI flags. Diagnostics stay on stderr.
@@ -2809,11 +2809,20 @@ retain exit codes `130` and `143` without a result.
Start with `codex-security --help` for the task groups and shared output and agent options. Each command’s help shows its inputs and supported output formats. Use `import --help` to choose between a live collector, a saved scanner report, and a Codex Security CSV or JSON export.
-Use `--llms` for the command manifest, `--llms-full` for argument details, and `scan --schema --format json` for the scan schema. The manifests and shell completion include `scan import` alongside the ordinary `scan [repository]` command. Generate completions with `completions bash|fish|nushell|zsh`. Scan output supports
+Use `--llms` for the command manifest, `--llms-full` for argument details, and `scan --schema --format json` for the scan schema. The manifests and shell completion include `scan import` alongside the ordinary `scan [repository]` command. Generate completions with `completions bash|fish|nushell|zsh`. Add `--json` to return the generated script as a JSON string. The same option returns the menu text when an omitted command or subcommand displays help. With `--full-output`, the text is in `data`. Scan output supports
`--format toon|json|yaml|jsonl` and `--full-output`. The existing `--format`,
`--filter-output`, `--token-limit`, and `--token-offset` options accept either
`--option value` or `--option=value`.
+`--token-limit` and `--token-offset` take nonnegative integers and select a
+text view of the formatted result. Truncated JSON and JSONL views are returned
+as a JSON string containing the excerpt and its token range. With
+`--full-output`, the excerpt is in `data` and `meta.nextOffset` identifies
+the next page when more tokens are available. `--token-count` returns the
+estimated size instead. A failed full-output JSON or JSONL response always
+retains its error code and message. If the failure carries result data,
+`--token-count` reports its size in `meta.tokenCount`.
+
`skills add` syncs generated CLI command guidance; it does not install the full
Codex Security plugin. `mcp add` registers the CLI as an MCP server, exposing
only read-only `info` because the transport cannot cancel scans. For the plugin's
diff --git a/sdk/typescript/package.json b/sdk/typescript/package.json
index 28de44870..20dbcd6f1 100644
--- a/sdk/typescript/package.json
+++ b/sdk/typescript/package.json
@@ -104,6 +104,7 @@
"smol-toml": "1.9.1",
"string-width": "8.3.0",
"strip-ansi": "7.2.0",
+ "tokenx": "1.6.0",
"yaml": "2.9.1",
"yauzl": "3.4.0",
"zod": "4.6.7"
diff --git a/sdk/typescript/pnpm-lock.yaml b/sdk/typescript/pnpm-lock.yaml
index 68869278d..d4c4c6597 100644
--- a/sdk/typescript/pnpm-lock.yaml
+++ b/sdk/typescript/pnpm-lock.yaml
@@ -71,6 +71,9 @@ importers:
strip-ansi:
specifier: 7.2.0
version: 7.2.0
+ tokenx:
+ specifier: 1.6.0
+ version: 1.6.0
yaml:
specifier: 2.9.1
version: 2.9.1
diff --git a/sdk/typescript/scripts/package-dist-files.mjs b/sdk/typescript/scripts/package-dist-files.mjs
index 8d9fb29d2..9890db929 100644
--- a/sdk/typescript/scripts/package-dist-files.mjs
+++ b/sdk/typescript/scripts/package-dist-files.mjs
@@ -19,6 +19,7 @@ const distModules = [
"cli-mcp",
"cli-scan-logs-json",
"cli-signals",
+ "cli-token-view",
"classify-severity",
"classify-severity-records",
"codeowners",
diff --git a/sdk/typescript/src/cli-help.ts b/sdk/typescript/src/cli-help.ts
index f7e7482f8..1533c1bde 100644
--- a/sdk/typescript/src/cli-help.ts
+++ b/sdk/typescript/src/cli-help.ts
@@ -192,6 +192,10 @@ function optionRow(row: Row, command: string): Row {
}
return `<${VALUE_LABELS[name] ?? (type === "number" ? "count" : name)}>`;
});
+ if (name === "token-limit")
+ description = "Maximum tokens in the text view (nonnegative integer).";
+ if (name === "token-offset")
+ description = "Start the text view at this token (nonnegative integer).";
label = label.replace(/^--([\w-]+), (-\w)/u, "$2, --$1");
if (command === "scan" && !/default:/iu.test(description)) {
const setting = DEEP_SCAN_SETTINGS.find(
@@ -241,11 +245,11 @@ function globalRows(rows: Row[], command: string): Row[] {
}
/** Present Incur's generated help without changing its routing or command output. */
-export function formatCliHelp(text: string, columns = 80): string {
+export function formatCliHelp(text: string, columns = 80): string | undefined {
const header = text.match(
/^(codex-security(?:@[^\s]+)?((?: [a-z][a-z-]*)*))(?: — ([^\n]*))?\n\nUsage: /u,
);
- if (!header) return text;
+ if (!header) return undefined;
const command = header[2]!.trim();
const sections: string[] = [];
// Presentation width only; long paths and copyable commands remain intact.
diff --git a/sdk/typescript/src/cli-token-view.ts b/sdk/typescript/src/cli-token-view.ts
new file mode 100644
index 000000000..4df546a8a
--- /dev/null
+++ b/sdk/typescript/src/cli-token-view.ts
@@ -0,0 +1,58 @@
+import { Formatter } from "incur";
+import { estimateTokenCount, sliceByTokens } from "tokenx";
+import { asRecord } from "./record.js";
+
+export interface TokenView {
+ count?: boolean;
+ limit?: number;
+ offset?: number;
+}
+
+/** Apply a window to the serialized data. Keep failure details and pagination
+ * metadata readable even when the caller requests a single token.
+ */
+export function formatJsonTokenView(
+ response: string,
+ format: "json" | "jsonl",
+ fullOutput: boolean,
+ view: TokenView,
+): string {
+ const envelope = fullOutput ? asRecord(JSON.parse(response)) : undefined;
+ const failed = envelope?.["ok"] === false;
+ if (failed && envelope["data"] == null) return response;
+ const text = envelope
+ ? Formatter.format(envelope["data"], format)
+ : response.replace(/\n$/u, "");
+ const total = estimateTokenCount(text);
+ if (view.count) {
+ if (!failed) return `${total}\n`;
+ const { data: _data, ...failure } = envelope;
+ return (
+ Formatter.format(
+ {
+ ...failure,
+ meta: { ...asRecord(failure["meta"]), tokenCount: total },
+ },
+ format,
+ ) + "\n"
+ );
+ }
+ const start = Math.min(view.offset ?? 0, total);
+ const end = Math.min(start + (view.limit ?? total), total);
+ if (start === 0 && end === total) return response;
+ const page = `${sliceByTokens(text, start, end)}\n[truncated: showing tokens ${start}–${end} of ${total}]`;
+ if (!envelope) return JSON.stringify(page) + "\n";
+ return (
+ Formatter.format(
+ {
+ ...envelope,
+ data: page,
+ meta: {
+ ...asRecord(envelope["meta"]),
+ ...(start < end && end < total && { nextOffset: end }),
+ },
+ },
+ format,
+ ) + "\n"
+ );
+}
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.ts
index fc11e3275..7535ffd73 100644
--- a/sdk/typescript/src/cli.ts
+++ b/sdk/typescript/src/cli.ts
@@ -74,6 +74,7 @@ import type { ZodType } from "zod";
import stringWidth from "string-width";
import Ajv2020, { type ValidateFunction } from "ajv/dist/2020.js";
import { formatCliHelp } from "./cli-help.js";
+import { formatJsonTokenView, type TokenView } from "./cli-token-view.js";
import { formatCoverageScope } from "./coverage-presentation.js";
import { resolveSkillAuthentication } from "./skill-authentication.js";
import { scanLogsJson } from "./cli-scan-logs-json.js";
@@ -2497,8 +2498,7 @@ export async function main(
message: string;
}
| undefined;
- let filteredScanFailure:
- { format: string; data: Record<string, unknown> } | undefined;
+ let unfilteredFailure: Record<string, unknown> | undefined;
const includeFailureResults = (
format: string,
): format is "json" | "jsonl" | "toon" | "yaml" =>
@@ -2528,8 +2528,7 @@ export async function main(
const message = errorMessage(outcome.error);
if (!argv.includes("--full-output")) {
const data = { status: "failed", code, message };
- if (frameworkFlags.filters.length)
- filteredScanFailure = { format, data };
+ if (frameworkFlags.filters.length) unfilteredFailure = data;
return data;
}
// Incur would wrap returned data in an ok: true envelope.
@@ -4457,7 +4456,7 @@ export async function main(
(!argv.includes("--full-output") || selection !== undefined) &&
frameworkFlags.filters.length
)
- filteredScanFailure = { format, data: failure };
+ unfilteredFailure = failure;
return structured ? failure : undefined;
} finally {
removeSignals();
@@ -4556,7 +4555,7 @@ export async function main(
}),
)
.optional(),
- async run({ args, options }) {
+ async run({ args, options, error: fail }) {
const controller = new AbortController();
const removeSignals = listenForAbort(dependencies, controller);
try {
@@ -4586,7 +4585,11 @@ export async function main(
exitCode = 2;
errorOutput.write(`codex-security: ${diagnosticValue(error)}\n`);
}
- throw error;
+ return fail({
+ code: "GITHUB_IMPORT_FAILED",
+ message: errorMessage(error),
+ exitCode,
+ });
} finally {
removeSignals();
}
@@ -7151,7 +7154,7 @@ export async function main(
const structured = format === "json" || format === "jsonl";
const reportDiagnostic = async (chunk: string): Promise<void> => {
if (structured) {
- if (!batchedVerification || frameworkFlags.tokenArguments.length)
+ if (!batchedVerification || frameworkFlags.tokenView)
deferredVerificationDiagnostic = chunk;
} else {
await writeCliOutput(errorOutput, chunk).catch(() => {});
@@ -8176,13 +8179,13 @@ export async function main(
return "Select a command before --.";
if (importArgs.error) return importArgs.error;
if (frameworkFlags.argumentError) return frameworkFlags.argumentError;
- if (command === undefined) return undefined;
+ if (command === undefined) return frameworkFlags.tokenError;
if (!entry) {
if (["skills", "skill", "mcp", "completions"].includes(command))
- return undefined;
+ return frameworkFlags.tokenError;
if (inspection)
return `Unknown command ${diagnosticValue(command)}. Use codex-security --help.`;
- return undefined;
+ return frameworkFlags.tokenError;
}
if (
"_group" in entry &&
@@ -8336,6 +8339,7 @@ export async function main(
: "";
return `Unexpected positional argument for ${command}${subcommand === undefined ? "" : ` ${subcommand}`}.${hint}`;
}
+ return frameworkFlags.tokenError;
}
const frameworkFlags = parseFrameworkArguments(argv);
const frameworkArgv = frameworkFlags.args;
@@ -8345,26 +8349,31 @@ export async function main(
frameworkFlags.fullOutput &&
!mixedAction &&
!argv.includes("--incur-update-check");
- const scanErrorFormat =
- command === "scan" && !scanImport && frameworkFlags.fullOutput
- ? jsonFormat
- : undefined;
- const argumentFailure = (message: string) =>
+ const envelopeFormat = frameworkFlags.fullOutput ? jsonFormat : undefined;
+ const commandPath = subcommand
+ ? `${command} ${subcommand}`
+ : (command ?? "codex-security");
+ const argumentFailure = (
+ message: string,
+ code = commandPath === "scan"
+ ? "SCAN_FAILED"
+ : command === "policy"
+ ? "POLICY_FAILED"
+ : "INVALID_ARGUMENTS",
+ ) =>
Formatter.format(
- {
- ok: false,
- error: { code: "SCAN_FAILED", message },
- meta: { command: "scan" },
- },
- scanErrorFormat,
+ { ok: false, error: { code, message }, meta: { command: commandPath } },
+ envelopeFormat,
) + "\n";
- const argumentError = validateCliArguments();
- if (argumentError !== undefined && !policyFullOutput) {
- errorOutput.write(`codex-security: ${argumentError}\n`);
- if (scanErrorFormat)
- await writeCliOutput(output, argumentFailure(argumentError));
+ const reportError = async (message: string, code?: string) => {
+ errorOutput.write(`codex-security: ${diagnosticLines(message)}\n`);
+ if (envelopeFormat)
+ await writeCliOutput(output, argumentFailure(message, code));
return 2;
- }
+ };
+ const argumentError = validateCliArguments();
+ if (argumentError !== undefined && (!policyFullOutput || envelopeFormat))
+ return reportError(argumentError);
if (protocol) {
const recordsCommand =
command === "dedupe" ||
@@ -8453,8 +8462,7 @@ export async function main(
notice = await Promise.race([pendingUpdate, undefined]);
}
} catch (error) {
- errorOutput.write(`codex-security: ${diagnosticLines(error)}\n`);
- return 2;
+ return reportError(errorMessage(error), "COMMAND_FAILED");
} finally {
updateController.abort();
}
@@ -8473,33 +8481,12 @@ export async function main(
const parent = commands.get(command);
const group = parent && "_group" in parent ? command : undefined;
const path = group && following ? `${group} ${following}` : command;
- errorOutput.write(
- `codex-security: Unknown command ${diagnosticValue(path)}. Use codex-security${group ? ` ${group}` : ""} --help.\n`,
+ return reportError(
+ `Unknown command ${diagnosticValue(path)}. Use codex-security${group ? ` ${group}` : ""} --help.`,
+ "COMMAND_NOT_FOUND",
);
- return 2;
}
- if (filteredScanFailure !== undefined) {
- // Success-field filters do not apply to diagnostics. Reuse Incur's format
- // and token controls without running the saved scan a second time.
- const failureOutput = captureOutput();
- const failureArguments = [
- "render",
- "--format",
- filteredScanFailure.format,
- ...frameworkFlags.tokenArguments,
- ];
- if (failedResultOutput) failureArguments.push("--full-output");
- const failure = filteredScanFailure.data;
- await Cli.create("codex-security-scan-error")
- .command("render", { run: () => failure })
- .serve(failureArguments, {
- stdout: failureOutput.stream.write,
- exit: () => undefined,
- });
- if (failedResultOutput) frameworkOutput = failureOutput.text();
- else renderedOutput = failureOutput.text();
- }
if (escapeFrameworkOutput)
frameworkOutput = escapeTerminalText(frameworkOutput, true);
const writeUpdateNotice = () => {
@@ -8510,10 +8497,17 @@ export async function main(
};
if (deferredVerificationDiagnostic === undefined) writeUpdateNotice();
if (frameworkExit !== undefined) {
- if (policyFullOutput || structuredError) {
+ // A canceled command can deliberately finish without a result.
+ if (
+ !structuredError &&
+ !policyFullOutput &&
+ (exitCode === 130 || exitCode === 143)
+ )
+ return exitCode;
+ if (!envelopeFormat && (policyFullOutput || structuredError)) {
if (exitCode === 0) exitCode = 2;
} else {
- if (exitCode !== 0) return exitCode;
+ if (exitCode !== 0 && !envelopeFormat) return exitCode;
const envelope = jsonFormat
? parseJson(() => frameworkOutput)
: undefined;
@@ -8521,7 +8515,7 @@ export async function main(
const error =
record?.["ok"] === false ? asRecord(record["error"]) : record;
const validationError = error?.["code"] === "VALIDATION_ERROR";
- const structuredFailure = Boolean(scanErrorFormat || validationError);
+ const structuredFailure = Boolean(envelopeFormat || validationError);
let message =
structuredFailure && typeof error?.["message"] === "string"
? error["message"]
@@ -8554,28 +8548,22 @@ export async function main(
error["message"] = message;
frameworkOutput = Formatter.format(envelope, jsonFormat) + "\n";
}
- errorOutput.write(`codex-security: ${diagnosticLines(message)}\n`);
+ // Handlers that set an exit code have already reported the execution error.
+ if (exitCode === 0)
+ errorOutput.write(`codex-security: ${diagnosticLines(message)}\n`);
if (!structuredFailure) return 2;
- exitCode = 2;
- // Errors in built-in flags precede Incur's format selection. Its other
- // parse errors already carry the requested envelope or token view.
- if (
- scanErrorFormat &&
- record?.["ok"] !== false &&
- !(
- typeof envelope === "number" &&
- frameworkFlags.tokenArguments.includes("--token-count")
- )
- ) {
+ if (exitCode === 0) exitCode = 2;
+ // Incur parses its built-in flags before selecting a format.
+ if (envelopeFormat && record?.["ok"] !== false)
frameworkOutput = argumentFailure(message);
- }
}
}
if (rawExportOutput) return exitCode;
if (
frameworkOutput.length === 0 &&
+ !(jsonFormat && frameworkFlags.tokenView?.count && exitCode === 0) &&
streamedLogs === undefined &&
- filteredScanFailure === undefined &&
+ unfilteredFailure === undefined &&
deferredVerificationDiagnostic === undefined
)
return exitCode;
@@ -8610,21 +8598,11 @@ export async function main(
}
} else if (failedResultOutput !== undefined) {
const envelope: JsonValue = JSON.parse(frameworkOutput);
- // Token-count output is a number, not a full-output envelope.
if (isJsonObject(envelope) && envelope["ok"] === true) {
- // Re-rendered failures carry the unfiltered page, but the command's
- // original metadata describes the actual invocation.
- const meta =
- filteredScanFailure && isJsonObject(envelope["meta"])
- ? {
- ...JSON.parse(frameworkCapture.text()).meta,
- nextOffset: envelope["meta"]["nextOffset"],
- }
- : envelope["meta"];
frameworkOutput = `${JSON.stringify(
{
...envelope,
- meta,
+ ...(unfilteredFailure && { data: unfilteredFailure }),
ok: false,
error: {
code: failedResultOutput.code ?? "SCAN_FAILED",
@@ -8636,12 +8614,33 @@ export async function main(
)}\n`;
}
}
- await writeCliOutput(
- output,
- logOutput ??
- renderedOutput ??
- formatCliHelp(frameworkOutput, output.columns),
- );
+ const help = formatCliHelp(frameworkOutput, output.columns);
+ let response = renderedOutput ?? help ?? frameworkOutput;
+ // Incur writes menus and completion scripts directly as plain text.
+ if (
+ jsonFormat &&
+ !inspection &&
+ exitCode === 0 &&
+ (help !== undefined || command === "completions")
+ ) {
+ response =
+ Formatter.format(
+ frameworkFlags.fullOutput
+ ? { ok: true, data: response, meta: { command: commandPath } }
+ : response,
+ jsonFormat,
+ ) + "\n";
+ }
+ if (jsonFormat && unfilteredFailure && !failedResultOutput)
+ response = Formatter.format(unfilteredFailure, jsonFormat) + "\n";
+ if (jsonFormat && frameworkFlags.tokenView && !inspection)
+ response = formatJsonTokenView(
+ response,
+ jsonFormat,
+ frameworkFlags.fullOutput,
+ frameworkFlags.tokenView,
+ );
+ await writeCliOutput(output, logOutput ?? response);
return exitCode;
} catch (error) {
errorOutput.write(`codex-security: ${diagnosticLines(error)}\n`);
@@ -8650,7 +8649,7 @@ export async function main(
if (deferredVerificationDiagnostic !== undefined) {
// Token output can omit the diagnostic. Otherwise a buffered stderr
// write is optional once the complete structured failure is on stdout.
- if (frameworkFlags.tokenArguments.length) {
+ if (frameworkFlags.tokenView) {
await writeCliOutput(errorOutput, deferredVerificationDiagnostic).catch(
() => {},
);
@@ -9001,10 +9000,6 @@ function normalizeImportArguments(
const seen = new Map<string, string>();
for (let index = args.length; index < argv.length; index++) {
const token = argv[index]!;
- if (token === "--") {
- args.push(...argv.slice(index));
- break;
- }
const equals = token.indexOf("=");
const name = equals < 0 ? token : token.slice(0, equals);
const flag = name.replace(/[A-Z]/g, (c) => "-" + c.toLowerCase());
@@ -9049,6 +9044,8 @@ function parseFrameworkArguments(argv: readonly string[]) {
const formats: string[] = [];
const filters: (string | undefined)[] = [];
const tokenArguments: string[] = [];
+ let tokenView: TokenView | undefined;
+ let tokenError: string | undefined;
let fullOutput = false;
let argumentError: string | undefined;
for (let index = 0; index < argv.length; index++) {
@@ -9057,10 +9054,14 @@ function parseFrameworkArguments(argv: readonly string[]) {
const equals = argument.indexOf("=");
const flag = equals < 0 ? argument : argument.slice(0, equals);
if (!FRAMEWORK_VALUE_OPTIONS.has(flag)) {
+ if (argument === "--token-count") {
+ (tokenView ??= {}).count = true;
+ tokenArguments.push(argument);
+ continue;
+ }
args.push(argument);
if (argument === "--json") formats.push("json");
if (argument === "--full-output") fullOutput = true;
- if (argument === "--token-count") tokenArguments.push(argument);
continue;
}
// Leave a following flag available when the option is missing its operand.
@@ -9089,17 +9090,31 @@ function parseFrameworkArguments(argv: readonly string[]) {
continue;
}
}
+ if (flag === "--token-limit" || flag === "--token-offset") {
+ if (
+ operand === undefined ||
+ !/^\d+$/u.test(operand) ||
+ !Number.isSafeInteger(Number(operand))
+ ) {
+ tokenError ??= `${flag} requires a nonnegative integer.`;
+ } else {
+ (tokenView ??= {})[flag === "--token-limit" ? "limit" : "offset"] =
+ Number(operand);
+ tokenArguments.push(flag, operand);
+ }
+ continue;
+ }
args.push(flag);
if (operand !== undefined) args.push(operand);
if (flag === "--format" && operand) formats.push(operand);
- if (
- (flag === "--token-limit" || flag === "--token-offset") &&
- operand !== undefined
- )
- tokenArguments.push(flag, operand);
}
- const format = formats.at(-1);
+ // Invalid format operands still go to Incur. Preserve a valid request for
+ // JSON diagnostics if parsing a later operand fails.
+ const format = formats.findLast((value) =>
+ ["json", "jsonl", "toon", "yaml", "md"].includes(value),
+ );
const jsonFormat = isJsonFormat(format) ? format : undefined;
+ if (!jsonFormat) args.push(...tokenArguments);
return {
args,
formats,
@@ -9108,6 +9123,8 @@ function parseFrameworkArguments(argv: readonly string[]) {
argumentError,
filters,
tokenArguments,
+ tokenView,
+ tokenError,
rawStructuredOutput:
!fullOutput && (jsonFormat !== undefined || format === "yaml"),
};
diff --git a/sdk/typescript/tests-ts/cli-dedupe.test.ts b/sdk/typescript/tests-ts/cli-dedupe.test.ts
index 21d24010a..ef0184c65 100644
--- a/sdk/typescript/tests-ts/cli-dedupe.test.ts
+++ b/sdk/typescript/tests-ts/cli-dedupe.test.ts
@@ -312,7 +312,7 @@ test.each([
"requires --scan or --workflow-id",
],
])(
- "dedupe does not emit an ok: true envelope when a scan is missing: %s",
+ "dedupe emits a failed envelope when a scan is missing: %s",
async (_label, flags, expected) => {
const { stdout, stderr } = createCliTest(main);
expect(
@@ -323,12 +323,15 @@ test.each([
dependencies(),
),
).toBe(2);
- expect(stdout.text()).toBe("");
+ expect(JSON.parse(stdout.text())).toMatchObject({
+ ok: false,
+ error: { message: expect.stringContaining(expected) },
+ });
expect(stderr.text()).toContain(expected);
},
);
-test("dedupe does not emit an ok: true envelope for a failed structured dedupe run", async () => {
+test("dedupe returns a failed envelope for an execution error", async () => {
const deps = dependencies();
deps.deduplicateScan = async () => {
throw new Error("Finding has not been indexed");
@@ -337,7 +340,10 @@ test("dedupe does not emit an ok: true envelope for a failed structured dedupe r
expect(
await main([...args, "--full-output"], stdout.stream, stderr.stream, deps),
).toBe(2);
- expect(stdout.text()).toBe("");
+ expect(JSON.parse(stdout.text())).toMatchObject({
+ ok: false,
+ error: { message: "Finding has not been indexed" },
+ });
expect(stderr.text()).toContain("Finding has not been indexed");
});
diff --git a/sdk/typescript/tests-ts/cli-diagnostics.test.ts b/sdk/typescript/tests-ts/cli-diagnostics.test.ts
index 4f549a6c9..11ec210f7 100644
--- a/sdk/typescript/tests-ts/cli-diagnostics.test.ts
+++ b/sdk/typescript/tests-ts/cli-diagnostics.test.ts
@@ -274,6 +274,55 @@ describe("CLI diagnostics", () => {
}
});
+ test.each(
+ [
+ ["info", "--badOption"],
+ ["info", "unexpected"],
+ ["import", "github", "invalid"],
+ ["import", "github-advisories", "invalid"],
+ ["scan", "import", "--csv", "missing.csv", "--dry-run"],
+ ["scans", "show", "missing"],
+ ].map((command) => ({ command })),
+ )("emits one full JSON error for $command", async ({ command }) => {
+ for (const format of [["--json"], ["--format=jsonl"]]) {
+ const { stdout, stderr, runCli } = createCliTest(main);
+ const deps = dependencies();
+ deps.runWorkbench = throwing("Missing saved scan.");
+ expect(
+ await runCli(
+ [...command, ...format, "--full-output", "--token-limit=1"],
+ deps,
+ ),
+ ).toBe(2);
+ const failure = JSON.parse(stdout.text());
+ expect(failure.ok).toBe(false);
+ expect(typeof failure.error.code).toBe("string");
+ expect(stderr.text()).toContain(failure.error.message.split("\n")[0]);
+ expect(stderr.text()).not.toContain('"ok":');
+ if (format[0] === "--format=jsonl")
+ expect(stdout.text().trimEnd().split("\n")).toHaveLength(1);
+ }
+ });
+
+ test.each(["--token-limit", "--token-offset"])(
+ "checks %s before executing the command",
+ async (flag) => {
+ for (const operand of ["", "-1", "1.5", "NaN", "9007199254740992"]) {
+ const { stdout, stderr, runCli } = createCliTest(main);
+ const deps = dependencies();
+ deps.currentDirectory = throwing("Unexpected execution.");
+ expect(
+ await runCli(
+ ["info", "--json", "--full-output", `${flag}=${operand}`],
+ deps,
+ ),
+ ).toBe(2);
+ expect(stderr.text()).toContain("nonnegative integer");
+ expect(JSON.parse(stdout.text()).error.message).toContain(flag);
+ }
+ },
+ );
+
test("does not format a token count after patch fails", async () => {
const { stdout, stderr, runCli } = createCliTest(main);
const deps = dependencies();
diff --git a/sdk/typescript/tests-ts/cli-help.test.ts b/sdk/typescript/tests-ts/cli-help.test.ts
index 9584866c2..3db5a5385 100644
--- a/sdk/typescript/tests-ts/cli-help.test.ts
+++ b/sdk/typescript/tests-ts/cli-help.test.ts
@@ -5,6 +5,7 @@ import { main } from "../src/cli.js";
import { DEFAULT_CODEX_CONFIG, scanModelConfiguration } from "../src/config.js";
import { DEFAULT_DEEP_SCAN_SETTINGS } from "../src/deep-scan-defaults.js";
import { capture, dependencies } from "./cli-fixtures.js";
+import { createCliTest } from "./support/cli-run.js";
async function help(args: readonly string[], columns?: number) {
const stdout = capture(true);
@@ -366,6 +367,40 @@ describe("CLI help", () => {
expect(stderr.text()).toContain(`Did you mean '${verb}'?`);
});
+ test.each([
+ { command: [], expected: "Usage: codex-security" },
+ ...["skills", "mcp", "import", "publish", "completions"].map((name) => ({
+ command: [name],
+ expected: `Usage: codex-security ${name}`,
+ })),
+ { command: ["completions", "zsh"], expected: "#compdef" },
+ ])(
+ "formats the text from $command before applying JSON token controls",
+ async ({ command, expected }) => {
+ async function run(...flags: string[]) {
+ const { runCli, stdout, stderr } = createCliTest(main);
+ expect(await runCli([...command, ...flags], dependencies())).toBe(0);
+ expect(stderr.text()).toBe("");
+ return stdout.text();
+ }
+ const plain = await run();
+ expect(plain).toContain(expected);
+ expect(JSON.parse(await run("--json"))).toBe(plain);
+ const flags = ["--format=jsonl", "--full-output"];
+ expect(JSON.parse(await run(...flags))).toMatchObject({
+ ok: true,
+ data: plain,
+ });
+ expect(JSON.parse(await run(...flags, "--token-count"))).toBeGreaterThan(
+ 0,
+ );
+ expect(JSON.parse(await run(...flags, "--token-limit=1"))).toMatchObject({
+ ok: true,
+ meta: { nextOffset: 1 },
+ });
+ },
+ );
+
test("uses the completion shell schema without generating a script", async () => {
const schema = JSON.parse(
await help(["completions", "--json", "--schema"]),
diff --git a/sdk/typescript/tests-ts/cli-scan-logs.test.ts b/sdk/typescript/tests-ts/cli-scan-logs.test.ts
index 817d711cc..b0c0d6a00 100644
--- a/sdk/typescript/tests-ts/cli-scan-logs.test.ts
+++ b/sdk/typescript/tests-ts/cli-scan-logs.test.ts
@@ -215,6 +215,12 @@ describe("saved logs JSON output", () => {
expect(withoutDuration(stdout.text())).toEqual(
withoutDuration(expected),
);
+ } else if (args.includes("999999") && args.includes("--token-offset")) {
+ expect(JSON.parse(stdout.text())).toMatch(
+ /showing tokens (\d+)–\1 of \1/u,
+ );
+ } else if (expected.includes("[truncated:")) {
+ expect(JSON.parse(stdout.text())).toBe(expected.trimEnd());
} else {
expect(stdout.text()).toBe(expected);
}
diff --git a/sdk/typescript/tests-ts/cli-verify-fix.test.ts b/sdk/typescript/tests-ts/cli-verify-fix.test.ts
index 714121350..5fee1d155 100644
--- a/sdk/typescript/tests-ts/cli-verify-fix.test.ts
+++ b/sdk/typescript/tests-ts/cli-verify-fix.test.ts
@@ -473,10 +473,16 @@ describe("read-only finding verification", () => {
expect(
await runCli(["verify-fix", "--scan", "scan", ...flags], deps),
).toBe(2);
- if (flags.includes("--token-count"))
- expect(stdout.text()).toMatch(/^\d+\n$/u);
- else expect(stdout.text()).toContain("[truncated:");
- expect(stdout.text()).not.toContain(message);
+ const value = JSON.parse(stdout.text());
+ if (flags.includes("--full-output")) {
+ expect(value).toMatchObject({ ok: false, error: { message } });
+ } else if (flags.includes("--token-count")) {
+ expect(typeof value).toBe("number");
+ } else {
+ expect(typeof value).toBe("string");
+ expect(value).toContain("[truncated:");
+ expect(value).not.toContain(message);
+ }
expect(stderr.text().split(message)).toHaveLength(2);
}
},
diff --git a/sdk/typescript/tests-ts/cli.test.ts b/sdk/typescript/tests-ts/cli.test.ts
index dd7502acf..ece327b31 100644
--- a/sdk/typescript/tests-ts/cli.test.ts
+++ b/sdk/typescript/tests-ts/cli.test.ts
@@ -2098,7 +2098,7 @@ describe("CLI", () => {
});
test.each([false, true])(
- "does not emit an ok: true envelope for a failed structured history command with full output %p",
+ "reports a structured history failure with full output %p",
async (fullOutput) => {
for (const argv of [
["scans", "show", "--json"],
@@ -2119,10 +2119,14 @@ describe("CLI", () => {
},
);
expect(result).toBe(2);
- expect(stdout.text()).toBe("");
- expect(stderr.text()).toContain(
- "Scan ID prefixes must be at least eight characters.",
- );
+ const message = "Scan ID prefixes must be at least eight characters.";
+ if (fullOutput)
+ expect(JSON.parse(stdout.text())).toMatchObject({
+ ok: false,
+ error: { message },
+ });
+ else expect(stdout.text()).toBe("");
+ expect(stderr.text()).toContain(message);
}
},
);
diff --git a/sdk/typescript/tests-ts/external-findings-publish.test.ts b/sdk/typescript/tests-ts/external-findings-publish.test.ts
index a16d2dfb7..d87292921 100644
--- a/sdk/typescript/tests-ts/external-findings-publish.test.ts
+++ b/sdk/typescript/tests-ts/external-findings-publish.test.ts
@@ -952,6 +952,12 @@ test("an entirely excluded report fails with all positions intact and a short di
data: expect.any(String),
meta: { nextOffset: 5 },
});
+ const counted = createCliTest(main);
+ expect(await counted.runCli([...flags, "--token-count"], f.cliDeps)).toBe(2);
+ const count = JSON.parse(counted.stdout.text());
+ expect(count.error).toEqual(failure.error);
+ expect(count.meta.tokenCount).toBeGreaterThan(5);
+ expect(count).not.toHaveProperty("data");
expect(f.posts).toHaveLength(0);
});