@holo-js/cli 0.2.6 → 0.3.0

package/dist/chunk-3RFRE7XG.mjs

@@ -0,0 +1,491 @@
+import {
+  normalizeCommandAliases
+} from "./chunk-TRYHX5S4.mjs";
+import {
+  APP_CONFIG_FILE_NAMES,
+  pathExists,
+  readTextFile,
+  resolveFirstExistingPath,
+  writeTextFile
+} from "./chunk-YACY2572.mjs";
+
+// src/project/plugins.ts
+import { createRequire } from "module";
+import { isAbsolute, join, relative, resolve } from "path";
+import { pathToFileURL } from "url";
+import { loadConfigDirectory } from "@holo-js/config";
+import {
+  loadHoloPluginDefinitions,
+  normalizeHoloPluginDefinition as normalizeKernelPluginDefinition
+} from "@holo-js/kernel";
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function isValidPackageName(packageName) {
+  return /^@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/i.test(packageName) || /^[a-z0-9][a-z0-9._-]*$/i.test(packageName);
+}
+function assertValidPackageName(packageName) {
+  if (!isValidPackageName(packageName)) {
+    throw new Error(`Invalid plugin package name: ${packageName || "(empty)"}.`);
+  }
+}
+function isHoloAppCommand(value) {
+  return isRecord(value) && typeof value.description === "string" && typeof value.run === "function" && (typeof value.name === "undefined" || typeof value.name === "string") && (typeof value.usage === "undefined" || typeof value.usage === "string") && (typeof value.aliases === "undefined" || Array.isArray(value.aliases) && value.aliases.every((alias) => typeof alias === "string"));
+}
+function normalizeStringArray(value) {
+  if (!Array.isArray(value)) {
+    return void 0;
+  }
+  const values = [...new Set(value.map(normalizeString).filter((entry) => Boolean(entry)))];
+  return values.length > 0 ? Object.freeze(values) : void 0;
+}
+function normalizeRequiredStringArray(value) {
+  return Array.isArray(value) && value.length > 0 && value.every((entry) => typeof entry === "string" && entry.trim()) ? Object.freeze(value.map((entry) => entry.trim())) : void 0;
+}
+function normalizeRequiredStringMap(value) {
+  if (!isRecord(value)) {
+    return void 0;
+  }
+  const entries = Object.entries(value).flatMap(([key, entry]) => {
+    return key.trim() && typeof entry === "string" && entry.trim() ? [[key.trim(), entry.trim()]] : [];
+  });
+  if (entries.length !== Object.keys(value).length) {
+    return void 0;
+  }
+  return Object.freeze(Object.fromEntries(entries));
+}
+function normalizeFrameworkTsconfigKind(value) {
+  return value === "nuxt" || value === "next" || value === "sveltekit" ? value : void 0;
+}
+function normalizeHoloPackageArray(value) {
+  const values = normalizeStringArray(value);
+  if (!values) {
+    return void 0;
+  }
+  const holoPackages = values.filter((entry) => entry.startsWith("@holo-js/"));
+  return holoPackages.length > 0 ? Object.freeze(holoPackages) : void 0;
+}
+function normalizeDependencyContributions(value) {
+  if (!isRecord(value)) {
+    return void 0;
+  }
+  const runtime = normalizeStringArray(value.runtime);
+  const holo = normalizeHoloPackageArray(value.holo);
+  if (!runtime && !holo) {
+    return void 0;
+  }
+  return Object.freeze({
+    ...runtime ? { runtime } : {},
+    ...holo ? { holo } : {}
+  });
+}
+function normalizeConfigContributions(value) {
+  if (!isRecord(value)) {
+    return void 0;
+  }
+  const files = normalizeStringArray(value.files);
+  const env = normalizeStringArray(value.env);
+  if (!files && !env) {
+    return void 0;
+  }
+  return Object.freeze({
+    ...files ? { files } : {},
+    ...env ? { env } : {}
+  });
+}
+function normalizeRuntimeMapContributions(value, key) {
+  if (!isRecord(value) || !isRecord(value[key])) {
+    return void 0;
+  }
+  const entries = [];
+  for (const [name, contribution] of Object.entries(value[key])) {
+    if (!isRecord(contribution)) {
+      continue;
+    }
+    const runtime = normalizeString(contribution.runtime);
+    if (runtime) {
+      entries.push([name, { runtime }]);
+    }
+  }
+  const contributions = Object.fromEntries(
+    entries.sort(([left], [right]) => left.localeCompare(right))
+  );
+  return Object.keys(contributions).length > 0 ? Object.freeze({ [key]: contributions }) : void 0;
+}
+function normalizeBroadcastContributions(value) {
+  return normalizeRuntimeMapContributions(value, "drivers");
+}
+function normalizeFrameworkContribution(value) {
+  if (!isRecord(value)) {
+    return void 0;
+  }
+  const id = normalizeString(value.id);
+  const displayName = normalizeString(value.displayName);
+  const detectPackages = normalizeRequiredStringArray(value.detectPackages);
+  const adapterPackage = normalizeString(value.adapterPackage);
+  if (!id || !displayName || !detectPackages || !adapterPackage?.startsWith("@holo-js/")) {
+    return void 0;
+  }
+  const fluxPackage = normalizeString(value.fluxPackage);
+  if (fluxPackage && !fluxPackage.startsWith("@holo-js/")) {
+    return void 0;
+  }
+  if (!isRecord(value.scaffold) || !isRecord(value.runner) || !isRecord(value.capabilities)) {
+    return void 0;
+  }
+  const scaffoldDependencies = normalizeRequiredStringMap(value.scaffold.dependencies);
+  const scaffoldDevDependencies = normalizeRequiredStringMap(value.scaffold.devDependencies);
+  const scaffoldScripts = normalizeRequiredStringMap(value.scaffold.scripts);
+  const lintScript = normalizeString(value.scaffold.lintScript);
+  const typecheckScript = normalizeString(value.scaffold.typecheckScript);
+  const defaultUrl = normalizeString(value.scaffold.defaultUrl);
+  const tsconfig = normalizeFrameworkTsconfigKind(value.scaffold.tsconfig);
+  if (!scaffoldDependencies || !scaffoldDevDependencies || !scaffoldScripts || !lintScript || !typecheckScript || !defaultUrl || !tsconfig) {
+    return void 0;
+  }
+  const commandName = normalizeString(value.runner.commandName);
+  const buildArgs = normalizeRequiredStringArray(value.runner.buildArgs);
+  const start = normalizeRequiredStringArray(value.runner.start);
+  if (!commandName || !buildArgs || !start || typeof value.runner.startUsesFrameworkBinary !== "boolean" || typeof value.runner.preloadNextRuntime !== "boolean" || typeof value.runner.suppressSvelteKitOutput !== "boolean" || typeof value.runner.nextDevServerConflictHandling !== "boolean" || typeof value.capabilities.managedBroadcastAuthRoute !== "boolean") {
+    return void 0;
+  }
+  const sync = normalizeFrameworkSync(value.sync);
+  const descriptor = {
+    id,
+    displayName,
+    detectPackages,
+    adapterPackage,
+    ...fluxPackage ? { fluxPackage } : {},
+    scaffold: {
+      dependencies: scaffoldDependencies,
+      devDependencies: scaffoldDevDependencies,
+      scripts: scaffoldScripts,
+      lintScript,
+      typecheckScript,
+      defaultUrl,
+      tsconfig,
+      ...typeof value.scaffold.vscodeVueHybridMode === "boolean" ? { vscodeVueHybridMode: value.scaffold.vscodeVueHybridMode } : {}
+    },
+    runner: {
+      commandName,
+      buildArgs,
+      start,
+      startUsesFrameworkBinary: value.runner.startUsesFrameworkBinary,
+      preloadNextRuntime: value.runner.preloadNextRuntime,
+      suppressSvelteKitOutput: value.runner.suppressSvelteKitOutput,
+      nextDevServerConflictHandling: value.runner.nextDevServerConflictHandling
+    },
+    capabilities: {
+      managedBroadcastAuthRoute: value.capabilities.managedBroadcastAuthRoute
+    },
+    ...sync ? { sync } : {}
+  };
+  return Object.freeze(descriptor);
+}
+function normalizeFrameworkSync(value) {
+  if (typeof value === "undefined") {
+    return void 0;
+  }
+  if (!isRecord(value) || !isRecord(value.commands)) {
+    return void 0;
+  }
+  const commandMap = value.commands;
+  const errorLabel = normalizeString(value.errorLabel);
+  if (!errorLabel) {
+    return void 0;
+  }
+  const managers = ["npm", "pnpm", "yarn", "bun"];
+  const commands = Object.fromEntries(managers.flatMap((manager) => {
+    const command = commandMap[manager];
+    return Array.isArray(command) && command.length > 0 && command.every((entry) => typeof entry === "string" && entry.trim()) ? [[manager, Object.freeze(command.map((entry) => entry.trim()))]] : [];
+  }));
+  return managers.every((manager) => manager in commands) ? Object.freeze({
+    commands,
+    errorLabel
+  }) : void 0;
+}
+function normalizeSinglePathContribution(value, key) {
+  if (!isRecord(value)) {
+    return void 0;
+  }
+  const entry = normalizeString(value[key]);
+  return entry ? Object.freeze({ [key]: entry }) : void 0;
+}
+function normalizePluginContributions(value) {
+  if (!isRecord(value)) {
+    return void 0;
+  }
+  const dependencies = normalizeDependencyContributions(value.dependencies);
+  const config = normalizeConfigContributions(value.config);
+  const broadcast = normalizeBroadcastContributions(value.broadcast);
+  const cache = normalizeRuntimeMapContributions(value.cache, "drivers");
+  const queue = normalizeRuntimeMapContributions(value.queue, "drivers");
+  const mail = normalizeRuntimeMapContributions(value.mail, "drivers");
+  const notifications = normalizeRuntimeMapContributions(value.notifications, "channels");
+  const runtime = normalizeSinglePathContribution(value.runtime, "boot");
+  const cli = normalizeSinglePathContribution(value.cli, "commands");
+  const migrations = normalizeSinglePathContribution(value.migrations, "publish");
+  const framework = normalizeFrameworkContribution(value.framework);
+  if (!dependencies && !config && !broadcast && !cache && !queue && !mail && !notifications && !runtime && !cli && !migrations && !framework) {
+    return void 0;
+  }
+  return Object.freeze({
+    ...dependencies ? { dependencies } : {},
+    ...config ? { config } : {},
+    ...broadcast ? { broadcast } : {},
+    ...cache ? { cache } : {},
+    ...queue ? { queue } : {},
+    ...mail ? { mail } : {},
+    ...notifications ? { notifications } : {},
+    ...runtime ? { runtime } : {},
+    ...cli ? { cli } : {},
+    ...migrations ? { migrations } : {},
+    ...framework ? { framework } : {}
+  });
+}
+function normalizeHoloPluginDefinition(value) {
+  const candidate = isRecord(value) && isRecord(value.default) ? value.default : isRecord(value) && isRecord(value.plugin) ? value.plugin : value;
+  const definition = normalizeKernelPluginDefinition(value);
+  const contributes = normalizePluginContributions(isRecord(candidate) ? candidate.contributes : void 0);
+  return Object.freeze({
+    id: definition.id,
+    ...definition.name ? { name: definition.name } : {},
+    ...definition.description ? { description: definition.description } : {},
+    ...contributes ? { contributes } : {}
+  });
+}
+async function loadHoloPluginFromPackage(projectRoot, packageName) {
+  assertValidPackageName(packageName);
+  const [loaded] = await loadHoloPluginDefinitions(projectRoot, [packageName], {
+    moduleVersion: String(Date.now())
+  });
+  if (!loaded) throw new Error(`Plugin package failed to load: ${packageName}.`);
+  return {
+    packageName,
+    packageRoot: loaded.packageRoot,
+    entryPath: loaded.entryPath,
+    definition: normalizeHoloPluginDefinition(loaded.definition)
+  };
+}
+function resolvePluginModulePath(projectRoot, plugin, specifier) {
+  const normalizedSpecifier = specifier.trim();
+  if (!normalizedSpecifier) {
+    throw new Error(`Plugin ${plugin.packageName} declared an empty module specifier.`);
+  }
+  if (isAbsolute(normalizedSpecifier)) {
+    throw new Error(`Plugin ${plugin.packageName} module specifier must not be absolute: ${specifier}.`);
+  }
+  if (normalizedSpecifier.startsWith(".")) {
+    const candidate = resolve(plugin.packageRoot, normalizedSpecifier);
+    const relativePath = relative(plugin.packageRoot, candidate);
+    if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
+      throw new Error(`Plugin ${plugin.packageName} module specifier must stay inside the package root: ${specifier}.`);
+    }
+    return {
+      specifier: normalizedSpecifier,
+      path: candidate
+    };
+  }
+  const projectRequire = createRequire(join(projectRoot, "package.json"));
+  return {
+    specifier: normalizedSpecifier,
+    path: projectRequire.resolve(normalizedSpecifier)
+  };
+}
+async function importPluginModule(modulePath) {
+  if (!await pathExists(modulePath.path)) {
+    throw new Error(`Plugin module does not exist: ${modulePath.specifier}.`);
+  }
+  return await import(`${pathToFileURL(modulePath.path).href}?t=${Date.now()}`);
+}
+function normalizePluginCommandExports(moduleValue, plugin, modulePath) {
+  const candidate = isRecord(moduleValue) && Array.isArray(moduleValue.commands) ? moduleValue.commands : isRecord(moduleValue) && typeof moduleValue.default !== "undefined" ? moduleValue.default : moduleValue;
+  const commands = Array.isArray(candidate) ? candidate : [candidate];
+  return Object.freeze(commands.map((command, index) => {
+    if (!isHoloAppCommand(command) || !command.name?.trim()) {
+      throw new Error(`Plugin ${plugin.packageName} command ${modulePath.specifier}#${index + 1} must define name, description, and run().`);
+    }
+    return Object.freeze({
+      ...command,
+      name: command.name.trim()
+    });
+  }));
+}
+async function loadProjectPluginCommands(projectRoot) {
+  const plugins = await resolveProjectPlugins(projectRoot);
+  const commands = [];
+  for (const resolvedPlugin of plugins) {
+    const loadedPlugin = resolvedPlugin.loaded;
+    const commandSpecifier = loadedPlugin?.definition.contributes?.cli?.commands;
+    if (!loadedPlugin || !commandSpecifier) {
+      continue;
+    }
+    const modulePath = resolvePluginModulePath(projectRoot, loadedPlugin, commandSpecifier);
+    const moduleValue = await importPluginModule(modulePath);
+    const pluginCommands = normalizePluginCommandExports(moduleValue, loadedPlugin, modulePath);
+    for (const command of pluginCommands) {
+      commands.push({
+        sourcePath: `${loadedPlugin.packageName}:${modulePath.specifier}`,
+        name: command.name ?? "",
+        aliases: normalizeCommandAliases(command.aliases),
+        description: command.description,
+        usage: command.usage,
+        async load() {
+          return command;
+        }
+      });
+    }
+  }
+  return Object.freeze(commands);
+}
+async function loadProjectPluginFrameworkDescriptors(projectRoot) {
+  const plugins = await resolveProjectPlugins(projectRoot);
+  const descriptors = [];
+  const ids = /* @__PURE__ */ new Set();
+  for (const resolvedPlugin of plugins) {
+    const descriptor = resolvedPlugin.loaded?.definition.contributes?.framework;
+    if (!descriptor) {
+      continue;
+    }
+    if (ids.has(descriptor.id)) {
+      throw new Error(`Duplicate plugin framework descriptor: ${descriptor.id}.`);
+    }
+    ids.add(descriptor.id);
+    descriptors.push(descriptor);
+  }
+  return Object.freeze(descriptors);
+}
+async function readProjectPluginNames(projectRoot) {
+  try {
+    const config = await loadConfigDirectory(projectRoot, {
+      preferCache: false,
+      processEnv: process.env
+    });
+    return Object.freeze([...new Set(config.app.plugins)]);
+  } catch {
+    return await readProjectPluginNamesFromSource(projectRoot);
+  }
+}
+async function readProjectPluginNamesFromSource(projectRoot) {
+  const manifestPath = await resolveFirstExistingPath(projectRoot, APP_CONFIG_FILE_NAMES);
+  if (!manifestPath) {
+    return Object.freeze([]);
+  }
+  const contents = await readTextFile(manifestPath);
+  if (!contents) {
+    return Object.freeze([]);
+  }
+  const pluginsMatch = contents.match(/^\s*plugins:\s*\[([\s\S]*?)\]/m) ?? contents.match(/^\s*"plugins":\s*\[([\s\S]*?)\]/m);
+  if (!pluginsMatch) {
+    return Object.freeze([]);
+  }
+  const pluginBlock = pluginsMatch[1] ?? "";
+  const pluginNames = [...pluginBlock.matchAll(/(['"])(.*?)\1/g)].map((match) => match[2]?.trim() ?? "").filter(Boolean);
+  return Object.freeze([...new Set(pluginNames)]);
+}
+function renderPluginConfigProperty(packageNames) {
+  if (packageNames.length === 0) {
+    return "  plugins: [],\n";
+  }
+  return [
+    "  plugins: [",
+    ...packageNames.map((packageName) => `    ${JSON.stringify(packageName)},`),
+    "  ],",
+    ""
+  ].join("\n");
+}
+function replaceExistingPluginsProperty(contents, packageNames) {
+  const nextProperty = renderPluginConfigProperty(packageNames);
+  const nextContents = contents.replace(/^\s*(?:"plugins"|plugins):\s*\[[\s\S]*?\],?\n/m, nextProperty);
+  return nextContents === contents ? void 0 : nextContents;
+}
+function hasNonLiteralPluginsProperty(contents) {
+  return /^\s*(?:"plugins"|plugins)\s*[:,]/m.test(contents);
+}
+function insertPluginsProperty(contents, packageNames) {
+  if (hasNonLiteralPluginsProperty(contents)) {
+    return void 0;
+  }
+  const nextProperty = renderPluginConfigProperty(packageNames);
+  const pathsMatch = contents.match(/^\s*(?:"paths"|paths):\s*\{/m);
+  if (pathsMatch?.index === void 0) {
+    const openConfigMatch = contents.match(/defineAppConfig\(\{\s*\n/);
+    if (openConfigMatch?.index !== void 0) {
+      const insertIndex = openConfigMatch.index + openConfigMatch[0].length;
+      return `${contents.slice(0, insertIndex)}${nextProperty}${contents.slice(insertIndex)}`;
+    }
+    const emptyConfigMatch = contents.match(/defineAppConfig\(\{\s*\}\)/);
+    return emptyConfigMatch ? contents.replace(emptyConfigMatch[0], `defineAppConfig({
+${nextProperty}})`) : void 0;
+  }
+  return `${contents.slice(0, pathsMatch.index)}${nextProperty}${contents.slice(pathsMatch.index)}`;
+}
+async function writeProjectPluginNames(projectRoot, packageNames) {
+  const manifestPath = await resolveFirstExistingPath(projectRoot, APP_CONFIG_FILE_NAMES);
+  if (!manifestPath) {
+    throw new Error(`Missing config/app.(ts|mts|js|mjs) in ${projectRoot}.`);
+  }
+  const contents = await readTextFile(manifestPath);
+  if (!contents) {
+    throw new Error(`Missing app config: ${manifestPath}.`);
+  }
+  const normalized = [...new Set(packageNames.map((packageName) => packageName.trim()).filter(Boolean))];
+  const nextContents = replaceExistingPluginsProperty(contents, normalized) ?? insertPluginsProperty(contents, normalized);
+  if (!nextContents) {
+    throw new Error(`Unable to update ${manifestPath} automatically. Add plugins: ${JSON.stringify(normalized)} to defineAppConfig().`);
+  }
+  if (nextContents === contents) {
+    return false;
+  }
+  await writeTextFile(manifestPath, nextContents);
+  return true;
+}
+async function activateProjectPlugin(projectRoot, packageName) {
+  assertValidPackageName(packageName);
+  const plugins = await readProjectPluginNames(projectRoot);
+  if (plugins.includes(packageName)) {
+    return false;
+  }
+  return await writeProjectPluginNames(projectRoot, [...plugins, packageName]);
+}
+async function deactivateProjectPlugin(projectRoot, packageName) {
+  assertValidPackageName(packageName);
+  const plugins = await readProjectPluginNames(projectRoot);
+  if (!plugins.includes(packageName)) {
+    return false;
+  }
+  return await writeProjectPluginNames(projectRoot, plugins.filter((plugin) => plugin !== packageName));
+}
+async function resolveProjectPlugins(projectRoot) {
+  const packageNames = await readProjectPluginNames(projectRoot);
+  const resolved = [];
+  for (const packageName of packageNames) {
+    try {
+      resolved.push({
+        packageName,
+        loaded: await loadHoloPluginFromPackage(projectRoot, packageName)
+      });
+    } catch (error) {
+      resolved.push({
+        packageName,
+        error: error instanceof Error && error.message ? error.message : `Failed to load ${packageName}.`
+      });
+    }
+  }
+  return Object.freeze(resolved);
+}
+
+export {
+  normalizeHoloPluginDefinition,
+  loadHoloPluginFromPackage,
+  loadProjectPluginCommands,
+  loadProjectPluginFrameworkDescriptors,
+  readProjectPluginNames,
+  writeProjectPluginNames,
+  activateProjectPlugin,
+  deactivateProjectPlugin,
+  resolveProjectPlugins
+};