deepwork-node-watchdog-window-service

Windows service manager for deepwork-node-watchdog.

Installs and manages the watchdog as a Windows background service that starts automatically with the system. Can be used as a global CLI or imported as a Node.js module.

Windows only. Requires Node.js 16+.

Requirements

The deepwork-node-watchdog package must be installed globally before starting the service:

npm install -g deepwork-node-watchdog

Global CLI

Installation

npm install -g deepwork-node-watchdog-window-service

Commands

| Command | Description | |---|---| | deepwork-watchdog-service start | Install (if needed) and start the service | | deepwork-watchdog-service start --blacklist <path> | Start with a custom blacklist file | | deepwork-watchdog-service start --blacklist <app1,app2> | Start with inline comma-separated values | | deepwork-watchdog-service stop | Stop and uninstall the service | | deepwork-watchdog-service status | Print the current service state | | deepwork-watchdog-service logs | Snapshot of all log files | | deepwork-watchdog-service logs -t | Stream the output log in real-time | | deepwork-watchdog-service logs --tail | Same as -t | | deepwork-watchdog-service pwd | Print the expected blacklist.txt location | | deepwork-watchdog-service -v | Print the installed version | | deepwork-watchdog-service --version | Same as -v |

Note: start and stop require an elevated (Administrator) terminal.

Blacklist setup

There are two ways to define the blacklist:

Option A — File (recommended for persistent config)

deepwork-watchdog-service pwd
# C:\Users\<you>\.deepwork\blacklist.txt

Create the file at that path with one application name per line (partial match, case-insensitive):

discord
whatsapp
spotify
steam
epic games

Then start normally:

deepwork-watchdog-service start

Option B — Inline values (no file needed)

Pass a comma-separated list directly with --blacklist:

deepwork-watchdog-service start --blacklist "discord,spotify,steam"

If the value contains a , it is treated as an inline list. Otherwise it is treated as a file path.

Option C — Custom file path

deepwork-watchdog-service start --blacklist "C:\Users\kevin\my-blacklist.txt"

Real-time log streaming

deepwork-watchdog-service logs -t
# Polls the .out.log every 500ms and prints new lines.
# Press Ctrl+C to exit.

Full example

# 1. Install dependencies
npm install -g deepwork-node-watchdog
npm install -g deepwork-node-watchdog-window-service

# 2. Start with inline values (no file needed)
deepwork-watchdog-service start --blacklist "discord,spotify,steam"
# → Service started successfully.

# 3. Check state
deepwork-watchdog-service status
# → Service status: RUNNING

# 4. Watch logs live
deepwork-watchdog-service logs -t

# 5. Stop
deepwork-watchdog-service stop
# → Service stopped and uninstalled.

Module usage

Installation

npm install deepwork-node-watchdog-window-service

CommonJS

const {
  startService,
  stopService,
  statusService,
  logsService,
  tailLogsService,
} = require('deepwork-node-watchdog-window-service');

// Start with default blacklist path (~/.deepwork/blacklist.txt)
startService().then(result => {
  console.log(result.message); // "Service started successfully."
  console.log(result.success); // true | false
});

// Start with a custom file path
startService({ blacklistPath: 'C:\\Users\\kevin\\blacklist.txt' })
  .then(result => console.log(result.message));

// Start with inline values (no file needed)
startService({ blacklistValues: ['discord', 'spotify', 'steam'] })
  .then(result => console.log(result.message));

// Check status
statusService().then(result => {
  console.log(result.status);  // "RUNNING" | "STOPPED" | ...
  console.log(result.message); // "Service status: RUNNING"
});

// Snapshot logs
logsService().then(result => {
  if (result.success) console.log(result.message);
});

// Real-time tail (polls every 500ms, runs until Ctrl+C)
tailLogsService();

// Stop
stopService().then(result => console.log(result.message));

TypeScript

import {
  startService,
  stopService,
  statusService,
  logsService,
  tailLogsService,
} from 'deepwork-node-watchdog-window-service';

import type {
  ServiceOptions,
  ServiceResult,
  StatusResult,
  ServiceStatus,
} from 'deepwork-node-watchdog-window-service';

// Using a file
const optsFile: ServiceOptions = {
  blacklistPath: 'C:\\Users\\kevin\\.deepwork\\blacklist.txt',
};
const result: ServiceResult = await startService(optsFile);

// Using inline values
const optsInline: ServiceOptions = {
  blacklistValues: ['discord', 'spotify', 'steam'],
};
const result2: ServiceResult = await startService(optsInline);

const status: StatusResult = await statusService();
if (status.status === 'RUNNING') {
  console.log('Watchdog is active.');
}

// Real-time tail (does not return — runs until Ctrl+C)
tailLogsService();

API Reference

startService(options?: ServiceOptions): Promise<ServiceResult>

Installs the Windows service (if not already installed) and starts it.

• options.blacklistPath — absolute path to blacklist.txt. Defaults to the path printed by pwd.
• options.blacklistValues — array of app names to block. Takes precedence over blacklistPath when provided.
• Validates that deepwork-node-watchdog is installed globally before proceeding.
• Returns { success: false } if neither blacklistValues nor a valid blacklistPath is provided.

stopService(): Promise<ServiceResult>

Stops and uninstalls the Windows service. Returns { success: false } if not installed.

statusService(): Promise<StatusResult>

Queries the current Windows service state via sc.exe.

logsService(): Promise<ServiceResult>

Reads all log files (OUT, ERR, WRAPPER) and returns them concatenated in result.message.

tailLogsService(pollIntervalMs?: number): void

Polls the .out.log file at the given interval (default 500ms) and prints new bytes as they arrive. Does not return — runs until SIGINT (Ctrl+C).

checkDeepworkWatchdogInstalled(): Promise<void>

Verifies that deepwork-node-watchdog is installed globally. Rejects with an install instruction if not found.

Types

type ServiceStatus =
  | 'STOPPED' | 'START_PENDING' | 'STOP_PENDING'
  | 'RUNNING' | 'CONTINUE_PENDING' | 'PAUSE_PENDING'
  | 'PAUSED' | 'UNKNOWN';

interface ServiceOptions {
  blacklistPath?: string;    // path to blacklist.txt
  blacklistValues?: string[]; // inline list of app names
}

interface ServiceResult {
  success: boolean;
  message: string;
}

interface StatusResult extends ServiceResult {
  status?: ServiceStatus;
}

Blacklist format

One application name per line (when using a file). Matching is partial and case-insensitive — a process whose window title or executable contains the entry will be matched.

discord
whatsapp
spotify
steam
epic games
origin
uplay

Troubleshooting

deepwork-node-watchdog is not installed globally

npm install -g deepwork-node-watchdog

Blacklist file not found

Run deepwork-watchdog-service pwd to get the expected path, or pass values inline:

deepwork-watchdog-service start --blacklist "discord,spotify"

Service commands require Administrator

Right-click your terminal and select "Run as administrator" before running start or stop.