@hypit/hypit 0.0.1 → 0.1.0

package/packages/package-loader-node/src/loader.ts

@@ -0,0 +1,301 @@
+import { readFile, realpath, stat } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { modulePackageAbi } from "@hypit/protocol";
+
+import type {
+  LoadedPackage,
+  LogicalPackageAddress,
+  NodePackageLoadOptions,
+  NodePackageContribution,
+  NodePackageSelectionRequest,
+} from "./types.js";
+import { externalPackageRoots, locateNodePackage } from "./location.js";
+
+type PackageJson = {
+  readonly name: string;
+  readonly version?: string;
+  readonly hypit?: { readonly activation?: string };
+  readonly dependencies: Readonly<Record<string, string>>;
+};
+
+type ResolvedPackage = { readonly root: string; readonly json: PackageJson };
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+function object(value: unknown, subject: string): Record<string, unknown> {
+  assert(value !== null && typeof value === "object" && !Array.isArray(value), `${subject} must be an object`);
+  return value as Record<string, unknown>;
+}
+
+function text(value: unknown, subject: string): string {
+  assert(typeof value === "string" && value.length > 0, `${subject} must be a non-empty string`);
+  return value;
+}
+
+function parsePackageJson(value: unknown, subject: string): PackageJson {
+  const item = object(value, subject);
+  const hypit = item.hypit === undefined ? undefined : object(item.hypit, `${subject}.hypit`);
+  const dependencies = item.dependencies === undefined ? {} : object(item.dependencies, `${subject}.dependencies`);
+  return {
+    name: text(item.name, `${subject}.name`),
+    ...(item.version === undefined ? {} : { version: text(item.version, `${subject}.version`) }),
+    ...(hypit?.activation === undefined ? {} : { hypit: { activation: text(hypit.activation, `${subject}.hypit.activation`) } }),
+    dependencies: Object.fromEntries(Object.entries(dependencies).map(([name, version]) => [
+      name,
+      text(version, `${subject}.dependencies.${name}`),
+    ])),
+  };
+}
+
+async function packageJson(root: string): Promise<PackageJson> {
+  const path = join(root, "package.json");
+  return parsePackageJson(JSON.parse(await readFile(path, "utf8")), path);
+}
+
+async function resolvePackage(specifier: string, roots: readonly string[]): Promise<ResolvedPackage> {
+  let failure: unknown;
+  for (const from of roots) {
+    try {
+      const located = locateNodePackage(specifier, {
+        from: join(resolve(from), "__hypit_package_loader__.mjs"),
+        workspaceRoots: [from],
+        distributionRoots: specifier.startsWith("@hypit/") ? [from] : [],
+        externalRoots: [],
+        allowExternal: false,
+      });
+      return { root: located.root, json: await packageJson(located.root) };
+    } catch (error) {
+      failure = error;
+    }
+  }
+  throw new Error(`cannot resolve installed package ${specifier} from ${roots.join(", ")}: ${failure instanceof Error ? failure.message : String(failure)}`);
+}
+
+function resolutionRoots(
+  specifier: string,
+  projectRoots: readonly string[],
+  distributionRoots: readonly string[],
+): readonly string[] {
+  // @hypit is the active Distribution's namespace. A project dependency with
+  // the same spelling must never silently replace the tool ABI it is using.
+  return specifier.startsWith("@hypit/") && distributionRoots.length > 0
+    ? distributionRoots
+    : [...projectRoots, ...distributionRoots];
+}
+
+function activationPath(item: ResolvedPackage): string {
+  const declared = item.json.hypit?.activation;
+  assert(declared !== undefined, `${item.json.name} does not declare hypit.activation`);
+  assert(!isAbsolute(declared), `${item.json.name} activation must be package-relative`);
+  const target = resolve(item.root, declared);
+  const relation = relative(item.root, target);
+  assert(relation !== "" && relation !== ".." && !relation.startsWith(`..${sep}`), `${item.json.name} activation escapes its package`);
+  return target;
+}
+
+async function importContribution(item: ResolvedPackage): Promise<NodePackageContribution> {
+  const target = activationPath(item);
+  assert((await stat(target)).isFile(), `${item.json.name} activation is not a file`);
+  const imported = await import(pathToFileURL(target).href) as { readonly default?: unknown };
+  assert(imported.default !== null && typeof imported.default === "object", `${item.json.name} activation has no default package export`);
+  const contribution = imported.default as Partial<NodePackageContribution>;
+  assert(contribution.format === "hypit.node-package@1", `${item.json.name} activation has an unsupported package format`);
+  return contribution as NodePackageContribution;
+}
+
+function within(root: string, candidate: string): boolean {
+  const relation = relative(resolve(root), resolve(candidate));
+  return relation === "" || (relation !== ".." && !relation.startsWith(`..${sep}`) && !isAbsolute(relation));
+}
+
+async function assertExternalDependencies(
+  item: ResolvedPackage,
+  distributionRoots: readonly string[],
+  externalRoots: readonly string[],
+): Promise<void> {
+  const distributionOwned = distributionRoots.some((root) => within(root, item.root));
+  for (const [name, required] of Object.entries(item.json.dependencies)) {
+    if (name.startsWith("@hypit/") || required.startsWith("workspace:")) continue;
+    try {
+      const resolved = locateNodePackage(name, {
+        from: join(item.root, "__hypit_package_dependencies__.mjs"),
+        distributionRoots,
+        externalRoots,
+        allowExternal: distributionOwned,
+      });
+      if (/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/u.test(required)
+        && resolved.manifest.version !== required) {
+        throw new Error(`installed version is ${resolved.manifest.version ?? "unknown"}`);
+      }
+    } catch (error) {
+      const repair = distributionOwned
+        ? `Install it once with: hypit packages install ${name}@${required}`
+        : `Install it with the project package manager that owns ${item.root}`;
+      throw new Error(`${item.json.name} requires ${name}@${required}. ${repair}`, { cause: error });
+    }
+  }
+}
+
+function addressKey(value: LogicalPackageAddress): string {
+  return `${value.abi}\u0000${value.name}`;
+}
+
+function offers(value: NodePackageContribution): readonly LogicalPackageAddress[] {
+  return [
+    ...(value.modules ?? []).flatMap((item) => [
+      `${item.manifest.name}@${item.manifest.version}`,
+      ...(item.specifiers ?? []),
+    ].map((name) => ({ abi: modulePackageAbi, name }))),
+    ...(value.hostFacets ?? []).flatMap((facet) => (facet.offers ?? []).map((name) => ({ abi: facet.abi, name }))),
+  ];
+}
+
+/** Conventional physical package spelling for a logical @scope/name@version address. */
+export function physicalPackageName(logical: string): string {
+  const slash = logical.startsWith("@") ? logical.indexOf("/", 1) : -1;
+  const version = logical.lastIndexOf("@");
+  const unversioned = version > Math.max(slash, 0) ? logical.slice(0, version) : logical;
+  if (!unversioned.startsWith("@")) return unversioned.split("/", 1)[0]!;
+  const packageSlash = unversioned.indexOf("/", 1);
+  const subpath = unversioned.indexOf("/", packageSlash + 1);
+  return subpath < 0 ? unversioned : unversioned.slice(0, subpath);
+}
+
+export class NodePackageSelectionMissingError extends Error {
+  readonly code = "PACKAGE_SELECTION_MISSING";
+  constructor(readonly address: LogicalPackageAddress) {
+    super(`installed packages do not provide ${address.abi} ${address.name}`);
+    this.name = "NodePackageSelectionMissingError";
+  }
+}
+
+/**
+ * Resolve the ordinary upstream npm dependencies of Distribution packages.
+ * Internal @hypit dependencies are followed to their manifests. Other selected
+ * packages belong to their project's package manager, including their dependencies.
+ */
+export async function distributionExternalPackageRequirements(
+  specifiers: readonly string[],
+  distributionRoot: string,
+): Promise<readonly { readonly name: string; readonly version: string; readonly specifier: string }[]> {
+  const root = resolve(distributionRoot);
+  const queue = [...new Set(specifiers.filter((name) => name.startsWith("@hypit/")))].sort();
+  const visited = new Set<string>();
+  const external = new Map<string, string>();
+  while (queue.length > 0) {
+    const name = queue.shift()!;
+    if (visited.has(name)) continue;
+    visited.add(name);
+    const physical = await resolvePackage(name, [root]);
+    for (const [dependency, version] of Object.entries(physical.json.dependencies)) {
+      if (dependency.startsWith("@hypit/")) {
+        queue.push(dependency);
+        continue;
+      }
+      const previous = external.get(dependency);
+      if (previous !== undefined && previous !== version) {
+        throw new Error(`${dependency} is required at both ${previous} and ${version} by the selected Distribution packages`);
+      }
+      external.set(dependency, version);
+    }
+  }
+  return [...external.entries()]
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([name, version]) => ({ name, version, specifier: `${name}@${version}` }));
+}
+
+/**
+ * Load the packages explicitly named by Source discovery or a Runtime Profile.
+ * Node's package manager owns installed versions and bytes; Hypit validates only the
+ * contribution boundary it consumes.
+ */
+export async function loadNodePackageSelection(
+  request: readonly string[] | NodePackageSelectionRequest,
+  root: string,
+  options: NodePackageLoadOptions = {},
+): Promise<readonly LoadedPackage[]> {
+  const normalized: NodePackageSelectionRequest = Array.isArray(request)
+    ? { selected: request }
+    : request as NodePackageSelectionRequest;
+  const selected = new Set(normalized.selected);
+  for (const address of normalized.logical ?? []) selected.add(physicalPackageName(address.name));
+  if (selected.size === 0) return [];
+
+  const projectRoot = await realpath(root);
+  const projectRoots = [projectRoot];
+  const distributionRoots = (await Promise.all((options.fallbackRoots ?? []).map(async (candidate) =>
+    await realpath(candidate))))
+    .filter((candidate) => candidate !== projectRoot);
+  const externalRoots = options.externalRoots ?? externalPackageRoots();
+  const roots = await Promise.all([...selected].sort().map(async (name) =>
+    await resolvePackage(name, resolutionRoots(name, projectRoots, distributionRoots))));
+  type ActivatedPackage = { readonly physical: ResolvedPackage; readonly contribution: NodePackageContribution };
+  const activated = new Map<string, ActivatedPackage>();
+  const providedModules = new Set<string>();
+  const requirements: { readonly key: string; readonly from: string }[] = [];
+  const moduleKey = (name: string, version: string) => `${name}@${version}`;
+  const add = (item: ActivatedPackage): void => {
+    assert(!activated.has(item.physical.json.name), `selected package ${item.physical.json.name} is repeated`);
+    activated.set(item.physical.json.name, item);
+    for (const module of item.contribution.modules ?? []) {
+      const key = moduleKey(module.manifest.name, module.manifest.version);
+      assert(!providedModules.has(key), `selected packages provide ${key} more than once`);
+      providedModules.add(key);
+      for (const dependency of module.manifest.dependencies) {
+        requirements.push({
+          key: moduleKey(dependency.module.name, dependency.module.version),
+          from: item.physical.root,
+        });
+      }
+    }
+  };
+  for (const item of await Promise.all(roots.map(async (physical) => ({
+    physical,
+    contribution: await (async () => {
+      await assertExternalDependencies(physical, distributionRoots, externalRoots);
+      return await importContribution(physical);
+    })(),
+  })))) add(item);
+
+  for (let cursor = 0; cursor < requirements.length; cursor += 1) {
+    const requirement = requirements[cursor] as { readonly key: string; readonly from: string };
+    if (providedModules.has(requirement.key)) continue;
+    const providerPackage = physicalPackageName(requirement.key);
+    assert(!activated.has(providerPackage), `selected package ${providerPackage} provides the wrong ${requirement.key}`);
+    const physical = await resolvePackage(
+      providerPackage,
+      resolutionRoots(providerPackage, [requirement.from, root], distributionRoots),
+    );
+    await assertExternalDependencies(physical, distributionRoots, externalRoots);
+    const provider = { physical, contribution: await importContribution(physical) };
+    add(provider);
+    assert(providedModules.has(requirement.key), `${providerPackage} does not provide the required ${requirement.key}`);
+  }
+
+  const offerOwners = new Map<string, Set<string>>();
+  for (const item of activated.values()) {
+    for (const offer of offers(item.contribution)) {
+      const key = addressKey(offer);
+      const owners = offerOwners.get(key) ?? new Set<string>();
+      owners.add(item.physical.json.name);
+      offerOwners.set(key, owners);
+    }
+  }
+  for (const address of normalized.logical ?? []) {
+    const providers = offerOwners.get(addressKey(address));
+    if (providers === undefined || providers.size === 0) throw new NodePackageSelectionMissingError(address);
+    assert(providers.size === 1, `${address.abi} ${address.name} is provided by more than one selected package`);
+  }
+
+  const packages: LoadedPackage[] = [...activated.values()]
+    .sort((left, right) => left.physical.json.name.localeCompare(right.physical.json.name))
+    .map((item) => ({
+      specifier: item.physical.json.name,
+      contribution: item.contribution,
+    }));
+  return packages;
+}

package/packages/package-loader-node/src/location.ts

@@ -0,0 +1,279 @@
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type LocatedNodePackage = {
+  readonly root: string;
+  readonly manifest: {
+    readonly name: string;
+    readonly version?: string;
+    readonly bin?: string | Readonly<Record<string, string>>;
+  };
+};
+
+export type LocatedNodePackageSource = {
+  readonly specifier: string;
+  readonly package: string;
+  readonly root: string;
+  readonly source: string;
+};
+
+export type LocateNodePackageOptions = {
+  /** File or module URL whose owning package is requesting the dependency. */
+  readonly from: string | URL;
+  /** Explicit project roots whose `packages/` or `services/` directories own selected packages. */
+  readonly workspaceRoots?: readonly string[];
+  /** Defaults to the active Hypit Distribution roots. */
+  readonly distributionRoots?: readonly string[];
+  /** Defaults to the active machine npm package roots. */
+  readonly externalRoots?: readonly string[];
+  /** Defaults to true only when `from` belongs to the active Distribution. */
+  readonly allowExternal?: boolean;
+};
+
+let activeDistributionRoots: readonly string[] = [];
+let activeExternalRoots: readonly string[] = [];
+
+function normalizedRoots(roots: readonly string[]): readonly string[] {
+  return [...new Set(roots.map((root) => resolve(root)))];
+}
+
+export function setActiveDistributionPackageRoots(roots: readonly string[]): void {
+  activeDistributionRoots = normalizedRoots(roots);
+}
+
+export function setActiveExternalPackageRoots(roots: readonly string[]): void {
+  activeExternalRoots = normalizedRoots(roots);
+}
+
+export function externalPackageRoots(): readonly string[] {
+  return activeExternalRoots;
+}
+
+function within(root: string, candidate: string): boolean {
+  const relation = relative(resolve(root), resolve(candidate));
+  return relation === "" || (relation !== ".." && !relation.startsWith(`..${sep}`) && !isAbsolute(relation));
+}
+
+function packageName(value: string): string {
+  const parts = value.split("/");
+  const segment = (item: string): boolean => /^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(item)
+    && item !== "." && item !== "..";
+  const valid = value.startsWith("@")
+    ? parts.length === 2 && parts[0]!.startsWith("@") && segment(parts[0]!.slice(1)) && segment(parts[1]!)
+    : parts.length === 1 && segment(value);
+  if (!valid) throw new Error(`${value} must be one exact npm package name`);
+  return value;
+}
+
+function packageSourceAddress(value: string): { readonly name: string; readonly subpath: string } {
+  if (value.startsWith(".") || value.startsWith("/") || value.startsWith("#") || value.includes(":")) {
+    throw new Error(`${value} must be one npm package Source export`);
+  }
+  const parts = value.split("/");
+  const name = value.startsWith("@")
+    ? parts.length >= 2 ? `${parts[0]}/${parts[1]}` : ""
+    : parts[0] ?? "";
+  const subpath = value.startsWith("@") ? parts.slice(2).join("/") : parts.slice(1).join("/");
+  packageName(name);
+  if (subpath.length > 0
+    && subpath.split("/").some((part) => part.length === 0 || part === "." || part === "..")) {
+    throw new Error(`${value} has an invalid package Source export path`);
+  }
+  return { name, subpath };
+}
+
+function fromPath(value: string | URL): string {
+  return value instanceof URL || value.startsWith("file:") ? fileURLToPath(value) : resolve(value);
+}
+
+function readPackage(root: string, expectedName: string): LocatedNodePackage | undefined {
+  const path = join(root, "package.json");
+  if (!existsSync(path)) return undefined;
+  const value = JSON.parse(readFileSync(path, "utf8")) as {
+    readonly name?: unknown;
+    readonly version?: unknown;
+    readonly bin?: unknown;
+  };
+  if (value.name !== expectedName) return undefined;
+  const bin = typeof value.bin === "string"
+    ? value.bin
+    : value.bin !== null && typeof value.bin === "object" && !Array.isArray(value.bin)
+      ? Object.fromEntries(Object.entries(value.bin).map(([name, target]) => {
+        if (typeof target !== "string") throw new Error(`${path}.bin.${name} must be a string`);
+        return [name, target];
+      }))
+      : undefined;
+  if (value.version !== undefined && typeof value.version !== "string") {
+    throw new Error(`${path}.version must be a string`);
+  }
+  return {
+    // `.native` because this is the physical path, and on Windows the JavaScript `realpathSync`
+    // resolves symlinks and junctions without expanding an 8.3 short name. A temporary directory
+    // under a service account arrives as `RUNNER~1\AppData\...`, so a root located here and the same
+    // root canonicalized through the asynchronous `realpath` — which does go through libuv — are two
+    // different strings for one directory, and every comparison between them fails.
+    root: realpathSync.native(root),
+    manifest: {
+      name: expectedName,
+      ...(value.version === undefined ? {} : { version: value.version }),
+      ...(bin === undefined ? {} : { bin }),
+    },
+  };
+}
+
+function nodeModulesPackage(root: string, name: string): LocatedNodePackage | undefined {
+  return readPackage(join(root, "node_modules", ...name.split("/")), name);
+}
+
+function ancestorPackage(name: string, from: string): LocatedNodePackage | undefined {
+  let cursor = dirname(from);
+  while (true) {
+    const found = nodeModulesPackage(cursor, name);
+    if (found !== undefined) return found;
+    const parent = dirname(cursor);
+    if (parent === cursor) return undefined;
+    cursor = parent;
+  }
+}
+
+export function distributionPackageDirectory(root: string, name: string): string | undefined {
+  const conventional = join(resolve(root), "packages", name.split("/").at(-1)!);
+  if (readPackage(conventional, name) !== undefined) return conventional;
+  const services = join(resolve(root), "services");
+  if (!existsSync(services)) return undefined;
+  for (const entry of readdirSync(services, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const candidate = join(services, entry.name);
+    if (readPackage(candidate, name) !== undefined) return candidate;
+  }
+  return undefined;
+}
+
+function distributionPackage(root: string, name: string): LocatedNodePackage | undefined {
+  const directory = distributionPackageDirectory(root, name);
+  return directory === undefined ? nodeModulesPackage(root, name) : readPackage(directory, name);
+}
+
+/**
+ * Locate package identity without assuming it has a CommonJS/root export. Package ownership stays
+ * explicit: @hypit belongs to the Distribution, project dependencies stay project-local, and only
+ * Distribution code may fall back to the machine npm home.
+ */
+export function locateNodePackage(nameValue: string, options: LocateNodePackageOptions): LocatedNodePackage {
+  const name = packageName(nameValue);
+  const from = fromPath(options.from);
+  const workspaceRoots = normalizedRoots(options.workspaceRoots ?? []);
+  const distributionRoots = normalizedRoots(options.distributionRoots ?? activeDistributionRoots);
+  const externalRoots = normalizedRoots(options.externalRoots ?? activeExternalRoots);
+  const nearby = ancestorPackage(name, from);
+
+  if (name.startsWith("@hypit/")) {
+    if (nearby !== undefined && (distributionRoots.length === 0
+      || distributionRoots.some((root) => within(root, nearby.root)))) return nearby;
+    for (const root of distributionRoots) {
+      const found = distributionPackage(root, name);
+      if (found !== undefined) return found;
+    }
+    throw new Error(`Active Hypit Distribution does not provide ${name}`);
+  }
+
+  if (nearby !== undefined) return nearby;
+  for (const root of workspaceRoots) {
+    const found = distributionPackage(root, name);
+    if (found !== undefined) return found;
+  }
+  const allowExternal = options.allowExternal
+    ?? distributionRoots.some((root) => within(root, dirname(from)));
+  if (allowExternal) {
+    for (const root of externalRoots) {
+      const found = nodeModulesPackage(root, name);
+      if (found !== undefined) return found;
+    }
+  }
+  throw new Error(`cannot locate installed package ${name}`);
+}
+
+function packageFile(
+  packageValue: LocatedNodePackage,
+  relativePath: string,
+  subject: string,
+): string {
+  if (relativePath.length === 0 || isAbsolute(relativePath)) {
+    throw new Error(`${subject} must be a non-empty package-relative path`);
+  }
+  const target = resolve(packageValue.root, relativePath);
+  const relation = relative(packageValue.root, target);
+  if (relation === "" || relation === ".." || relation.startsWith(`..${sep}`) || isAbsolute(relation)) {
+    throw new Error(`${subject} escapes ${packageValue.manifest.name}`);
+  }
+  if (!existsSync(target) || !statSync(target).isFile()) {
+    throw new Error(`${packageValue.manifest.name} does not contain ${relativePath}`);
+  }
+  return target;
+}
+
+/** Resolve an explicitly named package asset; package exports are module API, not a file inventory. */
+export function resolveNodePackageResource(
+  name: string,
+  relativePath: string,
+  options: LocateNodePackageOptions,
+): string {
+  return packageFile(locateNodePackage(name, options), relativePath, `${name} resource path`);
+}
+
+/**
+ * Resolve one explicitly imported Source through the owning package's standard `exports` map.
+ * This reads package data only; it never imports `hypit.activation` or executes package code.
+ */
+export function resolveNodePackageSource(
+  specifier: string,
+  options: LocateNodePackageOptions,
+): LocatedNodePackageSource {
+  const address = packageSourceAddress(specifier);
+  const located = locateNodePackage(address.name, options);
+  const manifestPath = join(located.root, "package.json");
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as {
+    readonly name?: unknown;
+    readonly exports?: unknown;
+  };
+  if (manifest.name !== address.name) throw new Error(`${manifestPath} does not describe ${address.name}`);
+  const key = address.subpath.length === 0 ? "." : `./${address.subpath}`;
+  let declared: unknown;
+  if (typeof manifest.exports === "string") {
+    if (key === ".") declared = manifest.exports;
+  } else if (manifest.exports !== null && typeof manifest.exports === "object" && !Array.isArray(manifest.exports)) {
+    declared = (manifest.exports as Readonly<Record<string, unknown>>)[key];
+  }
+  if (typeof declared !== "string") {
+    throw new Error(`${address.name} does not export Source ${key}`);
+  }
+  return {
+    specifier,
+    package: address.name,
+    root: located.root,
+    source: packageFile(located, declared, `${address.name} Source export ${key}`),
+  };
+}
+
+/** Resolve a command from the package's standard npm `bin` declaration. */
+export function resolveNodePackageExecutable(
+  name: string,
+  executable: string | undefined,
+  options: LocateNodePackageOptions,
+): string {
+  const located = locateNodePackage(name, options);
+  const declared = located.manifest.bin;
+  let target: string | undefined;
+  if (typeof declared === "string") {
+    const defaultName = name.split("/").at(-1)!;
+    if (executable === undefined || executable === defaultName) target = declared;
+  } else if (declared !== undefined) {
+    if (executable !== undefined) target = declared[executable];
+    else if (Object.keys(declared).length === 1) target = Object.values(declared)[0];
+  }
+  if (target === undefined) {
+    throw new Error(`${name} does not declare${executable === undefined ? " one unambiguous executable" : ` executable ${executable}`}`);
+  }
+  return packageFile(located, target, `${name} executable`);
+}

package/packages/package-loader-node/src/types.ts

@@ -0,0 +1,60 @@
+import type { ComponentPackage } from "@hypit/component-kit";
+import type { HostFacet } from "@hypit/host";
+import type { ModuleManifest } from "@hypit/protocol";
+
+/** Semantic Module declaration carried by one physical Node package. */
+export type NodeModuleContribution = {
+  readonly manifest: ModuleManifest;
+  /** Additional author import spellings resolved to this exact Manifest. */
+  readonly specifiers?: readonly string[];
+};
+
+/** Opaque logical address resolved to an explicitly selected installed package. */
+export type LogicalPackageAddress = {
+  readonly abi: string;
+  readonly name: string;
+};
+
+/**
+ * Executable facets exported by one installed physical package. The Host independently grants
+ * each exact Host ABI. Runtime facets remain inert unless a Runtime Profile selects the package.
+ */
+export type NodePackageContribution = {
+  readonly format: "hypit.node-package@1";
+  readonly modules?: readonly NodeModuleContribution[];
+  /** Syntax- or Host-specific executable facets, inert until their exact Host ABI selects them. */
+  readonly hostFacets?: readonly HostFacet[];
+  readonly components?: readonly ComponentPackage[];
+};
+
+/** Physical owner established by the Host; executable code never self-asserts this identity. */
+export type LoadedPackage = {
+  readonly specifier: string;
+  readonly contribution: NodePackageContribution;
+};
+
+/** Runtime Component implementations grouped by their physical package owner. */
+export type LoadedComponentPackage = {
+  readonly specifier: string;
+  readonly components: readonly ComponentPackage[];
+};
+
+export type NodePackageSelectionRequest = {
+  /** Physical packages selected by Source discovery or a Runtime Profile. */
+  readonly selected: readonly string[];
+  /** Logical capabilities that the selected packages must provide. */
+  readonly logical?: readonly LogicalPackageAddress[];
+};
+
+export type NodePackageLoadOptions = {
+  /**
+   * Additional read-only Distribution roots. They are fallbacks for project-scoped packages;
+   * the reserved @hypit namespace resolves only from these roots when they are present.
+   */
+  readonly fallbackRoots?: readonly string[];
+  /**
+   * Machine npm homes used only by Distribution-owned packages for their ordinary upstream
+   * dependencies. Defaults to the roots installed by the Hypit launcher.
+   */
+  readonly externalRoots?: readonly string[];
+};

package/packages/program-space/README.md

@@ -0,0 +1,20 @@
+# `@hypit/program-space`
+
+The time and frame domain shared by a compiled film. ProgramSpace contains `id`, `durationSec` and
+`frameRate`. Script identity belongs to semantic data; the physical film clock also serves animation
+with no speech or source media.
+
+For spoken work, SemanticTrack projects the selected performance's real duration and frame rate.
+For authored animation, `Space` declares them directly:
+
+```svml
+<import as="time" from="@hypit/program-space@1"/>
+<time:Space id="animation" frame-rate="30" duration="8s"/>
+```
+
+`duration` accepts seconds, milliseconds or frames (`8s`, `8000ms`, `240f`); the result must end on an
+exact frame boundary. The rate may be rational, such as `30000/1001`. `Space` publishes an ordinary
+inline ProgramSpace value and performs no media generation.
+
+`Clock` is the duration-free frame-rate input for media normalization. A clock does not prescribe
+how long a performance will be; its actual normalized material establishes that later.

package/packages/program-space/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@hypit/program-space",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "hypit": {
+    "activation": "./src/activation.ts"
+  },
+  "dependencies": {
+    "@hypit/markup": "workspace:*",
+    "@hypit/protocol": "workspace:*"
+  }
+}