@hla4ts/create-spacekit 0.1.0

package/README.md

@@ -0,0 +1,73 @@
+# @hla4ts/create-spacekit
+
+Scaffold a minimal `@hla4ts/spacekit` lunar rover app.
+
+The generated project is intentionally simpler than the repo's validation
+examples. It creates one `PhysicalEntity`, drives it with `SpacekitApp.run()`,
+and keeps the common RTI/Spacekit knobs in `.env`.
+
+## What It Generates
+
+- a Bun + TypeScript project
+- a single-file rover runtime built on `@hla4ts/spacekit`
+- `.env` defaults for RTI host/port/TLS, federation, federate, frame, timing,
+  and rover motion
+
+## Local Workspace Usage
+
+From this repo checkout:
+
+```bash
+bun run --filter @hla4ts/create-spacekit cli -- my-rover
+```
+
+## Intended Published Usage
+
+The package is structured with a `bin` entry so it is ready for:
+
+```bash
+bunx @hla4ts/create-spacekit my-rover
+```
+
+That one-line path still depends on publishing the package to the npm registry.
+
+## Options
+
+- `--template lunar-rover`
+- `--list-templates`
+- `--federation-name <name>`
+- `--federate-name <name>`
+- `--federate-type <type>`
+- `--rti-host <host>`
+- `--rti-port <port>`
+- `--rti-use-tls`
+- `--parent-reference-frame <frame>`
+- `--rover-name <name>`
+- `--rover-type <type>`
+- `--rover-speed-mps <value>`
+- `--lookahead-micros <value>`
+- `--update-period-micros <value>`
+- `--reference-frame-timeout-ms <value>`
+- `--reference-frame-missing-mode <mode>`
+- `--workspace-deps`
+- `--yes`
+
+`--workspace-deps` is for local monorepo validation. It writes
+`"@hla4ts/spacekit": "workspace:*"` into the generated project instead of the
+published semver range.
+
+`--reference-frame-missing-mode` controls what the generated rover does when
+its parent reference frame has not been published yet. The template default is
+`continue`.
+
+## Generated App
+
+After scaffolding:
+
+```bash
+cd my-rover
+bun install
+bun run start
+```
+
+Edit `.env` to point at your RTI and federation.

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@hla4ts/create-spacekit",
+  "version": "0.1.0",
+  "description": "Scaffold a minimal @hla4ts/spacekit rover app",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "bin": {
+    "spacekit": "src/cli.ts"
+  },
+  "files": [
+    "README.md",
+    "src",
+    "templates"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "cli": "bun run src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.9.0"
+  },
+  "license": "MIT"
+}

package/src/cli.ts

@@ -0,0 +1,364 @@
+#!/usr/bin/env bun
+import readline from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import path from "node:path";
+import {
+  DEFAULT_TEMPLATE,
+  TEMPLATE_DESCRIPTIONS,
+  listTemplates,
+  scaffoldApp,
+  type TemplateId,
+  type TemplateValues,
+} from "./scaffold.ts";
+
+interface CliOptions {
+  targetDir?: string;
+  template: TemplateId;
+  workspaceDeps: boolean;
+  yes: boolean;
+  values: Partial<TemplateValues>;
+  listTemplates: boolean;
+  help: boolean;
+}
+
+try {
+  await main();
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(message);
+  process.exit(1);
+}
+
+async function main(): Promise<void> {
+  const options = parseArgs(process.argv.slice(2));
+
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  if (options.listTemplates) {
+    for (const template of listTemplates()) {
+      console.log(`${template.id}\t${template.description}`);
+    }
+    return;
+  }
+
+  if (!options.targetDir) {
+    printHelp("Target directory is required.");
+    process.exit(1);
+  }
+
+  if (!isTemplateId(options.template)) {
+    throw new Error(`Unknown template "${options.template}". Run --list-templates to inspect choices.`);
+  }
+
+  const usePrompts = stdin.isTTY && stdout.isTTY && !options.yes;
+  const values = usePrompts
+    ? await promptForMissingValues(options.targetDir, options.template, options.values)
+    : options.values;
+  if (options.workspaceDeps) {
+    values.spacekitDependency = "workspace:*";
+  }
+
+  const result = await scaffoldApp({
+    targetDir: options.targetDir,
+    template: options.template,
+    values,
+  });
+
+  const relativeTarget = path.relative(process.cwd(), result.targetDir) || ".";
+  const displayTarget =
+    relativeTarget === "." || (!relativeTarget.startsWith("..") && !path.isAbsolute(relativeTarget))
+      ? relativeTarget
+      : result.targetDir;
+  console.log(`Created ${result.template} app in ${result.targetDir}`);
+  console.log("");
+  console.log("Next steps:");
+  console.log(`  cd ${displayTarget}`);
+  console.log("  bun install");
+  console.log("  bun run start");
+  console.log("");
+  console.log(
+    "This package is bunx-ready, but the one-line zero-clone flow still depends on npm publication:"
+  );
+  console.log(`  bunx @hla4ts/create-spacekit ${path.basename(result.targetDir)}`);
+}
+
+function parseArgs(argv: string[]): CliOptions {
+  const options: CliOptions = {
+    template: DEFAULT_TEMPLATE,
+    workspaceDeps: false,
+    yes: false,
+    values: {},
+    listTemplates: false,
+    help: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg) continue;
+
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+      continue;
+    }
+    if (arg === "--list-templates") {
+      options.listTemplates = true;
+      continue;
+    }
+    if (arg === "--yes" || arg === "-y") {
+      options.yes = true;
+      continue;
+    }
+    if (arg === "--workspace-deps") {
+      options.workspaceDeps = true;
+      continue;
+    }
+    if (arg === "--template") {
+      options.template = readValue(argv, ++index, arg) as TemplateId;
+      continue;
+    }
+    if (arg === "--federation-name") {
+      options.values.federationName = readValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--federate-name") {
+      options.values.federateName = readValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--federate-type") {
+      options.values.federateType = readValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--rti-host") {
+      options.values.rtiHost = readValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--rti-port") {
+      options.values.rtiPort = readValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--rti-use-tls") {
+      options.values.rtiUseTls = "true";
+      continue;
+    }
+    if (arg === "--parent-reference-frame") {
+      options.values.parentReferenceFrame = readValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--rover-name") {
+      options.values.roverName = readValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--rover-type") {
+      options.values.roverType = readValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--rover-speed-mps") {
+      options.values.roverSpeedMps = readValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--lookahead-micros") {
+      options.values.lookaheadMicros = readValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--update-period-micros") {
+      options.values.updatePeriodMicros = readValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--reference-frame-timeout-ms") {
+      options.values.referenceFrameTimeoutMs = readValue(argv, ++index, arg);
+      continue;
+    }
+    if (arg === "--reference-frame-missing-mode") {
+      options.values.referenceFrameMissingMode = readValue(argv, ++index, arg);
+      continue;
+    }
+
+    if (arg.startsWith("--")) {
+      throw new Error(`Unknown flag: ${arg}`);
+    }
+
+    if (!options.targetDir) {
+      options.targetDir = arg;
+      continue;
+    }
+
+    throw new Error(`Unexpected argument: ${arg}`);
+  }
+
+  return options;
+}
+
+async function promptForMissingValues(
+  targetDir: string,
+  template: TemplateId,
+  values: Partial<TemplateValues>
+): Promise<Partial<TemplateValues>> {
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  const defaults = {
+    federationName: "SpaceFederation",
+    federateName: "LunarRover-1",
+    federateType: "LunarRover",
+    rtiHost: "localhost",
+    rtiPort: "15164",
+    rtiUseTls: "false",
+    parentReferenceFrame: "AitkenBasinLocalFixed",
+    roverName: "LunarRover-1",
+    roverType: "LunarRover",
+    roverSpeedMps: "0.5",
+    lookaheadMicros: "1000000",
+    updatePeriodMicros: "1000000",
+    referenceFrameTimeoutMs: "30000",
+    referenceFrameMissingMode: "continue",
+  } satisfies Partial<TemplateValues>;
+
+  try {
+    console.log(`Scaffolding template "${template}" into ${path.resolve(targetDir)}`);
+    console.log(TEMPLATE_DESCRIPTIONS[template]);
+    console.log("");
+
+    const federationName = await ask(
+      rl,
+      "Federation name",
+      values.federationName ?? defaults.federationName
+    );
+    const federateName = await ask(
+      rl,
+      "Federate name",
+      values.federateName ?? defaults.federateName
+    );
+    const federateType = await ask(
+      rl,
+      "Federate type",
+      values.federateType ?? defaults.federateType
+    );
+    const rtiHost = await ask(rl, "RTI host", values.rtiHost ?? defaults.rtiHost);
+    const rtiPort = await ask(rl, "RTI port", values.rtiPort ?? defaults.rtiPort);
+    const rtiUseTls = await askBool(rl, "Use TLS", values.rtiUseTls ?? defaults.rtiUseTls);
+    const parentReferenceFrame = await ask(
+      rl,
+      "Parent reference frame",
+      values.parentReferenceFrame ?? defaults.parentReferenceFrame
+    );
+    const roverName = await ask(
+      rl,
+      "Rover object name",
+      values.roverName ?? federateName ?? defaults.roverName
+    );
+    const roverType = await ask(
+      rl,
+      "Rover type",
+      values.roverType ?? federateType ?? defaults.roverType
+    );
+    const roverSpeedMps = await ask(
+      rl,
+      "Rover speed (m/s)",
+      values.roverSpeedMps ?? defaults.roverSpeedMps
+    );
+    const lookaheadMicros = await ask(
+      rl,
+      "Lookahead (micros)",
+      values.lookaheadMicros ?? defaults.lookaheadMicros
+    );
+    const updatePeriodMicros = await ask(
+      rl,
+      "Update period (micros)",
+      values.updatePeriodMicros ?? defaults.updatePeriodMicros
+    );
+    const referenceFrameTimeoutMs = await ask(
+      rl,
+      "Reference frame timeout (ms)",
+      values.referenceFrameTimeoutMs ?? defaults.referenceFrameTimeoutMs
+    );
+    const referenceFrameMissingMode = await ask(
+      rl,
+      "Missing frame mode (error/continue)",
+      values.referenceFrameMissingMode ?? defaults.referenceFrameMissingMode
+    );
+
+    return {
+      ...values,
+      federationName,
+      federateName,
+      federateType,
+      rtiHost,
+      rtiPort,
+      rtiUseTls,
+      parentReferenceFrame,
+      roverName,
+      roverType,
+      roverSpeedMps,
+      lookaheadMicros,
+      updatePeriodMicros,
+      referenceFrameTimeoutMs,
+      referenceFrameMissingMode,
+    };
+  } finally {
+    rl.close();
+  }
+}
+
+async function ask(
+  rl: readline.Interface,
+  label: string,
+  fallback: string | undefined
+): Promise<string> {
+  const resolvedFallback = fallback ?? "";
+  const response = await rl.question(`${label} (${resolvedFallback}): `);
+  return response.trim() === "" ? resolvedFallback : response.trim();
+}
+
+async function askBool(
+  rl: readline.Interface,
+  label: string,
+  fallback: string | undefined
+): Promise<string> {
+  const response = await ask(rl, `${label} [y/N]`, fallback === "true" ? "y" : "n");
+  const normalized = response.toLowerCase();
+  return ["y", "yes", "true", "1"].includes(normalized) ? "true" : "false";
+}
+
+function readValue(argv: string[], index: number, flag: string): string {
+  const value = argv[index];
+  if (!value) {
+    throw new Error(`Missing value for ${flag}`);
+  }
+  return value;
+}
+
+function isTemplateId(value: string): value is TemplateId {
+  return value in TEMPLATE_DESCRIPTIONS;
+}
+
+function printHelp(errorMessage?: string): void {
+  if (errorMessage) {
+    console.error(errorMessage);
+    console.error("");
+  }
+
+  console.log("Usage:");
+  console.log("  spacekit <target-dir> [options]");
+  console.log("");
+  console.log("Options:");
+  console.log("  --template <name>                   Template to use (default: lunar-rover)");
+  console.log("  --list-templates                    Print the available templates");
+  console.log("  --federation-name <name>            Default federation name in .env");
+  console.log("  --federate-name <name>              Default federate name in .env");
+  console.log("  --federate-type <type>              Default federate type in .env");
+  console.log("  --rti-host <host>                   Default RTI host in .env");
+  console.log("  --rti-port <port>                   Default RTI port in .env");
+  console.log("  --rti-use-tls                       Enable TLS in .env");
+  console.log("  --parent-reference-frame <name>     Parent frame for the rover entity");
+  console.log("  --rover-name <name>                 Rover object instance name");
+  console.log("  --rover-type <type>                 Rover object type");
+  console.log("  --rover-speed-mps <value>           Rover speed along the X axis");
+  console.log("  --lookahead-micros <value>          Spacekit lookahead");
+  console.log("  --update-period-micros <value>      Spacekit tick period");
+  console.log("  --reference-frame-timeout-ms <ms>   How long to wait for the frame tree");
+  console.log("  --reference-frame-missing-mode <m>  error | continue");
+  console.log("  --workspace-deps                    Use workspace:* for @hla4ts/spacekit");
+  console.log("  --yes, -y                           Skip prompts and use defaults/flags");
+  console.log("  --help, -h                          Show this help text");
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export {
+  DEFAULT_TEMPLATE,
+  TEMPLATE_DESCRIPTIONS,
+  listTemplates,
+  sanitizePackageName,
+  scaffoldApp,
+  type ScaffoldAppOptions,
+  type ScaffoldAppResult,
+  type TemplateId,
+  type TemplateValues,
+} from "./scaffold.ts";

package/src/scaffold.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "bun:test";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { sanitizePackageName, scaffoldApp } from "./scaffold.ts";
+
+describe("@hla4ts/create-spacekit", () => {
+  test("sanitizePackageName normalizes arbitrary folder names", () => {
+    expect(sanitizePackageName("My Lunar Rover!")).toBe("my-lunar-rover");
+    expect(sanitizePackageName("  ")).toBe("hla4ts-spacekit-app");
+  });
+
+  test("scaffoldApp creates a configurable lunar rover project", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "hla4ts-scaffold-"));
+    const targetDir = path.join(tempRoot, "mission-rover");
+
+    await scaffoldApp({
+      targetDir,
+      values: {
+        spacekitDependency: "workspace:*",
+        referenceFrameMissingMode: "continue",
+        federationName: "MoonOps",
+        federateName: "Rover-Blue",
+        federateType: "ScoutRover",
+        rtiHost: "10.0.0.12",
+        roverSpeedMps: "1.25",
+      },
+    });
+
+    const packageJson = await fs.readFile(path.join(targetDir, "package.json"), "utf8");
+    const envFile = await fs.readFile(path.join(targetDir, ".env"), "utf8");
+    const indexFile = await fs.readFile(path.join(targetDir, "src", "index.ts"), "utf8");
+
+    expect(packageJson).toContain('"name": "mission-rover"');
+    expect(packageJson).toContain('"@hla4ts/spacekit": "workspace:*"');
+    expect(envFile).toContain("FEDERATION_NAME=MoonOps");
+    expect(envFile).toContain("FEDERATE_NAME=Rover-Blue");
+    expect(envFile).toContain("ROVER_NAME=Rover-Blue");
+    expect(envFile).toContain("ROVER_TYPE=ScoutRover");
+    expect(envFile).toContain("REFERENCE_FRAME_MISSING_MODE=continue");
+    expect(envFile).toContain("RTI_HOST=10.0.0.12");
+    expect(envFile).toContain("ROVER_SPEED_MPS=1.25");
+    expect(indexFile).toContain('import { PhysicalEntity, SpacekitApp');
+  });
+
+  test("scaffoldApp refuses non-empty target directories", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "hla4ts-scaffold-"));
+    const targetDir = path.join(tempRoot, "existing");
+    await fs.mkdir(targetDir, { recursive: true });
+    await fs.writeFile(path.join(targetDir, "keep.txt"), "existing", "utf8");
+
+    await expect(scaffoldApp({ targetDir })).rejects.toThrow(
+      "Refusing to scaffold into a non-empty directory"
+    );
+  });
+});

package/src/scaffold.ts

@@ -0,0 +1,199 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const DEFAULT_TEMPLATE = "lunar-rover";
+
+export const TEMPLATE_DESCRIPTIONS = {
+  "lunar-rover":
+    "Minimal Spacekit lunar rover with .env-driven RTI, federation, and timing config.",
+} as const;
+
+export type TemplateId = keyof typeof TEMPLATE_DESCRIPTIONS;
+
+export interface TemplateValues {
+  appName: string;
+  packageName: string;
+  spacekitDependency: "^0.1.0",
+  referenceFrameMissingMode: string;
+  federationName: string;
+  federateName: string;
+  federateType: string;
+  rtiHost: string;
+  rtiPort: string;
+  rtiUseTls: string;
+  parentReferenceFrame: string;
+  roverName: string;
+  roverType: string;
+  roverSpeedMps: string;
+  lookaheadMicros: string;
+  updatePeriodMicros: string;
+  referenceFrameTimeoutMs: string;
+}
+
+export interface ScaffoldAppOptions {
+  targetDir: string;
+  template?: TemplateId;
+  values?: Partial<TemplateValues>;
+}
+
+export interface ScaffoldAppResult {
+  template: TemplateId;
+  targetDir: string;
+  packageName: string;
+  filesWritten: number;
+}
+
+export async function scaffoldApp(options: ScaffoldAppOptions): Promise<ScaffoldAppResult> {
+  const template = options.template ?? DEFAULT_TEMPLATE;
+  assertTemplate(template);
+
+  const targetDir = path.resolve(options.targetDir);
+  await ensureEmptyTargetDirectory(targetDir);
+
+  const appName = deriveAppName(targetDir);
+  const values = {
+    ...defaultTemplateValues(appName),
+    ...(options.values ?? {}),
+  };
+  values.appName = values.appName.trim() || appName;
+  values.packageName = sanitizePackageName(values.packageName || values.appName);
+  values.roverName =
+    options.values?.roverName === undefined
+      ? values.federateName
+      : values.roverName.trim() || values.federateName;
+  values.roverType =
+    options.values?.roverType === undefined
+      ? values.federateType
+      : values.roverType.trim() || values.federateType;
+
+  const templateDir = resolveTemplateDir(template);
+  const files = await collectTemplateFiles(templateDir);
+
+  let filesWritten = 0;
+  for (const sourceFile of files) {
+    const relativePath = path.relative(templateDir, sourceFile);
+    const destinationPath = path.join(targetDir, relativePath);
+    await fs.mkdir(path.dirname(destinationPath), { recursive: true });
+    const content = await fs.readFile(sourceFile, "utf8");
+    const rendered = renderTemplate(content, values);
+    await fs.writeFile(destinationPath, rendered, "utf8");
+    filesWritten += 1;
+  }
+
+  return {
+    template,
+    targetDir,
+    packageName: values.packageName,
+    filesWritten,
+  };
+}
+
+export function listTemplates(): Array<{ id: TemplateId; description: string }> {
+  return (Object.entries(TEMPLATE_DESCRIPTIONS) as Array<[TemplateId, string]>).map(
+    ([id, description]) => ({ id, description })
+  );
+}
+
+export function sanitizePackageName(value: string): string {
+  const normalized = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+
+  return normalized.length > 0 ? normalized : "hla4ts-spacekit-app";
+}
+
+function defaultTemplateValues(appName: string): TemplateValues {
+  return {
+    appName,
+    packageName: sanitizePackageName(appName),
+    spacekitDependency: "^0.1.0",
+    referenceFrameMissingMode: "continue",
+    federationName: "SpaceFederation",
+    federateName: "LunarRover-1",
+    federateType: "LunarRover",
+    rtiHost: "localhost",
+    rtiPort: "15164",
+    rtiUseTls: "false",
+    parentReferenceFrame: "AitkenBasinLocalFixed",
+    roverName: "LunarRover-1",
+    roverType: "LunarRover",
+    roverSpeedMps: "0.5",
+    lookaheadMicros: "1000000",
+    updatePeriodMicros: "1000000",
+    referenceFrameTimeoutMs: "30000",
+  };
+}
+
+function assertTemplate(template: string): asserts template is TemplateId {
+  if (!(template in TEMPLATE_DESCRIPTIONS)) {
+    throw new Error(`Unknown template "${template}". Run --list-templates to inspect choices.`);
+  }
+}
+
+async function ensureEmptyTargetDirectory(targetDir: string): Promise<void> {
+  try {
+    const stat = await fs.stat(targetDir);
+    if (!stat.isDirectory()) {
+      throw new Error(`Target path exists and is not a directory: ${targetDir}`);
+    }
+    const entries = await fs.readdir(targetDir);
+    if (entries.length > 0) {
+      throw new Error(`Refusing to scaffold into a non-empty directory: ${targetDir}`);
+    }
+  } catch (error) {
+    if (isMissing(error)) {
+      await fs.mkdir(targetDir, { recursive: true });
+      return;
+    }
+    throw error;
+  }
+}
+
+async function collectTemplateFiles(root: string): Promise<string[]> {
+  const entries = await fs.readdir(root, { withFileTypes: true });
+  const files: string[] = [];
+
+  for (const entry of entries) {
+    const fullPath = path.join(root, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await collectTemplateFiles(fullPath)));
+      continue;
+    }
+    if (entry.isFile()) {
+      files.push(fullPath);
+    }
+  }
+
+  return files.sort();
+}
+
+function renderTemplate(content: string, values: TemplateValues): string {
+  return content.replace(/\{\{([A-Z_]+)\}\}/g, (_match, rawKey: string) => {
+    const key = toTemplateValueKey(rawKey);
+    return values[key] ?? _match;
+  });
+}
+
+function toTemplateValueKey(rawKey: string): keyof TemplateValues {
+  const key = rawKey.toLowerCase().replace(/_([a-z])/g, (_match, letter: string) =>
+    letter.toUpperCase()
+  );
+  return key as keyof TemplateValues;
+}
+
+function deriveAppName(targetDir: string): string {
+  const base = path.basename(targetDir);
+  return base === "." || base.length === 0 ? "hla4ts-spacekit-app" : base;
+}
+
+function resolveTemplateDir(template: TemplateId): string {
+  const currentFile = fileURLToPath(import.meta.url);
+  return path.resolve(path.dirname(currentFile), "..", "templates", template);
+}
+
+function isMissing(error: unknown): boolean {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}

package/templates/lunar-rover/.env

@@ -0,0 +1,14 @@
+FEDERATE_NAME={{FEDERATE_NAME}}
+FEDERATION_NAME={{FEDERATION_NAME}}
+FEDERATE_TYPE={{FEDERATE_TYPE}}
+ROVER_NAME={{ROVER_NAME}}
+ROVER_TYPE={{ROVER_TYPE}}
+PARENT_REFERENCE_FRAME={{PARENT_REFERENCE_FRAME}}
+RTI_HOST={{RTI_HOST}}
+RTI_PORT={{RTI_PORT}}
+RTI_USE_TLS={{RTI_USE_TLS}}
+LOOKAHEAD_MICROS={{LOOKAHEAD_MICROS}}
+UPDATE_PERIOD_MICROS={{UPDATE_PERIOD_MICROS}}
+REFERENCE_FRAME_MISSING_MODE={{REFERENCE_FRAME_MISSING_MODE}}
+REFERENCE_FRAME_TIMEOUT_MS={{REFERENCE_FRAME_TIMEOUT_MS}}
+ROVER_SPEED_MPS={{ROVER_SPEED_MPS}}

package/templates/lunar-rover/README.md

@@ -0,0 +1,37 @@
+# {{APP_NAME}}
+
+Minimal lunar rover example generated by `spacekit` from `@hla4ts/create-spacekit`.
+
+This app uses `@hla4ts/spacekit` directly:
+
+- `SpacekitApp.run()` owns the join/bootstrap/tick loop
+- `PhysicalEntity` publishes a single rover object
+- `.env` contains the RTI, federation, rover, and timing defaults
+
+## Prerequisites
+
+- Bun installed
+- an HLA 4 RTI reachable at the configured host/port
+- SpaceMaster and a root reference frame publisher if you are running a SEE late-join federation
+
+## Configure
+
+Edit `.env` if needed:
+
+- `RTI_HOST`, `RTI_PORT`, `RTI_USE_TLS`
+- `FEDERATION_NAME`, `FEDERATE_NAME`, `FEDERATE_TYPE`
+- `ROVER_NAME`, `ROVER_TYPE`, `PARENT_REFERENCE_FRAME`
+- `ROVER_SPEED_MPS`, `LOOKAHEAD_MICROS`, `UPDATE_PERIOD_MICROS`
+- `REFERENCE_FRAME_MISSING_MODE` (`continue` by default)
+
+## Run
+
+```bash
+bun install
+bun run start
+```
+
+The rover moves forward along the X axis at the configured speed and logs each
+published tick. By default the generated app uses `continue` mode for missing
+reference frames, so it warns and keeps running if the configured parent frame
+has not been published yet.

package/templates/lunar-rover/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "{{PACKAGE_NAME}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@hla4ts/spacekit": "{{SPACEKIT_DEPENDENCY}}"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.9.0"
+  }
+}

package/templates/lunar-rover/src/config.ts

@@ -0,0 +1,98 @@
+import {
+  createSpaceFomConfig,
+  type MissingReferenceFrameMode,
+  type SpacekitAppOptions,
+} from "@hla4ts/spacekit";
+
+export interface LunarRoverConfig {
+  app: SpacekitAppOptions;
+  roverName: string;
+  roverType: string;
+  roverStatus: string;
+  parentReferenceFrame: string;
+  roverSpeedMetersPerSec: number;
+  startPosition: [number, number, number];
+}
+
+export function loadConfig(): LunarRoverConfig {
+  const config = createSpaceFomConfig({
+    envDefaults: {
+      federationName: "{{FEDERATION_NAME}}",
+      federateName: "{{FEDERATE_NAME}}",
+      federateType: "{{FEDERATE_TYPE}}",
+      rtiHost: "{{RTI_HOST}}",
+      rtiPort: parseNumber("{{RTI_PORT}}", 15164),
+      rtiUseTls: parseBoolean("{{RTI_USE_TLS}}", false),
+      lookaheadMicros: parseBigInt("{{LOOKAHEAD_MICROS}}", 1000000n),
+      updatePeriodMicros: parseBigInt("{{UPDATE_PERIOD_MICROS}}", 1000000n),
+      referenceFrameTimeoutMs: parseNumber("{{REFERENCE_FRAME_TIMEOUT_MS}}", 30000),
+    },
+    extras: (env) => ({
+      roverName: env.ROVER_NAME ?? "{{ROVER_NAME}}",
+      roverType: env.ROVER_TYPE ?? "{{ROVER_TYPE}}",
+      roverStatus: env.ROVER_STATUS ?? "ACTIVE",
+      parentReferenceFrame: env.PARENT_REFERENCE_FRAME ?? "{{PARENT_REFERENCE_FRAME}}",
+      roverSpeedMetersPerSec: parseNumber(
+        env.ROVER_SPEED_MPS,
+        parseNumber("{{ROVER_SPEED_MPS}}", 0.5)
+      ),
+      startPosition: [
+        parseNumber(env.ROVER_START_X, 0),
+        parseNumber(env.ROVER_START_Y, 0),
+        parseNumber(env.ROVER_START_Z, 0),
+      ] as [number, number, number],
+    }),
+  });
+  config.app.missingReferenceFrameMode = parseReferenceFrameMissingMode(
+    process.env.REFERENCE_FRAME_MISSING_MODE ?? "{{REFERENCE_FRAME_MISSING_MODE}}"
+  );
+  return config;
+}
+
+function parseNumber(value: string | undefined, fallback: number): number {
+  if (value === undefined || value.trim() === "") {
+    return fallback;
+  }
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`Invalid numeric environment value: ${value}`);
+  }
+  return parsed;
+}
+
+function parseBigInt(value: string | undefined, fallback: bigint): bigint {
+  if (value === undefined || value.trim() === "") {
+    return fallback;
+  }
+  try {
+    return BigInt(value);
+  } catch {
+    throw new Error(`Invalid bigint environment value: ${value}`);
+  }
+}
+
+function parseBoolean(value: string | undefined, fallback: boolean): boolean {
+  if (value === undefined || value.trim() === "") {
+    return fallback;
+  }
+  const normalized = value.toLowerCase();
+  if (["true", "1", "yes", "y"].includes(normalized)) {
+    return true;
+  }
+  if (["false", "0", "no", "n"].includes(normalized)) {
+    return false;
+  }
+  throw new Error(`Invalid boolean environment value: ${value}`);
+}
+
+function parseReferenceFrameMissingMode(
+  value: string | undefined
+): MissingReferenceFrameMode {
+  if (!value || value.trim() === "") {
+    return "continue";
+  }
+  if (value === "error" || value === "continue") {
+    return value;
+  }
+  throw new Error(`Invalid reference frame missing mode: ${value}`);
+}

package/templates/lunar-rover/src/index.ts

@@ -0,0 +1,57 @@
+import { PhysicalEntity, SpacekitApp, type SpaceTimeCoordinateState } from "@hla4ts/spacekit";
+import { loadConfig } from "./config.ts";
+
+async function main(): Promise<void> {
+  const config = loadConfig();
+  const app = new SpacekitApp(config.app);
+  const rover = new PhysicalEntity(config.roverName, {
+    type: config.roverType,
+    status: config.roverStatus,
+    parent_reference_frame: config.parentReferenceFrame,
+  });
+
+  await app.run({
+    entities: [rover],
+    onTick: ({ initial, tick, timeMicros, timeSeconds, sendTimeMicros }) => {
+      if (initial) return;
+
+      rover.name = config.roverName;
+      rover.type = config.roverType;
+      rover.status = config.roverStatus;
+      rover.parent_reference_frame = config.parentReferenceFrame;
+      rover.state = buildRoverState(config, timeSeconds);
+
+      if (!app.shouldLogTick(tick)) return;
+
+      app.logger.info("Rover tick.", {
+        tick,
+        logicalTimeMicros: timeMicros.toString(),
+        sendTimeMicros: (sendTimeMicros ?? timeMicros).toString(),
+        position: rover.state.translation.position.map((value) => value.toFixed(3)),
+        velocity: rover.state.translation.velocity.map((value) => value.toFixed(3)),
+      });
+    },
+  });
+}
+
+function buildRoverState(
+  config: ReturnType<typeof loadConfig>,
+  timeSeconds: number
+): SpaceTimeCoordinateState {
+  const [startX, startY, startZ] = config.startPosition;
+  const positionX = startX + config.roverSpeedMetersPerSec * timeSeconds;
+
+  return {
+    translation: {
+      position: [positionX, startY, startZ],
+      velocity: [config.roverSpeedMetersPerSec, 0, 0],
+    },
+    rotation: {
+      attitude: { scalar: 1, vector: [0, 0, 0] },
+      angularVelocity: [0, 0, 0],
+    },
+    time: timeSeconds,
+  };
+}
+
+void main();

package/templates/lunar-rover/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "types": ["bun-types"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "allowImportingTsExtensions": true,
+    "experimentalDecorators": true,
+    "verbatimModuleSyntax": true
+  },
+  "include": ["src/**/*"]
+}