BREAKING CHANGE(tswatch): refactor tswatch to a config-driven design (load config from npmextra.json) and add interactive init wizard; change TsWatch public API and enhance Watcher behavior

2026-01-24 11:29:55 +00:00
parent 5a702055f4
commit 9fb3f6a872
20 changed files with 3686 additions and 4431 deletions
--- a/readme.hints.md
+++ b/readme.hints.md
@@ -1,51 +1,93 @@
 # tswatch Project Hints

-## Core Architecture
- tswatch is a TypeScript file watcher with multiple operation modes
- Main class `TsWatch` orchestrates different watch modes
- `Watcher` class handles individual file watching and command execution
+## Core Architecture (v3.x - Config-Driven)

-## Available Watch Modes
-1. **npm/node** (default): Runs `npm test` on changes
-2. **test**: Runs `npm run test2` on changes
-3. **element**: Web component development with dev server on port 3002
-4. **service**: Runs `npm run startTs` for service projects
-5. **website**: Full website mode with bundling and asset processing
-6. **echo**: Test mode that runs `npm -v` (for testing)
+tswatch is now a config-driven TypeScript file watcher. Configuration is read from `npmextra.json` under the key `@git.zone/tswatch`.
+
+### Key Classes
+
+- **TsWatch**: Main orchestrator class, accepts `ITswatchConfig`
+- **Watcher**: Handles individual file watching with debouncing and restart modes
+- **ConfigHandler**: Loads and manages configuration from npmextra.json
+- **TswatchInit**: Interactive wizard for creating configuration
+
+### Configuration Structure
+
+```json
+{
+  "@git.zone/tswatch": {
+    "watchers": [
+      {
+        "name": "backend",
+        "watch": "./ts/**/*",
+        "command": "npm run startTs",
+        "restart": true,
+        "debounce": 300,
+        "runOnStart": true
+      }
+    ],
+    "server": {
+      "enabled": true,
+      "port": 3002,
+      "serveDir": "./dist_watch/",
+      "liveReload": true
+    },
+    "bundles": [
+      {
+        "name": "frontend",
+        "from": "./html/index.ts",
+        "to": "./dist_watch/bundle.js",
+        "watchPatterns": ["./ts_web/**/*"],
+        "triggerReload": true
+      }
+    ],
+    "preset": "element"
+  }
+}
+```
+
+### Available Presets
+
+- **npm**: Watch ts/ and test/, run `npm test`
+- **test**: Watch ts/ and test/, run `npm run test2`
+- **service**: Watch ts/, run `npm run startTs` with restart
+- **element**: Dev server on 3002, bundle ts_web, watch html
+- **website**: Full stack with backend restart + frontend bundling + assets
+
+### CLI Commands
+
+- `tswatch` - Run with config (or launch wizard if no config)
+- `tswatch init` - Force run the configuration wizard

 ## Key Implementation Details
- Uses `@push.rocks/smartwatch` (v5.x) for file watching - class is `Smartwatch`
- Uses `@push.rocks/smartfs` (v1.x) for directory operations - uses `SmartFs` with `SmartFsProviderNode`
+
+- Uses `@push.rocks/smartwatch` (v6.x) for file watching - class is `Smartwatch`
+- Uses `@push.rocks/smartfs` (v1.x) for filesystem operations
+- Uses `@push.rocks/npmextra` for reading npmextra.json config
+- Uses `@push.rocks/smartinteract` for the init wizard
 - Uses `@git.zone/tsbundle` for bundling with esbuild
- Uses `@api.global/typedserver` for development server in element mode
- Element/website modes watch multiple `ts*/` directories
- All modes support both command execution and function callbacks
+- Uses `@api.global/typedserver` for development server

-## CLI Entry Points
- `cli.js` -> Main CLI entry point
- `ts/tswatch.cli.ts` -> CLI implementation with smartcli
- Default command triggers npm mode
+### Watcher Features

-## Project Structure Expectations
- `ts/` - Backend TypeScript files
- `ts_web/` - Frontend TypeScript files (element/website modes)
- `html/` - HTML templates (element/website modes)
- `assets/` - Static assets (website mode only)
- `dist_watch/` - Output for element mode
- `dist_serve/` - Output for website mode
+- **Debouncing**: Configurable delay before executing (default: 300ms)
+- **Restart mode**: Kill previous process before restarting (configurable)
+- **Named watchers**: All watchers have names for clear logging
+- **Multiple watch patterns**: Can watch multiple glob patterns

-## Development Server Details
- Port: 3002
- Features: CORS, gzip compression, live reload injection
- Only available in element mode via `typedserver` property
+### Server Features

-## Common Issues to Watch For
- The test mode runs `test2` script, not `test`
- Website mode restarts the entire server process on backend changes
- Element mode rebuilds and reloads on any ts* folder change
+- Port configurable (default: 3002)
+- CORS enabled
+- Gzip compression
+- Live reload injection (configurable)
+- SPA fallback support

-## Migration Notes (v2.2.x)
- Replaced `@push.rocks/smartchok` with `@push.rocks/smartwatch` (v5.x)
- Replaced `@push.rocks/smartfile` with `@push.rocks/smartfs` for directory listing
- Class names: `Smartwatch` for file watching, `SmartFs` + `SmartFsProviderNode` for filesystem ops
- Directory paths are converted to glob patterns (`/path/to/dir/` → `/path/to/dir/**/*`) for smartwatch compatibility
+## Project Structure
+
+- `ts/tswatch.classes.tswatch.ts` - Main TsWatch class
+- `ts/tswatch.classes.watcher.ts` - Watcher class with debounce/restart
+- `ts/tswatch.classes.confighandler.ts` - Config loading
+- `ts/tswatch.init.ts` - Interactive init wizard
+- `ts/tswatch.cli.ts` - CLI entry point
+- `ts/interfaces/interfaces.config.ts` - Type definitions