fix(exit-codes): a nonexistent project path is a usage error (exit 2), not a manifest-less project

[ZacxDev]

Closes #256.

The defect

validate.Dir stats the joined <dir>/block.manifest.json and branches on os.IsNotExist, which collapses "the directory does not exist" into "the directory exists but has no manifest". Measured on the base binary built from origin/main@8ed4d69:

invocation	base	this PR
app validate /nope/does/not/exist	✗ 1 validation error(s) … block.manifest.json not found at project root /nope/does/not/exist — rc 1	Error: /nope/does/not/exist: no such directory — pass the path to an App project root, or scaffold one with \civitai app init `` — rc 2
app validate README.md	Error: stat README.md/block.manifest.json: not a directory — a path the CLI assembled and the user never typed — rc 1	Error: README.md is not a directory — pass the App project ROOT (the directory holding block.manifest.json), not a file — rc 2
app validate <dir with no manifest>	rc 1	rc 1, byte-identical (control)
app submit /nope/does/not/exist --package-only	✗ validation failed (1 error(s)) … not found at project root — rc 1	rc 2, same message as validate

The published contract says a path that does not exist is a mistake about the invocation and exits 2; civitai generate --input /nope/x.json has honoured that since #251. app submit <dir> carried the identical hole — the fourth instance of the "one predicate, N copies, found one at a time" shape AGENTS item 24 exists to prevent.

The fix

resolveProjectDir (internal/cmd/project_dir.go) branches three ways on the path the user named, never the joined manifest path:

does not exist      -> asUsageError  (exit 2)
exists, not a dir   -> asUsageError  (exit 2)
a directory         -> nil; validate.Dir decides, unchanged
other stat failure  -> untagged      (exit 1 — the #241 answer for ENOTDIR/EACCES)

A directory that exists with no manifest is deliberately unchanged: the user pointed at a real place, so the invocation was right and the project is wrong. That is a validation verdict, not a usage error.

Two placement decisions worth reviewing:

• The gate is in internal/cmd, not internal/validate. ErrUsage is this package's sentinel (AGENTS item 7) and validate.Dir returns a validation verdict; pushing the tag down would make internal/validate import the usage sentinel and hold a slice of the exit-code contract. app init's validate.ManifestOnly self-check is untouched — it validates a directory it just created and has no user-named path to classify.
• One helper, both call sites, and the set is asserted. TestEveryValidateDirCallerGatesOnResolveProjectDir AST-walks the package and requires the set of files calling validate.Dir to equal the set calling resolveProjectDir — it fails when the set grows (a third command validating a user-named directory without the gate) and when it shrinks (a deleted gate, which would otherwise leave the ledger a false map). In app submit the gate runs ahead of --skip-validate, because "does the directory you typed exist" is not a validation opinion to waive.

🔴 Deliberate --json wire break

civitai app validate /nope --json used to print a fabricated validation result and exit 1:

{ "dir": "/nope", "errors": [ { "field": "(root)", "message": "block.manifest.json not found at project root /nope" } ], "ok": false, "warnings": [] }

It now writes nothing to stdout and exits 2. A path that does not exist produced no validation result to report, and this keeps the CLI-wide convention that a usage error emits no JSON object. This is a break of the same class as item 23's notation change, and it is announced in the code-2 README cell ("A usage error emits no JSON object, in every mode … Scripts that parsed that object must branch on the exit code first"). Scripts that read .ok for a possibly-missing path must branch on $? first.

--json for a real directory is unaffected: app validate <dir with no manifest> --json still emits the full object and exits 1 (asserted as a positive control, so "stdout is empty" cannot be satisfied by a --json mode that never prints).

Contract text

Both surfaces are generated from exitCodeDocs, so this is one edit that moves --help and the README table together (the README table region is regenerated, not hand-edited — TestREADMEExitCodeTableIsGenerated enforces byte-identity).

• Code 2's note was itself inaccurate: it read "that split is the rule for every local path a flag names", and the two commands that broke it take the path positionally, so the sentence structurally excluded exactly the cases that disagreed with it. Widened to "every local path the CLI is handed — a flag's value and a positional argument alike", plus an explicit clause for app validate <dir> / app submit <dir>.
• Code 1 gained app validate's own exit code, which was documented nowhere despite being the most common outcome of the most-run command: a validation verdict is 1, a manifest-less directory is the same verdict, and --json's ok field is the structured form of the answer.
• exitCodeContractClaims (the decision ledger asserted against both rendered surfaces) gains rows for the widened wording, the new project-path rule, and the counterweight (a validation verdict stays 1), so the narrower sentence cannot come back quietly.

Tests

internal/cmd/project_dir_test.go, driving the real commands through NewRootCmd() + SetArgs. Every classification assertion is errors.Is(err, ErrUsage) — never message text (item 7): asUsageError preserves the message byte for byte, so a wording assertion says nothing about echo $?.

• TestProjectDirExitCodes — 4 rows × validate and submit (the shared gate means both must answer identically): missing path → usage; regular file → usage; CONTROL real directory without a manifest → not usage; CONTROL valid project → no error.
• TestProjectDirRefusalNamesThePathTheUserTyped — a negative assertion that the assembled <file>/block.manifest.json is absent from the message (survives any rewording of the replacement, which a positive assertion would not), plus that the path the user typed is present.
• TestValidateJSONEmitsNothingForARefusedPath — the wire break, with the positive control above.
• TestResolveProjectDirClassification — unit rows including two controls: the default . must pass the gate, and ENOTDIR below a regular file must stay untagged (exit 1, the Every filesystem error exits 5 (the retry code): syscall.Errno satisfies net.Error, so isNetworkErr matches through *fs.PathError #241 answer).
• TestEveryValidateDirCallerGatesOnResolveProjectDir — the seam ledger, with a count floor so a pass cannot be built on two empty sets.

Mutation matrix

Every mutant checksum-gated (an edit that failed to apply exits non-zero rather than reading as a survivor). Counts are --- FAIL lines, leaf + parent, over the new tests plus the two doc guards. Baseline: RUN=34, FAIL=0, build errors=0.

mutant	FAIL lines	what reddened
M1 delete the gate from both call sites (= origin/main)	14	all 8 leaf rows: both exit-2 rows × both commands, both message rows, both --json rows, the seam guard
M2 gate runs but returns plain fmt.Errorf (classification gone, messages byte-identical)	13	the 4 exit-2 command rows, both --json rows, both unit rows — nothing message-based could have seen this
M3 the over-fix: tag every validation failure as a usage error	4	only the CONTROL rows (manifest-less directory, and the --json positive control) — this is what stops "tag everything" from passing
M4 gate moved below the --json block (old wire behaviour restored)	8	exactly the 3 --json/regular-file rows; the text-mode path does not exist row stays green, so an exit-code-only table would have missed it
M5 gate dropped from app submit only (one rule, two places)	7	the 2 submit rows, the submit message row, and the seam guard by name
M6 revert the widened code-2 wording	3	TestPublishedExitCodeClaims/…flag_OR_positional + TestREADMEExitCodeTableIsGenerated
M7 hand-edit the README table	1	TestREADMEExitCodeTableIsGenerated

Both directions are covered: M1/M2 prove the new tests see the defect, M3 proves the controls stop the over-fix, M5 proves the shared-helper ledger is not decorative.

Gate

make ci green. Read from the output, not the exit code: --- FAIL = 0, build failed = 0, 18/18 packages ok, gofmt -s -l . prints nothing over 298 .go files.

AGENTS.md

Item 24 gains a bullet for this fourth instance — the collapsed os.IsNotExist branch, the internal/cmd boundary, the asserted call-site set, the --json break, and the untagged-ENOTDIR residual. No existing item was renumbered.

🤖 Generated with Claude Code