@jskit-ai/jskit-cli 0.2.71 → 0.2.73

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

@@ -1,8 +1,20 @@
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { importFreshModuleFromAbsolutePath } from "@jskit-ai/kernel/server/support";
 import {
   ensureArray,
   ensureObject,
   sortStrings
 } from "../../shared/collectionUtils.js";
+import {
+  fileExists
+} from "../appCommands/shared.js";
+import {
+  ensureMobileConfigStub,
+  collectCapacitorShellInstallIssues,
+  ensureAndroidManifestDeepLinks,
+  ensureAndroidNativeShellIdentity
+} from "../mobileShellSupport.js";
 import {
   isHelpToken,
   renderAddCatalogHelp,
@@ -13,6 +25,7 @@ import {
   ensureLocalMainPlacementComponentProvisioning,
   resolveProvisionableLocalPlacementComponentTokens
 } from "./tabLinkItemProvisioning.js";
+import { resolvePackageTemplateRoot } from "../../cliRuntime/packageTemplateResolution.js";
 
 const COMPONENT_TOKEN_PATTERN = /\bcomponentToken\s*:\s*["']([^"']+)["']/g;
 
@@ -35,6 +48,262 @@ function collectPlacementComponentTokensFromManagedRecords(installedPackageRecor
   return sortStrings([...collectedTokens]);
 }
 
+function renderWrappedShellCommand(binaryName, args = [], {
+  maxWidth = 100,
+  continuationIndent = "  "
+} = {}) {
+  const tokens = [String(binaryName || "").trim(), ...ensureArray(args).map((entry) => String(entry || "").trim()).filter(Boolean)];
+  if (tokens.length < 1 || !tokens[0]) {
+    return "$";
+  }
+
+  let currentLine = "$";
+  const renderedLines = [];
+  for (const token of tokens) {
+    const prefix = currentLine === "$" ? " " : " ";
+    if ((`${currentLine}${prefix}${token}`).length <= maxWidth || currentLine === "$") {
+      currentLine = `${currentLine}${prefix}${token}`;
+      continue;
+    }
+
+    renderedLines.push(`${currentLine} \\`);
+    currentLine = `${continuationIndent}${token}`;
+  }
+
+  renderedLines.push(currentLine);
+  return renderedLines.join("\n");
+}
+
+async function runLocalProjectBinary(binaryName, args = [], {
+  appRoot,
+  io,
+  pathModule = path,
+  createCliError,
+  explanation = "",
+  dryRun = false
+} = {}) {
+  const renderedArgs = Array.isArray(args) ? args.join(" ") : "";
+  if (explanation) {
+    io?.stdout?.write(`${explanation}\n`);
+    io?.stdout?.write(`${renderWrappedShellCommand(binaryName, args)}\n`);
+  }
+  if (dryRun === true) {
+    io?.stdout?.write(`[dry-run] ${binaryName}${renderedArgs ? ` ${renderedArgs}` : ""}\n`);
+    return;
+  }
+
+  const localBinDirectory = pathModule.join(appRoot, "node_modules", ".bin");
+  const inheritedPath = String(process.env.PATH || "");
+  const spawnedEnv = {
+    ...process.env,
+    PATH: `${localBinDirectory}${pathModule.delimiter}${inheritedPath}`
+  };
+
+  await new Promise((resolve, reject) => {
+    const child = spawn(binaryName, Array.isArray(args) ? args : [], {
+      cwd: appRoot,
+      env: spawnedEnv,
+      stdio: "inherit"
+    });
+
+    child.on("error", (error) => {
+      if (error?.code === "ENOENT") {
+        reject(
+          createCliError(
+            `Could not find local "${binaryName}" in node_modules/.bin. Re-run the package install after dependencies are installed.`
+          )
+        );
+        return;
+      }
+      reject(error);
+    });
+    child.on("exit", (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(createCliError(`${binaryName} ${args.join(" ")} failed with exit code ${code}.`));
+    });
+  });
+}
+
+async function installAppDependenciesForHook({
+  appRoot,
+  appPackageJson,
+  io,
+  pathModule = path,
+  createCliError,
+  dryRun = false,
+  runDevlinks = false
+} = {}) {
+  const packageScripts =
+    appPackageJson?.scripts && typeof appPackageJson.scripts === "object"
+      ? appPackageJson.scripts
+      : {};
+
+  await runLocalProjectBinary("npm", ["install"], {
+    appRoot,
+    io,
+    pathModule,
+    createCliError,
+    explanation: "[mobile] Installing app dependencies for the mobile shell:",
+    dryRun
+  });
+
+  if (runDevlinks === true && Object.prototype.hasOwnProperty.call(packageScripts, "devlinks")) {
+    await runLocalProjectBinary("npm", ["run", "--if-present", "devlinks"], {
+      appRoot,
+      io,
+      pathModule,
+      createCliError,
+      explanation: "[mobile] Refreshing local JSKIT package links:",
+      dryRun
+    });
+  }
+}
+
+function validateHookResult(result = {}, { packageId = "", hookLabel = "" } = {}) {
+  if (typeof result === "undefined" || result === null) {
+    return {};
+  }
+  if (typeof result !== "object" || Array.isArray(result)) {
+    throw new Error(`${packageId} ${hookLabel} must return an object when it returns a value.`);
+  }
+  return result;
+}
+
+async function loadInstallHook({
+  packageEntry,
+  appRoot,
+  hookSpec,
+  hookLabel = ""
+} = {}) {
+  const entrypoint = String(hookSpec?.entrypoint || "").trim();
+  const exportName = String(hookSpec?.export || "").trim() || "default";
+  if (!entrypoint) {
+    return null;
+  }
+
+  const templateRoot = await resolvePackageTemplateRoot({
+    packageEntry,
+    appRoot
+  });
+  const absoluteEntrypointPath = path.resolve(templateRoot, entrypoint);
+  if (!(await fileExists(absoluteEntrypointPath))) {
+    throw new Error(`${packageEntry.packageId} ${hookLabel} entrypoint not found at ${entrypoint}.`);
+  }
+
+  let moduleNamespace = null;
+  try {
+    moduleNamespace = await importFreshModuleFromAbsolutePath(absoluteEntrypointPath);
+  } catch (error) {
+    throw new Error(
+      `Unable to load ${hookLabel} entrypoint ${entrypoint} for ${packageEntry.packageId}: ${String(error?.message || error || "unknown error")}`
+    );
+  }
+
+  const handler = exportName === "default" ? moduleNamespace?.default : moduleNamespace?.[exportName];
+  if (typeof handler !== "function") {
+    throw new Error(`${packageEntry.packageId} ${hookLabel} export "${exportName}" is not a function.`);
+  }
+
+  return handler;
+}
+
+function createInstallHookHelpers({
+  ctx,
+  appRoot,
+  io,
+  appPackageJson,
+  commandOptions = {}
+} = {}) {
+  return Object.freeze({
+    ensureManagedMobileConfig: async ({ dryRun = false } = {}) =>
+      await ensureMobileConfigStub({
+        ctx,
+        appRoot,
+        packageJson: appPackageJson,
+        dryRun,
+        stdout: io?.stdout
+      }),
+    installAppDependencies: async ({ dryRun = false } = {}) =>
+      await installAppDependenciesForHook({
+        appRoot,
+        appPackageJson,
+        io,
+        pathModule: ctx.path,
+        createCliError: ctx.createCliError,
+        dryRun,
+        runDevlinks: commandOptions.devlinks === true
+      }),
+    runProjectBinary: async (binaryName, args = [], { dryRun = false, explanation = "" } = {}) =>
+      await runLocalProjectBinary(binaryName, args, {
+        appRoot,
+        io,
+        pathModule: ctx.path,
+        createCliError: ctx.createCliError,
+        explanation,
+        dryRun
+      }),
+    collectCapacitorShellInstallIssues: async () =>
+      await collectCapacitorShellInstallIssues({
+        ctx,
+        appRoot
+      }),
+    ensureAndroidManifestDeepLinks: async ({ dryRun = false } = {}) =>
+      await ensureAndroidManifestDeepLinks({
+        ctx,
+        appRoot,
+        dryRun,
+        stdout: io?.stdout
+      }),
+    ensureAndroidNativeShellIdentity: async ({ dryRun = false } = {}) =>
+      await ensureAndroidNativeShellIdentity({
+        ctx,
+        appRoot,
+        dryRun,
+        stdout: io?.stdout
+      }),
+    fileExists
+  });
+}
+
+async function invokeInstallHook({
+  packageEntry,
+  appRoot,
+  hookSpec,
+  hookLabel,
+  hookContext,
+  createCliError
+} = {}) {
+  if (!hookSpec || Object.keys(ensureObject(hookSpec)).length < 1) {
+    return {};
+  }
+
+  const handler = await loadInstallHook({
+    packageEntry,
+    appRoot,
+    hookSpec,
+    hookLabel
+  });
+  if (!handler) {
+    return {};
+  }
+
+  let result = null;
+  try {
+    result = await handler(hookContext);
+  } catch (error) {
+    throw createCliError(
+      `${packageEntry.packageId} ${hookLabel} failed: ${String(error?.message || error || "unknown error")}`
+    );
+  }
+  return validateHookResult(result, {
+    packageId: packageEntry.packageId,
+    hookLabel
+  });
+}
+
 async function runPackageAddCommand(ctx = {}, { positional, options, cwd, io }) {
   const {
     createCliError,
@@ -264,6 +533,7 @@ async function runPackageAddCommand(ctx = {}, { positional, options, cwd, io })
 
   const packagesToInstall = [];
   const resolvedOptionsByPackage = {};
+  const installReasonByPackage = {};
   const reportTemplateFetchStatus = createCatalogFetchStatusReporter(io, {
     enabled: options.json !== true
   });
@@ -274,6 +544,8 @@ async function runPackageAddCommand(ctx = {}, { positional, options, cwd, io })
     const existingInstall = ensureObject(lock.installedPackages[packageId]);
     const existingVersion = String(existingInstall.version || "").trim();
     const isDirectTargetPackage = targetType === "package" && packageId === resolvedTargetPackageId;
+    const hasInstallLifecycleHooks =
+      Object.keys(ensureObject(ensureObject(ensureObject(packageEntry.descriptor).lifecycle).install)).length > 0;
     const packageInlineOptions = targetType === "bundle"
       ? resolveBundleInlineOptionsForPackage(packageEntry, options.inlineOptions)
       : isDirectTargetPackage
@@ -282,6 +554,7 @@ async function runPackageAddCommand(ctx = {}, { positional, options, cwd, io })
     const hasPackageInlineOptions = Object.keys(packageInlineOptions).length > 0;
     const shouldReapplyInstalledPackage =
       (isDirectTargetPackage && (forceReapplyTarget || hasInlineOptions)) ||
+      (isDirectTargetPackage && invocationMode === "add" && hasInstallLifecycleHooks && Boolean(existingVersion)) ||
       (targetType === "bundle" && hasPackageInlineOptions);
     const shouldSkipGenerateDependencyReinstall =
       invocationMode === "generate" &&
@@ -294,6 +567,11 @@ async function runPackageAddCommand(ctx = {}, { positional, options, cwd, io })
       continue;
     }
     packagesToInstall.push(packageId);
+    installReasonByPackage[packageId] = !existingVersion
+      ? "install"
+      : existingVersion === packageEntry.version
+        ? "reapply"
+        : "upgrade";
     const lockEntryOptions = ensureObject(existingInstall.options);
     resolvedOptionsByPackage[packageId] = await resolvePackageOptions(
       packageEntry,
@@ -308,6 +586,95 @@ async function runPackageAddCommand(ctx = {}, { positional, options, cwd, io })
 
   const touchedFiles = new Set();
   const installedPackageRecords = [];
+  const prepareHookWarnings = [];
+  const installHookHelpers = createInstallHookHelpers({
+    ctx,
+    appRoot,
+    io,
+    appPackageJson: packageJson,
+    commandOptions: options
+  });
+
+  for (const packageId of packagesToInstall) {
+    const packageEntry = combinedPackageRegistry.get(packageId);
+    const hookResult = await invokeInstallHook({
+      packageEntry,
+      appRoot,
+      hookSpec: ensureObject(ensureObject(ensureObject(packageEntry.descriptor).lifecycle).install).prepare,
+      hookLabel: "lifecycle.install.prepare",
+      createCliError,
+      hookContext: {
+        appRoot,
+        appPackageJson: packageJson,
+        lock,
+        packageEntry,
+        packageOptions: resolvedOptionsByPackage[packageId],
+        io,
+        dryRun: options.dryRun === true,
+        reason: installReasonByPackage[packageId],
+        skipManagedFinalize: options.forceReapplyTarget === true && options.runNpmInstall !== true,
+        helpers: installHookHelpers
+      }
+    });
+    for (const warning of ensureArray(hookResult.warnings)) {
+      const normalizedWarning = String(warning || "").trim();
+      if (normalizedWarning) {
+        prepareHookWarnings.push(normalizedWarning);
+      }
+    }
+    for (const touchedPath of ensureArray(hookResult.touchedFiles)) {
+      const normalizedPath = String(touchedPath || "").trim();
+      if (normalizedPath) {
+        touchedFiles.add(normalizedPath);
+      }
+    }
+    if (hookResult.stopInstall === true) {
+      if (options.dryRun !== true) {
+        throw createCliError(`${packageEntry.packageId} lifecycle.install.prepare requested stopInstall outside dry-run.`);
+      }
+      const touchedFileList = sortStrings([...touchedFiles]);
+      const installWarnings = sortStrings([...new Set(prepareHookWarnings)]);
+      const stopMessage = String(hookResult.stopMessage || "").trim();
+      if (options.json) {
+        io.stdout.write(`${JSON.stringify({
+          targetType: invocationMode === "generate" ? "generator" : targetType,
+          targetId,
+          resolvedPackages: resolvedPackageIds,
+          touchedFiles: touchedFileList,
+          lockPath: normalizeRelativePath(appRoot, lockPath),
+          externalDependencies,
+          dryRun: options.dryRun,
+          installed: [],
+          warnings: installWarnings,
+          stoppedAfterPrepare: true,
+          message: stopMessage
+        }, null, 2)}\n`);
+      } else {
+        io.stdout.write(
+          `${renderResolvedSummary(
+            `${invocationMode === "generate" ? "Generated with" : targetType === "bundle" ? "Added bundle" : "Added package"}`,
+            targetId,
+            resolvedPackageIds,
+            touchedFileList,
+            appRoot,
+            lockPath,
+            externalDependencies
+          )}\n`
+        );
+        if (installWarnings.length > 0) {
+          io.stdout.write(`Warnings (${installWarnings.length}):\n`);
+          for (const warning of installWarnings) {
+            io.stdout.write(`- ${warning}\n`);
+          }
+        }
+        if (stopMessage) {
+          io.stdout.write(`${stopMessage}\n`);
+        }
+        io.stdout.write("Dry run enabled: no files were written.\n");
+      }
+      return 0;
+    }
+  }
 
   for (const packageId of packagesToInstall) {
     const packageEntry = combinedPackageRegistry.get(packageId);
@@ -319,7 +686,8 @@ async function runPackageAddCommand(ctx = {}, { positional, options, cwd, io })
       lock,
       packageRegistry: combinedPackageRegistry,
       touchedFiles,
-      reportTemplateFetchStatus
+      reportTemplateFetchStatus,
+      dryRun: options.dryRun === true
     });
     installedPackageRecords.push(managedRecord);
   }
@@ -368,15 +736,60 @@ async function runPackageAddCommand(ctx = {}, { positional, options, cwd, io })
       : "Added package";
   const installWarnings = installedPackageRecords
     .flatMap((record) => ensureArray(ensureObject(record).warnings))
+    .concat(prepareHookWarnings)
     .map((value) => String(value || "").trim())
     .filter(Boolean);
+  const finalizeHookRecords = packagesToInstall
+    .map((packageId) => {
+      const packageEntry = combinedPackageRegistry.get(packageId);
+      const finalizeSpec = ensureObject(ensureObject(ensureObject(packageEntry.descriptor).lifecycle).install).finalize;
+      if (Object.keys(ensureObject(finalizeSpec)).length < 1) {
+        return null;
+      }
+      return {
+        packageEntry,
+        hookSpec: finalizeSpec,
+        packageOptions: resolvedOptionsByPackage[packageId],
+        reason: installReasonByPackage[packageId]
+      };
+    })
+    .filter(Boolean)
+    .sort((left, right) => Number(Boolean(right.hookSpec?.managesNpmInstall)) - Number(Boolean(left.hookSpec?.managesNpmInstall)));
+  const managesNpmInstall = finalizeHookRecords.some((record) => record.hookSpec?.managesNpmInstall === true);
 
   if (!options.dryRun) {
     await writeJsonFile(packageJsonPath, packageJson);
     await writeJsonFile(lockPath, lock);
-    if (options.runNpmInstall) {
+    if (options.runNpmInstall && !managesNpmInstall) {
       await runNpmInstall(appRoot, io.stderr);
     }
+    for (const finalizeRecord of finalizeHookRecords) {
+      const hookResult = await invokeInstallHook({
+        packageEntry: finalizeRecord.packageEntry,
+        appRoot,
+        hookSpec: finalizeRecord.hookSpec,
+        hookLabel: "lifecycle.install.finalize",
+        createCliError,
+        hookContext: {
+          appRoot,
+          appPackageJson: packageJson,
+          lock,
+          packageEntry: finalizeRecord.packageEntry,
+          packageOptions: finalizeRecord.packageOptions,
+          io,
+          dryRun: false,
+          reason: finalizeRecord.reason,
+          skipManagedFinalize: options.forceReapplyTarget === true && options.runNpmInstall !== true,
+          helpers: installHookHelpers
+        }
+      });
+      for (const warning of ensureArray(hookResult.warnings)) {
+        const normalizedWarning = String(warning || "").trim();
+        if (normalizedWarning) {
+          installWarnings.push(normalizedWarning);
+        }
+      }
+    }
   }
 
   if (options.json) {

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

@@ -99,7 +99,8 @@ async function runPackageMigrationsCommand(ctx = {}, { positional, options, cwd,
       packageOptions: resolvedOptions,
       appRoot,
       lock,
-      touchedFiles
+      touchedFiles,
+      dryRun: options.dryRun === true
     });
     migratedRecords.push(managedRecord);
     for (const warning of ensureArray(ensureObject(managedRecord).warnings)) {

package/src/server/core/argParser.js

@@ -14,6 +14,7 @@ function parseArgs(argv, { createCliError } = {}) {
       options: {
         dryRun: false,
         runNpmInstall: false,
+        devlinks: false,
         full: false,
         expanded: false,
         details: false,
@@ -39,6 +40,7 @@ function parseArgs(argv, { createCliError } = {}) {
   const options = {
     dryRun: false,
     runNpmInstall: false,
+    devlinks: false,
     full: false,
     expanded: false,
     details: false,
@@ -69,6 +71,10 @@ function parseArgs(argv, { createCliError } = {}) {
       options.runNpmInstall = true;
       continue;
     }
+    if (token === "--devlinks") {
+      options.devlinks = true;
+      continue;
+    }
     if (token === "--full") {
       options.full = true;
       continue;

package/src/server/core/commandCatalog.js

@@ -1,6 +1,7 @@
 const OPTION_FLAG_LABELS = Object.freeze({
   dryRun: "--dry-run",
   runNpmInstall: "--run-npm-install",
+  devlinks: "--devlinks",
   full: "--full",
   expanded: "--expanded",
   details: "--details",
@@ -167,6 +168,32 @@ const COMMAND_DESCRIPTORS = Object.freeze({
     allowedValueOptionNames: Object.freeze([]),
     canDelegateInlineOptions: (positional = []) => Array.isArray(positional) && positional.length > 0
   }),
+  mobile: Object.freeze({
+    command: "mobile",
+    aliases: Object.freeze([]),
+    showInOverview: true,
+    summary: "Run JSKIT-managed mobile-shell helpers.",
+    minimalUse: "jskit mobile add capacitor",
+    parameters: Object.freeze([
+      Object.freeze({
+        name: "<subcommand>",
+        description: "add (more mobile helpers will live here as Stage 1 expands)."
+      })
+    ]),
+    defaults: Object.freeze([
+      "The first supported flow is jskit mobile add capacitor.",
+      "Use jskit mobile <subcommand> help for subcommand-specific usage.",
+      "--dry-run is accepted by jskit mobile add/sync/run/build.",
+      "--devlinks runs npm run --if-present devlinks after install/sync maintenance for development-only relinking."
+    ]),
+    fullUse: "jskit mobile <subcommand> [help] [--dry-run] [--<option> <value>...]",
+    showHelpOnBareInvocation: true,
+    handlerName: "commandMobile",
+    allowedFlagKeys: Object.freeze(["dryRun", "devlinks"]),
+    inlineOptionMode: "delegate",
+    allowedValueOptionNames: Object.freeze([]),
+    canDelegateInlineOptions: (positional = []) => Array.isArray(positional) && positional.length > 0
+  }),
   add: Object.freeze({
     command: "add",
     aliases: Object.freeze([]),
@@ -187,13 +214,14 @@ const COMMAND_DESCRIPTORS = Object.freeze({
       "No npm install runs unless --run-npm-install is passed.",
       "Short ids resolve to @jskit-ai/<id> when available.",
       "Running without args lists bundles and runtime packages.",
-      "Existing matching version is skipped unless options force reapply."
+      "Existing matching version is skipped unless options force reapply.",
+      "--devlinks runs npm run --if-present devlinks after install when the app defines that script."
     ]),
     fullUse:
-      "jskit add <package|bundle> <id> [--<option> <value>...] [--dry-run] [--run-npm-install] [--json] [--verbose]",
+      "jskit add <package|bundle> <id> [--<option> <value>...] [--dry-run] [--run-npm-install] [--devlinks] [--json] [--verbose]",
     showHelpOnBareInvocation: false,
     handlerName: "commandAdd",
-    allowedFlagKeys: Object.freeze(["dryRun", "runNpmInstall", "json", "verbose"]),
+    allowedFlagKeys: Object.freeze(["dryRun", "runNpmInstall", "devlinks", "json", "verbose"]),
     inlineOptionMode: "delegate",
     allowedValueOptionNames: Object.freeze([]),
     canDelegateInlineOptions: canDelegateAddInlineOptions

package/src/server/core/createCommandHandlers.js

@@ -3,6 +3,7 @@ import { createListCommands } from "../commandHandlers/list.js";
 import { createShowCommand } from "../commandHandlers/show.js";
 import { createPackageCommands } from "../commandHandlers/package.js";
 import { createAppCommands } from "../commandHandlers/app.js";
+import { createMobileCommands } from "../commandHandlers/mobile.js";
 import { createHealthCommands } from "../commandHandlers/health.js";
 import { createCompletionCommands } from "../commandHandlers/completion.js";
 
@@ -25,6 +26,7 @@ function createCommandHandlers(deps = {}) {
     commandRemove
   } = createPackageCommands(commandContext);
   const { commandApp } = createAppCommands(commandContext);
+  const { commandMobile } = createMobileCommands(commandContext, { commandAdd });
   const { commandDoctor, commandLintDescriptors } = createHealthCommands(commandContext);
   const { commandCompletion } = createCompletionCommands(commandContext);
 
@@ -35,6 +37,7 @@ function createCommandHandlers(deps = {}) {
     commandCompletion,
     commandShow,
     commandApp,
+    commandMobile,
     commandCreate,
     commandAdd,
     commandGenerate,