@adecore/service 0.48.3 → 0.49.0

package/dist/cmd-line.d.ts

@@ -1,2 +1,4 @@
 export declare function cmdEscaped(text: string): string;
+export declare function batchEscaped(text: string): string;
+export declare function scheduledTaskScriptName(label: string): string;
 export declare function scheduledTaskMarker(label: string): string;

package/dist/cmd-line.js

@@ -3,9 +3,18 @@ const CMD_SPECIAL = /([()\][%!^"`<>&|;, *?])/g;
 export function cmdEscaped(text) {
     return text.replace(CMD_SPECIAL, '^$1');
 }
+/* The same on a line of a batch file, where cmd.exe reads `%` before any caret: only doubling keeps one. */
+export function batchEscaped(text) {
+    return text.replace(/[()\][!^"`<>&|;, *?]/g, '^$&').replace(/%/g, '%%');
+}
+/* The script of a task, beside its definition. Without anything that would need quoting on its command line. */
+export function scheduledTaskScriptName(label) {
+    return `${label.replace(/[^\w.-]/g, '_')}.cmd`;
+}
 /*
- * What a manager finds the cmd.exe of a task by: `schtasks /End` ends that process alone, so a stop
- * has to end the tree under it first. Its title is the label, which is the name of the task.
+ * What a manager finds the cmd.exe of a task from before it had a script by: `schtasks /End` ends that
+ * process alone, so a stop has to end the tree under it first. Its title is the label, which is the name
+ * of the task. A task on a script is found by the script's name on the cmd.exe line.
  */
 export function scheduledTaskMarker(label) {
     return `title ${cmdEscaped(label)} && `;

package/dist/definitions.d.ts

@@ -7,8 +7,13 @@ export interface ServiceSpec {
     workingDirectory: string;
     logFile: string;
     user?: string;
+    scriptDirectory?: string;
 }
 export declare function launchAgentPlist(spec: ServiceSpec): string;
 export declare function systemdUnit(spec: ServiceSpec): string;
 export declare function scheduledTask(spec: ServiceSpec): string;
+export declare function scheduledTaskScript(definition: string): {
+    path: string;
+    text: string;
+} | null;
 export declare function definitionRunsProgram(definition: string, program: string): boolean;

package/dist/definitions.js

@@ -1,9 +1,13 @@
-import { cmdEscaped, scheduledTaskMarker } from './cmd-line.js';
+import { batchEscaped, cmdEscaped, scheduledTaskScriptName } from './cmd-line.js';
 function xmlText(value) {
     return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
 function xmlValue(text) {
-    return text.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&');
+    return text
+        .replace(/&#(\d+);/g, (_, code) => String.fromCodePoint(Number(code)))
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&amp;/g, '&');
 }
 function plistString(value, indent) {
     return `${indent}<string>${xmlText(value)}</string>`;
@@ -64,21 +68,44 @@ function cmdArgument(arg) {
     if (/[\r\n]/.test(arg)) {
         throw new Error('A scheduled task cannot pass on a line break');
     }
-    return cmdEscaped(`"${arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, '$1$1')}"`);
+    return batchEscaped(`"${arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, '$1$1')}"`);
 }
-function taskCommandLine(spec) {
-    const variables = Object.entries(spec.environment).map(([name, value]) => `set ${cmdEscaped(`"${name}=${value}"`)}`);
-    const program = [cmdEscaped(spec.program), ...spec.args.map(cmdArgument)].join(' ');
-    return `${scheduledTaskMarker(spec.label)}${[...variables, `${program} >>${cmdEscaped(spec.logFile)} 2>&1`].join(' && ')}`;
+/* In quotes of its own, or the C runtime of the program splits its own path at a space, whatever the carets told cmd.exe. */
+function batchProgram(program) {
+    return batchEscaped(`"${program}"`);
+}
+/* The code page first, or cmd.exe reads the UTF-8 of a path outside the system's code page as something else. */
+function taskScript(spec) {
+    const variables = Object.entries(spec.environment).map(([name, value]) => `set ${batchEscaped(`"${name}=${value}"`)}`);
+    const program = [batchProgram(spec.program), ...spec.args.map(cmdArgument)].join(' ');
+    const lines = [
+        '@echo off',
+        'chcp 65001 >nul',
+        `cd /d ${batchEscaped(spec.workingDirectory)} || exit /b 1`,
+        ...variables,
+        `${program} >>${batchEscaped(spec.logFile)} 2>&1`
+    ];
+    if (lines.some((line) => /[\r\n]/.test(line))) {
+        throw new Error('A scheduled task cannot pass on a line break');
+    }
+    return `${lines.join('\r\n')}\r\n`;
 }
 /*
  * Started at the person's logon without a stored password, and run again every minute so it comes back
- * after a crash. RestartOnFailure would also start a task a stop ended. cmd.exe sets the environment.
+ * after a crash. RestartOnFailure would also start a task a stop ended.
+ *
+ * A task with an interactive token gives a console program a window, and closing that ends it. Only a
+ * headless conhost.exe shows none, but it joins its arguments again and loses every inner quote. So
+ * what needs quoting moves into a script, which the task starts from its own folder by a bare name.
+ * The definition carries the script in `Documentation`, and a manager writes it out on install.
  */
 export function scheduledTask(spec) {
     if (spec.user === undefined || spec.user === '') {
         throw new Error('A scheduled task needs the user it starts for.');
     }
+    if (spec.scriptDirectory === undefined || spec.scriptDirectory === '') {
+        throw new Error('A scheduled task needs the folder of its script.');
+    }
     const user = xmlText(spec.user);
     // No XML declaration: schtasks decodes the file itself and refuses one that names an encoding.
     const lines = [
@@ -86,6 +113,7 @@ export function scheduledTask(spec) {
         '  <RegistrationInfo>',
         `    <Description>${xmlText(spec.description)}</Description>`,
         `    <URI>\\${xmlText(spec.label)}</URI>`,
+        `    <Documentation>${xmlText(taskScript(spec))}</Documentation>`,
         '  </RegistrationInfo>',
         '  <Triggers>',
         '    <LogonTrigger>',
@@ -127,17 +155,33 @@ export function scheduledTask(spec) {
         '  </Settings>',
         '  <Actions Context="Author">',
         '    <Exec>',
-        '      <Command>%SystemRoot%\\System32\\cmd.exe</Command>',
-        `      <Arguments>${xmlText(`/d /s /c "${taskCommandLine(spec)}"`)}</Arguments>`,
-        `      <WorkingDirectory>${xmlText(spec.workingDirectory)}</WorkingDirectory>`,
+        '      <Command>%SystemRoot%\\System32\\conhost.exe</Command>',
+        `      <Arguments>--headless cmd.exe /d /c .\\${scheduledTaskScriptName(spec.label)}</Arguments>`,
+        `      <WorkingDirectory>${xmlText(spec.scriptDirectory)}</WorkingDirectory>`,
         '    </Exec>',
         '  </Actions>',
         '</Task>',
         ''
     ];
-    return lines.join('\r\n');
+    // ASCII with character references: schtasks reads a UTF-8 file as the system's code page, and refuses a BOM.
+    return lines.join('\r\n').replace(/[\u0080-\u{10ffff}]/gu, (character) => `&#${character.codePointAt(0)};`);
+}
+/* The script a definition starts, null for any other definition and for a task from before it had one. */
+export function scheduledTaskScript(definition) {
+    const text = /<Documentation>([^<]*)<\/Documentation>/.exec(definition)?.[1];
+    const name = /<Arguments>--headless cmd\.exe \/d \/c \.\\([^<]+)<\/Arguments>/.exec(definition)?.[1];
+    const folder = /<WorkingDirectory>([^<]*)<\/WorkingDirectory>/.exec(definition)?.[1];
+    if (text === undefined || name === undefined || folder === undefined) {
+        return null;
+    }
+    return { path: `${xmlValue(folder).replace(/\\$/, '')}\\${name}`, text: xmlValue(text) };
 }
 function scheduledTaskRunsProgram(definition, program) {
+    const script = scheduledTaskScript(definition);
+    if (script !== null) {
+        return (script.text.trimEnd().split('\r\n').at(-1) ?? '').startsWith(`${batchProgram(program)} `);
+    }
+    // A task from before the script: its one line ends in the program.
     const exec = definition.match(/<Exec>[\s\S]*?<\/Exec>/g);
     if (exec?.length !== 1) {
         return false;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { definitionRunsProgram, launchAgentPlist, scheduledTask, systemdUnit, type ServiceSpec } from './definitions.js';
+export { definitionRunsProgram, launchAgentPlist, scheduledTask, scheduledTaskScript, systemdUnit, type ServiceSpec } from './definitions.js';
 export { launchdManager, systemdManager, taskSchedulerManager, type CommandResult, type CommandRunner, type LaunchdOptions, type ServiceFiles, type ServiceManager, type SystemdOptions, type TaskSchedulerOptions } from './manager.js';
 export { platformServiceManager, serviceDefinition, type PlatformServiceOptions } from './platform.js';
 export { diskFiles, runCommand } from './system.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { definitionRunsProgram, launchAgentPlist, scheduledTask, systemdUnit } from './definitions.js';
+export { definitionRunsProgram, launchAgentPlist, scheduledTask, scheduledTaskScript, systemdUnit } from './definitions.js';
 export { launchdManager, systemdManager, taskSchedulerManager } from './manager.js';
 export { platformServiceManager, serviceDefinition } from './platform.js';
 export { diskFiles, runCommand } from './system.js';

package/dist/manager.js

@@ -1,5 +1,6 @@
 import { posix, win32 } from 'node:path';
-import { scheduledTaskMarker } from './cmd-line.js';
+import { scheduledTaskMarker, scheduledTaskScriptName } from './cmd-line.js';
+import { scheduledTaskScript } from './definitions.js';
 function expectSuccess(result, what) {
     if (result.code !== 0) {
         throw new Error(`${what} failed (${result.code}): ${(result.stderr || result.stdout).trim() || 'no output'}`);
@@ -134,9 +135,10 @@ export function taskSchedulerManager(options) {
     // Before `/End`, which leaves what the task's cmd.exe started running without a parent to find it by.
     const endTree = () => {
         const marker = scheduledTaskMarker(name).replace(/'/g, "''");
+        const scriptName = scheduledTaskScriptName(name);
         const script = [
             'Get-CimInstance Win32_Process -Filter "Name=\'cmd.exe\'"',
-            `Where-Object { $_.CommandLine -and $_.CommandLine.Contains('${marker}') }`,
+            `Where-Object { $_.CommandLine -and ($_.CommandLine.Contains('${scriptName}') -or $_.CommandLine.Contains('${marker}')) }`,
             'ForEach-Object { taskkill.exe /PID $_.ProcessId /T /F | Out-Null }'
         ].join(' | ');
         options.run('powershell.exe', ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64')]);
@@ -154,6 +156,10 @@ export function taskSchedulerManager(options) {
             // cmd.exe appends to the log but makes no folder for it, and the task ends at once without one.
             options.files.makeDirectory(win32.dirname(options.logFile));
             const previous = writeDefinition(options.files, path, definition);
+            const script = scheduledTaskScript(definition);
+            if (script !== null && options.files.read(script.path) !== script.text) {
+                options.files.write(script.path, script.text);
+            }
             if (previous !== definition || !exists()) {
                 expectSuccess(schtasks('/Create', '/TN', name, '/XML', path, '/F'), 'schtasks /Create');
             }
@@ -177,6 +183,10 @@ export function taskSchedulerManager(options) {
         },
         uninstall() {
             schtasks('/Delete', '/TN', name, '/F');
+            const script = scheduledTaskScript(options.files.read(path) ?? '');
+            if (script !== null) {
+                options.files.remove(script.path);
+            }
             options.files.remove(path);
         }
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/service",
-  "version": "0.48.3",
+  "version": "0.49.0",
   "description": "User service definitions and injectable launchd, systemd and Task Scheduler managers.",
   "license": "FSL-1.1-MIT",
   "author": "Bas Milius",

package/src/cmd-line.ts

@@ -5,9 +5,20 @@ export function cmdEscaped(text: string): string {
     return text.replace(CMD_SPECIAL, '^$1');
 }
 
+/* The same on a line of a batch file, where cmd.exe reads `%` before any caret: only doubling keeps one. */
+export function batchEscaped(text: string): string {
+    return text.replace(/[()\][!^"`<>&|;, *?]/g, '^$&').replace(/%/g, '%%');
+}
+
+/* The script of a task, beside its definition. Without anything that would need quoting on its command line. */
+export function scheduledTaskScriptName(label: string): string {
+    return `${label.replace(/[^\w.-]/g, '_')}.cmd`;
+}
+
 /*
- * What a manager finds the cmd.exe of a task by: `schtasks /End` ends that process alone, so a stop
- * has to end the tree under it first. Its title is the label, which is the name of the task.
+ * What a manager finds the cmd.exe of a task from before it had a script by: `schtasks /End` ends that
+ * process alone, so a stop has to end the tree under it first. Its title is the label, which is the name
+ * of the task. A task on a script is found by the script's name on the cmd.exe line.
  */
 export function scheduledTaskMarker(label: string): string {
     return `title ${cmdEscaped(label)} && `;

package/src/definitions.ts

@@ -1,4 +1,4 @@
-import { cmdEscaped, scheduledTaskMarker } from './cmd-line.js';
+import { batchEscaped, cmdEscaped, scheduledTaskScriptName } from './cmd-line.js';
 
 export interface ServiceSpec {
     label: string;
@@ -11,6 +11,8 @@ export interface ServiceSpec {
     logFile: string;
     /* The scheduled task only, which needs it: the account it starts for at logon, as `DOMAIN\\name`. */
     user?: string;
+    /* The scheduled task only, which needs it: the folder of the script it runs. */
+    scriptDirectory?: string;
 }
 
 function xmlText(value: string): string {
@@ -18,7 +20,11 @@ function xmlText(value: string): string {
 }
 
 function xmlValue(text: string): string {
-    return text.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&');
+    return text
+        .replace(/&#(\d+);/g, (_, code: string) => String.fromCodePoint(Number(code)))
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&amp;/g, '&');
 }
 
 function plistString(value: string, indent: string): string {
@@ -108,25 +114,51 @@ function cmdArgument(arg: string): string {
         throw new Error('A scheduled task cannot pass on a line break');
     }
 
-    return cmdEscaped(`"${arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, '$1$1')}"`);
+    return batchEscaped(`"${arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, '$1$1')}"`);
 }
 
-function taskCommandLine(spec: ServiceSpec): string {
-    const variables = Object.entries(spec.environment).map(([name, value]) => `set ${cmdEscaped(`"${name}=${value}"`)}`);
-    const program = [cmdEscaped(spec.program), ...spec.args.map(cmdArgument)].join(' ');
+/* In quotes of its own, or the C runtime of the program splits its own path at a space, whatever the carets told cmd.exe. */
+function batchProgram(program: string): string {
+    return batchEscaped(`"${program}"`);
+}
 
-    return `${scheduledTaskMarker(spec.label)}${[...variables, `${program} >>${cmdEscaped(spec.logFile)} 2>&1`].join(' && ')}`;
+/* The code page first, or cmd.exe reads the UTF-8 of a path outside the system's code page as something else. */
+function taskScript(spec: ServiceSpec): string {
+    const variables = Object.entries(spec.environment).map(([name, value]) => `set ${batchEscaped(`"${name}=${value}"`)}`);
+    const program = [batchProgram(spec.program), ...spec.args.map(cmdArgument)].join(' ');
+    const lines = [
+        '@echo off',
+        'chcp 65001 >nul',
+        `cd /d ${batchEscaped(spec.workingDirectory)} || exit /b 1`,
+        ...variables,
+        `${program} >>${batchEscaped(spec.logFile)} 2>&1`
+    ];
+
+    if (lines.some((line) => /[\r\n]/.test(line))) {
+        throw new Error('A scheduled task cannot pass on a line break');
+    }
+
+    return `${lines.join('\r\n')}\r\n`;
 }
 
 /*
  * Started at the person's logon without a stored password, and run again every minute so it comes back
- * after a crash. RestartOnFailure would also start a task a stop ended. cmd.exe sets the environment.
+ * after a crash. RestartOnFailure would also start a task a stop ended.
+ *
+ * A task with an interactive token gives a console program a window, and closing that ends it. Only a
+ * headless conhost.exe shows none, but it joins its arguments again and loses every inner quote. So
+ * what needs quoting moves into a script, which the task starts from its own folder by a bare name.
+ * The definition carries the script in `Documentation`, and a manager writes it out on install.
  */
 export function scheduledTask(spec: ServiceSpec): string {
     if (spec.user === undefined || spec.user === '') {
         throw new Error('A scheduled task needs the user it starts for.');
     }
 
+    if (spec.scriptDirectory === undefined || spec.scriptDirectory === '') {
+        throw new Error('A scheduled task needs the folder of its script.');
+    }
+
     const user = xmlText(spec.user);
 
     // No XML declaration: schtasks decodes the file itself and refuses one that names an encoding.
@@ -135,6 +167,7 @@ export function scheduledTask(spec: ServiceSpec): string {
         '  <RegistrationInfo>',
         `    <Description>${xmlText(spec.description)}</Description>`,
         `    <URI>\\${xmlText(spec.label)}</URI>`,
+        `    <Documentation>${xmlText(taskScript(spec))}</Documentation>`,
         '  </RegistrationInfo>',
         '  <Triggers>',
         '    <LogonTrigger>',
@@ -176,19 +209,40 @@ export function scheduledTask(spec: ServiceSpec): string {
         '  </Settings>',
         '  <Actions Context="Author">',
         '    <Exec>',
-        '      <Command>%SystemRoot%\\System32\\cmd.exe</Command>',
-        `      <Arguments>${xmlText(`/d /s /c "${taskCommandLine(spec)}"`)}</Arguments>`,
-        `      <WorkingDirectory>${xmlText(spec.workingDirectory)}</WorkingDirectory>`,
+        '      <Command>%SystemRoot%\\System32\\conhost.exe</Command>',
+        `      <Arguments>--headless cmd.exe /d /c .\\${scheduledTaskScriptName(spec.label)}</Arguments>`,
+        `      <WorkingDirectory>${xmlText(spec.scriptDirectory)}</WorkingDirectory>`,
         '    </Exec>',
         '  </Actions>',
         '</Task>',
         ''
     ];
 
-    return lines.join('\r\n');
+    // ASCII with character references: schtasks reads a UTF-8 file as the system's code page, and refuses a BOM.
+    return lines.join('\r\n').replace(/[\u0080-\u{10ffff}]/gu, (character) => `&#${character.codePointAt(0)};`);
+}
+
+/* The script a definition starts, null for any other definition and for a task from before it had one. */
+export function scheduledTaskScript(definition: string): { path: string; text: string } | null {
+    const text = /<Documentation>([^<]*)<\/Documentation>/.exec(definition)?.[1];
+    const name = /<Arguments>--headless cmd\.exe \/d \/c \.\\([^<]+)<\/Arguments>/.exec(definition)?.[1];
+    const folder = /<WorkingDirectory>([^<]*)<\/WorkingDirectory>/.exec(definition)?.[1];
+
+    if (text === undefined || name === undefined || folder === undefined) {
+        return null;
+    }
+
+    return { path: `${xmlValue(folder).replace(/\\$/, '')}\\${name}`, text: xmlValue(text) };
 }
 
 function scheduledTaskRunsProgram(definition: string, program: string): boolean {
+    const script = scheduledTaskScript(definition);
+
+    if (script !== null) {
+        return (script.text.trimEnd().split('\r\n').at(-1) ?? '').startsWith(`${batchProgram(program)} `);
+    }
+
+    // A task from before the script: its one line ends in the program.
     const exec = definition.match(/<Exec>[\s\S]*?<\/Exec>/g);
 
     if (exec?.length !== 1) {

package/src/index.ts

@@ -1,4 +1,4 @@
-export { definitionRunsProgram, launchAgentPlist, scheduledTask, systemdUnit, type ServiceSpec } from './definitions.js';
+export { definitionRunsProgram, launchAgentPlist, scheduledTask, scheduledTaskScript, systemdUnit, type ServiceSpec } from './definitions.js';
 export {
     launchdManager,
     systemdManager,

package/src/manager.ts

@@ -1,5 +1,6 @@
 import { posix, win32 } from 'node:path';
-import { scheduledTaskMarker } from './cmd-line.js';
+import { scheduledTaskMarker, scheduledTaskScriptName } from './cmd-line.js';
+import { scheduledTaskScript } from './definitions.js';
 
 export interface CommandResult {
     code: number;
@@ -231,10 +232,11 @@ export function taskSchedulerManager(options: TaskSchedulerOptions): ServiceMana
     // Before `/End`, which leaves what the task's cmd.exe started running without a parent to find it by.
     const endTree = (): void => {
         const marker = scheduledTaskMarker(name).replace(/'/g, "''");
+        const scriptName = scheduledTaskScriptName(name);
 
         const script = [
             'Get-CimInstance Win32_Process -Filter "Name=\'cmd.exe\'"',
-            `Where-Object { $_.CommandLine -and $_.CommandLine.Contains('${marker}') }`,
+            `Where-Object { $_.CommandLine -and ($_.CommandLine.Contains('${scriptName}') -or $_.CommandLine.Contains('${marker}')) }`,
             'ForEach-Object { taskkill.exe /PID $_.ProcessId /T /F | Out-Null }'
         ].join(' | ');
 
@@ -255,6 +257,11 @@ export function taskSchedulerManager(options: TaskSchedulerOptions): ServiceMana
             // cmd.exe appends to the log but makes no folder for it, and the task ends at once without one.
             options.files.makeDirectory(win32.dirname(options.logFile));
             const previous = writeDefinition(options.files, path, definition);
+            const script = scheduledTaskScript(definition);
+
+            if (script !== null && options.files.read(script.path) !== script.text) {
+                options.files.write(script.path, script.text);
+            }
 
             if (previous !== definition || !exists()) {
                 expectSuccess(schtasks('/Create', '/TN', name, '/XML', path, '/F'), 'schtasks /Create');
@@ -281,6 +288,12 @@ export function taskSchedulerManager(options: TaskSchedulerOptions): ServiceMana
         },
         uninstall() {
             schtasks('/Delete', '/TN', name, '/F');
+            const script = scheduledTaskScript(options.files.read(path) ?? '');
+
+            if (script !== null) {
+                options.files.remove(script.path);
+            }
+
             options.files.remove(path);
         }
     };