Refactor matr into a modern minimal CLI runtime

[euforic]

Summary

• move the importable library API to the module root and move the binary entrypoint to
• replace the generated task runner with a minimal cobra-like command runtime supporting aliases, local flags, invocation helpers, declarative dependencies, and timeout propagation
• extend Matrfile parsing for comment metadata, expand tests, and update the README/examples to match the new behavior

Test Plan

• go test ./...
• go test -cover ./...
• go vet ./...
• golangci-lint run ./...
• go run ./cmd/matr -no-cache -matrfile ./examples/Matrfile.go -h
• go run ./cmd/matr -no-cache -matrfile ./examples/Matrfile.go build -h

[Copilot]

Pull request overview

This PR refactors matr into a minimal CLI/runtime: the importable API is moved to the module root, the runner behavior is modernized (aliases, deps, command-scoped flags, timeouts), and Matrfile parsing is extended to support comment metadata.

Changes:

• Introduces a new in-process task runtime (Matr, Task, Invocation) with aliases, dependency execution, and command-scoped flags.
• Extends the Matrfile parser to read metadata from // @... comments (aliases, dependencies, flags).
• Adds timeout propagation via a launcher -timeout flag + MATR_TIMEOUT env var and updates docs/examples/tests accordingly.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
matr.go	New minimal runtime: task registry, alias lookup, dependency execution, flag parsing, usage output.
task.go	New task/flag/invocation types for the runtime API.
template.go	Generated runner main.go template updated for the new runtime + timeout context creation.
timeout.go	Adds timeout parsing helper used by the generated runner.
utils.go	Shell execution helper moved to module root.
discovery.go	CLI launcher updated: new flags (including timeout), caching/hash changes, env propagation.
parser/parser.go	Parser now reads docs + @alias/@depends/@<flag> metadata from comments.
parser/metadata_test.go	New tests for metadata parsing and validation.
parser/parser_test.go	Improves temp file cleanup/close handling in tests.
runtime_test.go / usage_test.go / timeout_test.go / discovery_test.go	New/expanded coverage for runtime behavior, usage output, timeouts, and caching helpers.
cmd/matr/main.go	Binary entrypoint updated to import module-root matr.
examples/Matrfile.go	Example updated to new handler signature + metadata comments.
README.md	Docs updated for new CLI flags, metadata format, and help output.
go.mod	Updates Go version declaration (currently set to an invalid version).

Comments suppressed due to low confidence (2)

discovery.go:219

• buildHashInputs hashes source files resolved via runtime.Caller(0). In installed/distributed binaries those source paths may not exist (e.g. after go clean -modcache or when built in CI and copied elsewhere), causing cache builds to fail at runtime. Consider hashing the currently running executable (os.Executable()), or using debug.ReadBuildInfo()/module version + executable mtime as the runtime input instead of opening source files.
  discovery.go:74
• On runner execution failure (run(...) returning an error), the CLI prints the error but exits with status 0. This breaks CI/pipelines expecting task failures to propagate. After printing, call os.Exit(1) (or return an error from Run and have main exit non-zero).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[euforic]

Addressed the two non-thread review notes as well: discovery.go now exits non-zero when launcher build/run steps fail, and cache invalidation now hashes the running executable instead of reopening source paths via runtime.Caller, which avoids failures after source paths disappear.