@hla4ts/spacekit 0.1.0

package/README.md

@@ -0,0 +1,154 @@
+# @hla4ts/spacekit
+
+SEE-first application layer for HLA federates.
+
+`@hla4ts/spacekit` is now the default entry point for new users, especially for
+SEE and SpaceFOM federates. It sits on top of `@hla4ts/hla-api` and bundles the
+runtime pieces most users actually need:
+
+- `SpacekitApp`: opinionated SEE/SpaceFOM app runtime
+- canonical SpaceFOM entity and interaction classes
+- late-joiner bootstrap and typed bootstrap state
+- run loop, `tick()`, and logical-time send-time helpers
+- declarative object/interaction schemas and decorator-based registration
+- entity sync, environment parsing, and console logging helpers
+
+`@hla4ts/spacefom` is now the thinner helper layer underneath it. Use that
+package directly only when you need raw SpaceFOM assets such as bundled XML
+modules or low-level coders.
+
+## Install
+
+```bash
+bun add @hla4ts/spacekit
+```
+
+## Recommended Entry Point
+
+```ts
+import { PhysicalEntity, SpacekitApp } from "@hla4ts/spacekit";
+
+const app = new SpacekitApp({
+  federationName: "SpaceFederation",
+  federateName: "LunarRover-1",
+  federateType: "LunarRover",
+});
+
+const rover = new PhysicalEntity("LunarRover-1", {
+  parent_reference_frame: "AitkenBasinLocalFixed",
+});
+
+await app.start();
+await app.registerEntity(rover);
+
+await app.run({
+  entities: [rover],
+  onTick: ({ timeSeconds }) => {
+    rover.state = {
+      translation: {
+        position: [0.5 * timeSeconds, 0, 0],
+        velocity: [0.5, 0, 0],
+      },
+      rotation: {
+        attitude: { scalar: 1, vector: [0, 0, 0] },
+        angularVelocity: [0, 0, 0],
+      },
+      time: timeSeconds,
+    };
+  },
+});
+```
+
+## What `SpacekitApp` Adds
+
+- SEE-oriented environment defaults
+- built-in `SpaceFomLateJoinerBootstrap`
+- automatic reference-frame waiting for `PhysicalEntity` registration
+- `tick()` and `run()` for paced logical-time loops
+- `getSendTimeMicros()` for timestamped updates/interactions
+- `spacefomState` for typed bootstrap state access
+- configurable missing-reference-frame behavior via `missingReferenceFrameMode`
+- graceful shutdown wiring by default
+
+If you want an app to keep running when a configured parent reference frame is
+not yet available, set `missingReferenceFrameMode: "continue"` on
+`SpacekitApp`. The app will warn and proceed instead of throwing during entity
+registration.
+
+## Canonical SpaceFOM Types
+
+The canonical decorated SpaceFOM classes now live in `@hla4ts/spacekit`:
+
+- `ExecutionConfiguration`
+- `ReferenceFrame`
+- `PhysicalEntity`
+- `DynamicalEntity`
+- `ModeTransitionRequest`
+
+These classes are the single source of truth for the runtime adapters,
+bootstrap subscriptions, and extension-FOM generation.
+
+## Lower-Level Escape Hatches
+
+If you need to drop below the SEE-first app layer, `@hla4ts/spacekit` still
+exports the generic framework primitives:
+
+- `BaseSpacekitApp`
+- `SpacekitFederate`
+- `DeclarativeFom`
+- `DeclarativeRuntime`
+- `SpacekitEntity`
+- decorators such as `FomObjectClass` and `FomInteractionClass`
+
+## SpaceFOM Assets and Coders
+
+`@hla4ts/spacekit` re-exports the common SpaceFOM helpers so most SEE users do
+not need a second package import:
+
+```ts
+import {
+  HLAunicodeStringCoder,
+  SpaceFomExecutionMode,
+  encodeSpaceTimeCoordinateState,
+  loadSpaceFomModules,
+} from "@hla4ts/spacekit";
+```
+
+## E2E Validation
+
+The repo includes an opt-in real-stack validation path built around the
+`lunar-rover` and `lunar-rover-tracker` examples.
+
+Prerequisites:
+
+- target RTI already running
+- SpaceMaster already running
+- Root Reference Frame Publisher already running
+
+Command:
+
+```bash
+RTI_HOST=localhost bun run e2e:spacekit-see
+```
+
+The command fails on timeout or missing success markers and validates:
+
+- join/bootstrap completion
+- reference-frame discovery
+- rover state publication
+- tracker receipt of rover updates
+- interaction round-trip plus ACK
+- multiple logical ticks for both federates
+
+## Package Split
+
+- `@hla4ts/spacekit`: default SEE/SpaceFOM app layer
+- `@hla4ts/spacefom`: bundled SpaceFOM XML modules, coders, constants, and optional dashboard loader
+- `@hla4ts/hla-api`: direct HLA API surface when you do not want the framework
+
+## Test
+
+```bash
+cd packages/spacekit
+bun test
+```

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@hla4ts/spacekit",
+  "version": "0.1.0",
+  "description": "SEE-first starter kit and default application layer for hla4typescript federates",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "README.md",
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@hla4ts/hla-api": "^0.1.0",
+    "@hla4ts/fom-codegen": "^0.1.0",
+    "@hla4ts/spacefom": "^0.1.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "license": "MIT"
+}

package/src/app-export.test.ts

@@ -0,0 +1,45 @@
+import { expect, test } from "bun:test";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { CallbackModel } from "@hla4ts/hla-api";
+import { SpacekitApp } from "./app.ts";
+
+test("SpacekitApp exports FOM XML on demand", async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "spacekit-fom-"));
+  const outputPath = path.join(tmpDir, "test.xml");
+
+  const app = new SpacekitApp({
+    federate: {
+      rti: { host: "localhost" },
+      connection: { callbackModel: CallbackModel.EVOKED },
+      federationName: "TestFederation",
+      federateType: "TestFederate",
+    },
+    fomExport: { path: outputPath, format: "fdd" },
+  });
+
+  app.defineObjectClass<{ name: string }>({
+    name: "HLAobjectRoot.TestEntity",
+    sharing: "PublishSubscribe",
+    attributes: {
+      name: {
+        name: "name",
+        dataType: "HLAunicodeString",
+        updateType: "Static",
+        updateCondition: "during initialization",
+        ownership: "NoTransfer",
+        sharing: "PublishSubscribe",
+        transportation: "HLAreliable",
+        order: "TimeStamp",
+        encode: (value) => new TextEncoder().encode(value),
+      },
+    },
+  });
+
+  const result = await app.exportFomXml();
+  const contents = await fs.readFile(outputPath, "utf8");
+
+  expect(result.path).toBe(path.resolve(outputPath));
+  expect(contents).toContain("<name>TestEntity</name>");
+});