@push.rocks/smartdaemon 2.2.0 → 2.3.1

package/.smartconfig.json

@@ -19,18 +19,38 @@
       ]
     },
     "release": {
-      "registries": [
-        "https://verdaccio.lossless.digital",
-        "https://registry.npmjs.org"
-      ],
-      "accessLevel": "public"
-    }
+      "preflight": {
+        "requireCleanTree": true,
+        "test": true,
+        "build": true
+      },
+      "targets": {
+        "git": {
+          "enabled": true,
+          "remote": "origin",
+          "pushBranch": true,
+          "pushTags": true
+        },
+        "npm": {
+          "enabled": true,
+          "registries": [
+            "https://verdaccio.lossless.digital",
+            "https://registry.npmjs.org"
+          ],
+          "accessLevel": "public",
+          "alreadyPublished": "success"
+        },
+        "docker": {
+          "enabled": false
+        }
+      }
+    },
+    "schemaVersion": 2
   },
   "@git.zone/tsdoc": {
     "legal": "\n## License and Legal Information\n\nThis repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. \n\n**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.\n\n### Trademarks\n\nThis project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.\n\n### Company Information\n\nTask Venture Capital GmbH  \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.\n"
   },
   "@ship.zone/szci": {
-    "npmGlobalTools": [],
-    "npmRegistryUrl": "registry.npmjs.org"
+    "npmGlobalTools": []
   }
 }

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@push.rocks/smartdaemon',
-    version: '2.2.0',
+    version: '2.3.1',
     description: 'Start scripts as long running daemons and manage them.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx5QkFBeUI7SUFDL0IsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLHdEQUF3RDtDQUN0RSxDQUFBIn0=

package/dist_ts/classes.systemdunit.d.ts

@@ -0,0 +1,38 @@
+export interface ISystemdUnitOptions {
+    unitName: string;
+    /** Absolute executable path supplied by trusted owning code. */
+    systemctlPath?: string;
+    /** Bounds the systemctl client, not the server-side job. Defaults to 120 seconds. */
+    commandTimeoutMs?: number;
+}
+export interface ISystemdUnitState {
+    readonly unitName: string;
+    readonly loadState: string;
+    readonly activeState: string;
+    readonly subState: string;
+    readonly unitFileState: string;
+    readonly mainPid: number;
+    readonly controlPid: number;
+    readonly controlGroup: string;
+    readonly killMode: string;
+    /** Empty when no systemd job is pending; otherwise systemctl's job description. */
+    readonly job: string;
+}
+export declare class SystemdUnitError extends Error {
+    readonly code: 'invalid_options' | 'command_failed' | 'invalid_state';
+    constructor(code: 'invalid_options' | 'command_failed' | 'invalid_state');
+}
+/** Controls an existing system unit without creating files, changing enablement or escalating privileges. */
+export declare class SystemdUnit {
+    private readonly unitName;
+    private readonly executable;
+    private readonly timeout;
+    constructor(optionsArg: ISystemdUnitOptions);
+    /** Snapshot only. Callers own application-specific admission and restart policy. */
+    inspect(): Promise<ISystemdUnitState>;
+    /** Await the systemd job, then inspect. This does not enable or unmask the unit. */
+    start(): Promise<ISystemdUnitState>;
+    /** Await the systemd job, then inspect. The snapshot alone is not an application data-drain proof. */
+    stop(): Promise<ISystemdUnitState>;
+    private command;
+}

package/dist_ts/classes.systemdunit.js

@@ -0,0 +1,97 @@
+import * as plugins from './smartdaemon.plugins.js';
+export class SystemdUnitError extends Error {
+    constructor(code) {
+        super(`Systemd unit operation failed: ${code}.`);
+        this.code = code;
+        this.name = 'SystemdUnitError';
+    }
+}
+const properties = [
+    'Id',
+    'LoadState',
+    'ActiveState',
+    'SubState',
+    'UnitFileState',
+    'MainPID',
+    'ControlPID',
+    'ControlGroup',
+    'KillMode',
+    'Job',
+];
+/** Controls an existing system unit without creating files, changing enablement or escalating privileges. */
+export class SystemdUnit {
+    constructor(optionsArg) {
+        this.unitName = optionsArg?.unitName;
+        this.executable = optionsArg?.systemctlPath ?? '/usr/bin/systemctl';
+        this.timeout = optionsArg?.commandTimeoutMs ?? 120000;
+        if (typeof this.unitName !== 'string' ||
+            !/^[a-zA-Z0-9][a-zA-Z0-9_.:@-]{0,230}\.service$/.test(this.unitName) ||
+            typeof this.executable !== 'string' || !plugins.path.isAbsolute(this.executable) ||
+            this.executable.includes('\0') || !Number.isSafeInteger(this.timeout) ||
+            this.timeout < 1 || this.timeout > 600000)
+            throw new SystemdUnitError('invalid_options');
+    }
+    /** Snapshot only. Callers own application-specific admission and restart policy. */
+    async inspect() {
+        const stdout = await this.command([
+            'show',
+            this.unitName,
+            `--property=${properties.join(',')}`,
+            '--all',
+        ]);
+        const fields = new Map();
+        for (const line of stdout.trimEnd().split('\n')) {
+            const separator = line.indexOf('=');
+            const key = line.slice(0, separator);
+            if (separator < 1 || !properties.includes(key) || fields.has(key)) {
+                throw new SystemdUnitError('invalid_state');
+            }
+            fields.set(key, line.slice(separator + 1));
+        }
+        if (fields.size !== properties.length || fields.get('Id') !== this.unitName ||
+            ['LoadState', 'ActiveState', 'SubState'].some((key) => !fields.get(key)) ||
+            ['MainPID', 'ControlPID'].some((key) => !/^(0|[1-9]\d*)$/.test(fields.get(key)) || !Number.isSafeInteger(Number(fields.get(key)))))
+            throw new SystemdUnitError('invalid_state');
+        return Object.freeze({
+            unitName: this.unitName,
+            loadState: fields.get('LoadState'),
+            activeState: fields.get('ActiveState'),
+            subState: fields.get('SubState'),
+            unitFileState: fields.get('UnitFileState'),
+            mainPid: Number(fields.get('MainPID')),
+            controlPid: Number(fields.get('ControlPID')),
+            controlGroup: fields.get('ControlGroup'),
+            killMode: fields.get('KillMode'),
+            job: fields.get('Job'),
+        });
+    }
+    /** Await the systemd job, then inspect. This does not enable or unmask the unit. */
+    async start() {
+        await this.command(['start', this.unitName]);
+        return this.inspect();
+    }
+    /** Await the systemd job, then inspect. The snapshot alone is not an application data-drain proof. */
+    async stop() {
+        await this.command(['stop', this.unitName]);
+        return this.inspect();
+    }
+    command(argsArg) {
+        return new Promise((resolve, reject) => {
+            plugins.childProcess.execFile(this.executable, ['--system', '--no-ask-password', '--no-pager', ...argsArg], {
+                encoding: 'utf8',
+                timeout: this.timeout,
+                killSignal: 'SIGKILL',
+                maxBuffer: 16384,
+                windowsHide: true,
+                env: { PATH: '/usr/bin:/bin', LANG: 'C', LC_ALL: 'C' },
+            }, (error, stdout) => {
+                // execFile settles after the client closes. A timed-out client's remote job may continue.
+                if (error)
+                    reject(new SystemdUnitError('command_failed'));
+                else
+                    resolve(stdout);
+            });
+        });
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5zeXN0ZW1kdW5pdC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL2NsYXNzZXMuc3lzdGVtZHVuaXQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSwwQkFBMEIsQ0FBQztBQXdCcEQsTUFBTSxPQUFPLGdCQUFpQixTQUFRLEtBQUs7SUFDekMsWUFBNEIsSUFBNEQ7UUFDdEYsS0FBSyxDQUFDLGtDQUFrQyxJQUFJLEdBQUcsQ0FBQyxDQUFDO1FBRHZCLFNBQUksR0FBSixJQUFJLENBQXdEO1FBRXRGLElBQUksQ0FBQyxJQUFJLEdBQUcsa0JBQWtCLENBQUM7SUFDakMsQ0FBQztDQUNGO0FBRUQsTUFBTSxVQUFVLEdBQUc7SUFDakIsSUFBSTtJQUNKLFdBQVc7SUFDWCxhQUFhO0lBQ2IsVUFBVTtJQUNWLGVBQWU7SUFDZixTQUFTO0lBQ1QsWUFBWTtJQUNaLGNBQWM7SUFDZCxVQUFVO0lBQ1YsS0FBSztDQUNHLENBQUM7QUFFWCw2R0FBNkc7QUFDN0csTUFBTSxPQUFPLFdBQVc7SUFLdEIsWUFBWSxVQUErQjtRQUN6QyxJQUFJLENBQUMsUUFBUSxHQUFHLFVBQVUsRUFBRSxRQUFRLENBQUM7UUFDckMsSUFBSSxDQUFDLFVBQVUsR0FBRyxVQUFVLEVBQUUsYUFBYSxJQUFJLG9CQUFvQixDQUFDO1FBQ3BFLElBQUksQ0FBQyxPQUFPLEdBQUcsVUFBVSxFQUFFLGdCQUFnQixJQUFJLE1BQU0sQ0FBQztRQUN0RCxJQUNFLE9BQU8sSUFBSSxDQUFDLFFBQVEsS0FBSyxRQUFRO1lBQ2pDLENBQUMsK0NBQStDLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxRQUFRLENBQUM7WUFDcEUsT0FBTyxJQUFJLENBQUMsVUFBVSxLQUFLLFFBQVEsSUFBSSxDQUFDLE9BQU8sQ0FBQyxJQUFJLENBQUMsVUFBVSxDQUFDLElBQUksQ0FBQyxVQUFVLENBQUM7WUFDaEYsSUFBSSxDQUFDLFVBQVUsQ0FBQyxR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

package/dist_ts/index.d.ts

@@ -1,2 +1,3 @@
 export * from './smartdaemon.classes.smartdaemon.js';
 export * from './smartdaemon.classes.service.js';
+export * from './classes.systemdunit.js';

package/dist_ts/index.js

@@ -1,3 +1,4 @@
 export * from './smartdaemon.classes.smartdaemon.js';
 export * from './smartdaemon.classes.service.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxjQUFjLHNDQUFzQyxDQUFDO0FBQ3JELGNBQWMsa0NBQWtDLENBQUMifQ==
+export * from './classes.systemdunit.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxjQUFjLHNDQUFzQyxDQUFDO0FBQ3JELGNBQWMsa0NBQWtDLENBQUM7QUFDakQsY0FBYywwQkFBMEIsQ0FBQyJ9

package/dist_ts/smartdaemon.plugins.d.ts

@@ -1,5 +1,6 @@
 import * as path from 'path';
-export { path };
+import * as childProcess from 'node:child_process';
+export { path, childProcess };
 import * as lik from '@push.rocks/lik';
 import * as smartfm from '@push.rocks/smartfm';
 import * as smartfs from '@push.rocks/smartfs';

package/dist_ts/smartdaemon.plugins.js

@@ -1,6 +1,7 @@
 // node native scope
 import * as path from 'path';
-export { path };
+import * as childProcess from 'node:child_process';
+export { path, childProcess };
 // @pushrocks scope
 import * as lik from '@push.rocks/lik';
 import * as smartfm from '@push.rocks/smartfm';
@@ -12,4 +13,4 @@ import * as smartshell from '@push.rocks/smartshell';
 import * as smartsystem from '@push.rocks/smartsystem';
 export { lik, smartfm, smartfs, smartlog, smartlogDestinationLocal, smartpath, smartshell, smartsystem, };
 // third party
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRkYWVtb24ucGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3NtYXJ0ZGFlbW9uLnBsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsb0JBQW9CO0FBQ3BCLE9BQU8sS0FBSyxJQUFJLE1BQU0sTUFBTSxDQUFDO0FBRTdCLE9BQU8sRUFBRSxJQUFJLEVBQUUsQ0FBQztBQUVoQixtQkFBbUI7QUFDbkIsT0FBTyxLQUFLLEdBQUcsTUFBTSxpQkFBaUIsQ0FBQztBQUN2QyxPQUFPLEtBQUssT0FBTyxNQUFNLHFCQUFxQixDQUFDO0FBQy9DLE9BQU8sS0FBSyxPQUFPLE1BQU0scUJBQXFCLENBQUM7QUFDL0MsT0FBTyxLQUFLLFFBQVEsTUFBTSxzQkFBc0IsQ0FBQztBQUNqRCxPQUFPLEtBQUssd0JBQXdCLE1BQU0sd0NBQXdDLENBQUM7QUFDbkYsT0FBTyxLQUFLLFNBQVMsTUFBTSx1QkFBdUIsQ0FBQztBQUNuRCxPQUFPLEtBQUssVUFBVSxNQUFNLHdCQUF3QixDQUFDO0FBQ3JELE9BQU8sS0FBSyxXQUFXLE1BQU0seUJBQXlCLENBQUM7QUFFdkQsT0FBTyxFQUNMLEdBQUcsRUFDSCxPQUFPLEVBQ1AsT0FBTyxFQUNQLFFBQVEsRUFDUix3QkFBd0IsRUFDeEIsU0FBUyxFQUNULFVBQVUsRUFDVixXQUFXLEdBQ1osQ0FBQztBQUVGLGNBQWMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRkYWVtb24ucGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3NtYXJ0ZGFlbW9uLnBsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsb0JBQW9CO0FBQ3BCLE9BQU8sS0FBSyxJQUFJLE1BQU0sTUFBTSxDQUFDO0FBQzdCLE9BQU8sS0FBSyxZQUFZLE1BQU0sb0JBQW9CLENBQUM7QUFFbkQsT0FBTyxFQUFFLElBQUksRUFBRSxZQUFZLEVBQUUsQ0FBQztBQUU5QixtQkFBbUI7QUFDbkIsT0FBTyxLQUFLLEdBQUcsTUFBTSxpQkFBaUIsQ0FBQztBQUN2QyxPQUFPLEtBQUssT0FBTyxNQUFNLHFCQUFxQixDQUFDO0FBQy9DLE9BQU8sS0FBSyxPQUFPLE1BQU0scUJBQXFCLENBQUM7QUFDL0MsT0FBTyxLQUFLLFFBQVEsTUFBTSxzQkFBc0IsQ0FBQztBQUNqRCxPQUFPLEtBQUssd0JBQXdCLE1BQU0sd0NBQXdDLENBQUM7QUFDbkYsT0FBTyxLQUFLLFNBQVMsTUFBTSx1QkFBdUIsQ0FBQztBQUNuRCxPQUFPLEtBQUssVUFBVSxNQUFNLHdCQUF3QixDQUFDO0FBQ3JELE9BQU8sS0FBSyxXQUFXLE1BQU0seUJBQXlCLENBQUM7QUFFdkQsT0FBTyxFQUNMLEdBQUcsRUFDSCxPQUFPLEVBQ1AsT0FBTyxFQUNQLFFBQVEsRUFDUix3QkFBd0IsRUFDeEIsU0FBUyxFQUNULFVBQVUsRUFDVixXQUFXLEdBQ1osQ0FBQztBQUVGLGNBQWMifQ==

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartdaemon",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "private": false,
   "description": "Start scripts as long running daemons and manage them.",
   "main": "dist_ts/index.js",
@@ -27,9 +27,9 @@
   "homepage": "https://code.foss.global/push.rocks/smartdaemon",
   "devDependencies": {
     "@git.zone/tsbuild": "^4.4.2",
-    "@git.zone/tsrun": "^2.0.4",
-    "@git.zone/tstest": "^3.6.6",
-    "@types/node": "^25.9.1"
+    "@git.zone/tsrun": "^2.0.6",
+    "@git.zone/tstest": "^4.0.0",
+    "@types/node": "^26.4.1"
   },
   "dependencies": {
     "@push.rocks/lik": "^6.4.1",

package/readme.md

@@ -1,6 +1,10 @@
 # @push.rocks/smartdaemon 🚀
 **Turn your Node.js scripts into production-ready system daemons**
 
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
 [![npm version](https://img.shields.io/npm/v/@push.rocks/smartdaemon.svg?style=flat-square)](https://www.npmjs.com/package/@push.rocks/smartdaemon)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
@@ -147,6 +151,41 @@ class SmartDaemon {
 }
 ```
 
+### Inspecting and controlling an existing systemd unit
+
+`SystemdUnit` works with an exact canonical `.service` name. Construction performs
+no I/O. It does not create or rewrite a unit, enable it, remove a mask, or invoke
+sudo. The caller must already have permission for lifecycle commands.
+
+```typescript
+import { SystemdUnit } from '@push.rocks/smartdaemon';
+
+const unit = new SystemdUnit({ unitName: 'smartdaemon_my-api-server.service' });
+const state = await unit.inspect();
+console.log(state.loadState, state.activeState, state.unitFileState);
+
+// Application code decides whether stopping or restarting is appropriate.
+// await unit.stop();
+// await unit.start();
+```
+
+Snapshots are immutable and also include `subState`, `mainPid`, `controlPid`,
+`controlGroup`, `killMode`, and `job`. An empty `job` means no systemd job was
+reported. Missing and masked units remain distinct from inactive or disabled
+units. Aliases resolving to a different canonical unit are rejected.
+
+`start()` and `stop()` await the systemctl command and return a fresh snapshot.
+They do not establish application readiness or prove database shutdown; callers
+must apply the owning application's lifecycle contract. A command failure or
+timeout rejects with `SystemdUnitError` and a local code, without returning raw
+command diagnostics. The systemd job can continue after a client timeout, so a
+failed command must not be treated as cancelled or successfully completed.
+
+Calls use an absolute `systemctlPath` (default `/usr/bin/systemctl`), a clean
+environment, no shell or password prompt, and bounded output. Trusted owning code
+can choose another absolute executable path and `commandTimeoutMs` (default
+120000, maximum 600000). This timeout bounds the client process only.
+
 ### SmartDaemonService Class
 
 ```typescript
@@ -424,4 +463,4 @@ Registered at District court Bremen HRB 35230 HB, Germany
 
 For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
 
-By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartdaemon',
-  version: '2.2.0',
+  version: '2.3.1',
   description: 'Start scripts as long running daemons and manage them.'
 }

package/ts/classes.systemdunit.ts

@@ -0,0 +1,135 @@
+import * as plugins from './smartdaemon.plugins.js';
+
+export interface ISystemdUnitOptions {
+  unitName: string;
+  /** Absolute executable path supplied by trusted owning code. */
+  systemctlPath?: string;
+  /** Bounds the systemctl client, not the server-side job. Defaults to 120 seconds. */
+  commandTimeoutMs?: number;
+}
+
+export interface ISystemdUnitState {
+  readonly unitName: string;
+  readonly loadState: string;
+  readonly activeState: string;
+  readonly subState: string;
+  readonly unitFileState: string;
+  readonly mainPid: number;
+  readonly controlPid: number;
+  readonly controlGroup: string;
+  readonly killMode: string;
+  /** Empty when no systemd job is pending; otherwise systemctl's job description. */
+  readonly job: string;
+}
+
+export class SystemdUnitError extends Error {
+  constructor(public readonly code: 'invalid_options' | 'command_failed' | 'invalid_state') {
+    super(`Systemd unit operation failed: ${code}.`);
+    this.name = 'SystemdUnitError';
+  }
+}
+
+const properties = [
+  'Id',
+  'LoadState',
+  'ActiveState',
+  'SubState',
+  'UnitFileState',
+  'MainPID',
+  'ControlPID',
+  'ControlGroup',
+  'KillMode',
+  'Job',
+] as const;
+
+/** Controls an existing system unit without creating files, changing enablement or escalating privileges. */
+export class SystemdUnit {
+  private readonly unitName: string;
+  private readonly executable: string;
+  private readonly timeout: number;
+
+  constructor(optionsArg: ISystemdUnitOptions) {
+    this.unitName = optionsArg?.unitName;
+    this.executable = optionsArg?.systemctlPath ?? '/usr/bin/systemctl';
+    this.timeout = optionsArg?.commandTimeoutMs ?? 120000;
+    if (
+      typeof this.unitName !== 'string' ||
+      !/^[a-zA-Z0-9][a-zA-Z0-9_.:@-]{0,230}\.service$/.test(this.unitName) ||
+      typeof this.executable !== 'string' || !plugins.path.isAbsolute(this.executable) ||
+      this.executable.includes('\0') || !Number.isSafeInteger(this.timeout) ||
+      this.timeout < 1 || this.timeout > 600000
+    ) throw new SystemdUnitError('invalid_options');
+  }
+
+  /** Snapshot only. Callers own application-specific admission and restart policy. */
+  public async inspect(): Promise<ISystemdUnitState> {
+    const stdout = await this.command([
+      'show',
+      this.unitName,
+      `--property=${properties.join(',')}`,
+      '--all',
+    ]);
+    const fields = new Map<string, string>();
+    for (const line of stdout.trimEnd().split('\n')) {
+      const separator = line.indexOf('=');
+      const key = line.slice(0, separator);
+      if (separator < 1 || !(properties as readonly string[]).includes(key) || fields.has(key)) {
+        throw new SystemdUnitError('invalid_state');
+      }
+      fields.set(key, line.slice(separator + 1));
+    }
+    if (
+      fields.size !== properties.length || fields.get('Id') !== this.unitName ||
+      ['LoadState', 'ActiveState', 'SubState'].some((key) => !fields.get(key)) ||
+      ['MainPID', 'ControlPID'].some((key) =>
+        !/^(0|[1-9]\d*)$/.test(fields.get(key)!) || !Number.isSafeInteger(Number(fields.get(key)))
+      )
+    ) throw new SystemdUnitError('invalid_state');
+    return Object.freeze({
+      unitName: this.unitName,
+      loadState: fields.get('LoadState')!,
+      activeState: fields.get('ActiveState')!,
+      subState: fields.get('SubState')!,
+      unitFileState: fields.get('UnitFileState')!,
+      mainPid: Number(fields.get('MainPID')),
+      controlPid: Number(fields.get('ControlPID')),
+      controlGroup: fields.get('ControlGroup')!,
+      killMode: fields.get('KillMode')!,
+      job: fields.get('Job')!,
+    });
+  }
+
+  /** Await the systemd job, then inspect. This does not enable or unmask the unit. */
+  public async start(): Promise<ISystemdUnitState> {
+    await this.command(['start', this.unitName]);
+    return this.inspect();
+  }
+
+  /** Await the systemd job, then inspect. The snapshot alone is not an application data-drain proof. */
+  public async stop(): Promise<ISystemdUnitState> {
+    await this.command(['stop', this.unitName]);
+    return this.inspect();
+  }
+
+  private command(argsArg: string[]): Promise<string> {
+    return new Promise((resolve, reject) => {
+      plugins.childProcess.execFile(
+        this.executable,
+        ['--system', '--no-ask-password', '--no-pager', ...argsArg],
+        {
+          encoding: 'utf8',
+          timeout: this.timeout,
+          killSignal: 'SIGKILL',
+          maxBuffer: 16384,
+          windowsHide: true,
+          env: { PATH: '/usr/bin:/bin', LANG: 'C', LC_ALL: 'C' },
+        },
+        (error, stdout) => {
+          // execFile settles after the client closes. A timed-out client's remote job may continue.
+          if (error) reject(new SystemdUnitError('command_failed'));
+          else resolve(stdout);
+        },
+      );
+    });
+  }
+}

package/ts/index.ts

@@ -1,2 +1,3 @@
 export * from './smartdaemon.classes.smartdaemon.js';
 export * from './smartdaemon.classes.service.js';
+export * from './classes.systemdunit.js';

package/ts/smartdaemon.plugins.ts

@@ -1,7 +1,8 @@
 // node native scope
 import * as path from 'path';
+import * as childProcess from 'node:child_process';
 
-export { path };
+export { path, childProcess };
 
 // @pushrocks scope
 import * as lik from '@push.rocks/lik';

package/readme.hints.md

@@ -1 +0,0 @@
-