KbCreateParameters.java
/*
* Copyright © 2026 IKE Network (support@ike.network)
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package network.ike.plugin;
import org.apache.maven.api.Session;
import org.apache.maven.api.plugin.Log;
import org.apache.maven.api.plugin.MojoException;
import org.apache.maven.api.plugin.annotations.Parameter;
import org.apache.maven.api.settings.Server;
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.Duration;
import java.util.ArrayList;
import java.util.List;
import java.util.Locale;
import java.util.Optional;
/**
* The shared input surface of the {@code ike:kb-create-*} pair
* (IKE-Network/ike-issues#1370). Required: the name and, for a source, the importer
* and release. Everything else is defaulted from the existing knowledge bases of
* {@code solor-kb-ws} or derived, and every knowledge source is pinned against the repository before
* anything is shown or written.
*/
abstract class KbCreateParameters {
/** The repository the knowledge sources are pinned against unless {@code -DknowledgeSourceRepository} says. */
static final String DEFAULT_KNOWLEDGE_SOURCE_REPOSITORY = "https://nexus.tinkar.org/repository/ike-restricted/";
/** The restricted releases repository, the default deploy target (decision 5). */
static final String DEFAULT_RELEASES = "https://nexus.tinkar.org/repository/ike-restricted-releases/";
/** The restricted snapshots repository, the default deploy target (decision 5). */
static final String DEFAULT_SNAPSHOTS = "https://nexus.tinkar.org/repository/ike-restricted-snapshots/";
/** How long one repository request may take. */
private static final Duration TIMEOUT = Duration.ofSeconds(60);
/** The artifactId, which also names the project's folder, such as {@code my-kb}. Required. */
@Parameter(property = "name")
String name;
/** {@code assembly} (the default) or {@code source}. */
@Parameter(property = "kind")
String kind;
/** The project's groupId. */
@Parameter(property = "groupId", defaultValue = "network.ike.data")
String groupId = "network.ike.data";
/** The project's version. */
@Parameter(property = "version", defaultValue = "1-SNAPSHOT")
String version = "1-SNAPSHOT";
/** The POM {@code <name>}; derived from the name when absent. */
@Parameter(property = "displayName")
String displayName;
/** The POM {@code <description>}; derived from the kind and knowledge sources when absent. */
@Parameter(property = "description")
String description;
/**
* The knowledge sources in load order, comma-separated, each
* {@code groupId:artifactId:zip:classifier:version}. The IKE starter set is put first
* unless it is listed or a {@code reasoned-pb} knowledge source is the base.
*/
@Parameter(property = "knowledgeSources")
String knowledgeSources;
/** Renamed {@code -DknowledgeSources}; refused with that word, so an old command is not silently ignored. */
@Parameter(property = "layers")
String layers;
/** Renamed {@code -DknowledgeSourceRepository}; refused the same way. */
@Parameter(property = "layerRepository")
String layerRepository;
/** Renamed {@code -DknowledgeSourceRepositoryId}; refused the same way. */
@Parameter(property = "layerRepositoryId")
String layerRepositoryId;
/** The starter set's version when it is put first. */
@Parameter(property = "starterSetVersion", defaultValue = "1-SNAPSHOT")
String starterSetVersion = "1-SNAPSHOT";
/** A source's importer, such as {@code snomed-rf2}: {@code dev.ikm.tinkar:importer-<name>}. */
@Parameter(property = "importer")
String importer;
/** A source's release: a Maven coordinate (pinned like a knowledge source) or a path. */
@Parameter(property = "release")
String release;
/** A source's importer options, such as {@code release=full}. */
@Parameter(property = "importerOptions")
String importerOptions;
/** The IKE Dashboard collection named in the store's descriptor; none when absent. */
@Parameter(property = "collection")
String collection;
/** The deploy repositories' server id. */
@Parameter(property = "distributionId", defaultValue = "ike-restricted")
String distributionId = "ike-restricted";
/** The releases repository a deploy goes to. */
@Parameter(property = "releasesUrl", defaultValue = DEFAULT_RELEASES)
String releasesUrl = DEFAULT_RELEASES;
/** The snapshots repository a deploy goes to. */
@Parameter(property = "snapshotsUrl", defaultValue = DEFAULT_SNAPSHOTS)
String snapshotsUrl = DEFAULT_SNAPSHOTS;
/** The site deploy URL ike-parent's enforcer requires; {@code https://ike.network/<name>/} when absent. */
@Parameter(property = "siteUrl")
String siteUrl;
/** {@code true} or {@code false} to force the Rocks store; decided by the knowledge sources' size when absent. */
@Parameter(property = "rocks")
String rocks;
/** The build heap, such as {@code -Xmx24g}; estimated from the knowledge sources when absent. */
@Parameter(property = "heap")
String heap;
/** The knowledge base's module UUID, whose versions alone authoring keeps; every version when absent. */
@Parameter(property = "editModule")
String editModule;
/** The {@code ike-parent} version; the scaffold's tested foundation parent when absent. */
@Parameter(property = "parentVersion")
String parentVersion;
/** The {@code ike-knowledge-provider} version, as solor-kb-ws pins it. */
@Parameter(property = "providerVersion", defaultValue = "7-SNAPSHOT")
String providerVersion = "7-SNAPSHOT";
/** The {@code tinkar-core} version a source's importer comes from, as solor-kb-ws pins it. */
@Parameter(property = "tinkarCoreVersion", defaultValue = "1.127.7-SNAPSHOT")
String tinkarCoreVersion = "1.127.7-SNAPSHOT";
/** The {@code rocks-kb} version, as solor-kb-ws pins it. */
@Parameter(property = "rocksKbVersion", defaultValue = "0.1.5-SNAPSHOT")
String rocksKbVersion = "0.1.5-SNAPSHOT";
/** The {@code rocksdbjni} version, as solor-kb-ws pins it. */
@Parameter(property = "rocksdbjniVersion", defaultValue = "10.4.2-r2")
String rocksdbjniVersion = "10.4.2-r2";
/** The {@code rocksdbjni} platform classifier; the existing knowledge bases build on macOS. */
@Parameter(property = "rocksdbjniClassifier", defaultValue = "osx")
String rocksdbjniClassifier = "osx";
/** The repository the knowledge sources are pinned against. */
@Parameter(property = "knowledgeSourceRepository", defaultValue = DEFAULT_KNOWLEDGE_SOURCE_REPOSITORY)
String knowledgeSourceRepository = DEFAULT_KNOWLEDGE_SOURCE_REPOSITORY;
/** The server id whose login in {@code settings.xml} reads the knowledge source repository. */
@Parameter(property = "knowledgeSourceRepositoryId", defaultValue = "ike-restricted")
String knowledgeSourceRepositoryId = "ike-restricted";
/** The project's folder; {@code <name>} under the directory Maven runs in when absent. */
@Parameter(property = "targetDirectory")
String targetDirectory;
/**
* The project's folder.
*
* @return its absolute path
* @throws MojoException if no name is given
*/
Path target() {
if (targetDirectory != null && !targetDirectory.isBlank()) {
return Path.of(targetDirectory).toAbsolutePath().normalize();
}
if (name == null || name.isBlank()) {
throw new MojoException("A knowledge base needs -Dname, its artifactId, such as -Dname=my-kb");
}
return Path.of(System.getProperty("user.dir"), name.strip()).toAbsolutePath().normalize();
}
/**
* Refuses the parameter names of {@code ike-maven-plugin} 280 and 281, which called the knowledge
* sources "layers" (IKE-Network/ike-issues#1370; KEC, 2026-11-12). A refusal, not an alias, so a
* command that still uses the old word says which word replaced it.
*
* @param layers the value of {@code -Dlayers}, or {@code null}
* @param layerRepository the value of {@code -DlayerRepository}, or {@code null}
* @param layerRepositoryId the value of {@code -DlayerRepositoryId}, or {@code null}
* @throws MojoException if any of them is given
*/
static void refuseOldNames(String layers, String layerRepository, String layerRepositoryId) {
List<String> renamed = new ArrayList<>();
if (layers != null) {
renamed.add("-Dlayers is now -DknowledgeSources");
}
if (layerRepository != null) {
renamed.add("-DlayerRepository is now -DknowledgeSourceRepository");
}
if (layerRepositoryId != null) {
renamed.add("-DlayerRepositoryId is now -DknowledgeSourceRepositoryId");
}
if (!renamed.isEmpty()) {
throw new MojoException(String.join("; ", renamed) + ". The knowledge sources were called layers before"
+ " ike-maven-plugin 282.");
}
}
/**
* Pins the knowledge sources against the repository and builds the plan.
*
* @param session the Maven session, for its settings and offline mode
* @param log where progress goes
* @param scaffoldRoot the unpacked scaffold, for the default parent version
* @return the plan
* @throws MojoException if a parameter is malformed, Maven runs offline, or a knowledge source
* cannot be pinned
*/
KbCreatePlan plan(Session session, Log log, Path scaffoldRoot) {
refuseOldNames(layers, layerRepository, layerRepositoryId);
if (name == null || name.isBlank()) {
throw new MojoException("A knowledge base needs -Dname, its artifactId, such as -Dname=my-kb");
}
if (session.getSettings().isOffline()) {
throw new MojoException("Creating a knowledge base pins every knowledge source against "
+ knowledgeSourceRepository + "; Maven is offline");
}
try {
KbKind parsedKind = KbKind.parse(kind);
List<KbKnowledgeSource> requested = new ArrayList<>();
if (knowledgeSources != null) {
for (String spec : knowledgeSources.split(",")) {
if (!spec.isBlank()) {
requested.add(KbKnowledgeSource.parse(spec));
}
}
}
List<KbKnowledgeSource> ordered = KbCreatePlan.withStarterSet(requested, starterSetVersion);
KbKnowledgeSourceResolver resolver = resolver(session, log);
List<KbKnowledgeSource> pinned = new ArrayList<>();
for (KbKnowledgeSource knowledgeSource : ordered) {
log.info("Pinning " + knowledgeSource.coordinate(knowledgeSource.version()) + " …");
pinned.add(resolver.pin(knowledgeSource));
}
KbKnowledgeSource pinnedRelease = null;
String releasePath = null;
if (release != null && !release.isBlank()) {
Optional<KbKnowledgeSource> coordinate = KbCreatePlan.coordinateOf(release.strip());
if (coordinate.isPresent()) {
log.info("Pinning " + release.strip() + " …");
pinnedRelease = resolver.pin(coordinate.get());
} else {
releasePath = release.strip();
}
}
Path target = target();
return new KbCreatePlan(new KbCreatePlan.Inputs(parsedKind, groupId, name.strip(), version,
displayName, description,
parentVersion != null && !parentVersion.isBlank() ? parentVersion.strip()
: KbCreateSupport.foundationParentVersion(scaffoldRoot),
!insideWorkspace(target), target.toUri().toString(), pinned,
importer, pinnedRelease, releasePath, importerOptions, collection,
distributionId, releasesUrl, snapshotsUrl,
siteUrl != null && !siteUrl.isBlank() ? siteUrl.strip() : "https://ike.network/" + name.strip() + "/",
parseRocks(rocks), heap, editModule, providerVersion, tinkarCoreVersion,
rocksKbVersion, rocksdbjniVersion, rocksdbjniClassifier));
} catch (IllegalArgumentException e) {
throw new MojoException(e.getMessage(), e);
} catch (IOException e) {
throw new MojoException("Cannot pin the knowledge sources: " + e.getMessage(), e);
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
throw new MojoException("Interrupted pinning the knowledge sources", e);
}
}
/**
* Whether a folder is a workspace member: its parent holds a {@code workspace.yaml}, so
* the workspace root, not the project, is the Maven root.
*
* @param target the project's folder
* @return {@code true} inside a workspace
*/
static boolean insideWorkspace(Path target) {
Path parent = target.getParent();
return parent != null && Files.isRegularFile(parent.resolve("workspace.yaml"));
}
/**
* Reads {@code -Drocks}.
*
* @param value {@code true}, {@code false}, or absent
* @return the forced choice, or {@code null} to decide by size
* @throws IllegalArgumentException for any other value
*/
static Boolean parseRocks(String value) {
if (value == null || value.isBlank()) {
return null;
}
return switch (value.strip().toLowerCase(Locale.ROOT)) {
case "true" -> Boolean.TRUE;
case "false" -> Boolean.FALSE;
default -> throw new IllegalArgumentException("-Drocks takes true or false, or nothing to decide by size; got " + value);
};
}
private KbKnowledgeSourceResolver resolver(Session session, Log log) {
String username = null;
String password = null;
for (Server server : session.getSettings().getServers()) {
if (knowledgeSourceRepositoryId.equals(server.getId())) {
String secret = server.getPassword();
if (secret != null && secret.startsWith("{") && secret.endsWith("}")) {
log.warn("The password for " + knowledgeSourceRepositoryId + " is encrypted; reading "
+ knowledgeSourceRepository + " without a login");
} else {
username = server.getUsername();
password = secret;
}
}
}
if (username == null) {
log.info("No login for " + knowledgeSourceRepositoryId + " in settings.xml; reading " + knowledgeSourceRepository + " anonymously");
}
return new KbKnowledgeSourceResolver(HttpClient.newBuilder().followRedirects(HttpClient.Redirect.NORMAL).build(),
URI.create(knowledgeSourceRepository), username, password, TIMEOUT);
}
}