@git.zone/tswatch 2.3.13 → 3.0.0

package/readme.md

@@ -1,176 +1,264 @@
 # @git.zone/tswatch
 
-A TypeScript file watcher that automatically recompiles and executes your project when files change. Designed to streamline development workflows for various TypeScript project types.
+A powerful, config-driven TypeScript file watcher that automatically recompiles and executes your project when files change. Built for modern TypeScript development with zero-config presets and deep customization options.
 
 ## 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.
 
-## Features
+## ✨ Features
 
-- 🔄 **Automatic recompilation** on file changes
-- 🚀 **Multiple project modes**: npm packages, web elements, services, and websites
-- 🌐 **Built-in development server** with live reload for web projects
-- ⚡ **Fast bundling** with esbuild integration
-- 🛠️ **Flexible CLI and programmatic API**
-- 📦 **Zero configuration** for standard project structures
+- 🔄 **Config-driven architecture** - Define watchers, bundles, and dev server in `npmextra.json`
+- ⚡ **Zero-config presets** - Get started instantly with `npm`, `element`, `service`, `website`, and `test` presets
+- 🧙 **Interactive wizard** - Run `tswatch init` to generate configuration interactively
+- 🌐 **Built-in dev server** - Live reload, CORS, compression, SPA fallback out of the box
+- 📦 **Smart bundling** - TypeScript, HTML, and assets with esbuild integration
+- 🔁 **Debounced execution** - Configurable debounce prevents command spam
+- 🛑 **Process management** - Automatic restart or queue mode for long-running commands
+- 🎯 **Glob patterns** - Watch any files with flexible pattern matching
 
-## Installation
-
-Install `@git.zone/tswatch` globally or as a development dependency:
+## 📦 Installation
 
 ```bash
-# Global installation
+# Global installation (recommended for CLI usage)
 pnpm install -g @git.zone/tswatch
 
 # As a dev dependency
 pnpm install --save-dev @git.zone/tswatch
 ```
 
-## Quick Start
-
-```bash
-# Watch and run tests on changes (default behavior)
-tswatch
+## 🚀 Quick Start
 
-# Watch a web element project with dev server
-tswatch element
+### Using the Wizard
 
-# Watch a service project
-tswatch service
+```bash
+# Run the interactive wizard to create your configuration
+tswatch init
 ```
 
-## CLI Commands
+The wizard will guide you through creating a `npmextra.json` configuration with your chosen preset or custom watchers.
 
-### `tswatch` or `tswatch npm`
+### Using Presets
 
-Watches TypeScript files and runs `npm test` on changes. This is the default mode.
+If you already have a configuration, just run:
 
 ```bash
 tswatch
-# or explicitly
-tswatch npm
 ```
 
-### `tswatch element`
-
-Sets up a development environment for web components/elements:
-- Starts a dev server on port 3002
-- Bundles TypeScript to `dist_watch/`
-- Enables live reload
-- Watches all `ts*/` folders
+This reads your config from `npmextra.json` under the `@git.zone/tswatch` key and starts watching.
 
-```bash
-tswatch element
-```
+## ⚙️ Configuration
 
-### `tswatch service`
+tswatch uses `npmextra.json` for configuration. Add your config under the `@git.zone/tswatch` key:
 
-Watches TypeScript files in `./ts/` and runs `npm run startTs` on changes. Ideal for backend services.
+```json
+{
+  "@git.zone/tswatch": {
+    "preset": "npm"
+  }
+}
+```
 
-```bash
-tswatch service
+### Available Presets
+
+| Preset | Description |
+|--------|-------------|
+| `npm` | Watch `ts/` and `test/`, run `npm test` on changes |
+| `test` | Watch `ts/` and `test/`, run `npm run test2` on changes |
+| `service` | Watch `ts/`, restart `npm run startTs` (ideal for backend services) |
+| `element` | Dev server on port 3002 + bundling for web components |
+| `website` | Full-stack: backend + frontend bundling + asset processing |
+
+### Full Configuration Schema
+
+```json
+{
+  "@git.zone/tswatch": {
+    "preset": "element",
+
+    "server": {
+      "enabled": true,
+      "port": 3002,
+      "serveDir": "./dist_watch/",
+      "liveReload": true
+    },
+
+    "bundles": [
+      {
+        "name": "main-bundle",
+        "from": "./ts_web/index.ts",
+        "to": "./dist_watch/bundle.js",
+        "watchPatterns": ["./ts_web/**/*"],
+        "triggerReload": true
+      },
+      {
+        "name": "html",
+        "from": "./html/index.html",
+        "to": "./dist_watch/index.html",
+        "watchPatterns": ["./html/**/*"],
+        "triggerReload": true
+      }
+    ],
+
+    "watchers": [
+      {
+        "name": "backend-build",
+        "watch": "./ts/**/*",
+        "command": "npm run build",
+        "restart": false,
+        "debounce": 300,
+        "runOnStart": true
+      },
+      {
+        "name": "tests",
+        "watch": ["./ts/**/*", "./test/**/*"],
+        "command": "npm test",
+        "restart": true,
+        "debounce": 300,
+        "runOnStart": true
+      }
+    ]
+  }
+}
 ```
 
-### `tswatch website`
+### Configuration Options
 
-Full website development mode:
-- Bundles TypeScript files to `dist_serve/`
-- Processes HTML files
-- Handles assets
-- Runs `npm run startTs` for server-side code
+#### `ITswatchConfig`
 
-```bash
-tswatch website
-```
+| Option | Type | Description |
+|--------|------|-------------|
+| `preset` | `string` | Use a preset: `npm`, `test`, `service`, `element`, `website` |
+| `watchers` | `IWatcherConfig[]` | Array of watcher configurations |
+| `server` | `IServerConfig` | Development server configuration |
+| `bundles` | `IBundleConfig[]` | Bundle configurations |
 
-### `tswatch test`
+#### `IWatcherConfig`
 
-Runs `npm run test2` whenever files change. Useful for projects with custom test scripts.
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `name` | `string` | *required* | Name for logging purposes |
+| `watch` | `string \| string[]` | *required* | Glob pattern(s) to watch |
+| `command` | `string` | - | Shell command to execute on changes |
+| `restart` | `boolean` | `true` | Kill previous process before restarting |
+| `debounce` | `number` | `300` | Debounce delay in milliseconds |
+| `runOnStart` | `boolean` | `true` | Run the command immediately on start |
 
-```bash
-tswatch test
-```
+#### `IServerConfig`
 
-## Project Structure
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | `boolean` | *required* | Whether the server is enabled |
+| `port` | `number` | `3002` | Server port |
+| `serveDir` | `string` | `./dist_watch/` | Directory to serve |
+| `liveReload` | `boolean` | `true` | Inject live reload script |
 
-tswatch expects certain project structures depending on the mode:
+#### `IBundleConfig`
 
-### NPM/Node Projects
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `name` | `string` | - | Name for logging purposes |
+| `from` | `string` | *required* | Entry point file |
+| `to` | `string` | *required* | Output file |
+| `watchPatterns` | `string[]` | - | Additional patterns to watch |
+| `triggerReload` | `boolean` | `true` | Trigger server reload after bundling |
 
-```
-project/
-├── ts/           # TypeScript source files
-├── test/         # Test files
-└── package.json  # With "test" script
-```
+## 🛠️ CLI Commands
 
-### Element Projects
+### `tswatch`
 
-```
-project/
-├── ts/           # Backend TypeScript
-├── ts_web/       # Frontend TypeScript
-├── html/         # HTML templates
-│   └── index.ts  # Entry point
-└── dist_watch/   # Output directory (auto-created)
+Runs with configuration from `npmextra.json`. If no config exists, launches the interactive wizard.
+
+```bash
+tswatch
 ```
 
-### Website Projects
+### `tswatch init`
 
-```
-project/
-├── ts/           # Backend TypeScript
-├── ts_web/       # Frontend TypeScript
-│   └── index.ts  # Entry point
-├── html/         # HTML files
-│   └── index.html
-├── assets/       # Static assets
-└── dist_serve/   # Output directory
+Force-run the configuration wizard (creates or overwrites existing config).
+
+```bash
+tswatch init
 ```
 
-## Programmatic API
+## 💻 Programmatic API
 
-### Basic Usage
+### Basic Usage with Config
 
 ```typescript
 import { TsWatch } from '@git.zone/tswatch';
 
-// Create and start a watcher
-const watcher = new TsWatch('node');
+// Create TsWatch with inline configuration
+const watcher = new TsWatch({
+  watchers: [
+    {
+      name: 'my-watcher',
+      watch: './src/**/*',
+      command: 'npm run build',
+      restart: true,
+      debounce: 300,
+      runOnStart: true,
+    },
+  ],
+});
+
 await watcher.start();
 
-// Stop when done
+// Later: stop watching
 await watcher.stop();
 ```
 
-### Available Watch Modes
+### Load from Config File
 
-The `TsWatch` class accepts the following modes:
+```typescript
+import { TsWatch } from '@git.zone/tswatch';
 
-| Mode | Description |
-|------|-------------|
-| `node` | Runs `npm test` on changes (default) |
-| `test` | Runs `npm run test2` on changes |
-| `element` | Web component development with dev server |
-| `service` | Runs `npm run startTs` for services |
-| `website` | Full website mode with bundling |
-| `echo` | Test mode that runs `npm -v` |
+// Load configuration from npmextra.json
+const watcher = TsWatch.fromConfig();
 
-### Custom Watchers
+if (watcher) {
+  await watcher.start();
+}
+```
 
-For more granular control, use the `Watcher` class directly:
+### Using ConfigHandler
+
+```typescript
+import { ConfigHandler } from '@git.zone/tswatch';
+
+const configHandler = new ConfigHandler();
+
+// Check if config exists
+if (configHandler.hasConfig()) {
+  const config = configHandler.loadConfig();
+  console.log(config);
+}
+
+// Get available presets
+const presets = configHandler.getPresetNames();
+console.log(presets); // ['npm', 'test', 'service', 'element', 'website']
+
+// Get a specific preset
+const npmPreset = configHandler.getPreset('npm');
+```
+
+### Using Watcher Directly
+
+For more granular control, use the `Watcher` class:
 
 ```typescript
 import { Watcher } from '@git.zone/tswatch';
 
-const customWatcher = new Watcher({
-  filePathToWatch: './src',
-  commandToExecute: 'npm run build',
-  timeout: 5000 // Optional timeout in ms
+// Create from config object
+const watcher = Watcher.fromConfig({
+  name: 'my-watcher',
+  watch: ['./src/**/*', './lib/**/*'],
+  command: 'npm run compile',
+  restart: true,
 });
 
-await customWatcher.start();
+await watcher.start();
 ```
 
 ### Using Function Callbacks
@@ -179,79 +267,126 @@ await customWatcher.start();
 import { Watcher } from '@git.zone/tswatch';
 
 const watcher = new Watcher({
-  filePathToWatch: './src',
+  name: 'custom-handler',
+  filePathToWatch: './src/**/*',
   functionToCall: async () => {
-    console.log('Files changed!');
-    // Your custom logic here
-  }
+    console.log('Files changed! Running custom logic...');
+    // Your custom build/test/deploy logic here
+  },
+  debounce: 500,
+  runOnStart: true,
 });
 
 await watcher.start();
 ```
 
-### Watcher Options
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `filePathToWatch` | `string` | Path to watch for changes |
-| `commandToExecute` | `string` | Shell command to run on changes |
-| `functionToCall` | `() => Promise<any>` | Async function to call on changes |
-| `timeout` | `number` | Optional timeout in milliseconds |
-
-## Development Server
+## 📁 Project Structures
 
-Element mode includes a built-in development server:
+### NPM Package / Node.js Library
 
-- **Port**: 3002
-- **Features**: CORS enabled, gzip compression, live reload
-- **Serve directory**: `./dist_watch/`
+```
+project/
+├── ts/           # TypeScript source files
+├── test/         # Test files
+├── package.json  # With "test" script
+└── npmextra.json # tswatch config
+```
 
-Access your project at `http://localhost:3002` when running in element mode.
+Config:
+```json
+{
+  "@git.zone/tswatch": {
+    "preset": "npm"
+  }
+}
+```
 
-## Configuration Tips
+### Backend Service
 
-1. **TypeScript Config**: Ensure your `tsconfig.json` is properly configured for your target environment
-2. **Package Scripts**: Define appropriate scripts in `package.json`:
-   - `test`: For npm mode
-   - `test2`: For test mode
-   - `startTs`: For service/website modes
-   - `build`: For general compilation
+```
+project/
+├── ts/           # TypeScript source files
+├── package.json  # With "startTs" script
+└── npmextra.json
+```
 
-3. **File Organization**: Keep TypeScript files in `ts/` (backend) and `ts_web/` (frontend) directories
+Config:
+```json
+{
+  "@git.zone/tswatch": {
+    "preset": "service"
+  }
+}
+```
 
-## Common Use Cases
+### Web Component / Element
 
-### Developing a Node.js Library
+```
+project/
+├── ts/           # Backend TypeScript (optional)
+├── ts_web/       # Frontend TypeScript
+├── html/
+│   ├── index.ts  # Web entry point
+│   └── index.html
+├── dist_watch/   # Output (auto-created)
+└── npmextra.json
+```
 
-```bash
-tswatch npm
+Config:
+```json
+{
+  "@git.zone/tswatch": {
+    "preset": "element"
+  }
+}
 ```
 
-Automatically runs tests when you modify source files.
+Access your project at `http://localhost:3002`
 
-### Building a Web Component
+### Full-Stack Website
 
-```bash
-tswatch element
+```
+project/
+├── ts/           # Backend TypeScript
+├── ts_web/       # Frontend TypeScript
+│   └── index.ts
+├── html/
+│   └── index.html
+├── assets/       # Static assets
+├── dist_serve/   # Output
+└── npmextra.json
 ```
 
-Get instant feedback with live reload while developing custom elements.
+Config:
+```json
+{
+  "@git.zone/tswatch": {
+    "preset": "website"
+  }
+}
+```
 
-### Creating a Backend Service
+## 🌐 Development Server
 
-```bash
-tswatch service
-```
+The built-in development server (enabled in `element` and `website` presets) features:
 
-Automatically restart your service on code changes.
+- **Live Reload** - Automatically refreshes browser on changes
+- **CORS** - Cross-origin requests enabled
+- **Compression** - Gzip compression for faster loading
+- **SPA Fallback** - Single-page application routing support
+- **Security Headers** - Cross-origin isolation headers
 
-### Full-Stack Web Application
+Default configuration:
+- **Port**: 3002
+- **Serve Directory**: `./dist_watch/`
+- **Live Reload**: Enabled
 
-```bash
-tswatch website
-```
+## 🔧 Configuration Tips
 
-Handle both frontend and backend compilation with asset processing.
+1. **Use presets for common workflows** - They're battle-tested and cover most use cases
+2. **Customize with explicit config** - Override preset defaults by adding explicit `watchers`, `bundles`, or `server` config
+3. **Debounce wisely** - Default 300ms works well; increase for slower builds
+4. **Use `restart: false`** for one-shot commands (like builds) and `restart: true` for long-running processes (like servers)
 
 ## License and Legal Information
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@git.zone/tswatch',
-  version: '2.3.13',
+  version: '3.0.0',
   description: 'A development tool for automatically watching and re-compiling TypeScript projects upon detecting file changes, enhancing developer workflows.'
 }

package/ts/index.ts

@@ -1,7 +1,11 @@
 import * as early from '@push.rocks/early';
 early.start('tswatch');
+
 export * from './tswatch.classes.tswatch.js';
+export * from './tswatch.classes.watcher.js';
+export * from './tswatch.classes.confighandler.js';
 export * from './tswatch.cli.js';
-early.stop();
+export * from './tswatch.init.js';
+export * from './interfaces/index.js';
 
-export * from './tswatch.classes.watcher.js';
+early.stop();

package/ts/interfaces/index.ts

@@ -1 +1 @@
-export * from './interfaces.watchmodes.js';
+export * from './interfaces.config.js';

package/ts/interfaces/interfaces.config.ts

@@ -0,0 +1,61 @@
+/**
+ * Configuration for a single watcher
+ */
+export interface IWatcherConfig {
+  /** Name for this watcher (used in logging) */
+  name: string;
+  /** Glob pattern(s) to watch */
+  watch: string | string[];
+  /** Shell command to execute on changes */
+  command?: string;
+  /** If true, kill previous process before restarting (default: true) */
+  restart?: boolean;
+  /** Debounce delay in ms (default: 300) */
+  debounce?: number;
+  /** If true, run the command immediately on start (default: true) */
+  runOnStart?: boolean;
+}
+
+/**
+ * Configuration for the development server
+ */
+export interface IServerConfig {
+  /** Whether the server is enabled */
+  enabled: boolean;
+  /** Server port (default: 3002) */
+  port?: number;
+  /** Directory to serve (default: ./dist_watch/) */
+  serveDir?: string;
+  /** Whether to inject live reload script (default: true) */
+  liveReload?: boolean;
+}
+
+/**
+ * Configuration for a bundle operation
+ */
+export interface IBundleConfig {
+  /** Name for this bundle (used in logging) */
+  name?: string;
+  /** Entry point file */
+  from: string;
+  /** Output file */
+  to: string;
+  /** Additional patterns to watch that trigger this bundle */
+  watchPatterns?: string[];
+  /** If true, trigger server reload after bundling (default: true) */
+  triggerReload?: boolean;
+}
+
+/**
+ * Main tswatch configuration
+ */
+export interface ITswatchConfig {
+  /** Array of watcher configurations */
+  watchers?: IWatcherConfig[];
+  /** Development server configuration */
+  server?: IServerConfig;
+  /** Bundle configurations */
+  bundles?: IBundleConfig[];
+  /** Use a preset configuration (overridden by explicit watchers/server/bundles) */
+  preset?: 'element' | 'website' | 'npm' | 'service' | 'test';
+}