@jskit-ai/jskit-cli 0.2.27 → 0.2.29

package/src/server/commandHandlers/packageCommands/position.js

@@ -0,0 +1,103 @@
+import {
+  ensureObject,
+  sortStrings
+} from "../../shared/collectionUtils.js";
+
+async function runPackagePositionCommand(ctx = {}, { positional, options, cwd, io }) {
+  const {
+    createCliError,
+    normalizeRelativePath,
+    resolveAppRootFromCwd,
+    loadPackageRegistry,
+    loadAppLocalPackageRegistry,
+    mergePackageRegistries,
+    loadLockFile,
+    resolveInstalledPackageIdInput,
+    hydratePackageRegistryFromInstalledNodeModules,
+    validateInlineOptionsForPackage,
+    resolvePackageOptions,
+    applyPackagePositioning,
+    writeJsonFile
+  } = ctx;
+
+  const targetType = String(positional[0] || "").trim();
+  const targetId = String(positional[1] || "").trim();
+  if (targetType !== "element" || !targetId) {
+    throw createCliError("position requires: position element <packageId>", { showUsage: true });
+  }
+
+  const appRoot = await resolveAppRootFromCwd(cwd);
+  const packageRegistry = await loadPackageRegistry();
+  const appLocalRegistry = await loadAppLocalPackageRegistry(appRoot);
+  const combinedPackageRegistry = mergePackageRegistries(packageRegistry, appLocalRegistry);
+  const { lockPath, lock } = await loadLockFile(appRoot);
+  const installedPackages = ensureObject(lock.installedPackages);
+  const resolvedTargetId = resolveInstalledPackageIdInput(targetId, installedPackages);
+  if (!resolvedTargetId) {
+    throw createCliError(`Element is not installed: ${targetId}`);
+  }
+
+  await hydratePackageRegistryFromInstalledNodeModules({
+    appRoot,
+    packageRegistry: combinedPackageRegistry,
+    seedPackageIds: [resolvedTargetId]
+  });
+  const packageEntry = combinedPackageRegistry.get(resolvedTargetId);
+  if (!packageEntry) {
+    throw createCliError(
+      `Installed element descriptor not found: ${resolvedTargetId}. Ensure it exists in catalog, app packages/, or node_modules.`
+    );
+  }
+  validateInlineOptionsForPackage(packageEntry, options.inlineOptions);
+
+  const installedRecord = ensureObject(installedPackages[resolvedTargetId]);
+  const resolvedOptions = await resolvePackageOptions(
+    packageEntry,
+    {
+      ...ensureObject(installedRecord.options),
+      ...ensureObject(options.inlineOptions)
+    },
+    io,
+    { appRoot }
+  );
+
+  const touchedFiles = new Set();
+  const positionedRecord = await applyPackagePositioning({
+    packageEntry,
+    packageOptions: resolvedOptions,
+    appRoot,
+    lock,
+    touchedFiles
+  });
+  const touchedFileList = sortStrings([...touchedFiles]);
+
+  if (!options.dryRun) {
+    await writeJsonFile(lockPath, lock);
+  }
+
+  if (options.json) {
+    io.stdout.write(`${JSON.stringify({
+      targetType: "element",
+      elementId: resolvedTargetId,
+      packageId: resolvedTargetId,
+      touchedFiles: touchedFileList,
+      lockPath: normalizeRelativePath(appRoot, lockPath),
+      dryRun: options.dryRun,
+      positioned: positionedRecord
+    }, null, 2)}\n`);
+  } else {
+    io.stdout.write(`Positioned element ${resolvedTargetId}.\n`);
+    io.stdout.write(`Touched files (${touchedFileList.length}):\n`);
+    for (const touchedFile of touchedFileList) {
+      io.stdout.write(`- ${touchedFile}\n`);
+    }
+    io.stdout.write(`Lock file: ${normalizeRelativePath(appRoot, lockPath)}\n`);
+    if (options.dryRun) {
+      io.stdout.write("Dry run enabled: no files were written.\n");
+    }
+  }
+
+  return 0;
+}
+
+export { runPackagePositionCommand };

package/src/server/commandHandlers/packageCommands/remove.js

@@ -0,0 +1,181 @@
+import {
+  ensureArray,
+  ensureObject,
+  sortStrings
+} from "../../shared/collectionUtils.js";
+
+async function runPackageRemoveCommand(ctx = {}, { positional, options, cwd, io }) {
+  const {
+    createCliError,
+    normalizeRelativePath,
+    resolveAppRootFromCwd,
+    loadPackageRegistry,
+    loadAppLocalPackageRegistry,
+    mergePackageRegistries,
+    loadAppPackageJson,
+    loadLockFile,
+    hydratePackageRegistryFromInstalledNodeModules,
+    resolveInstalledPackageIdInput,
+    getInstalledDependents,
+    restorePackageJsonField,
+    path,
+    readFileBufferIfExists,
+    removeEnvValue,
+    writeFile,
+    removeManagedViteProxyEntries,
+    hashBuffer,
+    rm,
+    writeJsonFile,
+    runNpmInstall
+  } = ctx;
+
+  const targetType = String(positional[0] || "").trim();
+  const targetId = String(positional[1] || "").trim();
+  if (targetType !== "package" || !targetId) {
+    throw createCliError("remove requires: remove package <packageId>", { showUsage: true });
+  }
+
+  const appRoot = await resolveAppRootFromCwd(cwd);
+  const packageRegistry = await loadPackageRegistry();
+  const appLocalRegistry = await loadAppLocalPackageRegistry(appRoot);
+  const combinedPackageRegistry = mergePackageRegistries(packageRegistry, appLocalRegistry);
+  const { packageJsonPath, packageJson } = await loadAppPackageJson(appRoot);
+  const { lockPath, lock } = await loadLockFile(appRoot);
+  const installed = ensureObject(lock.installedPackages);
+  await hydratePackageRegistryFromInstalledNodeModules({
+    appRoot,
+    packageRegistry: combinedPackageRegistry,
+    seedPackageIds: Object.keys(installed)
+  });
+  const resolvedTargetId = resolveInstalledPackageIdInput(targetId, installed);
+
+  if (!resolvedTargetId) {
+    throw createCliError(`Package is not installed: ${targetId}`);
+  }
+
+  const dependents = getInstalledDependents(lock, resolvedTargetId, combinedPackageRegistry);
+  if (dependents.length > 0) {
+    throw createCliError(
+      `Cannot remove ${resolvedTargetId}; installed packages depend on it: ${dependents.join(", ")}`
+    );
+  }
+
+  const lockEntry = ensureObject(installed[resolvedTargetId]);
+  const managed = ensureObject(lockEntry.managed);
+  const touchedFiles = new Set();
+
+  const managedPackageJson = ensureObject(managed.packageJson);
+  for (const [dependencyId, managedChange] of Object.entries(ensureObject(managedPackageJson.dependencies))) {
+    if (restorePackageJsonField(packageJson, "dependencies", dependencyId, managedChange)) {
+      touchedFiles.add("package.json");
+    }
+  }
+  for (const [dependencyId, managedChange] of Object.entries(ensureObject(managedPackageJson.devDependencies))) {
+    if (restorePackageJsonField(packageJson, "devDependencies", dependencyId, managedChange)) {
+      touchedFiles.add("package.json");
+    }
+  }
+  for (const [scriptName, managedChange] of Object.entries(ensureObject(managedPackageJson.scripts))) {
+    if (restorePackageJsonField(packageJson, "scripts", scriptName, managedChange)) {
+      touchedFiles.add("package.json");
+    }
+  }
+
+  const managedText = ensureObject(managed.text);
+  for (const change of Object.values(managedText)) {
+    const changeRecord = ensureObject(change);
+    if (String(changeRecord.op || "") !== "upsert-env") {
+      continue;
+    }
+    const relativeFile = String(changeRecord.file || "").trim();
+    if (!relativeFile) {
+      continue;
+    }
+    const absoluteFile = path.join(appRoot, relativeFile);
+    const existing = await readFileBufferIfExists(absoluteFile);
+    if (!existing.exists) {
+      continue;
+    }
+    const updated = removeEnvValue(
+      existing.buffer.toString("utf8"),
+      String(changeRecord.key || ""),
+      String(changeRecord.value || ""),
+      {
+        hadPrevious: Boolean(changeRecord.hadPrevious),
+        previousValue: String(changeRecord.previousValue || "")
+      }
+    );
+    if (updated.changed) {
+      await writeFile(absoluteFile, updated.content, "utf8");
+      touchedFiles.add(normalizeRelativePath(appRoot, absoluteFile));
+    }
+  }
+
+  await removeManagedViteProxyEntries({
+    appRoot,
+    packageId: resolvedTargetId,
+    managedViteChanges: ensureObject(managed.vite),
+    touchedFiles
+  });
+
+  for (const fileChange of ensureArray(managed.files)) {
+    const changeRecord = ensureObject(fileChange);
+    if (changeRecord.preserveOnRemove === true) {
+      continue;
+    }
+    const relativeFile = String(changeRecord.path || "").trim();
+    if (!relativeFile) {
+      continue;
+    }
+    const absoluteFile = path.join(appRoot, relativeFile);
+    const existing = await readFileBufferIfExists(absoluteFile);
+    if (!existing.exists) {
+      continue;
+    }
+    if (hashBuffer(existing.buffer) !== String(changeRecord.hash || "")) {
+      continue;
+    }
+
+    if (changeRecord.hadPrevious) {
+      const previousBuffer = Buffer.from(String(changeRecord.previousContentBase64 || ""), "base64");
+      await writeFile(absoluteFile, previousBuffer);
+    } else {
+      await rm(absoluteFile);
+    }
+    touchedFiles.add(relativeFile);
+  }
+
+  delete installed[resolvedTargetId];
+  const touchedFileList = sortStrings([...touchedFiles]);
+
+  if (!options.dryRun) {
+    await writeJsonFile(packageJsonPath, packageJson);
+    await writeJsonFile(lockPath, lock);
+    if (options.runNpmInstall) {
+      await runNpmInstall(appRoot, io.stderr);
+    }
+  }
+
+  if (options.json) {
+    io.stdout.write(`${JSON.stringify({
+      removedPackage: resolvedTargetId,
+      touchedFiles: touchedFileList,
+      lockPath: normalizeRelativePath(appRoot, lockPath),
+      dryRun: options.dryRun
+    }, null, 2)}\n`);
+  } else {
+    io.stdout.write(`Removed package ${resolvedTargetId}.\n`);
+    io.stdout.write(`Touched files (${touchedFileList.length}):\n`);
+    for (const touchedFile of touchedFileList) {
+      io.stdout.write(`- ${touchedFile}\n`);
+    }
+    io.stdout.write(`Lock file: ${normalizeRelativePath(appRoot, lockPath)}\n`);
+    if (options.dryRun) {
+      io.stdout.write("Dry run enabled: no files were written.\n");
+    }
+  }
+
+  return 0;
+}
+
+export { runPackageRemoveCommand };

package/src/server/commandHandlers/packageCommands/update.js

@@ -0,0 +1,40 @@
+import { ensureObject } from "../../shared/collectionUtils.js";
+
+async function runPackageUpdateCommand(
+  ctx = {},
+  { positional, options, cwd, io },
+  { runCommandAdd }
+) {
+  const {
+    createCliError,
+    resolveAppRootFromCwd,
+    loadLockFile,
+    resolveInstalledPackageIdInput
+  } = ctx;
+
+  const targetType = String(positional[0] || "").trim();
+  const targetId = String(positional[1] || "").trim();
+  if (targetType !== "package" || !targetId) {
+    throw createCliError("update requires: update package <packageId>", { showUsage: true });
+  }
+
+  const appRoot = await resolveAppRootFromCwd(cwd);
+  const { lock } = await loadLockFile(appRoot);
+  const installedPackages = ensureObject(lock.installedPackages);
+  const resolvedTargetId = resolveInstalledPackageIdInput(targetId, installedPackages);
+  if (!resolvedTargetId) {
+    throw createCliError(`Package is not installed: ${targetId}`);
+  }
+
+  return runCommandAdd({
+    positional: ["package", resolvedTargetId],
+    options: {
+      ...options,
+      forceReapplyTarget: true
+    },
+    cwd,
+    io
+  });
+}
+
+export { runPackageUpdateCommand };

package/src/server/commandHandlers/shared.js

@@ -0,0 +1,314 @@
+import { spawn } from "node:child_process";
+import { pathToFileURL } from "node:url";
+import {
+  ensureArray,
+  ensureObject,
+  sortStrings
+} from "../shared/collectionUtils.js";
+
+function createCommandHandlerShared(ctx = {}) {
+  const {
+    createCliError,
+    normalizeRelativePath,
+    resolvePackageIdInput,
+    resolveInstalledNodeModulePackageEntry,
+    path,
+    fileExists
+  } = ctx;
+
+  function renderResolvedSummary(commandType, targetId, resolvedPackageIds, touchedFiles, appRoot, lockPath, externalDependencies) {
+    const lines = [];
+    lines.push(`${commandType} ${targetId}.`);
+    lines.push(`Resolved packages (${resolvedPackageIds.length}):`);
+    for (const packageId of resolvedPackageIds) {
+      lines.push(`- ${packageId}`);
+    }
+
+    if (externalDependencies.length > 0) {
+      lines.push(`External dependencies (${externalDependencies.length}):`);
+      for (const dependencyId of externalDependencies) {
+        lines.push(`- ${dependencyId}`);
+      }
+    }
+
+    lines.push(`Touched files (${touchedFiles.length}):`);
+    for (const touchedFile of touchedFiles) {
+      lines.push(`- ${touchedFile}`);
+    }
+    lines.push(`Lock file: ${normalizeRelativePath(appRoot, lockPath)}`);
+    return lines.join("\n");
+  }
+
+  async function runNpmInstall(appRoot, stderr) {
+    await new Promise((resolve, reject) => {
+      const child = spawn("npm", ["install"], {
+        cwd: appRoot,
+        stdio: "inherit"
+      });
+
+      child.on("error", reject);
+      child.on("exit", (code) => {
+        if (code === 0) {
+          resolve();
+        } else {
+          reject(createCliError(`npm install failed with exit code ${code}.`));
+        }
+      });
+    }).catch((error) => {
+      stderr.write(`npm install failed: ${error.message}\n`);
+      throw error;
+    });
+  }
+
+  function getInstalledDependents(lock, packageId, packageRegistry) {
+    const dependents = [];
+    const installedPackageIds = Object.keys(ensureObject(lock.installedPackages));
+
+    for (const installedId of installedPackageIds) {
+      if (installedId === packageId) {
+        continue;
+      }
+      const packageEntry = packageRegistry.get(installedId);
+      if (!packageEntry) {
+        continue;
+      }
+      const dependencies = ensureArray(packageEntry.descriptor.dependsOn).map((value) => String(value));
+      if (dependencies.includes(packageId)) {
+        dependents.push(installedId);
+      }
+    }
+
+    return sortStrings(dependents);
+  }
+
+  function resolvePackageKind(packageEntry) {
+    const descriptor = ensureObject(packageEntry?.descriptor);
+    const normalizedKind = String(descriptor.kind || "").trim().toLowerCase();
+    if (normalizedKind === "runtime" || normalizedKind === "generator") {
+      return normalizedKind;
+    }
+    const packageId = String(packageEntry?.packageId || descriptor.packageId || "unknown-package").trim();
+    throw createCliError(
+      `Invalid package descriptor for ${packageId}: missing/invalid kind (expected runtime or generator).`
+    );
+  }
+
+  function resolvePackageOptionNames(packageEntry) {
+    const optionSchemas = ensureObject(packageEntry?.descriptor?.options);
+    return Object.keys(optionSchemas);
+  }
+
+  function resolveBundleInlineOptionsForPackage(packageEntry, inlineOptions) {
+    const allowedOptionNames = new Set(resolvePackageOptionNames(packageEntry));
+    const resolved = {};
+
+    for (const [optionName, optionValue] of Object.entries(ensureObject(inlineOptions))) {
+      if (!allowedOptionNames.has(optionName)) {
+        continue;
+      }
+      resolved[optionName] = String(optionValue || "").trim();
+    }
+
+    return resolved;
+  }
+
+  function resolveGeneratorSubcommands(packageEntry) {
+    const descriptor = ensureObject(packageEntry?.descriptor);
+    const metadata = ensureObject(descriptor.metadata);
+    return ensureObject(metadata.generatorSubcommands || descriptor.generatorSubcommands);
+  }
+
+  function resolveGeneratorSubcommandDefinition(packageEntry, subcommandName) {
+    const subcommands = resolveGeneratorSubcommands(packageEntry);
+    const definition = ensureObject(subcommands[subcommandName]);
+    const entrypoint = String(definition.entrypoint || "").trim();
+    const exportName = String(definition.export || "runGeneratorSubcommand").trim() || "runGeneratorSubcommand";
+    if (!entrypoint) {
+      throw createCliError(
+        `Generator ${packageEntry?.packageId || "unknown"} does not define subcommand "${subcommandName}".`
+      );
+    }
+
+    return Object.freeze({
+      entrypoint,
+      exportName
+    });
+  }
+
+  function hasGeneratorSubcommandDefinition(packageEntry, subcommandName) {
+    const subcommands = resolveGeneratorSubcommands(packageEntry);
+    const normalizedSubcommandName = String(subcommandName || "").trim();
+    if (!normalizedSubcommandName) {
+      return false;
+    }
+
+    const definition = ensureObject(subcommands[normalizedSubcommandName]);
+    return String(definition.entrypoint || "").trim().length > 0;
+  }
+
+  function resolveGeneratorPrimarySubcommand(packageEntry) {
+    const descriptor = ensureObject(packageEntry?.descriptor);
+    const metadata = ensureObject(descriptor.metadata);
+    return String(metadata.generatorPrimarySubcommand || descriptor.generatorPrimarySubcommand || "")
+      .trim()
+      .toLowerCase();
+  }
+
+  async function resolvePackageIdFromRegistryOrNodeModules({
+    appRoot,
+    packageRegistry,
+    packageIdInput
+  }) {
+    let resolvedPackageId = resolvePackageIdInput(packageIdInput, packageRegistry);
+    const packageIdForNodeModulesLookup = resolvedPackageId || packageIdInput;
+    const installedNodeModuleEntry = await resolveInstalledNodeModulePackageEntry({
+      appRoot,
+      packageId: packageIdForNodeModulesLookup
+    });
+    if (installedNodeModuleEntry) {
+      packageRegistry.set(installedNodeModuleEntry.packageId, installedNodeModuleEntry);
+      resolvedPackageId = installedNodeModuleEntry.packageId;
+    }
+
+    return resolvedPackageId;
+  }
+
+  async function runGeneratorSubcommand({
+    packageEntry,
+    subcommandName,
+    subcommandArgs = [],
+    inlineOptions = {},
+    appRoot,
+    io,
+    dryRun = false,
+    json = false
+  }) {
+    const normalizedSubcommandName = String(subcommandName || "").trim();
+    if (!normalizedSubcommandName) {
+      throw createCliError("Generator subcommand name is required.");
+    }
+
+    const packageId = String(packageEntry?.packageId || "").trim();
+    const packageRoot = String(packageEntry?.rootDir || "").trim();
+    if (!packageRoot) {
+      throw createCliError(`Could not resolve package root for generator ${packageId || "<unknown>"}.`);
+    }
+
+    const definition = resolveGeneratorSubcommandDefinition(packageEntry, normalizedSubcommandName);
+    const entrypointPath = path.resolve(packageRoot, definition.entrypoint);
+    if (!(await fileExists(entrypointPath))) {
+      throw createCliError(
+        `Generator subcommand entrypoint not found: ${normalizeRelativePath(appRoot, entrypointPath)}`
+      );
+    }
+
+    let moduleNamespace = null;
+    try {
+      moduleNamespace = await import(`${pathToFileURL(entrypointPath).href}?t=${Date.now()}_${Math.random()}`);
+    } catch (error) {
+      throw createCliError(
+        `Unable to load generator subcommand entrypoint ${normalizeRelativePath(appRoot, entrypointPath)}: ${String(error?.message || error || "unknown error")}`
+      );
+    }
+
+    const handler =
+      (typeof moduleNamespace?.[definition.exportName] === "function" && moduleNamespace[definition.exportName]) ||
+      (typeof moduleNamespace?.default === "function" && moduleNamespace.default) ||
+      null;
+    if (!handler) {
+      throw createCliError(
+        `Generator subcommand "${normalizedSubcommandName}" export "${definition.exportName}" was not found in ${normalizeRelativePath(appRoot, entrypointPath)}.`
+      );
+    }
+
+    const result = await handler({
+      appRoot,
+      packageId,
+      subcommand: normalizedSubcommandName,
+      args: ensureArray(subcommandArgs).map((value) => String(value || "")),
+      options: ensureObject(inlineOptions),
+      dryRun: dryRun === true
+    });
+    const payload = ensureObject(result);
+    const touchedFiles = sortStrings(
+      ensureArray(payload.touchedFiles).map((value) => String(value || "").trim()).filter(Boolean)
+    );
+    const summary = String(payload.summary || "").trim();
+
+    if (json) {
+      io.stdout.write(`${JSON.stringify({
+        targetType: "generator-subcommand",
+        packageId,
+        subcommand: normalizedSubcommandName,
+        touchedFiles,
+        summary,
+        dryRun: dryRun === true
+      }, null, 2)}\n`);
+    } else {
+      io.stdout.write(`Generated with ${packageId} (${normalizedSubcommandName}).\n`);
+      if (summary) {
+        io.stdout.write(`${summary}\n`);
+      }
+      io.stdout.write(`Touched files (${touchedFiles.length}):\n`);
+      for (const touchedFile of touchedFiles) {
+        io.stdout.write(`- ${touchedFile}\n`);
+      }
+      if (dryRun) {
+        io.stdout.write("Dry run enabled: no files were written.\n");
+      }
+    }
+
+    return 0;
+  }
+
+  function validateInlineOptionsForBundle({
+    bundleId,
+    inlineOptions,
+    packageIds,
+    packageRegistry
+  }) {
+    const providedOptionNames = Object.keys(ensureObject(inlineOptions));
+    if (providedOptionNames.length < 1) {
+      return;
+    }
+
+    const allowedOptionNames = new Set();
+    for (const packageId of ensureArray(packageIds).map((value) => String(value || "").trim()).filter(Boolean)) {
+      const packageEntry = packageRegistry.get(packageId);
+      if (!packageEntry) {
+        continue;
+      }
+      for (const optionName of resolvePackageOptionNames(packageEntry)) {
+        allowedOptionNames.add(optionName);
+      }
+    }
+
+    const unknownOptionNames = providedOptionNames.filter((optionName) => !allowedOptionNames.has(optionName));
+    if (unknownOptionNames.length < 1) {
+      return;
+    }
+
+    const sortedUnknown = sortStrings(unknownOptionNames);
+    const sortedAllowed = sortStrings([...allowedOptionNames]);
+    const suffix = sortedAllowed.length > 0
+      ? ` Allowed options: ${sortedAllowed.join(", ")}.`
+      : " This bundle does not accept inline options.";
+    throw createCliError(`Unknown option(s) for bundle ${bundleId}: ${sortedUnknown.join(", ")}.${suffix}`);
+  }
+
+  return {
+    renderResolvedSummary,
+    runNpmInstall,
+    getInstalledDependents,
+    resolvePackageKind,
+    resolveBundleInlineOptionsForPackage,
+    resolveGeneratorSubcommandDefinition,
+    hasGeneratorSubcommandDefinition,
+    resolveGeneratorPrimarySubcommand,
+    resolvePackageIdFromRegistryOrNodeModules,
+    runGeneratorSubcommand,
+    validateInlineOptionsForBundle
+  };
+}
+
+export { createCommandHandlerShared };