@hydranium/cli 1.0.0-next.42 → 1.0.0-next.420

package/src/commands/harness-args.ts

@@ -31,11 +31,12 @@
  * parser rejects is an invocation that fails for no visible reason.
  */
 
-import type { LogThreshold } from '@hydranium/protocol';
-import { statSync } from 'node:fs';
+import { describeError, type LogThreshold } from '@hydranium/protocol';
+import { readFileSync, statSync } from 'node:fs';
+import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { parseLogLevelOption } from '../log-level.js';
+import { type LogOptions, parseLogLevelOption } from '../log-level.js';
 
 /**
  * How a parser reports a usage problem. It never returns, so a parser can treat
@@ -56,9 +57,18 @@ export function exitWithUsage(message: string): never {
    process.exit(2);
 }
 
-/** The value flag {@link parseHarnessArgs} consumes itself, before any the subcommand declares. */
+/** Overrides the services module configured by the project. */
 export const SERVICES_FLAG = '--services';
 
+/**
+ * Registers a loader in the driver child that imports the head. The child is a
+ * fresh `node`, so a loader registered on the CLI's own process never reaches it.
+ */
+export const IMPORT_FLAG = '--import';
+
+/** The value flags {@link parseHarnessArgs} consumes itself, before any the subcommand declares. */
+export const HARNESS_VALUE_FLAGS = [SERVICES_FLAG, IMPORT_FLAG] as const;
+
 /**
  * The one spelling of the log threshold, shared by both subcommand families.
  *
@@ -68,33 +78,68 @@ export const SERVICES_FLAG = '--services';
  * on which command a caller happened to reach for.
  */
 export const LOG_LEVEL_FLAG = '--log-level';
+export const LOG_FILE_FLAG = '--log-file';
+export const LOG_FILE_LEVEL_FLAG = '--log-file-level';
+
+/** The log flags every subcommand takes, read by {@link logOptions}. */
+export const LOG_VALUE_FLAGS = [LOG_LEVEL_FLAG, LOG_FILE_FLAG, LOG_FILE_LEVEL_FLAG] as const;
 
 /** The value flags {@link parseServerSpawnOptions} consumes itself. */
-export const SERVER_SPAWN_VALUE_FLAGS: readonly string[] = ['--server', '--cwd', LOG_LEVEL_FLAG];
+export const SERVER_SPAWN_VALUE_FLAGS: readonly string[] = ['--server', '--cwd', ...LOG_VALUE_FLAGS];
 
 /**
- * The `--help` line every subcommand describes {@link LOG_LEVEL_FLAG} with.
+ * The `--help` lines every subcommand describes {@link LOG_VALUE_FLAGS} with.
  *
  * Shared text, per-command padding: `command-args.test.ts` compares the flags a
  * help block DESCRIBES against the flags the parser accepts, and it recognises a
- * description by the two-space indent — so the line has to be a real option entry
+ * description by the two-space indent — so each line has to be a real option entry
  * in each block, and the column each block aligns its descriptions at is the
- * block's own.
+ * block's own. A flag too wide for that column takes its description on the
+ * next line, at the column.
  */
-export function logLevelHelpLine(padTo: number): string {
-   return `  ${`${LOG_LEVEL_FLAG} <lvl>`.padEnd(padTo)}Log threshold for the head this boots (off|error|warn|info|debug|trace).`;
+export function logHelpLines(padTo: number, head = 'the head this boots'): string[] {
+   return [
+      helpLine(`${LOG_LEVEL_FLAG} <lvl>`, `Log threshold for ${head} (off|error|warn|info|debug|trace).`, padTo),
+      helpLine(
+         `${LOG_FILE_FLAG} <file>`,
+         `Also write ${head}'s log to <file>; {workspace} expands to the workspace, {pid} to the process id.`,
+         padTo
+      ),
+      helpLine(`${LOG_FILE_LEVEL_FLAG} <lvl>`, `Threshold for that file, which the log-level setting does not change.`, padTo)
+   ].flat();
+}
+
+/** The `--help` lines every `--services` subcommand describes {@link IMPORT_FLAG} with, aligned as {@link logHelpLines}. */
+export function importHelpLines(padTo: number): string[] {
+   return helpLine(`${IMPORT_FLAG} <specifier>`, 'Loader to register before importing <module>, e.g. tsx (repeatable).', padTo);
+}
+
+function helpLine(flag: string, text: string, padTo: number): string[] {
+   return flag.length < padTo - 1 ? [`  ${flag.padEnd(padTo)}${text}`] : [`  ${flag}`, `${' '.repeat(padTo + 2)}${text}`];
 }
 
 /**
- * Narrow a raw {@link LOG_LEVEL_FLAG} value that {@link parseHarnessArgs}
- * collected, leaving an absent flag absent.
+ * Narrow the raw {@link LOG_VALUE_FLAGS} values a parser collected, leaving
+ * absent flags absent.
+ *
+ * `--log-file` resolves against the caller's directory: the child may run
+ * elsewhere (`--cwd`), and a relative path would land the log there.
  *
  * Throws rather than reaching `onError`, matching {@link parseServerSpawnOptions}:
  * the level vocabulary belongs to the protocol package, which reports it, and the
  * entry point's catch turns that into the same message-and-exit.
  */
-export function logLevelOption(value: string | undefined): LogThreshold | undefined {
-   return value === undefined ? undefined : parseLogLevelOption(value);
+export function logOptions(options: Readonly<Record<string, string | undefined>>): LogOptions {
+   const level = (flag: string): LogThreshold | undefined => {
+      const value = options[flag];
+      return value === undefined ? undefined : parseLogLevelOption(value, flag);
+   };
+   const logFile = options[LOG_FILE_FLAG];
+   return {
+      logLevel: level(LOG_LEVEL_FLAG),
+      logFile: logFile === undefined ? undefined : path.resolve(logFile),
+      logFileLevel: level(LOG_FILE_LEVEL_FLAG)
+   };
 }
 
 /**
@@ -134,6 +179,8 @@ export function printHelp(lines: readonly string[]): void {
 /** What {@link parseHarnessArgs} recovered from an argv. */
 export interface ParsedHarnessArgs {
    servicesModule: string;
+   /** The {@link IMPORT_FLAG} values in the order given, absent when there were none. */
+   imports?: string[];
    /**
     * An absolute directory path, resolved by {@link resolveWorkspaceArgument} and
     * checked to exist. `''` when the subcommand declared `requireWorkspace: false`.
@@ -162,13 +209,14 @@ export interface HarnessArgsConfig {
 }
 
 /**
- * Shared parser for the headless-harness subcommands. Consumes the required
- * `--services <module>` value flag and a single positional `<workspace>`, plus
- * the `valueFlags` (each takes a value) and `boolFlags` (presence-only, recorded
- * as `'true'`) the subcommand recognises. Unknown flags or a missing
- * `--services`/`<workspace>` are usage errors, and so is a `<workspace>` that
- * reaches no directory — see {@link resolveWorkspaceArgument} for why that cannot
- * be left to the run.
+ * Shared parser for the headless-harness subcommands. Consumes the
+ * `--services <module>` override, the repeatable `--import <specifier>` and a
+ * single positional `<workspace>`, plus the `valueFlags` (each takes a value)
+ * and `boolFlags` (presence-only, recorded as `'true'`) the subcommand
+ * recognises. Services default to the nearest package manifest. Unknown flags,
+ * missing services or a missing `<workspace>` are usage errors, and so is a
+ * `<workspace>` that reaches no directory — see
+ * {@link resolveWorkspaceArgument} for why that cannot be left to the run.
  */
 export function parseHarnessArgs(
    args: string[],
@@ -185,6 +233,7 @@ export function parseHarnessArgs(
    const options: Record<string, string | undefined> = {};
    const values: Record<string, string[]> = {};
    let servicesModule: string | undefined;
+   let imports: string[] | undefined;
    let workspace: string | undefined;
    for (let index = 0; index < args.length; index += 1) {
       const flag = args[index];
@@ -196,8 +245,10 @@ export function parseHarnessArgs(
          index += 1;
          return value;
       };
-      if (flag === '--services') {
+      if (flag === SERVICES_FLAG) {
          servicesModule = next();
+      } else if (flag === IMPORT_FLAG) {
+         (imports ??= []).push(next());
       } else if (boolSet.has(flag)) {
          options[flag] = 'true';
       } else if (repeatableSet.has(flag)) {
@@ -212,8 +263,15 @@ export function parseHarnessArgs(
          onError(`Unexpected argument: ${flag} (hydranium-cli ${commandName} --help)`);
       }
    }
+   servicesModule ??= configuredServicesModule(onError);
+   if (servicesModule === undefined) {
+      return onError(
+         `Missing required option: ${SERVICES_FLAG} (hydranium-cli ${commandName} --help). Pass --services or set hydranium.services in package.json.`
+      );
+   }
    return {
-      servicesModule: assertRequired(servicesModule, '--services', commandName, onError),
+      servicesModule,
+      imports,
       workspace: requireWorkspace
          ? resolveWorkspaceArgument(assertRequired(workspace, '<workspace>', commandName, onError), commandName, onError)
          : (workspace ?? ''),
@@ -222,6 +280,61 @@ export function parseHarnessArgs(
    };
 }
 
+/**
+ * Stop at the nearest manifest even when it has no setting: inheriting through
+ * a workspace member would silently select another package's composition.
+ * Read only after argv, so an explicit override needs no valid project config.
+ */
+function configuredServicesModule(onError: UsageError): string | undefined {
+   let directory = process.cwd();
+   for (;;) {
+      const manifestPath = path.join(directory, 'package.json');
+      if (statSync(manifestPath, { throwIfNoEntry: false }) !== undefined) {
+         let manifest: unknown;
+         try {
+            manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+         } catch (error: unknown) {
+            return onError(`Cannot read ${manifestPath}: ${describeError(error)}`);
+         }
+         if (typeof manifest !== 'object' || manifest === null || Array.isArray(manifest)) {
+            return onError(`${manifestPath} must contain a JSON object.`);
+         }
+         if (!('hydranium' in manifest)) {
+            return undefined;
+         }
+         const configuration = manifest.hydranium;
+         if (typeof configuration !== 'object' || configuration === null || Array.isArray(configuration)) {
+            return onError(`hydranium in ${manifestPath} must be an object.`);
+         }
+         if (!('services' in configuration)) {
+            return undefined;
+         }
+         const services = configuration.services;
+         if (typeof services !== 'string' || services.trim() === '') {
+            return onError(`hydranium.services in ${manifestPath} must be a non-empty file path.`);
+         }
+         const modulePath = path.resolve(directory, services);
+         let stats;
+         try {
+            stats = statSync(modulePath, { throwIfNoEntry: false });
+         } catch (error: unknown) {
+            return onError(`Cannot read hydranium.services in ${manifestPath}: ${describeError(error)}`);
+         }
+         if (stats === undefined || !stats.isFile()) {
+            return onError(
+               `hydranium.services in ${manifestPath} points to '${services}' (${modulePath}), which is not an existing file. Build the project or correct the setting.`
+            );
+         }
+         return modulePath;
+      }
+      const parent = path.dirname(directory);
+      if (parent === directory) {
+         return undefined;
+      }
+      directory = parent;
+   }
+}
+
 /**
  * Resolve the `<workspace>` positional to an absolute directory path, reporting
  * a usage error when it reaches anything else.
@@ -257,7 +370,7 @@ export function resolveWorkspaceArgument(workspace: string, commandName: string,
    try {
       stats = statSync(resolved, { throwIfNoEntry: false });
    } catch (err: unknown) {
-      const detail = err instanceof Error ? err.message : String(err);
+      const detail = describeError(err);
       onError(`<workspace> is not reachable: '${workspace}' resolved to ${resolved} (${detail}) ${help}`);
    }
    if (stats === undefined) {
@@ -276,7 +389,7 @@ function toWorkspacePath(workspace: string, commandName: string, onError: UsageE
    try {
       return fileURLToPath(workspace);
    } catch (err: unknown) {
-      const detail = err instanceof Error ? err.message : String(err);
+      const detail = describeError(err);
       onError(`<workspace> is not a usable file URI: '${workspace}' (${detail}) (hydranium-cli ${commandName} --help)`);
    }
 }
@@ -336,11 +449,10 @@ function kebabToCamel(name: string): string {
 }
 
 /** What {@link parseServerSpawnOptions} recovered from an argv. */
-export interface SpawnOptions {
+export interface SpawnOptions extends LogOptions {
    serverCommand: string;
    serverArgs: string[];
    cwd?: string;
-   logLevel?: LogThreshold;
    /** The tokens this parser did not claim, for the subcommand's own options. */
    extra: string[];
 }
@@ -363,10 +475,10 @@ function isRelativePathToken(token: string, isCommand: boolean): boolean {
 
 /**
  * Shared option parser for subcommands that spawn a data-server child. Consumes
- * `--server` / `--cwd` / `--log-level` and returns the surviving tokens as
+ * `--server` / `--cwd` / the {@link LOG_VALUE_FLAGS} and returns the surviving tokens as
  * `extra` for {@link parseFlagOptions} to finish.
  *
- * An unrecognised `--log-level` value throws rather than reaching `onError`: the
+ * An unrecognised log level value throws rather than reaching `onError`: the
  * level vocabulary belongs to the protocol package, which reports it, and the
  * entry point's catch turns that into the same message-and-exit.
  *
@@ -383,7 +495,7 @@ function isRelativePathToken(token: string, isCommand: boolean): boolean {
 export function parseServerSpawnOptions(args: string[], commandName: string, onError: UsageError = exitWithUsage): SpawnOptions {
    let serverSpec: string | undefined;
    let cwd: string | undefined;
-   let logLevel: LogThreshold | undefined;
+   const logFlags: Record<string, string> = {};
    const extra: string[] = [];
    for (let index = 0; index < args.length; index += 1) {
       const flag = args[index];
@@ -399,8 +511,8 @@ export function parseServerSpawnOptions(args: string[], commandName: string, onE
          serverSpec = claim();
       } else if (flag === '--cwd') {
          cwd = claim();
-      } else if (flag === LOG_LEVEL_FLAG) {
-         logLevel = parseLogLevelOption(claim());
+      } else if ((LOG_VALUE_FLAGS as readonly string[]).includes(flag)) {
+         logFlags[flag] = claim();
       } else {
          extra.push(flag);
       }
@@ -425,5 +537,23 @@ export function parseServerSpawnOptions(args: string[], commandName: string, onE
          );
       }
    }
-   return { serverCommand, serverArgs, cwd, logLevel, extra };
+   return { serverCommand, serverArgs, cwd, ...logOptions(logFlags), extra };
+}
+
+/**
+ * Resolve the `--content` argument to its textual form. The `@<path>`
+ * prefix reads from a file (parses as UTF-8); anything else is taken
+ * literally. The leading `@` can be escaped as `\@` for content that
+ * legitimately starts with `@`.
+ */
+export async function resolveContent(content: string, readFile?: (path: string) => Promise<string>): Promise<string> {
+   if (content.startsWith('@')) {
+      const file = content.slice(1);
+      const reader = readFile ?? ((target: string) => fs.readFile(target, 'utf8'));
+      return reader(file);
+   }
+   if (content.startsWith('\\@')) {
+      return content.slice(1);
+   }
+   return content;
 }

package/src/commands/headless-harness.ts

@@ -8,14 +8,14 @@
  ********************************************************************************/
 
 import type * as HydraniumCoreNode from '@hydranium/core/node';
-import type { LogThreshold } from '@hydranium/protocol';
 import { spawn } from 'node:child_process';
 import { statSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import * as path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { logLevelEnv } from '../log-level.js';
-import { SERVICES_FLAG } from './harness-args.js';
+import { driverHeapArgs, type HeapReading } from '../driver-heap.js';
+import { logEnv, type LogOptions } from '../log-level.js';
+import { IMPORT_FLAG, SERVICES_FLAG } from './harness-args.js';
 
 /** The flag every report-producing subcommand names its destination file with. */
 export const OUT_FILE_FLAG = '--out-file';
@@ -43,13 +43,15 @@ export interface HeadlessContext {
  * its `createServices` thunk AND the `@hydranium/core/node` harness, both
  * resolved from the HEAD's location rather than the CLI's.
  *
- * The module is an ESM file (typically a compiled `lib/*.js`) exporting a
- * ZERO-ARG `createServices(): { shared }`. `hydranium-cli` is language-agnostic
+ * The module is an ESM file exporting a ZERO-ARG `createServices(): { shared }`:
+ * a compiled `lib/*.js`, or the TypeScript source when the child was started
+ * with a loader through {@link IMPORT_FLAG}. `hydranium-cli` is language-agnostic
  * and cannot statically import a head's `create<Lang>Services`, so the dynamic
  * import is the seam that keeps the binary head-neutral. Resolving the harness
- * from the head's graph (via `createRequire` rooted at the head module) means the
- * CLI itself needs no `@hydranium/core` dependency — the head always has it — and
- * guarantees the harness runs against the SAME core copy as `createServices`.
+ * from the head's graph (via `createRequire` rooted at the head module) rather
+ * than from the CLI's guarantees it runs against the SAME core copy as
+ * `createServices`, which a second copy of the module would break even where
+ * both resolve.
  *
  * Throws a clear error when the path names no file, and when the export is
  * missing or not a function.
@@ -64,12 +66,17 @@ export async function loadHeadlessContext(servicesModule: string): Promise<Headl
    if (stats === undefined || !stats.isFile()) {
       throw new Error(
          `${SERVICES_FLAG} must name an existing ESM file; '${servicesModule}' resolved to ${modulePath}, ` +
-            `which is not one. Pass the head's COMPILED entry, e.g. \`${SERVICES_FLAG} ./lib/services.js\` — ` +
-            'not the TypeScript source and not a package name.'
+            "which is not one. Pass the path of the server package's built `lib/node/services.js` from where you run this — " +
+            'not a package name.'
       );
    }
    const moduleUrl = pathToFileURL(modulePath).href;
-   const imported = (await import(moduleUrl)) as Record<string, unknown>;
+   let imported: Record<string, unknown>;
+   try {
+      imported = (await import(moduleUrl)) as Record<string, unknown>;
+   } catch (err: unknown) {
+      throw withLoaderHint(err, modulePath);
+   }
    const createServices = imported.createServices;
    if (typeof createServices !== 'function') {
       throw new Error(
@@ -84,6 +91,32 @@ export async function loadHeadlessContext(servicesModule: string): Promise<Headl
    return { createServices: createServices as ServicesFactory, coreNode };
 }
 
+/** The codes Node fails a TypeScript entry with when no loader handled it, depending on its version. */
+const UNLOADED_TYPESCRIPT_CODES: ReadonlySet<string> = new Set([
+   'ERR_UNKNOWN_FILE_EXTENSION',
+   'ERR_MODULE_NOT_FOUND',
+   'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX'
+]);
+
+/**
+ * Append a loader hint to a TypeScript entry's import failure, unless the child
+ * was started with {@link IMPORT_FLAG}, where the hint would only repeat the
+ * caller's own command. Appended rather than substituted: a loader set through
+ * `NODE_OPTIONS` does not show in `execArgv`, and under it the failure can be a
+ * missing module that only Node's own message names.
+ */
+function withLoaderHint(err: unknown, modulePath: string): unknown {
+   if (!(err instanceof Error) || !/\.[cm]?ts$/.test(modulePath) || !('code' in err) || typeof err.code !== 'string') {
+      return err;
+   }
+   if (!UNLOADED_TYPESCRIPT_CODES.has(err.code) || process.execArgv.some(arg => arg.startsWith(IMPORT_FLAG))) {
+      return err;
+   }
+   return new Error(`${err.message}\nA TypeScript head needs a loader registered with \`${IMPORT_FLAG}\`, e.g. \`${IMPORT_FLAG} tsx\`.`, {
+      cause: err
+   });
+}
+
 /**
  * Child-side: deliver a finished report — to `outFile` when one was named, else
  * to stdout.
@@ -101,8 +134,9 @@ export function emitReport(report: string, outFile: string | undefined): void {
    }
    writeFileSync(outFile, report.endsWith('\n') ? report : `${report}\n`);
    // Progress on stderr, so a caller that also captures stdout gets a clean
-   // stream rather than a note where the report used to be.
-   console.error(`Wrote ${outFile}`);
+   // stream rather than a note where the report used to be. Not `console.error`,
+   // which a configured log file records as an error line.
+   process.stderr.write(`Wrote ${outFile}\n`);
 }
 
 /**
@@ -129,37 +163,64 @@ export function spawnNodeChild(execArgs: string[], env?: Record<string, string>)
 /** How a subcommand parent reaches its driver child; the seam `__spawnForTest` replaces. */
 export type SpawnDriverChild = (execArgs: string[], env?: Record<string, string>) => Promise<number>;
 
-/** What every `--services` subcommand carries for the child it spawns, on top of its own options. */
-export interface DriverSpawnOptions {
-   /**
-    * Log threshold for the head the driver boots. Absent leaves the child's
-    * inherited environment alone, so an ambient `HYDRANIUM_LOG_LEVEL` still wins
-    * where a caller set one.
-    */
-   readonly logLevel?: LogThreshold;
+/**
+ * What every `--services` subcommand carries for the child it spawns, on top of
+ * its own options. The log options apply to the head the driver boots; an
+ * absent one leaves the child's inherited environment alone, so an ambient
+ * variable still wins where a caller set one.
+ */
+export interface DriverSpawnOptions extends LogOptions {
+   /** Specifiers the driver child registers with Node's `--import`, in order, before it imports the head. */
+   readonly imports?: readonly string[];
    /** Test-only: capture the node argv and env instead of spawning the real child. */
    readonly __spawnForTest?: SpawnDriverChild;
+   /**
+    * Test-only: decide the heap ceiling from a stated cgroup reading rather
+    * than the machine's. Without it an argv assertion means one thing on a
+    * workstation and nothing at all under a memory limit, so a suite that
+    * asserts the ceiling is present passes vacuously in a container.
+    */
+   readonly __heapReadingForTest?: HeapReading;
 }
 
 /**
  * Parent-side: run a subcommand's driver child and propagate its exit code, so a
  * shell or CI step sees the gate.
  *
- * **The log threshold travels in the child's ENVIRONMENT, not its argv.** The
- * head's logger reads `HYDRANIUM_LOG_LEVEL` while `createServices` constructs it,
- * which is inside the driver's dynamic import — a flag the driver parsed would
- * arrive after the only moment it can be read. Setting it here rather than
- * exporting it also leaves the CLI's own output alone, unlike an ambient
- * `HYDRANIUM_LOG_LEVEL=…` the parent would carry too.
+ * **The log options travel in the child's ENVIRONMENT, not its argv.** The
+ * head's logger reads its `HYDRANIUM_LOG_*` variables while `createServices`
+ * constructs it, which is inside the driver's dynamic import — a flag the driver
+ * parsed would arrive after the only moment it can be read. Setting them here
+ * rather than exporting them also leaves the CLI's own output alone, unlike
+ * ambient variables the parent would carry too.
  *
  * A head that binds a logger of its own decides for itself whether the flag means
  * anything, which is the intended seam: the CLI is language-agnostic and cannot
  * reach past `createServices`.
+ *
+ * **The heap ceiling is prepended HERE rather than passed by each subcommand.**
+ * Every caller wants the same answer to the same question, and the answer is not
+ * a constant — see {@link driverHeapArgs}. A literal at the call site is a place
+ * the container case can be missed, and the caller that misses it takes the whole
+ * cgroup down with it rather than failing on its own.
  */
 export async function runDriverChild(execArgs: string[], options: DriverSpawnOptions): Promise<void> {
    const spawnChild = options.__spawnForTest ?? spawnNodeChild;
-   const code = await spawnChild(execArgs, options.logLevel === undefined ? undefined : logLevelEnv(options.logLevel));
+   const importArgs = (options.imports ?? []).map(specifier => `${IMPORT_FLAG}=${loaderSpecifier(specifier)}`);
+   const code = await spawnChild([...driverHeapArgs(options.__heapReadingForTest), ...importArgs, ...execArgs], logEnv(options));
    if (code) {
       process.exitCode = code;
    }
 }
+
+/**
+ * A path, absolute or `./`/`../` relative with either separator, becomes a file
+ * URL resolved against the caller's directory. Node reads `--import` as a URL or
+ * package specifier, so it would take a Windows `C:\…` for the URL scheme `c:`
+ * and a `.\…` for a package name. Any other specifier passes through as Node
+ * reads it.
+ */
+function loaderSpecifier(specifier: string): string {
+   const isPath = path.isAbsolute(specifier) || /^\.\.?[\\/]/.test(specifier);
+   return isPath ? pathToFileURL(path.resolve(specifier)).href : specifier;
+}