Prepare systemdkit 0.1.0 release

Author: dannote

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## v0.1.0
+
+First stable release.
+
+- Added D-Bus-backed systemd manager APIs for unit lifecycle, unit-file operations, jobs, and signals.
+- Added loss-aware systemd unit-file parsing and rendering.
+- Added builders for service, socket, timer, mount, path, and target units.
+- Added parser-backed validation for common unit-file directives, including resource-control and sandboxing settings.
+- Added typed structs for units, jobs, unit-file operations, unit-file status, and unit/service/socket/timer state.
+- Added transient-unit helpers, including resource-control properties.
+- Added structured errors with permission/polkit classification.
+- Added real Linux/systemd integration tests and documentation guides.
+
 ## v0.1.0-pre.1
 
 - Removed VibeKit/Igniter scaffold dependencies from runtime package dependencies.

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing
 
-Before opening release-oriented changes or publishing a pre-release/Hex package:
+Before opening release-oriented changes or publishing a Hex package:
 
 - Run `mix ci` locally.
 - Run `mix docs` and inspect generated module examples.

README.md

@@ -1,88 +1,122 @@
-# Systemd
+# systemdkit
 
-Pure Elixir tools for working with systemd.
+Pure Elixir tools for systemd unit files and D-Bus manager control.
 
-Hex package name: `systemdkit`. The Mix application and public modules remain `:systemd` / `Systemd`.
+`systemdkit` is for Elixir applications and deployment tools that need to generate unit files, inspect systemd state, or control systemd directly over D-Bus without shelling out to `systemctl`.
 
-```elixir
-{:systemdkit, "~> 0.1.0-pre"}
-```
+## Installation
 
-The package exposes a small D-Bus backed manager client:
+The Hex package is named `systemdkit`; the Mix application and modules are `:systemd` / `Systemd`.
 
 ```elixir
-{:ok, conn} = Systemd.Manager.connect()
-{:ok, units} = Systemd.Manager.list_units(conn)
-{:ok, unit} = Systemd.Manager.get_unit(conn, "dbus.service")
-{:ok, state} = Systemd.UnitObject.state(conn, unit)
-{:ok, service_state} = Systemd.UnitObject.service_state(conn, unit)
+def deps do
+  [
+    {:systemd, "~> 0.1.0", hex: :systemdkit}
+  ]
+end
 ```
 
-It also includes a NimbleParsec-backed unit file parser/generator:
+## Unit files
 
-```elixir
-{:ok, unit_file} = Systemd.UnitFile.parse("[Service]\nExecStart=/bin/app start\n")
-Systemd.UnitFile.to_string(unit_file)
+Build systemd units with typed helpers, render them, and validate them before installation:
 
+```elixir
 unit_file =
   Systemd.UnitFile.service(
-    unit: [description: "My app"],
-    service: [exec_start: "/bin/app start", restart: :always],
+    unit: [description: "My app", after: "network.target"],
+    service: [
+      type: :exec,
+      user: "deploy",
+      working_directory: "/opt/my-app/current",
+      exec_start: "/opt/my-app/current/bin/my_app start",
+      restart: "on-failure",
+      memory_max: "512M",
+      tasks_max: 512,
+      no_new_privileges: true,
+      protect_system: :strict
+    ],
     install: [wanted_by: "multi-user.target"]
   )
+
+:ok = Systemd.UnitFile.validate(unit_file, :service)
+Systemd.UnitFile.to_string(unit_file)
 ```
 
-The package depends on [`rebus`](https://hex.pm/packages/rebus) for the D-Bus wire protocol instead of shelling out to `systemctl`.
+Parsing is loss-aware: comments, blank lines, duplicate directives, reset directives, and source spans are preserved.
 
-APIs return idiomatic `{:ok, value}` / `{:error, %Systemd.Error{}}` tuples. Permission and polkit failures are classified with `category: :permission` and can be checked with `Systemd.Error.permission?/1`.
+```elixir
+{:ok, unit_file} = Systemd.UnitFile.parse("[Service]\nExecStart=/bin/true\n")
+Systemd.UnitFile.get_all(unit_file, "Service", "ExecStart")
+```
 
-See `examples/` for service, timer, and user-bus snippets, `guides/dbus-manager.md` for D-Bus manager operations, and `guides/xamal-style-deployment.md` for a deployment-oriented template unit example.
+Builders are available for service, socket, timer, mount, path, and target units.
 
-## Permissions
+## D-Bus manager control
 
-Systemd control happens over D-Bus. Read-only calls such as listing units usually work as an unprivileged user. Mutating calls such as daemon reload, starting system units, enabling units, or writing to `/etc/systemd/system` may require root or a polkit rule for the caller. The package returns structured `Systemd.Error` values for D-Bus policy failures instead of retrying through `sudo`.
+Use the top-level API for short-lived D-Bus operations:
 
-For user units, pass `bus: :session` when a systemd user session bus is available:
+```elixir
+{:ok, units} = Systemd.list_units()
+{:ok, unit_files} = Systemd.list_unit_files()
+{:ok, state} = Systemd.unit_state("dbus.service")
+
+:ok = Systemd.reload()
+:ok = Systemd.start_unit("my_app.service")
+:ok = Systemd.restart_unit("my_app.service")
+```
+
+Use `Systemd.Manager` when you want to reuse a connection or inspect jobs:
 
 ```elixir
-Systemd.list_units(bus: :session)
+Systemd.with_connection([], fn conn ->
+  with {:ok, job} <- Systemd.Manager.restart_unit(conn, "my_app.service"),
+       :ok <- Systemd.Job.await_signal(conn, job, timeout: 10_000) do
+    :ok
+  end
+end)
 ```
 
-## Unit files
+## Errors and permissions
 
-`Systemd.UnitFile` preserves comments, blank lines, duplicate directives, reset directives, and source spans. Validation is intentionally separate from parsing and includes directive-specific value checks for common service, socket, timer, and install keys:
+APIs return `{:ok, value}` or `{:error, %Systemd.Error{}}`. Permission and polkit failures are classified as `:permission`:
 
 ```elixir
-unit_file = Systemd.UnitFile.parse!("[Service]\nExecStart=/bin/true\n")
-:ok = Systemd.UnitFile.validate(unit_file, :service)
+case Systemd.start_unit("my_app.service") do
+  :ok -> :ok
+  {:error, error} ->
+    if Systemd.Error.permission?(error), do: {:error, :permission_denied}, else: {:error, error}
+end
 ```
 
-## Development
+Read-only calls often work unprivileged. Mutating system units typically require root or appropriate polkit rules. `systemdkit` reports those D-Bus errors directly; it does not retry through `sudo`.
 
-```sh
-mix deps.get
-mix ci
+For user units, pass `bus: :session` when a systemd user session bus is available:
+
+```elixir
+Systemd.list_units(bus: :session)
 ```
 
-Integration tests are excluded by default because they require Linux with systemd and a system bus. For local development, run them inside the Lima Debian VM named `systemd-test`:
+## Guides
+
+- [D-Bus manager operations](guides/dbus-manager.md)
+- [Xamal-style deployment units](guides/xamal-style-deployment.md)
+
+## Integration testing
+
+The test suite includes optional integration tests against a real Linux systemd manager. They are excluded by default:
 
 ```sh
-~/.local/bin/limactl shell systemd-test
-cd /Users/dannote/Development/systemd
-SYSTEMD_INTEGRATION=1 mix test
+mix test
 ```
 
-Or from macOS, copy the source into the VM and run the full integration suite:
+Run them on Linux with systemd and a system bus:
 
 ```sh
-scripts/integration_test.sh
+SYSTEMD_INTEGRATION=1 mix test
 ```
 
-Quick VM checks:
+This repository also includes a Lima helper used by maintainers:
 
 ```sh
-~/.local/bin/limactl shell systemd-test -- systemctl is-system-running
-~/.local/bin/limactl shell systemd-test -- busctl --system list --no-pager
+scripts/integration_test.sh
 ```
-
-See `CONTRIBUTING.md` before publishing a release.

mix.exs

@@ -1,7 +1,7 @@
 defmodule Systemd.MixProject do
   use Mix.Project
 
-  @version "0.1.0-pre.1"
+  @version "0.1.0"
   @source_url "https://github.com/elixir-vibe/systemd"
 
   def project do
@@ -18,7 +18,6 @@ defmodule Systemd.MixProject do
     ]
   end
 
-  # Run "mix help compile.app" to learn about applications.
   def application do
     [
       extra_applications: [:logger, :rebus]
@@ -31,7 +30,6 @@ defmodule Systemd.MixProject do
     ]
   end
 
-  # Run "mix help deps" to learn about dependencies.
   defp deps do
     [
       {:ex_doc, "~> 0.38", only: :dev, runtime: false},
@@ -44,16 +42,15 @@ defmodule Systemd.MixProject do
       {:rebus, "~> 0.2.0"},
       {:vibe_kit, "== 0.1.2", only: [:dev, :test], runtime: false},
       {:igniter, "~> 0.6", only: [:dev, :test], runtime: false}
-      # {:dep_from_hexpm, "~> 0.3.0"},
-      # {:dep_from_git, git: "https://github.com/elixir-lang/my_dep.git", tag: "0.1.0"}
     ]
   end
 
   defp package do
     [
       name: "systemdkit",
       licenses: ["MIT"],
-      links: %{"GitHub" => @source_url}
+      links: %{"GitHub" => @source_url},
+      files: ~w(lib guides examples .formatter.exs mix.exs README.md LICENSE CHANGELOG.md)
     ]
   end
 
@@ -69,7 +66,48 @@ defmodule Systemd.MixProject do
         "guides/xamal-style-deployment.md",
         "guides/dbus-manager.md"
       ],
-      groups_for_extras: [Guides: ~r/guides\//]
+      groups_for_extras: [Guides: ~r/guides\//],
+      groups_for_modules: [
+        "D-Bus": [
+          Systemd.DBus,
+          Systemd.DBus.Result,
+          Systemd.Manager,
+          Systemd.Signal,
+          Systemd.Properties
+        ],
+        "Unit files": [
+          Systemd.UnitFile,
+          Systemd.UnitFile.Blank,
+          Systemd.UnitFile.Builder,
+          Systemd.UnitFile.Comment,
+          Systemd.UnitFile.Directive,
+          Systemd.UnitFile.ParseError,
+          Systemd.UnitFile.Raw,
+          Systemd.UnitFile.Section,
+          Systemd.UnitFile.Span,
+          Systemd.UnitFile.ValidationError,
+          Systemd.UnitFile.Value
+        ],
+        "Runtime structs": [
+          Systemd.Error,
+          Systemd.Job,
+          Systemd.JobStatus,
+          Systemd.ServiceState,
+          Systemd.SocketState,
+          Systemd.TimerState,
+          Systemd.Unit,
+          Systemd.UnitFileChange,
+          Systemd.UnitFileOperation,
+          Systemd.UnitFileStatus,
+          Systemd.UnitObject,
+          Systemd.UnitState
+        ],
+        "Transient units": [
+          Systemd.TransientUnit,
+          Systemd.TransientUnit.AuxUnit,
+          Systemd.TransientUnit.Property
+        ]
+      ]
     ]
   end