Report Builder: file-based persistence (manifest + bands JSON), clone + sync-system

[nielsdrost7]

Status 2026-07-13: implemented on feature/130-report-builder (#608) — as-built notes in the #130 status section.

---

Parent: #130 (Report Builder — bands + bricks). Phase 1. Part of epic #506, Track A.

Scope

Persistence is file-based only — no report_templates table, no DB rows. Layout:

resources/report-templates/                  # shipped, version-controlled
  invoice/default/manifest.json              # { name, slug, type, version }
  invoice/default/bands.json                 # { header: […], group_header: […], details: […], group_footer: […], footer: […] }
  quote/default/{manifest,bands}.json
storage/app/report_templates/                # runtime disk 'report_templates'
  system/…                                   # published via `php artisan reports:sync-system`
  {company_id}/{slug}/{manifest,bands}.json  # company clones

bands.json entries are data only: { "brick": "header_company", "width": "half", "config": { … } } — never code.

Build ReportTemplateStorage (rework of the old branch's MasonTemplateStorage + ReportTemplateFileRepository):

• list($companyId) — disk scan of system/ + the company folder
• loadManifest()/loadBands()/save()/delete()
• clone($from, $companyId, $newName) — copy folder + rewrite manifest (name, slug, cloned_from)
• Validation on load: unknown brick ids skipped, config filtered against the brick's schema, width/band values validated against enums
• Slug sanitization: [a-z0-9-] only, .. rejected; company path always derived from the current tenant, never from user input

Plus the reports:sync-system artisan command (idempotent publish of resources/report-templates/ → storage/app/report_templates/system/).

Acceptance criteria

• Save → load round-trips manifest + bands unchanged.
• Clone copies the folder and rewrites the manifest; the source stays untouched; system templates are read-only.
• ../, uppercase, and non-slug characters are rejected with an exception.
• Company A cannot list or load company B's templates.
• reports:sync-system is idempotent and never touches company folders.
• Loading a bands.json with an unknown brick id or invalid width silently drops that entry (and logs a warning).

Test scenarios (PHPUnit, #[Test], no Pest)

• Round-trip, clone, sanitization, tenant-isolation and sync-idempotency tests (adapt the harvested MasonStorageAdapterTest / ReportTemplateFileRepositoryTest suites to the no-DB design).

[nielsdrost7]

SMART Plan — Report Builder: file-based persistence (manifest + bands JSON), clone + sync-system

Context/Epic: Core (Reports), Track A / Phase 1 of epic #506 — parent #130

Specific

Templates should persist as files only (no report_templates DB table) under a shipped resources/report-templates/ source and a runtime report_templates disk, with a ReportTemplateStorage service handling list/load/save/clone and a reports:sync-system command publishing the shipped defaults. Current state on develop: none of ReportTemplateStorage, resources/report-templates/, or the reports:sync-system command exist (confirmed — no such artisan command class anywhere in Modules/Core/Console). One piece is already real: config/filesystems.php already defines a report_templates disk rooted at storage_path('app/report_templates') — build against that, don't introduce a second one. Note also: storage/app/report_templates/system/{invoice,quote}/default/{manifest,bands}.json currently contain plausible-looking sample data on this machine, but those files are gitignored (storage/app/.gitignore) and not reproducible by anything currently in the codebase — they're leftover artifacts from locally checking out feature/130-report-builder at some point, not evidence this is built on develop.

Measurable

• Save then load round-trips manifest + bands unchanged.
  • PHPUnit: it_round_trips_manifest_and_bands_through_save_and_load()

    #[Test]
    public function it_round_trips_manifest_and_bands_through_save_and_load(): void
    {
        /* Arrange */
        $bands = ['header' => [], 'group_header' => [], 'details' => [], 'group_footer' => [], 'footer' => []];

        /* Act */
        app(ReportTemplateStorage::class)->save('my-template', $this->company->id, $bands);
        $loaded = app(ReportTemplateStorage::class)->loadBands('my-template', $this->company->id);

        /* Assert */
        $this->assertSame($bands, $loaded);
    }

• Clone copies the folder and rewrites the manifest without touching the source.

  • PHPUnit: it_clones_a_template_without_modifying_the_source()

• A slug containing ../ or uppercase characters is rejected.

  • PHPUnit: it_rejects_a_slug_containing_path_traversal_or_uppercase_characters()

    #[Test]
    public function it_rejects_a_slug_containing_path_traversal_or_uppercase_characters(): void
    {
        /* Act & Assert */
        $this->expectException(InvalidArgumentException::class);
        app(ReportTemplateStorage::class)->save('../etc/passwd', $this->company->id, []);
    }

• Company A cannot list or load Company B's templates.

  • PHPUnit: it_does_not_expose_another_companys_templates()

• reports:sync-system is idempotent and never touches company folders.

  • PHPUnit: it_does_not_modify_company_folders_when_syncing_system_templates_twice()

Achievable

1. Build ReportTemplateStorage against the already-configured report_templates disk in config/filesystems.php — no new disk needed.
2. Create resources/report-templates/ (the shipped, version-controlled source) — it doesn't exist yet; seed it with at least invoice/default and quote/default. The leftover storage/app/report_templates/system/* files on this machine show a plausible shape for that data, but aren't authoritative since they're gitignored artifacts, not committed source.
3. Review PR [IP-130]: Report Builder — bands + bricks (IP-130, Phases 1-4 + Browsershot driver) #608 first — it's the origin of both this design and its (unmerged) implementation.
4. This blocks Report Builder: drag & drop bricks within band canvases #519, Report Builder: five band canvases (header, group header, details, group footer, footer) #523, Report Builder: move bricks between bands (move-to-band action) #525 — land it early in Phase 1, alongside Report Builder: code-defined Bricks (fields + config schema) #521.

Relevant

Every other Phase 2 issue needs this storage layer to save and load templates against; without it there's no persistence for anything the builder UI produces.

Time-bound

Sprint 5.