Skip to content

Replace App Builder generated strings with declarative templates #144

Description

@kattsushi

Requested outcome

Replace imperative generated-file and workspace-root TypeScript template strings with real parameterized template files, and make the Nx adapter materialize them through @nx/devkit.generateFiles.

This is a blocking child correction of #131. It follows ready PR #143 at 66bfa635feb61fc8f19556d96dbc22dd695148a9, which targets #141. The correction must be implemented and reviewed before the current chain merges.

Problem

The current App Builder implementation keeps generated output behind imperative TypeScript assembly:

  • templates/todo/index.ts embeds generated TypeScript source as strings;
  • workspace-root and package-surface generators assemble source and JSON imperatively;
  • the Nx adapter writes pre-rendered contributions directly and does not call generateFiles;
  • the declarative source of truth therefore does not resemble the generated workspace closely enough for maintainers to inspect and evolve safely.

Current Nx guidance is to use generateFiles(tree, templateDir, targetDir, substitutions), with an absolute template source directory, a Tree-relative target, filename substitutions, and EJS content substitutions.

Required behavior

  • Store generated TypeScript sources and workspace-root files as real parameterized template assets in an output-shaped template tree close to the generated result.
  • Make the Nx adapter call @nx/devkit.generateFiles with the correct Tree, template directory, target directory, and substitutions.
  • Keep one declarative template source of truth shared by CLI and Nx materialization while preserving host-specific write boundaries.
  • Preserve the typed pure generation kernel, catalog composition, planning, and replay contracts; template rendering must not move filesystem or Tree mutation authority into the kernel.
  • Preserve atomic capability ownership, duplicate-path rejection, deterministic ordering, replay completeness, path safety, prevalidation, and rollback behavior.
  • Preserve CLI/Nx equivalence and the frozen Todo v1 contract.

Acceptance criteria

  • Generated TypeScript sources and workspace-root files are represented by real parameterized template files rather than embedded generated-source strings.
  • The template directory remains visibly aligned with the generated output layout and contains the declarative source of truth used by both public adapters.
  • Focused Nx tests prove @nx/devkit.generateFiles is invoked with the expected Tree, absolute template directory, Tree-relative target directory, and substitutions, and that it materializes the expected files.
  • CLI and Nx produce byte-identical output for the same validated render context.
  • The independent frozen Todo v1 fixture remains compatible with all 18 expected outputs and its existing digest/parity assertions remain unchanged.
  • The typed pure kernel, planning, and replay contracts remain intact, including complete output identities before reads.
  • Atomic generators retain exclusive capability and surface ownership; no duplicate output paths or competing root/package-surface owners are introduced.
  • Unsafe, escaping, or unlisted root paths still fail before mutation, and failures retain rollback semantics without partial output.
  • No imperative generated TypeScript source or workspace-root file strings remain in templates/todo/index.ts, workspace-root generators, package-surface generators, or CLI/Nx adapters. Any remaining imperative serialization must be limited to justified metadata, documented in the PR, and covered by focused tests.
  • Full affected Nx verification passes, including lint, typecheck, test, and build targets, plus App Builder generation, CLI, Nx adapter, frozen parity, path-safety, rollback, and isolated public equivalence evidence.

Delivery constraint

The maintainer explicitly approved a size:exception for this correction:

  • deliver one consolidated child PR only;
  • do not split the correction;
  • maximum review budget: 2,000 changed lines (additions + deletions);
  • record the final changed-line count and exception rationale in the PR chain context.

This exception applies only to this declarative-template correction and overrides the normal 400-line chained-PR split threshold.

Out of scope

  • Redesigning or weakening the typed generation kernel, planning, or replay contracts.
  • Changing the frozen Todo v1 18-output public contract.
  • Adding unrelated App Builder capabilities.
  • Regenerating, editing, retargeting, or otherwise mutating PR feat(app-builder): regenerate canonical Todo showcase #130.
  • Publishing or modifying any implementation before this approved issue is linked from its child PR.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions