On this page
Generation with codepotx
codepotx treats generation as a planned transaction rather than a direct template-to-files loop. A task binds an authoring source, a template pack, an output root, project variables, commands, and cleanup policy. The runtime resolves and validates every dependency before project files are changed.
Generation inputs
A generation task is normally declared in CodepotFile.yml:
allow: true is an intentional execution gate. Generation and configured commands must not run when the project has not explicitly enabled them.
The exact task contract continues to evolve with the active workspace package, but the stable responsibilities are already clear:
- resolve authoring and template sources;
- compile both sources into versioned artifacts;
- validate required template variables and capabilities;
- produce a complete generation plan;
- render files in memory;
- apply lifecycle and ownership policy;
- execute approved commands;
- return structured diagnostics and reports.
Planning before mutation
A GenerationPlan describes the intended work before the filesystem is changed. It includes output paths, lifecycle modes, dependencies, commands, cleanup actions, diagnostics, and refusals.
Use the runtime or CLI to inspect the plan:
A dry run must not write files, delete stale files, or execute before/after commands. It is the recommended first step after changing contracts, templates, task variables, or lifecycle settings.
Rendering in memory
Templates render into a virtual result before writes begin. This separates template errors from filesystem mutation and makes the rendered generation inspectable by terminals, web tools, editor integrations, tests, and AI-assisted workflows.
The rendered result records:
- output path;
- rendered content or binary payload;
- lifecycle mode;
- template and selector provenance;
- dependency and import information;
- diagnostics.
Managed and immutable files
codepotx distinguishes generated ownership from project ownership.
Managed files
Managed files belong to the generator within approved roots. They may be created, refreshed, and removed when a later manifest proves they are stale.
Immutable files
Immutable files are created only when absent. Existing files are preserved so developers can own and edit them safely after the initial scaffold.
Protected or refused writes
A planned output is refused when it escapes the configured output boundary, conflicts with lifecycle policy, attempts unsafe cleanup, or otherwise violates the generation contract. A refusal is a result that callers can display and inspect; it must not be silently converted into a write.
Manifests and stale cleanup
Successful managed generation records a manifest describing files owned by the task. A later run can compare the new plan with the previous manifest and remove only files that are both:
- known to have been generated by that task; and
- located inside an approved cleanup root.
This prevents broad directory deletion and makes stale cleanup deterministic.
Atomic application and rollback
The generation engine plans and renders before applying changes. Filesystem mutation uses platform services that support changed-aware writes, temporary files, atomic replacement, and transaction reporting.
When a required step fails, the result records the failed stage and rollback information. Frontends should display the structured failure rather than infer success from partial console output.
Commands
Tasks may include project-owned commands such as formatting or validation. Commands are part of the plan and run only when generation is allowed and the caller has not requested a dry run or a skip option.
Commands should remain narrow, deterministic, and reviewable. Compiler or generator behavior belongs in codepotx, not in shell scripts hidden behind a task.
Cancellation and events
Long-running operations accept cancellation through platform services. Runtime lifecycle events are observational: listeners can report progress, but listener failure must not change required generation control flow.
Typical events cover source resolution, compilation, planning, rendering, writing, cleanup, commands, completion, and failure.
Recommended workflow
- Validate the project configuration.
- Inspect required variables.
- Generate a JSON plan.
- Run a dry run.
- Review file ownership and cleanup actions.
- Execute generation.
- Run project tests or validation.
- Commit generated changes together with the contract, templates, and manifest when appropriate.