systemd-unit-doctor-kit

Inspect .service, .timer and .socket systemd unit files with portable, structured diagnostics.

systemd-unit-doctor-kit is a clean-room TypeScript draft. The core has no runtime dependency and does not call Node APIs, so it can run in browsers, workers, CLIs and CI tooling. The bundled CLI is a thin Node wrapper around the same core.

Demo

Try the browser preview: packages.wasta-wocket.fr/systemd-unit-doctor-kit.

Package quality

• TypeScript types are generated from the source.
• ESM-only package with no runtime dependencies in the core.
• Marked as side-effect free for bundlers.
• CI runs npm ci, typecheck, build, and test.
• Tested on Node.js 20 and 22 with GitHub Actions.
• Browser-friendly implementation with Node-only code isolated in the CLI.

Install

npm install systemd-unit-doctor-kit

Quick Start

import { formatSystemdUnitDiagnostics, inspectSystemdUnit } from "systemd-unit-doctor-kit";

const source = `[Unit]
Description=Nightly sync

[Service]
Type=oneshot
ExecStart=/usr/local/bin/sync-data %q
Restart=always
`;

const result = inspectSystemdUnit(source, { kind: "service" });

console.log(result.ok);
console.log(formatSystemdUnitDiagnostics(result));

Output:

false
WARNING unescaped-percent-specifier 6:31 Service.ExecStart - Value contains a percent sequence outside the MVP specifier allowlist; use %% for a literal percent.
INFO missing-install-section 1:1 - No [Install] section found; the unit may not be enableable.
WARNING risky-restart-with-oneshot 7:1 Service.Restart - Type=oneshot with this Restart policy is often rejected or surprising; verify with systemd-analyze.

CLI

systemd-unit-doctor ./worker.service --format=markdown
systemd-unit-doctor ./backup.timer --json
systemd-unit-doctor ./listener.socket --no-install-check

The CLI exits with 1 when an error-level diagnostic is present.

API

inspectSystemdUnit(input, options?)

Returns:

• ok: false when at least one error-level diagnostic exists;
• kind: service, timer, socket or unknown;
• sections: section names with source lines;
• assignments: parsed key=value entries with section, value and line;
• diagnostics: stable objects with code, severity, message, line, column, and optional section/directive.

Options:

| Option | Default | Description | | --- | --- | --- | | kind | inferred from sections | Unit kind to check against. | | requireInstall | true | Report an info diagnostic when [Install] is missing. | | allowUnknownDirectives | false | Disable MVP directive allowlist warnings. | | maxInputCharacters | 1000000 | Stop before parsing unexpectedly large inputs. |

createSystemdUnitInspector(defaultOptions?)

Creates a reusable inspector with default options.

formatSystemdUnitDiagnostics(result)

Formats diagnostics for terminal output, Markdown reports or tests.

MVP Diagnostics

• invalid or empty input;
• input that exceeds the configured size limit;
• malformed sections and assignments;
• assignments before any section;
• unknown sections and directives for the MVP allowlist;
• sections that do not match the selected unit kind;
• duplicate non-repeatable directives;
• suspicious percent specifiers and dangling continuations;
• comments inside continued lines;
• missing [Unit], kind section or [Install];
• Type=oneshot with risky Restart values;
• timer units without an OnCalendar/OnBootSec style trigger.

Limits

This package complements systemd-analyze verify; it does not replace it. The MVP rule table is intentionally small, versionless and focused on .service, .timer and .socket files. It does not evaluate drop-ins, dependency graph semantics, filesystem state, user/group existence or distro-specific systemd versions.

License

MPL-2.0