repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

docs(java): refine source script guidance

441fbccf19dc8108bbe078401f616073a3ac948e

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (1)

pi/agent/skills/java-source-scripts/SKILL.md

Modified
11 11 ## Default stance
13 13 - Script invocation is `java path/to/script.java [args...]`.
14 +- Prefer a `.java` extension and explicit `java ...` invocation for cross-platform use.
14 15 - Shebang is allowed for Unix convenience, but never required; Windows does not support it.
15 16 - Prefer standard library only. No Maven/Gradle/JBang/Picocli unless the task explicitly needs them.
16 17 - Prefer one pragmatic file over a package/module/build setup.
17 18 - Use modern Java features and APIs. Terse is good. Boilerplate is not.
19 +- For repo-managed scripts, ensure the script is committed before testing from a fresh clone/container.
19 21 ## Source-file launcher facts
23 25 - The first top-level class, or an instance `void main(String[] args)` / `void main()` on modern Java, is the entry point.
24 26 - JDK 22+ can resolve referenced sibling `.java` files automatically for multi-file source programs.
25 27 - Shebang launch only applies to single-file scripts; for portability still document `java script.java`.
28 +- Source-file mode triggers only when the source file exists; otherwise `java` may treat the argument as a class name.
29 +- If a container image only has a JRE, `java script.java` may work while `javac` does not. Install a JDK when compiling ahead of time.
27 31 ## Shape
74 78 - Prefer `record` for small immutable option/result/config carriers.
75 79 - Prefer early returns over nested control flow.
76 80 - Prefer `Path`, `Files`, `ProcessBuilder`, `HttpClient`, `URI`, `Instant`, `Duration`, `Pattern`, `System.getenv` over shelling out.
81 +- Prefer `Path.of(...)` for new code; use `Paths.get(...)` only when matching older local style.
82 +- Prefer command arrays (`new ProcessBuilder(cmd)`) over shell strings.
77 83 - Prefer loops when clearer; do not force streams.
78 84 - Keep helpers small and named by behavior.
79 85 - Keep constants in one place when repeated.
99 105 Keep OS special cases local to the call site, e.g. `mvnw.cmd` on Windows.
107 +Process helper baseline:
109 +```java
110 +CommandResult runCaptureIgnoreFail( String... cmd ) throws Exception
112 + final var p = new ProcessBuilder( cmd ).redirectErrorStream( true ).start();
113 + final var output = new String( p.getInputStream().readAllBytes() );
114 + return new CommandResult( p.waitFor(), output );
117 +record CommandResult( int exitCode, String output ) {}
118 +```
120 +Use `inheritIO()` for interactive commands; use capture helpers only when the script needs output.
101 122 ## Output and errors
103 124 - Console output is the UI. `IO.println`/`IO.print` are fine.
105 126 - Fail fast on required errors with direct messages.
106 127 - If ignoring errors, make it explicit in helper names or comments.
107 128 - Validate required env vars early. Defaults must be explicit.
129 +- Never print secret env values; print only whether they are set or which variable is missing.
109 131 ## Documentation
123 145 - JavaScript/Node assumptions.
124 146 - Bash/POSIX-only logic when Java stdlib works.
125 147 - Build tools for simple scripts.
148 +- Depending on Bash/POSIX tools for bootstrapping/setup/maintenance when Java stdlib can do it.
126 149 - `public static void main` boilerplate unless compatibility demands it.
127 150 - Mutable tiny config classes; use records.
128 151 - Broad abstractions for cleanliness alone.