NeitzelFXDesigner/docs/repository-bootstrap-plan.md

# NeitzelFXDesigner repository bootstrap plan

Status: repository foundation implemented by the initial commit; work package 2 has a verified development artifact; work package 3 implements the module/service foundation; work package 4 implements configuration and protocol validation; work package 5 implements Build and Refresh with immutable snapshots; work package 6 validates the preview API and target adapter with real fixtures; work package 7 connects the first workflow in both minimal hosts. Consolidated 2026-11-12. Scope is the ordered implementation start for the [accepted initial contract](initial-project-contract.md); the initial commit creates the foundation only and does not publish a library release.

## Starting-point evidence before bootstrap

- `git ls-remote ssh://git@gitea.neitzel.de:2222/konrad/NeitzelFXDesigner.git` succeeded and advertised no refs. Recheck before bootstrapping; do not overwrite work created meanwhile.
- Canonical workspace is `/Volumes/PlanckSSD/KI/java`. Its catalog requires independent project checkouts and currently has no NeitzelFXDesigner row.
- Workspace sync clones a named catalog branch. Create/push initial `main` before expecting ordinary catalog sync to clone it.
- NeitzelLib has existing local changes, including the Component builder work and unrelated tray changes. Integrate only reviewed Component changes; never sweep the working tree into a release commit.
- Current library coordinates: `de.neitzel.lib:fx:1.0-SNAPSHOT`, parent `de.neitzel.lib:neitzellib:1.0-SNAPSHOT`. The parent POM declares Java 21, JavaFX 21.0.7 and Maven minimum 3.8.6; wrapper scripts exist.
- Inspected library HEAD: `23ad65062f629f2b41fe481c5fe9a541f6da405f` on `feature/native-tray-quit`. The Component builder fix in `fx/src/main/java/de/neitzel/fx/view/Components.java` and its regression fixtures are uncommitted. Existing local tray changes must remain intact. Recheck this state before implementation.
- No local tags or corrected released artifact were established. Remote release publication was not audited. Exact corrected minimum version remains unset; local source/prototype success does not prove publication.
- The parent POM sets Surefire `testFailureIgnore=true`. Override it where effective and inspect test reports; Maven exit success alone is not acceptance evidence.
- No source `module-info.java` was found in the inspected library tree. Qualify the actual automatic/named-module behavior and access requirements in the module-path fixture; do not assume a declared named-module contract.

## Ordered work packages

Work package 1 supplies this repository, documentation, pinned wrapper and `python3 scripts/check-bootstrap.py`. Its remote-main and workspace-registration checks are verified during publication. Work package 2 is now integrated with a verified local development artifact; work package 3 is documented in [module and host boundaries](module-host-boundaries.md).

### 1. Bootstrap the independent repository and workspace registration

Recheck remote refs and destination. Reuse an existing correct checkout if one has appeared; otherwise create the independent checkout at `/Volumes/PlanckSSD/KI/java/NeitzelFXDesigner`. Do not create it inside NeitzelLib or commit its files into the workspace repository.

Create initial `main` with project README, ignore rules, concise project instructions, build entry points and the accepted contract/plan (move their authoritative implementation home into the new repository and leave workspace links). Preserve third-party attribution obligations when bringing over code; do not copy an entire throwaway prototype. Pin actual build-tool versions when verified. Suggested initial project version: `0.1.0-SNAPSHOT`; artifact/group/module spellings are implementation defaults, not previously published coordinates.

The bootstrap must have a reproducible validation command and a truthful README stating which modules are scaffolded versus runnable. Only advertise working commands. Verify the independent Git root and remote, inspect the initial diff, create/push initial main, and verify it exists remotely. Use the workspace-prescribed feature-branch and landing policy for subsequent work.

Then register the checkout in the canonical workspace catalog and retain its root ignore boundary. Proposed row:

| name | kind | remote | branch | language | merge | notes |
| --- | --- | --- | --- | --- | --- | --- |
| NeitzelFXDesigner | app | ssh://git@gitea.neitzel.de:2222/konrad/NeitzelFXDesigner.git | main | java | merge-delete | Shared Kit designer, standalone application and IntelliJ host |

Update the catalog's project count and validate catalog parsing without unnecessarily pulling unrelated checkouts. This plan does not edit the live catalog before the checkout/branch exists.

**Exit:** independent clean checkout, remote main, valid catalog/ignore boundary, documented reproducible bootstrap check.

### 2. Integrate and identify the corrected NeitzelLib artifact

Completed for development: the isolated Component fix is on NeitzelLib main, all 112 reactor tests and 38 adapter-free smoke checks pass, and the matching local artifacts are recorded in [runtime provenance](runtime/neitzellib-baseline.md). A corrected released minimum remains unset; remote artifact publication is separate. The following procedure is retained for reproducibility.

Read the library's current instructions/POM and inspect only the Component builder diff, regression fixtures/tests and related documentation. Preserve unrelated local changes. Run relevant library tests and the direct adapter-free smoke scenario. Verify actual test results despite the parent POM's failure-ignore setting. Capture an isolated library change through its normal feature/landing workflow.

Establish the first release containing the fix through actual artifact/source evidence. Do not invent a minimum version. Until then, fixtures may use a locally installed snapshot with documented source revision, any required patch digest, and build/artifact identity. Record the release/capability prerequisite in compatibility metadata when verified.

**Exit:** isolated validated library change, identifiable usable development artifact and a clear release prerequisite; publication is a separate action, not implied by the plan.

### 3. Establish buildable module and host-service boundaries

Implemented: six shared modules, separate pinned IntelliJ adapter build, minimal host services and regression checks. See [scope and validation](module-host-boundaries.md). This does not complete the first end-to-end designer workflow.

Create the contract's shared artifacts and two host adapters. Define interfaces for document drafts/edit transactions/undo, build execution/output/cancellation, navigation, diagnostics, runtime resolution and lifecycle. Keep UI and IDE dependencies out of contracts/preview artifacts. Verify dependency rules with build checks.

Build shared libraries/fixtures using the Maven structure; verify and pin the actual IntelliJ SDK packaging toolchain, using a separate adapter build if required. Provide one documented orchestration entry point. Retain independent standalone/plugin packaging gates. Select per-artifact Java bytecode baselines from real target requirements rather than propagating the host JDK into every artifact.

**Exit:** reproducible clean build, dependency boundary checks, minimal host service adapters; no unsupported public API baseline claims.

### 4. Make configuration and compatibility executable

Implemented: packaged schemas, profile-qualified effective-reactor context selection, local runtime mappings, shared compatibility gating, bounded wire codec and authentication/correlation state. See [implementation and validation](configuration-and-protocol.md). Effective Maven capture and worker/minimal UI wiring are implemented in work packages 5 and 7; a general setup wizard remains later work.

Implement JSON schema, context resolution and local runtime mappings. Turn the illustrative fields into a versioned v1 schema and fixtures. Check invalid paths/modules, missing runtimes, unknown schema versions/capabilities, multiple matching contexts and parent-to-Component context inheritance. Define protocol framing, bounded message/image payloads and negotiation/error fixtures before worker implementation depends on them.

**Exit:** common configuration tests pass in both host adapters; incompatible setup leaves source editing available; protocol specification is testable and independently versioned.

### 5. Implement Build and Refresh with immutable snapshots

Implemented: shared coordinator, scoped effective Maven capture, explicit draft save approval, isolated builds, consistent private runtime copies, atomic publication, persistent outdated/last-successful state and cross-process snapshot leases. See [implementation and limits](build-and-refresh.md). The UI and worker restart now consume these interfaces in work package 7.

Resolve scoped Maven builds, preview source arrangements, explicit save/cancel and runtime choices. Capture successful outputs/resources/dependencies with an input/output manifest. Validate consistency and publish atomically; pin active snapshots against eviction. Provide explicit last-successful-build selection and stale diagnostics.

**Exit:** success, cancellation, failed build, input edits during build/capture, mutable output replacement, and snapshot-lifetime tests pass. Known unsaved build inputs cannot silently fall back to disk.

### 6. Validate the preview API and target adapter against real fixtures

Implemented: resource-only discovery, typed sessions, real NeitzelLib loading/rendering and 24 classpath/module-path process checks. See [qualification and lifecycle limits](preview-target-fixtures.md). Library-held Model/ViewModel state requires a fresh JVM per session; external shutdown enforcement is now implemented in work package 7.

Add classpath/module-path Maven fixture applications using NeitzelLib artifacts. Implement non-constructing descriptor discovery and typed provider/session lifecycle against the real library. Test fresh Models/services, readiness, cleanup, invalid attributes and write-back. Freeze public Java signatures only after these tests establish the adapter contract.

**Exit:** standalone target-side tests pass without Kit/IntelliJ dependencies leaking into application-facing artifacts; both preview source arrangements are represented.

### 7. Complete the first workflow in both minimal hosts

Implemented: both minimal hosts use the same Kit UI and workflow, immutable snapshots, authenticated worker transport, parent/Component overlays, native document edits and undo/redo. The narrow Kit selection fix is carried with provenance. See [implementation, qualification and limits](first-connected-workflow.md). Broader projection, interactive preview controls and product qualification remain subsequent work.

Connect shared core/UI to the worker protocol and fixtures. Exercise Build and Refresh, discovery, parent/Component draft overlays and target-runtime render in standalone and IntelliJ. Use the qualified exclusive JavaFX 26 host setup; keep application runtime execution outside each host. Carry only the verified narrow Kit patch where still needed, with provenance and regression coverage.

**Exit:** all initial-contract acceptance requirements pass in both hosts with logs/artifact identities and explicit limitations. Then proceed to roadmap stage 2 and later feature stages. Full handoff, binding/generation UI, broader projection/control support and product packaging are not silently included in this first milestone.

## Delivery discipline

Do not label these packages as additional unresolved Wayfinder decisions: the architecture is accepted. They are concrete implementation work with validation gates. Reopen a focused design question only if implementation evidence exposes a real incompatibility or missing seam. Bootstrap, library integration and designer implementation remain separately reviewable changes.

## After bootstrap: source-preserving projection

Roadmap stage 2 now has source-range transactions, broader Component projection and shared live checks in both hosts. See [implementation and qualification boundaries](source-preserving-projection.md). The [human standalone and IntelliJ review](manual-input-validation.md) now closes the physical drag/drop and resize gate on the recorded macOS baseline, including the corner-resize correction at `b9d59e1`. Broader platform/input coverage remains separate. Continue with the [stage-3 implementation plan](target-runtime-stage-plan.md): retained target sessions, occurrence identity and sizing, shared canvas refresh, Component/Row navigation, and separate interactive previews.