seokang-sk 0.2.0 → 0.2.2

package/README.MD

@@ -11,7 +11,18 @@
 
 `sk`는 최종적으로 `~/.agents/skills`의 로컬 저장소를 기준으로 동작해야 한다.
 
-즉, npm으로 배포한 뒤에도 `~/.agents/skills/sk-feature-workflow/SKILL.md` 같은 스킬 파일을 로컬에서 바로 수정할 수 있어야 한다. 배포 패키지는 설치 진입점과 디스패치만 담당하고, 실제 기준 원본은 로컬 저장소에 남는다.
+즉, npm으로 배포한 뒤에도 `~/.agents/skills/skills/sk-feature-workflow/SKILL.md` 같은 스킬 파일을 로컬에서 바로 수정할 수 있어야 한다. 배포 패키지는 설치 진입점과 디스패치만 담당하고, 실제 기준 원본은 로컬 저장소에 남는다.
+
+중요:
+- `~/.agents/skills`는 이 저장소의 repo root다.
+- 실제 skill 폴더는 `~/.agents/skills/skills/` 아래에 둔다.
+- `docs/`, `codex-config/`, `scripts/`는 지원 폴더이고, `skills/`가 skill 묶음 폴더다.
+
+## 30초 구조 요약
+
+- repo root는 `~/.agents/skills`다.
+- 실제 skill은 `~/.agents/skills/skills/sk-이름/SKILL.md` 형태로 둔다.
+- `docs/`, `codex-config/`, `scripts/`는 지원 폴더이며, `skills/`만 skill 묶음 폴더다.
 
 ## 처음 설치
 
@@ -23,6 +34,12 @@ sk init
 sk status
 ```
 
+- DB safe-read login-path alias를 프로젝트 track 기준으로 맞추려면 아래 명령을 사용한다.
+
+```bash
+sk setup --configure-db-safe-read
+```
+
 - Notion 문서까지 함께 쓸 계획이면 설치 후 한 번 더 아래 명령을 실행한다.
 
 ```bash
@@ -31,7 +48,8 @@ sk setup --configure-notion
 
 - `Records` / `Projects` 데이터베이스 URL에 Notion id가 들어 있으면 `data source id`는 setup 중 자동으로 추출한다.
 
-- Notion 문서 기록이 Codex에서 실패하면 아래 명령으로 MCP 인증을 다시 연결한다.
+- Notion 문서 기록이 `invalid_grant`, `unauthorized`, `forbidden` 같은 인증 오류로 실패하면 아래 명령으로 MCP 인증을 다시 연결한다.
+- `Tool ... not found`처럼 특정 Notion tool만 빠진 경우는 로그인 문제가 아닐 수 있으니, exact error를 남기고 남아 있는 Notion MCP tool로 우회 가능한지 먼저 확인한다.
 
 ```bash
 codex mcp login notion
@@ -53,15 +71,16 @@ codex mcp login notion
 
 ```text
 .
-|- sk-feature-workflow     # 기능 작업 메인 오케스트레이터
-|- sk-bugfix-workflow      # 버그 수정 워크플로
-|- sk-refactor             # 리팩토링 워크플로
-|- sk-plan                 # 기획/설계 응답 워크플로
-|- sk-db                   # DB 변경 워크플로
-|- sk-design-system        # 디자인 시스템 점검/구축
-|- sk-docs                 # 변경 문서 작성
-|- sk-git                  # git add/commit/push 워크플로
-|- sk-deploy               # 배포 워크플로
+|- skills/
+|  |- sk-feature-workflow  # 기능 작업 메인 오케스트레이터
+|  |- sk-bugfix-workflow   # 버그 수정 워크플로
+|  |- sk-refactor          # 리팩토링 워크플로
+|  |- sk-plan              # 기획/설계 응답 워크플로
+|  |- sk-db                # DB 변경 워크플로
+|  |- sk-design-system     # 디자인 시스템 점검/구축
+|  |- sk-docs              # 변경 문서 작성
+|  |- sk-git               # git add/commit/push 워크플로
+|  |- sk-deploy            # 배포 워크플로
 |- codex-config/
 |  |- config/              # ~/.codex/config.toml 공용 원본
 |  |- agents/              # ~/.codex/agents 공용 원본
@@ -69,6 +88,14 @@ codex mcp login notion
 |- scripts/                # 공용 설치 / 보조 스크립트
 ```
 
+- 실제 skill 엔트리는 `skills/sk-*/SKILL.md`다.
+
+## 어디를 수정하나
+
+- skill 동작 변경: `skills/sk-*/SKILL.md`
+- 설치/런타임 설정 변경: `codex-config/**`, `scripts/**`
+- 사용법/운영 가이드 변경: `docs/**`, `README.MD`
+
 ---
 
 ## 목적
@@ -178,7 +205,7 @@ sh ./sk status
   - `docs/**` 인덱스/개요 문서
   - 현재 요청과 직접 관련된 상세 문서
 - 문서가 많으면 전부 읽으려 하지 말고, 인덱스/개요 → 관련 상세 순서로 좁혀 읽는다.
-- `.agents/skills`에서는 `README.MD`, `docs/**`, 수정 대상 `SKILL.md`, 관련 setup/config 문서를 기본 세트로 본다.
+- `.agents/skills`에서는 `README.MD`, `docs/**`, `skills/**`, 수정 대상 `SKILL.md`, 관련 setup/config 문서를 기본 세트로 본다.
 
 ---
 
@@ -304,8 +331,8 @@ LOCAL_JAR_PATH=./build/libs/km-admin-api.jar
 
 `seokang-skill` 프로젝트에서는 아래 스크립트/템플릿을 사용한다.
 
-- `sk-deploy/deploy-npm.sh`
-- `sk-deploy/deploy.local.conf.template.npm`
+- `skills/sk-deploy/deploy-npm.sh`
+- `skills/sk-deploy/deploy.local.conf.template.npm`
 
 ---
 

package/docs/sk-cli-guide.md

@@ -12,7 +12,19 @@
 
 `sk`는 최종적으로 `~/.agents/skills`의 로컬 저장소를 기준으로 동작해야 한다.
 
-그래서 npm으로 배포한 뒤에도 `~/.agents/skills/sk-feature-workflow/SKILL.md`를 바로 수정할 수 있다. 배포 패키지는 설치 진입점과 디스패치만 담당하고, 실제 기준 원본은 여전히 로컬 저장소다.
+그래서 npm으로 배포한 뒤에도 `~/.agents/skills/skills/sk-feature-workflow/SKILL.md`를 바로 수정할 수 있다. 배포 패키지는 설치 진입점과 디스패치만 담당하고, 실제 기준 원본은 여전히 로컬 저장소다.
+
+중요:
+
+- `~/.agents/skills`는 repo root다.
+- 실제 skill은 `~/.agents/skills/skills/` 아래에 둔다.
+- `docs/`, `codex-config/`, `scripts/`는 지원 폴더이고, `skills/`가 skill 묶음 폴더다.
+
+## 하지 말아야 할 구조 변경
+
+- `sk-*` 디렉터리를 `skills/` 밖 여기저기에 흩어 놓지 않는다.
+- `SKILL.md`를 루트 밖 공용 문서 폴더로 합치지 않는다.
+- 프로젝트별 상태 폴더 `.sk/`와 이 저장소의 skill 디렉터리를 같은 개념으로 보지 않는다.
 
 ## 처음 설치
 
@@ -196,6 +208,11 @@ sk check
 
 이 명령은 source와 실제 설치 대상이 일치하는지 확인한다.
 
+- DB safe-read를 자주 쓰는 환경이면 `mysql`/`mysql_config_editor`의 PATH 또는 full path fallback, `~/.mylogin.cnf`, login-path alias 상태도 함께 보여준다.
+- 출력이 `PATH 미노출`이더라도 full path fallback이 보이면 곧바로 `mysql 없음`으로 판단하지 않는다.
+- 현재 프로젝트에서 legacy alias만 보이면 `sk setup --configure-db-safe-read`로 track alias migration을 바로 진행할 수 있다.
+- `DB client` 경고가 뜨면 alias보다 먼저 client 설치/PATH를 해결해야 한다. 현재 메시지에서 바로 다음 액션까지 확인할 수 있다.
+
 ### 4-3. 현재 상태 보기
 
 ```bash
@@ -204,7 +221,56 @@ sk status
 
 이 명령은 현재 프로젝트 기준 `.sk` 상태, 메모 파일 존재 여부, 최근 backup을 보여준다.
 
-### 4-4. 현재 프로젝트 `.sk` 초기화
+### 4-4. DB safe-read alias 맞추기
+
+현재 프로젝트 track 기준 DB login-path alias를 `sk` 안에서 맞추려면 아래처럼 실행한다.
+
+```bash
+sk setup --configure-db-safe-read
+```
+
+- 예: `slk-api` 프로젝트에서 실행하면 `codex-db-slk-server` alias를 기준으로 맞춘다.
+- 이미 `codex_ro`만 있으면 host / port / user를 재사용하고, 비밀번호만 `mysql_config_editor` 프롬프트에서 다시 입력한다.
+- track을 직접 지정하고 싶으면 `--track <name>`을 붙일 수 있다.
+
+```bash
+sk setup --configure-db-safe-read --track slk-server
+```
+
+### 4-5. DB safe-read 선행 조건
+
+`sk setup --configure-db-safe-read`가 바로 동작하려면 `mysql`과 `mysql_config_editor`가 먼저 준비돼 있어야 한다.
+
+가장 짧은 확인 순서는 아래다.
+
+1. `sk check`로 현재 상태가 `client 부재`, `PATH 미노출`, `alias 없음` 중 어디인지 먼저 본다.
+2. `DB client` 경고면 client 설치/PATH를 먼저 해결한다.
+3. 그다음 `sk check`를 다시 실행한다.
+4. client가 잡히면 `sk setup --configure-db-safe-read`로 alias를 만든다.
+
+#### macOS
+
+```bash
+brew install mysql-client
+sk check
+sk setup --configure-db-safe-read
+```
+
+PATH를 따로 추가하지 않아도 `sk`는 Homebrew 표준 full path fallback을 먼저 시도한다.
+
+#### Windows Git Bash
+
+MySQL client tools(`mysql`, `mysql_config_editor`)가 있어야 한다. MariaDB 설치본은 `mysql_config_editor`가 빠질 수 있으니 `sk check`로 먼저 확인한다. 설치 후 Git Bash에서 아래처럼 PATH를 맞춘다.
+
+```bash
+export PATH="/c/Program Files/MySQL/MySQL Server 8.0/bin:$PATH"
+sk check
+sk setup --configure-db-safe-read
+```
+
+`sk check`에서 client fallback 경로가 보이면 PATH 미노출일 뿐이므로 즉시 alias 단계로 넘어가도 된다.
+
+### 4-6. 현재 프로젝트 `.sk` 초기화
 
 ```bash
 cd /path/to/project

package/docs/sk-notion-workspace.md

@@ -24,6 +24,8 @@ sk setup --configure-notion
 추출이 안 되는 특수 URL만 `workspace.json`에서 수동으로 보완하면 된다.
 
 필요하면 이어서 아래 명령으로 Codex의 Notion MCP 인증도 연결한다.
+단, 이 재로그인은 `invalid_grant`, `unauthorized`, `forbidden` 같은 인증/세션 오류일 때의 기본 대응이다.
+`Tool ... not found`처럼 특정 MCP tool만 누락된 경우는 로그인 문제가 아닐 수 있으므로, exact error를 남기고 다른 Notion MCP tool로 우회 가능한지 먼저 본다.
 
 ```bash
 codex mcp login notion
@@ -56,5 +58,6 @@ codex mcp login notion
 - public skill 본문에 개인 Notion URL, DB id, collection id를 직접 적지 않는다.
 - Notion 작업 전에는 먼저 local config 파일 존재 여부와 `configured` 상태를 확인한다.
 - local config가 없거나 `configured=false`면 Notion 기록 시도를 생략하고 Markdown fallback을 기본 출력으로 사용한다.
+- `Tool ... not found`처럼 특정 Notion MCP tool만 빠진 경우는 Notion 전체 장애로 단정하지 않는다. local config의 data source id와 project/history 위치가 있으면 `fetch`/`search`/`create_pages`/`update_page` 같은 생존 tool로 먼저 우회 시도한다.
 - fallback Markdown를 나중에 Notion으로 옮길 때는 `Projects > History`의 `Date`를 이관 완료 시점의 로컬 datetime으로 다시 저장하고, `date:Date:is_datetime=1`을 유지한 뒤에만 fallback 파일을 제거한다.
 - 사용자가 이후 Notion 기록도 원하면 그때 `sk setup --configure-notion`을 안내하고, Notion MCP 실패 여부와 구분해서 보고한다.

package/docs/sk-setup-architecture.md

@@ -21,10 +21,16 @@ The most important rule is:
 
 That is why editing a file like:
 
-`~/.agents/skills/sk-feature-workflow/SKILL.md`
+`~/.agents/skills/skills/sk-feature-workflow/SKILL.md`
 
 stays simple. You are editing the real source file that `sk` will delegate to, not a hidden copy inside the npm install directory.
 
+One more rule matters here:
+
+- `~/.agents/skills` is the repo root
+- actual skill folders live under `~/.agents/skills/skills`
+- support files like `docs/`, `codex-config/`, and `scripts/` stay at repo root
+
 ## Install flow
 
 Recommended first-time setup:
@@ -64,6 +70,8 @@ It only needs enough code to:
 
 The full skills, config, agents, docs, and repo-local helpers stay in `~/.agents/skills`.
 
+That includes the skill directories themselves under `~/.agents/skills/skills`, which Codex can still discover from the canonical user skills root.
+
 ## Editing model
 
 After setup, improvements happen in one place only:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seokang-sk",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "SeoKang Codex 공용 설정과 스킬을 설치하는 CLI",
   "license": "MIT",
   "homepage": "https://github.com/Seokang/seokang-codex-setting",

package/scripts/sk.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { spawnSync } from 'node:child_process';
-import { createReadStream, existsSync } from 'node:fs';
+import { createReadStream, existsSync, readdirSync } from 'node:fs';
 import {
   copyFile,
   mkdir,
@@ -29,6 +29,63 @@ const NOTION_CONFIG_FILE = 'workspace.json';
 const GUIDE_RELATIVE_PATH = join('docs', 'sk-cli-guide.md');
 const DEFAULT_BOOTSTRAP_REPO = 'https://github.com/Seokang/seokang-codex-setting.git';
 const CANONICAL_SKILLS_SEGMENTS = ['.agents', 'skills'];
+function windowsMysqlCandidates(binaryName) {
+  if (process.platform !== 'win32') return [];
+
+  const candidates = [];
+  const programRoots = [
+    'C:\\Program Files',
+    'C:\\Program Files (x86)',
+  ];
+
+  for (const programRoot of programRoots) {
+    const mysqlRoot = join(programRoot, 'MySQL');
+    if (existsSync(mysqlRoot)) {
+      for (const entry of readdirSync(mysqlRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        candidates.push(join(mysqlRoot, entry.name, 'bin', binaryName));
+      }
+    }
+
+    if (!existsSync(programRoot)) continue;
+    for (const entry of readdirSync(programRoot, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      if (!entry.name.toLowerCase().startsWith('mariadb')) continue;
+      candidates.push(join(programRoot, entry.name, 'bin', binaryName));
+    }
+  }
+
+  return [...new Set(candidates)];
+}
+
+const MYSQL_BIN_CANDIDATES = [
+  '/opt/homebrew/opt/mysql-client/bin/mysql',
+  '/usr/local/opt/mysql-client/bin/mysql',
+  '/c/Program Files/MySQL/MySQL Server 8.0/bin/mysql.exe',
+  '/c/Program Files/MySQL/MySQL Server 8.0/bin/mysql',
+  '/c/Program Files/MariaDB 11.4/bin/mysql.exe',
+  '/c/Program Files/MariaDB 11.4/bin/mysql',
+  ...windowsMysqlCandidates('mysql.exe'),
+];
+const MYSQL_CONFIG_EDITOR_CANDIDATES = [
+  '/opt/homebrew/opt/mysql-client/bin/mysql_config_editor',
+  '/usr/local/opt/mysql-client/bin/mysql_config_editor',
+  '/c/Program Files/MySQL/MySQL Server 8.0/bin/mysql_config_editor.exe',
+  '/c/Program Files/MySQL/MySQL Server 8.0/bin/mysql_config_editor',
+  ...windowsMysqlCandidates('mysql_config_editor.exe'),
+];
+const LEGACY_DB_LOGIN_PATH = 'codex_ro';
+const DB_TRACK_RULES = [
+  { track: 'slk-server', needles: ['slk-api', 'slk-server'] },
+  { track: 'server', needles: ['km-admin-api', '/server', '\\server'] },
+  { track: 'price-spinks', needles: ['price-advisor-spinks', 'price-spinks', 'spinks'] },
+  { track: 'price-sealy', needles: ['price-advisor-sealy', 'price-sealy', 'sealy'] },
+  { track: 'price', needles: ['price-advisor', '/price', '\\price'] },
+  { track: 'office-web', needles: ['kwang-admin', 'admin-web', 'office-web'] },
+  { track: 'office-app', needles: ['office-app', '/app', '\\app'] },
+  { track: 'flow-frame', needles: ['flow-frame'] },
+  { track: 'seokang-skill', needles: ['.agents/skills', 'seokang-skill', 'sellink docs'] },
+];
 
 function canonicalRepoRoot() {
   return resolve(process.env.SK_REPO_ROOT || join(homedir(), ...CANONICAL_SKILLS_SEGMENTS));
@@ -58,6 +115,357 @@ function canRun(command, args = ['--version']) {
   return !result.error && result.status === 0;
 }
 
+function detectExecutable(commandName, candidates = []) {
+  if (canRun(commandName)) {
+    return { source: 'path', path: commandName };
+  }
+
+  for (const candidate of candidates) {
+    if (candidate && canRun(candidate)) {
+      return { source: 'fallback', path: candidate };
+    }
+  }
+
+  return null;
+}
+
+function summarizeAliases(aliasNames) {
+  if (aliasNames.length === 0) return '없음';
+  if (aliasNames.length <= 3) return aliasNames.join(', ');
+  return `${aliasNames.slice(0, 3).join(', ')} 외 ${aliasNames.length - 3}개`;
+}
+
+function inferTrackFromPath(cwd = process.cwd()) {
+  const normalized = resolve(cwd).replaceAll('\\', '/').toLowerCase();
+  for (const rule of DB_TRACK_RULES) {
+    if (rule.needles.some((needle) => normalized.includes(needle))) {
+      return rule.track;
+    }
+  }
+  return null;
+}
+
+function dbTargetAlias(track) {
+  return track ? `codex-db-${track}` : 'codex-db-default';
+}
+
+function dbSafeReadSetupCommand(track) {
+  return track ? `sk setup --configure-db-safe-read --track ${track}` : 'sk setup --configure-db-safe-read';
+}
+
+function mysqlClientInstallHint() {
+  if (process.platform === 'darwin') {
+    return 'macOS: 먼저 "brew install mysql-client"를 실행하고, 필요하면 "/opt/homebrew/opt/mysql-client/bin" PATH를 확인하세요.';
+  }
+
+  if (process.platform === 'win32') {
+    return 'Windows Git Bash: MySQL client tools(mysql, mysql_config_editor)를 설치하고 "/c/Program Files/MySQL/.../bin"을 PATH에 추가하세요. MariaDB 설치본은 mysql_config_editor가 빠질 수 있으니 같이 확인하세요.';
+  }
+
+  return '먼저 mysql client tools(mysql, mysql_config_editor)를 설치하고 PATH를 맞추세요.';
+}
+
+function mysqlClientRecoveryHint(track) {
+  return `${mysqlClientInstallHint()} 그다음 "sk check"로 client 상태를 다시 확인하고, alias가 없으면 "${dbSafeReadSetupCommand(track)}"를 실행하세요.`;
+}
+
+function normalizeMysqlConfigValue(rawValue = '') {
+  const value = String(rawValue).trim();
+  if (value.startsWith('"') && value.endsWith('"')) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+function parseMysqlConfigEditorOutput(output = '') {
+  const profiles = {};
+  let currentAlias = null;
+
+  for (const line of String(output).split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+    const aliasMatch = trimmed.match(/^\[([^\]]+)\]$/);
+    if (aliasMatch) {
+      currentAlias = aliasMatch[1];
+      profiles[currentAlias] = {};
+      continue;
+    }
+
+    if (!currentAlias) continue;
+
+    const fieldMatch = trimmed.match(/^([a-zA-Z0-9_-]+)\s*=\s*(.+)$/);
+    if (!fieldMatch) continue;
+
+    profiles[currentAlias][fieldMatch[1]] = normalizeMysqlConfigValue(fieldMatch[2]);
+  }
+
+  return profiles;
+}
+
+function chooseDbSourceProfile(profiles, targetAlias) {
+  const preferredAliases = ['codex-db-default', LEGACY_DB_LOGIN_PATH];
+  for (const alias of preferredAliases) {
+    if (alias === targetAlias) continue;
+    if (profiles[alias]?.host && profiles[alias]?.user) {
+      return { alias, ...profiles[alias] };
+    }
+  }
+
+  for (const [alias, profile] of Object.entries(profiles)) {
+    if (alias === targetAlias) continue;
+    if (profile?.host && profile?.user) {
+      return { alias, ...profile };
+    }
+  }
+
+  return null;
+}
+
+async function promptForDbSafeReadProfile({ targetAlias, track }) {
+  const reader = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  console.log('sk setup (user) - DB safe-read 설정');
+  console.log(`  🎯 대상 alias: ${targetAlias}${track ? ` (track=${track})` : ''}`);
+  console.log('  기존 alias를 복사할 수 없어 host / port / user를 먼저 입력받습니다.');
+  console.log('  비밀번호는 이어지는 mysql_config_editor 프롬프트에서만 입력합니다.');
+
+  try {
+    const host = (await promptWithInterface(reader, 'DB host: ')).trim();
+    const port = (await promptWithInterface(reader, 'DB port [3306]: ')).trim();
+    const user = (await promptWithInterface(reader, 'DB user: ')).trim();
+
+    if (!host || !user) {
+      fail('DB safe-read 설정을 진행하려면 host와 user가 필요합니다.');
+    }
+
+    return {
+      host,
+      port: port || '3306',
+      user,
+      sourceAlias: null,
+    };
+  } finally {
+    reader.close();
+  }
+}
+
+async function ensureDbSafeReadConfig({
+  configure,
+  dryRun,
+  force,
+  verbose,
+  trackOverride,
+  contextCwd,
+}) {
+  if (!configure) {
+    return { configured: false, changed: false, message: '요청 없음' };
+  }
+
+  const track = trackOverride || inferTrackFromPath(contextCwd);
+  const targetAlias = dbTargetAlias(track);
+  const editor = detectExecutable('mysql_config_editor', MYSQL_CONFIG_EDITOR_CANDIDATES);
+  if (!editor) {
+    fail(`DB safe-read 설정을 진행하려면 mysql_config_editor가 필요합니다. ${mysqlClientRecoveryHint(track)}`);
+  }
+
+  const currentAliasesResult = spawnSync(editor.path, ['print', '--all'], { encoding: 'utf-8' });
+  if (currentAliasesResult.error) {
+    fail(`DB alias 목록을 읽지 못했습니다: ${currentAliasesResult.error.message}`);
+  }
+  if (currentAliasesResult.status !== 0) {
+    const stderr = typeof currentAliasesResult.stderr === 'string' ? currentAliasesResult.stderr.trim() : '';
+    fail(`DB alias 목록을 읽지 못했습니다.${stderr ? ` ${stderr}` : ''}`);
+  }
+
+  const profiles = parseMysqlConfigEditorOutput(currentAliasesResult.stdout);
+  if (profiles[targetAlias] && !force) {
+    return {
+      configured: true,
+      changed: false,
+      targetAlias,
+      track,
+      message: `${targetAlias} alias가 이미 있습니다.`,
+    };
+  }
+
+  let profileInput = chooseDbSourceProfile(profiles, targetAlias);
+  if (!profileInput && dryRun) {
+    return {
+      configured: false,
+      changed: false,
+      targetAlias,
+      track,
+      message: `${targetAlias} alias를 만들려면 host / port / user 입력이 필요합니다.`,
+    };
+  }
+
+  if (!profileInput) {
+    if (!(process.stdin.isTTY && process.stdout.isTTY)) {
+      fail('기존 DB alias를 복사할 수 없어서 입력이 필요합니다. TTY에서 "sk setup --configure-db-safe-read"를 다시 실행하세요.');
+    }
+    profileInput = await promptForDbSafeReadProfile({ targetAlias, track });
+  }
+
+  const host = profileInput.host;
+  const port = profileInput.port || '3306';
+  const user = profileInput.user;
+  const sourceAlias = profileInput.alias || profileInput.sourceAlias || null;
+
+  if (dryRun) {
+    return {
+      configured: false,
+      changed: false,
+      targetAlias,
+      track,
+      message: `${targetAlias} alias를 준비합니다. ${sourceAlias ? `${sourceAlias}의 host/user/port를 재사용` : 'host/user/port를 입력받아 사용'}`,
+    };
+  }
+
+  if (verbose) {
+    console.log(`  🗄️  DB alias 생성: ${targetAlias}${sourceAlias ? ` (기준=${sourceAlias})` : ''}`);
+  }
+
+  // 비밀번호는 mysql_config_editor 프롬프트에서만 입력해 user-local secret으로 유지한다.
+  runCommandOrFail(editor.path, [
+    'set',
+    `--login-path=${targetAlias}`,
+    `--host=${host}`,
+    `--port=${port}`,
+    `--user=${user}`,
+    '--password',
+  ]);
+
+  const mysql = detectExecutable('mysql', MYSQL_BIN_CANDIDATES);
+  if (!mysql) {
+    return {
+      configured: true,
+      changed: true,
+      targetAlias,
+      track,
+      message: `${targetAlias} alias를 만들었습니다. mysql PATH/fallback 확인은 다음 sk check에서 확인하세요.`,
+    };
+  }
+
+  const verifyResult = spawnSync(mysql.path, [
+    `--login-path=${targetAlias}`,
+    '--connect-timeout=5',
+    '-N',
+    '-B',
+    '-e',
+    'SELECT 1',
+  ], { encoding: 'utf-8' });
+
+  if (verifyResult.error || verifyResult.status !== 0) {
+    const stderr = typeof verifyResult.stderr === 'string' ? verifyResult.stderr.trim() : '';
+    return {
+      configured: true,
+      changed: true,
+      targetAlias,
+      track,
+      message: `${targetAlias} alias를 만들었지만 즉시 연결 검증은 실패했습니다.${stderr ? ` ${stderr}` : ''}`,
+    };
+  }
+
+  return {
+    configured: true,
+    changed: true,
+    targetAlias,
+    track,
+    message: `${targetAlias} alias를 만들고 SELECT 1 검증까지 통과했습니다.`,
+  };
+}
+
+function buildDbSafeReadChecks(cwd = process.cwd()) {
+  const mysql = detectExecutable('mysql', MYSQL_BIN_CANDIDATES);
+  const editor = detectExecutable('mysql_config_editor', MYSQL_CONFIG_EDITOR_CANDIDATES);
+  const checks = [];
+  const track = inferTrackFromPath(cwd);
+  const targetAlias = dbTargetAlias(track);
+
+  if (!mysql && !editor) {
+    checks.push(check('warn', 'DB client', `mysql, mysql_config_editor를 찾지 못했습니다. ${mysqlClientRecoveryHint(track)}`));
+  } else if (mysql?.source === 'path' && editor?.source === 'path') {
+    checks.push(check('pass', 'DB client', 'mysql, mysql_config_editor가 PATH에 있습니다.'));
+  } else if (mysql && editor) {
+    checks.push(check(
+      'pass',
+      'DB client',
+      `PATH 미노출이지만 fallback으로 사용 가능합니다. mysql=${mysql.path} | mysql_config_editor=${editor.path}`,
+    ));
+  } else {
+    const parts = [];
+    if (mysql) {
+      parts.push(mysql.source === 'path'
+        ? 'mysql=PATH'
+        : `mysql=fallback(${mysql.path})`);
+    } else {
+      parts.push('mysql=missing');
+    }
+    if (editor) {
+      parts.push(editor.source === 'path'
+        ? 'mysql_config_editor=PATH'
+        : `mysql_config_editor=fallback(${editor.path})`);
+    } else {
+      parts.push('mysql_config_editor=missing');
+    }
+    const missingDetail = !mysql
+      ? 'safe-read 실행에는 mysql이 필요합니다.'
+      : 'login-path alias setup에는 mysql_config_editor가 필요합니다.';
+    checks.push(check('warn', 'DB client', `${parts.join(' | ')}. ${missingDetail} ${mysqlClientRecoveryHint(track)}`));
+  }
+
+  const loginFile = join(homedir(), '.mylogin.cnf');
+  if (!editor) {
+    checks.push(check('warn', 'DB login-path', `mysql_config_editor를 찾지 못해 login-path alias를 확인할 수 없습니다. ${mysqlClientRecoveryHint(track)}`));
+    return checks;
+  }
+
+  if (!existsSync(loginFile)) {
+    checks.push(check('warn', 'DB login-path', `${loginFile} 파일이 없습니다. 먼저 "${dbSafeReadSetupCommand(track)}"로 login-path setup을 진행하세요.`));
+    return checks;
+  }
+
+  const result = spawnSync(editor.path, ['print', '--all'], { encoding: 'utf-8' });
+  if (result.error) {
+    checks.push(check('warn', 'DB login-path', `alias 확인 실패: ${result.error.message}`));
+    return checks;
+  }
+  if (result.status !== 0) {
+    const stderr = typeof result.stderr === 'string' ? result.stderr.trim() : '';
+    checks.push(check('warn', 'DB login-path', `alias 확인 실패(종료 코드 ${result.status})${stderr ? `: ${stderr}` : ''}`));
+    return checks;
+  }
+
+  const aliasNames = (typeof result.stdout === 'string' ? result.stdout : '')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith('[') && line.endsWith(']'))
+    .map((line) => line.slice(1, -1));
+
+  const trackAliases = aliasNames.filter((alias) => alias.startsWith('codex-db-'));
+  if (trackAliases.includes(targetAlias)) {
+    checks.push(check('pass', 'DB login-path', `track alias 확인: ${targetAlias}`));
+    return checks;
+  }
+
+  if (trackAliases.length > 0) {
+    checks.push(check('warn', 'DB login-path', `다른 track alias는 있지만 현재 track alias(${targetAlias})는 없습니다. 현재 프로젝트에서 "${dbSafeReadSetupCommand(track)}"로 맞출 수 있습니다.`));
+    return checks;
+  }
+
+  if (aliasNames.includes(LEGACY_DB_LOGIN_PATH)) {
+    checks.push(check('warn', 'DB login-path', `legacy alias만 확인: ${LEGACY_DB_LOGIN_PATH}. 현재 프로젝트에서 "${dbSafeReadSetupCommand(track)}"로 ${targetAlias} alias를 만들 수 있습니다.`));
+    return checks;
+  }
+
+  checks.push(check('warn', 'DB login-path', `사용 가능한 alias를 확인하지 못했습니다. 현재 alias=${summarizeAliases(aliasNames)}. 현재 프로젝트에서 "${dbSafeReadSetupCommand(track)}"를 실행하세요.`));
+  return checks;
+}
+
 function runCommandOrFail(command, args, options = {}) {
   const result = spawnSync(command, args, {
     stdio: 'inherit',
@@ -121,7 +529,7 @@ function ensureFullBootstrapHistory(repoDir, verbose) {
 
 function resolveLocalDispatcher(command) {
   if (process.env.SK_DISABLE_FORWARD === '1') return null;
-  if (command === 'setup' || command === 'setup-internal') return null;
+  if (command === 'setup-internal') return null;
   if (hasManagedSources(REPO_ROOT)) return null;
 
   const localScript = canonicalScriptPath();
@@ -219,7 +627,7 @@ function printUsage() {
       '  sk search "<query>"     로컬 Codex 세션 기록 검색',
       '',
       '📝 사용법',
-      '  sk setup [--dir <path>] [--repo <url>] [--dry-run] [--verbose] [--configure-notion] [--skip-notion]',
+      '  sk setup [--dir <path>] [--cwd <path>] [--repo <url>] [--dry-run] [--verbose] [--configure-notion] [--configure-db-safe-read] [--track <name>] [--skip-notion]',
       '  sk init [--cwd <path>] [--dry-run] [--force] [--verbose]',
       '  sk check [--cwd <path>] [--json]',
       '  sk status [--cwd <path>] [--json]',
@@ -233,6 +641,7 @@ function printUsage() {
       '  - 배포된 npm 패키지는 설치 진입점과 디스패처 역할만 합니다.',
       `  - setup은 수정 가능한 원본 저장소를 ${canonicalRepoRoot()} 경로에 준비합니다.`,
       '  - setup은 로컬 원본 저장소를 기준으로 config, rules, 공용 agent를 동기화하고 check까지 실행합니다.',
+      '  - setup에 --configure-db-safe-read를 붙이면 현재 프로젝트(track) 기준 DB login-path alias를 sk 안에서 맞출 수 있습니다.',
       '  - init은 현재 프로젝트 루트에 .sk 상태 파일만 준비합니다.',
       '  - setup은 ~/.codex/sk/notion/workspace.json 아래에 Notion 설정 파일도 만들 수 있습니다.',
       `  - 프로젝트 상태는 ${STATE_DIRNAME}/ 아래에 저장됩니다.`,
@@ -240,7 +649,7 @@ function printUsage() {
       `  - 공용 메모는 ${STATE_DIRNAME}/${NOTEPAD_FILE} 에 저장됩니다.`,
       '  - 다른 프로젝트를 대상으로 하려면 cd 대신 init/status/memory에 --cwd <path>를 사용할 수 있습니다.',
       '  - user 설정은 $CODEX_HOME 또는 ~/.codex를 대상으로 사용합니다.',
-      '  - Notion 기록이 Codex에서 실패하면 "codex mcp login notion"으로 MCP 인증을 다시 연결하세요.',
+      '  - Notion 기록이 invalid_grant/unauthorized/forbidden 같은 인증 오류로 실패하면 "codex mcp login notion"으로 MCP 인증을 다시 연결하세요.',
       `  - 자세한 가이드: ${guidePath}`,
     ].join('\n'),
   );
@@ -273,12 +682,12 @@ function parseFlags(args) {
       continue;
     }
 
-    if (token === '--json' || token === '--dry-run' || token === '--verbose' || token === '--case-sensitive' || token === '--force' || token === '--configure-notion' || token === '--skip-notion') {
+    if (token === '--json' || token === '--dry-run' || token === '--verbose' || token === '--case-sensitive' || token === '--force' || token === '--configure-notion' || token === '--configure-db' || token === '--configure-db-safe-read' || token === '--skip-notion') {
       flags.set(token.slice(2), true);
       continue;
     }
 
-    if (token === '--scope' || token === '--cwd' || token === '--dir' || token === '--repo' || token === '--limit' || token === '--since' || token === '--project' || token === '--context' || token === '--session' || token === '--category' || token === '--priority') {
+    if (token === '--scope' || token === '--cwd' || token === '--dir' || token === '--repo' || token === '--limit' || token === '--since' || token === '--project' || token === '--context' || token === '--session' || token === '--category' || token === '--priority' || token === '--track' || token === '--db-cwd') {
       const next = args[index + 1];
       if (!next || next.startsWith('-')) {
         fail(`${token} 뒤에 값이 필요합니다.`);
@@ -291,6 +700,10 @@ function parseFlags(args) {
     fail(`알 수 없는 옵션입니다: ${token}`);
   }
 
+  if (flags.get('configure-db-safe-read')) {
+    flags.set('configure-db', true);
+  }
+
   return { flags, rest };
 }
 
@@ -659,11 +1072,17 @@ async function writeScopeFile(scope, cwd, dryRun) {
 
 function buildInternalSetupArgs(flags, targetDir) {
   const args = ['setup-internal', '--scope', 'user', '--cwd', targetDir];
-  for (const name of ['dry-run', 'verbose', 'configure-notion', 'skip-notion']) {
+  for (const name of ['dry-run', 'verbose', 'configure-notion', 'configure-db', 'skip-notion']) {
     if (flags.get(name)) {
       args.push(`--${name}`);
     }
   }
+  if (flags.get('track')) {
+    args.push('--track', String(flags.get('track')));
+  }
+  if (flags.get('db-cwd')) {
+    args.push('--db-cwd', String(flags.get('db-cwd')));
+  }
   return args;
 }
 
@@ -927,7 +1346,11 @@ async function runSetup(flags) {
   const dryRun = Boolean(flags.get('dry-run'));
   const verbose = Boolean(flags.get('verbose'));
   const configureNotion = Boolean(flags.get('configure-notion'));
+  const configureDb = Boolean(flags.get('configure-db'));
   const skipNotion = Boolean(flags.get('skip-notion'));
+  const force = Boolean(flags.get('force'));
+  const dbContextCwd = resolve(String(flags.get('db-cwd') || requestedCwd));
+  const trackOverride = flags.get('track') ? String(flags.get('track')) : null;
   const sources = await validateSources();
   const target = targetPaths(scope, cwd);
   const mergedConfig = await buildMergedConfig();
@@ -984,6 +1407,14 @@ async function runSetup(flags) {
     configure: configureNotion,
     skipNotion,
   });
+  const dbSummary = await ensureDbSafeReadConfig({
+    configure: configureDb,
+    dryRun,
+    force,
+    verbose,
+    trackOverride,
+    contextCwd: dbContextCwd,
+  });
 
   const scopePath = await writeScopeFile(scope, cwd, dryRun);
   const stateSummary = await ensureProjectStateFiles({ cwd, dryRun, verbose });
@@ -996,6 +1427,9 @@ async function runSetup(flags) {
   console.log(`  📏 규칙 파일: ${target.rulesPath}`);
   console.log(`  🤖 에이전트: ${target.agentsDir}`);
   console.log(`  📝 Notion 설정: ${notionSummary.path}`);
+  if (configureDb) {
+    console.log(`  🗄️  DB safe-read: ${dbSummary.message}`);
+  }
   console.log(`  🗂️  상태 파일: ${scopePath}`);
   console.log(`  🧠 프로젝트 메모리: ${projectMemoryPath(cwd)}`);
   console.log(`  📒 메모장: ${notepadPath(cwd)}`);
@@ -1009,7 +1443,7 @@ async function runSetup(flags) {
   );
   if (notionSummary.configured) {
     console.log('  ✅ Notion 워크스페이스 설정이 준비되었습니다.');
-    console.log('  🔐 Codex에서 Notion 문서 기록이 실패하면 아래 명령으로 MCP 인증을 다시 연결하세요.');
+    console.log('  🔐 Codex에서 Notion 문서 기록이 invalid_grant/unauthorized/forbidden 같은 인증 오류로 실패하면 아래 명령으로 MCP 인증을 다시 연결하세요.');
     console.log('     codex mcp login notion');
   } else {
     console.log('  ⚠️  Notion 설정이 아직 완전하지 않습니다. 준비되면 "sk setup --configure-notion"을 다시 실행하세요.');
@@ -1017,6 +1451,7 @@ async function runSetup(flags) {
 }
 
 async function runSetupCommand(flags) {
+  const invocationCwd = resolveWorkingDirectory(flags);
   const targetDir = resolve(String(flags.get('dir') || canonicalRepoRoot()));
   const repoUrl = String(flags.get('repo') || DEFAULT_BOOTSTRAP_REPO);
   const verbose = Boolean(flags.get('verbose'));
@@ -1077,12 +1512,16 @@ async function runSetupCommand(flags) {
     SK_DISABLE_FORWARD: '1',
     SK_REPO_ROOT: targetDir,
   };
+  if (!flags.get('db-cwd')) {
+    flags.set('db-cwd', invocationCwd);
+  }
 
   console.log(`sk setup (${repoStatus === 'cloned' ? '새로 복제됨' : repoStatus === 'reused' ? '기존 저장소 재사용' : repoStatus === 'current-source' ? '현재 저장소 사용' : repoStatus})`);
   console.log(`  📁 기준 저장소: ${targetDir}`);
   console.log(`  🔗 원본: ${repoUrl}`);
   runCommandOrFail(process.execPath, [localScript, ...buildInternalSetupArgs(flags, targetDir)], { env: sharedEnv });
-  runCommandOrFail(process.execPath, [localScript, 'check', '--cwd', targetDir], { env: sharedEnv });
+  const verifyCwd = flags.get('configure-db') ? invocationCwd : targetDir;
+  runCommandOrFail(process.execPath, [localScript, 'check', '--cwd', verifyCwd], { env: sharedEnv });
 
   console.log('  ✅ 완료: setup이 끝났습니다.');
   if (!hasManagedSources(REPO_ROOT)) {
@@ -1208,6 +1647,8 @@ async function buildDoctorResult(cwd = process.cwd()) {
     ? check('pass', '메모장', notepadPath(cwd))
     : check('warn', '메모장', `${notepadPath(cwd)} 파일이 없습니다.`));
 
+  checks.push(...buildDbSafeReadChecks(cwd));
+
   if (!existsSync(target.notionConfigPath)) {
     checks.push(check('warn', 'Notion 설정', `${target.notionConfigPath} 파일이 없습니다. "sk setup --configure-notion"을 실행하세요.`));
   } else if (!notionConfig || !notionWorkspaceConfigured(notionConfig)) {
@@ -1297,7 +1738,7 @@ async function runStatus(flags) {
     console.log(`  ${icon} ${entry.name}: ${entry.message}`);
   }
   if (status.notion_config_exists && status.notion_configured) {
-    console.log('  💡 Notion 기록이 Codex에서 실패하면 "codex mcp login notion"으로 MCP 인증을 다시 연결하세요.');
+    console.log('  💡 Notion 기록이 invalid_grant/unauthorized/forbidden 같은 인증 오류로 실패하면 "codex mcp login notion"으로 MCP 인증을 다시 연결하세요.');
   }
   if (status.checks.some((entry) => entry.status === 'fail')) {
     process.exitCode = 1;