@withstudiocms/internal_helpers 0.1.0-beta.2 → 0.1.0-beta.4

package/dist/astro-integration/integrationLogger.js

@@ -23,7 +23,7 @@ async function logMessages(messages, options, logger) {
       {
         logger: logger.fork(label),
         logLevel,
-        verbose: logLevel === "info" ? options.verbose : true
+        verbose: logLevel === "info" || logLevel === "debug" ? options.verbose : true
       },
       message
     );

package/dist/cli-providers/core/formatter.d.ts

@@ -0,0 +1,23 @@
+import { styleText } from 'node:util';
+import type { TextFormatter } from '../definitions';
+type StyleTextFormatColor = Parameters<typeof styleText>[0];
+/**
+ * Options for formatting and styling debug information.
+ */
+export type FormatOptions = {
+    keyStyle: StyleTextFormatColor;
+    valueStyle: StyleTextFormatColor;
+};
+export type DebugStylerOptions = {
+    indent?: number;
+    style?: FormatOptions;
+};
+/**
+ * A utility class for formatting and styling debug information.
+ */
+export declare class Formatter implements TextFormatter {
+    #private;
+    constructor(obj: Record<string, string>, opts?: DebugStylerOptions);
+    format(styled?: boolean): string;
+}
+export {};

package/dist/cli-providers/core/formatter.js

@@ -0,0 +1,47 @@
+import { styleText } from "node:util";
+class Formatter {
+  #indent;
+  #obj;
+  #style;
+  constructor(obj, opts) {
+    this.#indent = opts?.indent ?? 2;
+    this.#obj = obj;
+    this.#style = opts?.style ?? {
+      keyStyle: "cyan",
+      valueStyle: "white"
+    };
+  }
+  get #getKeyPair() {
+    return Object.entries(this.#obj).map(([key, value]) => ({ key, value }));
+  }
+  #textProcessor(text, type, styled) {
+    const style = type === "key" ? this.#style.keyStyle : this.#style.valueStyle;
+    return styled ? styleText(style, text) : text;
+  }
+  #getTextProcessor(styled) {
+    return (text, type) => this.#textProcessor(text, type, styled);
+  }
+  format(styled) {
+    const pairs = this.#getKeyPair;
+    if (pairs.length === 0) return "";
+    const maxKeyLength = Math.max(...pairs.map((p) => p.key.length));
+    const lines = [];
+    const processText = this.#getTextProcessor(styled);
+    for (const { key, value } of pairs) {
+      const padding = " ".repeat(maxKeyLength - key.length + this.#indent);
+      const valueLines = value.split("\n");
+      const styledKey = processText(key, "key");
+      const styledValue = processText(valueLines[0], "value");
+      lines.push(`${styledKey}${padding}${styledValue}`);
+      for (let i = 1; i < valueLines.length; i++) {
+        const indent = " ".repeat(maxKeyLength + this.#indent);
+        const styledLine = processText(valueLines[i], "value");
+        lines.push(`${indent}${styledLine}`);
+      }
+    }
+    return lines.join("\n");
+  }
+}
+export {
+  Formatter
+};

package/dist/cli-providers/core/get-package-manger.d.ts

@@ -0,0 +1,13 @@
+import type { CommandExecutor, PackageManager, PackageManagerUserAgentProvider } from '../definitions.js';
+interface Options {
+    packageManagerUserAgentProvider: PackageManagerUserAgentProvider;
+    commandExecutor: CommandExecutor;
+}
+/**
+ * Determines the package manager based on the user agent string.
+ *
+ * @param options - The options object containing the user agent provider.
+ * @returns A promise that resolves to the appropriate PackageManager instance.
+ */
+export declare function getPackageManager({ packageManagerUserAgentProvider, commandExecutor, }: Options): Promise<PackageManager>;
+export {};

package/dist/cli-providers/core/get-package-manger.js

@@ -0,0 +1,37 @@
+async function getPackageManager({
+  packageManagerUserAgentProvider,
+  commandExecutor
+}) {
+  if (!packageManagerUserAgentProvider.userAgent) {
+    const { NoopPackageManager } = await import("../infra/noop-package-manager.js");
+    return new NoopPackageManager();
+  }
+  const specifier = packageManagerUserAgentProvider.userAgent.split(" ")[0];
+  const _name = specifier.substring(0, specifier.lastIndexOf("/"));
+  const name = _name === "npminstall" ? "cnpm" : _name;
+  switch (name) {
+    case "pnpm": {
+      const { PnpmPackageManager } = await import("../infra/pnpm-package-manager.js");
+      return new PnpmPackageManager({ commandExecutor });
+    }
+    case "npm": {
+      const { NpmPackageManager } = await import("../infra/npm-package-manager.js");
+      return new NpmPackageManager({ commandExecutor });
+    }
+    case "yarn": {
+      const { YarnPackageManager } = await import("../infra/yarn-package-manager.js");
+      return new YarnPackageManager({ commandExecutor });
+    }
+    case "bun": {
+      const { BunPackageManager } = await import("../infra/bun-package-manager.js");
+      return new BunPackageManager();
+    }
+    default: {
+      const { NoopPackageManager } = await import("../infra/noop-package-manager.js");
+      return new NoopPackageManager();
+    }
+  }
+}
+export {
+  getPackageManager
+};

package/dist/cli-providers/core/process-node-version-provider.d.ts

@@ -0,0 +1,7 @@
+import type { NodeVersionProvider } from '../definitions.js';
+/**
+ * Provides the Node.js version from the current process.
+ */
+export declare class ProcessNodeVersionProvider implements NodeVersionProvider {
+    readonly version: string;
+}

package/dist/cli-providers/core/process-node-version-provider.js

@@ -0,0 +1,6 @@
+class ProcessNodeVersionProvider {
+  version = process.version;
+}
+export {
+  ProcessNodeVersionProvider
+};

package/dist/cli-providers/core/process-package-manager-user-agent-provider.d.ts

@@ -0,0 +1,7 @@
+import type { PackageManagerUserAgentProvider } from '../definitions.js';
+/**
+ * Provides the package manager user agent from the current process environment.
+ */
+export declare class ProcessPackageManagerUserAgentProvider implements PackageManagerUserAgentProvider {
+    readonly userAgent: string | null;
+}

package/dist/cli-providers/core/process-package-manager-user-agent-provider.js

@@ -0,0 +1,7 @@
+class ProcessPackageManagerUserAgentProvider {
+  // https://docs.npmjs.com/cli/v8/using-npm/config#user-agent
+  userAgent = process.env.npm_config_user_agent ?? null;
+}
+export {
+  ProcessPackageManagerUserAgentProvider
+};

package/dist/cli-providers/core/system-info-provider.d.ts

@@ -0,0 +1,9 @@
+import type { SystemInfoProvider } from '../definitions.js';
+/**
+ * Provides system information based on the current process.
+ */
+export declare class ProcessSystemInfoProvider implements SystemInfoProvider {
+    #private;
+    readonly name: NodeJS.Platform;
+    readonly displayName: string;
+}

package/dist/cli-providers/core/system-info-provider.js

@@ -0,0 +1,24 @@
+class ProcessSystemInfoProvider {
+  #platformToOs = {
+    win32: "Windows",
+    darwin: "macOS",
+    linux: "Linux",
+    aix: "AIX",
+    freebsd: "FreeBSD",
+    openbsd: "OpenBSD",
+    sunos: "SunOS"
+  };
+  #archToArchName = {
+    x64: "x64",
+    arm64: "ARM64",
+    ia32: "x86",
+    arm: "ARM",
+    mips: "MIPS",
+    ppc: "PowerPC"
+  };
+  name = process.platform;
+  displayName = `${this.#platformToOs[this.name] ?? this.name} (${this.#archToArchName[process.arch] ?? process.arch})`;
+}
+export {
+  ProcessSystemInfoProvider
+};

package/dist/cli-providers/core/tinyexec.d.ts

@@ -0,0 +1,9 @@
+import type { CommandExecutor, CommandExecutorOptions } from '../definitions.js';
+/**
+ * Provides a command executor that uses the Tinyexec library to run shell commands.
+ */
+export declare class TinyexecCommandExecutor implements CommandExecutor {
+    execute(command: string, args?: Array<string>, options?: CommandExecutorOptions): Promise<{
+        stdout: string;
+    }>;
+}

package/dist/cli-providers/core/tinyexec.js

@@ -0,0 +1,38 @@
+import { NonZeroExitError, x } from "tinyexec";
+class TinyExecError extends Error {
+  stderr;
+  stdout;
+}
+class TinyexecCommandExecutor {
+  async execute(command, args, options) {
+    const proc = x(command, args, {
+      throwOnError: true,
+      nodeOptions: {
+        cwd: options?.cwd,
+        env: options?.env,
+        shell: options?.shell,
+        stdio: options?.stdio
+      }
+    });
+    if (options?.input) {
+      proc.process?.stdin?.end(options.input);
+    }
+    return await proc.then(
+      (o) => o,
+      (e) => {
+        if (e instanceof NonZeroExitError) {
+          const fullCommand = args?.length ? `${command} ${args.map((a) => a.includes(" ") ? `"${a}"` : a).join(" ")}` : command;
+          const message = `The command \`${fullCommand}\` exited with code ${e.exitCode}`;
+          const newError = new TinyExecError(message, e.cause ? { cause: e.cause } : void 0);
+          newError.stderr = e.output?.stderr;
+          newError.stdout = e.output?.stdout;
+          throw newError;
+        }
+        throw e;
+      }
+    );
+  }
+}
+export {
+  TinyexecCommandExecutor
+};

package/dist/cli-providers/definitions.d.ts

@@ -0,0 +1,58 @@
+import type { StdioOptions } from 'node:child_process';
+/**
+ * Defines interfaces for package managers, Node.js version, and system information providers.
+ */
+export interface PackageManager {
+    readonly name: string;
+    getPackageVersion: (name: string) => Promise<string | undefined>;
+}
+/**
+ * Provides the user agent string of the package manager.
+ */
+export interface PackageManagerUserAgentProvider {
+    readonly userAgent: string | null;
+}
+/**
+ * Provides the Node.js version.
+ */
+export interface NodeVersionProvider {
+    readonly version: string;
+}
+/**
+ * Provides system information.
+ */
+export interface SystemInfoProvider {
+    readonly name: NodeJS.Platform;
+    readonly displayName: string;
+}
+/**
+ * Represents debug information about the environment.
+ */
+export interface CommandExecutorOptions {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    shell?: boolean;
+    input?: string;
+    stdio?: StdioOptions;
+}
+/**
+ * Represents a command executor that can run shell commands.
+ */
+export interface CommandExecutor {
+    execute: (command: string, args?: Array<string>, options?: CommandExecutorOptions) => Promise<{
+        stdout: string;
+    }>;
+}
+/**
+ * Represents the structure of a bare NPM-like version output.
+ */
+export interface BareNpmLikeVersionOutput {
+    version: string;
+    dependencies: Record<string, BareNpmLikeVersionOutput>;
+}
+/**
+ * Represents a text formatter for styling output.
+ */
+export interface TextFormatter {
+    format: (styled?: boolean) => string;
+}

package/dist/cli-providers/index.d.ts

@@ -0,0 +1,6 @@
+export * from './core/formatter.js';
+export * from './core/get-package-manger.js';
+export * from './core/process-node-version-provider.js';
+export * from './core/process-package-manager-user-agent-provider.js';
+export * from './core/system-info-provider.js';
+export * from './core/tinyexec.js';

package/dist/cli-providers/index.js

@@ -0,0 +1,6 @@
+export * from "./core/formatter.js";
+export * from "./core/get-package-manger.js";
+export * from "./core/process-node-version-provider.js";
+export * from "./core/process-package-manager-user-agent-provider.js";
+export * from "./core/system-info-provider.js";
+export * from "./core/tinyexec.js";

package/dist/cli-providers/infra/bun-package-manager.d.ts

@@ -0,0 +1,8 @@
+import type { PackageManager } from '../definitions.js';
+/**
+ * Represents the Bun package manager.
+ */
+export declare class BunPackageManager implements PackageManager {
+    readonly name: string;
+    getPackageVersion(_name: string): Promise<string | undefined>;
+}

package/dist/cli-providers/infra/bun-package-manager.js

@@ -0,0 +1,9 @@
+class BunPackageManager {
+  name = "bun";
+  async getPackageVersion(_name) {
+    return void 0;
+  }
+}
+export {
+  BunPackageManager
+};

package/dist/cli-providers/infra/noop-package-manager.d.ts

@@ -0,0 +1,8 @@
+import type { PackageManager } from '../definitions.js';
+/**
+ * Represents a no-operation package manager for unknown cases.
+ */
+export declare class NoopPackageManager implements PackageManager {
+    readonly name: string;
+    getPackageVersion(_name: string): Promise<string | undefined>;
+}

package/dist/cli-providers/infra/noop-package-manager.js

@@ -0,0 +1,9 @@
+class NoopPackageManager {
+  name = "unknown";
+  async getPackageVersion(_name) {
+    return void 0;
+  }
+}
+export {
+  NoopPackageManager
+};

package/dist/cli-providers/infra/npm-package-manager.d.ts

@@ -0,0 +1,12 @@
+import type { CommandExecutor, PackageManager } from '../definitions.js';
+/**
+ * Represents the NPM package manager.
+ */
+export declare class NpmPackageManager implements PackageManager {
+    #private;
+    readonly name: string;
+    constructor({ commandExecutor }: {
+        commandExecutor: CommandExecutor;
+    });
+    getPackageVersion(name: string): Promise<string | undefined>;
+}

package/dist/cli-providers/infra/npm-package-manager.js

@@ -0,0 +1,36 @@
+class NpmPackageManager {
+  name = "npm";
+  #commandExecutor;
+  constructor({ commandExecutor }) {
+    this.#commandExecutor = commandExecutor;
+  }
+  async getPackageVersion(name) {
+    try {
+      const { stdout } = await this.#commandExecutor.execute(
+        "npm",
+        ["ls", name, "--json", "--depth=1"],
+        {
+          shell: true
+        }
+      );
+      const parsedNpmOutput = JSON.parse(stdout);
+      if (!parsedNpmOutput.dependencies) {
+        return void 0;
+      }
+      if (parsedNpmOutput.dependencies[name]) {
+        return `v${parsedNpmOutput.dependencies[name].version}`;
+      }
+      const studiocms = parsedNpmOutput.dependencies.studiocms;
+      if (studiocms?.dependencies?.[name]?.version) {
+        return `v${studiocms.dependencies[name].version}`;
+      }
+      const astro = parsedNpmOutput.dependencies.astro;
+      return astro?.dependencies?.[name]?.version ? `v${astro.dependencies[name].version}` : void 0;
+    } catch {
+      return void 0;
+    }
+  }
+}
+export {
+  NpmPackageManager
+};

package/dist/cli-providers/infra/pnpm-package-manager.d.ts

@@ -0,0 +1,12 @@
+import type { CommandExecutor, PackageManager } from '../definitions.js';
+/**
+ * Represents the PNPM package manager.
+ */
+export declare class PnpmPackageManager implements PackageManager {
+    #private;
+    readonly name: string;
+    constructor({ commandExecutor }: {
+        commandExecutor: CommandExecutor;
+    });
+    getPackageVersion(name: string): Promise<string | undefined>;
+}

package/dist/cli-providers/infra/pnpm-package-manager.js

@@ -0,0 +1,68 @@
+function formatPnpmVersionOutput(versionOutput) {
+  return versionOutput.startsWith("link:") ? "Local" : `v${versionOutput}`;
+}
+class PnpmPackageManager {
+  name = "pnpm";
+  #commandExecutor;
+  constructor({ commandExecutor }) {
+    this.#commandExecutor = commandExecutor;
+  }
+  #processPnpmWhyOutput(name, pnpmWhy) {
+    const parsedOutput = JSON.parse(pnpmWhy);
+    if (parsedOutput.length === 0) {
+      return void 0;
+    }
+    const deps = parsedOutput[0].dependencies;
+    if (!deps) {
+      return void 0;
+    }
+    const userProvidedDependency = deps[name];
+    if (userProvidedDependency) {
+      return formatPnpmVersionOutput(userProvidedDependency.version);
+    }
+    const studiocmsDependency = deps.studiocms?.dependencies?.[name];
+    if (studiocmsDependency) {
+      return formatPnpmVersionOutput(studiocmsDependency.version);
+    }
+    const astroDependency = deps.astro?.dependencies?.[name];
+    return astroDependency ? formatPnpmVersionOutput(astroDependency.version) : void 0;
+  }
+  #processPnpmLsOutput(name, pnpmLs) {
+    const parsedOutput = JSON.parse(pnpmLs);
+    if (parsedOutput.length === 0) {
+      return void 0;
+    }
+    const deps = parsedOutput[0].dependencies;
+    if (!deps) {
+      return void 0;
+    }
+    const userProvidedDependency = deps[name];
+    if (userProvidedDependency) {
+      return formatPnpmVersionOutput(userProvidedDependency.version);
+    }
+  }
+  async getPackageVersion(name) {
+    try {
+      const { stdout: pnpmLs } = await this.#commandExecutor.execute("pnpm", ["ls", "--json"], {
+        shell: true
+      });
+      const lsVersion = this.#processPnpmLsOutput(name, pnpmLs);
+      if (lsVersion) {
+        return lsVersion;
+      }
+      const { stdout: pnpmWhy } = await this.#commandExecutor.execute(
+        "pnpm",
+        ["why", name, "--json"],
+        {
+          shell: true
+        }
+      );
+      return this.#processPnpmWhyOutput(name, pnpmWhy);
+    } catch {
+      return void 0;
+    }
+  }
+}
+export {
+  PnpmPackageManager
+};

package/dist/cli-providers/infra/yarn-package-manager.d.ts

@@ -0,0 +1,12 @@
+import type { CommandExecutor, PackageManager } from '../definitions.js';
+/**
+ * Represents the Yarn package manager.
+ */
+export declare class YarnPackageManager implements PackageManager {
+    #private;
+    readonly name: string;
+    constructor({ commandExecutor }: {
+        commandExecutor: CommandExecutor;
+    });
+    getPackageVersion(name: string): Promise<string | undefined>;
+}

package/dist/cli-providers/infra/yarn-package-manager.js

@@ -0,0 +1,36 @@
+function getYarnOutputDepVersion(dependency, outputLine) {
+  const parsed = JSON.parse(outputLine);
+  for (const [key, value] of Object.entries(parsed.children)) {
+    if (key.startsWith(`${dependency}@`)) {
+      return `v${value.locator.split(":").pop()}`;
+    }
+  }
+}
+class YarnPackageManager {
+  name = "yarn";
+  #commandExecutor;
+  constructor({ commandExecutor }) {
+    this.#commandExecutor = commandExecutor;
+  }
+  async getPackageVersion(name) {
+    try {
+      const { stdout } = await this.#commandExecutor.execute("yarn", ["why", name, "--json"], {
+        shell: true
+      });
+      const hasUserDefinition = stdout.includes("workspace:.");
+      for (const line of stdout.split("\n")) {
+        if (hasUserDefinition && line.includes("workspace:."))
+          return getYarnOutputDepVersion(name, line);
+        if (hasUserDefinition && line.includes("studiocms@"))
+          return getYarnOutputDepVersion(name, line);
+        if (!hasUserDefinition && line.includes("astro@"))
+          return getYarnOutputDepVersion(name, line);
+      }
+    } catch {
+      return void 0;
+    }
+  }
+}
+export {
+  YarnPackageManager
+};

package/dist/debug-info-provider.d.ts

@@ -0,0 +1,50 @@
+import type { FormatOptions } from './cli-providers/core/formatter.js';
+/**
+ * Represents debug information about the Astro and StudioCMS environment.
+ */
+export type DebugInfo = {
+    Astro: string;
+    'Astro Adapter': string;
+    'Database Dialect': string;
+    'Node.js': string;
+    'Package Manager': string;
+    System: string;
+    StudioCMS: string;
+    'StudioCMS UI': string;
+    'StudioCMS Plugins': string;
+};
+/**
+ * Represents a list of installed plugins.
+ */
+type PluginList = {
+    identifier: string;
+    name: string;
+}[];
+/**
+ * Represents the context required to gather debug information.
+ */
+export interface DebugInfoContext {
+    adapterName: string;
+    databaseDialect: string;
+    installedPlugins: PluginList;
+}
+export declare class DebugInfoProvider {
+    #private;
+    constructor(ctx: DebugInfoContext);
+    /**
+     * Gathers debug information as an object.
+     *
+     * @returns A promise that resolves to the debug information object.
+     */
+    getDebugInfoObj(): Promise<DebugInfo>;
+    /**
+     * Gathers debug information as a formatted string.
+     *
+     * @returns A promise that resolves to the debug information string.
+     */
+    getDebugInfoString(indent?: number, { styled, styles: style }?: {
+        styled: boolean;
+        styles?: FormatOptions;
+    }): Promise<string>;
+}
+export {};

package/dist/debug-info-provider.js

@@ -0,0 +1,79 @@
+const dbDialectLabels = {
+  libsql: "LibSQL",
+  mysql: "MySQL",
+  postgres: "PostgreSQL",
+  sqlite: "SQLite"
+};
+class DebugInfoProvider {
+  #ctx;
+  constructor(ctx) {
+    this.#ctx = ctx;
+  }
+  /**
+   * Gathers debug information as an object.
+   *
+   * @returns A promise that resolves to the debug information object.
+   */
+  async getDebugInfoObj() {
+    const { adapterName, databaseDialect, installedPlugins } = this.#ctx;
+    const {
+      getPackageManager,
+      ProcessNodeVersionProvider,
+      ProcessPackageManagerUserAgentProvider,
+      ProcessSystemInfoProvider,
+      TinyexecCommandExecutor
+    } = await import("./cli-providers/index.js");
+    const nodeVersionProvider = new ProcessNodeVersionProvider();
+    const packageManagerUserAgentProvider = new ProcessPackageManagerUserAgentProvider();
+    const systemInfoProvider = new ProcessSystemInfoProvider();
+    const commandExecutor = new TinyexecCommandExecutor();
+    const packageManagerProvider = await getPackageManager({
+      packageManagerUserAgentProvider,
+      commandExecutor
+    });
+    async function getVersionWithIdentifier(identifier) {
+      const version = await packageManagerProvider.getPackageVersion(identifier);
+      if (!version) {
+        return identifier;
+      }
+      return `${identifier} (${version})`;
+    }
+    const fallbackValue = "Unavailable";
+    const AstroVersion = await packageManagerProvider.getPackageVersion("astro") || fallbackValue;
+    const AstroAdapter = await getVersionWithIdentifier(adapterName);
+    const DatabaseDialect = dbDialectLabels[databaseDialect] ?? databaseDialect;
+    const StudioCMSVersion = await packageManagerProvider.getPackageVersion("studiocms") || fallbackValue;
+    const StudioCMSUiVersion = await packageManagerProvider.getPackageVersion("@studiocms/ui") || fallbackValue;
+    return {
+      Astro: AstroVersion,
+      "Astro Adapter": AstroAdapter,
+      "Database Dialect": DatabaseDialect,
+      "Node.js": nodeVersionProvider.version,
+      "Package Manager": packageManagerProvider.name,
+      System: systemInfoProvider.displayName,
+      StudioCMS: StudioCMSVersion,
+      "StudioCMS UI": StudioCMSUiVersion,
+      "StudioCMS Plugins": await Promise.all(
+        installedPlugins.map(
+          async ({ identifier, name }) => `${name} - ${await getVersionWithIdentifier(identifier)}`
+        )
+      ).then((versions) => versions.join("\n"))
+    };
+  }
+  /**
+   * Gathers debug information as a formatted string.
+   *
+   * @returns A promise that resolves to the debug information string.
+   */
+  async getDebugInfoString(indent, { styled, styles: style } = {
+    styled: false
+  }) {
+    const { Formatter } = await import("./cli-providers/core/formatter.js");
+    const debugInfo = await this.getDebugInfoObj();
+    const styler = new Formatter(debugInfo, { indent, style });
+    return styler.format(styled);
+  }
+}
+export {
+  DebugInfoProvider
+};

package/dist/headConfigSchema.d.ts

@@ -7,11 +7,11 @@ export declare const HeadConfigSchema: () => z.ZodDefault<z.ZodArray<z.ZodObject
     /** Content to place inside the tag (optional). */
     content: z.ZodDefault<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    tag: "title" | "base" | "link" | "style" | "meta" | "script" | "noscript" | "template";
+    tag: "style" | "title" | "base" | "link" | "meta" | "script" | "noscript" | "template";
     attrs: Record<string, string | boolean | undefined>;
     content: string;
 }, {
-    tag: "title" | "base" | "link" | "style" | "meta" | "script" | "noscript" | "template";
+    tag: "style" | "title" | "base" | "link" | "meta" | "script" | "noscript" | "template";
     attrs?: Record<string, string | boolean | undefined> | undefined;
     content?: string | undefined;
 }>, "many">>;
@@ -25,17 +25,17 @@ export declare const HeadSchema: z.ZodDefault<z.ZodArray<z.ZodObject<{
     /** Content to place inside the tag (optional). */
     content: z.ZodDefault<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    tag: "title" | "base" | "link" | "style" | "meta" | "script" | "noscript" | "template";
+    tag: "style" | "title" | "base" | "link" | "meta" | "script" | "noscript" | "template";
     attrs: Record<string, string | boolean | undefined>;
     content: string;
 }, {
-    tag: "title" | "base" | "link" | "style" | "meta" | "script" | "noscript" | "template";
+    tag: "style" | "title" | "base" | "link" | "meta" | "script" | "noscript" | "template";
     attrs?: Record<string, string | boolean | undefined> | undefined;
     content?: string | undefined;
 }>, "many">>;
 /** Create a fully parsed, merged, and sorted head entry array from multiple sources. */
 export declare function createHead(defaults: HeadUserConfig, ...heads: HeadConfig[]): {
-    tag: "title" | "base" | "link" | "style" | "meta" | "script" | "noscript" | "template";
+    tag: "style" | "title" | "base" | "link" | "meta" | "script" | "noscript" | "template";
     attrs: Record<string, string | boolean | undefined>;
     content: string;
 }[];
@@ -57,15 +57,15 @@ export declare function hasOneOf(head: HeadConfig, entry: HeadConfig[number], ke
 export declare function getAttr(keys: string[], entry: HeadConfig[number]): [key: string, value: string | boolean] | undefined;
 /** Merge two heads, overwriting entries in the first head that exist in the second. */
 export declare function mergeHead(oldHead: HeadConfig, newHead: HeadConfig): {
-    tag: "title" | "base" | "link" | "style" | "meta" | "script" | "noscript" | "template";
+    tag: "style" | "title" | "base" | "link" | "meta" | "script" | "noscript" | "template";
     attrs: Record<string, string | boolean | undefined>;
     content: string;
 }[];
 /** Sort head tags to place important tags first and relegate “SEO” meta tags. */
 export declare function sortHead(head: HeadConfig): {
-    tag: "title" | "base" | "link" | "style" | "meta" | "script" | "noscript" | "template";
+    tag: "style" | "title" | "base" | "link" | "meta" | "script" | "noscript" | "template";
     attrs: Record<string, string | boolean | undefined>;
     content: string;
 }[];
 /** Get the relative importance of a specific head tag. */
-export declare function getImportance(entry: HeadConfig[number]): 100 | 90 | 70 | 80 | 0;
+export declare function getImportance(entry: HeadConfig[number]): 0 | 100 | 90 | 70 | 80;

package/dist/pathResolver.d.ts

@@ -0,0 +1,30 @@
+interface PathResolver {
+    resolve: (...segments: string[]) => string;
+    resolveURL: (...segments: string[]) => URL;
+}
+/**
+ * Create a path resolver anchored to the provided base.
+ *
+ * The function accepts either a file URL (for example `import.meta.url`, i.e. a string
+ * that starts with `file://`) or a regular filesystem path (absolute or relative,
+ * e.g. `process.cwd()` or a custom string). If a file URL is provided it will be
+ * converted to the directory containing that file; otherwise the provided string is
+ * used directly as the base directory.
+ *
+ * @param baseOption - Base location used to resolve relative paths. Either:
+ *   - a file URL string (starts with "file://", e.g. `import.meta.url`), or
+ *   - a filesystem path string (absolute or relative).
+ * @returns An object with two helpers:
+ *   - `resolve(...segments: string[]): string` — resolves the given path segments
+ *     against the computed base directory and returns an absolute filesystem path.
+ *   - `resolveURL(...segments: string[]): URL` — resolves the given path segments
+ *     against the computed base directory and returns a `file://` URL.
+ *
+ * @example
+ * // Using import.meta.url as the base:
+ * const resolver = createPathResolver(import.meta.url);
+ * const absolutePath = resolver.resolve('..', 'assets', 'image.png');
+ * const fileUrl = resolver.resolveURL('..', 'assets', 'image.png');
+ */
+declare function createPathResolver(baseOption: string): PathResolver;
+export default createPathResolver;

package/dist/pathResolver.js

@@ -0,0 +1,31 @@
+import * as path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+function createPathResolver(baseOption) {
+  let baseDir;
+  if (baseOption.startsWith("file://")) {
+    const filePath = fileURLToPath(baseOption);
+    baseDir = path.dirname(filePath);
+  } else {
+    baseDir = path.resolve(baseOption);
+  }
+  return {
+    /**
+     * Resolve path segments against the base directory.
+     *
+     * @param segments - Path segments to resolve.
+     * @returns The resolved absolute filesystem path.
+     */
+    resolve: (...segments) => path.resolve(baseDir, ...segments),
+    /**
+     * Resolve path segments against the base directory and return a file URL.
+     *
+     * @param segments - Path segments to resolve.
+     * @returns The resolved file URL.
+     */
+    resolveURL: (...segments) => pathToFileURL(path.resolve(baseDir, ...segments))
+  };
+}
+var pathResolver_default = createPathResolver;
+export {
+  pathResolver_default as default
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withstudiocms/internal_helpers",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.4",
   "description": "Internal helper utilities for StudioCMS",
   "author": {
     "name": "withstudiocms",
@@ -56,14 +56,35 @@
     "./headConfigSchema": {
       "types": "./dist/headConfigSchema.d.ts",
       "default": "./dist/headConfigSchema.js"
+    },
+    "./pathResolver": {
+      "types": "./dist/pathResolver.d.ts",
+      "default": "./dist/pathResolver.js"
+    },
+    "./debug-info-provider": {
+      "types": "./dist/debug-info-provider.d.ts",
+      "default": "./dist/debug-info-provider.js"
+    },
+    "./cli-providers": {
+      "types": "./dist/cli-providers/index.d.ts",
+      "default": "./dist/cli-providers/index.js"
+    },
+    "./cli-providers/definitions": {
+      "types": "./dist/cli-providers/definitions.d.ts",
+      "default": "./dist/cli-providers/definitions.js"
+    },
+    "./cli-providers/core/*": {
+      "types": "./dist/cli-providers/core/*.d.ts",
+      "default": "./dist/cli-providers/core/*.js"
     }
   },
   "type": "module",
   "dependencies": {
-    "astro-integration-kit": "^0.19.0",
+    "astro-integration-kit": "^0.19.1",
     "mdast-util-from-markdown": "^2.0.2",
     "mdast-util-to-string": "^4.0.0",
-    "unist-util-visit": "^5.0.0"
+    "unist-util-visit": "^5.0.0",
+    "tinyexec": "^1.0.2"
   },
   "devDependencies": {
     "@types/mdast": "^4.0.4",