Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add inspect and view commands to CLI
Yuechen Lie342680809b3
diff --git a/Aetheris.CLI.Tests/AirTraceCommandTests.cs b/Aetheris.CLI.Tests/AirTraceCommandTests.csindex 959df643..31eaa645 100644--- a/Aetheris.CLI.Tests/AirTraceCommandTests.cs+++ b/Aetheris.CLI.Tests/AirTraceCommandTests.cs@@ -9,7 +9,7 @@ public sealed class AirTraceCommandTests{var stdout = new StringWriter(); var stderr = new StringWriter();Assert.Equal(0, Aetheris.CLI.CliRunner.Run(["--help"], stdout, stderr));- Assert.Contains("trace", stdout.ToString(), StringComparison.Ordinal);+ Assert.DoesNotContain("trace", stdout.ToString(), StringComparison.Ordinal);stdout = new StringWriter(); stderr = new StringWriter();Assert.Equal(0, Aetheris.CLI.CliRunner.Run(["trace", "--help"], stdout, stderr));diff --git a/Aetheris.CLI.Tests/CanonicalCliWorkflowTests.cs b/Aetheris.CLI.Tests/CanonicalCliWorkflowTests.csnew file mode 100644index 00000000..d8a4c618--- /dev/null+++ b/Aetheris.CLI.Tests/CanonicalCliWorkflowTests.cs@@ -0,0 +1,71 @@+using System.Text.Json;++namespace Aetheris.CLI.Tests;++public sealed class CanonicalCliWorkflowTests+{+ [Fact]+ public void Build_Defaults_To_Adjacent_Step_And_Reports_It()+ {+ var directory = Path.Combine(Path.GetTempPath(), "aetheris cli space " + Guid.NewGuid().ToString("N"));+ Directory.CreateDirectory(directory);+ var source = Path.Combine(directory, "plate.firmament");+ var output = Path.ChangeExtension(source, ".step");+ File.WriteAllText(source, """+ Model Plate {+ Units: mm+ Box Body { Size: [10mm, 20mm, 3mm] }+ }+ """);++ try+ {+ var stdout = new StringWriter();+ var stderr = new StringWriter();+ var exitCode = Aetheris.CLI.CliRunner.Run(["build", source], stdout, stderr);++ Assert.Equal(0, exitCode);+ Assert.True(File.Exists(output), stderr.ToString());+ Assert.Contains("STEP: " + output, stdout.ToString(), StringComparison.Ordinal);+ }+ finally { if (Directory.Exists(directory)) Directory.Delete(directory, recursive: true); }+ }++ [Fact]+ public void Inspect_Firmament_Reports_Semantic_Model_As_Json()+ {+ var source = Path.Combine(Path.GetTempPath(), $"inspect-{Guid.NewGuid():N}.firmament");+ File.WriteAllText(source, """+ Model Plate {+ Units: mm+ Box Body { Size: [10mm, 20mm, 3mm] }+ }+ """);+ try+ {+ var stdout = new StringWriter();+ var stderr = new StringWriter();+ var exitCode = Aetheris.CLI.CliRunner.Run(["inspect", source, "--json"], stdout, stderr);++ Assert.Equal(0, exitCode);+ Assert.True(string.IsNullOrWhiteSpace(stderr.ToString()));+ using var document = JsonDocument.Parse(stdout.ToString());+ Assert.Equal("inspect", document.RootElement.GetProperty("command").GetString());+ Assert.True(document.RootElement.GetProperty("success").GetBoolean());+ Assert.Equal("Plate", document.RootElement.GetProperty("model").GetString());+ }+ finally { File.Delete(source); }+ }++ [Fact]+ public void Analyze_Rejects_Firmament_With_A_Clear_Route_Hint()+ {+ var stdout = new StringWriter();+ var stderr = new StringWriter();++ var exitCode = Aetheris.CLI.CliRunner.Run(["analyze", "part.firmament"], stdout, stderr);++ Assert.Equal(1, exitCode);+ Assert.Contains("STEP", stderr.ToString(), StringComparison.OrdinalIgnoreCase);+ }+}diff --git a/Aetheris.CLI.Tests/CliBaselineTests.cs b/Aetheris.CLI.Tests/CliBaselineTests.csindex 18b5113c..dd526dc3 100644--- a/Aetheris.CLI.Tests/CliBaselineTests.cs+++ b/Aetheris.CLI.Tests/CliBaselineTests.cs@@ -28,7 +28,7 @@ public sealed class CliBaselineTestsAssert.Equal(0, exitCode);Assert.True(File.Exists(outputPath), stderr.ToString());- Assert.Contains("Build succeeded", stdout.ToString());+ Assert.Contains("Built box_basic.firmament", stdout.ToString());File.Delete(outputPath);}diff --git a/Aetheris.CLI.Tests/CliHelpAndUsageTests.cs b/Aetheris.CLI.Tests/CliHelpAndUsageTests.csindex ffd0acf3..fafe7dd4 100644--- a/Aetheris.CLI.Tests/CliHelpAndUsageTests.cs+++ b/Aetheris.CLI.Tests/CliHelpAndUsageTests.cs@@ -20,14 +20,14 @@ public sealed class CliHelpAndUsageTestsAssert.Equal(0, exitCode);Assert.True(string.IsNullOrWhiteSpace(stderr.ToString()));var text = stdout.ToString();- Assert.Contains("Usage: aetheris <build|analyze|trace|canon|asm|experimental>", text, StringComparison.Ordinal);+ Assert.Contains("Usage: aetheris <command> [options]", text, StringComparison.Ordinal);Assert.Contains("Commands:", text, StringComparison.Ordinal);Assert.Contains("build", text, StringComparison.Ordinal);Assert.Contains("analyze", text, StringComparison.Ordinal);- Assert.Contains("trace", text, StringComparison.Ordinal);- Assert.Contains("canon", text, StringComparison.Ordinal);- Assert.Contains("asm", text, StringComparison.Ordinal);- Assert.Contains("experimental", text, StringComparison.Ordinal);+ Assert.Contains("validate", text, StringComparison.Ordinal);+ Assert.Contains("inspect", text, StringComparison.Ordinal);+ Assert.Contains("verify", text, StringComparison.Ordinal);+ Assert.Contains("view", text, StringComparison.Ordinal);}[Theory]diff --git a/Aetheris.CLI/CliRunner.cs b/Aetheris.CLI/CliRunner.csindex bf6dbda9..8a34a3ef 100644--- a/Aetheris.CLI/CliRunner.cs+++ b/Aetheris.CLI/CliRunner.cs@@ -114,8 +114,8 @@ public static class CliRunnerstring? Error,string? Classification = null,int? RigidRootCount = null);- private const string TopLevelUsage = "Usage: aetheris <build|validate|inspect-profile|inspect-compose|inspect-selections|sections|analyze|verify|match|trace|canon|asm|experimental> <path> [options]";- private const string BuildUsage = "Usage: aetheris build <file.firmament> [--out <path>] [--json]";+ private const string TopLevelUsage = "Usage: aetheris <command> [options]";+ private const string BuildUsage = "Usage: aetheris build <file.firmament> [--output <path>] [--json]";private const string ValidateUsage = "Usage: aetheris validate <file.firmament|file.firmfixture> [--forge-pack <path>] [--json]";private const string InspectProfileUsage = "Usage: aetheris inspect-profile <file.firmament> [--json]";private const string InspectComposeUsage = "Usage: aetheris inspect-compose <file.firmament> --json [--materialize]";@@ -126,7 +126,9 @@ public static class CliRunnerprivate const string AnalyzeVolumeUsage = "Usage: aetheris analyze volume <file.step> [--approximate --resolution <N>] [--json]";private const string AnalyzeCompareUsage = "Usage: aetheris analyze compare <reference.step> <candidate.step> [--approximate-volume --resolution <N>] [--json]";private const string SectionsUsage = "Usage: aetheris sections <artifact.step> --axis Z --levels <z,...> [--epsilon <mm>] --json";- private const string VerifyUsage = "Usage: aetheris verify <artifact.step> [--expected-volume <value>] [--cad-assistant] [--cad-assistant-path <path>] [--timeout <seconds>] [--evidence-dir <path>] [--require-external] [--json]";+ private const string VerifyUsage = "Usage: aetheris verify <file.firmament|file.step> [--expected-volume <value>] [--cad-assistant] [--cad-assistant-path <path>] [--timeout <seconds>] [--evidence-dir <path>] [--require-external] [--json]";+ private const string InspectUsage = "Usage: aetheris inspect <file.firmament|file.step> [--json]";+ private const string ViewUsage = "Usage: aetheris view <file.firmament|file.step> [--cad-assistant-path <path>] [--json]";private const string MatchUsage = "Usage: aetheris match <file.step> <concept.firmament> [--linear-tolerance <mm>] [--angular-tolerance <deg>] [--json]";private const string TraceUsage = "Usage: aetheris trace (--case <name>|--fixture <path>) [--out-dir <dir>] [--json]";private const string CanonUsage = "Usage: aetheris canon <file.step> --out <canonical.step> [--mode deterministic|production] [--json]";@@ -177,12 +179,14 @@ public static class CliRunner{"build" => RunBuild(args.Skip(1).ToArray(), stdout, stderr),"validate" => RunValidate(args.Skip(1).ToArray(), stdout, stderr),+ "inspect" => RunInspect(args.Skip(1).ToArray(), stdout, stderr),"inspect-profile" => RunInspectProfile(args.Skip(1).ToArray(), stdout, stderr),"inspect-compose" => RunInspectCompose(args.Skip(1).ToArray(), stdout, stderr),"inspect-selections" => RunInspectSelections(args.Skip(1).ToArray(), stdout, stderr),"sections" => RunSections(args.Skip(1).ToArray(), stdout, stderr),"analyze" => RunAnalyze(args.Skip(1).ToArray(), stdout, stderr),"verify" => RunVerify(args.Skip(1).ToArray(), stdout, stderr),+ "view" => RunView(args.Skip(1).ToArray(), stdout, stderr),"match" => RunMatch(args.Skip(1).ToArray(), stdout, stderr),"trace" => RunTrace(args.Skip(1).ToArray(), stdout, stderr),"canon" => RunCanon(args.Skip(1).ToArray(), stdout, stderr),@@ -223,6 +227,22 @@ public static class CliRunnerdefault: stderr.WriteLine($"Unknown verify option '{args[i]}'."); stderr.WriteLine(VerifyUsage); return 1;}}+ if (string.Equals(Path.GetExtension(stepPath), ".firmament", StringComparison.OrdinalIgnoreCase))+ {+ var build = FirmamentBuildAndExport.Run(stepPath);+ if (!build.IsSuccess)+ {+ if (json) stdout.WriteLine(JsonSerializer.Serialize(new { command = "verify", success = false, input = Path.GetFullPath(stepPath), diagnostics = build.Diagnostics.Select(d => new { d.Source, d.Message, severity = d.Severity.ToString() }) }, JsonOptions));+ else { stderr.WriteLine("Verification stopped because build failed."); foreach (var diagnostic in build.Diagnostics) stderr.WriteLine($"error: {diagnostic.Message}"); }+ return 1;+ }+ stepPath = build.Value.OutputPath;+ }+ else if (!string.Equals(Path.GetExtension(stepPath), ".step", StringComparison.OrdinalIgnoreCase) && !string.Equals(Path.GetExtension(stepPath), ".stp", StringComparison.OrdinalIgnoreCase))+ {+ stderr.WriteLine("Verify expects Firmament (.firmament) or STEP (.step, .stp) input.");+ return 1;+ }if (!File.Exists(stepPath)) { stderr.WriteLine($"STEP artifact '{stepPath}' does not exist."); return 1; }var fullPath = Path.GetFullPath(stepPath);var hash = Convert.ToHexString(SHA256.HashData(File.ReadAllBytes(fullPath))).ToLowerInvariant();@@ -335,11 +355,13 @@ public static class CliRunner{switch (args[i]){- case "--out" when i + 1 < args.Length:+ case "--output" when i + 1 < args.Length:+ case "--out" when i + 1 < args.Length: // Compatibility alias; prefer --output in public help.outPath = args[++i];break;+ case "--output":case "--out":- stderr.WriteLine("Build option --out requires a path value.");+ stderr.WriteLine("Build option --output requires a path value.");stderr.WriteLine(BuildUsage);return 1;case "--json":@@ -363,7 +385,9 @@ public static class CliRunner{stdout.WriteLine(JsonSerializer.Serialize(new{+ command = "build",success = false,+ input = Path.GetFullPath(sourcePath),diagnostics = build.Diagnostics.Select(d => new { d.Source, d.Message, severity = d.Severity.ToString() })}, JsonOptions));}@@ -383,7 +407,10 @@ public static class CliRunner{stdout.WriteLine(JsonSerializer.Serialize(new{+ command = "build",success = true,+ input = build.Value.SourcePath,+ output = build.Value.OutputPath,sourcePath = build.Value.SourcePath,outputPath = build.Value.OutputPath,conceptIr = build.Value.Export.ConceptIr,@@ -405,12 +432,123 @@ public static class CliRunner}else{- stdout.WriteLine($"Build succeeded: {build.Value.OutputPath}");+ stdout.WriteLine($"Built {Path.GetFileName(build.Value.SourcePath)}");+ stdout.WriteLine($"STEP: {build.Value.OutputPath}");+ stdout.WriteLine($"Model: {build.Value.Export.ExportedFeatureId}");}return 0;}+ private static int RunInspect(string[] args, TextWriter stdout, TextWriter stderr)+ {+ if (args.Length == 0 || IsHelpFlag(args[0]))+ {+ WriteInspectHelp(stdout);+ return args.Length == 0 ? 1 : 0;+ }++ var input = args[0];+ var json = args.Skip(1).SequenceEqual(["--json"]);+ if (!json && args.Length > 1) { stderr.WriteLine($"Unknown inspect option '{args[1]}'."); stderr.WriteLine(InspectUsage); return 1; }+ if (!File.Exists(input)) { stderr.WriteLine($"Inspect input was not found: {input}"); return 1; }++ var fullPath = Path.GetFullPath(input);+ var extension = Path.GetExtension(fullPath);+ if (string.Equals(extension, ".step", StringComparison.OrdinalIgnoreCase) || string.Equals(extension, ".stp", StringComparison.OrdinalIgnoreCase))+ return RunAnalyze([fullPath, .. args.Skip(1)], stdout, stderr);+ if (!string.Equals(extension, ".firmament", StringComparison.OrdinalIgnoreCase))+ {+ stderr.WriteLine("Inspect expects Firmament (.firmament) or STEP (.step, .stp) input.");+ return 1;+ }++ var parse = FirmamentV2Parser.Parse(File.ReadAllText(fullPath), Path.GetDirectoryName(fullPath));+ var document = parse.Document;+ var success = parse.IsSuccess && document is not null;+ var features = document?.ModifyBlocks?.SelectMany(block =>+ block.SemanticHoles.Select(hole => $"Hole<{hole.Variant}> {hole.Name}")+ .Concat((block.EdgeFinishes ?? []).Select(finish => $"{finish.Kind} {finish.Name}"))) ?? [];+ var report = new+ {+ command = "inspect",+ success,+ input = fullPath,+ model = document?.ModelName,+ units = document?.Units,+ bodies = document?.Solids.Select(solid => new { name = solid.Name, kind = solid.RecordType }).ToArray() ?? [],+ features,+ pmi = document?.Pmi?.Select(item => new { item.Kind, item.Name, item.Target }).ToArray() ?? [],+ assertions = document?.VolumeAssertions?.Select(assertion => new { assertion.Id, assertion.TargetBodyId, assertion.ExpectedMm3, assertion.ToleranceMm3 }).ToArray() ?? [],+ diagnostics = parse.Diagnostics.Order(StringComparer.Ordinal).ToArray()+ };+ if (json) stdout.WriteLine(JsonSerializer.Serialize(report, JsonOptions));+ else if (!success)+ {+ stderr.WriteLine($"Inspect failed for {fullPath}.");+ foreach (var diagnostic in parse.Diagnostics.Order(StringComparer.Ordinal)) stderr.WriteLine($"error: {diagnostic}");+ }+ else+ {+ stdout.WriteLine($"Model: {document!.ModelName}");+ stdout.WriteLine($"Bodies: {document.Solids.Count}");+ foreach (var feature in features) stdout.WriteLine($"Feature: {feature}");+ foreach (var item in document.Pmi ?? []) stdout.WriteLine($"PMI: {item.Kind} {item.Name}");+ foreach (var assertion in document.VolumeAssertions ?? []) stdout.WriteLine($"Assertion: Volume {assertion.TargetBodyId}");+ }+ return success ? 0 : 1;+ }++ private static int RunView(string[] args, TextWriter stdout, TextWriter stderr)+ {+ if (args.Length == 0 || IsHelpFlag(args[0])) { WriteViewHelp(stdout); return args.Length == 0 ? 1 : 0; }+ var input = args[0];+ string? executable = null;+ var json = false;+ for (var i = 1; i < args.Length; i++)+ {+ if (args[i] == "--cad-assistant-path" && i + 1 < args.Length) { executable = args[++i]; continue; }+ if (args[i] == "--json") { json = true; continue; }+ stderr.WriteLine($"Unknown view option '{args[i]}'."); stderr.WriteLine(ViewUsage); return 1;+ }+ if (!File.Exists(input)) { stderr.WriteLine($"View input was not found: {input}"); return 1; }+ var fullInput = Path.GetFullPath(input);+ var extension = Path.GetExtension(fullInput);+ string stepPath;+ if (string.Equals(extension, ".firmament", StringComparison.OrdinalIgnoreCase))+ {+ var build = FirmamentBuildAndExport.Run(fullInput);+ if (!build.IsSuccess)+ {+ if (json) stdout.WriteLine(JsonSerializer.Serialize(new { command = "view", success = false, input = fullInput, diagnostics = build.Diagnostics.Select(d => new { d.Source, d.Message, severity = d.Severity.ToString() }) }, JsonOptions));+ else { stderr.WriteLine("View stopped because build failed."); foreach (var diagnostic in build.Diagnostics) stderr.WriteLine($"error: {diagnostic.Message}"); }+ return 1;+ }+ stepPath = build.Value.OutputPath;+ }+ else if (string.Equals(extension, ".step", StringComparison.OrdinalIgnoreCase) || string.Equals(extension, ".stp", StringComparison.OrdinalIgnoreCase)) stepPath = fullInput;+ else { stderr.WriteLine("View expects Firmament (.firmament) or STEP (.step, .stp) input."); return 1; }++ var resolvedExecutable = CadAssistantInspection.ResolveExecutable(executable);+ if (resolvedExecutable is null)+ {+ const string message = "Cadmata/CAD Assistant was not found. Set --cad-assistant-path or AETHERIS_CAD_ASSISTANT_PATH.";+ if (json) stdout.WriteLine(JsonSerializer.Serialize(new { command = "view", success = false, input = fullInput, output = stepPath, diagnostics = new[] { message } }, JsonOptions));+ else stderr.WriteLine(message);+ return 1;+ }+ try+ {+ var startInfo = new ProcessStartInfo(resolvedExecutable) { UseShellExecute = true };+ startInfo.ArgumentList.Add(stepPath);+ if (Process.Start(startInfo) is null) throw new InvalidOperationException("Process.Start returned no process.");+ }+ catch (Exception ex) { stderr.WriteLine($"Could not open '{stepPath}' in Cadmata/CAD Assistant: {ex.Message}"); return 1; }+ if (json) stdout.WriteLine(JsonSerializer.Serialize(new { command = "view", success = true, input = fullInput, output = stepPath, launcher = resolvedExecutable }, JsonOptions));+ else stdout.WriteLine($"Opened {stepPath} in Cadmata/CAD Assistant.");+ return 0;+ }+private static int RunInspectProfile(string[] args, TextWriter stdout, TextWriter stderr){@@ -1391,6 +1529,17 @@ public static class CliRunnerreturn 1;}+ if (string.Equals(Path.GetExtension(stepPath), ".firmament", StringComparison.OrdinalIgnoreCase))+ {+ stderr.WriteLine("Analyze expects STEP; use `aetheris build <file.firmament>` first.");+ return 1;+ }+ if (!string.Equals(Path.GetExtension(stepPath), ".step", StringComparison.OrdinalIgnoreCase) && !string.Equals(Path.GetExtension(stepPath), ".stp", StringComparison.OrdinalIgnoreCase))+ {+ stderr.WriteLine("Analyze expects STEP (.step or .stp) input.");+ return 1;+ }+AnalyzeResult analysis;try{@@ -2761,7 +2910,7 @@ public static class CliRunnerprivate static int UnknownCommand(string command, TextWriter stderr){- stderr.WriteLine($"Unknown command '{command}'. Expected one of: build, validate, analyze, trace, canon, asm, experimental.");+ stderr.WriteLine($"Unknown command '{command}'. Expected one of: validate, build, inspect, analyze, verify, view.");stderr.WriteLine("Run 'aetheris --help' for usage and examples.");return 1;}@@ -2807,52 +2956,27 @@ public static class CliRunnerprivate static void WriteTopLevelHelp(TextWriter stdout){- stdout.WriteLine("aetheris - firmament build and STEP analysis CLI");+ stdout.WriteLine("Aetheris — exact code-first CAD");stdout.WriteLine();stdout.WriteLine(TopLevelUsage);- // Keep this stable discovery string while the longer usage line above- // advertises the newer inspection commands.- stdout.WriteLine("Usage: aetheris <build|analyze|trace|canon|asm|experimental> <path> [options]");stdout.WriteLine();stdout.WriteLine("Commands:");- stdout.WriteLine(" build Build a .firmament source file into STEP.");- stdout.WriteLine(" validate Validate Firmament V2 manufacturing intent and emit report JSON.");- stdout.WriteLine(" inspect-profile Resolve and validate a scaffold-referenced Profile.");- stdout.WriteLine(" inspect-compose Normalize and inspect a profile-composition section stack.");- stdout.WriteLine(" inspect-selections Resolve source-grounded topology selections without STEP analysis.");- stdout.WriteLine(" sections Normalize exact horizontal STEP section fragments.");- stdout.WriteLine(" analyze Analyze STEP topology, geometry, map, and sections.");- stdout.WriteLine(" verify Reimport STEP and emit independent B-rep/external-display evidence.");- stdout.WriteLine(" match Match a compile-time Concept Struct against observed STEP geometry.");- stdout.WriteLine(" trace Trace built-in AIR lowering cases through route, BRepPlan, STEP smoke, and CIR mirror.");- stdout.WriteLine(" canon Import and re-export STEP/AP242 as canonical STEP.");- stdout.WriteLine(" asm Execute/export .firmasm assembly IR using rigid world-space composition.");- stdout.WriteLine(" experimental Experimental/lab-only artifact export and generated-source inspection commands.");+ stdout.WriteLine(" validate Check Firmament source without materializing geometry.");+ stdout.WriteLine(" build Compile Firmament to exact STEP AP242.");+ stdout.WriteLine(" view Build/open a model in Cadmata or CAD Assistant.");+ stdout.WriteLine(" inspect Inspect Firmament semantics or STEP topology.");+ stdout.WriteLine(" analyze Analyze STEP topology and analytic surfaces.");+ stdout.WriteLine(" verify Build/reimport and verify a model.");stdout.WriteLine();stdout.WriteLine("Global options:");stdout.WriteLine(" -h, --help Show help.");stdout.WriteLine(" -v, --version Show CLI version.");stdout.WriteLine();stdout.WriteLine("Examples:");- stdout.WriteLine(" aetheris build model.firmament --out model.step");- stdout.WriteLine(" aetheris validate fixtures/FirmamentV2/Language/valid/v2-phase1-validation-report.valid.firmfixture --json");- stdout.WriteLine(" aetheris inspect-profile fixtures/FirmamentV2/Profile/valid/scaffold-rectangle.firmament --json");- stdout.WriteLine(" aetheris analyze model.step");- stdout.WriteLine(" aetheris analyze model.step --json");- stdout.WriteLine(" aetheris match model.step concept.firmament --json");- stdout.WriteLine(" aetheris trace --case top-face-loop-chamfer");- stdout.WriteLine(" aetheris trace --fixture fixtures/Firmament/Chamfer/valid/top-face-loop-chamfer.valid.firmfixture");- stdout.WriteLine(" aetheris trace --case prismatic-section-transition --json");- stdout.WriteLine(" aetheris canon input.step --out canonical.step --mode production --json");- stdout.WriteLine(" aetheris asm exec assembly.firmasm --json");- stdout.WriteLine(" aetheris asm export assembly.firmasm --out out/assembly-roundtrip --json");- stdout.WriteLine(" aetheris experimental airchamfer-cube --out edge-x10-airchamfer-cube-one-edge.step --json");- stdout.WriteLine(" aetheris experimental prismatic-map --case rectangle-inset --rows 16 --cols 16 --json");- stdout.WriteLine(" aetheris analyze map model.step --top --rows 40 --cols 60 --json");- stdout.WriteLine(" aetheris analyze section model.step --xy --offset 2.5 --json");- stdout.WriteLine(" aetheris sections model.step --axis Z --levels -100,-60,-50,0,5,50 --json");- stdout.WriteLine(" aetheris analyze volume model.step --json");- stdout.WriteLine(" aetheris verify model.step --json");+ stdout.WriteLine(" aetheris validate bracket.firmament");+ stdout.WriteLine(" aetheris build bracket.firmament");+ stdout.WriteLine(" aetheris view bracket.firmament");+ stdout.WriteLine(" aetheris analyze imported.step --json");stdout.WriteLine();stdout.WriteLine("Run 'aetheris <command> --help' for command-specific usage.");}@@ -2864,12 +2988,13 @@ public static class CliRunnerstdout.WriteLine(BuildUsage);stdout.WriteLine();stdout.WriteLine("Options:");- stdout.WriteLine(" --out <path> Optional output STEP path.");+ stdout.WriteLine(" --output <path> Optional output STEP path; defaults to a .step file beside the source.");stdout.WriteLine(" --json Emit machine-readable success/failure JSON.");stdout.WriteLine(" -h, --help Show this help.");stdout.WriteLine();stdout.WriteLine("Example:");- stdout.WriteLine(" aetheris build part.firmament --out part.step --json");+ stdout.WriteLine(" aetheris build part.firmament");+ stdout.WriteLine(" aetheris build part.firmament --output out/part.step --json");}private static void WriteMatchHelp(TextWriter stdout)@@ -2886,11 +3011,32 @@ public static class CliRunnerprivate static void WriteValidateHelp(TextWriter stdout){+ stdout.WriteLine("Check syntax, binding, dimensions, and static semantics without materializing geometry.");+ stdout.WriteLine("Use build for materialization, STEP generation, and build-time assertions.");+ stdout.WriteLine();stdout.WriteLine(ValidateUsage);stdout.WriteLine(" --json Emit Firmament V2 validation report JSON.");stdout.WriteLine(" --forge-pack <path> Load a trusted local .NET assembly containing IForgeConceptPack implementations. This executes local code; Aetheris does not sandbox external packs. Do not load untrusted packs.");}+ private static void WriteInspectHelp(TextWriter stdout)+ {+ stdout.WriteLine("Inspect what Aetheris understands a model to mean.");+ stdout.WriteLine("Firmament input reports semantic declarations; STEP input reports topology through analyze.");+ stdout.WriteLine();+ stdout.WriteLine(InspectUsage);+ stdout.WriteLine("Example: aetheris inspect part.firmament --json");+ }++ private static void WriteViewHelp(TextWriter stdout)+ {+ stdout.WriteLine("Open a STEP model in Cadmata/CAD Assistant.");+ stdout.WriteLine("Firmament input is built to its adjacent .step artifact before launch; STEP input opens directly.");+ stdout.WriteLine();+ stdout.WriteLine(ViewUsage);+ stdout.WriteLine("Example: aetheris view part.firmament");+ }+private static void WriteTraceHelp(TextWriter stdout){stdout.WriteLine("Trace a built-in Aetheris lowering case through AIR, route selection, BRepPlan, emitted BRep/STEP smoke, and CIR mirror admission. Use `analyze` for existing STEP/BRep geometry.");@@ -3013,7 +3159,7 @@ public static class CliRunner{stdout.WriteLine(VerifyUsage);stdout.WriteLine();- stdout.WriteLine("Reimport a STEP artifact, evaluate independent B-rep mass properties, and optionally run bounded external CAD display inspection.");+ stdout.WriteLine("Firmament input is built first; STEP input is reimported directly for independent B-rep mass properties and optional external display inspection.");stdout.WriteLine("The report is hash-tied to artifacts/verification/<fixture>/<sha256>/ by default.");stdout.WriteLine();stdout.WriteLine("Options:");diff --git a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.csindex e33c3890..19d0ddfa 100644--- a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs+++ b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs@@ -1723,25 +1723,10 @@ public static class FirmamentBuildAndExportprivate static string ResolveDefaultOutputPath(string fullSourcePath){- var root = FindRepositoryRoot(Path.GetDirectoryName(fullSourcePath)!);- var sourceFileName = Path.GetFileNameWithoutExtension(fullSourcePath);- return Path.Combine(root, "testdata", "firmament", "exports", sourceFileName + ".step");- }-- private static string FindRepositoryRoot(string startDirectory)- {- var directory = new DirectoryInfo(startDirectory);- while (directory is not null)- {- if (File.Exists(Path.Combine(directory.FullName, "Aetheris.slnx")))- {- return directory.FullName;- }-- directory = directory.Parent;- }-- throw new InvalidOperationException("Unable to locate repository root for Firmament export output.");+ // A source file is the only project boundary Preview 1 needs. Keeping the+ // generated artifact adjacent to it is deterministic, discoverable, and+ // works identically from a checkout, a package, or a user directory.+ return Path.ChangeExtension(fullSourcePath, ".step");}private static string NormalizeLf(string value) =>diff --git a/docs/release/p1-cli-ux-m1-audit.md b/docs/release/p1-cli-ux-m1-audit.mdnew file mode 100644index 00000000..55dbe7fb--- /dev/null+++ b/docs/release/p1-cli-ux-m1-audit.md@@ -0,0 +1,47 @@+# P1-CLI-UX-M1 CLI audit++## Baseline++The previous root help mixed public authoring work with internal/lab commands+(`trace`, `canon`, `asm`, `experimental`, and specialized inspection routes).+`build` advertised `--out`, while its implicit output searched for an+`Aetheris.slnx` checkout and wrote beneath `testdata/firmament/exports`.+That made a normal user directory fail despite the compiler otherwise being+file-oriented. `verify` accepted only an existing STEP artifact. There was no+public `inspect` or `view` command.++## Preview 1 public surface++The root help now presents only `validate`, `build`, `view`, `inspect`,+`analyze`, and `verify`. Existing specialized commands and `build --out` stay+available as compatibility/internal routes but are intentionally absent from+primary discovery. `--output` is the documented spelling.++Input policy is explicit: Firmament is accepted by validate/build/inspect/+verify/view; STEP (`.step` or `.stp`) is accepted by inspect/analyze/verify/+view. `analyze` rejects Firmament with a build-first hint. Build defaults to a+same-directory `.step` file and deterministically replaces compiler-generated+output; `--output` can select another path and its parent is created.++`validate` remains parse/bind/static-semantic validation and does not perform+materialization. `build` materializes, exports STEP, and evaluates existing+build-time assertions. `verify source.firmament` builds first, then uses the+existing STEP reimport verification route. `inspect` reports parsed Firmament+semantics or delegates STEP input to topology analysis.++## View and packaging boundary++`view source.firmament` builds its adjacent STEP artifact, and `view artifact.step`+opens directly. The narrow handoff starts the configured CAD Assistant/Cadmata+executable with the STEP path. Resolution uses `--cad-assistant-path`, then+`AETHERIS_CAD_ASSISTANT_PATH`, then established CAD Assistant install paths.+There is no existing-instance IPC: Preview 1 starts a new process. No executable+was available on the development machine for a GUI smoke, so packaging/Cadmata+delivery remains the P1-CADMATA-M1 / P1-PACKAGE-M1 boundary.++## Evidence++The clean-directory smoke uses the built CLI DLL from a temporary directory+containing only `plate.firmament`. Help, version, validate, build, inspect,+verify, and analyze succeeded; build emitted adjacent `plate.step`. `view`+correctly stopped with the actionable missing-launcher diagnostic.