Bootstrap Neitzel FX Designer repository foundation
This commit is contained in:
@@ -0,0 +1,131 @@
|
||||
# NeitzelFXDesigner initial project contract
|
||||
|
||||
Status: accepted architecture consolidated from decision rounds Q1–Q15 on 2026-11-12. Module and JSON field spellings below are proposed implementation names; public Java signatures and numerical protocol limits must pass their bootstrap validation before publication. This document refines roadmap stage 1, not the complete product specification.
|
||||
|
||||
Decision provenance: [accepted workspace decisions](provenance.md). Execution order: [repository bootstrap plan](repository-bootstrap-plan.md). Existing authoring, preview, binding, generation and host requirements remain in the [broader roadmap context](provenance.md#broader-roadmap).
|
||||
|
||||
## Project and scope
|
||||
|
||||
- Repository: **NeitzelFXDesigner**; application name: **Neitzel FX Designer**.
|
||||
- Remote: `ssh://git@gitea.neitzel.de:2222/konrad/NeitzelFXDesigner.git`.
|
||||
- Canonical independent checkout: `/Volumes/PlanckSSD/KI/java/NeitzelFXDesigner`, alongside NeitzelLib in the canonical Java workspace. The research worktree is not its permanent checkout.
|
||||
- Initial default branch: `main`. The initial repository bootstrap establishes this branch; the earlier consolidation found no advertised remote refs.
|
||||
- The Component builder fix belongs to NeitzelLib. Designer/tooling code belongs to NeitzelFXDesigner. Application fixtures depend on library artifacts, never copied NeitzelLib sources.
|
||||
- First milestone: one real Component and sample Model through Build and Refresh, successful-build capture, metadata discovery and target-runtime rendering in both minimal hosts. Include classpath and module-path fixtures and failure diagnostics.
|
||||
- Full binding/generation UI, general projection editing, production handoff, packaging and wider qualification retain their later roadmap gates. Minimal hosts are not feature-complete releases.
|
||||
|
||||
## Modules and dependency direction
|
||||
|
||||
Names are proposed, while the responsibility boundaries are accepted.
|
||||
|
||||
| Module/directory | Responsibility | Boundary |
|
||||
| --- | --- | --- |
|
||||
| `designer-contracts` | Configuration types/schema, wire envelopes, metadata DTOs and capability definitions | No Kit, IntelliJ or application classes; schema/protocol versions are independently tracked |
|
||||
| `designer-core` | Application contexts, build/snapshot orchestration, validation, document edit intents and worker sessions | Depends on contracts; obtains host services through interfaces, not host implementations |
|
||||
| `designer-kit-ui` | Shared canvas, hierarchy, inspector and later binding/generation panels | Depends on core and pinned Kit/JavaFX; no IntelliJ API |
|
||||
| `designer-standalone` | Native application entry point, documents/undo, menus, navigation and lifecycle | Adapts core/UI to standalone services |
|
||||
| `designer-intellij` | FXML editor, IDE Documents/commands, project/build/navigation integration and focus | Adapts the same core/UI; qualify build and packaging against the selected IDE SDK |
|
||||
| `designer-preview-api` | Typed example descriptors and fresh preview-session lifecycle | Small project-facing artifact; no Kit or IntelliJ dependency |
|
||||
| `designer-target-tools` | Discovery and NeitzelLib loading/rendering adapter in the application runtime | Uses contracts/preview API and target-compatible library dependencies; never execute application classes in a host |
|
||||
| `integration-fixtures/` | Real classpath and module-path Maven applications, examples and failure cases | Same scenarios consumed by both hosts; normal artifact dependencies |
|
||||
|
||||
Shared contracts may be Java artifacts without implying identical JDK/JavaFX versions in hosts and workers. Select bytecode/API baselines per module from the supported target fixtures; verify that application-facing artifacts load on the oldest initial target before publishing them. The IntelliJ packaging toolchain must be pinned and tested; a Maven reactor for shared artifacts does not assume that ordinary Maven JAR packaging produces a supported plugin.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
S[Standalone adapter] --> U[Shared Kit UI]
|
||||
I[IntelliJ adapter] --> U
|
||||
U --> C[Shared designer core]
|
||||
S --> C
|
||||
I --> C
|
||||
C --> K[Configuration / protocol / metadata contracts]
|
||||
C -->|Dedicated local IPC| W[Target-runtime tooling]
|
||||
W --> K
|
||||
W --> P[Preview API]
|
||||
A[Application examples] --> P
|
||||
W --> N[NeitzelLib and application runtime]
|
||||
```
|
||||
|
||||
Each host owns its own engine/UI instances. The authoritative document and undo history belong to the active host. Kit remains a projection. This diagram describes dependencies and process boundaries, not shared mutable state across hosts.
|
||||
|
||||
## Shared application configuration
|
||||
|
||||
`neitzel-fx-designer.json` lives at the application's Maven reactor root. It contains a schema version and named application contexts. A context selects an application module, Maven profiles, classpath/module-path launch mode, preview sources/module and examples. Relative paths resolve from the configuration location, never the process working directory. Validate modules and paths against the selected reactor. Obtain dependency graphs and ordinary source/resource roots from Maven rather than maintaining competing lists.
|
||||
|
||||
Illustrative shape for the first schema (field names are a concrete draft, not a released schema):
|
||||
|
||||
```json
|
||||
{
|
||||
"schemaVersion": "1.0",
|
||||
"contexts": {
|
||||
"desktop": {
|
||||
"applicationModule": "app",
|
||||
"mavenProfiles": ["designer-preview"],
|
||||
"launchMode": "classpath",
|
||||
"buildRuntime": "build-java",
|
||||
"targetRuntime": "application-java",
|
||||
"preview": {
|
||||
"sourceSet": "module",
|
||||
"module": "preview",
|
||||
"provider": "example.preview.PersonExamples",
|
||||
"defaultExample": "person.standard"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The schema must also cover `test` preview sources in the application module, module-path entry/access settings and runtime requirements. Example IDs belong to provider descriptors; configuration selects a default and may select/filter descriptors rather than duplicating their metadata. A provider class name identifies a typed implementation, not an arbitrary reflective factory method. Provider registration/descriptor extraction must be validated against the library before the public API is frozen.
|
||||
|
||||
Select the context automatically when exactly one matches. Otherwise ask, show the active context and remember the choice locally. Opening a Component from a parent inherits that context. Shared source documents retain one host-owned draft even when usable in multiple contexts.
|
||||
|
||||
Local settings hold installed JDK mappings, absolute machine paths and remembered context/UI preferences. Shared runtime names refer to required build and target runtimes; resolve, display and validate those roles separately. Application JavaFX comes from Maven. A missing/incompatible target requests setup; never silently substitute the designer's or IDE's JVM. No automatic configuration migration. Unsupported schema/capabilities disable the affected tool with diagnostics while ordinary source editing remains available.
|
||||
|
||||
## Build and snapshot contract
|
||||
|
||||
1. Resolve the selected context and required reactor dependencies, including configured preview sources. Prefer the Maven wrapper; expose the plan, command/output and cancellation. Avoid unrelated applications unless dependency resolution requires them.
|
||||
2. Identify known unsaved Java, Maven and designer-configuration inputs affecting the build. Offer **Save affected files and build** or **Cancel**, listing the affected files. Do not implicitly build older disk versions. Account for IDE autosave; another process's unsaved buffers are not observable.
|
||||
3. Capture the relevant input identity/revision manifest and execute the build with the selected build runtime. FXML-only draft edits have separate revisions and need not trigger Java compilation.
|
||||
4. After success, stage a consistent snapshot of compiled outputs, generated metadata, resources and resolved dependency content/identities into an ignored designer cache. Do not hand workers mutable `target` paths or mutable dependency outputs. Copy or content-address artifacts; a snapshot must not change if later builds overwrite their inputs.
|
||||
5. Verify inputs/output capture remained consistent throughout the operation. A fingerprint at only one instant is insufficient. Detected changes, capture failures, cancellation or failed builds prevent activation. Publish a complete manifest/snapshot atomically, never a partially populated directory.
|
||||
6. Activate the successful snapshot, refresh discovery and restart affected preview sessions. A manifest identifies context, build inputs, artifacts/digests, runtime requirements and tool contracts. Discovery and rendering use the same build identity.
|
||||
7. Retain the last usable successful snapshot after failure, mark retained derived results outdated, and require explicit **Preview with last successful build**. An outdated build is not silently promoted to current.
|
||||
|
||||
Cache contents are local, ignored and reconstructible. Active workers retain their snapshots until stopped; eviction must not remove in-use artifacts. Numerical retention limits are operational defaults, not a new authoring decision.
|
||||
|
||||
FXML previews overlay the owning host's current parent and open Component drafts onto the selected build snapshot. Document revisions and snapshot identity remain distinct; source edits must not silently change a worker's captured input. Reject obsolete results using host-owned revision ordering, not numeric assumptions about IDE modification stamps. Resources outside the supported draft-overlay mechanism remain part of explicit resource/build freshness validation.
|
||||
|
||||
## Discovery and preview API
|
||||
|
||||
Metadata listing must not construct Models or invoke Controller methods. Separate example descriptors (stable IDs, display labels, compatible Model/View information and declared capabilities) from runtime construction. Generated descriptor metadata or equivalent non-constructing discovery must be tested; calling arbitrary provider initialization merely to list examples does not satisfy this boundary.
|
||||
|
||||
Selecting an example creates a fresh owned preview session with its Model graph and explicitly configured services. Provide readiness and cleanup hooks. Ordinary examples become ready after load/CSS/layout; asynchronous examples signal readiness subject to cancellation/timeout. Construction, services, Controller actions and cleanup execute only in the target JVM. Verify the adapter against NeitzelLib's actual injection/loading lifecycle before publishing Java signatures.
|
||||
|
||||
A parent rendering snapshot shares its Model graph across embedded Components; standalone Component preview selects its own example. Interactive preview has its own JVM/session. Bounded graceful cleanup precedes forced worker termination when necessary; cleanup callbacks cannot be guaranteed after process death, so host-side lifecycle ownership remains required.
|
||||
|
||||
## Versions and communication
|
||||
|
||||
Track configuration schema, wire/metadata contracts and preview API compatibility independently from product releases. Major changes represent breaking contracts; additive features use declared optional capabilities. Equal product versions alone are not proof of compatibility. Verify discovery and rendering independently so one unavailable capability does not unnecessarily disable the other.
|
||||
|
||||
Use a dedicated loopback-only socket with a per-launch random token and version/capability handshake for worker messages. Standard output/error remain captured application logs and cannot carry protocol framing. Do not log tokens. Bind the session to the launched worker and reject messages before authentication/negotiation. Use explicit bounded framing, validate lengths and resource limits before allocation, correlate requests/replies and define cancellation/error outcomes. Exact encoding and limits are bootstrap protocol-specification tasks, not facts established by the prototype.
|
||||
|
||||
Every applicable request/result identifies its worker session, request, context and build snapshot; rendering also identifies document revisions and requested size. Obsolete results cannot mutate current document/UI state. Diagnostics identify operation and available source origin while preserving editing.
|
||||
|
||||
Keep the proven reserved owner-lifetime channel for worker cleanup independent of FX responsiveness. The independently owning standalone editor must survive IDE death; it does not use the preview-worker death rule. Production host-to-host handoff remains a separate protocol/gate; choosing a worker socket does not silently choose its production transport.
|
||||
|
||||
## Library prerequisite and acceptance
|
||||
|
||||
Integrate and test the Component builder fix separately in NeitzelLib, preserve unrelated work, and establish the first released artifact containing it. Declare the resulting supported minimum/capability in designer metadata. Older unsupported versions receive diagnostics, not a hidden adapter. Until release, development fixtures may pin a clearly identified installed snapshot; a SNAPSHOT name alone does not establish fix provenance. The inspected source currently declares `de.neitzel.lib:fx:1.0-SNAPSHOT` with Java 21 / JavaFX 21.0.7, and the fix remains uncommitted. No corrected minimum released version is asserted; see the bootstrap plan for provenance and test-run caveats.
|
||||
|
||||
Accept the first milestone only when both minimal hosts use the same core/UI/fixtures and demonstrate:
|
||||
|
||||
- Constructor-only Components accept custom/inherited FXML attributes after initialization; invalid values fail; Model identity/write-back survive without an adapter.
|
||||
- Classpath and module-path applications build, discover and render through their selected runtimes; missing module access is diagnosed rather than repaired with silent broad opens.
|
||||
- Build scope and explicit save choices are observable; failed/cancelled/stale builds preserve documents and do not publish a current snapshot.
|
||||
- Subsequent builds cannot mutate a running worker's snapshot; active snapshot cleanup is safe.
|
||||
- FXML draft updates render without Java recompilation and stale responses are ignored.
|
||||
- Missing/incompatible runtime/schema/protocol/capability failures are actionable and limited to affected tools.
|
||||
- Listing examples performs no Model/Controller construction; selecting an example produces fresh state and honors readiness/cleanup.
|
||||
- Console output cannot corrupt worker messages; owner death, cancellation and timeout terminate workers.
|
||||
|
||||
These are acceptance requirements, not newly passed tests. Broader product behavior remains governed by the existing roadmap.
|
||||
@@ -0,0 +1,11 @@
|
||||
# Decision provenance
|
||||
|
||||
The architecture and bootstrap plan were accepted by Konrad through the Java workspace Wayfinder effort **NeitzelLib FX support in Scene Builder**, culminating in **Choose the initial implementation project and contracts** (Q1–Q15, consolidated 2026-11-12).
|
||||
|
||||
The authoritative implementation documents now live here: [initial contract](initial-project-contract.md) and [bootstrap plan](repository-bootstrap-plan.md). Workspace documents retain links here. The original discussion record remains at `docs/issues/neitzellib-scene-builder/issues/23-choose-initial-project-contract.md` in the Java workspace. On the development workstation that workspace is `/Volumes/PlanckSSD/KI/java`.
|
||||
|
||||
## Broader roadmap
|
||||
|
||||
The wider authoring/generation and delivery plan remains at `docs/issues/neitzellib-scene-builder/integration-roadmap.md` in the Java workspace. It covers later binding/generation UI, projection, handoff and packaging gates; this repository's initial contract deliberately covers only its first implementation stage. The selected host architecture shares Kit UI, keeps authoritative documents in their hosts, and isolates application execution in target workers. VoiceOver qualification and remote IDE development remain outside the agreed initial scope.
|
||||
|
||||
The throwaway experiments remain in the workspace repository, not in this production foundation. Their captured evidence includes the [shared Kit/standalone result](https://gitea.neitzel.de/konrad/workspace-java/src/commit/65ffa56215ed666dec5db12746346e8a1f2baa08/docs/issues/neitzellib-scene-builder/prototypes/PROTOTYPE-intellij/STANDALONE-RESULTS.md) and [coordinated handoff result](https://gitea.neitzel.de/konrad/workspace-java/src/commit/327311a4f88061324357a13f76295bf191d4cc70/docs/issues/neitzellib-scene-builder/prototypes/PROTOTYPE-intellij/HANDOFF-RESULTS.md). Their bounded test results are not qualification of this new repository.
|
||||
@@ -0,0 +1,81 @@
|
||||
# NeitzelFXDesigner repository bootstrap plan
|
||||
|
||||
Status: repository foundation implemented by the initial commit; work packages 2–7 remain planned. 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. The remaining packages below are not implemented.
|
||||
|
||||
### 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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
Reference in New Issue
Block a user