space-data-module-sdk 0.8.11 → 0.8.13

package/src/scaffold/index.js

@@ -0,0 +1,150 @@
+/**
+ * `space-data-module init` — scaffold a new SDN WASM module skeleton from a
+ * family template under `templates/<family>-module/`.
+ *
+ * Family resolution deliberately mirrors `normalizePluginFamily`
+ * (`src/manifest/normalize.js`): an unrecognized value is a THROW, never a
+ * silent fallback to a generic template. Two checks apply, in order:
+ *
+ *   1. Is `--family` even a name in the SDK's plugin-family vocabulary
+ *      (the same vocabulary `pluginFamily` in a manifest is validated
+ *      against)? If not, `normalizePluginFamily` itself throws
+ *      `UnknownPluginFamilyError`, naming the offender and the whole
+ *      vocabulary.
+ *   2. Does that family have an init TEMPLATE (`templates/<family>-module/
+ *      plugin-manifest.json`)? Most families do not — only `propagator`
+ *      ships one today. If not, `ScaffoldFamilyTemplateError` names the
+ *      offender and lists the families that DO have a template.
+ *
+ * Both refusals name the value and the valid vocabulary; neither ever
+ * degrades into "pick the closest template" or "use a blank template".
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { normalizePluginFamily } from "../manifest/normalize.js";
+import { copyTemplateTree, ensureWritableOutputDir } from "./copyTemplate.js";
+import { buildTokenMap } from "./tokens.js";
+
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+export const packageRoot = path.resolve(moduleDir, "..", "..");
+export const templatesRoot = path.join(packageRoot, "templates");
+
+const TEMPLATE_DIR_SUFFIX = "-module";
+/** The file every real init-scaffold template must have at its root. This is
+ * what distinguishes a scaffold template (propagator-module) from the
+ * pre-existing ABI-header-only reference dirs under templates/
+ * (gpu-module, provider-access-module) that ship no plugin-manifest.json and
+ * are not meant to be scaffolded from. */
+const TEMPLATE_MANIFEST_FILE = "plugin-manifest.json";
+
+/**
+ * Thrown when `--family` names a value that does not have an init template,
+ * even if it IS a recognized `pluginFamily` string. Distinct from
+ * `UnknownPluginFamilyError` (which fires first, for values that are not a
+ * recognized family AT ALL) — this one fires for real-but-template-less
+ * families such as "sensor" today.
+ */
+export class ScaffoldFamilyTemplateError extends Error {
+  constructor(value, availableFamilies) {
+    const list =
+      availableFamilies.length > 0
+        ? availableFamilies.join(", ")
+        : "(none — no templates/*-module directory has a plugin-manifest.json yet)";
+    super(
+      `No init template for family ${JSON.stringify(value)}. ` +
+        `Families with an init template: ${list}.`,
+    );
+    this.name = "ScaffoldFamilyTemplateError";
+    this.code = "unknown-scaffold-family-template";
+    this.value = value;
+    this.availableFamilies = availableFamilies;
+  }
+}
+
+/** List family names (e.g. `["propagator"]`) that have a real init template. */
+export function listScaffoldFamilies() {
+  let entries;
+  try {
+    entries = fs.readdirSync(templatesRoot, { withFileTypes: true });
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+  const families = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !entry.name.endsWith(TEMPLATE_DIR_SUFFIX)) {
+      continue;
+    }
+    const manifestPath = path.join(
+      templatesRoot,
+      entry.name,
+      TEMPLATE_MANIFEST_FILE,
+    );
+    if (fs.existsSync(manifestPath)) {
+      families.push(entry.name.slice(0, -TEMPLATE_DIR_SUFFIX.length));
+    }
+  }
+  return families.sort();
+}
+
+/**
+ * Resolve `--family` to a template directory, or throw loudly. See the
+ * module docstring for the two-stage refusal shape.
+ */
+export function resolveScaffoldTemplateDir(family) {
+  // Stage 1: is this even a real plugin family? Throws UnknownPluginFamilyError
+  // (naming the value + the FULL manifest vocabulary) if not.
+  normalizePluginFamily(family);
+
+  const normalized = String(family).trim().toLowerCase();
+  const available = listScaffoldFamilies();
+  if (!available.includes(normalized)) {
+    // Stage 2: real family, but no init template ships for it (yet).
+    throw new ScaffoldFamilyTemplateError(family, available);
+  }
+  return path.join(templatesRoot, `${normalized}${TEMPLATE_DIR_SUFFIX}`);
+}
+
+/**
+ * Scaffold a new module skeleton.
+ *
+ * @param {object} options
+ * @param {string} options.family - e.g. "propagator". Must have an init
+ *   template (see {@link resolveScaffoldTemplateDir}).
+ * @param {string} options.name - kebab-case module name, e.g. "my-propagator".
+ * @param {string} [options.outDir] - defaults to `./<name>` under cwd.
+ * @param {string} [options.pluginId] - defaults to
+ *   `com.orbpro.<name-with-dots>`.
+ * @param {boolean} [options.force] - allow scaffolding into a non-empty
+ *   `outDir`.
+ * @returns {Promise<{ok: true, family: string, name: string, pluginId: string, outDir: string, files: string[]}>}
+ */
+export async function scaffoldModule({
+  family,
+  name,
+  outDir,
+  pluginId,
+  force = false,
+} = {}) {
+  const templateDir = resolveScaffoldTemplateDir(family);
+  const tokens = buildTokenMap({ name, pluginId });
+  const resolvedOutDir = path.resolve(outDir ?? path.join(process.cwd(), name));
+
+  await ensureWritableOutputDir(resolvedOutDir, force === true);
+  const files = await copyTemplateTree(templateDir, resolvedOutDir, tokens);
+
+  return {
+    ok: true,
+    family: String(family).trim().toLowerCase(),
+    name,
+    pluginId: tokens.PLUGIN_ID,
+    outDir: resolvedOutDir,
+    files,
+  };
+}
+
+export { defaultPluginId } from "./tokens.js";

package/src/scaffold/tokens.js

@@ -0,0 +1,90 @@
+/**
+ * Token vocabulary for `space-data-module init`.
+ *
+ * These are the ONLY tokens the scaffold engine substitutes. They are matched
+ * as whole `__NAME__` runs so a token can never partially match inside a
+ * longer identifier that happens to share a prefix.
+ */
+export const SCAFFOLD_TOKEN_NAMES = Object.freeze([
+  "MODULE_NAME",
+  "PLUGIN_ID",
+  "MODULE_NAME_SNAKE",
+  "MODULE_NAME_CAMEL",
+]);
+
+const TOKEN_PATTERN = new RegExp(
+  `__(${SCAFFOLD_TOKEN_NAMES.join("|")})__`,
+  "g",
+);
+
+const MODULE_NAME_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+/**
+ * Validate a `--name` value against the kebab-case shape every derived token
+ * assumes. Refuses loudly rather than silently mangling an unexpected name
+ * into something that merely looks plausible.
+ */
+export function assertValidModuleName(name) {
+  if (typeof name !== "string" || name.trim().length === 0) {
+    throw new Error("--name is required and must be a non-empty string.");
+  }
+  if (!MODULE_NAME_PATTERN.test(name)) {
+    throw new Error(
+      `--name ${JSON.stringify(name)} is not valid. Module names must be ` +
+        `lowercase kebab-case: start with a letter, then letters, digits, or ` +
+        `single hyphens (e.g. "keplerian-reference").`,
+    );
+  }
+}
+
+/** `foo-bar` -> `foo_bar` */
+export function toSnakeCase(name) {
+  return name.replace(/-/g, "_");
+}
+
+/** `foo-bar` -> `fooBar` */
+export function toCamelCase(name) {
+  return name
+    .split(/[-_]+/)
+    .filter(Boolean)
+    .map((part, index) =>
+      index === 0
+        ? part.toLowerCase()
+        : part.charAt(0).toUpperCase() + part.slice(1).toLowerCase(),
+    )
+    .join("");
+}
+
+/**
+ * `com.orbpro.<module-name-with-dots>` — the documented default `--plugin-id`
+ * when the author does not supply one. Hyphens become dots so the plugin id
+ * reads as reverse-DNS-style segments, matching how the SDK's own examples
+ * namespace multi-word module ids.
+ */
+export function defaultPluginId(name) {
+  return `com.orbpro.${name.replace(/-/g, ".")}`;
+}
+
+/**
+ * Build the full token -> replacement-string map for one scaffold run.
+ */
+export function buildTokenMap({ name, pluginId }) {
+  assertValidModuleName(name);
+  const resolvedPluginId =
+    typeof pluginId === "string" && pluginId.trim().length > 0
+      ? pluginId.trim()
+      : defaultPluginId(name);
+  return {
+    MODULE_NAME: name,
+    PLUGIN_ID: resolvedPluginId,
+    MODULE_NAME_SNAKE: toSnakeCase(name),
+    MODULE_NAME_CAMEL: toCamelCase(name),
+  };
+}
+
+/** Substitute every `__TOKEN__` occurrence in `text` using `tokens`. */
+export function substituteTokens(text, tokens) {
+  return text.replace(TOKEN_PATTERN, (match, key) =>
+    key in tokens ? tokens[key] : match,
+  );
+}

package/src/testing/parityBrowserRunner.js

@@ -17,6 +17,7 @@ import { createBrowserModuleHarness } from "../host/browserModuleHarness.js";
 const OK = "ok";
 const GUEST_ERROR = "guest-error";
 const TRAP = "trap";
+const OUT_OF_SCOPE = "out-of-declared-scope";
 
 function base64ToBytes(value) {
   const binary = atob(String(value ?? ""));
@@ -42,6 +43,16 @@ function classifyBrowserError(error) {
   if (error?.name === "WasiExitError") {
     return { exitClass: GUEST_ERROR, exitDetail: `exit=${error.code}` };
   }
+  // The harness refused the artifact because the ARTIFACT declares it does not
+  // run here. That is the contract working. Classing it TRAP would score a
+  // correct refusal as a P1 cross-runtime divergence — the gate failing the
+  // very artifacts the compiler now legitimately emits.
+  if (error?.name === "RuntimeTargetError") {
+    return {
+      exitClass: OUT_OF_SCOPE,
+      exitDetail: `declared runtimeTargets [${(error.declaredTargets ?? []).join(", ")}]`,
+    };
+  }
   return {
     exitClass: TRAP,
     exitDetail: `${error?.name ?? "Error"}: ${error?.message ?? String(error)}`,