[codex] Structure ACP schema generator errors

[juliusmarminge]

Summary

• add structured Schema errors for ACP asset download/storage, document decoding, formatter processes, and generator invariants
• preserve immediate HTTP, filesystem, schema, and process causes while attaching URL/path/command context
• register downloaded-asset cleanup before either request so partial downloads are cleaned up on failure

Validation

• vp test packages/effect-acp/scripts/generate.test.ts --no-cache
• vp check (passes with pre-existing warnings)
• vp run typecheck
• vpr typecheck

Overlap audit

No current open PR touches either changed path, including previous filenames.

---

Note

Low Risk
Dev-tooling and error-shape changes in the generator script only; no runtime auth, data, or production API impact.

Overview
Replaces the single generic generator failure type with Effect Schema tagged errors that carry URL, output path, pipeline stage, document kind, formatter command/args, and exit codes while preserving underlying causes.

Download and decode paths map HTTP, filesystem, and JSON decode failures into distinct error classes; schema/metadata decoding goes through exported helpers that attach file path context. Formatting is centralized in formatGeneratedFiles, and malformed generated type/const pairs now fail with dedicated invariant errors instead of plain Error.

Operational tweaks: downloaded upstream asset cleanup is registered before the HTTP fetches so partial runs still remove temp files, and the CLI only runs when import.meta.main is true so tests can import the module safely.

Adds Vitest coverage for failed HTTP download, write-to-directory failure, document decode context, and nonzero formatter exit codes.

^{Reviewed by Cursor Bugbot for commit 15152d6. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Structure ACP schema generator errors into tagged error classes

• Replaces the generic GenerateCommandError interface with seven tagged error classes (AcpGeneratorDownloadError, AcpGeneratorDownloadFileError, AcpGeneratorDocumentDecodeError, AcpGeneratorFormatProcessError, AcpGeneratorFormatExitError, AcpGeneratorSchemaValueDeclarationMissingError, AcpGeneratorSchemaNameParseError) in generate.ts, each carrying structured context (stage, file path, exit code, etc.).
• Adds decodeUpstreamSchemaDocument and decodeMetaDocument helpers so decode failures carry document type and file path context.
• Extracts formatter invocation into formatGeneratedFiles, which maps spawn/exit failures to structured errors including exit code.
• Wraps the Command.run entrypoint in an import.meta.main guard so importing the module no longer triggers execution.
• Adds test coverage in generate.test.ts for download, write, decode, and formatter exit error paths.
• Behavioral Change: the module no longer auto-executes when imported; it must be run as the program entrypoint.

^{Macroscope summarized 15152d6.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 96d6ac6e-2486-4ba7-9f43-b9c7fcc320a7

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/acp-generator-errors

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[macroscopeapp]

Approvability

Verdict: Approved

This PR improves error handling in internal code generation scripts by adding structured error classes and comprehensive tests. Changes are isolated to developer tooling with no runtime application impact.

No code changes detected at 15152d6. Prior analysis still applies.

^{You can customize Macroscope's approvability policy. Learn more.}