cli

cli — audit issues

Audited 2026-06-20. Repo: software/cli. Criteria: completeness · tests · separation of concerns · verb-named functions · file size (<1000 lines) · organization.

Health summary

A small, clean, well-factored CLI: four subcommands (check, convert, pack, unpack) across 436 lines of source split sensibly into arg-parsing (main.cpp), a format/codec layer (Convert), and bundle I/O (Pack). It builds with no warnings and test.sh passes all 25 smoke assertions. The main defects are documentation/usage-string format-name drift (a --from/--to value the usage advertises is actually rejected), gaps in test coverage for convert argument-parsing and several pack/unpack error paths, and a stale-binary/no-real-help polish layer. Nothing is a stub or unimplemented; severity is concentrated in MEDIUM and LOW.

Issues

[MEDIUM] completeness — usage string advertises an invalid format name (kinogaki)

• Where: src/main.cpp:44
• Problem: The usage text lists fmt = prisma | kinogaki | json | markdown | html | svg | text | blob, but formatByName (src/Convert.cpp:76) accepts the binary native format only under the name prism, never kinogaki. So convert in out --from kinogaki (copied straight from the tool's own help) fails with a bare usage error, while the genuinely-valid name prism is never advertised. The help is self-contradicting and misleads the user away from the working flag value.
• Fix: Change the usage line to fmt = prisma | prism | json | markdown | html | svg | text | blob, matching formatByName/formatName. Same fix applies to the README (see organization issue below).

[MEDIUM] tests — convert argument parsing and --from/--to are untested

• Where: test.sh (whole file); parser at src/main.cpp:128-145
• Problem: Every convert test relies on extension/content inference; the explicit --from <fmt> / --to <fmt> flags and formatByName are never exercised, nor is any malformed-args path (unknown flag, --from with a bad/missing value, too many/too few positionals, bogus subcommand). The format-name bug above survived precisely because no test passes a --from value. There is also no assertion that a forced format overrides inference.
• Fix: Add cases: convert --from json data.txt out.prisma (force input fmt against a misleading extension); --to prism forcing output; --from bogus → exit 2; convert a b c (extra positional) → exit 2; unknown --flag → exit 2; bad subcommand → exit 2. These are one-line expect "$rc" "2" ... additions.

[MEDIUM] tests — pack/unpack error paths and .prisma-text bundles untested

• Where: test.sh:76-89; error paths in src/Pack.cpp:87,95,102,105,106,77
• Problem: Only the happy path (pack a dir → .prism → unpack) is covered. Untested: pack on a non-directory (Pack.cpp:87 → exit 1), unpack on a non-bundle / unparseable input (Pack.cpp:105-106 → exit 1, verified working by hand but unguarded by tests), packing to/unpacking the editable .prisma text form (Pack.cpp:94 chooses text vs compressed binary by suffix — a whole branch with zero coverage), and an empty / dotfile-only directory. A regression in any of these would pass CI.
• Fix: Add a pack site site.prisma round-trip assertion plus negative cases: pack a regular file → exit 1; unpack a good.prisma non-bundle → exit 1; pack a dir containing only a dotfile and confirm it is skipped.

[LOW] organization — README is stale: duplicate format name, missing pack/unpack sections, wrong dependency claim

• Where: README.md:9 and README.md:1-67
• Problem: Line 9's fmt list reads fmt = kinogaki | kinogaki | json | ... — "kinogaki" appears twice and neither is a real format name (should be prisma | prism). The README's intro (lines 3-4) says the tool only "validate[s] … and convert[s] between formats" and "links KinogakiCore (no other dependencies)", but the tool also has pack/unpack and depends on KinogakiCodecs too (build.sh:7, CMakeLists.txt:19-24). There is no README section documenting pack/unpack beyond the one-line synopsis, unlike the dedicated check/convert sections.
• Fix: Fix line 9 to prisma | prism | json | markdown | html | svg | text | blob; update the intro to mention bundling and the KinogakiCodecs dependency; add a ## pack / unpack section mirroring the existing examples.

[LOW] organization — stale renamed binaries left in build/

• Where: build/prism, build/prisma (alongside build/kinogaki)
• Problem: build/ (gitignored, so not committed — good) still holds two binaries from the pre-rename era (prism, prisma) next to the current kinogaki. They are dead local artifacts that can confuse ./build/<tab> completion and PATH usage after the project's rename to kinogaki.
• Fix: Have build.sh start with rm -rf "$OUT" (or clean only its own product) before mkdir -p "$OUT", so the output dir reflects only the current build. Delete the stale binaries now.

[LOW] completeness — no real --help; usage goes to stderr with exit 2 for any unrecognized command

• Where: src/main.cpp:39-48,112-146
• Problem: README line 64 documents kinogaki --help, but there is no help handling: --help (and -h, no args, or any bad subcommand) all fall through to usage(), which prints to stderr and returns 2. A user explicitly asking for help gets help text on the error stream and a failure exit code — conventionally --help prints to stdout and exits 0. Bad-input → stderr+2 is correct; an explicit help request being treated as an error is not.
• Fix: Special-case --help/-h/help in main to print the same text to stdout and return 0; keep usage() (stderr, exit 2) for the error path.

[LOW] completeness — readFile/writeFile duplicated across translation units

• Where: src/main.cpp:27-37 and src/Pack.cpp:25-35
• Problem: Near-identical readFile/writeFile helpers are defined privately in both main.cpp and Pack.cpp (the only divergence is writeFile's path type: std::string vs fs::path). Minor duplication; a future fix (e.g. better error reporting on partial writes) must be made in two places.
• Fix: Hoist a small io.h/io.cpp (or extend Convert) with shared readFile/writeFile; not urgent given the tiny size.

[LOW] separation — clean

• Argument parsing lives in main.cpp (subcommand dispatch + convert flag loop, main.cpp:112-146); format/codec policy is isolated behind the Convert layer (Convert.h/.cpp) with a single codec registry (Convert.cpp:29-45); bundle filesystem I/O is in Pack. No business logic leaks into main; the command bodies (cmdCheck, cmdConvert, cmdPack, cmdUnpack) are thin and each owns one job. Good layering for a tool this size.

[LOW] naming — clean

• All functions read as verbs: readFile, writeFile, usage, cmdCheck/cmdConvert/cmdPack/cmdUnpack, importToStage, exportFromStage, formatForPath, formatByName, looksNative, looksBinary, packInto, unpackInto, sortedEntries, endsWith, lowerExt. formatName(f) and foreignCodec(f) are noun-named but are conventional getters/lookups, not actions — acceptable. No misleading or ambiguous names found.

[LOW] filesize — clean

• Largest source file is src/main.cpp at 147 lines. All files are well under the 800/1000-line thresholds (Convert.cpp 118, Pack.cpp 112, Convert.h 46, Pack.h 13). No file flagged.