Console Laravel Package

Getting Started

Ichiloto Console is a globally installed CLI toolchain, not a package you require into a Laravel app. Install the complete Console → Editor → Engine graph:

composer global require ichiloto/console:^0.5 --with-all-dependencies

Make sure ~/.config/composer/vendor/bin (or ~/.composer/vendor/bin) is on your PATH, then run ichiloto list to see the 0.5 command surface: validate, battle, upgrade, edit, generate:figlet, and the project/actor/map generators.

First use case — validate an existing project read-only:

cd my-rpg
ichiloto validate

This loads the project the way the runtime would and runs the Editor's shared ProjectValidator over authored content: references, identity collisions, maps/NPCs, events/cutscenes, summons, achievements, battle escape policy, equipment optimization, and save metadata. If the project predates Engine 0.5, run ichiloto upgrade first, commit assets/Data/save-compatibility.php, then re-validate. Where to look first in a project: that compatibility manifest and the generated project metadata (identity, supported controls, save envelope settings) — those are what 0.5 changed.

Implementation Patterns

• CI validation gate. Add ichiloto validate before tests/deploy. It reads project namespaces without modifying authored data, so it is safe on every branch, and exit codes make it a natural gate.
• Balancing loop. Use ichiloto battle as a repeatable experiment: tweak actors, enemies, skills, and equipment, rerun, and diff reports (participants, actions, damage, states, rewards, outcome). Participants are restored after each simulation, so repeated runs compare cleanly.
• Legacy migration workflow. Treat upgrade as a one-time migration: run it, review the generated save-compatibility.php, commit it, run validate, then smoke-test a real old save. The manifest is the explicit place to declare renamed or removed content.
• Scaffold, then generate. New Engine 0.5 projects start with stable identity, save metadata, and supported controls already wired. Actor/map generators now have overwrite protection — still run them with a clean git status so regenerated definitions are reviewable.
• Editor round-trip. ichiloto edit opens the full-screen authoring workspace. Pair it with validate in a tight loop (author → validate → fix) instead of discovering broken references at runtime.
• Project-local ergonomics. Since the binary is global, wrap common calls in Composer scripts ("validate": "ichiloto validate") or a bin/ shim; in Docker/CI, install globally inside the image.

Gotchas and Tips

• PHP 8.4.1+ and Symfony Console 8 are hard requirements. Check CI base images and local PHP before upgrading — this is the most likely blocker.
• Keep it global, not a project dependency. Requiring ichiloto/console inside a Laravel app can drag Symfony Console 8 into an app pinned to Console 7. Install globally and invoke the binary.
• Use --with-all-dependencies. Console 0.5 pins Editor 0.5, which pins Engine 0.5; a plain composer global update ichiloto/console can leave stale transitive versions.
• Run from the project root. Project loading is based on the selected working directory; running from a subdirectory can load the wrong project or fail.
• upgrade writes files. It adds project identity and save-compatibility metadata. Run once per legacy project, commit the manifest, and review the diff rather than assuming it is a no-op.
• Validation checks declared metadata, not intent. It flags missing or invalid save-compatibility entries, but cannot infer that OldSkill became NewSkill — you must describe that in the manifest.
• Battle restoration covers normal runs, not crashes. If a simulation aborts mid-run, do not assume in-process state was restored; the separate CLI process is the safe boundary.
• Overwrite protection isn't version control. Generators are safer in 0.5, but review generated actor/map definitions before committing.
• Debugging: use Symfony verbosity (-v, -vvv) and ichiloto list for discovery; branch on exit codes in scripts rather than scraping output.
• Extension point: validation shares the Editor's ProjectValidator, so satisfying validate also fixes what the Editor enforces during authoring.