feat: bootstrap portable engineering protocol CLI
Implement milestones 0 and 1 with project and repository configuration, Work persistence, discussions, draft decisions, evidence integrity, and deterministic context exports. Add Java 25, Spring Boot and Modulith, native distributions, CI workflows, protocol documentation, and the pinned SDKMAN GraalVM CE toolchain. Validated with 20 passing tests and the macOS ARM64 native multi-repository continuity smoke.
This commit is contained in:
@@ -0,0 +1,150 @@
|
||||
package net.intrepid.aiengineering.cli;
|
||||
|
||||
import net.intrepid.aiengineering.filesystem.*;
|
||||
import net.intrepid.aiengineering.project.*;
|
||||
import net.intrepid.aiengineering.work.*;
|
||||
import net.intrepid.aiengineering.discussion.*;
|
||||
import net.intrepid.aiengineering.decision.*;
|
||||
import net.intrepid.aiengineering.artifact.*;
|
||||
import net.intrepid.aiengineering.verification.*;
|
||||
import picocli.CommandLine;
|
||||
import picocli.CommandLine.*;
|
||||
import java.io.PrintWriter;
|
||||
import java.nio.file.Path;
|
||||
import java.util.List;
|
||||
|
||||
@Command(name = "ai-engineering", description = "Portable engineering protocol for humans and AI agents.",
|
||||
mixinStandardHelpOptions = true, version = "ai-engineering 0.1.0")
|
||||
public final class EngineeringCli implements Runnable {
|
||||
private final Path cwd;
|
||||
private final ProjectService projects = new ProjectService();
|
||||
private final WorkService works = new WorkService();
|
||||
private final VerificationService verification = new VerificationService();
|
||||
private PrintWriter output;
|
||||
private CommandLine commandLine;
|
||||
@Option(names = "--project", scope = ScopeType.INHERIT, description = "Engineering project root or .ai-engineering directory.") Path project;
|
||||
public EngineeringCli(Path cwd) { this.cwd = cwd.toAbsolutePath().normalize(); }
|
||||
public int execute(PrintWriter out, PrintWriter err, String... args) {
|
||||
output = out;
|
||||
commandLine = new CommandLine(this)
|
||||
.addSubcommand("project", new ProjectCommands()).addSubcommand("repo", new RepoCommands())
|
||||
.addSubcommand("work", new WorkCommands()).addSubcommand("discussion", new DiscussionCommands())
|
||||
.addSubcommand("decision", new DecisionCommands()).addSubcommand("artifact", new ArtifactCommands());
|
||||
configure(commandLine, out, err);
|
||||
commandLine.setExecutionExceptionHandler((exception, command, parse) -> {
|
||||
if (exception instanceof ProtocolException problem) { err.println(problem.getMessage()); return problem.exitCode(); }
|
||||
if (exception instanceof IllegalArgumentException) { err.println("Invalid input: " + exception.getMessage()); return 2; }
|
||||
err.println("Operation failed: " + exception.getMessage()); return 1;
|
||||
});
|
||||
int result = commandLine.execute(args); out.flush(); err.flush(); return result;
|
||||
}
|
||||
private void configure(CommandLine command, PrintWriter out, PrintWriter err) {
|
||||
command.setOut(out).setErr(err).setCaseInsensitiveEnumValuesAllowed(true);
|
||||
command.getSubcommands().values().forEach(child -> configure(child, out, err));
|
||||
}
|
||||
@Override public void run() { commandLine.usage(output); }
|
||||
private Path root() { return projects.discover(cwd, project == null ? null : resolve(project)); }
|
||||
private Path resolve(Path path) { return path.isAbsolute() ? path : cwd.resolve(path); }
|
||||
enum Format { markdown, json }
|
||||
private int emit(Object value, Format format) {
|
||||
output.print(format == Format.json ? Documents.json(value) : Documents.yaml(value)); return 0;
|
||||
}
|
||||
private int report(ValidationReport report, Format format) { emit(report, format); return report.valid() ? 0 : 4; }
|
||||
|
||||
@Command(name = "init", mixinStandardHelpOptions = true, description = "Initialize protocol files without modifying Git.")
|
||||
int init(@Option(names = "--name", required = true) String name) {
|
||||
Path target = project == null ? cwd : resolve(project);
|
||||
return emit(projects.initialize(target, name), Format.markdown);
|
||||
}
|
||||
@Command(name = "project", mixinStandardHelpOptions = true, description = "Inspect and validate the engineering project.")
|
||||
public class ProjectCommands {
|
||||
@Command(name = "show", mixinStandardHelpOptions = true)
|
||||
int show(@Option(names = "--format", defaultValue = "markdown") Format format) { return emit(projects.load(root()), format); }
|
||||
@Command(name = "validate", mixinStandardHelpOptions = true)
|
||||
int validate(@Option(names = "--format", defaultValue = "markdown") Format format) { return report(verification.project(root()), format); }
|
||||
}
|
||||
@Command(name = "repo", mixinStandardHelpOptions = true, description = "Register existing source repositories; default access is read-only.")
|
||||
public class RepoCommands {
|
||||
@Command(name = "add", mixinStandardHelpOptions = true)
|
||||
int add(@Parameters(index = "0") String id, @Option(names = "--path", required = true) String path,
|
||||
@Option(names = "--type", defaultValue = "linked-git") String type,
|
||||
@Option(names = "--language") String language, @Option(names = "--allow-edit") boolean edit,
|
||||
@Option(names = "--validation-command") List<String> commands) {
|
||||
var repo = new ProjectConfig.Repository(id, path, type, language, new ProjectConfig.Access(true, edit), commands);
|
||||
return emit(projects.addRepository(root(), repo), Format.markdown);
|
||||
}
|
||||
@Command(name = "list", mixinStandardHelpOptions = true)
|
||||
int list(@Option(names = "--format", defaultValue = "markdown") Format format) { return emit(projects.load(root()).repositories(), format); }
|
||||
}
|
||||
@Command(name = "work", mixinStandardHelpOptions = true, description = "Create, inspect, validate and export Works.")
|
||||
public class WorkCommands {
|
||||
@Command(name = "create", mixinStandardHelpOptions = true)
|
||||
int create(@Parameters(index = "0") String title,
|
||||
@Option(names = "--description", defaultValue = "") String description,
|
||||
@Option(names = "--goal", defaultValue = "") String goal,
|
||||
@Option(names = "--motivation", defaultValue = "") String motivation,
|
||||
@Option(names = "--constraint") List<String> constraints,
|
||||
@Option(names = "--acceptance") List<String> criteria,
|
||||
@Option(names = "--repo") List<String> repositories,
|
||||
@Option(names = "--author", defaultValue = "human") String author) {
|
||||
return emit(works.create(root(), title, description, goal, motivation, safe(constraints), safe(criteria), safe(repositories), author), Format.markdown);
|
||||
}
|
||||
@Command(name = "list", mixinStandardHelpOptions = true)
|
||||
int list(@Option(names = "--format", defaultValue = "markdown") Format format) { return emit(works.list(root()), format); }
|
||||
@Command(name = "show", mixinStandardHelpOptions = true)
|
||||
int show(@Parameters(index = "0") String id, @Option(names = "--format", defaultValue = "markdown") Format format) { return emit(works.load(root(), id), format); }
|
||||
@Command(name = "validate", mixinStandardHelpOptions = true)
|
||||
int validate(@Parameters(index = "0") String id, @Option(names = "--format", defaultValue = "markdown") Format format) {
|
||||
Work.identifier(id, "WRK"); Path root = root(); works.load(root, id); return report(verification.work(root, id), format);
|
||||
}
|
||||
@Command(name = "context", mixinStandardHelpOptions = true)
|
||||
int context(@Parameters(index = "0") String id, @Option(names = "--format", defaultValue = "markdown") Format format) {
|
||||
Work.identifier(id, "WRK"); Path root = root(); works.load(root, id);
|
||||
var context = verification.context(root, id);
|
||||
output.print(format == Format.json ? Documents.json(context) : verification.markdown(context)); return 0;
|
||||
}
|
||||
@Command(name = "status", mixinStandardHelpOptions = true, description = "Set lifecycle status; transitions remain reversible.")
|
||||
int status(@Parameters(index = "0") String id, @Parameters(index = "1") Work.Status status) { return emit(works.status(root(), id, status), Format.markdown); }
|
||||
}
|
||||
@Command(name = "discussion", mixinStandardHelpOptions = true, description = "Append human or agent refinement entries.")
|
||||
public class DiscussionCommands {
|
||||
@Command(name = "add", mixinStandardHelpOptions = true)
|
||||
int add(@Parameters(index = "0") String id, @Option(names = "--text", required = true) String text,
|
||||
@Option(names = "--kind", defaultValue = "NOTE") DiscussionEntry.Kind kind,
|
||||
@Option(names = "--author", defaultValue = "human") String author,
|
||||
@Option(names = "--discussion", defaultValue = "main") String thread,
|
||||
@Option(names = "--responds-to") String respondsTo) {
|
||||
return emit(new DiscussionService().add(root(), id, text, kind, author, thread, respondsTo), Format.markdown);
|
||||
}
|
||||
@Command(name = "list", mixinStandardHelpOptions = true)
|
||||
int list(@Parameters(index = "0") String id, @Option(names = "--format", defaultValue = "markdown") Format format) {
|
||||
return emit(new DiscussionService().list(root(), id), format);
|
||||
}
|
||||
}
|
||||
@Command(name = "decision", mixinStandardHelpOptions = true, description = "Persist draft formal decisions.")
|
||||
public class DecisionCommands {
|
||||
@Command(name = "draft", mixinStandardHelpOptions = true)
|
||||
int draft(@Parameters(index = "0") String id, @Option(names = "--title", required = true) String title,
|
||||
@Option(names = "--context", defaultValue = "") String context,
|
||||
@Option(names = "--approach", defaultValue = "") String approach,
|
||||
@Option(names = "--rationale", defaultValue = "") String rationale,
|
||||
@Option(names = "--evidence") List<String> evidence,
|
||||
@Option(names = "--author", defaultValue = "human") String author) {
|
||||
return emit(new DecisionService().draft(root(), id, title, context, approach, rationale, safe(evidence), author), Format.markdown);
|
||||
}
|
||||
@Command(name = "list", mixinStandardHelpOptions = true)
|
||||
int list(@Parameters(index = "0") String id, @Option(names = "--format", defaultValue = "markdown") Format format) {
|
||||
return emit(new DecisionService().list(root(), id), format);
|
||||
}
|
||||
}
|
||||
@Command(name = "artifact", mixinStandardHelpOptions = true, description = "Attach small evidence files with integrity metadata.")
|
||||
public class ArtifactCommands {
|
||||
@Command(name = "add", mixinStandardHelpOptions = true)
|
||||
int add(@Parameters(index = "0") String id, @Option(names = "--file", required = true) Path file,
|
||||
@Option(names = "--purpose", required = true) String purpose, @Option(names = "--origin") String origin,
|
||||
@Option(names = "--author", defaultValue = "human") String author) {
|
||||
return emit(new ArtifactService().attach(root(), id, resolve(file), purpose, origin, author), Format.markdown);
|
||||
}
|
||||
}
|
||||
private static <T> List<T> safe(List<T> list) { return list == null ? List.of() : list; }
|
||||
}
|
||||
Reference in New Issue
Block a user