@jskit-ai/jskit-cli 0.2.27 → 0.2.28

package/src/server/cliRuntime/localPackageSupport.js

@@ -0,0 +1,390 @@
+import { createCliError } from "../shared/cliError.js";
+import {
+  ensureArray,
+  ensureObject,
+  sortStrings
+} from "../shared/collectionUtils.js";
+
+function resolvePackageDependencySpecifier(packageEntry, { existingValue = "" } = {}) {
+  const source = ensureObject(packageEntry?.source);
+  const sourceType = String(source.type || packageEntry?.sourceType || "").trim();
+  if (sourceType === "app-local-package" || sourceType === "local-package") {
+    const packagePath = normalizeRelativePosixPath(String(source.packagePath || packageEntry?.relativeDir || "").trim());
+    if (!packagePath) {
+      throw createCliError(`Unable to resolve local package path for ${String(packageEntry?.packageId || "unknown package")}.`);
+    }
+    return toFileDependencySpecifier(packagePath);
+  }
+  if (sourceType === "npm-installed-package") {
+    const normalizedExisting = String(existingValue || "").trim();
+    if (normalizedExisting) {
+      return normalizedExisting;
+    }
+  }
+
+  const descriptorVersion = String(packageEntry?.version || "").trim();
+  if (descriptorVersion) {
+    return normalizeJskitDependencySpecifier(packageEntry?.packageId, descriptorVersion);
+  }
+  const packageJsonVersion = String(packageEntry?.packageJson?.version || "").trim();
+  if (packageJsonVersion) {
+    return normalizeJskitDependencySpecifier(packageEntry?.packageId, packageJsonVersion);
+  }
+  throw createCliError(`Unable to resolve dependency specifier for ${String(packageEntry?.packageId || "unknown package")}.`);
+}
+
+function normalizeJskitDependencySpecifier(packageId, dependencySpecifier) {
+  const normalizedPackageId = String(packageId || "").trim();
+  const normalizedSpecifier = String(dependencySpecifier || "").trim();
+  if (!normalizedSpecifier || !normalizedPackageId.startsWith("@jskit-ai/")) {
+    return normalizedSpecifier;
+  }
+
+  const semverMatch = /^(\d+)\.\d+\.\d+(?:[.+-][0-9A-Za-z.-]+)?$/.exec(normalizedSpecifier);
+  if (!semverMatch) {
+    return normalizedSpecifier;
+  }
+
+  return `${semverMatch[1]}.x`;
+}
+
+function normalizePackageNameSegment(rawValue, { label = "package name" } = {}) {
+  const lowered = String(rawValue || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^[._-]+|[._-]+$/g, "");
+  if (!lowered) {
+    throw createCliError(`Invalid ${label}. Use letters, numbers, dash, underscore, or dot.`);
+  }
+  return lowered;
+}
+
+function normalizeScopeName(rawScope) {
+  const normalized = String(rawScope || "").trim().replace(/^@+/, "");
+  return normalizePackageNameSegment(normalized, { label: "scope" });
+}
+
+function resolveDefaultLocalScopeFromAppName(appPackageName) {
+  const appName = String(appPackageName || "").trim();
+  if (!appName) {
+    return "app";
+  }
+
+  const unscoped = appName.startsWith("@")
+    ? appName.slice(appName.indexOf("/") + 1)
+    : appName;
+  return normalizeScopeName(unscoped || "app");
+}
+
+function normalizeRelativePosixPath(pathValue) {
+  return String(pathValue || "")
+    .trim()
+    .replace(/\\/g, "/")
+    .replace(/^\/+|\/+$/g, "")
+    .replace(/\/{2,}/g, "/");
+}
+
+function toFileDependencySpecifier(relativePath) {
+  const normalized = normalizeRelativePosixPath(relativePath);
+  if (!normalized) {
+    throw createCliError("Cannot create file: dependency specifier from empty relative path.");
+  }
+  return `file:${normalized}`;
+}
+
+function resolveLocalPackageId({ rawName, appPackageName, inlineOptions }) {
+  const explicitPackageId = String(inlineOptions["package-id"] || "").trim();
+  if (explicitPackageId) {
+    const scopedPattern = /^@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/;
+    if (!scopedPattern.test(explicitPackageId)) {
+      throw createCliError(
+        `Invalid --package-id ${explicitPackageId}. Expected format: @scope/name (lowercase alphanumeric, ., _, -).`
+      );
+    }
+    const packageName = explicitPackageId.slice(explicitPackageId.indexOf("/") + 1);
+    return {
+      packageId: explicitPackageId,
+      packageDirName: normalizePackageNameSegment(packageName)
+    };
+  }
+
+  const packageDirName = normalizePackageNameSegment(rawName);
+  const scopeName = String(inlineOptions.scope || "").trim()
+    ? normalizeScopeName(inlineOptions.scope)
+    : resolveDefaultLocalScopeFromAppName(appPackageName);
+  return {
+    packageId: `@${scopeName}/${packageDirName}`,
+    packageDirName
+  };
+}
+
+function createLocalPackageDescriptorTemplate({ packageId, description }) {
+  return `export default Object.freeze({
+  packageVersion: 1,
+  packageId: "${packageId}",
+  version: "0.1.0",
+  kind: "runtime",
+  description: ${JSON.stringify(String(description || ""))},
+  dependsOn: [
+    // "@jskit-ai/kernel"
+  ],
+  capabilities: {
+    provides: [
+      // "example.feature"
+    ],
+    requires: [
+      // "example.dependency"
+    ]
+  },
+  options: {
+    // "example-option": {
+    //   required: true,
+    //   promptLabel: "Enter option value",
+    //   promptHint: "Used by mutations.text interpolation",
+    //   defaultValue: "example"
+    // }
+  },
+  runtime: {
+    server: {
+      providers: [
+        // {
+        //   entrypoint: "src/server/providers/ExampleServerProvider.js",
+        //   export: "ExampleServerProvider"
+        // }
+      ]
+    },
+    client: {
+      providers: [
+        // {
+        //   entrypoint: "src/client/providers/ExampleClientProvider.js",
+        //   export: "ExampleClientProvider"
+        // }
+      ]
+    }
+  },
+  metadata: {
+    server: {
+      routes: [
+        // {
+        //   method: "GET",
+        //   path: "/api/example",
+        //   summary: "Describe server route validator"
+        // }
+      ]
+    },
+    ui: {
+      routes: [
+        // {
+        //   id: "example.route",
+        //   path: "/example",
+        //   scope: "global",
+        //   name: "example-route",
+        //   componentKey: "example-route",
+        //   autoRegister: true,
+        //   guard: {
+        //     policy: "public"
+        //   },
+        //   purpose: "Describe what this route is for."
+        // }
+      ],
+      elements: [
+        // {
+        //   key: "example-route",
+        //   export: "ExampleView",
+        //   entrypoint: "src/client/views/ExampleView.vue",
+        //   purpose: "UI element exposed by this package."
+        // }
+      ],
+      overrides: [
+        // {
+        //   targetId: "some.existing.route",
+        //   mode: "replace",
+        //   reason: "Explain override intent."
+        // }
+      ]
+    }
+  },
+  mutations: {
+    dependencies: {
+      runtime: {
+        // "@example/runtime-dependency": "^1.0.0"
+      },
+      dev: {
+        // "@example/dev-dependency": "^1.0.0"
+      }
+    },
+    packageJson: {
+      scripts: {
+        // "lint:example": "eslint src/example"
+      }
+    },
+    procfile: {
+      // worker: "node ./bin/worker.js"
+    },
+    vite: {
+      proxy: [
+        // {
+        //   id: "example-socket-proxy",
+        //   path: "/socket.io",
+        //   changeOrigin: true,
+        //   ws: true,
+        //   target: "http://localhost:3000",
+        //   reason: "Explain why this proxy is needed."
+        // }
+      ]
+    },
+    text: [
+      // {
+      //   op: "upsert-env",
+      //   file: ".env",
+      //   key: "EXAMPLE_ENV",
+      //   value: "\${option:example-option}",
+      //   reason: "Explain why this env var is needed.",
+      //   category: "runtime-config",
+      //   id: "example-env"
+      // }
+    ],
+    files: [
+      // {
+      //   from: "templates/src/pages/example/index.vue",
+      //   to: "src/pages/example/index.vue",
+      //   reason: "Explain what is scaffolded.",
+      //   category: "example",
+      //   id: "example-file"
+      // }
+    ]
+  }
+});
+`;
+}
+
+function createLocalPackageScaffoldFiles({ packageId, packageDescription }) {
+  return [
+    {
+      relativePath: "package.json",
+      content: `${JSON.stringify(
+        {
+          name: packageId,
+          version: "0.1.0",
+          private: true,
+          type: "module",
+          exports: {
+            ".": "./src/index.js",
+            "./client": "./src/client/index.js",
+            "./server": "./src/server/index.js",
+            "./shared": "./src/shared/index.js"
+          }
+        },
+        null,
+        2
+      )}\n`
+    },
+    {
+      relativePath: "package.descriptor.mjs",
+      content: createLocalPackageDescriptorTemplate({
+        packageId,
+        description: packageDescription
+      })
+    },
+    {
+      relativePath: "src/index.js",
+      content: "export {};\n"
+    },
+    {
+      relativePath: "src/server/index.js",
+      content: "export {};\n"
+    },
+    {
+      relativePath: "src/client/index.js",
+      content: [
+        "const routeComponents = Object.freeze({});",
+        "",
+        "async function bootClient({ logger } = {}) {",
+        "  if (logger && typeof logger.debug === \"function\") {",
+        `    logger.debug({ packageId: ${JSON.stringify(packageId)} }, "bootClient executed.");`,
+        "  }",
+        "}",
+        "",
+        "export { routeComponents, bootClient };",
+        ""
+      ].join("\n")
+    },
+    {
+      relativePath: "src/shared/index.js",
+      content: "export {};\n"
+    },
+    {
+      relativePath: "README.md",
+      content: [
+        `# ${packageId}`,
+        "",
+        "App-local JSKIT module scaffold.",
+        "",
+        "## Next Steps",
+        "",
+        "- Define runtime providers in `package.descriptor.mjs`.",
+        "- Add client/server exports under `src/`.",
+        "- Keep package version in sync with descriptor version.",
+        ""
+      ].join("\n")
+    }
+  ];
+}
+
+function resolveLocalDependencyOrder(initialPackageIds, packageRegistry) {
+  const ordered = [];
+  const visited = new Set();
+  const visiting = new Set();
+  const externalDependencies = new Set();
+
+  function visit(packageId, lineage = []) {
+    if (visited.has(packageId)) {
+      return;
+    }
+    if (visiting.has(packageId)) {
+      const cyclePath = [...lineage, packageId].join(" -> ");
+      throw createCliError(`Dependency cycle detected: ${cyclePath}`);
+    }
+
+    const packageEntry = packageRegistry.get(packageId);
+    if (!packageEntry) {
+      throw createCliError(`Unknown package: ${packageId}`);
+    }
+
+    visiting.add(packageId);
+    for (const dependencyId of ensureArray(packageEntry.descriptor.dependsOn).map((value) => String(value))) {
+      if (packageRegistry.has(dependencyId)) {
+        visit(dependencyId, [...lineage, packageId]);
+      } else {
+        externalDependencies.add(dependencyId);
+      }
+    }
+    visiting.delete(packageId);
+    visited.add(packageId);
+    ordered.push(packageId);
+  }
+
+  for (const packageId of initialPackageIds) {
+    visit(packageId);
+  }
+
+  return {
+    ordered,
+    externalDependencies: sortStrings([...externalDependencies])
+  };
+}
+
+export {
+  resolvePackageDependencySpecifier,
+  normalizeJskitDependencySpecifier,
+  normalizePackageNameSegment,
+  normalizeScopeName,
+  resolveDefaultLocalScopeFromAppName,
+  normalizeRelativePosixPath,
+  toFileDependencySpecifier,
+  resolveLocalPackageId,
+  createLocalPackageScaffoldFiles,
+  resolveLocalDependencyOrder
+};

package/src/server/cliRuntime/mutationApplication.js

@@ -0,0 +1,9 @@
+export {
+  applyFileMutations,
+  preflightFileMutationTemplateContexts
+} from "./mutations/fileMutations.js";
+
+export {
+  applyTextMutations,
+  resolvePositioningMutations
+} from "./mutations/textMutations.js";

package/src/server/cliRuntime/mutationWhen.js

@@ -0,0 +1,285 @@
+import { createCliError } from "../shared/cliError.js";
+import {
+  ensureArray,
+  ensureObject
+} from "../shared/collectionUtils.js";
+
+function normalizeMutationExtension(value) {
+  const extension = String(value || "").trim();
+  if (!extension) {
+    return "";
+  }
+  if (extension.startsWith(".")) {
+    return extension;
+  }
+  return `.${extension}`;
+}
+
+function normalizeTemplateContextRecord(value) {
+  const record = ensureObject(value);
+  const entrypoint = String(record.entrypoint || "").trim();
+  const exportName = String(record.export || "").trim();
+  if (!entrypoint && !exportName) {
+    return null;
+  }
+
+  return Object.freeze({
+    entrypoint,
+    export: exportName || "buildTemplateContext"
+  });
+}
+
+function normalizeFileMutationRecord(value) {
+  const record = ensureObject(value);
+  const op = String(record.op || "copy-file").trim().toLowerCase() || "copy-file";
+  return {
+    op,
+    from: String(record.from || "").trim(),
+    to: String(record.to || "").trim(),
+    toSurface: String(record.toSurface || "").trim(),
+    toSurfacePath: String(record.toSurfacePath || "").trim(),
+    toSurfaceRoot: record.toSurfaceRoot === true,
+    toDir: String(record.toDir || "").trim(),
+    extension: normalizeMutationExtension(record.extension),
+    preserveOnRemove: record.preserveOnRemove === true,
+    id: String(record.id || "").trim(),
+    category: String(record.category || "").trim(),
+    reason: String(record.reason || "").trim(),
+    templateContext: normalizeTemplateContextRecord(record.templateContext),
+    when: normalizeMutationWhen(record.when)
+  };
+}
+
+function normalizeMutationWhen(value) {
+  const source = ensureObject(value);
+  const allConditions = ensureArray(source.all)
+    .map((entry) => normalizeMutationWhen(entry))
+    .filter(Boolean);
+  if (allConditions.length > 0) {
+    return {
+      all: allConditions
+    };
+  }
+
+  const option = String(source.option || "").trim();
+  const config = String(source.config || "").trim();
+  const equals = String(source.equals || "").trim();
+  const notEquals = String(source.notEquals || "").trim();
+  const contains = String(source.contains || "").trim();
+  const notContains = String(source.notContains || "").trim();
+  const includes = ensureArray(source.in).map((entry) => String(entry || "").trim()).filter(Boolean);
+  const excludes = ensureArray(source.notIn).map((entry) => String(entry || "").trim()).filter(Boolean);
+
+  if (!option && !config) {
+    return null;
+  }
+
+  return {
+    option,
+    config,
+    equals,
+    notEquals,
+    contains,
+    notContains,
+    includes,
+    excludes
+  };
+}
+
+function readObjectPath(source, rawPath) {
+  const valueSource = ensureObject(source);
+  const fullPath = String(rawPath || "").trim();
+  if (!fullPath) {
+    return undefined;
+  }
+
+  if (Object.prototype.hasOwnProperty.call(valueSource, fullPath)) {
+    return valueSource[fullPath];
+  }
+
+  const segments = fullPath
+    .split(".")
+    .map((entry) => String(entry || "").trim())
+    .filter(Boolean);
+  if (segments.length < 1) {
+    return undefined;
+  }
+
+  let cursor = valueSource;
+  for (const segment of segments) {
+    if (!cursor || typeof cursor !== "object" || Array.isArray(cursor)) {
+      return undefined;
+    }
+    if (!Object.prototype.hasOwnProperty.call(cursor, segment)) {
+      return undefined;
+    }
+    cursor = cursor[segment];
+  }
+
+  return cursor;
+}
+
+function normalizeWhenSourceValue(value) {
+  if (value == null) {
+    return "";
+  }
+  if (typeof value === "string") {
+    return value.trim();
+  }
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value).trim();
+  }
+  return "";
+}
+
+function normalizeWhenComparisonValue(value) {
+  const normalizedValue = normalizeWhenSourceValue(value);
+  if (!normalizedValue.includes(",")) {
+    return normalizedValue;
+  }
+
+  return normalizedValue
+    .split(",")
+    .map((entry) => String(entry || "").trim())
+    .filter(Boolean)
+    .join(",");
+}
+
+function splitWhenComparisonTokens(value) {
+  return normalizeWhenComparisonValue(value)
+    .split(",")
+    .map((entry) => String(entry || "").trim())
+    .filter(Boolean);
+}
+
+function matchesWhenComparisonValue(optionValue, optionTokens, expectedValue) {
+  const expected = normalizeWhenComparisonValue(expectedValue);
+  if (!expected) {
+    return false;
+  }
+
+  const expectedTokens = splitWhenComparisonTokens(expected);
+  if (expectedTokens.length > 1) {
+    return optionValue === expected;
+  }
+
+  if (optionTokens.length > 1) {
+    return optionTokens.includes(expectedTokens[0]);
+  }
+
+  return optionValue === expectedTokens[0];
+}
+
+function resolveWhenConfigValue(configContext = {}, configPath = "") {
+  const normalizedPath = String(configPath || "").trim();
+  if (!normalizedPath) {
+    return "";
+  }
+
+  const publicConfig = ensureObject(configContext.public);
+  const serverConfig = ensureObject(configContext.server);
+  const mergedConfig = ensureObject(configContext.merged);
+  if (normalizedPath === "public") {
+    return publicConfig;
+  }
+  if (normalizedPath === "server") {
+    return serverConfig;
+  }
+  if (normalizedPath === "merged") {
+    return mergedConfig;
+  }
+
+  if (normalizedPath.startsWith("public.")) {
+    return readObjectPath(publicConfig, normalizedPath.slice("public.".length));
+  }
+  if (normalizedPath.startsWith("server.")) {
+    return readObjectPath(serverConfig, normalizedPath.slice("server.".length));
+  }
+  if (normalizedPath.startsWith("merged.")) {
+    return readObjectPath(mergedConfig, normalizedPath.slice("merged.".length));
+  }
+
+  return readObjectPath(mergedConfig, normalizedPath);
+}
+
+function shouldApplyMutationWhen(
+  when,
+  {
+    options = {},
+    configContext = {},
+    packageId = "",
+    mutationContext = "mutation"
+  } = {}
+) {
+  if (!when || typeof when !== "object") {
+    return true;
+  }
+
+  const allConditions = ensureArray(when.all).filter((entry) => entry && typeof entry === "object");
+  if (allConditions.length > 0) {
+    return allConditions.every((entry) =>
+      shouldApplyMutationWhen(entry, {
+        options,
+        configContext,
+        packageId,
+        mutationContext
+      })
+    );
+  }
+
+  const optionName = String(when.option || "").trim();
+  const configPath = String(when.config || "").trim();
+  if (!optionName && !configPath) {
+    return true;
+  }
+  if (optionName && configPath) {
+    const packagePrefix = packageId ? `${packageId} ` : "";
+    throw createCliError(
+      `Invalid ${packagePrefix}${mutationContext}: when cannot declare both "option" and "config".`
+    );
+  }
+
+  const sourceValue = optionName
+    ? readObjectPath(options, optionName)
+    : resolveWhenConfigValue(configContext, configPath);
+  const optionValue = normalizeWhenComparisonValue(sourceValue);
+  const optionTokens = splitWhenComparisonTokens(optionValue);
+  const equals = normalizeWhenComparisonValue(when.equals);
+  const notEquals = normalizeWhenComparisonValue(when.notEquals);
+  const contains = normalizeWhenComparisonValue(when.contains);
+  const notContains = normalizeWhenComparisonValue(when.notContains);
+  const includes = ensureArray(when.includes).map((entry) => normalizeWhenComparisonValue(entry)).filter(Boolean);
+  const excludes = ensureArray(when.excludes).map((entry) => normalizeWhenComparisonValue(entry)).filter(Boolean);
+
+  if (equals && optionValue !== equals) {
+    return false;
+  }
+  if (notEquals && optionValue === notEquals) {
+    return false;
+  }
+  if (contains && !optionValue.includes(contains)) {
+    return false;
+  }
+  if (notContains && optionValue.includes(notContains)) {
+    return false;
+  }
+  if (includes.length > 0 && !includes.some((entry) => matchesWhenComparisonValue(optionValue, optionTokens, entry))) {
+    return false;
+  }
+  if (excludes.length > 0 && excludes.some((entry) => matchesWhenComparisonValue(optionValue, optionTokens, entry))) {
+    return false;
+  }
+
+  return true;
+}
+
+export {
+  normalizeMutationExtension,
+  normalizeTemplateContextRecord,
+  normalizeFileMutationRecord,
+  normalizeMutationWhen,
+  readObjectPath,
+  normalizeWhenSourceValue,
+  resolveWhenConfigValue,
+  shouldApplyMutationWhen
+};