@push.rocks/smartdaemon 2.2.0 → 2.4.0

package/.smartconfig.json

@@ -19,18 +19,37 @@
       ]
     },
     "release": {
-      "registries": [
-        "https://verdaccio.lossless.digital",
-        "https://registry.npmjs.org"
-      ],
-      "accessLevel": "public"
-    }
+      "preflight": {
+        "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.4.0',
     description: 'Start scripts as long running daemons and manage them.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx5QkFBeUI7SUFDL0IsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLHdEQUF3RDtDQUN0RSxDQUFBIn0=

package/dist_ts/classes.systemdservicedefinition.d.ts

@@ -0,0 +1,22 @@
+export interface ISystemdServiceDefinitionOptions {
+    unitName: string;
+    description: string;
+    executable: string;
+    args: readonly string[];
+    workingDirectory: string;
+    user: string;
+    group: string;
+    restart: 'no' | 'on-failure' | 'always';
+    killMode: 'mixed' | 'control-group';
+    timeoutStopSeconds: number;
+}
+export declare class SystemdServiceDefinitionError extends Error {
+    constructor();
+}
+/** Literal direct-execution definition; never introduces a shell or environment expansion. */
+export declare class SystemdServiceDefinition {
+    readonly unitName: string;
+    readonly content: string;
+    readonly sha256: string;
+    constructor(options: ISystemdServiceDefinitionOptions);
+}

package/dist_ts/classes.systemdservicedefinition.js

@@ -0,0 +1,93 @@
+import * as plugins from './smartdaemon.plugins.js';
+export class SystemdServiceDefinitionError extends Error {
+    constructor() {
+        super('Invalid direct systemd service definition.');
+        this.name = 'SystemdServiceDefinitionError';
+    }
+}
+/** Literal direct-execution definition; never introduces a shell or environment expansion. */
+export class SystemdServiceDefinition {
+    constructor(options) {
+        const requireValue = (value) => {
+            if (!value)
+                throw new SystemdServiceDefinitionError();
+        };
+        const text = (value, maximum = 4096) => typeof value === 'string' && value.length <= maximum && !/[\x00-\x1f\x7f]/.test(value) &&
+            !/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(value);
+        const absolute = (value) => text(value) && plugins.path.isAbsolute(value) &&
+            plugins.path.normalize(value) === value;
+        const keys = [
+            'unitName',
+            'description',
+            'executable',
+            'args',
+            'workingDirectory',
+            'user',
+            'group',
+            'restart',
+            'killMode',
+            'timeoutStopSeconds',
+        ];
+        requireValue(options && Object.getPrototypeOf(options) === Object.prototype &&
+            Reflect.ownKeys(options).length === keys.length && keys.every((key) => {
+            const descriptor = Object.getOwnPropertyDescriptor(options, key);
+            return descriptor && 'value' in descriptor;
+        }));
+        requireValue(typeof options.unitName === 'string' &&
+            /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,230}\.service$/.test(options.unitName));
+        requireValue(text(options.description, 1024) && options.description.length > 0 &&
+            options.description.trim() === options.description && !options.description.includes('\\'));
+        requireValue(absolute(options.executable) && options.executable !== '/' &&
+            !/[\\"']/.test(options.executable) && !options.executable.endsWith('/') &&
+            absolute(options.workingDirectory) &&
+            options.workingDirectory.trim() === options.workingDirectory &&
+            !options.workingDirectory.includes('\\'));
+        requireValue(Array.isArray(options.args) && Object.getPrototypeOf(options.args) === Array.prototype &&
+            options.args.length <= 128 &&
+            Reflect.ownKeys(options.args).length === options.args.length + 1 &&
+            Array.from({ length: options.args.length }, (_, index) => Object.getOwnPropertyDescriptor(options.args, String(index)))
+                .every((descriptor) => descriptor && 'value' in descriptor && text(descriptor.value)));
+        requireValue([options.user, options.group].every((value) => typeof value === 'string' && /^[a-zA-Z_][a-zA-Z0-9_-]{0,63}$/.test(value)));
+        requireValue(['no', 'on-failure', 'always'].includes(options.restart) &&
+            ['mixed', 'control-group'].includes(options.killMode) &&
+            Number.isSafeInteger(options.timeoutStopSeconds) &&
+            options.timeoutStopSeconds >= 1 && options.timeoutStopSeconds <= 600);
+        // Quoting and percent/dollar escaping follow systemd.syntax and systemd.service.
+        const quote = (value, command = false) => '"' + value
+            .replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%')
+            .replaceAll('$', () => command ? '$$' : '$') +
+            '"';
+        this.unitName = options.unitName;
+        this.content = [
+            '[Unit]',
+            `Description=${options.description.replaceAll('%', '%%')}`,
+            'After=local-fs.target',
+            '',
+            '[Service]',
+            'Type=exec',
+            `User=${options.user}`,
+            `Group=${options.group}`,
+            `ExecStart=${[quote(options.executable), ...options.args.map((value) => quote(value, true))].join(' ')}`,
+            // WorkingDirectory is a raw path value, not an ExecStart word list.
+            `WorkingDirectory=${options.workingDirectory.replaceAll('%', '%%')}`,
+            `Restart=${options.restart}`,
+            `KillMode=${options.killMode}`,
+            'KillSignal=SIGTERM',
+            'FinalKillSignal=SIGKILL',
+            'SendSIGKILL=yes',
+            'SendSIGHUP=no',
+            `TimeoutStopSec=${options.timeoutStopSeconds}s`,
+            'StandardInput=null',
+            'StandardOutput=journal',
+            'StandardError=journal',
+            '',
+            '[Install]',
+            'WantedBy=multi-user.target',
+            '',
+        ].join('\n');
+        requireValue(Buffer.byteLength(this.content) <= 16384);
+        this.sha256 = plugins.crypto.createHash('sha256').update(this.content).digest('hex');
+        Object.freeze(this);
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5zeXN0ZW1kc2VydmljZWRlZmluaXRpb24uanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9jbGFzc2VzLnN5c3RlbWRzZXJ2aWNlZGVmaW5pdGlvbi50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLDBCQUEwQixDQUFDO0FBZXBELE1BQU0sT0FBTyw2QkFBOEIsU0FBUSxLQUFLO0lBQ3REO1FBQ0UsS0FBSyxDQUFDLDRDQUE0QyxDQUFDLENBQUM7UUFDcEQsSUFBSSxDQUFDLElBQUksR0FBRywrQkFBK0IsQ0FBQztJQUM5QyxDQUFDO0NBQ0Y7QUFFRCw4RkFBOEY7QUFDOUYsTUFBTSxPQUFPLHdCQUF3QjtJQUtuQyxZQUFZLE9BQXlDO1FBQ25ELE1BQU0sWUFBWSxHQUFHLENBQUMsS0FBYyxFQUFRLEVBQUU7WUFDNUMsSUFBSSxDQUFDLEtBQUs7Z0JBQUUsTUFBTSxJQUFJLDZCQUE2QixFQUFFLENBQUM7UUFDeEQsQ0FBQyxDQUFDO1FBQ0YsTUFBTSxJQUFJLEdBQUcsQ0FBQyxLQUFjLEVBQUUsT0FBTyxHQUFHLElBQUksRUFBbUIsRUFBRSxDQUMvRCxPQUFPLEtBQUssS0FBSyxRQUFRLElBQUksS0FBSyxDQUFDLE1BQU0sSUFBSSxPQUFPLElBQUksQ0FBQyxpQkFBaUIsQ0FBQyxJQUFJLENBQUMsS0FBSyxDQUFDO1lBQ3RGLENBQUMseUVBQXlFLENBQUMsSUFBSSxDQUFDLEtBQUssQ0FBQyxDQUFDO1FBQ3pGLE1BQU0sUUFBUSxHQUFHLENBQUMsS0FBYyxFQUFFLEVBQUUsQ0FDbEMsSUFBSSxDQUFDLEtBQUssQ0FBQyxJQUFJLE9BQU8sQ0FBQyxJQUFJLENBQUMsVUFBVSxDQUFDLEtBQUssQ0FBQztZQUM3QyxPQUFPLENBQUMsSUFBSSxDQUFDLFNBQVMsQ0FBQyxLQUFLLENBQUMsS0FBSyxLQUFLLENBQUM7UUFDMUMsTUFBTSxJQUFJLEdBQUc7WUFDWCxVQUFVO1lBQ1YsYUFBYTtZ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

package/dist_ts/classes.systemdunit.d.ts

@@ -0,0 +1,49 @@
+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 interface ISystemdUnitConfigurationState {
+    readonly unitName: string;
+    readonly fragmentPath: string;
+    /** Opaque systemctl path list. An empty value proves no effective drop-ins. */
+    readonly dropInPaths: string;
+    readonly needsReload: boolean;
+}
+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>;
+    /** Reports the manager's selected definition without reading or changing its contents. */
+    inspectConfiguration(): Promise<ISystemdUnitConfigurationState>;
+    /** Reloads unit definitions globally; does not enable, unmask, start or stop a unit. */
+    reloadConfiguration(): Promise<ISystemdUnitConfigurationState>;
+    private command;
+}

package/dist_ts/classes.systemdunit.js

@@ -0,0 +1,125 @@
+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();
+    }
+    /** Reports the manager's selected definition without reading or changing its contents. */
+    async inspectConfiguration() {
+        const keys = ['Id', 'FragmentPath', 'DropInPaths', 'NeedDaemonReload'];
+        const stdout = await this.command(['show', this.unitName, `--property=${keys.join(',')}`, '--all']);
+        const fields = new Map();
+        for (const line of stdout.trimEnd().split('\n')) {
+            const separator = line.indexOf('='), key = line.slice(0, separator);
+            if (separator < 1 || !keys.includes(key) || fields.has(key)) {
+                throw new SystemdUnitError('invalid_state');
+            }
+            fields.set(key, line.slice(separator + 1));
+        }
+        if (fields.size !== keys.length || fields.get('Id') !== this.unitName ||
+            !['yes', 'no'].includes(fields.get('NeedDaemonReload'))) {
+            throw new SystemdUnitError('invalid_state');
+        }
+        return Object.freeze({
+            unitName: this.unitName,
+            fragmentPath: fields.get('FragmentPath'),
+            dropInPaths: fields.get('DropInPaths'),
+            needsReload: fields.get('NeedDaemonReload') === 'yes',
+        });
+    }
+    /** Reloads unit definitions globally; does not enable, unmask, start or stop a unit. */
+    async reloadConfiguration() {
+        await this.command(['daemon-reload']);
+        return this.inspectConfiguration();
+    }
+    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,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5zeXN0ZW1kdW5pdC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL2NsYXNzZXMuc3lzdGVtZHVuaXQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSwwQkFBMEIsQ0FBQztBQWdDcEQsTUFBTSxPQUFPLGdCQUFpQixTQUFRLEtBQUs7SUFDekMsWUFBNEIsSUFBNEQ7UUFDdEYsS0FBSyxDQUFDLGtDQUFrQyxJQUFJLEdBQUcsQ0FBQyxDQUFDO1FBRHZCLFNBQUksR0FBSixJQUFJLENBQXdEO1FBRXRGLElBQUksQ0FBQyxJQUFJLEdBQUcsa0JBQWtCLENBQUM7SUFDakMsQ0FBQztDQUNGO0FBRUQsTUFBTSxVQUFVLEdBQUc7SUFDakIsSUFBSTtJQUNKLFdBQVc7SUFDWCxhQUFhO0lBQ2IsVUFBVTtJQUNWLGVBQWU7SUFDZixTQUFTO0lBQ1QsWUFBWTtJQUNaLGNBQWM7SUFDZCxVQUFVO0lBQ1YsS0FBSztDQUNHLENBQUM7QUFFWCw2R0FBNkc7QUFDN0csTUFBTSxPQUFPLFdBQVc7SUFLdEIsWUFBWSxVQUErQjtRQUN6QyxJQUFJLENBQUMsUUFBUSxHQUFHLFVBQVUsRUFBRSxRQUFRLENBQUM7UUFDckMsSUFBSSxDQUFDLFVBQVUsR0FBRyxVQUFVLEVBQUUsYUFBYSxJQUFJLG9CQUFvQixDQUFDO1FBQ3BFLElBQUksQ0FBQyxPQUFPLEdBQUcsVUFBVSxFQUFFLGdCQUFnQixJQUFJLE1BQU0sQ0FBQztRQUN0RCxJQUNFLE9BQU8sSUFBSSxDQUFDLFFBQVEsS0FBSyxRQUFRO1lBQ2pDLENBQUMsK0NBQStDLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxRQUFRLENBQUM7WUFDcEUsT0FBTyxJQUFJLENBQUMsVUFBVSxLQUFLLFFBQVEsSUFBSSxDQUFDLE9BQU8sQ0FBQyxJQUFJLENBQUMsVUFBVSxDQUFDLElBQUksQ0FBQyxVQUFVLENBQUM7WUFDaEYsSUFBSSxDQUFDLFVBQVUsQ0FBQyxR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

package/dist_ts/classes.systemdunitfile.d.ts

@@ -0,0 +1,45 @@
+import { SystemdServiceDefinition } from './classes.systemdservicedefinition.js';
+import { type ISystemdUnitOptions } from './classes.systemdunit.js';
+export interface ISystemdUnitFileOptions extends ISystemdUnitOptions {
+    /** Local vendor definitions can be installed without removing an administrator's mask. */
+    unitDirectory?: string;
+    /** Trusted owning-code qualification only. Defaults to root. */
+    expectedUid?: number;
+}
+export interface ISystemdUnitFileRecord {
+    readonly path: string;
+    readonly sha256: string;
+}
+export declare class SystemdUnitFileError extends Error {
+    readonly code: 'invalid_options' | 'unsafe_path' | 'busy' | 'changed' | 'unsafe_unit' | 'write_failed' | 'reload_failed';
+    constructor(code: 'invalid_options' | 'unsafe_path' | 'busy' | 'changed' | 'unsafe_unit' | 'write_failed' | 'reload_failed');
+}
+/**
+ * Protected code/config installation, inside the caller's cross-process installation ownership scope.
+ * Other privileged writers must be serialized by that owner. Never changes enablement or masks.
+ */
+export declare class SystemdUnitFile {
+    readonly path: string;
+    private readonly directory;
+    private readonly uid;
+    private readonly unit;
+    private readonly name;
+    private busy;
+    constructor(options: ISystemdUnitFileOptions);
+    /** Reads only the exact protected definition; no systemd or filesystem mutation. */
+    inspect(): Promise<ISystemdUnitFileRecord | null>;
+    /**
+     * Expected previous digest is mandatory; null admits an absent file. Exact desired bytes are idempotent.
+     * Retains changed definitions beside the unit before replacement. A failed reload never rolls code back.
+     */
+    install(definition: SystemdServiceDefinition, expectedSha256: string | null): Promise<Readonly<{
+        changed: boolean;
+        record: ISystemdUnitFileRecord;
+        masked: boolean;
+    }>>;
+    private admit;
+    private directories;
+    private read;
+    private create;
+    private flushDirectory;
+}