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; 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.

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. 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. 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. 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. 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. 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. 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. The human standalone and IntelliJ review 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: retained target sessions, occurrence identity and sizing, shared canvas refresh, Component/Row navigation, and separate interactive previews.

Target-runtime sessions, sizing and navigation

Stage 3 now has retained workers, scoped occurrences and target measurements, shared sizing/refresh, independent interactive preview, and Component/Row source navigation. See implementation and qualification. The human navigation review records standalone and initial IntelliJ passes; on 2026-11-13 the user explicitly skipped the remainder and accepted moving to shared discovery. Skipped checks are not reported as passed.

Manual review disposition (2026-11-13): the user accepted proceeding after the recorded standalone and initial IntelliJ passes. Remaining human checks are skipped explicitly, not passed. Continue with shared discovery.

Shared discovery: first stage-4 slice

Implemented the read-only binding browser in the shared Kit UI: target-side Person Attribute/path and collection-element discovery, Component Model declarations and direction-aware binding-target compatibility. Real classpath and module-path fixtures qualify both hosts. The first editable DirectBinding inspector adds creation, changing, removal and explicit conflict replacement through one source-preserving host undo command per operation. Remaining metadata categories and broader binding authoring retain their subsequent work packages.

Converter discovery and binding validation

The next shared stage-4 slice adds optional concrete-class capabilities, non-initializing classpath/module-path discovery, reviewed Converter proposals and DirectBinding diagnostics with preview gating in both hosts. Full metadata, structural reference repair and Problems integration remain open.

Custom ViewModels and Computed bindings

The shared signature-based slice implements explicit Controller/Component ViewModel selection, subclass/replacement property discovery and Computed-method validation. Generated metadata, cross-View selection conflicts, full collection authoring and Problems integration remain open.

Shared Computed-binding inspector

The Computed authoring slice adds create/change/remove and explicit conflict replacement in both hosts through the same source-preserving editor as Direct bindings. Target method choices prepare the form without changing source; normal host Undo/Redo owns each operation. Full collection authoring, generated metadata, reference refactoring and Problems integration remain open.

Shared Repeat-binding inspector

The Repeat authoring slice adds create/change/remove, explicit duplicate-pane replacement, structural diagnostics and normal host Undo/Redo in both hosts. Collection/Component compatibility discovery is covered by the next completed slice below. Table/Column authoring, generated metadata, reference refactoring and Problems integration remain subsequent work.

Repeat collection and Component compatibility

The shared Repeat discovery slice adds collection, pane and Component choices, non-initializing target-side type comparisons, source-preserving explicit selections and document diagnostics with preview gating. Runtime construction and values remain preview checks. Table/Column authoring, generated metadata, reference refactoring and Problems integration remain open.

Shared Table / Column inspector

The Table/Column authoring slice adds Table and ordered Column CRUD, explicit reordering, optional widths and Row navigation in both hosts. Lexical edits and normal host Undo/Redo preserve the authoritative document. Structural errors block preview while drafts remain saveable. Row alignment and Table-specific type discovery remain unverified; generated metadata, reference refactoring and Problems integration remain open.