Skip to content

Commit 2b374b2

Browse files
loong10kloong10k
committed
test: add JUnit tests; docs: comprehensive English JavaDoc
1 parent 7bfff60 commit 2b374b2

16 files changed

Lines changed: 2804 additions & 111 deletions

‎src/main/java/io/github/easy4j/codex/CodexClient.java‎

Lines changed: 560 additions & 64 deletions
Large diffs are not rendered by default.

‎src/main/java/io/github/easy4j/codex/CodexClientConfig.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@
3434
* while the bypass flags default to {@code false} so that operations always
3535
* require approvals unless explicitly opted-in.</p>
3636
*
37-
* @author easy-4-java contributors
37+
* @author [@Loong Wan](https://github.com/loong10k)
3838
* @since 3.0.0
3939
* @see CodexClient
4040
*/

‎src/main/java/io/github/easy4j/codex/cli/CodexCli.java‎

Lines changed: 231 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@
4545
* exact CLI flag spelling, isolating that knowledge from the rest of the code
4646
* base.</p>
4747
*
48-
* @author easy-4-java contributors
48+
* @author [@Loong Wan](https://github.com/loong10k)
4949
* @since 3.0.0
5050
* @see <a href="https://github.com/openai/codex">Codex CLI</a>
5151
* @see CodexCliExecutor
@@ -796,7 +796,7 @@ public CodexCliResult execServer(String... args) {
796796
* flags can be supplied through {@link #configOverrides(String...)} without
797797
* requiring changes to this class.</p>
798798
*
799-
* @author easy-4-java contributors
799+
* @author [@Loong Wan](https://github.com/loong10k)
800800
* @since 3.0.0
801801
*/
802802
public static class ExecOptions {
@@ -830,47 +830,152 @@ public static class ExecOptions {
830830
*/
831831
public ExecOptions(String prompt) { this.prompt = prompt; }
832832

833-
/** Sets the {@code --model} flag. */
833+
/**
834+
* Sets the {@code --model} flag.
835+
*
836+
* @param v the model identifier (e.g. {@code gpt-5-codex}).
837+
* @return this builder for chaining.
838+
*/
834839
public ExecOptions model(String v) { this.model = v; return this; }
835-
/** Sets the {@code --sandbox} flag. */
840+
/**
841+
* Sets the {@code --sandbox} flag.
842+
*
843+
* @param v the sandbox mode (e.g. {@code read-only}, {@code workspace-write}).
844+
* @return this builder for chaining.
845+
*/
836846
public ExecOptions sandbox(String v) { this.sandbox = v; return this; }
837-
/** Sets the {@code --ask-for-approval} flag. */
847+
/**
848+
* Sets the {@code --ask-for-approval} flag.
849+
*
850+
* @param v the approval policy (e.g. {@code untrusted}, {@code on-request}, {@code never}).
851+
* @return this builder for chaining.
852+
*/
838853
public ExecOptions approvalPolicy(String v) { this.approvalPolicy = v; return this; }
839-
/** Sets the {@code --profile} flag. */
854+
/**
855+
* Sets the {@code --profile} flag.
856+
*
857+
* @param v the configuration profile name.
858+
* @return this builder for chaining.
859+
*/
840860
public ExecOptions profile(String v) { this.profile = v; return this; }
841-
/** Sets the {@code -C} flag. */
861+
/**
862+
* Sets the {@code -C} flag.
863+
*
864+
* @param v the working directory for the CLI process.
865+
* @return this builder for chaining.
866+
*/
842867
public ExecOptions workingDir(String v) { this.workingDir = v; return this; }
843-
/** Sets the {@code --add-dir} flag. */
868+
/**
869+
* Sets the {@code --add-dir} flag.
870+
*
871+
* @param v additional directory granted to the agent at runtime.
872+
* @return this builder for chaining.
873+
*/
844874
public ExecOptions addDir(String v) { this.addDir = v; return this; }
845-
/** Sets the {@code -o} flag. */
875+
/**
876+
* Sets the {@code -o} flag.
877+
*
878+
* @param v destination file path for the final message.
879+
* @return this builder for chaining.
880+
*/
846881
public ExecOptions outputFile(String v) { this.outputFile = v; return this; }
847-
/** Sets the {@code --output-schema} flag. */
882+
/**
883+
* Sets the {@code --output-schema} flag.
884+
*
885+
* @param v path to a JSON Schema file describing the expected structured output.
886+
* @return this builder for chaining.
887+
*/
848888
public ExecOptions outputSchema(String v) { this.outputSchema = v; return this; }
849-
/** Sets the {@code --json} flag (default {@code true}). */
889+
/**
890+
* Sets the {@code --json} flag (default {@code true}).
891+
*
892+
* @param v {@code true} to enable JSON-Lines output, {@code false} to disable.
893+
* @return this builder for chaining.
894+
*/
850895
public ExecOptions json(boolean v) { this.json = v; return this; }
851-
/** Sets the {@code --ephemeral} flag. */
896+
/**
897+
* Sets the {@code --ephemeral} flag.
898+
*
899+
* @param v {@code true} to prevent session persistence to disk.
900+
* @return this builder for chaining.
901+
*/
852902
public ExecOptions ephemeral(boolean v) { this.ephemeral = v; return this; }
853-
/** Sets the {@code --skip-git-repo-check} flag. */
903+
/**
904+
* Sets the {@code --skip-git-repo-check} flag.
905+
*
906+
* @param v {@code true} to skip the git repository precondition check.
907+
* @return this builder for chaining.
908+
*/
854909
public ExecOptions skipGitRepoCheck(boolean v) { this.skipGitRepoCheck = v; return this; }
855-
/** Sets the {@code --oss} flag. */
910+
/**
911+
* Sets the {@code --oss} flag.
912+
*
913+
* @param v {@code true} to use the OSS provider instead of OpenAI-hosted models.
914+
* @return this builder for chaining.
915+
*/
856916
public ExecOptions oss(boolean v) { this.oss = v; return this; }
857-
/** Sets the {@code --local-provider} flag. */
917+
/**
918+
* Sets the {@code --local-provider} flag.
919+
*
920+
* @param v the local provider name (e.g. {@code lmstudio}, {@code ollama}).
921+
* @return this builder for chaining.
922+
*/
858923
public ExecOptions localProvider(String v) { this.localProvider = v; return this; }
859-
/** Sets the {@code --search} flag. */
924+
/**
925+
* Sets the {@code --search} flag.
926+
*
927+
* @param v {@code true} to enable the web-search tool during execution.
928+
* @return this builder for chaining.
929+
*/
860930
public ExecOptions search(boolean v) { this.search = v; return this; }
861-
/** Sets the {@code --image} flag. */
931+
/**
932+
* Sets the {@code --image} flag.
933+
*
934+
* @param v path to an image attachment forwarded to the agent.
935+
* @return this builder for chaining.
936+
*/
862937
public ExecOptions image(String v) { this.image = v; return this; }
863-
/** Sets one or more {@code -c key=value} overrides. */
938+
/**
939+
* Sets one or more {@code -c key=value} overrides.
940+
*
941+
* @param v configuration override entries; each element becomes a separate {@code -c} flag.
942+
* @return this builder for chaining.
943+
*/
864944
public ExecOptions configOverrides(String... v) { this.configOverrides = v; return this; }
865-
/** Sets the {@code --dangerously-bypass-approvals-and-sandbox} flag. */
945+
/**
946+
* Sets the {@code --dangerously-bypass-approvals-and-sandbox} flag.
947+
*
948+
* @param v {@code true} to bypass ALL approval prompts and the OS sandbox.
949+
* @return this builder for chaining.
950+
*/
866951
public ExecOptions dangerouslyBypassApprovalsAndSandbox(boolean v) { this.dangerouslyBypassApprovalsAndSandbox = v; return this; }
867-
/** Sets the {@code --dangerously-bypass-hook-trust} flag. */
952+
/**
953+
* Sets the {@code --dangerously-bypass-hook-trust} flag.
954+
*
955+
* @param v {@code true} to skip trust verification for plugin hooks.
956+
* @return this builder for chaining.
957+
*/
868958
public ExecOptions dangerouslyBypassHookTrust(boolean v) { this.dangerouslyBypassHookTrust = v; return this; }
869-
/** Sets the {@code --strict-config} flag. */
959+
/**
960+
* Sets the {@code --strict-config} flag.
961+
*
962+
* @param v {@code true} to fail fast on unknown configuration keys.
963+
* @return this builder for chaining.
964+
*/
870965
public ExecOptions strictConfig(boolean v) { this.strictConfig = v; return this; }
871-
/** Sets one or more {@code --enable} flags. */
966+
/**
967+
* Sets one or more {@code --enable} flags.
968+
*
969+
* @param v feature flag names to enable.
970+
* @return this builder for chaining.
971+
*/
872972
public ExecOptions enable(String... v) { this.enable = v; return this; }
873-
/** Sets one or more {@code --disable} flags. */
973+
/**
974+
* Sets one or more {@code --disable} flags.
975+
*
976+
* @param v feature flag names to disable.
977+
* @return this builder for chaining.
978+
*/
874979
public ExecOptions disable(String... v) { this.disable = v; return this; }
875980

876981
/**
@@ -925,7 +1030,7 @@ public String[] toArgs() {
9251030
* {@code "exec"} because the global flags apply to whichever sub-command
9261031
* follows them.</p>
9271032
*
928-
* @author easy-4-java contributors
1033+
* @author [@Loong Wan](https://github.com/loong10k)
9291034
* @since 3.0.0
9301035
*/
9311036
public static class GlobalOptions {
@@ -947,39 +1052,124 @@ public static class GlobalOptions {
9471052
private String[] disable;
9481053
private boolean noAltScreen;
9491054

950-
/** Sets the {@code --model} flag. */
1055+
/**
1056+
* Sets the {@code --model} flag.
1057+
*
1058+
* @param v the model identifier (e.g. {@code gpt-5-codex}).
1059+
* @return this builder for chaining.
1060+
*/
9511061
public GlobalOptions model(String v) { this.model = v; return this; }
952-
/** Sets the {@code --sandbox} flag. */
1062+
/**
1063+
* Sets the {@code --sandbox} flag.
1064+
*
1065+
* @param v the sandbox mode (e.g. {@code read-only}, {@code workspace-write}).
1066+
* @return this builder for chaining.
1067+
*/
9531068
public GlobalOptions sandbox(String v) { this.sandbox = v; return this; }
954-
/** Sets the {@code --ask-for-approval} flag. */
1069+
/**
1070+
* Sets the {@code --ask-for-approval} flag.
1071+
*
1072+
* @param v the approval policy (e.g. {@code untrusted}, {@code on-request}, {@code never}).
1073+
* @return this builder for chaining.
1074+
*/
9551075
public GlobalOptions approvalPolicy(String v) { this.approvalPolicy = v; return this; }
956-
/** Sets the {@code --profile} flag. */
1076+
/**
1077+
* Sets the {@code --profile} flag.
1078+
*
1079+
* @param v the configuration profile name.
1080+
* @return this builder for chaining.
1081+
*/
9571082
public GlobalOptions profile(String v) { this.profile = v; return this; }
958-
/** Sets the {@code -C} flag. */
1083+
/**
1084+
* Sets the {@code -C} flag.
1085+
*
1086+
* @param v the working directory for the CLI process.
1087+
* @return this builder for chaining.
1088+
*/
9591089
public GlobalOptions workingDir(String v) { this.workingDir = v; return this; }
960-
/** Sets the {@code --add-dir} flag. */
1090+
/**
1091+
* Sets the {@code --add-dir} flag.
1092+
*
1093+
* @param v additional directory granted to the agent at runtime.
1094+
* @return this builder for chaining.
1095+
*/
9611096
public GlobalOptions addDir(String v) { this.addDir = v; return this; }
962-
/** Sets the {@code --oss} flag. */
1097+
/**
1098+
* Sets the {@code --oss} flag.
1099+
*
1100+
* @param v {@code true} to use the OSS provider instead of OpenAI-hosted models.
1101+
* @return this builder for chaining.
1102+
*/
9631103
public GlobalOptions oss(boolean v) { this.oss = v; return this; }
964-
/** Sets the {@code --local-provider} flag. */
1104+
/**
1105+
* Sets the {@code --local-provider} flag.
1106+
*
1107+
* @param v the local provider name (e.g. {@code lmstudio}, {@code ollama}).
1108+
* @return this builder for chaining.
1109+
*/
9651110
public GlobalOptions localProvider(String v) { this.localProvider = v; return this; }
966-
/** Sets the {@code --search} flag. */
1111+
/**
1112+
* Sets the {@code --search} flag.
1113+
*
1114+
* @param v {@code true} to enable the web-search tool during execution.
1115+
* @return this builder for chaining.
1116+
*/
9671117
public GlobalOptions search(boolean v) { this.search = v; return this; }
968-
/** Sets one or more {@code --image} flags. */
1118+
/**
1119+
* Sets one or more {@code --image} flags.
1120+
*
1121+
* @param v paths to image attachments forwarded to the agent.
1122+
* @return this builder for chaining.
1123+
*/
9691124
public GlobalOptions image(String... v) { this.image = v; return this; }
970-
/** Sets one or more {@code -c key=value} overrides. */
1125+
/**
1126+
* Sets one or more {@code -c key=value} overrides.
1127+
*
1128+
* @param v configuration override entries; each element becomes a separate {@code -c} flag.
1129+
* @return this builder for chaining.
1130+
*/
9711131
public GlobalOptions configOverrides(String... v) { this.configOverrides = v; return this; }
972-
/** Sets the {@code --dangerously-bypass-approvals-and-sandbox} flag. */
1132+
/**
1133+
* Sets the {@code --dangerously-bypass-approvals-and-sandbox} flag.
1134+
*
1135+
* @param v {@code true} to bypass ALL approval prompts and the OS sandbox.
1136+
* @return this builder for chaining.
1137+
*/
9731138
public GlobalOptions dangerouslyBypassApprovalsAndSandbox(boolean v) { this.dangerouslyBypassApprovalsAndSandbox = v; return this; }
974-
/** Sets the {@code --dangerously-bypass-hook-trust} flag. */
1139+
/**
1140+
* Sets the {@code --dangerously-bypass-hook-trust} flag.
1141+
*
1142+
* @param v {@code true} to skip trust verification for plugin hooks.
1143+
* @return this builder for chaining.
1144+
*/
9751145
public GlobalOptions dangerouslyBypassHookTrust(boolean v) { this.dangerouslyBypassHookTrust = v; return this; }
976-
/** Sets the {@code --strict-config} flag. */
1146+
/**
1147+
* Sets the {@code --strict-config} flag.
1148+
*
1149+
* @param v {@code true} to fail fast on unknown configuration keys.
1150+
* @return this builder for chaining.
1151+
*/
9771152
public GlobalOptions strictConfig(boolean v) { this.strictConfig = v; return this; }
978-
/** Sets one or more {@code --enable} flags. */
1153+
/**
1154+
* Sets one or more {@code --enable} flags.
1155+
*
1156+
* @param v feature flag names to enable.
1157+
* @return this builder for chaining.
1158+
*/
9791159
public GlobalOptions enable(String... v) { this.enable = v; return this; }
980-
/** Sets one or more {@code --disable} flags. */
1160+
/**
1161+
* Sets one or more {@code --disable} flags.
1162+
*
1163+
* @param v feature flag names to disable.
1164+
* @return this builder for chaining.
1165+
*/
9811166
public GlobalOptions disable(String... v) { this.disable = v; return this; }
982-
/** Sets the {@code --no-alt-screen} flag. */
1167+
/**
1168+
* Sets the {@code --no-alt-screen} flag.
1169+
*
1170+
* @param v {@code true} to disable the alternate-screen mode in the interactive TUI.
1171+
* @return this builder for chaining.
1172+
*/
9831173
public GlobalOptions noAltScreen(boolean v) { this.noAltScreen = v; return this; }
9841174

9851175
/**

‎src/main/java/io/github/easy4j/codex/cli/CodexCliExecutor.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@
4545
* injected configuration) so it can be safely shared between threads and
4646
* pooled by higher-level components.</p>
4747
*
48-
* @author easy-4-java contributors
48+
* @author [@Loong Wan](https://github.com/loong10k)
4949
* @since 3.0.0
5050
* @see CodexCliResult
5151
*/

‎src/main/java/io/github/easy4j/codex/cli/CodexCliResult.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@
3434
* encapsulate the common predicate checks so that callers do not have to
3535
* inspect the raw exit code or stderr payload themselves.</p>
3636
*
37-
* @author easy-4-java contributors
37+
* @author [@Loong Wan](https://github.com/loong10k)
3838
* @since 3.0.0
3939
* @see CodexCliExecutor
4040
* @see CodexCli

‎src/main/java/io/github/easy4j/codex/model/CodexDoctorReport.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@
3030
* the raw JSON shape. Unknown properties are tolerated so the SDK remains
3131
* compatible with future CLI versions.</p>
3232
*
33-
* @author easy-4-java contributors
33+
* @author [@Loong Wan](https://github.com/loong10k)
3434
* @since 3.0.0
3535
* @see CodexEvent
3636
*/

‎src/main/java/io/github/easy4j/codex/model/CodexEvent.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@
3333
* who need strongly-typed access should re-deserialise those fields with
3434
* Jackson once the concrete schema is known.</p>
3535
*
36-
* @author easy-4-java contributors
36+
* @author [@Loong Wan](https://github.com/loong10k)
3737
* @since 3.0.0
3838
* @see CodexDoctorReport
3939
* @see CodexSession

‎src/main/java/io/github/easy4j/codex/model/CodexSession.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@
3030
* <p>Unknown fields are intentionally tolerated so the SDK stays forward
3131
* compatible with future CLI revisions.</p>
3232
*
33-
* @author easy-4-java contributors
33+
* @author [@Loong Wan](https://github.com/loong10k)
3434
* @since 3.0.0
3535
* @see CodexEvent
3636
*/

0 commit comments

Comments
 (0)