KbCreateSupport.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 network.ike.plugin.scaffold.DirectoryTemplateSource;
import network.ike.plugin.scaffold.ManifestEntry;
import network.ike.plugin.scaffold.ModelAdapters;
import network.ike.plugin.scaffold.PathResolver;
import network.ike.plugin.scaffold.ScaffoldApplier;
import network.ike.plugin.scaffold.ScaffoldLockfile;
import network.ike.plugin.scaffold.ScaffoldLockfileIo;
import network.ike.plugin.scaffold.ScaffoldManifest;
import network.ike.plugin.scaffold.ScaffoldMojoSupport;
import network.ike.plugin.scaffold.ScaffoldPlan;
import network.ike.plugin.scaffold.ScaffoldPlanner;
import network.ike.plugin.scaffold.ScaffoldScope;
import network.ike.plugin.scaffold.TierHandlers;
import org.apache.maven.api.Session;
import org.apache.maven.api.plugin.Log;
import org.apache.maven.api.plugin.MojoException;
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;
import java.util.ArrayList;
import java.util.Enumeration;
import java.util.List;
import java.util.Map;
import java.util.TreeMap;
import java.util.stream.Stream;
import java.util.zip.ZipEntry;
import java.util.zip.ZipFile;
/**
* Shared mechanics of the {@code ike:kb-create-*} goals (IKE-Network/ike-issues#1370):
* the {@code kb/} templates and the project scaffold both come from the
* {@code ike-build-standards} scaffold zip of this plugin's own version, the one source
* the starter-set genesis and {@code ike:scaffold-publish} read too.
*/
final class KbCreateSupport {
/** The template directory inside the scaffold artifact. */
static final String TEMPLATE_ROOT = "kb";
private KbCreateSupport() {
}
/**
* Unpacks the {@code ike-build-standards} scaffold zip matching this plugin's version.
*
* @param session the Maven session, for artifact resolution
* @param into an empty directory to unpack into
* @return the scaffold tree's root, holding {@code scaffold-manifest.yaml}
* @throws MojoException if the artifact cannot be resolved or unpacked
*/
static Path unpackScaffold(Session session, Path into) {
String coordinates = "network.ike.tooling:ike-build-standards:zip:scaffold:"
+ StarterSetCreateSupport.pluginVersion();
Path zipPath;
try {
zipPath = session.resolveArtifact(session.createArtifactCoordinates(coordinates)).getPath();
} catch (RuntimeException e) {
throw new MojoException("Cannot resolve the standards scaffold artifact " + coordinates
+ " carrying the knowledge-base templates", e);
}
try (ZipFile zip = new ZipFile(zipPath.toFile())) {
Path root = into.toAbsolutePath().normalize();
Enumeration<? extends ZipEntry> entries = zip.entries();
while (entries.hasMoreElements()) {
ZipEntry entry = entries.nextElement();
Path target = root.resolve(entry.getName()).normalize();
if (!target.startsWith(root)) {
throw new MojoException("The scaffold artifact holds an entry outside its root: "
+ entry.getName());
}
if (entry.isDirectory()) {
Files.createDirectories(target);
continue;
}
Files.createDirectories(target.getParent());
try (InputStream in = zip.getInputStream(entry)) {
Files.copy(in, target, StandardCopyOption.REPLACE_EXISTING);
}
}
return root;
} catch (IOException e) {
throw new MojoException("Cannot unpack the standards scaffold artifact " + zipPath, e);
}
}
/**
* Reads the {@code kb/} templates of a scaffold tree.
*
* @param scaffoldRoot the scaffold tree's root
* @return template path within {@code kb/} to its text, sorted
* @throws MojoException if the tree has no {@code kb/} templates
*/
static Map<String, String> templates(Path scaffoldRoot) {
Path root = scaffoldRoot.resolve(TEMPLATE_ROOT);
if (!Files.isDirectory(root)) {
throw new MojoException("The scaffold at " + scaffoldRoot + " carries no knowledge-base"
+ " templates (kb/) — ike-build-standards and ike-maven-plugin versions must match");
}
Map<String, String> templates = new TreeMap<>();
try (Stream<Path> files = Files.walk(root)) {
for (Path file : files.filter(Files::isRegularFile).toList()) {
String relative = root.relativize(file).toString().replace('\\', '/');
templates.put(relative, Files.readString(file, StandardCharsets.UTF_8));
}
} catch (IOException e) {
throw new MojoException("Cannot read the knowledge-base templates under " + root, e);
}
return templates;
}
/**
* The {@code ike-parent} version the scaffold tested its standards with: the default
* parent of a new project.
*
* @param scaffoldRoot the scaffold tree's root
* @return the version
* @throws MojoException if the manifest names no foundation parent
*/
static String foundationParentVersion(Path scaffoldRoot) {
ScaffoldManifest manifest = ScaffoldMojoSupport.loadManifest(scaffoldRoot);
if (manifest.foundation() == null || manifest.foundation().parent() == null) {
throw new MojoException("The scaffold manifest names no foundation parent; set -DparentVersion");
}
return manifest.foundation().parent().version();
}
/**
* The files the project scope of the scaffold writes, by project-relative path: the
* wrapper, {@code .mvn}, {@code .gitignore}, {@code CLAUDE.md}, {@code README.md}.
*
* @param scaffoldRoot the scaffold tree's root
* @return the paths
*/
static List<String> projectScaffoldFiles(Path scaffoldRoot) {
ScaffoldManifest manifest = ScaffoldMojoSupport.loadManifest(scaffoldRoot);
List<String> paths = new ArrayList<>();
for (ManifestEntry entry : manifest.entriesInScope(ScaffoldScope.PROJECT)) {
paths.add(entry.dest());
}
paths.add(".ike/scaffold.lock");
return paths;
}
/**
* Applies the scaffold's project scope to a new project, as {@code ike:scaffold-publish}
* does, and writes its lockfile. The user scope ({@code ~/.gitconfig},
* {@code ~/.m2/settings.xml}) is left alone: creating a project changes nothing outside
* it.
*
* @param scaffoldRoot the scaffold tree's root
* @param projectRoot the new project
* @param userHome the user's home, which the manifest's paths resolve against
* @return the project-relative paths the scaffold wrote, lockfile included
*/
static List<String> applyProjectScaffold(Path scaffoldRoot, Path projectRoot, Path userHome) {
ScaffoldManifest manifest = ScaffoldMojoSupport.loadManifest(scaffoldRoot);
PathResolver resolver = new PathResolver(userHome, projectRoot);
ScaffoldPlanner planner = new ScaffoldPlanner(new TierHandlers(), new ModelAdapters());
Path lockPath = ScaffoldMojoSupport.projectLockfilePath(projectRoot);
ScaffoldLockfile lockfile = ScaffoldMojoSupport.loadLockfileOrEmpty(lockPath);
ScaffoldPlan plan = planner.plan(manifest, lockfile, ScaffoldScope.PROJECT, resolver,
new DirectoryTemplateSource(scaffoldRoot));
ScaffoldLockfile applied = new ScaffoldApplier().apply(plan, lockfile);
ScaffoldLockfileIo.write(applied, lockPath);
List<String> written = new ArrayList<>();
for (String path : projectScaffoldFiles(scaffoldRoot)) {
if (Files.exists(projectRoot.resolve(path))) {
written.add(path);
}
}
return written;
}
/**
* Runs a command in a directory, logging its output, and fails on a non-zero exit.
*
* @param log where its output goes
* @param directory where it runs
* @param command the command and its arguments
* @throws MojoException if it cannot run or exits non-zero
*/
static void run(Log log, Path directory, String... command) {
try {
Process process = new ProcessBuilder(command)
.directory(directory.toFile())
.redirectErrorStream(true)
.start();
try (BufferedReader reader = new BufferedReader(
new InputStreamReader(process.getInputStream(), StandardCharsets.UTF_8))) {
String line = reader.readLine();
while (line != null) {
log.info("[kb-create] " + line);
line = reader.readLine();
}
}
int exit = process.waitFor();
if (exit != 0) {
throw new MojoException("Step failed (exit " + exit + "): " + String.join(" ", command));
}
} catch (IOException e) {
throw new MojoException("Cannot run: " + String.join(" ", command), e);
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
throw new MojoException("Interrupted running: " + String.join(" ", command), e);
}
}
}