@jskit-ai/jskit-cli 0.2.128 → 0.2.130

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.128",
+  "version": "0.2.130",
   "description": "Bundle and package orchestration CLI for JSKIT apps.",
   "type": "module",
   "files": [
@@ -20,11 +20,12 @@
     "test": "node --test"
   },
   "dependencies": {
-    "@jskit-ai/jskit-catalog": "0.1.123",
-    "@jskit-ai/kernel": "0.1.116",
-    "@jskit-ai/shell-web": "0.1.115",
+    "@jskit-ai/jskit-catalog": "0.1.125",
+    "@jskit-ai/kernel": "0.1.118",
+    "@jskit-ai/shell-web": "0.1.116",
     "@vue/compiler-sfc": "^3.5.29",
-    "ts-morph": "^28.0.0"
+    "ts-morph": "^28.0.0",
+    "yaml": "^2.8.3"
   },
   "engines": {
     "node": ">=20 <23"

package/src/server/cliRuntime/appState.js

@@ -66,7 +66,8 @@ async function loadAppPackageJson(appRoot) {
 function createDefaultLock() {
   return {
     lockVersion: LOCK_VERSION,
-    installedPackages: {}
+    installedPackages: {},
+    managed: {}
   };
 }
 
@@ -81,12 +82,14 @@ async function loadLockFile(appRoot) {
 
   const lock = await readJsonFile(lockPath);
   const installedPackages = ensureObject(lock?.installedPackages);
+  const managed = ensureObject(lock?.managed);
   const lockVersion = Number(lock?.lockVersion);
   return {
     lockPath,
     lock: {
       lockVersion: Number.isFinite(lockVersion) && lockVersion > 0 ? lockVersion : LOCK_VERSION,
-      installedPackages
+      installedPackages,
+      managed
     }
   };
 }

package/src/server/cliRuntime/ci/composer.js

@@ -0,0 +1,171 @@
+import { normalizeCiContribution } from "./contract.js";
+
+class CiCompositionError extends Error {
+  constructor(code, message, details = {}) {
+    super(`[ci:${code}] ${message}`);
+    this.name = "CiCompositionError";
+    this.code = `ci:${code}`;
+    this.details = details && typeof details === "object" ? { ...details } : {};
+  }
+}
+
+function canonicalValue(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => canonicalValue(entry));
+  }
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort((left, right) => left.localeCompare(right))
+        .map((key) => [key, canonicalValue(value[key])])
+    );
+  }
+  return value;
+}
+
+function valuesMatch(left, right) {
+  return JSON.stringify(canonicalValue(left)) === JSON.stringify(canonicalValue(right));
+}
+
+function formatConflictValue(value) {
+  return JSON.stringify(canonicalValue(value));
+}
+
+function normalizePackageEntries(packageEntries = []) {
+  const entries = packageEntries instanceof Map ? [...packageEntries.values()] : packageEntries;
+  if (!Array.isArray(entries)) {
+    throw new TypeError("composeCiContributions requires package entries as an array or Map.");
+  }
+  return entries
+    .map((entry) => ({
+      packageId: String(entry?.packageId || entry?.descriptor?.packageId || "").trim(),
+      descriptor: entry?.descriptor && typeof entry.descriptor === "object" ? entry.descriptor : {}
+    }))
+    .filter((entry) => Boolean(entry.packageId))
+    .sort((left, right) => left.packageId.localeCompare(right.packageId));
+}
+
+function appendSource(sourceMap, key, packageId) {
+  if (!sourceMap.has(key)) {
+    sourceMap.set(key, new Set());
+  }
+  sourceMap.get(key).add(packageId);
+}
+
+function conflict({ kind, id, existing, incoming, existingPackages, incomingPackage }) {
+  const label = kind === "environment" ? "environment key" : `${kind} ID`;
+  throw new CiCompositionError(
+    `${kind}-conflict`,
+    `Conflicting CI ${label} "${id}" from ${[...existingPackages].sort().join(", ")} and ${incomingPackage}. ` +
+      `Existing value: ${formatConflictValue(existing)}. Incoming value: ${formatConflictValue(incoming)}. ` +
+      "Align the package descriptors or remove one of the conflicting packages.",
+    {
+      kind,
+      id,
+      existing,
+      incoming,
+      existingPackages: [...existingPackages].sort(),
+      incomingPackage
+    }
+  );
+}
+
+function sourcesToObject(sourceMap) {
+  return Object.fromEntries(
+    [...sourceMap.entries()]
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, packageIds]) => [key, [...packageIds].sort((left, right) => left.localeCompare(right))])
+  );
+}
+
+function composeCiContributions(packageEntries = []) {
+  const environmentByKey = new Map();
+  const servicesById = new Map();
+  const stepsById = new Map();
+  const environmentSources = new Map();
+  const serviceSources = new Map();
+  const stepSources = new Map();
+  const contributingPackages = new Set();
+
+  for (const packageEntry of normalizePackageEntries(packageEntries)) {
+    const { packageId, descriptor } = packageEntry;
+    const contribution = normalizeCiContribution(descriptor.ci, {
+      packageId,
+      descriptorPath: packageId
+    });
+    const contributes =
+      Object.keys(contribution.environment).length > 0 ||
+      contribution.services.length > 0 ||
+      contribution.steps.length > 0;
+    if (contributes) {
+      contributingPackages.add(packageId);
+    }
+
+    for (const [key, value] of Object.entries(contribution.environment)) {
+      if (environmentByKey.has(key) && environmentByKey.get(key) !== value) {
+        conflict({
+          kind: "environment",
+          id: key,
+          existing: environmentByKey.get(key),
+          incoming: value,
+          existingPackages: environmentSources.get(key),
+          incomingPackage: packageId
+        });
+      }
+      environmentByKey.set(key, value);
+      appendSource(environmentSources, key, packageId);
+    }
+
+    for (const service of contribution.services) {
+      if (servicesById.has(service.id) && !valuesMatch(servicesById.get(service.id), service)) {
+        conflict({
+          kind: "service",
+          id: service.id,
+          existing: servicesById.get(service.id),
+          incoming: service,
+          existingPackages: serviceSources.get(service.id),
+          incomingPackage: packageId
+        });
+      }
+      servicesById.set(service.id, service);
+      appendSource(serviceSources, service.id, packageId);
+    }
+
+    for (const step of contribution.steps) {
+      if (stepsById.has(step.id) && !valuesMatch(stepsById.get(step.id), step)) {
+        conflict({
+          kind: "step",
+          id: step.id,
+          existing: stepsById.get(step.id),
+          incoming: step,
+          existingPackages: stepSources.get(step.id),
+          incomingPackage: packageId
+        });
+      }
+      stepsById.set(step.id, step);
+      appendSource(stepSources, step.id, packageId);
+    }
+  }
+
+  return {
+    environment: Object.fromEntries(
+      [...environmentByKey.entries()].sort(([left], [right]) => left.localeCompare(right))
+    ),
+    services: [...servicesById.values()].sort((left, right) => left.id.localeCompare(right.id)),
+    steps: [...stepsById.values()].sort((left, right) => {
+      const phaseComparison = left.phase.localeCompare(right.phase);
+      return phaseComparison || left.id.localeCompare(right.id);
+    }),
+    sources: {
+      environment: sourcesToObject(environmentSources),
+      services: sourcesToObject(serviceSources),
+      steps: sourcesToObject(stepSources)
+    },
+    packages: [...contributingPackages].sort((left, right) => left.localeCompare(right))
+  };
+}
+
+export {
+  CiCompositionError,
+  composeCiContributions
+};

package/src/server/cliRuntime/ci/contract.js

@@ -0,0 +1,218 @@
+import { createCliError } from "../../shared/cliError.js";
+
+const CI_STEP_PHASE_BEFORE_VERIFY = "before-verify";
+const CI_STEP_PHASES = Object.freeze([
+  CI_STEP_PHASE_BEFORE_VERIFY
+]);
+const CI_ID_PATTERN = /^[a-z][a-z0-9-]*$/u;
+const CI_SERVICE_ID_PATTERN = /^[a-z][a-z0-9_-]*$/u;
+const RESERVED_CI_STEP_IDS = new Set([
+  "checkout",
+  "install-dependencies",
+  "setup-node",
+  "verify"
+]);
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function invalidCiContract(message, { descriptorPath = "", packageId = "" } = {}) {
+  const location = String(descriptorPath || packageId || "package descriptor").trim();
+  return createCliError(`Invalid package descriptor at ${location}: ${message}`);
+}
+
+function requirePlainObject(value, label, context) {
+  if (!isPlainObject(value)) {
+    throw invalidCiContract(`${label} must be an object.`, context);
+  }
+  return value;
+}
+
+function rejectUnknownKeys(value, allowedKeys, label, context) {
+  const unknownKeys = Object.keys(value).filter((key) => !allowedKeys.includes(key));
+  if (unknownKeys.length > 0) {
+    throw invalidCiContract(
+      `${label} contains unsupported field${unknownKeys.length === 1 ? "" : "s"}: ${unknownKeys.sort().join(", ")}.`,
+      context
+    );
+  }
+}
+
+function normalizeCiScalar(value, label, context) {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "boolean") {
+    return String(value);
+  }
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return String(value);
+  }
+  throw invalidCiContract(`${label} must be a string, boolean, or finite number.`, context);
+}
+
+function normalizeCiEnvironment(value, label, context) {
+  if (typeof value === "undefined") {
+    return {};
+  }
+  const environment = requirePlainObject(value, label, context);
+  const normalized = {};
+  for (const key of Object.keys(environment).sort((left, right) => left.localeCompare(right))) {
+    const normalizedKey = String(key || "").trim();
+    if (!normalizedKey) {
+      throw invalidCiContract(`${label} contains an empty key.`, context);
+    }
+    normalized[normalizedKey] = normalizeCiScalar(
+      environment[key],
+      `${label}.${normalizedKey}`,
+      context
+    );
+  }
+  return normalized;
+}
+
+function normalizeCiPorts(value, label, context) {
+  if (typeof value === "undefined") {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    throw invalidCiContract(`${label} must be an array.`, context);
+  }
+  const ports = value.map((port, index) => {
+    const normalized = String(port || "").trim();
+    if (!normalized) {
+      throw invalidCiContract(`${label}[${index}] must be a non-empty string.`, context);
+    }
+    return normalized;
+  });
+  return [...new Set(ports)].sort((left, right) => left.localeCompare(right));
+}
+
+function normalizeCiHealthCheck(value, label, context) {
+  if (typeof value === "undefined") {
+    return null;
+  }
+  const healthCheck = requirePlainObject(value, label, context);
+  rejectUnknownKeys(healthCheck, ["command", "interval", "timeout", "retries"], label, context);
+  const command = String(healthCheck.command || "").trim();
+  if (!command) {
+    throw invalidCiContract(`${label}.command is required.`, context);
+  }
+
+  const normalized = { command };
+  for (const propertyName of ["interval", "timeout"]) {
+    if (typeof healthCheck[propertyName] === "undefined") {
+      continue;
+    }
+    const propertyValue = String(healthCheck[propertyName] || "").trim();
+    if (!propertyValue) {
+      throw invalidCiContract(`${label}.${propertyName} must be a non-empty string.`, context);
+    }
+    normalized[propertyName] = propertyValue;
+  }
+
+  if (typeof healthCheck.retries !== "undefined") {
+    const retries = Number(healthCheck.retries);
+    if (!Number.isInteger(retries) || retries < 1) {
+      throw invalidCiContract(`${label}.retries must be a positive integer.`, context);
+    }
+    normalized.retries = retries;
+  }
+  return normalized;
+}
+
+function normalizeCiService(value, index, context) {
+  const label = `ci.services[${index}]`;
+  const service = requirePlainObject(value, label, context);
+  rejectUnknownKeys(service, ["id", "image", "environment", "ports", "healthCheck"], label, context);
+  const id = String(service.id || "").trim();
+  const image = String(service.image || "").trim();
+  if (!CI_SERVICE_ID_PATTERN.test(id)) {
+    throw invalidCiContract(
+      `${label}.id must match ${CI_SERVICE_ID_PATTERN.source}.`,
+      context
+    );
+  }
+  if (!image) {
+    throw invalidCiContract(`${label}.image is required.`, context);
+  }
+
+  const normalized = {
+    id,
+    image,
+    environment: normalizeCiEnvironment(service.environment, `${label}.environment`, context),
+    ports: normalizeCiPorts(service.ports, `${label}.ports`, context)
+  };
+  const healthCheck = normalizeCiHealthCheck(service.healthCheck, `${label}.healthCheck`, context);
+  if (healthCheck) {
+    normalized.healthCheck = healthCheck;
+  }
+  return normalized;
+}
+
+function normalizeCiStep(value, index, context) {
+  const label = `ci.steps[${index}]`;
+  const step = requirePlainObject(value, label, context);
+  rejectUnknownKeys(step, ["id", "phase", "label", "command"], label, context);
+  const id = String(step.id || "").trim();
+  const phase = String(step.phase || "").trim();
+  const stepLabel = String(step.label || "").trim();
+  const command = String(step.command || "").trim();
+
+  if (!CI_ID_PATTERN.test(id)) {
+    throw invalidCiContract(`${label}.id must match ${CI_ID_PATTERN.source}.`, context);
+  }
+  if (RESERVED_CI_STEP_IDS.has(id)) {
+    throw invalidCiContract(`${label}.id "${id}" is reserved by the JSKIT workflow.`, context);
+  }
+  if (!CI_STEP_PHASES.includes(phase)) {
+    throw invalidCiContract(
+      `${label}.phase must be one of: ${CI_STEP_PHASES.join(", ")}.`,
+      context
+    );
+  }
+  if (!stepLabel) {
+    throw invalidCiContract(`${label}.label is required.`, context);
+  }
+  if (!command) {
+    throw invalidCiContract(`${label}.command is required.`, context);
+  }
+
+  return {
+    id,
+    phase,
+    label: stepLabel,
+    command
+  };
+}
+
+function normalizeCiContribution(value, context = {}) {
+  if (typeof value === "undefined") {
+    return {
+      environment: {},
+      services: [],
+      steps: []
+    };
+  }
+  const ci = requirePlainObject(value, "ci", context);
+  rejectUnknownKeys(ci, ["environment", "services", "steps"], "ci", context);
+  if (typeof ci.services !== "undefined" && !Array.isArray(ci.services)) {
+    throw invalidCiContract("ci.services must be an array.", context);
+  }
+  if (typeof ci.steps !== "undefined" && !Array.isArray(ci.steps)) {
+    throw invalidCiContract("ci.steps must be an array.", context);
+  }
+
+  return {
+    environment: normalizeCiEnvironment(ci.environment, "ci.environment", context),
+    services: (ci.services || []).map((service, index) => normalizeCiService(service, index, context)),
+    steps: (ci.steps || []).map((step, index) => normalizeCiStep(step, index, context))
+  };
+}
+
+export {
+  CI_STEP_PHASE_BEFORE_VERIFY,
+  CI_STEP_PHASES,
+  normalizeCiContribution
+};

package/src/server/cliRuntime/ci/githubWorkflow.js

@@ -0,0 +1,136 @@
+import YAML from "yaml";
+import { CI_STEP_PHASE_BEFORE_VERIFY } from "./contract.js";
+
+const JSKIT_CI_WORKFLOW_RELATIVE_PATH = ".github/workflows/jskit-verify.yml";
+const LEGACY_CI_WORKFLOW_RELATIVE_PATH = ".github/workflows/verify.yml";
+const GENERATED_WORKFLOW_HEADER = [
+  "# Generated and managed by JSKIT. Run `npx jskit app sync-ci` to regenerate.",
+  "# Put application-specific CI in a separate workflow; edits to this file are not merged.",
+  ""
+].join("\n");
+const LEGACY_VERIFY_WORKFLOW_HASH = "9f274b8400ca51004446f98a9cf55e74180f11b016ee48b60f6d86e3b434bdb6";
+
+function quoteDockerOptionValue(value) {
+  return JSON.stringify(String(value || ""));
+}
+
+function renderGithubServiceOptions(service = {}) {
+  const healthCheck = service?.healthCheck;
+  if (!healthCheck || typeof healthCheck !== "object") {
+    return "";
+  }
+  const options = [`--health-cmd=${quoteDockerOptionValue(healthCheck.command)}`];
+  if (healthCheck.interval) {
+    options.push(`--health-interval=${healthCheck.interval}`);
+  }
+  if (healthCheck.timeout) {
+    options.push(`--health-timeout=${healthCheck.timeout}`);
+  }
+  if (healthCheck.retries) {
+    options.push(`--health-retries=${healthCheck.retries}`);
+  }
+  return options.join(" ");
+}
+
+function renderGithubService(service = {}) {
+  const rendered = {
+    image: service.image
+  };
+  if (Object.keys(service.environment || {}).length > 0) {
+    rendered.env = service.environment;
+  }
+  if (Array.isArray(service.ports) && service.ports.length > 0) {
+    rendered.ports = service.ports;
+  }
+  const options = renderGithubServiceOptions(service);
+  if (options) {
+    rendered.options = options;
+  }
+  return rendered;
+}
+
+function buildGithubWorkflowDocument(model = {}) {
+  const beforeVerifySteps = (Array.isArray(model.steps) ? model.steps : [])
+    .filter((step) => step.phase === CI_STEP_PHASE_BEFORE_VERIFY)
+    .map((step) => ({
+      id: step.id,
+      name: step.label,
+      run: step.command
+    }));
+  const steps = [
+    {
+      id: "checkout",
+      name: "Checkout",
+      uses: "actions/checkout@v4"
+    },
+    {
+      id: "setup-node",
+      name: "Setup Node",
+      uses: "actions/setup-node@v4",
+      with: {
+        "node-version": 20,
+        cache: "npm"
+      }
+    },
+    {
+      id: "install-dependencies",
+      name: "Install dependencies",
+      run: "npm ci"
+    },
+    ...beforeVerifySteps,
+    {
+      id: "verify",
+      name: "Run verification",
+      run: "npm run verify"
+    }
+  ];
+  const verifyJob = {
+    "runs-on": "ubuntu-latest"
+  };
+  if (Object.keys(model.environment || {}).length > 0) {
+    verifyJob.env = model.environment;
+  }
+  if (Array.isArray(model.services) && model.services.length > 0) {
+    verifyJob.services = Object.fromEntries(
+      model.services.map((service) => [service.id, renderGithubService(service)])
+    );
+  }
+  verifyJob.steps = steps;
+
+  return {
+    name: "JSKIT Verify",
+    on: {
+      pull_request: null,
+      push: {
+        branches: ["main"]
+      }
+    },
+    permissions: {
+      contents: "read"
+    },
+    jobs: {
+      verify: verifyJob
+    }
+  };
+}
+
+function renderGithubWorkflow(model = {}) {
+  return `${GENERATED_WORKFLOW_HEADER}${YAML.stringify(buildGithubWorkflowDocument(model), {
+    lineWidth: 0
+  })}`;
+}
+
+function parseGithubWorkflow(source = "") {
+  return YAML.parse(String(source || ""));
+}
+
+export {
+  GENERATED_WORKFLOW_HEADER,
+  JSKIT_CI_WORKFLOW_RELATIVE_PATH,
+  LEGACY_CI_WORKFLOW_RELATIVE_PATH,
+  LEGACY_VERIFY_WORKFLOW_HASH,
+  buildGithubWorkflowDocument,
+  parseGithubWorkflow,
+  renderGithubServiceOptions,
+  renderGithubWorkflow
+};