@xfilecom/xframe 0.1.20 → 0.1.22

package/bin/xframe.js

@@ -30,12 +30,52 @@ function shouldProcess(filePath) {
   return false;
 }
 
+/** 모노레포 sibling 패키지 또는 배포 tarball 의 defaults.json → ^semver */
+let defaultCoreSpecsCache;
+function getDefaultCoreSpecs() {
+  if (defaultCoreSpecsCache) return defaultCoreSpecsCache;
+  const hardcoded = { backendCore: '^1.0.1', frontCore: '^0.2.6' };
+  const readCaret = (pkgPath, expectedName) => {
+    try {
+      if (!fs.existsSync(pkgPath)) return null;
+      const j = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      if (j.name !== expectedName || !j.version) return null;
+      return `^${j.version}`;
+    } catch {
+      return null;
+    }
+  };
+  const binDir = __dirname;
+  const monoBackend = path.join(binDir, '..', '..', 'backend-core', 'package.json');
+  const monoFront = path.join(binDir, '..', '..', 'front-core', 'package.json');
+  let backendCore = readCaret(monoBackend, '@xfilecom/backend-core');
+  let frontCore = readCaret(monoFront, '@xfilecom/front-core');
+  if (!backendCore || !frontCore) {
+    try {
+      const defPath = path.join(binDir, '..', 'defaults.json');
+      if (fs.existsSync(defPath)) {
+        const d = JSON.parse(fs.readFileSync(defPath, 'utf8'));
+        if (d.backendCore) backendCore = backendCore || d.backendCore;
+        if (d.frontCore) frontCore = frontCore || d.frontCore;
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+  defaultCoreSpecsCache = {
+    backendCore: backendCore || hardcoded.backendCore,
+    frontCore: frontCore || hardcoded.frontCore,
+  };
+  return defaultCoreSpecsCache;
+}
+
 function usage() {
+  const { backendCore: defB, frontCore: defF } = getDefaultCoreSpecs();
   console.log(`Usage: xframe <project-directory> [options]
 
 Options:
-  --backend-core <spec>   @xfilecom/backend-core (default: ^1.0.0)
-  --front-core <spec>     @xfilecom/front-core (default: ^0.2.1)
+  --backend-core <spec>   @xfilecom/backend-core (default: ${defB})
+  --front-core <spec>     @xfilecom/front-core (default: ${defF}, npm 공개 레지스트리)
   --no-install            스캐폴드만 하고 yarn/npm install 생략
 
 MySQL (shared/config/api/application.yml 의 database.*)
@@ -57,10 +97,11 @@ Examples:
 }
 
 function parseArgs(argv) {
+  const defs = getDefaultCoreSpecs();
   const rest = argv.slice(2);
   let projectDir = null;
-  let backendCore = '^1.0.0';
-  let frontCore = '^0.2.1';
+  let backendCore = defs.backendCore;
+  let frontCore = defs.frontCore;
   let skipInstall = false;
   let skipDbPrompt = false;
   let dbPull = false;

package/defaults.json

@@ -0,0 +1,4 @@
+{
+  "backendCore": "^1.0.3",
+  "frontCore": "^0.2.8"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfilecom/xframe",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "Scaffold full-stack app: Nest + @xfilecom/backend-core, Vite/React + @xfilecom/front-core",
   "license": "UNLICENSED",
   "bin": {
@@ -8,8 +8,14 @@
   },
   "files": [
     "bin",
+    "defaults.json",
     "template"
   ],
+  "scripts": {
+    "sync-defaults": "node scripts/sync-defaults.js",
+    "sync-template-front-core": "node scripts/sync-template-front-core.js",
+    "prepublishOnly": "npm run sync-defaults && npm run sync-template-front-core"
+  },
   "engines": {
     "node": ">=18"
   },

package/template/README.md

@@ -20,6 +20,8 @@ Nest API (`@xfilecom/backend-core`) + Vite/React client·admin (`@xfilecom/front
 - Client: `http://localhost:3001` — `CommonResponse` 형태로 `/health` 표시
 - Admin: `http://localhost:3002`
 
+`@xfilecom/front-core` / `@xfilecom/backend-core` 는 **`package.json`에서 npm 버전 범위**(예: `^0.2.6`, `^1.0.1`)로 두는 것을 권장합니다. `file:../../../packages/...` 는 폴더 구조에 따라 깨지기 쉽습니다. 스캐폴드 시 `npx @xfilecom/xframe` 이 넣는 기본 범위는 **배포 시점의 코어 패키지 버전**과 맞춰지며(`defaults.json`, `npm publish` 전 동기화), 필요하면 `--backend-core` / `--front-core` 로 덮어쓸 수 있습니다.
+
 ## `shared/` (설정·스키마·SQL·endpoint)
 
 - **`shared/config/api`**, **`shared/config/web/client`**, **`shared/config/web/admin`**: YAML (`application.yml` + `application-<env>.yml`)
@@ -32,6 +34,20 @@ Nest API (`@xfilecom/backend-core`) + Vite/React client·admin (`@xfilecom/front
 
 설정 흐름, `DatabaseService` / `DatabaseQuery` 주입, Drizzle Kit 스크립트는 **[docs/DATABASE.md](./docs/DATABASE.md)** 를 보면 됩니다.
 
+## 브라우저 콘솔: `content.js`, `chrome-extension://invalid`, `locales.getpip.com`
+
+Client/Admin을 Chrome으로 열었을 때 아래 같은 메시지가 **앱 코드와 무관**하게 뜰 수 있습니다.
+
+| 증상 | 원인 |
+|------|------|
+| `content.js:…` 스택 | Chrome **확장 프로그램**이 페이지에 주입한 스크립트 |
+| `GET chrome-extension://invalid/ … ERR_FAILED` | 지갑·Web3 등 확장이 잘못된 확장 URL로 리소스를 요청할 때 |
+| `GET https://locales.getpip.com/… … ERR_NAME_NOT_RESOLVED` | 일부 확장이 원격 번역/로케일을 가져오다 DNS·네트워크로 실패할 때 |
+
+**대응:** 앱 버그가 아니므로 무시해도 됩니다. 콘솔을 깨끗이 보고 싶으면 **시크릿 창**(확장 기본 비활성)에서 `localhost`를 열거나, 개발용 Chrome 프로필에서 확장을 끄면 됩니다.
+
+자세한 설명은 **[docs/WEB_DEV_CONSOLE.md](./docs/WEB_DEV_CONSOLE.md)** 참고.
+
 ## GitLab `~/.npmrc` 와 충돌 시
 
 프로젝트 루트 `.npmrc`의 `@xfilecom:registry`가 npm 공개 레지스트리를 가리키므로, `@xfilecom/*` 설치는 여기서 우선합니다.

package/template/apps/api/package.json

@@ -3,9 +3,9 @@
   "version": "0.0.1",
   "private": true,
   "scripts": {
-    "build": "nest build",
-    "start": "nest build && node --enable-source-maps dist/apps/api/src/main.js",
-    "start:dev": "tsc-watch -p tsconfig.build.json --onSuccess \"node --enable-source-maps dist/apps/api/src/main.js\" --noClear",
+    "build": "nest build && tsc-alias -p tsconfig.build.json",
+    "start": "npm run build && node --enable-source-maps dist/apps/api/src/main.js",
+    "start:dev": "tsc-watch -p tsconfig.build.json --onSuccess \"tsc-alias -p tsconfig.build.json && node --enable-source-maps dist/apps/api/src/main.js\" --noClear",
     "start:prod": "node --enable-source-maps dist/apps/api/src/main.js"
   },
   "dependencies": {
@@ -20,6 +20,7 @@
     "@nestjs/cli": "^10.0.0",
     "@types/express": "^4.17.21",
     "@types/node": "^20.0.0",
+    "tsc-alias": "^1.8.10",
     "tsc-watch": "^6.2.1",
     "typescript": "^5.0.0"
   }

package/template/apps/api/src/app.module.ts

@@ -5,7 +5,7 @@ import { AppController } from './app.controller';
 import { AppService } from './app.service';
 import { SqlQueryController } from './sql-query/sql-query.controller';
 import { SqlQueryService } from './sql-query/sql-query.service';
-import { schema } from '../../../shared/schema';
+import { schema } from '@shared/schema';
 
 function coreOptionsFromYaml(): CoreModuleOptions {
   const c = appConfig.core;

package/template/apps/api/src/sql-query/sql-query.controller.ts

@@ -8,7 +8,7 @@ import {
 } from '@nestjs/common';
 import { ControllerHelpers, Public } from '@xfilecom/backend-core';
 import { appConfig } from '../config.loader';
-import type { SqlDatabaseListPostBody, SqlListPostBody } from '../../../../shared/sql/sql';
+import type { SqlDatabaseListPostBody, SqlListPostBody } from '@shared/sql/sql';
 import { SqlQueryService } from './sql-query.service';
 
 /**

package/template/apps/api/src/sql-query/sql-query.service.ts

@@ -11,13 +11,13 @@ import {
   listPageableColumnNames,
   pageableFromClause,
   pickDefaultSortColumn,
-} from '../../../../shared/sql/pageable-drizzle';
+} from '@shared/sql/pageable-drizzle';
 import {
   getPageableResourceKeyByMysqlTableName,
   getPageableTable,
   getPageableTableByMysqlTableName,
   PAGEABLE_RESOURCE_OPTIONS,
-} from '../../../../shared/sql/pageable-tables';
+} from '@shared/sql/pageable-tables';
 import {
   escapeLikePattern,
   isSafeSqlIdentifier,
@@ -25,7 +25,7 @@ import {
   resolveEndpointSqlQuery,
   type SqlDatabaseListPostBody,
   type SqlListPostBody,
-} from '../../../../shared/sql/sql';
+} from '@shared/sql/sql';
 
 @Injectable()
 export class SqlQueryService {

package/template/apps/api/tsconfig.json

@@ -10,6 +10,9 @@
     "sourceMap": true,
     "outDir": "./dist",
     "baseUrl": "./",
+    "paths": {
+      "@shared/*": ["../../shared/*"]
+    },
     "incremental": true,
     "skipLibCheck": true,
     "strictNullChecks": false,

package/template/docs/WEB_DEV_CONSOLE.md

@@ -0,0 +1,20 @@
+# 웹 Client/Admin — 브라우저 콘솔 노이즈
+
+Chrome에서 `http://localhost:3001` 등을 열었을 때 DevTools 콘솔에 아래가 보일 수 있습니다. **이 프로젝트(Vite/React) 소스와는 무관**합니다.
+
+## `content.js` / `chrome-extension://invalid/`
+
+- Chrome **확장 프로그램**이 모든 탭에 주입하는 **content script**가 `content.js`처럼 보이는 스택을 남깁니다.
+- `chrome-extension://invalid/` 요청은 지갑·Web3·기타 확장이 내부 리소스 URL을 잘못 잡았을 때 발생합니다.
+- 스택에 `getProvider`, `autoConnect` 등이 보이면 **지갑 확장** 쪽일 가능성이 큽니다.
+
+## `locales.getpip.com` / `ERR_NAME_NOT_RESOLVED`
+
+- 일부 확장이 원격 번역 JSON을 받아오다 DNS 실패·차단으로 네트워크 오류를 냅니다.
+- 앱의 `fetch` / 라우팅과는 별개입니다.
+
+## 권장 대응
+
+1. **무시** — 앱 동작·배포와 무관하면 그대로 두어도 됩니다.
+2. **시크릿 창**에서 로컬 호스트를 열면 확장이 기본 꺼져 콘솔이 조용해집니다.
+3. 개발 전용 Chrome 프로필에서 확장을 끄거나, 해당 확장만 비활성화합니다.

package/template/shared/README.md

@@ -10,6 +10,8 @@
 | **`sql/`** | 마이그레이션·시드·원시 SQL; **`sql/sql.ts`** (`databaseSqlManifest`) 로 경로·절차 메타 정리 |
 | **`endpoint/`** | HTTP 계약(OpenAPI yaml, 공유 DTO 타입, 라우트 메타) — 제품에 맞게 확장 |
 
+프론트 전용 공유 패키지(**`web/shared`**)는 이 루트 `shared/`와 **별도**입니다. 설명은 **[`web/shared/README.md`](../web/shared/README.md)** 를 참고하세요.
+
 `apps/api/src/config.loader.ts`는 **`shared/config/api`** 를 읽습니다.  
 `web/client/vite.config.ts` / `web/admin/vite.config.ts`는 각각 **`shared/config/web/client`**, **`shared/config/web/admin`** 을 읽습니다.
 

package/template/web/admin/src/main.tsx

@@ -1,9 +1,9 @@
 import React from 'react';
 import ReactDOM from 'react-dom/client';
 import '@xfilecom/front-core/tokens.css';
-import '../../shared/src/styles/xfc-theme.css';
+import '__WEB_SHARED_WORKSPACE__/styles/xfc-theme.css';
 import '@xfilecom/front-core/base.css';
-import '../../shared/src/styles/app.css';
+import '__WEB_SHARED_WORKSPACE__/styles/app.css';
 import { App } from './App';
 
 ReactDOM.createRoot(document.getElementById('root')!).render(

package/template/web/client/src/main.tsx

@@ -1,9 +1,9 @@
 import React from 'react';
 import ReactDOM from 'react-dom/client';
 import '@xfilecom/front-core/tokens.css';
-import '../../shared/src/styles/xfc-theme.css';
+import '__WEB_SHARED_WORKSPACE__/styles/xfc-theme.css';
 import '@xfilecom/front-core/base.css';
-import '../../shared/src/styles/app.css';
+import '__WEB_SHARED_WORKSPACE__/styles/app.css';
 import { App } from './App';
 
 ReactDOM.createRoot(document.getElementById('root')!).render(

package/template/web/shared/README.md

@@ -0,0 +1,25 @@
+# `web/shared` — 클라이언트·어드민 공유 패키지
+
+Vite 앱(`web/client`, `web/admin`)이 함께 쓰는 **React 컴포넌트, 스타일, 훅, 타입**을 두는 워크스페이스 패키지입니다.  
+프로젝트 루트의 **`shared/`**(Drizzle 스키마, `sql/`, API `config/` 등)와 **별도**입니다.
+
+## 백엔드 `@shared/*`와 겹치나요?
+
+**겹치지 않습니다.** Nest(`apps/api`)는 `@shared/*`를 루트 `shared/`로만 쓰고, 프론트는 이 패키지의 **npm 이름**(`__WEB_SHARED_WORKSPACE__` → 스캐폴드 시 실제 이름)과 **`exports`** 서브패스로만 연결합니다.
+
+## 스타일 (`main.tsx`)
+
+```ts
+import '@xfilecom/front-core/tokens.css';
+import '__WEB_SHARED_WORKSPACE__/styles/xfc-theme.css';
+import '@xfilecom/front-core/base.css';
+import '__WEB_SHARED_WORKSPACE__/styles/app.css';
+```
+
+## TS/컴포넌트
+
+```ts
+import { Shell } from '__WEB_SHARED_WORKSPACE__';
+```
+
+새 파일을 앱에서 가져오려면 `package.json`의 **`exports`**에 서브패스를 추가하세요.