feat: scaffold crucible cli module

Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>

Author: joshua-temple

cmd/crucible/go.mod

@@ -0,0 +1,12 @@
+module github.com/stablekernel/crucible/cmd/crucible
+
+go 1.25.11
+
+require (
+	github.com/stablekernel/crucible/gen v0.0.0
+	github.com/stablekernel/crucible/state v0.0.0
+)
+
+replace github.com/stablekernel/crucible/state => ../../state
+
+replace github.com/stablekernel/crucible/gen => ../../gen

cmd/crucible/main.go

@@ -0,0 +1,95 @@
+// Command crucible is a headless command-line tool over the crucible
+// state-machine IR. It lints, renders, diffs, validates, and ejects a machine's
+// serialized IR JSON without running any behavior.
+package main
+
+import (
+	"fmt"
+	"io"
+	"os"
+)
+
+// version is the crucible CLI's own version, independent of the state module's
+// v1 freeze.
+const version = "0.1.0"
+
+// exit codes. 0 is success, 1 a runtime or load error, 2 a usage error, and a
+// non-zero code (1) also signals lint findings.
+const (
+	exitOK       = 0
+	exitError    = 1
+	exitUsage    = 2
+	exitFindings = 1
+)
+
+func main() {
+	os.Exit(run(os.Args[1:], os.Stdout, os.Stderr))
+}
+
+// run dispatches a subcommand and returns its exit code. It is the testable
+// seam: every subcommand is a func(args, stdout, stderr) int, so the whole CLI
+// is exercised without spawning a process.
+func run(args []string, stdout, stderr io.Writer) int {
+	if len(args) == 0 {
+		usage(stderr)
+		return exitUsage
+	}
+
+	cmd, rest := args[0], args[1:]
+	switch cmd {
+	case "lint":
+		return runLint(rest, stdout, stderr)
+	case "render":
+		return runRender(rest, stdout, stderr)
+	case "diff":
+		return runDiff(rest, stdout, stderr)
+	case "validate":
+		return runValidate(rest, stdout, stderr)
+	case "eject":
+		return runEject(rest, stdout, stderr)
+	case "version":
+		emitln(stdout, version)
+		return exitOK
+	case "-version", "--version":
+		emitln(stdout, version)
+		return exitOK
+	case "-h", "--help", "help":
+		usage(stdout)
+		return exitOK
+	default:
+		emitf(stderr, "crucible: unknown subcommand %q\n\n", cmd)
+		usage(stderr)
+		return exitUsage
+	}
+}
+
+// printf, println, and print write diagnostics and command output to an
+// io.Writer. A failure writing to stdout or stderr is unrecoverable for a
+// command-line tool (the stream the user reads is gone), so the error is
+// deliberately ignored here rather than threaded back through every call site.
+func emitf(w io.Writer, format string, a ...any) { _, _ = fmt.Fprintf(w, format, a...) }
+func emitln(w io.Writer, a ...any)               { _, _ = fmt.Fprintln(w, a...) }
+func emit(w io.Writer, a ...any)                 { _, _ = fmt.Fprint(w, a...) }
+
+// usage prints the top-level command listing.
+func usage(w io.Writer) {
+	emit(w, `crucible - headless tooling for the crucible state-machine IR
+
+Usage:
+  crucible <command> [arguments]
+
+Commands:
+  lint      <ir.json>                 run static analysis and report findings
+  render    <ir.json> [-format f]     render the machine as mermaid (default) or dot
+  diff      <old.json> <new.json>     classify changes and recommend a semver bump
+  validate  <ir.json>                 confirm the IR loads and assembles
+  eject     <ir.json> [-package p] [-o f]   generate typed Go behavior stubs
+  version                             print the crucible CLI version
+
+Each command reads an IR JSON file path, or - for stdin.
+
+Flags:
+  -version    print the crucible CLI version
+  -h, --help  show this help
+`)
+}

go.work

@@ -12,6 +12,7 @@ go 1.25.11
 // source modules join the workspace.
 use (
 	./cluster
+	./cmd/crucible
 	./durable
 	./e2e
 	./examples/dispatch