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.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
refactor: centralize machine package resolution
kashorinec075a86d82f
diff --git a/docs/guide/providers.md b/docs/guide/providers.mdindex 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.mdindex 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.tsindex 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.jsonindex 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.tsindex 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.mdindex 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.tsindex 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 sureturn { 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[]): voidthrow 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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 Hypfunction 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.jsonindex 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.tsindex 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.tsindex 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.jsonindex 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.tsindex 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.jsonindex 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.tsindex 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 }),"..",);