Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

refactor: centralize machine package resolution

kashorinec075a86d82f
diff --git a/docs/guide/providers.md b/docs/guide/providers.md
index c43cd3fb..1e2094a8 100644
--- a/docs/guide/providers.md
+++ b/docs/guide/providers.md
@@ -221,5 +221,5 @@ hypit doctor hypit.runtime.json
| `provider-hyperframes-local` | Local process: Chrome rendering with worker parallelism and output probe validation |
| `provider-hyperframes-aws-lambda` | Remote asynchronous job: Step Functions submission, polling and S3 streaming |
| `provider-image-opencv-local` | Local Python: bounded OpenCV/NumPy with locked Python environment |
-| `provider-media-aws-lambda` | Remote synchronous Lambda: the same eight capabilities as local media |
+| `provider-media-aws-lambda` | Remote synchronous Lambda: the same nine capabilities as local media |
| `provider-xiaomi-mimo` | Remote immediate API: exact MiMo TTS requests to persisted audio Artifacts |
diff --git a/docs/zh/guide/providers.md b/docs/zh/guide/providers.md
index beba44ab..43831dbc 100644
--- a/docs/zh/guide/providers.md
+++ b/docs/zh/guide/providers.md
@@ -213,5 +213,5 @@ hypit doctor hypit.runtime.json
| `provider-hyperframes-local` | 本地进程:Chrome 渲染,带 worker 并行与输出探测校验 |
| `provider-hyperframes-aws-lambda` | 远程可恢复任务:确定性 Step Functions 提交、轮询与 S3 流式落库 |
| `provider-image-opencv-local` | 本地 Python:有界的 OpenCV/NumPy,配合锁定的 Python 环境 |
-| `provider-media-aws-lambda` | 远程同步 Lambda:与本地媒体相同的八项能力 |
+| `provider-media-aws-lambda` | 远程同步 Lambda:与本地媒体相同的九项能力 |
| `provider-xiaomi-mimo` | 远程即时 API:把精确 MiMo TTS 请求落成持久化音频 Artifact |
diff --git a/packages/credential-store-os/src/store.ts b/packages/credential-store-os/src/store.ts
index 1e7edbda..dfedcb35 100644
--- a/packages/credential-store-os/src/store.ts
+++ b/packages/credential-store-os/src/store.ts
@@ -34,7 +34,7 @@ function macosReader(service: string): OsCredentialReader {
function macosWriter(service: string): OsCredentialWriter {
return async (_service, account, secret) => await new Promise((resolve, reject) => {
const child = spawn("/usr/bin/security", ["add-generic-password", "-U", "-s", service, "-a", account, "-w"], {
- shell: false, windowsHide: true, stdio: ["pipe", "ignore", "ignore"],
+ detached: true, shell: false, windowsHide: true, stdio: ["pipe", "ignore", "ignore"],
});
const timeout = setTimeout(() => child.kill(), 10_000);
child.on("error", (error) => { clearTimeout(timeout); reject(error); });
@@ -43,7 +43,7 @@ function macosWriter(service: string): OsCredentialWriter {
if (code === 0) resolve();
else reject(new Error(`OS credential write for ${account} failed`));
});
- child.stdin.end(`${secret}\n`);
+ child.stdin.end(`${secret}\n${secret}\n`);
});
}
diff --git a/packages/fonts-open/package.json b/packages/fonts-open/package.json
index b8d993f8..cc9ab456 100644
--- a/packages/fonts-open/package.json
+++ b/packages/fonts-open/package.json
@@ -123,6 +123,7 @@
},
"dependencies": {
"@hypit/media": "workspace:*",
+ "@hypit/package-loader-node": "workspace:*",
"@hypit/protocol": "workspace:*",
"@hypit/markup": "workspace:*"
}
diff --git a/packages/fonts-open/src/surface.ts b/packages/fonts-open/src/surface.ts
index bb8ad8c1..7f58b482 100644
--- a/packages/fonts-open/src/surface.ts
+++ b/packages/fonts-open/src/surface.ts
@@ -1,6 +1,5 @@
import { readFileSync } from "node:fs";
import { readFile } from "node:fs/promises";
-import { createRequire } from "node:module";
import { basename as fileName } from "node:path";
import {
@@ -10,6 +9,7 @@ import {
} from "@hypit/media";
import type { FontArtifactRef, FontStackRef } from "@hypit/media";
import type { StructuredElement, StructuredSurfaceHandler } from "@hypit/markup";
+import { resolveNodePackageResource } from "@hypit/package-loader-node";
import {
openFontFamilies,
@@ -21,11 +21,9 @@ import type {
OpenFontStyle,
} from "./catalog.js";
-const require = createRequire(import.meta.url);
-
function resolveFontPackageFile(packageName: string, path: string): string {
try {
- return require.resolve(`${packageName}/${path}`);
+ return resolveNodePackageResource(packageName, path, { from: import.meta.url });
} catch (error) {
const version = packageName === "@infolektuell/noto-color-emoji" ? "0.2.0" : "5.3.0";
throw new Error(
diff --git a/packages/package-loader-node/README.md b/packages/package-loader-node/README.md
index 1805e5e7..bd9227d9 100644
--- a/packages/package-loader-node/README.md
+++ b/packages/package-loader-node/README.md
@@ -9,3 +9,9 @@ not a package manager or registry.
Module dependencies declared by selected packages are loaded from ordinary installed dependencies.
Syntax, components and Runtime facets remain inert until a matching Host ABI consumes them.
+
+Physical lookup distinguishes package identity, ESM imports, package resources and npm executables.
+It does not use a CommonJS root export as evidence that a package is installed: CLI-only,
+import-only and resource-only packages are valid. The active Distribution owns `@hypit/*`;
+Distribution code may use upstream dependencies from the machine npm home, while project packages
+continue to resolve their own dependencies from the project.
diff --git a/packages/package-loader-node/src/distribution-resolution.ts b/packages/package-loader-node/src/distribution-resolution.ts
index 33533efd..b5043759 100644
--- a/packages/package-loader-node/src/distribution-resolution.ts
+++ b/packages/package-loader-node/src/distribution-resolution.ts
@@ -1,8 +1,14 @@
-import { createRequire, registerHooks } from "node:module";
-import { basename, join, resolve } from "node:path";
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { registerHooks } from "node:module";
+import { join, resolve } from "node:path";
+import { readFileSync } from "node:fs";
import { pathToFileURL } from "node:url";
+import {
+ distributionPackageDirectory,
+ setActiveDistributionPackageRoots,
+ setActiveExternalPackageRoots,
+} from "./location.js";
+
let installed: readonly string[] = [];
let externalInstalled: readonly string[] = [];
@@ -15,26 +21,17 @@ function packageAddress(specifier: string): { readonly name: string; readonly su
return { name: parts[0]!, subpath: parts.slice(1).join("/") };
}
-function packageDirectory(root: string, name: string): string | undefined {
- const conventional = join(root, "packages", basename(name));
- if (existsSync(join(conventional, "package.json"))) return conventional;
- const services = join(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);
- const manifestPath = join(candidate, "package.json");
- if (!existsSync(manifestPath)) continue;
- const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as { readonly name?: string };
- if (manifest.name === name) return candidate;
- }
- return undefined;
+function barePackageSpecifier(specifier: string): boolean {
+ return !specifier.startsWith(".")
+ && !specifier.startsWith("/")
+ && !specifier.startsWith("#")
+ && !specifier.includes(":");
}
function distributionPackageEntry(root: string, specifier: string): string | undefined {
const address = packageAddress(specifier);
if (address === undefined) return undefined;
- const packageRoot = packageDirectory(root, address.name);
+ const packageRoot = distributionPackageDirectory(root, address.name);
if (packageRoot === undefined) return undefined;
const manifestPath = join(packageRoot, "package.json");
const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as {
@@ -58,7 +55,7 @@ export function installDistributionPackageResolution(roots: readonly string[]):
if (next.every((root, index) => root === installed[index]) && next.length === installed.length) return;
if (installed.length > 0) throw new Error("Distribution package roots cannot change inside one Host process");
installed = next;
- const resolvers = installed.map((root) => createRequire(join(root, "__hypit_distribution__.cjs")));
+ setActiveDistributionPackageRoots(installed);
const rootUrls = installed.map((root) => pathToFileURL(`${root}/`).href);
registerHooks({
resolve(specifier, context, nextResolve) {
@@ -75,14 +72,9 @@ export function installDistributionPackageResolution(roots: readonly string[]):
} catch {
// Try the explicit Distribution resolvers below.
}
- for (const resolver of resolvers) {
- try {
- return { url: pathToFileURL(resolver.resolve(specifier)).href, shortCircuit: true };
- } catch {
- const entry = distributionPackageEntry(installed[resolvers.indexOf(resolver)]!, specifier);
- if (entry !== undefined) return { url: pathToFileURL(entry).href, shortCircuit: true };
- // Try the next explicit Distribution root.
- }
+ for (const root of installed) {
+ const entry = distributionPackageEntry(root, specifier);
+ if (entry !== undefined) return { url: pathToFileURL(entry).href, shortCircuit: true };
}
throw new Error(`Active Hypit Distribution does not provide ${specifier}`);
}
@@ -104,16 +96,19 @@ export function installExternalPackageResolution(roots: readonly string[]): void
throw new Error("External package roots cannot change inside one Host process");
}
externalInstalled = next;
- const resolvers = externalInstalled.map((root) => createRequire(join(root, "__hypit_external__.cjs")));
+ setActiveExternalPackageRoots(externalInstalled);
+ const parentUrls = externalInstalled.map((root) => pathToFileURL(join(root, "__hypit_external__.mjs")).href);
registerHooks({
resolve(specifier, context, nextResolve) {
- if (specifier.startsWith("@hypit/")) return nextResolve(specifier, context);
+ if (specifier.startsWith("@hypit/") || !barePackageSpecifier(specifier)) {
+ return nextResolve(specifier, context);
+ }
try {
return nextResolve(specifier, context);
} catch (original) {
- for (const resolver of resolvers) {
+ for (const parentURL of parentUrls) {
try {
- return { url: pathToFileURL(resolver.resolve(specifier)).href, shortCircuit: true };
+ return nextResolve(specifier, { ...context, parentURL });
} catch {
// Try the next machine package root before preserving Node's error.
}
diff --git a/packages/package-loader-node/src/index.ts b/packages/package-loader-node/src/index.ts
index abaf5223..44274305 100644
--- a/packages/package-loader-node/src/index.ts
+++ b/packages/package-loader-node/src/index.ts
@@ -11,4 +11,13 @@ export {
installDistributionPackageResolution,
installExternalPackageResolution,
} from "./distribution-resolution.js";
+export {
+ locateNodePackage,
+ resolveNodePackageExecutable,
+ resolveNodePackageResource,
+} from "./location.js";
+export type {
+ LocatedNodePackage,
+ LocateNodePackageOptions,
+} from "./location.js";
export type * from "./types.js";
diff --git a/packages/package-loader-node/src/loader.ts b/packages/package-loader-node/src/loader.ts
index 80b3adb4..c188f4a5 100644
--- a/packages/package-loader-node/src/loader.ts
+++ b/packages/package-loader-node/src/loader.ts
@@ -1,6 +1,5 @@
-import { readFile, readdir, realpath, stat } from "node:fs/promises";
-import { createRequire } from "node:module";
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+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";
@@ -12,6 +11,7 @@ import type {
NodePackageContribution,
NodePackageSelectionRequest,
} from "./types.js";
+import { externalPackageRoots, locateNodePackage } from "./location.js";
type PackageJson = {
readonly name: string;
@@ -56,59 +56,21 @@ async function packageJson(root: string): Promise<PackageJson> {
return parsePackageJson(JSON.parse(await readFile(path, "utf8")), path);
}
-function missingFile(error: unknown): boolean {
- return error instanceof Error && "code" in error && error.code === "ENOENT";
-}
-
-async function packageRoot(entry: string, expectedName: string): Promise<ResolvedPackage> {
- let cursor = dirname(await realpath(entry));
- while (true) {
- try {
- const json = await packageJson(cursor);
- if (json.name === expectedName) return { root: cursor, json };
- } catch (error) {
- if (!missingFile(error)) throw error;
- }
- const parent = dirname(cursor);
- if (parent === cursor) throw new Error(`resolved entry for ${expectedName} is outside its package`);
- cursor = parent;
- }
-}
-
async function resolvePackage(specifier: string, roots: readonly string[]): Promise<ResolvedPackage> {
let failure: unknown;
for (const from of roots) {
- const resolver = createRequire(join(resolve(from), "__hypit_package_loader__.cjs"));
- let entry: string;
try {
- entry = resolver.resolve(specifier);
- } catch (entryError) {
- try {
- entry = resolver.resolve(`${specifier}/package.json`);
- } catch {
- const root = resolve(from);
- const local = join(root, "packages", basename(specifier));
- const candidates = [local];
- try {
- for (const service of await readdir(join(root, "services"), { withFileTypes: true })) {
- if (service.isDirectory()) candidates.push(join(root, "services", service.name));
- }
- } catch (servicesError) {
- if (!missingFile(servicesError)) throw servicesError;
- }
- for (const candidate of candidates) {
- try {
- const json = await packageJson(candidate);
- if (json.name === specifier) return { root: candidate, json };
- } catch (localError) {
- if (!missingFile(localError)) throw localError;
- }
- }
- failure = entryError;
- continue;
- }
+ 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;
}
- return await packageRoot(entry, specifier);
}
throw new Error(`cannot resolve installed package ${specifier} from ${roots.join(", ")}: ${failure instanceof Error ? failure.message : String(failure)}`);
}
@@ -153,16 +115,21 @@ function within(root: string, candidate: string): boolean {
async function assertExternalDependencies(
item: ResolvedPackage,
distributionRoots: readonly string[],
+ externalRoots: readonly string[],
): Promise<void> {
- const resolver = createRequire(join(item.root, "__hypit_package_dependencies__.cjs"));
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 = await packageRoot(resolver.resolve(name), name);
+ 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.json.version !== required) {
- throw new Error(`installed version is ${resolved.json.version ?? "unknown"}`);
+ && resolved.manifest.version !== required) {
+ throw new Error(`installed version is ${resolved.manifest.version ?? "unknown"}`);
}
} catch (error) {
const repair = distributionOwned
@@ -258,9 +225,12 @@ export async function loadNodePackageSelection(
for (const address of normalized.logical ?? []) selected.add(physicalPackageName(address.name));
if (selected.size === 0) return [];
- const projectRoots = [root];
- const distributionRoots = (options.fallbackRoots ?? [])
- .filter((candidate) => resolve(candidate) !== resolve(root));
+ 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 };
@@ -286,7 +256,7 @@ export async function loadNodePackageSelection(
for (const item of await Promise.all(roots.map(async (physical) => ({
physical,
contribution: await (async () => {
- await assertExternalDependencies(physical, distributionRoots);
+ await assertExternalDependencies(physical, distributionRoots, externalRoots);
return await importContribution(physical);
})(),
})))) add(item);
@@ -300,7 +270,7 @@ export async function loadNodePackageSelection(
providerPackage,
resolutionRoots(providerPackage, [requirement.from, root], distributionRoots),
);
- await assertExternalDependencies(physical, 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}`);
diff --git a/packages/package-loader-node/src/location.ts b/packages/package-loader-node/src/location.ts
new file mode 100644
index 00000000..790ac486
--- /dev/null
+++ b/packages/package-loader-node/src/location.ts
@@ -0,0 +1,216 @@
+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 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 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 {
+ root: realpathSync(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 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`);
+}
diff --git a/packages/package-loader-node/src/types.ts b/packages/package-loader-node/src/types.ts
index 45a4bddc..4d0449af 100644
--- a/packages/package-loader-node/src/types.ts
+++ b/packages/package-loader-node/src/types.ts
@@ -46,4 +46,9 @@ export type NodePackageLoadOptions = {
* 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[];
};
diff --git a/packages/package-loader-node/test/loader.test.ts b/packages/package-loader-node/test/loader.test.ts
index 854a4848..73b020b2 100644
--- a/packages/package-loader-node/test/loader.test.ts
+++ b/packages/package-loader-node/test/loader.test.ts
@@ -83,6 +83,36 @@ test("Distribution requirements follow internal packages and return only exact u
}
});
+test("a Distribution package accepts an exact CLI-only dependency from the machine npm home", async () => {
+ const project = await mkdtemp(join(tmpdir(), "hypit-cli-only-project-"));
+ const distribution = await mkdtemp(join(tmpdir(), "hypit-cli-only-distribution-"));
+ const machine = await mkdtemp(join(tmpdir(), "hypit-cli-only-machine-"));
+ try {
+ await projectPackage(distribution, "@hypit/provider-example", `{
+ format: "hypit.node-package@1",
+ hostFacets: [{ abi: "example.provider@1", offers: ["example"] }]
+ }`, { "cli-only": "1.2.3" });
+ const cli = join(machine, "node_modules", "cli-only");
+ await mkdir(join(cli, "bin"), { recursive: true });
+ await writeFile(join(cli, "package.json"), JSON.stringify({
+ name: "cli-only",
+ version: "1.2.3",
+ type: "module",
+ bin: { "cli-only": "./bin/cli.mjs" },
+ }), "utf8");
+ await writeFile(join(cli, "bin", "cli.mjs"), "export {};\n", "utf8");
+ const loaded = await loadNodePackageSelection(["@hypit/provider-example"], project, {
+ fallbackRoots: [distribution],
+ externalRoots: [machine],
+ });
+ assert.deepEqual(loaded.map((item) => item.specifier), ["@hypit/provider-example"]);
+ } finally {
+ await rm(project, { recursive: true, force: true });
+ await rm(distribution, { recursive: true, force: true });
+ await rm(machine, { recursive: true, force: true });
+ }
+});
+
test("resolves a logical request to its conventional installed package", async () => {
const root = await mkdtemp(join(tmpdir(), "hypit-package-selection-"));
try {
diff --git a/packages/package-loader-node/test/location.test.ts b/packages/package-loader-node/test/location.test.ts
new file mode 100644
index 00000000..8a00038e
--- /dev/null
+++ b/packages/package-loader-node/test/location.test.ts
@@ -0,0 +1,81 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+import {
+ installExternalPackageResolution,
+ locateNodePackage,
+ resolveNodePackageExecutable,
+ resolveNodePackageResource,
+} from "@hypit/package-loader-node";
+
+async function machinePackage(
+ machine: string,
+ name: string,
+ manifest: Readonly<Record<string, unknown>>,
+ files: Readonly<Record<string, string>>,
+): Promise<string> {
+ const root = join(machine, "node_modules", ...name.split("/"));
+ await mkdir(root, { recursive: true });
+ await writeFile(join(root, "package.json"), JSON.stringify({ name, ...manifest }), "utf8");
+ for (const [path, contents] of Object.entries(files)) {
+ await mkdir(join(root, path, ".."), { recursive: true });
+ await writeFile(join(root, path), contents, "utf8");
+ }
+ return root;
+}
+
+test("one physical locator distinguishes CLI packages, resources and project ownership", async () => {
+ const distribution = await mkdtemp(join(tmpdir(), "hypit-locator-distribution-"));
+ const project = await mkdtemp(join(tmpdir(), "hypit-locator-project-"));
+ const machine = await mkdtemp(join(tmpdir(), "hypit-locator-machine-"));
+ try {
+ const cli = await machinePackage(machine, "cli-only", {
+ version: "1.2.3",
+ type: "module",
+ bin: { tool: "./bin/tool.mjs" },
+ }, { "bin/tool.mjs": "export {};\n" });
+ const resource = await machinePackage(machine, "resource-only", {
+ version: "2.3.4",
+ }, { "files/value.txt": "value\n" });
+ const fromDistribution = join(distribution, "packages", "provider", "activation.mjs");
+ const options = {
+ from: fromDistribution,
+ distributionRoots: [distribution],
+ externalRoots: [machine],
+ } as const;
+
+ const canonicalCli = await realpath(cli);
+ const canonicalResource = await realpath(resource);
+ assert.equal(locateNodePackage("cli-only", options).root, canonicalCli);
+ assert.equal(resolveNodePackageExecutable("cli-only", "tool", options), join(canonicalCli, "bin", "tool.mjs"));
+ assert.equal(resolveNodePackageResource("resource-only", "files/value.txt", options), join(canonicalResource, "files", "value.txt"));
+ assert.throws(() => locateNodePackage("resource-only", {
+ ...options,
+ from: join(project, "package.mjs"),
+ }), /cannot locate installed package/u);
+ } finally {
+ await rm(distribution, { recursive: true, force: true });
+ await rm(project, { recursive: true, force: true });
+ await rm(machine, { recursive: true, force: true });
+ }
+});
+
+test("machine npm fallback preserves ESM import conditions", async () => {
+ const machine = await mkdtemp(join(tmpdir(), "hypit-esm-machine-"));
+ try {
+ await machinePackage(machine, "import-only", {
+ version: "1.0.0",
+ type: "module",
+ exports: { ".": { import: "./index.mjs" } },
+ }, { "index.mjs": "export const value = 42;\n" });
+ installExternalPackageResolution([machine]);
+ const specifier = "import-only";
+ const imported = await import(specifier) as { readonly value?: unknown };
+ assert.equal(imported.value, 42);
+ } finally {
+ await rm(machine, { recursive: true, force: true });
+ }
+});
diff --git a/packages/provider-hyperframes-aws-lambda/test/live-canary.ts b/packages/provider-hyperframes-aws-lambda/test/live-canary.ts
index 7957f3c0..5276d788 100644
--- a/packages/provider-hyperframes-aws-lambda/test/live-canary.ts
+++ b/packages/provider-hyperframes-aws-lambda/test/live-canary.ts
@@ -64,11 +64,11 @@ assert(Number.isSafeInteger(memorySizeMb) && memorySizeMb >= 2_048, "invalid Hyp
function documentFixture(canaryId: string): HyperframesDocument {
const frameRate = { numerator: 24, denominator: 1 } as const;
const frameCount = 24;
- const programSpace = sealProgramSpace({
+ const programSpace = sealProgramSpace({ id: "test-space", narrativeId: "test-narrative",
durationSec: 1,
frameRate,
});
- const track = sealVisualTrack({
+ const track = sealVisualTrack({ programSpaceId: "test-space",
visualIr: "hypit.visual-ir@1",
id: `hyperframes-aws-canary-${canaryId}`,
presents: [{
diff --git a/packages/provider-hyperframes-local/package.json b/packages/provider-hyperframes-local/package.json
index 3a9cf5a8..24806f9b 100644
--- a/packages/provider-hyperframes-local/package.json
+++ b/packages/provider-hyperframes-local/package.json
@@ -15,6 +15,7 @@
"@hypit/hyperframes": "workspace:*",
"@hypit/media": "workspace:*",
"@hypit/media-execution": "workspace:*",
+ "@hypit/package-loader-node": "workspace:*",
"@hypit/protocol": "workspace:*",
"@hypit/render-hyperframes": "workspace:*",
"@hypit/runtime": "workspace:*",
diff --git a/packages/provider-hyperframes-local/src/provider.ts b/packages/provider-hyperframes-local/src/provider.ts
index 5c1662e3..8e7bcb40 100644
--- a/packages/provider-hyperframes-local/src/provider.ts
+++ b/packages/provider-hyperframes-local/src/provider.ts
@@ -1,9 +1,8 @@
import { spawn } from "node:child_process";
import { createReadStream } from "node:fs";
-import { createRequire } from "node:module";
import { mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
+import { join } from "node:path";
import { mediaTypes, sealRenderedVisual } from "@hypit/media";
import type { RenderedVisual } from "@hypit/media";
import { verifyCompositableSurfaceBytes } from "@hypit/media-execution";
@@ -13,6 +12,7 @@ import type { HyperframesDocument } from "@hypit/hyperframes";
import { stageHyperframesProject } from "@hypit/hyperframes/project";
import { renderHyperframesCapabilities } from "@hypit/render-hyperframes";
import { canonicalize } from "@hypit/protocol";
+import { resolveNodePackageExecutable } from "@hypit/package-loader-node";
import { isStreamingArtifactStore } from "@hypit/runtime";
import type { BlobRef, CanonicalValue } from "@hypit/protocol";
import { defineEndpointPackage } from "@hypit/endpoint-kit";
@@ -71,8 +71,7 @@ function positiveInteger(value: number, subject: string): number {
}
export function defaultHyperframesCliPath(): string {
- const require = createRequire(import.meta.url);
- return join(dirname(require.resolve("hyperframes/package.json")), "bin", "hyperframes.mjs");
+ return resolveNodePackageExecutable("hyperframes", "hyperframes", { from: import.meta.url });
}
function processEnvironment(): NodeJS.ProcessEnv {
diff --git a/packages/provider-hyperframes-local/test/provider.test.ts b/packages/provider-hyperframes-local/test/provider.test.ts
index de810eff..1b977c21 100644
--- a/packages/provider-hyperframes-local/test/provider.test.ts
+++ b/packages/provider-hyperframes-local/test/provider.test.ts
@@ -20,11 +20,11 @@ const liveEnabled = process.env.HYPIT_BROWSER_TESTS === "1";
const hasFfprobe = spawnSync("ffprobe", ["-version"], { stdio: "ignore", windowsHide: true }).status === 0;
function documentFixture(surface?: CompositableSurfaceRef) {
- const programSpace = sealProgramSpace({
+ const programSpace = sealProgramSpace({ id: "test-space", narrativeId: "test-narrative",
durationSec: 1,
frameRate: { numerator: 12, denominator: 1 },
});
- const track = sealVisualTrack({
+ const track = sealVisualTrack({ programSpaceId: "test-space",
visualIr: "hypit.visual-ir@1",
id: "provider-fixture",
presents: [{
diff --git a/packages/provider-image-opencv-local/package.json b/packages/provider-image-opencv-local/package.json
index 03b44eb4..305e88ec 100644
--- a/packages/provider-image-opencv-local/package.json
+++ b/packages/provider-image-opencv-local/package.json
@@ -16,6 +16,7 @@
"@hypit/protocol": "workspace:*",
"@hypit/raster": "workspace:*",
"@hypit/image-opencv-runtime": "workspace:*",
+ "@hypit/package-loader-node": "workspace:*",
"@hypit/runtime-kit": "workspace:*",
"@hypit/runtime-host-node": "workspace:*"
},
diff --git a/packages/provider-image-opencv-local/src/deployment.ts b/packages/provider-image-opencv-local/src/deployment.ts
index 0c9e904e..3ef7e687 100644
--- a/packages/provider-image-opencv-local/src/deployment.ts
+++ b/packages/provider-image-opencv-local/src/deployment.ts
@@ -1,7 +1,7 @@
import { existsSync } from "node:fs";
-import { createRequire } from "node:module";
import { join } from "node:path";
+import { resolveNodePackageResource } from "@hypit/package-loader-node";
import { runtimeConfigObject, runtimeConfigString } from "@hypit/runtime-kit";
import type { RuntimeAdapterFactoryContext, ManagedProgramCommand } from "@hypit/runtime-kit";
import {
@@ -13,9 +13,8 @@ import {
* The locked Python project is its own package asset. Repository workspaces and
* installed npm distributions therefore resolve the same immutable input.
*/
-const require = createRequire(import.meta.url);
export const localOpenCvManagedProject = join(
- require.resolve("@hypit/image-opencv-runtime/pyproject.toml"),
+ resolveNodePackageResource("@hypit/image-opencv-runtime", "pyproject.toml", { from: import.meta.url }),
"..",
);
diff --git a/packages/provider-whisperx-local/package.json b/packages/provider-whisperx-local/package.json
index 0edf9a55..b8ef3064 100644
--- a/packages/provider-whisperx-local/package.json
+++ b/packages/provider-whisperx-local/package.json
@@ -12,6 +12,7 @@
},
"dependencies": {
"@hypit/endpoint-kit": "workspace:*",
+ "@hypit/package-loader-node": "workspace:*",
"@hypit/protocol": "workspace:*",
"@hypit/runtime-host-node": "workspace:*",
"@hypit/runtime-kit": "workspace:*",
diff --git a/packages/provider-whisperx-local/src/program.ts b/packages/provider-whisperx-local/src/program.ts
index aa414ffc..1f9342a8 100644
--- a/packages/provider-whisperx-local/src/program.ts
+++ b/packages/provider-whisperx-local/src/program.ts
@@ -1,8 +1,8 @@
import { execFile } from "node:child_process";
import { existsSync } from "node:fs";
-import { createRequire } from "node:module";
import { join } from "node:path";
+import { resolveNodePackageResource } from "@hypit/package-loader-node";
import { runtimeConfigObject, runtimeConfigString } from "@hypit/runtime-kit";
import type {
ManagedProgram,
@@ -22,9 +22,8 @@ import { pythonEnvironmentCommand } from "@hypit/runtime-host-node";
* program home, while this read-only project remains replaceable Distribution
* input. A custom service command transfers process ownership to that deployment.
*/
-const require = createRequire(import.meta.url);
export const localWhisperXManagedProject = join(
- require.resolve("@hypit/whisperx-service-runtime/pyproject.toml"),
+ resolveNodePackageResource("@hypit/whisperx-service-runtime", "pyproject.toml", { from: import.meta.url }),
"..",
);