Scaffold read-only sourceosctl CLI

Adds a conservative read-only/dry-run sourceosctl CLI scaffold with fixtures, tests, validation, and documentation.

Closes #1.

Author: Copilot

.gitignore

@@ -0,0 +1,13 @@
+# Python bytecode
+__pycache__/
+*.py[cod]
+*.pyo
+
+# Distribution / packaging
+*.egg-info/
+dist/
+build/
+
+# Temporary files
+*.tmp
+.DS_Store

Makefile

@@ -1,22 +1,12 @@
-.PHONY: validate
+.PHONY: validate test
 
-validate:
+validate: test
 	@test -f README.md
 	@test -f AGENTS.md
 	@test -f .github/copilot-instructions.md
 	@test -f docs/DEVTOOLS_SCOPE.md
 	@test -f repo.maturity.yaml
-	@python3 - <<'PY'
-import pathlib
-for path in [
-    'README.md',
-    'AGENTS.md',
-    '.github/copilot-instructions.md',
-    'docs/DEVTOOLS_SCOPE.md',
-    'repo.maturity.yaml',
-]:
-    text = pathlib.Path(path).read_text()
-    if not text.strip():
-        raise SystemExit(f'{path} is empty')
-print('OK: sourceos-devtools validation')
-PY
+	@python3 scripts/validate_scaffold.py
+
+test:
+	@python3 -m unittest discover -s tests -v

README.md

@@ -34,6 +34,45 @@ It should not contain:
 - SourceOS image build state;
 - secrets, tokens, credentials, private keys, or device-specific enrollment secrets.
 
+## sourceosctl CLI
+
+`sourceosctl` is the read-only/dry-run CLI surface for SourceOS developer and AI operator workflows.
+
+### Usage
+
+```text
+sourceosctl [--version] <command> [<subcommand>] [options]
+```
+
+### Commands
+
+| Command | Description |
+| --- | --- |
+| `sourceosctl doctor` | Run environment health checks (read-only) |
+| `sourceosctl profiles list` | List available SourceOS profiles (read-only) |
+| `sourceosctl nlboot evidence inspect <path>` | Inspect a NLBoot evidence JSON file (read-only) |
+| `sourceosctl release inspect <path>` | Inspect a release artifact JSON file (read-only) |
+| `sourceosctl fingerprint collect --dry-run` | Print environment fingerprint fields (dry-run only) |
+| `sourceosctl ai labs list` | List available AI labs (read-only) |
+| `sourceosctl agents sandbox plan --dry-run` | Print agent sandbox plan (dry-run only) |
+
+### Running from the repo
+
+```bash
+python3 bin/sourceosctl --help
+python3 bin/sourceosctl doctor
+python3 bin/sourceosctl profiles list
+python3 bin/sourceosctl nlboot evidence inspect fixtures/sample_nlboot_evidence.json
+python3 bin/sourceosctl release inspect fixtures/sample_release.json
+python3 bin/sourceosctl fingerprint collect --dry-run
+python3 bin/sourceosctl ai labs list
+python3 bin/sourceosctl agents sandbox plan --dry-run
+```
+
+### Design constraints
+
+All commands in the current surface are **read-only or dry-run**. No mutating command is implemented. Commands that would mutate host state are explicitly rejected at runtime.
+
 ## First milestone
 
 M1 is repo maturity and install surface definition:
@@ -62,4 +101,9 @@ M1 is repo maturity and install surface definition:
 make validate
 ```
 
-The initial validation target checks repository metadata and JSON/YAML syntax where present. Implementation-specific validation should be added with each tool surface.
+The validation target runs the unit test suite and checks repository metadata. All 21 tests must pass.
+
+```bash
+make test   # run tests only
+```
+

bin/sourceosctl

@@ -0,0 +1,11 @@
+#!/usr/bin/env python3
+"""sourceosctl entry-point script."""
+import sys
+import os
+
+# Allow running directly from the repo root without installing.
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from sourceosctl.cli import main
+
+sys.exit(main())

fixtures/sample_nlboot_evidence.json

@@ -0,0 +1,17 @@
+{
+  "schemaVersion": "nlboot-evidence.v1",
+  "kind": "NLBootEvidence",
+  "timestamp": "2025-01-01T00:00:00Z",
+  "target": {
+    "host": "example-host",
+    "arch": "x86_64",
+    "uefi": true
+  },
+  "boot": {
+    "loader": "systemd-boot",
+    "kernel": "6.6.0-sourceos",
+    "cmdline": "root=/dev/sda1 ro quiet"
+  },
+  "status": "verified",
+  "signature": "stub-signature-not-real"
+}

fixtures/sample_release.json

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": "sourceos-release.v1",
+  "name": "sourceos-devtools",
+  "version": "0.1.0",
+  "channel": "stable",
+  "artifacts": [
+    "sourceosctl-0.1.0-linux-x86_64.tar.gz",
+    "sourceosctl-0.1.0-darwin-arm64.tar.gz"
+  ],
+  "metadata": {
+    "gitRef": "refs/heads/main",
+    "builtAt": "2025-01-01T00:00:00Z"
+  }
+}

scripts/validate_scaffold.py

@@ -0,0 +1,21 @@
+"""Validation script for sourceos-devtools repository scaffold."""
+
+import pathlib
+import sys
+
+REQUIRED = [
+    "README.md",
+    "AGENTS.md",
+    ".github/copilot-instructions.md",
+    "docs/DEVTOOLS_SCOPE.md",
+    "repo.maturity.yaml",
+]
+
+for path in REQUIRED:
+    p = pathlib.Path(path)
+    if not p.exists():
+        raise SystemExit(f"MISSING: {path}")
+    if not p.read_text().strip():
+        raise SystemExit(f"EMPTY: {path}")
+
+print("OK: sourceos-devtools validation")

sourceosctl/__init__.py

@@ -0,0 +1,3 @@
+"""sourceosctl - SourceOS Developer and AI Operator CLI."""
+
+__version__ = "0.1.0"

sourceosctl/cli.py

@@ -0,0 +1,125 @@
+"""sourceosctl CLI entry point."""
+
+import argparse
+import sys
+
+from sourceosctl import __version__
+from sourceosctl.commands import (
+    doctor,
+    profiles,
+    nlboot,
+    release,
+    fingerprint,
+    ai,
+    agents,
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build and return the argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="sourceosctl",
+        description="SourceOS developer and AI operator CLI (read-only / dry-run surface)",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"sourceosctl {__version__}"
+    )
+
+    sub = parser.add_subparsers(dest="command", metavar="<command>")
+    sub.required = True
+
+    # --- doctor ---
+    doctor_p = sub.add_parser("doctor", help="Run environment health checks")
+    doctor_p.set_defaults(func=doctor.run)
+
+    # --- profiles ---
+    profiles_p = sub.add_parser("profiles", help="Profile management")
+    profiles_sub = profiles_p.add_subparsers(dest="profiles_command", metavar="<subcommand>")
+    profiles_sub.required = True
+    profiles_list_p = profiles_sub.add_parser("list", help="List available profiles")
+    profiles_list_p.set_defaults(func=profiles.list_profiles)
+
+    # --- nlboot ---
+    nlboot_p = sub.add_parser("nlboot", help="NLBoot operator helpers")
+    nlboot_sub = nlboot_p.add_subparsers(dest="nlboot_command", metavar="<subcommand>")
+    nlboot_sub.required = True
+    nlboot_evidence_p = nlboot_sub.add_parser("evidence", help="NLBoot evidence helpers")
+    nlboot_evidence_sub = nlboot_evidence_p.add_subparsers(
+        dest="nlboot_evidence_command", metavar="<subcommand>"
+    )
+    nlboot_evidence_sub.required = True
+    nlboot_inspect_p = nlboot_evidence_sub.add_parser(
+        "inspect", help="Inspect a NLBoot evidence file"
+    )
+    nlboot_inspect_p.add_argument("path", help="Path to NLBoot evidence JSON file")
+    nlboot_inspect_p.set_defaults(func=nlboot.inspect_evidence)
+
+    # --- release ---
+    release_p = sub.add_parser("release", help="Release artifact inspection")
+    release_sub = release_p.add_subparsers(dest="release_command", metavar="<subcommand>")
+    release_sub.required = True
+    release_inspect_p = release_sub.add_parser("inspect", help="Inspect a release artifact")
+    release_inspect_p.add_argument("path", help="Path to release artifact JSON file")
+    release_inspect_p.set_defaults(func=release.inspect)
+
+    # --- fingerprint ---
+    fingerprint_p = sub.add_parser("fingerprint", help="Environment fingerprint utilities")
+    fingerprint_sub = fingerprint_p.add_subparsers(
+        dest="fingerprint_command", metavar="<subcommand>"
+    )
+    fingerprint_sub.required = True
+    fingerprint_collect_p = fingerprint_sub.add_parser(
+        "collect", help="Collect environment fingerprint (dry-run only)"
+    )
+    fingerprint_collect_p.add_argument(
+        "--dry-run",
+        action="store_true",
+        default=True,
+        dest="dry_run",
+        help="Print what would be collected without writing to disk (default: True)",
+    )
+    fingerprint_collect_p.set_defaults(func=fingerprint.collect)
+
+    # --- ai ---
+    ai_p = sub.add_parser("ai", help="AI operator utilities")
+    ai_sub = ai_p.add_subparsers(dest="ai_command", metavar="<subcommand>")
+    ai_sub.required = True
+    ai_labs_p = ai_sub.add_parser("labs", help="AI lab helpers")
+    ai_labs_sub = ai_labs_p.add_subparsers(dest="ai_labs_command", metavar="<subcommand>")
+    ai_labs_sub.required = True
+    ai_labs_list_p = ai_labs_sub.add_parser("list", help="List available AI labs")
+    ai_labs_list_p.set_defaults(func=ai.list_labs)
+
+    # --- agents ---
+    agents_p = sub.add_parser("agents", help="Agent sandbox helpers")
+    agents_sub = agents_p.add_subparsers(dest="agents_command", metavar="<subcommand>")
+    agents_sub.required = True
+    agents_sandbox_p = agents_sub.add_parser("sandbox", help="Agent sandbox management")
+    agents_sandbox_sub = agents_sandbox_p.add_subparsers(
+        dest="agents_sandbox_command", metavar="<subcommand>"
+    )
+    agents_sandbox_sub.required = True
+    agents_sandbox_plan_p = agents_sandbox_sub.add_parser(
+        "plan", help="Plan agent sandbox (dry-run only)"
+    )
+    agents_sandbox_plan_p.add_argument(
+        "--dry-run",
+        action="store_true",
+        default=True,
+        dest="dry_run",
+        help="Print plan without executing (default: True)",
+    )
+    agents_sandbox_plan_p.set_defaults(func=agents.sandbox_plan)
+
+    return parser
+
+
+def main(argv=None) -> int:
+    """Main entry point. Returns exit code."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args) or 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sourceosctl/commands/__init__.py

@@ -0,0 +1 @@
+"""sourceosctl command modules."""