ngx-locatorjs 0.3.0 → 0.4.0

package/README.ko.md

@@ -15,10 +15,9 @@
 1. 패키지 설치: `npm i -D ngx-locatorjs`
 2. 설정/프록시 생성: `npx locatorjs-config`
 3. `main.ts`에 런타임 훅 추가 (아래 예시 참고)
-4. 파일 오프너 서버 + dev 서버 실행 (둘 다 켜진 상태 유지): `npx locatorjs-open-in-editor --watch` + `ng serve --proxy-config {proxyConfigPath}`
+4. 파일 오프너 서버 + dev 서버 실행 (둘 다 켜진 상태 유지): `npx locatorjs-open-in-editor --watch` + `ng serve --proxy-config ngx-locatorjs.proxy.cjs`
 
-`npm run start` 사용 시 `--` 뒤에 전달: `npm run start -- --proxy-config {proxyConfigPath}`
-`{proxyConfigPath}`는 `npx locatorjs-config`가 선택/병합한 실제 프록시 파일 경로로 바꿔서 사용하세요.
+기존 0.3.0 버전에서 업그레이드했다면 `npx locatorjs-config`를 다시 실행해 `authToken`과 proxy 헤더를 재생성하고, `--proxy-config`(또는 `angular.json`)를 `ngx-locatorjs.proxy.cjs`로 맞추세요.
 
 **Angular 코드 추가 (main.ts)**
 
@@ -65,10 +64,10 @@ bootstrapApplication(AppComponent, appConfig)
 **Angular dev server 예시**
 
 - CLI 실행
-  `ng serve --proxy-config {proxyConfigPath}`
+  `ng serve --proxy-config ngx-locatorjs.proxy.cjs`
 
 - angular.json에 적용
-  `"serve"` 옵션에 `"proxyConfig": "{proxyConfigPath}"` 추가
+  `"serve"` 옵션에 `"proxyConfig": "ngx-locatorjs.proxy.cjs"` 추가
 
 **컴포넌트 맵 스캔**
 
@@ -94,7 +93,7 @@ bootstrapApplication(AppComponent, appConfig)
 **중요**
 
 - `npx locatorjs-config`는 **실행한 현재 폴더를 기준**으로 설정합니다.
-- 기본값: `port: 4123`, `workspaceRoot: "."`.
+- 기본값: `host: "127.0.0.1"`, `port: 4123`, `workspaceRoot: "."`.
 - 모노레포처럼 실제 Angular 앱이 하위 폴더에 있으면 `workspaceRoot`를 그 **상대 경로**로 수정하세요. (예: `apps/web`)
 - `.gitignore`가 있으면 `npx locatorjs-config`가 `.open-in-editor/`를 자동 추가합니다. 커밋하려면 해당 항목을 제거하세요.
 
@@ -102,10 +101,12 @@ bootstrapApplication(AppComponent, appConfig)
 
 ```json
 {
+  "host": "127.0.0.1",
   "port": 4123,
   "workspaceRoot": ".",
   "editor": "cursor",
   "fallbackEditor": "code",
+  "authToken": "locatorjs-config가 자동 생성",
   "scan": {
     "includeGlobs": [
       "src/**/*.{ts,tsx}",
@@ -129,9 +130,11 @@ bootstrapApplication(AppComponent, appConfig)
 **필드 설명**
 
 - `port`: 로컬 file-opener 서버 포트입니다.
+- `host`: file-opener 서버 바인드 주소입니다. 로컬 전용으로 `127.0.0.1` 사용을 권장합니다.
 - `workspaceRoot`: 명령 실행 위치 기준 Angular 워크스페이스 루트 상대 경로입니다.
-- `editor`: 기본 에디터입니다 (`cursor`, `zed`, `antigravity`, `code`, `webstorm`).
+- `editor`: 기본 에디터입니다 (`cursor`, `code`, `webstorm`).
 - `fallbackEditor`: 기본 에디터 실행 실패 시 사용할 대체 에디터입니다.
+- `authToken`: open-in-editor 서버 요청 검증 토큰입니다. `locatorjs-config`가 자동 생성합니다.
 - `scan.includeGlobs`: 컴포넌트 소스 파일 탐색 대상 glob 목록입니다.
 - `scan.excludeGlobs`: 컴포넌트 스캔에서 제외할 glob 목록입니다.
 
@@ -151,41 +154,25 @@ bootstrapApplication(AppComponent, appConfig)
 3. `ngx-locatorjs.config.json`의 `editor`
 4. 자동 감지된 에디터
 
-**프록시 설정 ({proxyConfigPath})**
-`{proxyConfigPath}`는 `npx locatorjs-config` 실행 시 아래 규칙으로 결정됩니다.
-
-- `angular.json`에 `proxyConfig`가 지정되어 있으면 그 파일에 병합합니다.
-- 없고 `proxy.conf.json`이 있으면 그 파일에 병합합니다.
-- 둘 다 없으면 `ngx-locatorjs.proxy.json`을 생성합니다.
+**프록시 설정 (ngx-locatorjs.proxy.cjs)**
+`npx locatorjs-config` 실행 시 자동 생성됩니다. 이 파일은 실행 시점에 `ngx-locatorjs.config.json`을 읽어 target을 구성하므로, 포트를 바꾸려면 `ngx-locatorjs.config.json`의 `port`만 수정하면 됩니다.
 
 예시:
 
-```json
-{
-  "/__open-in-editor": {
-    "target": "http://localhost:4123",
-    "secure": false,
-    "changeOrigin": true
-  },
-  "/__open-in-editor-search": {
-    "target": "http://localhost:4123",
-    "secure": false,
-    "changeOrigin": true
-  },
-  "/__cmp-map": {
-    "target": "http://localhost:4123",
-    "secure": false,
-    "changeOrigin": true
-  }
-}
+```js
+module.exports = {
+  '/__open-in-editor': { target, secure: false, changeOrigin: true, headers },
+  '/__open-in-editor-search': { target, secure: false, changeOrigin: true, headers },
+  '/__cmp-map': { target, secure: false, changeOrigin: true, headers },
+};
 ```
 
 **트러블슈팅**
 
 1. CORS 에러
-   `ng serve --proxy-config {proxyConfigPath}` 사용 여부 확인
+   `ng serve --proxy-config ngx-locatorjs.proxy.cjs` 사용 여부 확인
 2. npm run 경고
-   `npm run start -- --proxy-config {proxyConfigPath}` 형태로 실행
+   `npm run start -- --proxy-config ngx-locatorjs.proxy.cjs` 형태로 실행
 3. 네트워크 비활성
    `installAngularLocator({ enableNetwork: true })` 설정 확인
 4. component-map.json not found
@@ -199,31 +186,20 @@ bootstrapApplication(AppComponent, appConfig)
 8. 하이라이트가 안 보이거나 info가 null로 나옴
    `http://localhost:${port}/__cmp-map` 에서 컴포넌트 정보가 잘 나타나는지 확인
 9. 포트 충돌
-   `ngx-locatorjs.config.json`과 `{proxyConfigPath}`에서 포트 일치 여부 확인
+   `ngx-locatorjs.config.json`의 `port`만 수정하면 됩니다
+10. opener 라우트에서 401 발생
+    `npx locatorjs-config` 재실행으로 토큰/프록시 헤더를 다시 생성하거나, 프록시 없이 직접 호출 시 `installAngularLocator`에 `authToken` 전달
 
 **주의**
 
 - 개발 모드에서만 사용하세요. 프로덕션 번들에 포함되지 않도록 `environment.production` 체크를 권장합니다.
 - 네트워크 요청은 opt-in이며 localhost로만 제한됩니다. `enableNetwork: true`로 활성화하세요.
+- opener 서버는 기본적으로 loopback(`127.0.0.1`)에만 바인드되며, `workspaceRoot` 바깥 파일은 열 수 없습니다.
 
 **원 커맨드 실행 (추천)**
-file-opener 서버와 Angular dev server를 한 번에 띄우려면 아래 방식 중 하나를 사용하세요.
-
-### Option A: `concurrently`
-
-```bash
-npm i -D concurrently
-```
-
-```json
-{
-  "scripts": {
-    "dev:locator": "concurrently -k -n opener,ng \"npx locatorjs-open-in-editor\" \"ng serve --proxy-config {proxyConfigPath}\""
-  }
-}
-```
+file-opener 서버와 Angular dev server를 한 번에 띄우려면 아래 방식을 사용하세요.
 
-### Option B: `npm-run-all`
+### `npm-run-all`
 
 ```bash
 npm i -D npm-run-all
@@ -233,7 +209,7 @@ npm i -D npm-run-all
 {
   "scripts": {
     "locator:opener": "npx locatorjs-open-in-editor",
-    "dev:app": "ng serve --proxy-config {proxyConfigPath}",
+    "dev:app": "ng serve --proxy-config ngx-locatorjs.proxy.cjs",
     "dev:locator": "run-p locator:opener dev:app"
   }
 }

package/README.md

@@ -32,10 +32,9 @@ You must complete steps 1–4 for this to work.
 1. Install the package: `npm i -D ngx-locatorjs`
 2. Generate config + proxy: `npx locatorjs-config`
 3. Add the runtime hook to `main.ts` (see the examples below)
-4. Run the file-opener server and your dev server (keep both running): `npx locatorjs-open-in-editor --watch` + `ng serve --proxy-config {proxyConfigPath}`
+4. Run the file-opener server and your dev server (keep both running): `npx locatorjs-open-in-editor --watch` + `ng serve --proxy-config ngx-locatorjs.proxy.cjs`
 
-If you use `npm run start`, pass args after `--`: `npm run start -- --proxy-config {proxyConfigPath}`
-Replace `{proxyConfigPath}` with the actual proxy file path selected/updated by `npx locatorjs-config`.
+If you are upgrading from an older version, run `npx locatorjs-config` again so `authToken` and proxy headers are generated, then use `ngx-locatorjs.proxy.cjs` in your `--proxy-config` or `angular.json`.
 
 ## Add to `main.ts`
 
@@ -94,7 +93,7 @@ Location: project root
 **Important**
 
 - `npx locatorjs-config` uses the **current directory** as the base.
-- Defaults: `port: 4123`, `workspaceRoot: "."`.
+- Defaults: `host: "127.0.0.1"`, `port: 4123`, `workspaceRoot: "."`.
 - In a monorepo, update `workspaceRoot` to the **relative path** of your Angular app (e.g. `apps/web`).
 - If `.gitignore` exists, `npx locatorjs-config` will append `.open-in-editor/`. Remove it if you want to commit the map.
 
@@ -102,10 +101,12 @@ Example:
 
 ```json
 {
+  "host": "127.0.0.1",
   "port": 4123,
   "workspaceRoot": ".",
   "editor": "cursor",
   "fallbackEditor": "code",
+  "authToken": "generated-by-locatorjs-config",
   "scan": {
     "includeGlobs": [
       "src/**/*.{ts,tsx}",
@@ -129,9 +130,11 @@ Example:
 ### Field Reference
 
 - `port`: Port for the local file-opener server.
+- `host`: Bind address for the file-opener server. Keep `127.0.0.1` for local-only access.
 - `workspaceRoot`: Angular workspace root path (relative to where you run commands).
-- `editor`: Preferred editor (`cursor`, `zed`, `antigravity`, `code`, `webstorm`).
+- `editor`: Preferred editor (`cursor`, `code`, `webstorm`).
 - `fallbackEditor`: Fallback editor if the preferred editor cannot be launched.
+- `authToken`: Request token validated by the open-in-editor server. Generated automatically by `locatorjs-config`.
 - `scan.includeGlobs`: Globs used to find component source files.
 - `scan.excludeGlobs`: Globs excluded from component scanning.
 
@@ -141,34 +144,18 @@ Example:
 - Angular workspace: `"projects/**/*.{ts,tsx}"`
 - Nx: `"apps/**/*.{ts,tsx}", "libs/**/*.{ts,tsx}"`
 
-## Proxy (`{proxyConfigPath}`)
+## Proxy (`ngx-locatorjs.proxy.cjs`)
 
-`{proxyConfigPath}` is decided by `npx locatorjs-config`:
-
-- If `angular.json` already specifies `proxyConfig`, it updates that file.
-- Else if `proxy.conf.json` exists, it updates that file.
-- Otherwise it creates `ngx-locatorjs.proxy.json`.
+Generated by `npx locatorjs-config`. This dynamic proxy module reads `ngx-locatorjs.config.json` at runtime, so changing `port` in config updates proxy target automatically.
 
 Example:
 
-```json
-{
-  "/__open-in-editor": {
-    "target": "http://localhost:4123",
-    "secure": false,
-    "changeOrigin": true
-  },
-  "/__open-in-editor-search": {
-    "target": "http://localhost:4123",
-    "secure": false,
-    "changeOrigin": true
-  },
-  "/__cmp-map": {
-    "target": "http://localhost:4123",
-    "secure": false,
-    "changeOrigin": true
-  }
-}
+```js
+module.exports = {
+  '/__open-in-editor': { target, secure: false, changeOrigin: true, headers },
+  '/__open-in-editor-search': { target, secure: false, changeOrigin: true, headers },
+  '/__cmp-map': { target, secure: false, changeOrigin: true, headers },
+};
 ```
 
 ## Environment Variable Priority
@@ -180,40 +167,28 @@ Example:
 
 ## Troubleshooting
 
-- **CORS / JSON parse error**: ensure dev server uses `--proxy-config {proxyConfigPath}`
-- **npm run shows "Unknown cli config --proxy-config"**: use `npm run start -- --proxy-config {proxyConfigPath}`
+- **CORS / JSON parse error**: ensure dev server uses `--proxy-config ngx-locatorjs.proxy.cjs`
+- **npm run shows "Unknown cli config --proxy-config"**: use `npm run start -- --proxy-config ngx-locatorjs.proxy.cjs`
 - **Network disabled**: pass `enableNetwork: true` to `installAngularLocator`
 - **component-map.json not found**: run `npx locatorjs-scan`
 - **Component changes not reflected**: run `npx locatorjs-open-in-editor --watch` or re-run `npx locatorjs-scan`
 - **Map is empty or missing components**: check `scan.includeGlobs` and rerun the scan
 - **Wrong files open or nothing matches**: confirm `workspaceRoot` points to the actual Angular app root
 - **No highlight / info is null**: make sure `http://localhost:${port}/__cmp-map` is loading and includes your component class name
-- **Port conflict**: change port in both `ngx-locatorjs.config.json` and `{proxyConfigPath}`
+- **Port conflict**: change `port` in `ngx-locatorjs.config.json` only
+- **401 Unauthorized from opener routes**: regenerate config/proxy (`npx locatorjs-config`) or pass `authToken` to `installAngularLocator` if you call the opener without Angular proxy headers
 
 ## Notes
 
 - Use only in development (guard with `environment.production`).
 - Network requests are opt-in and limited to localhost. Set `enableNetwork: true` to activate.
+- Opener server accepts files only inside `workspaceRoot` and binds to loopback by default.
 
 ## One-Command Dev (Recommended)
 
 Running the file-opener server and Angular dev server separately is tedious. You can wire them into a single script.
 
-### Option A: `concurrently`
-
-```bash
-npm i -D concurrently
-```
-
-```json
-{
-  "scripts": {
-    "dev:locator": "concurrently -k -n opener,ng \"npx locatorjs-open-in-editor\" \"ng serve --proxy-config {proxyConfigPath}\""
-  }
-}
-```
-
-### Option B: `npm-run-all`
+### `npm-run-all`
 
 ```bash
 npm i -D npm-run-all
@@ -223,7 +198,7 @@ npm i -D npm-run-all
 {
   "scripts": {
     "locator:opener": "npx locatorjs-open-in-editor",
-    "dev:app": "ng serve --proxy-config {proxyConfigPath}",
+    "dev:app": "ng serve --proxy-config ngx-locatorjs.proxy.cjs",
     "dev:locator": "run-p locator:opener dev:app"
   }
 }

package/dist/browser/index.d.ts

@@ -20,6 +20,7 @@ export type AngularLocatorOptions = {
     enableClick?: boolean;
     showTooltip?: boolean;
     showClickFeedback?: boolean;
+    authToken?: string;
     debug?: boolean;
 };
 declare function ensureMap(forceRefresh?: boolean): Promise<CmpMap>;

package/dist/browser/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA,KAAK,OAAO,GAAG;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,KAAK,MAAM,GAAG;IACZ,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAChD,CAAC;AAkBF,MAAM,MAAM,uBAAuB,GAAG;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,SAAS,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAC7C,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AA4EF,iBAAe,SAAS,CAAC,YAAY,UAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CA2B9D;AA+eD,wBAAsB,qBAAqB,CAAC,OAAO,GAAE,qBAA0B,iBAa9E;AAED,wBAAsB,mBAAmB,kBASxC;AAED,wBAAsB,mBAAmB,kBAExC;AAED,wBAAgB,yBAAyB,YAExC;AAED,eAAO,MAAM,SAAS;;CAErB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA,KAAK,OAAO,GAAG;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,KAAK,MAAM,GAAG;IACZ,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAChD,CAAC;AAkBF,MAAM,MAAM,uBAAuB,GAAG;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,SAAS,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAC7C,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AA+FF,iBAAe,SAAS,CAAC,YAAY,UAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CA4B9D;AAmfD,wBAAsB,qBAAqB,CAAC,OAAO,GAAE,qBAA0B,iBAc9E;AAED,wBAAsB,mBAAmB,kBASxC;AAED,wBAAsB,mBAAmB,kBAExC;AAED,wBAAgB,yBAAyB,YAExC;AAED,eAAO,MAAM,SAAS;;CAErB,CAAC"}

package/dist/browser/index.js

@@ -11,6 +11,7 @@ const DEFAULT_OPTIONS = {
     enableClick: true,
     showTooltip: true,
     showClickFeedback: true,
+    authToken: null,
     debug: false,
 };
 let OPTIONS = DEFAULT_OPTIONS;
@@ -41,6 +42,22 @@ function assertNetworkAllowed(url) {
     }
     return resolved.toString();
 }
+function attachAuthToken(url) {
+    if (!OPTIONS.authToken)
+        return url;
+    const resolved = new URL(url, window.location.href);
+    if (!resolved.searchParams.has('token')) {
+        resolved.searchParams.set('token', OPTIONS.authToken);
+    }
+    return resolved.toString();
+}
+function getAuthHeaders() {
+    if (!OPTIONS.authToken)
+        return undefined;
+    return {
+        'x-locatorjs-token': OPTIONS.authToken,
+    };
+}
 function normalizeMap(map) {
     if (!map.filePathsByClassName || Object.keys(map.filePathsByClassName).length === 0) {
         const rebuilt = {};
@@ -59,12 +76,13 @@ async function ensureMap(forceRefresh = false) {
     if (CMP_MAP && !forceRefresh)
         return CMP_MAP;
     const timestamp = Date.now();
-    const res = await fetch(assertNetworkAllowed(`${OPTIONS.endpoints.componentMap}?t=${timestamp}`), {
+    const res = await fetch(attachAuthToken(assertNetworkAllowed(`${OPTIONS.endpoints.componentMap}?t=${timestamp}`)), {
         cache: 'no-store',
         headers: {
             'Cache-Control': 'no-cache, no-store, must-revalidate',
             Pragma: 'no-cache',
             Expires: '0',
+            ...getAuthHeaders(),
         },
     });
     const text = await res.text();
@@ -198,9 +216,9 @@ function getNearestComponent(el) {
     };
 }
 async function openFile(absPath, line = 1, col = 1) {
-    const url = assertNetworkAllowed(`${OPTIONS.endpoints.openInEditor}?file=${encodeURIComponent(absPath)}&line=${line}&col=${col}`);
+    const url = attachAuthToken(assertNetworkAllowed(`${OPTIONS.endpoints.openInEditor}?file=${encodeURIComponent(absPath)}&line=${line}&col=${col}`));
     try {
-        await fetch(url);
+        await fetch(url, { headers: getAuthHeaders() });
     }
     catch (e) {
         if (OPTIONS.debug) {
@@ -209,9 +227,9 @@ async function openFile(absPath, line = 1, col = 1) {
     }
 }
 async function openFileWithSearch(absPath, searchTerms) {
-    const url = assertNetworkAllowed(`${OPTIONS.endpoints.openInEditorSearch}?file=${encodeURIComponent(absPath)}&search=${encodeURIComponent(JSON.stringify(searchTerms))}`);
+    const url = attachAuthToken(assertNetworkAllowed(`${OPTIONS.endpoints.openInEditorSearch}?file=${encodeURIComponent(absPath)}&search=${encodeURIComponent(JSON.stringify(searchTerms))}`));
     try {
-        await fetch(url);
+        await fetch(url, { headers: getAuthHeaders() });
     }
     catch (e) {
         if (OPTIONS.debug) {
@@ -524,6 +542,7 @@ export async function installAngularLocator(options = {}) {
     const mergedOptions = {
         ...DEFAULT_OPTIONS,
         ...options,
+        authToken: options.authToken ?? DEFAULT_OPTIONS.authToken,
         endpoints: {
             ...DEFAULT_ENDPOINTS,
             ...options.endpoints,

package/dist/node/cmp-scan.js

@@ -110,10 +110,31 @@ async function main() {
     fs.mkdirSync(outDir, { recursive: true });
     function loadCache() {
         try {
-            return JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+            const raw = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+            if (!raw || typeof raw !== 'object')
+                return { version: 2, files: {} };
+            const typed = raw;
+            if (typed.version === 2 && typed.files && typeof typed.files === 'object') {
+                return {
+                    version: 2,
+                    files: typed.files,
+                };
+            }
+            // Backward compatibility for old cache shape: { [filePath]: mtimeMs }
+            const files = {};
+            for (const [filePath, mtime] of Object.entries(raw)) {
+                if (typeof mtime === 'number') {
+                    files[filePath] = {
+                        // Force one-time reparsing after legacy-cache migration.
+                        mtimeMs: -1,
+                        components: [],
+                    };
+                }
+            }
+            return { version: 2, files };
         }
         catch {
-            return {};
+            return { version: 2, files: {} };
         }
     }
     function saveCache(cache) {
@@ -144,19 +165,36 @@ async function main() {
     const filePaths = [...new Set(allFiles)];
     const currentStats = getFileStats(filePaths);
     const previousCache = loadCache();
-    const hasChanges = filePaths.some((filePath) => !previousCache[filePath] || previousCache[filePath] !== currentStats[filePath]);
-    const cachedPaths = Object.keys(previousCache);
-    const hasNewOrDeletedFiles = filePaths.length !== cachedPaths.length ||
-        filePaths.some((p) => !previousCache[p]) ||
-        cachedPaths.some((p) => !currentStats[p]);
-    if (!hasChanges && !hasNewOrDeletedFiles && fs.existsSync(outFile)) {
+    const previousFiles = previousCache.files;
+    const previousPaths = Object.keys(previousFiles);
+    const changedOrNewPaths = filePaths.filter((filePath) => {
+        const currentMtime = currentStats[filePath];
+        const cached = previousFiles[filePath];
+        return !cached || cached.mtimeMs !== currentMtime;
+    });
+    const deletedPaths = previousPaths.filter((cachedPath) => !currentStats[cachedPath]);
+    if (changedOrNewPaths.length === 0 && deletedPaths.length === 0 && fs.existsSync(outFile)) {
         process.exit(0);
     }
-    const detailByFilePath = {};
-    const filePathsByClassName = {};
+    const nextFiles = {};
     for (const filePath of filePaths) {
+        const previous = previousFiles[filePath];
+        const currentMtime = currentStats[filePath];
+        if (previous && previous.mtimeMs === currentMtime) {
+            nextFiles[filePath] = previous;
+            continue;
+        }
         const sourceCode = fs.readFileSync(filePath, 'utf8');
         const components = parseSourceFile(filePath, sourceCode);
+        nextFiles[filePath] = {
+            mtimeMs: currentMtime,
+            components,
+        };
+    }
+    const detailByFilePath = {};
+    const filePathsByClassName = {};
+    for (const entry of Object.values(nextFiles)) {
+        const components = entry.components;
         for (const cmp of components) {
             detailByFilePath[cmp.filePath] = cmp;
             if (!filePathsByClassName[cmp.className]) {
@@ -173,8 +211,11 @@ async function main() {
         filePathsByClassName,
     };
     fs.writeFileSync(outFile, JSON.stringify(out, null, 2));
-    saveCache(currentStats);
-    console.log(`[cmp-scan] ✅ Saved ${Object.keys(detailByFilePath).length} components to ${path.relative(root, outFile)}`);
+    saveCache({
+        version: 2,
+        files: nextFiles,
+    });
+    console.log(`[cmp-scan] ✅ Saved ${Object.keys(detailByFilePath).length} components to ${path.relative(root, outFile)} (updated ${changedOrNewPaths.length}, removed ${deletedPaths.length})`);
 }
 main().catch((err) => {
     console.error('[cmp-scan] Failed:', err);

package/dist/node/config-setup.js

@@ -3,12 +3,13 @@ import fs from 'fs';
 import path from 'path';
 import readline from 'readline';
 import { spawn } from 'child_process';
+import crypto from 'crypto';
 import { fileURLToPath } from 'url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const root = process.cwd();
 const CONFIG_FILENAME = 'ngx-locatorjs.config.json';
-const PROXY_FILENAME = 'ngx-locatorjs.proxy.json';
+const PROXY_FILENAME = 'ngx-locatorjs.proxy.cjs';
 const configPath = path.resolve(root, CONFIG_FILENAME);
 const proxyConfigPath = resolveProxyConfigPath();
 console.log('🚀 LocatorJs (Open-in-Editor) Configuration Setup\n');
@@ -33,36 +34,22 @@ else {
 async function startSetup() {
     try {
         logDefaults();
+        const authToken = generateAuthToken();
         const config = {
             port: 4123,
+            host: '127.0.0.1',
             workspaceRoot: '.',
             editor: await selectEditor(),
             fallbackEditor: 'code',
+            authToken,
             scan: await promptScanSettings(),
         };
         fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
-        const proxyConfig = {
-            '/__open-in-editor': {
-                target: `http://localhost:${config.port}`,
-                secure: false,
-                changeOrigin: true,
-            },
-            '/__open-in-editor-search': {
-                target: `http://localhost:${config.port}`,
-                secure: false,
-                changeOrigin: true,
-            },
-            '/__cmp-map': {
-                target: `http://localhost:${config.port}`,
-                secure: false,
-                changeOrigin: true,
-            },
-        };
-        const mergedProxyConfig = mergeProxyConfig(proxyConfigPath, proxyConfig);
-        fs.writeFileSync(proxyConfigPath, JSON.stringify(mergedProxyConfig, null, 2));
+        fs.writeFileSync(proxyConfigPath, buildDynamicProxyModule());
         console.log('\n✅ Configuration saved successfully!');
         console.log(`📁 Config: ${path.relative(root, configPath)}`);
-        console.log(`🔗 Proxy: ${path.relative(root, proxyConfigPath)} (port: ${config.port})`);
+        console.log(`🔗 Proxy: ${path.relative(root, proxyConfigPath)} (dynamic from config port)`);
+        console.log('🔒 Request auth token generated and wired into proxy headers');
         ensureGitignoreEntries(['.open-in-editor/']);
         console.log('\n🔍 Running component scan...');
         const scanScript = path.resolve(__dirname, 'cmp-scan.js');
@@ -108,45 +95,65 @@ function printNextSteps(proxyPath) {
     console.log('   npx locatorjs-open-in-editor');
     console.log(`   (run your Angular dev server with --proxy-config ${path.relative(root, proxyPath)})`);
 }
-function mergeProxyConfig(proxyConfigPath, addition) {
-    const existing = readProxyConfig(proxyConfigPath);
-    if (existing && typeof existing === 'object' && !Array.isArray(existing)) {
-        return {
-            ...existing,
-            ...addition,
-        };
-    }
-    if (fs.existsSync(proxyConfigPath)) {
-        console.log('⚠️  Existing proxy config is not valid JSON. Overwriting with locator config.');
-    }
-    return addition;
+function buildDynamicProxyModule() {
+    return `'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function loadLocatorConfig() {
+  const configPath = path.resolve(process.cwd(), '${CONFIG_FILENAME}');
+  try {
+    return JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch {
+    return {};
+  }
 }
-function readProxyConfig(filePath) {
-    if (!fs.existsSync(filePath))
-        return null;
-    try {
-        const existing = JSON.parse(fs.readFileSync(filePath, 'utf8'));
-        if (existing && typeof existing === 'object' && !Array.isArray(existing)) {
-            return existing;
-        }
-    }
-    catch {
-        // ignore parse errors
-    }
-    return null;
+
+const cfg = loadLocatorConfig();
+const host = typeof cfg.host === 'string' && cfg.host.trim() ? cfg.host.trim() : '127.0.0.1';
+const port = Number(process.env.OPEN_IN_EDITOR_PORT || cfg.port || 4123);
+const authToken = typeof cfg.authToken === 'string' ? cfg.authToken : '';
+const headers = authToken ? { 'x-locatorjs-token': authToken } : {};
+const target = \`http://\${host}:\${port}\`;
+
+module.exports = {
+  '/__open-in-editor': {
+    target,
+    secure: false,
+    changeOrigin: true,
+    headers,
+  },
+  '/__open-in-editor-search': {
+    target,
+    secure: false,
+    changeOrigin: true,
+    headers,
+  },
+  '/__cmp-map': {
+    target,
+    secure: false,
+    changeOrigin: true,
+    headers,
+  },
+};
+`;
 }
 function resolveProxyConfigPath() {
     const angularProxyPath = findProxyConfigFromAngularJson();
     if (angularProxyPath) {
-        if (path.extname(angularProxyPath) !== '.json') {
-            console.log(`⚠️  proxyConfig in angular.json is not a JSON file (${path.basename(angularProxyPath)}). Creating ${PROXY_FILENAME} instead.`);
+        const ext = path.extname(angularProxyPath).toLowerCase();
+        if (ext === '.js' || ext === '.cjs') {
+            return angularProxyPath;
+        }
+        if (ext === '.json') {
+            console.log(`⚠️  angular.json points to JSON proxy (${path.basename(angularProxyPath)}).`);
+            console.log(`   Creating dynamic proxy module ${PROXY_FILENAME} instead. Update angular.json proxyConfig to use it for single-source port management.`);
             return path.resolve(root, PROXY_FILENAME);
         }
-        return angularProxyPath;
+        console.log(`⚠️  Unsupported proxy extension (${path.basename(angularProxyPath)}). Creating ${PROXY_FILENAME} instead.`);
+        return path.resolve(root, PROXY_FILENAME);
     }
-    const defaultProxy = path.resolve(root, 'proxy.conf.json');
-    if (fs.existsSync(defaultProxy))
-        return defaultProxy;
     return path.resolve(root, PROXY_FILENAME);
 }
 function findProxyConfigFromAngularJson() {
@@ -198,8 +205,12 @@ function ensureGitignoreEntries(entries) {
 function logDefaults() {
     console.log('⚙️  Defaults applied:');
     console.log('   → Port: 4123');
+    console.log('   → Host: 127.0.0.1');
     console.log('   → Workspace root: .');
 }
+function generateAuthToken() {
+    return crypto.randomBytes(24).toString('hex');
+}
 function selectEditor() {
     const availableEditors = [
         { name: 'Cursor', value: 'cursor' },

package/dist/node/file-opener.js

@@ -4,6 +4,7 @@ import path from 'path';
 import childProcess from 'child_process';
 import http from 'http';
 import { spawn } from 'child_process';
+import crypto from 'crypto';
 import { fileURLToPath } from 'url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -31,8 +32,13 @@ const cfgScan = cfg.scan ?? {};
 const scanIncludeGlobs = cfgScan.includeGlobs ?? DEFAULT_INCLUDE_GLOBS;
 const scanWorkspaceRoot = cfg.workspaceRoot?.trim() || '.';
 const cfgPort = cfg.port;
+const cfgHost = cfg.host?.trim();
 const PORT = Number(process.env.OPEN_IN_EDITOR_PORT || cfgPort || 4123);
+const HOST = process.env.OPEN_IN_EDITOR_HOST || cfgHost || '127.0.0.1';
+const AUTH_TOKEN = (process.env.OPEN_IN_EDITOR_TOKEN || cfg.authToken || '').trim() || null;
+const WORKSPACE_ROOT = path.resolve(root, scanWorkspaceRoot);
 const MAP_PATH = path.resolve(root, '.open-in-editor/component-map.json');
+const SAFE_WATCH_DIR_NAMES = new Set(['node_modules', 'dist', '.git', '.angular', 'coverage']);
 const editorCLICache = {};
 function checkEditorCLI(editorName, cliCommand = editorName) {
     if (editorCLICache[editorName] !== undefined)
@@ -183,6 +189,57 @@ function findBestLineInFile(filePath, searchTerms) {
         return 1;
     }
 }
+function getWatchRoots(includeGlobs, workspaceRoot) {
+    const roots = new Set();
+    includeGlobs.forEach((glob) => {
+        const base = globToBaseDir(glob);
+        const resolved = path.resolve(root, workspaceRoot, base);
+        if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
+            roots.add(resolved);
+        }
+    });
+    return Array.from(roots);
+}
+function globToBaseDir(glob) {
+    const wildcardIndex = glob.search(/[*?[\]{]/);
+    if (wildcardIndex === -1)
+        return glob;
+    const prefix = glob.slice(0, wildcardIndex);
+    if (prefix.endsWith('/'))
+        return prefix.slice(0, -1);
+    return path.dirname(prefix);
+}
+function collectNestedDirectories(baseDir, out = new Set()) {
+    if (!fs.existsSync(baseDir))
+        return out;
+    let stat;
+    try {
+        stat = fs.statSync(baseDir);
+    }
+    catch {
+        return out;
+    }
+    if (!stat.isDirectory())
+        return out;
+    if (out.has(baseDir))
+        return out;
+    out.add(baseDir);
+    let entries = [];
+    try {
+        entries = fs.readdirSync(baseDir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (SAFE_WATCH_DIR_NAMES.has(entry.name))
+            continue;
+        collectNestedDirectories(path.join(baseDir, entry.name), out);
+    }
+    return out;
+}
 function startScanWatch() {
     const scanScript = path.resolve(__dirname, 'cmp-scan.js');
     if (!fs.existsSync(scanScript)) {
@@ -194,8 +251,8 @@ function startScanWatch() {
         console.log('[file-opener] watch roots not found, watch disabled.');
         return;
     }
-    const recursive = process.platform === 'darwin' || process.platform === 'win32';
-    const watchers = [];
+    const supportsRecursive = process.platform === 'darwin' || process.platform === 'win32';
+    const watcherByPath = new Map();
     let scanRunning = false;
     let scanQueued = false;
     let timer = null;
@@ -228,52 +285,111 @@ function startScanWatch() {
     const scheduleScan = (reason) => {
         if (timer)
             clearTimeout(timer);
-        timer = setTimeout(() => runScan(reason), 500);
+        timer = setTimeout(() => runScan(reason), 400);
+    };
+    const refreshWatchers = () => {
+        if (supportsRecursive)
+            return;
+        const nextPaths = new Set();
+        for (const baseRoot of roots) {
+            const dirs = collectNestedDirectories(baseRoot);
+            for (const dir of dirs) {
+                nextPaths.add(dir);
+            }
+        }
+        for (const [watchPath, watcher] of watcherByPath.entries()) {
+            if (!nextPaths.has(watchPath)) {
+                watcher.close();
+                watcherByPath.delete(watchPath);
+            }
+        }
+        for (const watchPath of nextPaths) {
+            attachWatcher(watchPath);
+        }
     };
     const attachWatcher = (watchPath) => {
+        if (watcherByPath.has(watchPath))
+            return;
         try {
-            const watcher = fs.watch(watchPath, { recursive }, (eventType, filename) => {
+            const watcher = fs.watch(watchPath, { recursive: supportsRecursive }, (eventType, filename) => {
                 const detail = filename ? `${eventType}:${filename.toString()}` : eventType;
                 scheduleScan(detail);
+                if (!supportsRecursive && eventType === 'rename') {
+                    refreshWatchers();
+                }
             });
-            watchers.push(watcher);
+            watcherByPath.set(watchPath, watcher);
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
             console.log(`[file-opener] failed to watch ${watchPath}: ${message}`);
-            throw err;
         }
     };
-    try {
+    if (supportsRecursive) {
         roots.forEach(attachWatcher);
-        console.log(`[file-opener] watch enabled (${recursive ? 'recursive' : 'non-recursive'}): ${roots.join(', ')}`);
+        console.log(`[file-opener] watch enabled (recursive): ${roots.join(', ')}`);
     }
-    catch {
-        watchers.forEach((w) => w.close());
-        console.log('[file-opener] falling back to polling scan every 5s');
-        setInterval(() => runScan('poll'), 5000);
+    else {
+        refreshWatchers();
+        console.log(`[file-opener] watch enabled (directory-mode): ${watcherByPath.size} directories`);
+        setInterval(refreshWatchers, 10000);
     }
     runScan('initial');
 }
-function getWatchRoots(includeGlobs, workspaceRoot) {
-    const roots = new Set();
-    includeGlobs.forEach((glob) => {
-        const base = globToBaseDir(glob);
-        const resolved = path.resolve(root, workspaceRoot, base);
-        if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
-            roots.add(resolved);
-        }
-    });
-    return Array.from(roots);
+function safeCompareToken(actual, expected) {
+    const actualBuffer = Buffer.from(actual);
+    const expectedBuffer = Buffer.from(expected);
+    if (actualBuffer.length !== expectedBuffer.length)
+        return false;
+    return crypto.timingSafeEqual(actualBuffer, expectedBuffer);
 }
-function globToBaseDir(glob) {
-    const wildcardIndex = glob.search(/[*?[\]{]/);
-    if (wildcardIndex === -1)
-        return glob;
-    const prefix = glob.slice(0, wildcardIndex);
-    if (prefix.endsWith('/'))
-        return prefix.slice(0, -1);
-    return path.dirname(prefix);
+function extractRequestToken(req, url) {
+    const queryToken = url.searchParams.get('token');
+    if (queryToken)
+        return queryToken;
+    const headerToken = req.headers['x-locatorjs-token'];
+    if (typeof headerToken === 'string' && headerToken.trim().length > 0) {
+        return headerToken.trim();
+    }
+    const authorization = req.headers.authorization;
+    if (typeof authorization === 'string' && authorization.startsWith('Bearer ')) {
+        return authorization.slice('Bearer '.length).trim();
+    }
+    return null;
+}
+function ensureAuthorized(req, url) {
+    if (!AUTH_TOKEN)
+        return true;
+    const token = extractRequestToken(req, url);
+    if (!token)
+        return false;
+    return safeCompareToken(token, AUTH_TOKEN);
+}
+function resolveAllowedFilePath(rawPath) {
+    const trimmed = rawPath.trim();
+    if (!trimmed) {
+        throw new Error('file is required');
+    }
+    if (trimmed.includes('\0')) {
+        throw new Error('file path is invalid');
+    }
+    const resolved = path.isAbsolute(trimmed)
+        ? path.resolve(trimmed)
+        : path.resolve(WORKSPACE_ROOT, trimmed);
+    if (!fs.existsSync(resolved)) {
+        throw new Error('file does not exist');
+    }
+    const realWorkspaceRoot = fs.realpathSync(WORKSPACE_ROOT);
+    const realPath = fs.realpathSync(resolved);
+    const relative = path.relative(realWorkspaceRoot, realPath);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error('file path is outside workspace root');
+    }
+    const stat = fs.statSync(realPath);
+    if (!stat.isFile()) {
+        throw new Error('path must be a file');
+    }
+    return realPath;
 }
 const server = http.createServer((req, res) => {
     if (!req.url) {
@@ -288,6 +404,11 @@ const server = http.createServer((req, res) => {
     }
     const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
     const pathname = url.pathname;
+    if (!ensureAuthorized(req, url)) {
+        res.statusCode = 401;
+        res.end('Unauthorized request');
+        return;
+    }
     if (pathname === '/__cmp-map') {
         if (!fs.existsSync(MAP_PATH)) {
             res.statusCode = 404;
@@ -307,9 +428,18 @@ const server = http.createServer((req, res) => {
             res.end('file is required');
             return;
         }
-        const decoded = decodeURIComponent(file);
-        console.log(`[file-opener] Opening file: ${decoded}:${line}:${col}`);
-        const fileWithPos = `${decoded}:${line}:${col}`;
+        let safePath;
+        try {
+            safePath = resolveAllowedFilePath(decodeURIComponent(file));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'invalid file';
+            res.statusCode = 403;
+            res.end(message);
+            return;
+        }
+        console.log(`[file-opener] Opening file: ${safePath}:${line}:${col}`);
+        const fileWithPos = `${safePath}:${line}:${col}`;
         const ok = launchInEditor(fileWithPos);
         if (!ok) {
             res.statusCode = 500;
@@ -332,11 +462,25 @@ const server = http.createServer((req, res) => {
             res.end('search terms required');
             return;
         }
-        const decoded = decodeURIComponent(file);
+        let safePath;
+        try {
+            safePath = resolveAllowedFilePath(decodeURIComponent(file));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'invalid file';
+            res.statusCode = 403;
+            res.end(message);
+            return;
+        }
         try {
             const searchTerms = JSON.parse(decodeURIComponent(searchParam));
-            const bestLine = findBestLineInFile(decoded, searchTerms);
-            const fileWithPos = `${decoded}:${bestLine}:1`;
+            if (!Array.isArray(searchTerms) || !searchTerms.every((term) => typeof term === 'string')) {
+                res.statusCode = 400;
+                res.end('search terms must be string[]');
+                return;
+            }
+            const bestLine = findBestLineInFile(safePath, searchTerms);
+            const fileWithPos = `${safePath}:${bestLine}:1`;
             const ok = launchInEditor(fileWithPos);
             if (!ok) {
                 res.statusCode = 500;
@@ -357,10 +501,17 @@ const server = http.createServer((req, res) => {
     res.end('Not found');
 });
 server
-    .listen(PORT, () => {
-    console.log(`[file-opener] http://localhost:${PORT}`);
+    .listen(PORT, HOST, () => {
+    console.log(`[file-opener] http://${HOST}:${PORT}`);
     console.log(` - map: ${path.relative(root, MAP_PATH)}`);
     console.log(` - editor: ${DEFAULT_EDITOR} (fallback: ${FALLBACK_EDITOR})`);
+    console.log(` - workspace root: ${WORKSPACE_ROOT}`);
+    if (AUTH_TOKEN) {
+        console.log(' - auth: enabled');
+    }
+    else {
+        console.log(' - auth: disabled (legacy config, run locatorjs-config to enable)');
+    }
     if (AVAILABLE_EDITORS.length > 0) {
         console.log(' - detected editors:');
         AVAILABLE_EDITORS.forEach((editor) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-locatorjs",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "LocatorJs open-in-editor tools for Angular projects",
   "keywords": [
     "angular",
@@ -49,8 +49,11 @@
     "build:node": "tsc -p tsconfig.node.json",
     "clean": "rm -rf dist",
     "prepare": "npm run build",
+    "test": "node --test",
+    "test:ci": "npm run build && npm test",
     "format": "oxfmt",
-    "format:check": "oxfmt --check"
+    "format:check": "oxfmt --check",
+    "publish:github": "node scripts/publish-github.mjs"
   },
   "dependencies": {
     "glob": "^13.0.6"