@withstudiocms/internal_helpers 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present StudioCMS - withstudiocms (https://github.com/withstudiocms)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @withstudiocms/internal_helpers
+
+Internal helpers and utilities for the @withstudiocms eco-system.
+
+## License
+
+[MIT Licensed](./LICENSE)

package/dist/astro-integration/addIntegrationArray.d.ts

@@ -0,0 +1,24 @@
+import type { AstroIntegration } from 'astro';
+/**
+ * Easily add a list of integrations from within an integration.
+ *
+ * @param {import("astro").HookParameters<"astro:config:setup">} params
+ * @param {array} integrations
+ *
+ * @example
+ * ```ts
+ * import Vue from "@astrojs/vue";
+ * import tailwindcss from "@astrojs/tailwind";
+ *
+ * addIntegrationArray(params, [
+ *  { integration: Vue(), ensureUnique: true }
+ *  { integration: tailwindcss() }
+ * ])
+ * ```
+ *
+ * @see https://astro-integration-kit.netlify.app/utilities/add-integration/
+ */
+export declare const addIntegrationArray: import("astro-integration-kit").HookUtility<"astro:config:setup", [integrations: {
+    integration: AstroIntegration;
+    ensureUnique?: boolean | undefined;
+}[]], void>;

package/dist/astro-integration/addIntegrationArray.js

@@ -0,0 +1,11 @@
+import { addIntegration, defineUtility } from "astro-integration-kit";
+const addIntegrationArray = defineUtility("astro:config:setup")(
+  (params, integrations) => {
+    for (const { integration, ensureUnique } of integrations) {
+      addIntegration(params, { integration, ensureUnique });
+    }
+  }
+);
+export {
+  addIntegrationArray
+};

package/dist/astro-integration/getLatestVersion.d.ts

@@ -0,0 +1,12 @@
+import type { AstroIntegrationLogger } from 'astro';
+/**
+ * Fetches the latest version of a given npm package from the npm registry.
+ *
+ * @param packageName - The name of the npm package to fetch the latest version for.
+ * @param logger - An instance of `AstroIntegrationLogger` used to log errors if the fetch fails.
+ * @returns A promise that resolves to the latest version of the package as a string,
+ *          or `null` if an error occurs during the fetch process.
+ *
+ * @throws Will throw an error if the HTTP response from the npm registry is not successful.
+ */
+export declare function getLatestVersion(packageName: string, logger: AstroIntegrationLogger, cacheJsonFile: URL | undefined, isDevMode: boolean): Promise<string | null>;

package/dist/astro-integration/getLatestVersion.js

@@ -0,0 +1,36 @@
+import fs from "node:fs";
+import { jsonParse } from "../utils/jsonUtils.js";
+async function getLatestVersion(packageName, logger, cacheJsonFile, isDevMode) {
+  let cacheData = {};
+  if (isDevMode && cacheJsonFile) {
+    const file = fs.readFileSync(cacheJsonFile, { encoding: "utf-8" });
+    cacheData = jsonParse(file);
+    if (cacheData.latestVersionCheck?.lastChecked && new Date(cacheData.latestVersionCheck.lastChecked).getTime() > new Date(Date.now() - 60 * 60 * 1e3).getTime()) {
+      return cacheData.latestVersionCheck.version;
+    }
+  }
+  try {
+    const response = await fetch(`https://registry.npmjs.org/${packageName}/latest`);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch package info: ${response.statusText}`);
+    }
+    const data = await response.json();
+    if (isDevMode && cacheJsonFile) {
+      const updatedCacheData = {
+        ...cacheData,
+        latestVersionCheck: {
+          lastChecked: /* @__PURE__ */ new Date(),
+          version: data.version
+        }
+      };
+      fs.writeFileSync(cacheJsonFile, JSON.stringify(updatedCacheData, null, 2), "utf-8");
+    }
+    return data.version;
+  } catch (error) {
+    logger.error(`Error fetching latest version of ${packageName}: ${error}`);
+    return null;
+  }
+}
+export {
+  getLatestVersion
+};

package/dist/astro-integration/index.d.ts

@@ -0,0 +1,4 @@
+export * from './addIntegrationArray.js';
+export * from './getLatestVersion.js';
+export * from './injectScripts.js';
+export * from './integrationLogger.js';

package/dist/astro-integration/index.js

@@ -0,0 +1,4 @@
+export * from "./addIntegrationArray.js";
+export * from "./getLatestVersion.js";
+export * from "./injectScripts.js";
+export * from "./integrationLogger.js";

package/dist/astro-integration/injectScripts.d.ts

@@ -0,0 +1,26 @@
+import type { InjectedScriptStage } from 'astro';
+/**
+ * Represents a script to be injected at a specific stage of the integration process.
+ *
+ * @property stage - The stage at which the script should be injected.
+ * @property content - The actual script content as a string.
+ * @property enabled - Indicates whether the script is enabled for injection.
+ */
+export interface ScriptEntry {
+    stage: InjectedScriptStage;
+    content: string;
+    enabled: boolean;
+}
+/**
+ * Injects scripts into the Astro configuration setup stage.
+ *
+ * This utility iterates over an array of script entries and injects each enabled script
+ * at the specified stage using the provided `params.injectScript` method.
+ *
+ * @param params - The parameters provided by the Astro integration context, including the `injectScript` function.
+ * @param entries - An array of script entries to be injected. Each entry contains:
+ *   - `stage`: The stage at which the script should be injected.
+ *   - `content`: The script content to inject.
+ *   - `enabled`: A boolean indicating whether the script should be injected.
+ */
+export declare const injectScripts: import("astro-integration-kit").HookUtility<"astro:config:setup", [entries: ScriptEntry[]], void>;

package/dist/astro-integration/injectScripts.js

@@ -0,0 +1,12 @@
+import { defineUtility } from "astro-integration-kit";
+const injectScripts = defineUtility("astro:config:setup")(
+  ({ injectScript }, entries) => {
+    for (const { enabled, stage, content } of entries) {
+      if (!enabled) continue;
+      injectScript(stage, content);
+    }
+  }
+);
+export {
+  injectScripts
+};

package/dist/astro-integration/integrationLogger.d.ts

@@ -0,0 +1,59 @@
+import type { AstroIntegrationLogger } from 'astro';
+/**
+ * Represents an array of message objects.
+ * Each message object contains information about a log message.
+ *
+ * @property {string} label - The label associated with the message.
+ * @property {'info' | 'warn' | 'error' | 'debug'} logLevel - The level of the log message.
+ * @property {string} message - The content of the log message.
+ */
+export type Messages = {
+    label: string;
+    logLevel: 'info' | 'warn' | 'error' | 'debug';
+    message: string;
+}[];
+/**
+ * Options for configuring the integration logger.
+ *
+ * @property logLevel - The minimum level of messages to log. Can be 'info', 'warn', 'error', or 'debug'.
+ * @property logger - The logger instance to use for logging messages.
+ * @property verbose - Optional flag to enable verbose logging output.
+ */
+export type LoggerOpts = {
+    logLevel: 'info' | 'warn' | 'error' | 'debug';
+    logger: AstroIntegrationLogger;
+    verbose?: boolean;
+};
+/**
+ * Logs a message using the provided logger and log level, with optional verbosity control.
+ *
+ * @param opts - An object containing logger options:
+ *   - `logLevel`: The level at which to log the message (e.g., 'debug', 'info', 'warn', 'error').
+ *   - `logger`: The logger instance with methods corresponding to log levels.
+ *   - `verbose`: If true, always logs the message; if false, only logs for levels other than 'debug' and 'info'.
+ * @param message - The message to be logged.
+ * @returns A promise that resolves when logging is complete.
+ */
+export declare const integrationLogger: (opts: LoggerOpts, message: string) => Promise<void>;
+/**
+ * Creates a new `AstroIntegrationLogger` instance scoped to a specific plugin.
+ *
+ * @param id - The unique identifier for the plugin.
+ * @param logger - The base `AstroIntegrationLogger` to fork from.
+ * @returns A new `AstroIntegrationLogger` instance with a namespace prefixed by `plugin:{id}`.
+ */
+export declare function pluginLogger(id: string, logger: AstroIntegrationLogger): AstroIntegrationLogger;
+/**
+ * Logs a series of messages using the provided Astro integration logger.
+ *
+ * @param messages - An array of message objects, each containing a label, message, and log level.
+ * @param options - Options for logging, including a `verbose` flag to control verbosity.
+ * @param logger - The Astro integration logger instance used for logging messages.
+ *
+ * @remarks
+ * Each message is logged with a forked logger using its label. The verbosity of 'info' level logs
+ * is controlled by the `options.verbose` flag, while other log levels are always logged.
+ */
+export declare function logMessages(messages: Messages, options: {
+    verbose: boolean;
+}, logger: AstroIntegrationLogger): Promise<void>;

package/dist/astro-integration/integrationLogger.js

@@ -0,0 +1,36 @@
+const integrationLogger = async (opts, message) => {
+  const { logLevel, logger, verbose } = opts;
+  switch (verbose) {
+    case true:
+      logger[logLevel](message);
+      break;
+    case false:
+      if (logLevel !== "debug" && logLevel !== "info") {
+        logger[logLevel](message);
+      }
+      break;
+    default:
+      logger[logLevel](message);
+  }
+};
+function pluginLogger(id, logger) {
+  const newLogger = logger.fork(`plugin:${id}`);
+  return newLogger;
+}
+async function logMessages(messages, options, logger) {
+  for (const { label, message, logLevel } of messages) {
+    await integrationLogger(
+      {
+        logger: logger.fork(label),
+        logLevel,
+        verbose: logLevel === "info" ? options.verbose : true
+      },
+      message
+    );
+  }
+}
+export {
+  integrationLogger,
+  logMessages,
+  pluginLogger
+};

package/dist/headConfigSchema.d.ts

@@ -0,0 +1,71 @@
+import { z } from 'astro/zod';
+export declare const HeadConfigSchema: () => z.ZodDefault<z.ZodArray<z.ZodObject<{
+    /** Name of the HTML tag to add to `<head>`, e.g. `'meta'`, `'link'`, or `'script'`. */
+    tag: z.ZodEnum<["title", "base", "link", "style", "meta", "script", "noscript", "template"]>;
+    /** Attributes to set on the tag, e.g. `{ rel: 'stylesheet', href: '/custom.css' }`. */
+    attrs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodBoolean, z.ZodUndefined]>>>;
+    /** Content to place inside the tag (optional). */
+    content: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    tag: "title" | "base" | "link" | "style" | "meta" | "script" | "noscript" | "template";
+    attrs: Record<string, string | boolean | undefined>;
+    content: string;
+}, {
+    tag: "title" | "base" | "link" | "style" | "meta" | "script" | "noscript" | "template";
+    attrs?: Record<string, string | boolean | undefined> | undefined;
+    content?: string | undefined;
+}>, "many">>;
+export type HeadUserConfig = z.input<ReturnType<typeof HeadConfigSchema>>;
+export type HeadConfig = z.output<ReturnType<typeof HeadConfigSchema>>;
+export declare const HeadSchema: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    /** Name of the HTML tag to add to `<head>`, e.g. `'meta'`, `'link'`, or `'script'`. */
+    tag: z.ZodEnum<["title", "base", "link", "style", "meta", "script", "noscript", "template"]>;
+    /** Attributes to set on the tag, e.g. `{ rel: 'stylesheet', href: '/custom.css' }`. */
+    attrs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodBoolean, z.ZodUndefined]>>>;
+    /** Content to place inside the tag (optional). */
+    content: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    tag: "title" | "base" | "link" | "style" | "meta" | "script" | "noscript" | "template";
+    attrs: Record<string, string | boolean | undefined>;
+    content: string;
+}, {
+    tag: "title" | "base" | "link" | "style" | "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";
+    attrs: Record<string, string | boolean | undefined>;
+    content: string;
+}[];
+/**
+ * Test if a head config object contains a matching `<title>` or `<meta>` tag.
+ *
+ * For example, will return true if `head` already contains
+ * `<meta name="description" content="A">` and the passed `tag`
+ * is `<meta name="description" content="B">`. Tests against `name`,
+ * `property`, and `http-equiv` attributes for `<meta>` tags.
+ */
+export declare function hasTag(head: HeadConfig, entry: HeadConfig[number]): boolean;
+/**
+ * Test if a head config object contains a tag of the same type
+ * as `entry` and a matching attribute for one of the passed `keys`.
+ */
+export declare function hasOneOf(head: HeadConfig, entry: HeadConfig[number], keys: string[]): boolean;
+/** Find the first matching key–value pair in a head entry’s attributes. */
+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";
+    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";
+    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;

package/dist/headConfigSchema.js

@@ -0,0 +1,80 @@
+import { z } from "astro/zod";
+const HeadConfigSchema = () => z.array(
+  z.object({
+    /** Name of the HTML tag to add to `<head>`, e.g. `'meta'`, `'link'`, or `'script'`. */
+    tag: z.enum(["title", "base", "link", "style", "meta", "script", "noscript", "template"]),
+    /** Attributes to set on the tag, e.g. `{ rel: 'stylesheet', href: '/custom.css' }`. */
+    attrs: z.record(z.union([z.string(), z.boolean(), z.undefined()])).default({}),
+    /** Content to place inside the tag (optional). */
+    content: z.string().default("")
+  })
+).default([]);
+const HeadSchema = HeadConfigSchema();
+function createHead(defaults, ...heads) {
+  let head = HeadSchema.parse(defaults);
+  for (const next of heads) {
+    head = mergeHead(head, next);
+  }
+  return sortHead(head);
+}
+function hasTag(head, entry) {
+  switch (entry.tag) {
+    case "title":
+      return head.some(({ tag }) => tag === "title");
+    case "meta":
+      return hasOneOf(head, entry, ["name", "property", "http-equiv"]);
+    default:
+      return false;
+  }
+}
+function hasOneOf(head, entry, keys) {
+  const attr = getAttr(keys, entry);
+  if (!attr) return false;
+  const [key, val] = attr;
+  return head.some(({ tag, attrs }) => tag === entry.tag && attrs[key] === val);
+}
+function getAttr(keys, entry) {
+  let attr;
+  for (const key of keys) {
+    const val = entry.attrs[key];
+    if (val) {
+      attr = [key, val];
+      break;
+    }
+  }
+  return attr;
+}
+function mergeHead(oldHead, newHead) {
+  return [...oldHead.filter((tag) => !hasTag(newHead, tag)), ...newHead];
+}
+function sortHead(head) {
+  return head.sort((a, b) => {
+    const aImportance = getImportance(a);
+    const bImportance = getImportance(b);
+    return aImportance > bImportance ? -1 : bImportance > aImportance ? 1 : 0;
+  });
+}
+function getImportance(entry) {
+  if (entry.tag === "meta" && ("charset" in entry.attrs || "http-equiv" in entry.attrs || entry.attrs.name === "viewport")) {
+    return 100;
+  }
+  if (entry.tag === "title") return 90;
+  if (entry.tag !== "meta") {
+    if (entry.tag === "link" && "rel" in entry.attrs && entry.attrs.rel === "shortcut icon") {
+      return 70;
+    }
+    return 80;
+  }
+  return 0;
+}
+export {
+  HeadConfigSchema,
+  HeadSchema,
+  createHead,
+  getAttr,
+  getImportance,
+  hasOneOf,
+  hasTag,
+  mergeHead,
+  sortHead
+};

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './utils/index.js';

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./utils/index.js";

package/dist/pathGenerators.d.ts

@@ -0,0 +1,20 @@
+/** Get the a root-relative URL path with the site’s `base` prefixed. */
+export declare function pathWithBase(path: string): string;
+/** Get the a root-relative file URL path with the site’s `base` prefixed. */
+export declare function fileWithBase(path: string): string;
+/** Ensure the passed path starts with a leading slash. */
+export declare function ensureLeadingSlash(href: string): string;
+/** Ensure the passed path ends with a trailing slash. */
+export declare function ensureTrailingSlash(href: string): string;
+/** Ensure the passed path starts and ends with slashes. */
+export declare function ensureLeadingAndTrailingSlashes(href: string): string;
+/** Ensure the passed path does not start with a leading slash. */
+export declare function stripLeadingSlash(href: string): string;
+/** Ensure the passed path does not end with a trailing slash. */
+export declare function stripTrailingSlash(href: string): string;
+/** Ensure the passed path does not start and end with slashes. */
+export declare function stripLeadingAndTrailingSlashes(href: string): string;
+/** Remove the extension from a path. */
+export declare function stripHtmlExtension(path: string): string;
+/** Add '.html' extension to a path. */
+export declare function ensureHtmlExtension(path: string): string;

package/dist/pathGenerators.js

@@ -0,0 +1,66 @@
+function pathWithBase(path) {
+  let newPath = path;
+  newPath = stripLeadingSlash(newPath);
+  return newPath ? `/${newPath}` : "/";
+}
+function fileWithBase(path) {
+  let newPath = path;
+  newPath = stripLeadingSlash(newPath);
+  return newPath ? `/${newPath}` : "/";
+}
+function ensureLeadingSlash(href) {
+  let newHref = href;
+  if (newHref[0] !== "/") newHref = `/${newHref}`;
+  return newHref;
+}
+function ensureTrailingSlash(href) {
+  let newHref = href;
+  if (newHref[newHref.length - 1] !== "/") newHref += "/";
+  return newHref;
+}
+function ensureLeadingAndTrailingSlashes(href) {
+  let newHref = href;
+  newHref = ensureLeadingSlash(newHref);
+  newHref = ensureTrailingSlash(newHref);
+  return newHref;
+}
+function stripLeadingSlash(href) {
+  let newHref = href;
+  if (newHref[0] === "/") newHref = newHref.slice(1);
+  return newHref;
+}
+function stripTrailingSlash(href) {
+  let newHref = href;
+  if (newHref[newHref.length - 1] === "/") newHref = newHref.slice(0, -1);
+  return newHref;
+}
+function stripLeadingAndTrailingSlashes(href) {
+  let newHref = href;
+  newHref = stripLeadingSlash(newHref);
+  newHref = stripTrailingSlash(newHref);
+  return newHref;
+}
+function stripHtmlExtension(path) {
+  const pathWithoutTrailingSlash = stripTrailingSlash(path);
+  return pathWithoutTrailingSlash.endsWith(".html") ? pathWithoutTrailingSlash.slice(0, -5) : pathWithoutTrailingSlash;
+}
+function ensureHtmlExtension(path) {
+  let newPath = path;
+  newPath = stripLeadingAndTrailingSlashes(newPath);
+  if (!newPath.endsWith(".html")) {
+    newPath = newPath ? `${newPath}.html` : "/index.html";
+  }
+  return ensureLeadingSlash(newPath);
+}
+export {
+  ensureHtmlExtension,
+  ensureLeadingAndTrailingSlashes,
+  ensureLeadingSlash,
+  ensureTrailingSlash,
+  fileWithBase,
+  pathWithBase,
+  stripHtmlExtension,
+  stripLeadingAndTrailingSlashes,
+  stripLeadingSlash,
+  stripTrailingSlash
+};

package/dist/urlGenFactory.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Creates a URL generator factory function with a default dashboard route.
+ *
+ * The returned `urlGenFactory` function generates URLs based on whether the route is a dashboard route,
+ * an optional path, and an optional dashboard route override.
+ *
+ * @param defaultDashboardRoute - The default base route for dashboard URLs.
+ * @returns A factory function that generates URLs based on the provided parameters.
+ *
+ * @example
+ * const urlGen = createURLGenFactory('dashboard');
+ * urlGen(true, 'settings'); // Returns '/dashboard/settings'
+ * urlGen(false, 'about');   // Returns '/about'
+ */
+export declare function createURLGenFactory(defaultDashboardRoute: string): (isDashboardRoute: boolean, path: string | undefined, DashboardRouteOverride?: string) => string;

package/dist/urlGenFactory.js

@@ -0,0 +1,28 @@
+import { pathWithBase, stripLeadingAndTrailingSlashes } from "./pathGenerators.js";
+function createURLGenFactory(defaultDashboardRoute) {
+  return function urlGenFactory(isDashboardRoute, path, DashboardRouteOverride) {
+    let url;
+    let dashboardRoute = stripLeadingAndTrailingSlashes(defaultDashboardRoute);
+    if (DashboardRouteOverride) {
+      dashboardRoute = stripLeadingAndTrailingSlashes(DashboardRouteOverride);
+    }
+    if (path) {
+      const cleanPath = stripLeadingAndTrailingSlashes(path);
+      if (isDashboardRoute) {
+        url = pathWithBase(`${dashboardRoute}/${cleanPath}`);
+      } else {
+        url = pathWithBase(cleanPath);
+      }
+    } else {
+      if (isDashboardRoute) {
+        url = pathWithBase(dashboardRoute);
+      } else {
+        url = pathWithBase("");
+      }
+    }
+    return url;
+  };
+}
+export {
+  createURLGenFactory
+};

package/dist/utils/index.d.ts

@@ -0,0 +1,4 @@
+export * from './jsonUtils.js';
+export * from './loadChangelog.js';
+export * from './pageTypeFilter.js';
+export * from './safeString.js';

package/dist/utils/index.js

@@ -0,0 +1,4 @@
+export * from "./jsonUtils.js";
+export * from "./loadChangelog.js";
+export * from "./pageTypeFilter.js";
+export * from "./safeString.js";

package/dist/utils/jsonUtils.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Parses a JSON string and returns the resulting object.
+ *
+ * @template T - The expected type of the parsed object.
+ * @param text - The JSON string to parse.
+ * @returns The parsed object of type `T`.
+ * @throws {SyntaxError} If the input string is not valid JSON.
+ */
+export declare function jsonParse<T extends object>(text: string): T;
+/**
+ * Reads a JSON file and parses it into an object of type T.
+ */
+export declare function readJson<T extends object>(path: string | URL): T;

package/dist/utils/jsonUtils.js

@@ -0,0 +1,11 @@
+import fs from "node:fs";
+function jsonParse(text) {
+  return JSON.parse(text);
+}
+function readJson(path) {
+  return jsonParse(fs.readFileSync(path, "utf-8"));
+}
+export {
+  jsonParse,
+  readJson
+};

package/dist/utils/loadChangelog.d.ts

@@ -0,0 +1,82 @@
+import type { List } from 'mdast';
+/**
+ * Represents a changelog entry for a specific version.
+ *
+ * @property version - The semantic version string (e.g., "1.2.3").
+ * @property changes - An object mapping each semantic version category to a list of changes.
+ * @property includes - A set of strings indicating included features or modules for this version.
+ */
+export type Version = {
+    version: string;
+    changes: {
+        [key in SemverCategory]: List;
+    };
+    includes: Set<string>;
+};
+/**
+ * Represents the changelog for a package, including its name and a list of versions.
+ *
+ * @property packageName - The name of the package.
+ * @property versions - An array of version objects associated with the package.
+ */
+export type Changelog = {
+    packageName: string;
+    versions: Version[];
+};
+/**
+ * Defines the semantic versioning categories used to classify changes.
+ * - `major`: Indicates breaking changes.
+ * - `minor`: Indicates backward-compatible feature additions.
+ * - `patch`: Indicates backward-compatible bug fixes.
+ */
+export declare const semverCategories: readonly ["major", "minor", "patch"];
+/**
+ * Represents a semantic versioning category, derived from the `semverCategories` array.
+ *
+ * This type is useful for constraining values to valid semantic version categories.
+ */
+export type SemverCategory = (typeof semverCategories)[number];
+/**
+ * Represents the raw source of a changelog.
+ *
+ * @property raw - The raw changelog content as a string.
+ */
+type RawChangelogSrc = {
+    raw: string;
+};
+/**
+ * Represents a changelog to be loaded from a file.
+ *
+ * @property path - The file system path to the changelog file.
+ */
+type FromFileChangelog = {
+    path: string;
+};
+/**
+ * Represents the source of a changelog, which can either be a raw changelog source
+ * or a changelog loaded from a file.
+ *
+ * @see RawChangelogSrc
+ * @see FromFileChangelog
+ */
+export type ChangeLogSrc = RawChangelogSrc | FromFileChangelog;
+/**
+ * Loads and parses a changelog from either a file path or a raw markdown string.
+ *
+ * - Reads the changelog markdown content from the provided source.
+ * - Converts GitHub usernames in "Thanks ..." sentences to markdown links.
+ * - Parses the markdown into an AST and extracts structured changelog information:
+ *   - The package name (from the first-level heading).
+ *   - Versions (from second-level headings).
+ *   - Semantic version categories (from third-level headings).
+ *   - Changes for each category, filtering out package references and dependency updates.
+ *   - Tracks included package references for each version.
+ *
+ * Throws errors if the markdown structure does not match the expected format.
+ *
+ * @param src - The source of the changelog, either a file path or raw markdown.
+ * @returns The parsed changelog object containing package name, versions, and categorized changes.
+ * @throws {Error} If the markdown structure is unexpected or invalid.
+ */
+export declare function loadChangelog(src: ChangeLogSrc): Changelog;
+export {};

package/dist/utils/loadChangelog.js

@@ -0,0 +1,109 @@
+import fs from "node:fs";
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { toString as ToString } from "mdast-util-to-string";
+import { visit } from "unist-util-visit";
+const semverCategories = ["major", "minor", "patch"];
+function loadChangelog(src) {
+  let markdown;
+  if ("path" in src) {
+    markdown = fs.readFileSync(src.path, "utf8");
+  } else {
+    markdown = src.raw;
+  }
+  markdown = markdown.replace(
+    /(?<=Thank[^.!]*? )@([a-z0-9-]+)(?=[\s,.!])/gi,
+    "[@$1](https://github.com/$1)"
+  );
+  const ast = fromMarkdown(markdown);
+  const changelog = {
+    packageName: "",
+    versions: []
+  };
+  let state = "packageName";
+  let version;
+  let semverCategory;
+  function handleNode(node) {
+    if (node.type === "heading") {
+      if (node.depth === 1) {
+        if (state !== "packageName") throw new Error("Unexpected h1");
+        changelog.packageName = ToString(node);
+        state = "version";
+        return;
+      }
+      if (node.depth === 2) {
+        if (state === "packageName") throw new Error("Unexpected h2");
+        version = {
+          version: ToString(node),
+          changes: {
+            major: { type: "list", children: [] },
+            minor: { type: "list", children: [] },
+            patch: { type: "list", children: [] }
+          },
+          includes: /* @__PURE__ */ new Set()
+        };
+        changelog.versions.push(version);
+        state = "semverCategory";
+        return;
+      }
+      if (node.depth === 3) {
+        if (state === "packageName" || state === "version") throw new Error("Unexpected h3");
+        semverCategory = (ToString(node).split(" ")[0] || "").toLowerCase();
+        if (!semverCategories.includes(semverCategory))
+          throw new Error(`Unexpected semver category: ${semverCategory}`);
+        state = "changes";
+        return;
+      }
+    }
+    if (node.type === "list") {
+      if (state !== "changes" || !version || !semverCategory) throw new Error("Unexpected list");
+      for (let listItemIdx = 0; listItemIdx < node.children.length; listItemIdx++) {
+        const listItem = node.children[listItemIdx];
+        if (!listItem) continue;
+        const lastChild = listItem.children[listItem.children.length - 1];
+        if (lastChild?.type === "list") {
+          const packageRefs = [];
+          lastChild.children.forEach((subListItem) => {
+            const text = ToString(subListItem);
+            if (parsePackageReference(text)) packageRefs.push(text);
+          });
+          if (packageRefs.length === lastChild.children.length) {
+            for (const packageRef of packageRefs) {
+              version.includes.add(packageRef);
+            }
+            listItem.children.pop();
+          }
+        }
+        const firstPara = listItem.children[0]?.type === "paragraph" ? listItem.children[0] : void 0;
+        if (firstPara) {
+          visit(firstPara, "text", (textNode) => {
+            textNode.value = textNode.value.replace(/(^[0-9a-f]{7,}: | \[[0-9a-f]{7,}\]$)/, "");
+          });
+          const firstParaText = ToString(firstPara);
+          if (firstParaText === "Updated dependencies") continue;
+          const packageRef = parsePackageReference(firstParaText);
+          if (packageRef) {
+            version.includes.add(firstParaText);
+            continue;
+          }
+          version.changes[semverCategory].children.push(listItem);
+        }
+      }
+      return;
+    }
+    throw new Error(`Unexpected node: ${JSON.stringify(node)}`);
+  }
+  ast.children.forEach((node) => {
+    handleNode(node);
+  });
+  return changelog;
+}
+function parsePackageReference(str) {
+  const matches = str.match(/^([@/a-z0-9-]+)@([0-9.]+)$/);
+  if (!matches) return;
+  const [, packageName, version] = matches;
+  return { packageName, version };
+}
+export {
+  loadChangelog,
+  semverCategories
+};

package/dist/utils/pageTypeFilter.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Generates an export statement for a renderer component based on the provided component path and page type.
+ *
+ * @param comp - The path to the renderer component. Must be a non-undefined string.
+ * @param safePageType - The page type to use as the exported name.
+ * @returns An export statement string that re-exports the default export of the component under the given page type name.
+ * @throws {Error} If the `comp` parameter is undefined.
+ */
+export declare function rendererComponentFilter(comp: string | undefined, safePageType: string): string;
+/**
+ * Generates an export statement for a page content component based on the provided component path and page type.
+ *
+ * @param comp - The path to the component as a string. If undefined, an error is thrown.
+ * @param safePageType - The safe page type string used as the export alias.
+ * @returns An export statement string that re-exports the default export of the component under the given page type alias.
+ * @throws {Error} If the `comp` parameter is not provided.
+ */
+export declare function pageContentComponentFilter(comp: string | undefined, safePageType: string): string;

package/dist/utils/pageTypeFilter.js

@@ -0,0 +1,16 @@
+function rendererComponentFilter(comp, safePageType) {
+  if (!comp) {
+    throw new Error(`Renderer Component path is required for page type: ${safePageType}`);
+  }
+  return `export { default as ${safePageType} } from '${comp}';`;
+}
+function pageContentComponentFilter(comp, safePageType) {
+  if (!comp) {
+    throw new Error(`Page Content Component path is required for page type: ${safePageType}`);
+  }
+  return `export { default as ${safePageType} } from '${comp}';`;
+}
+export {
+  pageContentComponentFilter,
+  rendererComponentFilter
+};

package/dist/utils/safeString.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Converts a given string into a "safe" string by replacing all non-alphanumeric
+ * characters with underscores, trimming leading and trailing underscores, and converting
+ * the result to lowercase.
+ *
+ * @param string - The input string to be converted.
+ * @returns The sanitized, lowercase string with non-alphanumeric characters replaced by underscores.
+ */
+export declare function convertToSafeString(string: string): string;

package/dist/utils/safeString.js

@@ -0,0 +1,6 @@
+function convertToSafeString(string) {
+  return string.replace(/[^a-zA-Z0-9]/g, "_").replace(/^_+|_+$/g, "").toLowerCase();
+}
+export {
+  convertToSafeString
+};

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@withstudiocms/internal_helpers",
+  "version": "0.1.0-beta.1",
+  "description": "Internal helper utilities for StudioCMS",
+  "author": {
+    "name": "withstudiocms",
+    "url": "https://studiocms.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/withstudiocms/studiocms.git",
+    "directory": "packages/@withstudiocms/internal_helpers"
+  },
+  "contributors": [
+    "Adammatthiesen",
+    "jdtjenkins",
+    "dreyfus92",
+    "code.spirit"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "astro-studiocms",
+    "cms",
+    "studiocms"
+  ],
+  "homepage": "https://studiocms.dev",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./utils": {
+      "types": "./dist/utils/index.d.ts",
+      "default": "./dist/utils/index.js"
+    },
+    "./astro-integration": {
+      "types": "./dist/astro-integration/index.d.ts",
+      "default": "./dist/astro-integration/index.js"
+    },
+    "./pathGenerators": {
+      "types": "./dist/pathGenerators.d.ts",
+      "default": "./dist/pathGenerators.js"
+    },
+    "./urlGenFactory": {
+      "types": "./dist/urlGenFactory.d.ts",
+      "default": "./dist/urlGenFactory.js"
+    },
+    "./headConfigSchema": {
+      "types": "./dist/headConfigSchema.d.ts",
+      "default": "./dist/headConfigSchema.js"
+    }
+  },
+  "type": "module",
+  "dependencies": {
+    "astro-integration-kit": "^0.19.0",
+    "mdast-util-from-markdown": "^2.0.2",
+    "mdast-util-to-string": "^4.0.0",
+    "unist-util-visit": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/mdast": "^4.0.4",
+    "@types/node": "^22.0.0"
+  },
+  "peerDependencies": {
+    "astro": "^5.12.9"
+  },
+  "scripts": {
+    "build": "buildkit build 'src/**/*.{ts,astro,css,json,png}'",
+    "dev": "buildkit dev 'src/**/*.{ts,astro,css,json,png}'",
+    "test": "buildkit test 'test/**/*.test.js'",
+    "typecheck": "tspc -p tsconfig.tspc.json"
+  }
+}