@jskit-ai/jskit-cli 0.2.26 → 0.2.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.26",
+  "version": "0.2.28",
   "description": "Bundle and package orchestration CLI for JSKIT apps.",
   "type": "module",
   "files": [
@@ -20,7 +20,8 @@
     "test": "node --test"
   },
   "dependencies": {
-    "@jskit-ai/jskit-catalog": "0.1.26"
+    "@jskit-ai/jskit-catalog": "0.1.28",
+    "@jskit-ai/kernel": "0.1.20"
   },
   "engines": {
     "node": "20.x"

package/src/server/cliRuntime/appState.js

@@ -0,0 +1,226 @@
+import path from "node:path";
+import process from "node:process";
+import { createCliError } from "../shared/cliError.js";
+import { ensureObject } from "../shared/collectionUtils.js";
+import { escapeRegExp } from "../shared/optionInterpolation.js";
+import {
+  fileExists,
+  readJsonFile,
+  writeJsonFile
+} from "./ioAndMigrations.js";
+
+const LOCK_RELATIVE_PATH = ".jskit/lock.json";
+const LOCK_VERSION = 1;
+
+async function resolveAppRootFromCwd(cwd) {
+  const startDirectory = path.resolve(String(cwd || process.cwd()));
+  let currentDirectory = startDirectory;
+
+  while (true) {
+    const packageJsonPath = path.join(currentDirectory, "package.json");
+    if (await fileExists(packageJsonPath)) {
+      return currentDirectory;
+    }
+
+    const parentDirectory = path.dirname(currentDirectory);
+    if (parentDirectory === currentDirectory) {
+      throw createCliError(
+        `Could not locate package.json starting from ${startDirectory}. Run jskit from an app directory (or a child directory of one).`
+      );
+    }
+    currentDirectory = parentDirectory;
+  }
+}
+
+async function loadAppPackageJson(appRoot) {
+  const packageJsonPath = path.join(appRoot, "package.json");
+  const packageJson = await readJsonFile(packageJsonPath);
+  return {
+    packageJsonPath,
+    packageJson
+  };
+}
+
+function createDefaultLock() {
+  return {
+    lockVersion: LOCK_VERSION,
+    installedPackages: {}
+  };
+}
+
+async function loadLockFile(appRoot) {
+  const lockPath = path.join(appRoot, LOCK_RELATIVE_PATH);
+  if (!(await fileExists(lockPath))) {
+    return {
+      lockPath,
+      lock: createDefaultLock()
+    };
+  }
+
+  const lock = await readJsonFile(lockPath);
+  const installedPackages = ensureObject(lock?.installedPackages);
+  const lockVersion = Number(lock?.lockVersion);
+  return {
+    lockPath,
+    lock: {
+      lockVersion: Number.isFinite(lockVersion) && lockVersion > 0 ? lockVersion : LOCK_VERSION,
+      installedPackages
+    }
+  };
+}
+
+function createManagedPackageJsonChange(hadPrevious, previousValue, value) {
+  return {
+    hadPrevious: Boolean(hadPrevious),
+    previousValue: hadPrevious ? String(previousValue) : "",
+    value: String(value)
+  };
+}
+
+function ensurePackageJsonSection(packageJson, sectionName) {
+  const sectionValue = ensureObject(packageJson[sectionName]);
+  packageJson[sectionName] = sectionValue;
+  return sectionValue;
+}
+
+function applyPackageJsonField(packageJson, sectionName, key, value) {
+  const section = ensurePackageJsonSection(packageJson, sectionName);
+  const nextValue = String(value);
+  const hadPrevious = Object.prototype.hasOwnProperty.call(section, key);
+  const previousValue = hadPrevious ? String(section[key]) : "";
+  const changed = !hadPrevious || previousValue !== nextValue;
+  section[key] = nextValue;
+  return {
+    changed,
+    managed: createManagedPackageJsonChange(hadPrevious, previousValue, nextValue)
+  };
+}
+
+function removePackageJsonField(packageJson, sectionName, key) {
+  const section = ensureObject(packageJson[sectionName]);
+  if (!Object.prototype.hasOwnProperty.call(section, key)) {
+    return false;
+  }
+  delete section[key];
+  if (Object.keys(section).length < 1) {
+    delete packageJson[sectionName];
+  }
+  return true;
+}
+
+function restorePackageJsonField(packageJson, sectionName, key, managedChange) {
+  const section = ensurePackageJsonSection(packageJson, sectionName);
+  const currentValue = Object.prototype.hasOwnProperty.call(section, key) ? String(section[key]) : "";
+  if (currentValue !== String(managedChange?.value || "")) {
+    return false;
+  }
+
+  if (managedChange?.hadPrevious) {
+    section[key] = String(managedChange.previousValue || "");
+  } else {
+    delete section[key];
+  }
+  return true;
+}
+
+function parseEnvLineValue(line, key) {
+  const pattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`);
+  if (!pattern.test(line)) {
+    return null;
+  }
+  const index = line.indexOf("=");
+  if (index === -1) {
+    return "";
+  }
+  return line.slice(index + 1);
+}
+
+function upsertEnvValue(content, key, value) {
+  const lines = String(content || "").split(/\r?\n/);
+  const lookupPattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`);
+  let index = -1;
+
+  for (let cursor = 0; cursor < lines.length; cursor += 1) {
+    if (lookupPattern.test(lines[cursor])) {
+      index = cursor;
+      break;
+    }
+  }
+
+  const hadPrevious = index >= 0;
+  const previousValue = hadPrevious ? String(parseEnvLineValue(lines[index], key) || "") : "";
+  const nextLine = `${key}=${value}`;
+
+  if (hadPrevious) {
+    lines[index] = nextLine;
+  } else {
+    if (lines.length === 1 && lines[0] === "") {
+      lines[0] = nextLine;
+    } else {
+      lines.push(nextLine);
+    }
+  }
+
+  const normalized = `${lines.join("\n").replace(/\n+$/, "")}\n`;
+  return {
+    hadPrevious,
+    previousValue,
+    content: normalized
+  };
+}
+
+function removeEnvValue(content, key, expectedValue, previous) {
+  const lines = String(content || "").split(/\r?\n/);
+  const lookupPattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`);
+  let index = -1;
+
+  for (let cursor = 0; cursor < lines.length; cursor += 1) {
+    if (lookupPattern.test(lines[cursor])) {
+      index = cursor;
+      break;
+    }
+  }
+
+  if (index < 0) {
+    return {
+      changed: false,
+      content: content
+    };
+  }
+
+  const currentValue = String(parseEnvLineValue(lines[index], key) || "");
+  if (currentValue !== String(expectedValue || "")) {
+    return {
+      changed: false,
+      content: content
+    };
+  }
+
+  if (previous?.hadPrevious) {
+    lines[index] = `${key}=${String(previous.previousValue || "")}`;
+  } else {
+    lines.splice(index, 1);
+  }
+
+  const normalized = `${lines.join("\n").replace(/\n+$/, "")}\n`;
+  return {
+    changed: true,
+    content: normalized
+  };
+}
+
+export {
+  resolveAppRootFromCwd,
+  loadAppPackageJson,
+  createDefaultLock,
+  loadLockFile,
+  createManagedPackageJsonChange,
+  ensurePackageJsonSection,
+  applyPackageJsonField,
+  removePackageJsonField,
+  restorePackageJsonField,
+  parseEnvLineValue,
+  upsertEnvValue,
+  removeEnvValue,
+  writeJsonFile
+};

package/src/server/cliRuntime/capabilitySupport.js

@@ -0,0 +1,194 @@
+import { createCliError } from "../shared/cliError.js";
+import {
+  ensureArray,
+  ensureObject,
+  sortStrings
+} from "../shared/collectionUtils.js";
+
+const BUILTIN_CAPABILITY_PROVIDERS = Object.freeze({
+  "runtime.actions": Object.freeze(["@jskit-ai/kernel"])
+});
+
+function listDeclaredCapabilities(capabilitiesSection, fieldName) {
+  const section = ensureObject(capabilitiesSection);
+  const source = ensureArray(section[fieldName]);
+  const normalized = [];
+  const seen = new Set();
+  for (const value of source) {
+    const capabilityId = String(value || "").trim();
+    if (!capabilityId || seen.has(capabilityId)) {
+      continue;
+    }
+    seen.add(capabilityId);
+    normalized.push(capabilityId);
+  }
+  return normalized;
+}
+
+function buildCapabilityGraph(packageRegistry) {
+  const graph = new Map();
+  const ensureNode = (capabilityId) => {
+    if (!graph.has(capabilityId)) {
+      graph.set(capabilityId, {
+        providers: new Set(),
+        requirers: new Set()
+      });
+    }
+    return graph.get(capabilityId);
+  };
+
+  for (const [packageId, packageEntry] of packageRegistry.entries()) {
+    const capabilities = ensureObject(packageEntry?.descriptor?.capabilities);
+    for (const capabilityId of listDeclaredCapabilities(capabilities, "provides")) {
+      ensureNode(capabilityId).providers.add(packageId);
+    }
+    for (const capabilityId of listDeclaredCapabilities(capabilities, "requires")) {
+      ensureNode(capabilityId).requirers.add(packageId);
+    }
+  }
+
+  for (const [capabilityId, providers] of Object.entries(BUILTIN_CAPABILITY_PROVIDERS)) {
+    const node = ensureNode(capabilityId);
+    for (const providerId of ensureArray(providers).map((value) => String(value || "").trim()).filter(Boolean)) {
+      node.providers.add(providerId);
+    }
+  }
+
+  const normalizedGraph = new Map();
+  for (const [capabilityId, node] of graph.entries()) {
+    normalizedGraph.set(capabilityId, {
+      providers: sortStrings([...node.providers]),
+      requirers: sortStrings([...node.requirers])
+    });
+  }
+  return normalizedGraph;
+}
+
+function createCapabilityPackageDetail(packageId, packageRegistry) {
+  const packageEntry = packageRegistry.get(packageId);
+  return {
+    packageId,
+    version: String(packageEntry?.version || packageEntry?.descriptor?.version || "").trim(),
+    descriptorPath: String(packageEntry?.descriptorRelativePath || "").trim()
+  };
+}
+
+function buildCapabilityDetailsForPackage({ packageRegistry, packageId, dependsOn = [], provides = [], requires = [] }) {
+  const graph = buildCapabilityGraph(packageRegistry);
+  const dependsOnSet = new Set(ensureArray(dependsOn).map((value) => String(value || "").trim()).filter(Boolean));
+
+  function buildCapabilityRecord(capabilityId) {
+    const node = graph.get(capabilityId) || {
+      providers: [],
+      requirers: []
+    };
+    const providers = sortStrings(ensureArray(node.providers));
+    const requirers = sortStrings(ensureArray(node.requirers));
+    const providersInDependsOn = providers.filter((providerId) => dependsOnSet.has(providerId));
+    return {
+      capabilityId,
+      providers,
+      requirers,
+      providersInDependsOn,
+      providerDetails: providers.map((providerId) => createCapabilityPackageDetail(providerId, packageRegistry)),
+      requirerDetails: requirers.map((requirerId) => createCapabilityPackageDetail(requirerId, packageRegistry)),
+      isProvidedByCurrentPackage: providers.includes(packageId),
+      isRequiredByCurrentPackage: requirers.includes(packageId)
+    };
+  }
+
+  return {
+    provides: ensureArray(provides).map((capabilityId) => buildCapabilityRecord(capabilityId)),
+    requires: ensureArray(requires).map((capabilityId) => buildCapabilityRecord(capabilityId))
+  };
+}
+
+function collectPlannedCapabilityIssues(plannedPackageIds, packageRegistry) {
+  const selectedPackageIds = sortStrings(
+    [...new Set(ensureArray(plannedPackageIds).map((value) => String(value || "").trim()).filter(Boolean))]
+  );
+  const selectedPackageSet = new Set(selectedPackageIds);
+  const providersByCapability = new Map();
+
+  for (const [capabilityId, providers] of Object.entries(BUILTIN_CAPABILITY_PROVIDERS)) {
+    if (!providersByCapability.has(capabilityId)) {
+      providersByCapability.set(capabilityId, new Set());
+    }
+    for (const providerId of ensureArray(providers).map((value) => String(value || "").trim()).filter(Boolean)) {
+      providersByCapability.get(capabilityId).add(providerId);
+    }
+  }
+
+  for (const packageId of selectedPackageIds) {
+    const packageEntry = packageRegistry.get(packageId);
+    if (!packageEntry) {
+      continue;
+    }
+    const provides = listDeclaredCapabilities(packageEntry.descriptor.capabilities, "provides");
+    for (const capabilityId of provides) {
+      if (!providersByCapability.has(capabilityId)) {
+        providersByCapability.set(capabilityId, new Set());
+      }
+      providersByCapability.get(capabilityId).add(packageId);
+    }
+  }
+
+  const issues = [];
+  for (const packageId of selectedPackageIds) {
+    const packageEntry = packageRegistry.get(packageId);
+    if (!packageEntry) {
+      continue;
+    }
+    const requires = listDeclaredCapabilities(packageEntry.descriptor.capabilities, "requires");
+    for (const capabilityId of requires) {
+      const selectedProviders = providersByCapability.get(capabilityId);
+      if (selectedProviders && selectedProviders.size > 0) {
+        continue;
+      }
+
+      const availableProviders = [];
+      for (const [candidatePackageId, candidatePackageEntry] of packageRegistry.entries()) {
+        if (selectedPackageSet.has(candidatePackageId)) {
+          continue;
+        }
+        const candidateProvides = listDeclaredCapabilities(candidatePackageEntry.descriptor.capabilities, "provides");
+        if (candidateProvides.includes(capabilityId)) {
+          availableProviders.push(candidatePackageId);
+        }
+      }
+
+      issues.push({
+        packageId,
+        capabilityId,
+        availableProviders: sortStrings(availableProviders)
+      });
+    }
+  }
+
+  return issues;
+}
+
+function validatePlannedCapabilityClosure(plannedPackageIds, packageRegistry, actionLabel) {
+  const issues = collectPlannedCapabilityIssues(plannedPackageIds, packageRegistry);
+  if (issues.length === 0) {
+    return;
+  }
+
+  const lines = [`Cannot ${actionLabel}: capability requirements are not satisfied.`];
+  for (const issue of issues) {
+    const providersHint = issue.availableProviders.length > 0
+      ? ` Available providers: ${issue.availableProviders.join(", ")}.`
+      : "";
+    lines.push(
+      `- ${issue.packageId} requires capability ${issue.capabilityId}, but no selected package provides it.${providersHint}`
+    );
+  }
+
+  throw createCliError(lines.join("\n"));
+}
+
+export {
+  listDeclaredCapabilities,
+  buildCapabilityDetailsForPackage,
+  validatePlannedCapabilityClosure
+};

package/src/server/cliRuntime/descriptorValidation.js

@@ -0,0 +1,150 @@
+import { createCliError } from "../shared/cliError.js";
+import {
+  ensureArray,
+  ensureObject
+} from "../shared/collectionUtils.js";
+import { normalizeFileMutationRecord } from "./mutationWhen.js";
+
+const PACKAGE_KIND_RUNTIME = "runtime";
+const PACKAGE_KIND_GENERATOR = "generator";
+const PACKAGE_KINDS = Object.freeze([PACKAGE_KIND_RUNTIME, PACKAGE_KIND_GENERATOR]);
+
+function normalizePackageKind(rawValue, descriptorPath) {
+  const normalized = String(rawValue || "").trim().toLowerCase();
+  if (!normalized) {
+    throw createCliError(
+      `Invalid package descriptor at ${descriptorPath}: missing kind (expected ${PACKAGE_KINDS.join(" | ")}).`
+    );
+  }
+  if (!PACKAGE_KINDS.includes(normalized)) {
+    throw createCliError(
+      `Invalid package descriptor at ${descriptorPath}: kind must be one of: ${PACKAGE_KINDS.join(", ")}.`
+    );
+  }
+  return normalized;
+}
+
+function validateInstallMigrationMutationShape(descriptor, descriptorPath) {
+  const packageId = String(ensureObject(descriptor).packageId || "").trim() || "unknown-package";
+  const mutations = ensureObject(ensureObject(descriptor).mutations);
+  const files = ensureArray(mutations.files);
+  for (const fileMutation of files) {
+    const normalized = normalizeFileMutationRecord(fileMutation);
+    if (normalized.op !== "install-migration") {
+      continue;
+    }
+    if (!normalized.from) {
+      throw createCliError(
+        `Invalid package descriptor at ${descriptorPath}: install-migration in ${packageId} requires "from".`
+      );
+    }
+    if (!normalized.id) {
+      throw createCliError(
+        `Invalid package descriptor at ${descriptorPath}: install-migration in ${packageId} requires "id".`
+      );
+    }
+  }
+}
+
+function validatePackageDescriptorShape(descriptor, descriptorPath) {
+  const normalized = ensureObject(descriptor);
+  const packageId = String(normalized.packageId || "").trim();
+  const version = String(normalized.version || "").trim();
+
+  if (!packageId.startsWith("@jskit-ai/")) {
+    throw createCliError(`Invalid package descriptor at ${descriptorPath}: packageId must start with @jskit-ai/.`);
+  }
+  if (!version) {
+    throw createCliError(`Invalid package descriptor at ${descriptorPath}: missing version.`);
+  }
+
+  const runtime = ensureObject(normalized.runtime);
+  const server = ensureObject(runtime.server);
+  const client = ensureObject(runtime.client);
+  const hasServerProviders = Array.isArray(server.providers);
+  const hasClientProviders = Array.isArray(client.providers);
+  if (!hasServerProviders && !hasClientProviders) {
+    throw createCliError(
+      `Invalid package descriptor at ${descriptorPath}: runtime.server.providers or runtime.client.providers must be declared.`
+    );
+  }
+
+  validateInstallMigrationMutationShape(normalized, descriptorPath);
+
+  return {
+    ...normalized,
+    kind: normalizePackageKind(normalized.kind, descriptorPath)
+  };
+}
+
+function isGeneratorPackageEntry(packageEntry) {
+  const descriptor = ensureObject(packageEntry?.descriptor);
+  return String(descriptor.kind || "").trim().toLowerCase() === PACKAGE_KIND_GENERATOR;
+}
+
+function validateAppLocalPackageDescriptorShape(descriptor, descriptorPath, { expectedPackageId = "", fallbackVersion = "" } = {}) {
+  const normalized = ensureObject(descriptor);
+  const packageId = String(normalized.packageId || "").trim();
+  const version = String(normalized.version || "").trim() || String(fallbackVersion || "").trim();
+
+  if (!packageId) {
+    throw createCliError(`Invalid app-local package descriptor at ${descriptorPath}: missing packageId.`);
+  }
+  if (expectedPackageId && packageId !== expectedPackageId) {
+    throw createCliError(
+      `Descriptor/package mismatch at ${descriptorPath}: package.descriptor.mjs has ${packageId} but package.json has ${expectedPackageId}.`
+    );
+  }
+  if (!version) {
+    throw createCliError(`Invalid app-local package descriptor at ${descriptorPath}: missing version.`);
+  }
+
+  validateInstallMigrationMutationShape(normalized, descriptorPath);
+
+  return {
+    ...normalized,
+    packageId,
+    version,
+    kind: normalizePackageKind(normalized.kind, descriptorPath)
+  };
+}
+
+function createPackageEntry({
+  packageId,
+  version,
+  descriptor,
+  rootDir = "",
+  relativeDir = "",
+  descriptorRelativePath = "",
+  packageJson = {},
+  sourceType = "",
+  source = {}
+}) {
+  const normalizedSourceType = String(sourceType || "").trim() || "package";
+  const normalizedDescriptorPath = String(descriptorRelativePath || "").trim();
+  const normalizedSource = {
+    type: normalizedSourceType,
+    ...ensureObject(source)
+  };
+  if (!normalizedSource.descriptorPath && normalizedDescriptorPath) {
+    normalizedSource.descriptorPath = normalizedDescriptorPath;
+  }
+  return {
+    packageId: String(packageId || "").trim(),
+    version: String(version || "").trim(),
+    descriptor: ensureObject(descriptor),
+    rootDir: String(rootDir || "").trim(),
+    relativeDir: String(relativeDir || "").trim(),
+    descriptorRelativePath: normalizedDescriptorPath,
+    packageJson: ensureObject(packageJson),
+    sourceType: normalizedSourceType,
+    source: normalizedSource
+  };
+}
+
+export {
+  validatePackageDescriptorShape,
+  validateAppLocalPackageDescriptorShape,
+  createPackageEntry,
+  isGeneratorPackageEntry
+};