daiso 1.0.5 → 1.0.6

package/dist/api/lottemartHandlers.js

@@ -5,6 +5,15 @@ import { errorResponse, successResponse } from './response.js';
 import { fetchLotteMartStores, searchLotteMartProducts } from '../services/lottemart/client.js';
 import { DEFAULT_LOTTEMART_TIMEOUT_MS } from '../services/lottemart/config.js';
 import { probeLotteMartUpstream } from '../services/lottemart/debug.js';
+function parseLotteMartProductSource(value) {
+    if (!value || value === 'auto') {
+        return 'auto';
+    }
+    if (value === 'legacy' || value === 'zetta') {
+        return value;
+    }
+    return null;
+}
 /**
  * 롯데마트 매장 검색 API 핸들러
  * GET /api/lottemart/stores?keyword={키워드}&lat={위도}&lng={경도}
@@ -62,9 +71,15 @@ export async function handleLotteMartSearchProducts(c) {
     const storeCode = c.req.query('storeCode') || '';
     const storeName = c.req.query('storeName') || '';
     const pageLimit = parseInt(c.req.query('pageLimit') || '3', 10);
+    const parsedTimeoutMs = parseInt(c.req.query('timeoutMs') || String(DEFAULT_LOTTEMART_TIMEOUT_MS), 10);
+    const timeoutMs = Number.isFinite(parsedTimeoutMs) && parsedTimeoutMs > 0 ? parsedTimeoutMs : DEFAULT_LOTTEMART_TIMEOUT_MS;
+    const source = parseLotteMartProductSource(c.req.query('source'));
     if (keyword.trim().length === 0) {
         return errorResponse(c, 'MISSING_QUERY', '검색어(keyword)를 입력해주세요.');
     }
+    if (!source) {
+        return errorResponse(c, 'INVALID_LOTTEMART_SOURCE', 'source는 auto, legacy, zetta 중 하나여야 합니다.');
+    }
     if (storeCode.trim().length === 0 && storeName.trim().length === 0) {
         return errorResponse(c, 'MISSING_STORE', 'storeCode 또는 storeName 중 하나를 입력해주세요.');
     }
@@ -75,8 +90,9 @@ export async function handleLotteMartSearchProducts(c) {
             storeName,
             keyword,
             pageLimit,
+            source,
         }, {
-            timeout: DEFAULT_LOTTEMART_TIMEOUT_MS,
+            timeout: timeoutMs,
             zyteApiKey: c.env?.ZYTE_API_KEY,
         });
         return successResponse(c, {

package/dist/api/response.js

@@ -1,6 +1,7 @@
 /**
  * API 공통 응답 유틸리티
  */
+import { toStandardErrorDiagnostics } from '../core/errors.js';
 /**
  * 성공 응답 생성
  */
@@ -18,5 +19,6 @@ export function errorResponse(c, code, message, status = 400) {
     return c.json({
         success: false,
         error: { code, message },
+        diagnostics: toStandardErrorDiagnostics(code, message, { status }),
     }, status);
 }

package/dist/api/routes/healthRoutes.js

@@ -14,6 +14,15 @@ function readHealthCheckToken(headers) {
     }
     return (headers.get('x-health-check-key') || '').trim();
 }
+function parseMode(value) {
+    if (!value || value === 'quick') {
+        return 'quick';
+    }
+    if (value === 'deep' || value === 'full') {
+        return value;
+    }
+    return null;
+}
 export function registerHealthRoutes(app) {
     app.get('/api/health/checks', async (c) => {
         const secret = c.env?.HEALTH_CHECK_SECRET?.trim();
@@ -23,10 +32,16 @@ export function registerHealthRoutes(app) {
         if (readHealthCheckToken(c.req.raw.headers) !== secret) {
             return errorResponse(c, 'UNAUTHORIZED_HEALTH_CHECK', '유효한 헬스 체크 시크릿 키가 필요합니다.', 401);
         }
-        const mode = c.req.query('mode') === 'deep' ? 'deep' : 'quick';
+        const mode = parseMode(c.req.query('mode'));
+        if (!mode) {
+            return errorResponse(c, 'INVALID_HEALTH_CHECK_MODE', 'mode는 quick, deep, full 중 하나여야 합니다.', 400);
+        }
         const timeoutMs = Number.parseInt(c.req.query('timeoutMs') || '3000', 10);
-        const baseUrl = c.env?.HEALTH_CHECK_BASE_URL?.trim() || new URL(c.req.url).origin;
-        const fetchImpl = c.env?.HEALTH_CHECK_BASE_URL && c.env?.HEALTH_CHECK_TRANSPORT !== 'network'
+        const slowThresholdMs = Number.parseInt(c.req.query('slowThresholdMs') || c.env?.HEALTH_CHECK_SLOW_THRESHOLD_MS || '0', 10);
+        const baseUrl = c.req.query('baseUrl')?.trim() || c.env?.HEALTH_CHECK_BASE_URL?.trim() || new URL(c.req.url).origin;
+        const transport = c.req.query('transport') || c.env?.HEALTH_CHECK_TRANSPORT || 'internal';
+        const cacheBust = parseBoolean(c.req.query('cacheBust')) || transport === 'network';
+        const fetchImpl = c.env?.HEALTH_CHECK_BASE_URL && transport !== 'network'
             ? async (input, init) => app.fetch(new Request(input, init), c.env)
             : undefined;
         const result = await runHealthChecks({
@@ -35,8 +50,10 @@ export function registerHealthRoutes(app) {
             check: c.req.query('check') || undefined,
             mode,
             timeoutMs,
+            slowThresholdMs,
             includeSamples: parseBoolean(c.req.query('includeSamples')),
             fresh: parseBoolean(c.req.query('fresh')),
+            cacheBust,
             fetchImpl,
         });
         return c.json(result);

package/dist/cli/args.js

@@ -52,3 +52,24 @@ export function toQueryOptions(options) {
     }
     return queryOptions;
 }
+export function findUnknownOption(options, allowedOptions) {
+    const allowed = new Set(allowedOptions);
+    for (const key of Object.keys(options)) {
+        if (!allowed.has(key)) {
+            return key;
+        }
+    }
+    return null;
+}
+export function writeUnknownOptionError(options, allowedOptions, writeErr, hint) {
+    const unknownOption = findUnknownOption(options, allowedOptions);
+    if (!unknownOption) {
+        return false;
+    }
+    writeErr(`알 수 없는 옵션: --${unknownOption}`);
+    if (hint) {
+        writeErr(hint);
+    }
+    writeErr('도움말: daiso help');
+    return true;
+}

package/dist/cli/commandOptions.js

@@ -0,0 +1,38 @@
+/**
+ * CLI 명령별 허용 옵션 정의
+ */
+import { writeUnknownOptionError } from './args.js';
+export const COMMAND_OPTION_ALLOWLISTS = {
+    version: [],
+    url: [],
+    health: [],
+    claude: ['exec'],
+    products: ['help', 'json', 'page', 'pageSize'],
+    product: ['help', 'json'],
+    stores: ['help', 'json', 'keyword', 'sido', 'gugun', 'dong', 'limit'],
+    inventory: ['help', 'json', 'keyword', 'lat', 'lng', 'page', 'pageSize'],
+    'display-location': ['help', 'json'],
+    'cu-stores': ['help', 'json', 'keyword', 'lat', 'lng', 'limit'],
+    'cu-inventory': ['help', 'json', 'storeKeyword', 'lat', 'lng', 'size', 'offset', 'searchSort', 'storeLimit'],
+    'lottecinema-theaters': ['help', 'json', 'keyword', 'lat', 'lng', 'playDate', 'limit'],
+    'lottecinema-movies': ['help', 'json', 'keyword', 'playDate', 'theaterId', 'movieId', 'lat', 'lng'],
+    'lottecinema-seats': ['help', 'json', 'keyword', 'playDate', 'theaterId', 'movieId', 'lat', 'lng', 'limit'],
+    'emart24-stores': ['help', 'json', 'keyword', 'area1', 'area2', 'lat', 'lng', 'service24h', 'limit'],
+    'emart24-products': ['help', 'json', 'page', 'pageSize'],
+    'emart24-inventory': ['help', 'json', 'bizNoArr', 'storeKeyword', 'area1', 'area2', 'lat', 'lng', 'storeLimit'],
+    'lottemart-stores': ['help', 'json', 'keyword', 'area', 'brandVariant', 'lat', 'lng', 'limit'],
+    'lottemart-products': ['help', 'json', 'storeCode', 'storeName', 'area', 'brandVariant', 'pageLimit'],
+    'gs25-stores': ['help', 'json', 'keyword', 'lat', 'lng', 'serviceCode', 'limit'],
+    'gs25-products': ['help', 'json', 'serviceCode', 'limit'],
+    'gs25-inventory': ['help', 'json', 'storeKeyword', 'lat', 'lng', 'serviceCode', 'storeLimit'],
+    'seveneleven-products': ['help', 'json', 'page', 'size', 'sort'],
+    'seveneleven-stores': ['help', 'json', 'limit'],
+    'seveneleven-popwords': ['help', 'json', 'label'],
+    'seveneleven-catalog': ['help', 'json', 'includeIssues', 'includeExhibition', 'limit'],
+};
+const COMMAND_OPTION_HINTS = {
+    inventory: '매장명은 --keyword로 전달하세요. 예: daiso inventory 1034604 --keyword 강남역',
+};
+export function validateCommandOptions(command, options, writeErr) {
+    return writeUnknownOptionError(options, COMMAND_OPTION_ALLOWLISTS[command], writeErr, COMMAND_OPTION_HINTS[command]);
+}

package/dist/cli/commands/convenience.js

@@ -4,6 +4,7 @@
  */
 import { printCommandHelp } from '../../cliHelp.js';
 import { parseCliArgs, toUrl, applyOptionsToQuery, toQueryOptions } from '../args.js';
+import { validateCommandOptions } from '../commandOptions.js';
 import { requestAndPrintResponse } from '../http.js';
 export async function handleCuStores(options, deps) {
     const parsed = parseCliArgs(options);
@@ -14,6 +15,9 @@ export async function handleCuStores(options, deps) {
     if (keyword) {
         parsed.options.keyword = keyword;
     }
+    if (validateCommandOptions('cu-stores', parsed.options, deps.writeErr)) {
+        return 1;
+    }
     const targetUrl = toUrl('/api/cu/stores');
     applyOptionsToQuery(targetUrl, toQueryOptions(parsed.options));
     return await requestAndPrintResponse(deps.fetchImpl, deps.writeOut, deps.writeErr, targetUrl, 'cu-stores', parsed.options.json === 'true');
@@ -23,6 +27,9 @@ export async function handleCuInventory(options, deps) {
     if (parsed.options.help === 'true') {
         return printCommandHelp('cu-inventory', deps.writeOut, deps.writeErr);
     }
+    if (validateCommandOptions('cu-inventory', parsed.options, deps.writeErr)) {
+        return 1;
+    }
     const keyword = parsed.positionals[0];
     if (!keyword) {
         deps.writeErr('cu-inventory 명령은 검색어가 필요합니다. 예: daiso cu-inventory 과자');
@@ -42,6 +49,9 @@ export async function handleEmart24Stores(options, deps) {
     if (keyword) {
         parsed.options.keyword = keyword;
     }
+    if (validateCommandOptions('emart24-stores', parsed.options, deps.writeErr)) {
+        return 1;
+    }
     const targetUrl = toUrl('/api/emart24/stores');
     applyOptionsToQuery(targetUrl, toQueryOptions(parsed.options));
     return await requestAndPrintResponse(deps.fetchImpl, deps.writeOut, deps.writeErr, targetUrl, 'emart24-stores', parsed.options.json === 'true');
@@ -51,6 +61,9 @@ export async function handleEmart24Products(options, deps) {
     if (parsed.options.help === 'true') {
         return printCommandHelp('emart24-products', deps.writeOut, deps.writeErr);
     }
+    if (validateCommandOptions('emart24-products', parsed.options, deps.writeErr)) {
+        return 1;
+    }
     const keyword = parsed.positionals[0];
     if (!keyword) {
         deps.writeErr('emart24-products 명령은 검색어가 필요합니다. 예: daiso emart24-products 두바이');
@@ -66,6 +79,9 @@ export async function handleEmart24Inventory(options, deps) {
     if (parsed.options.help === 'true') {
         return printCommandHelp('emart24-inventory', deps.writeOut, deps.writeErr);
     }
+    if (validateCommandOptions('emart24-inventory', parsed.options, deps.writeErr)) {
+        return 1;
+    }
     const pluCd = parsed.positionals[0];
     const bizNoArr = parsed.options.bizNoArr;
     if (!pluCd || !bizNoArr) {
@@ -86,6 +102,9 @@ export async function handleLotteMartStores(options, deps) {
     if (keyword) {
         parsed.options.keyword = keyword;
     }
+    if (validateCommandOptions('lottemart-stores', parsed.options, deps.writeErr)) {
+        return 1;
+    }
     const targetUrl = toUrl('/api/lottemart/stores');
     applyOptionsToQuery(targetUrl, toQueryOptions(parsed.options));
     return await requestAndPrintResponse(deps.fetchImpl, deps.writeOut, deps.writeErr, targetUrl, 'lottemart-stores', parsed.options.json === 'true');
@@ -95,13 +114,16 @@ export async function handleLotteMartProducts(options, deps) {
     if (parsed.options.help === 'true') {
         return printCommandHelp('lottemart-products', deps.writeOut, deps.writeErr);
     }
+    if (validateCommandOptions('lottemart-products', parsed.options, deps.writeErr)) {
+        return 1;
+    }
     const keyword = parsed.positionals[0];
     if (!keyword) {
         deps.writeErr('lottemart-products 명령은 검색어가 필요합니다. 예: daiso lottemart-products 콜라 --storeName 강변점');
         return 1;
     }
     if (!parsed.options.storeCode && !parsed.options.storeName) {
-        deps.writeErr('lottemart-products 명령은 --storeCode 또는 --storeName이 필요합니다. 예: daiso lottemart-products 콜라 --storeName 강변점');
+        deps.writeErr('lottemart-products 명령은 --storeCode 또는 --storeName이 필요합니다. 매장을 모르면 먼저 daiso lottemart-stores 잠실 --area 서울 명령으로 storeName/storeCode를 확인하세요. 예: daiso lottemart-products 콜라 --storeName 강변점');
         return 1;
     }
     const targetUrl = toUrl('/api/lottemart/products');
@@ -118,6 +140,9 @@ export async function handleGs25Stores(options, deps) {
     if (keyword) {
         parsed.options.keyword = keyword;
     }
+    if (validateCommandOptions('gs25-stores', parsed.options, deps.writeErr)) {
+        return 1;
+    }
     const targetUrl = toUrl('/api/gs25/stores');
     applyOptionsToQuery(targetUrl, toQueryOptions(parsed.options));
     return await requestAndPrintResponse(deps.fetchImpl, deps.writeOut, deps.writeErr, targetUrl, 'gs25-stores', parsed.options.json === 'true');
@@ -127,6 +152,9 @@ export async function handleGs25Products(options, deps) {
     if (parsed.options.help === 'true') {
         return printCommandHelp('gs25-products', deps.writeOut, deps.writeErr);
     }
+    if (validateCommandOptions('gs25-products', parsed.options, deps.writeErr)) {
+        return 1;
+    }
     const keyword = parsed.positionals[0];
     if (!keyword) {
         deps.writeErr('gs25-products 명령은 검색어가 필요합니다. 예: daiso gs25-products 오감자');
@@ -142,6 +170,9 @@ export async function handleGs25Inventory(options, deps) {
     if (parsed.options.help === 'true') {
         return printCommandHelp('gs25-inventory', deps.writeOut, deps.writeErr);
     }
+    if (validateCommandOptions('gs25-inventory', parsed.options, deps.writeErr)) {
+        return 1;
+    }
     const keyword = parsed.positionals[0];
     if (!keyword) {
         deps.writeErr('gs25-inventory 명령은 검색어가 필요합니다. 예: daiso gs25-inventory 오감자');
@@ -157,6 +188,9 @@ export async function handleSevenElevenProducts(options, deps) {
     if (parsed.options.help === 'true') {
         return printCommandHelp('seveneleven-products', deps.writeOut, deps.writeErr);
     }
+    if (validateCommandOptions('seveneleven-products', parsed.options, deps.writeErr)) {
+        return 1;
+    }
     const query = parsed.positionals[0];
     if (!query) {
         deps.writeErr('seveneleven-products 명령은 검색어가 필요합니다. 예: daiso seveneleven-products 삼각김밥');
@@ -172,6 +206,9 @@ export async function handleSevenElevenStores(options, deps) {
     if (parsed.options.help === 'true') {
         return printCommandHelp('seveneleven-stores', deps.writeOut, deps.writeErr);
     }
+    if (validateCommandOptions('seveneleven-stores', parsed.options, deps.writeErr)) {
+        return 1;
+    }
     const keyword = parsed.positionals[0];
     if (!keyword) {
         deps.writeErr('seveneleven-stores 명령은 검색어가 필요합니다. 예: daiso seveneleven-stores 안산 중앙역');
@@ -187,6 +224,9 @@ export async function handleSevenElevenPopwords(options, deps) {
     if (parsed.options.help === 'true') {
         return printCommandHelp('seveneleven-popwords', deps.writeOut, deps.writeErr);
     }
+    if (validateCommandOptions('seveneleven-popwords', parsed.options, deps.writeErr)) {
+        return 1;
+    }
     const targetUrl = toUrl('/api/seveneleven/popwords');
     applyOptionsToQuery(targetUrl, toQueryOptions(parsed.options));
     return await requestAndPrintResponse(deps.fetchImpl, deps.writeOut, deps.writeErr, targetUrl, 'seveneleven-popwords', parsed.options.json === 'true');
@@ -196,6 +236,9 @@ export async function handleSevenElevenCatalog(options, deps) {
     if (parsed.options.help === 'true') {
         return printCommandHelp('seveneleven-catalog', deps.writeOut, deps.writeErr);
     }
+    if (validateCommandOptions('seveneleven-catalog', parsed.options, deps.writeErr)) {
+        return 1;
+    }
     const targetUrl = toUrl('/api/seveneleven/catalog');
     applyOptionsToQuery(targetUrl, toQueryOptions(parsed.options));
     return await requestAndPrintResponse(deps.fetchImpl, deps.writeOut, deps.writeErr, targetUrl, 'seveneleven-catalog', parsed.options.json === 'true');
@@ -209,6 +252,9 @@ export async function handleLottecinemaTheaters(options, deps) {
     if (keyword) {
         parsed.options.keyword = keyword;
     }
+    if (validateCommandOptions('lottecinema-theaters', parsed.options, deps.writeErr)) {
+        return 1;
+    }
     const targetUrl = toUrl('/api/lottecinema/theaters');
     applyOptionsToQuery(targetUrl, toQueryOptions(parsed.options));
     return await requestAndPrintResponse(deps.fetchImpl, deps.writeOut, deps.writeErr, targetUrl, 'lottecinema-theaters', parsed.options.json === 'true');
@@ -222,6 +268,9 @@ export async function handleLottecinemaMovies(options, deps) {
     if (keyword) {
         parsed.options.keyword = keyword;
     }
+    if (validateCommandOptions('lottecinema-movies', parsed.options, deps.writeErr)) {
+        return 1;
+    }
     const targetUrl = toUrl('/api/lottecinema/movies');
     applyOptionsToQuery(targetUrl, toQueryOptions(parsed.options));
     return await requestAndPrintResponse(deps.fetchImpl, deps.writeOut, deps.writeErr, targetUrl, 'lottecinema-movies', parsed.options.json === 'true');
@@ -235,6 +284,9 @@ export async function handleLottecinemaSeats(options, deps) {
     if (keyword) {
         parsed.options.keyword = keyword;
     }
+    if (validateCommandOptions('lottecinema-seats', parsed.options, deps.writeErr)) {
+        return 1;
+    }
     const targetUrl = toUrl('/api/lottecinema/seats');
     applyOptionsToQuery(targetUrl, toQueryOptions(parsed.options));
     return await requestAndPrintResponse(deps.fetchImpl, deps.writeOut, deps.writeErr, targetUrl, 'lottecinema-seats', parsed.options.json === 'true');

package/dist/cli/commands/daiso.js

@@ -3,6 +3,7 @@
  */
 import { printCommandHelp } from '../../cliHelp.js';
 import { parseCliArgs, toUrl, applyOptionsToQuery, toQueryOptions } from '../args.js';
+import { validateCommandOptions } from '../commandOptions.js';
 import { requestAndPrintResponse, requestAndPrintStoresWithKeywordFallback } from '../http.js';
 export async function handleGet(options, deps) {
     const parsed = parseCliArgs(options);
@@ -23,6 +24,9 @@ export async function handleProducts(options, deps) {
     if (parsed.options.help === 'true') {
         return printCommandHelp('products', deps.writeOut, deps.writeErr);
     }
+    if (validateCommandOptions('products', parsed.options, deps.writeErr)) {
+        return 1;
+    }
     const query = parsed.positionals[0];
     if (!query) {
         deps.writeErr('products 명령은 검색어가 필요합니다. 예: daiso products 수납박스');
@@ -38,6 +42,9 @@ export async function handleProduct(options, deps) {
     if (parsed.options.help === 'true') {
         return printCommandHelp('product', deps.writeOut, deps.writeErr);
     }
+    if (validateCommandOptions('product', parsed.options, deps.writeErr)) {
+        return 1;
+    }
     const productId = parsed.positionals[0];
     if (!productId) {
         deps.writeErr('product 명령은 제품 ID가 필요합니다. 예: daiso product 1034604');
@@ -56,6 +63,9 @@ export async function handleStores(options, deps) {
     if (keyword) {
         parsed.options.keyword = keyword;
     }
+    if (validateCommandOptions('stores', parsed.options, deps.writeErr)) {
+        return 1;
+    }
     if (!parsed.options.keyword && !parsed.options.sido) {
         deps.writeErr('stores 명령은 keyword 또는 --sido가 필요합니다. 예: daiso stores 강남역 / daiso stores --sido 서울');
         return 1;
@@ -67,9 +77,12 @@ export async function handleInventory(options, deps) {
     if (parsed.options.help === 'true') {
         return printCommandHelp('inventory', deps.writeOut, deps.writeErr);
     }
+    if (validateCommandOptions('inventory', parsed.options, deps.writeErr)) {
+        return 1;
+    }
     const productId = parsed.positionals[0];
     if (!productId) {
-        deps.writeErr('inventory 명령은 제품 ID가 필요합니다. 예: daiso inventory 1034604 --keyword 강남역');
+        deps.writeErr('inventory 명령은 제품 ID가 필요합니다. 제품명만 알면 먼저 daiso products 수납박스 명령으로 productId를 확인하세요. 예: daiso inventory 1034604 --keyword 강남역');
         return 1;
     }
     const targetUrl = toUrl('/api/daiso/inventory');
@@ -82,10 +95,13 @@ export async function handleDisplayLocation(options, deps) {
     if (parsed.options.help === 'true') {
         return printCommandHelp('display-location', deps.writeOut, deps.writeErr);
     }
+    if (validateCommandOptions('display-location', parsed.options, deps.writeErr)) {
+        return 1;
+    }
     const productId = parsed.positionals[0];
     const storeCode = parsed.positionals[1];
     if (!productId || !storeCode) {
-        deps.writeErr('display-location 명령은 productId와 storeCode가 필요합니다. 예: daiso display-location 1034604 04515');
+        deps.writeErr('display-location 명령은 productId와 storeCode가 필요합니다. storeCode를 모르면 먼저 daiso inventory 1034604 --keyword 매장명 결과의 storeInventory.stores[].storeCode를 확인하세요. 예: daiso display-location 1034604 04515');
         return 1;
     }
     const targetUrl = toUrl('/api/daiso/display-location');

package/dist/cli/http.js

@@ -4,6 +4,61 @@
 import { renderApiEnvelope } from '../cliRenderer.js';
 import { buildDaisoStoreKeywordVariants } from '../utils/daisoKeyword.js';
 import { applyOptionsToQuery, toUrl } from './args.js';
+function parseErrorCode(bodyText) {
+    try {
+        const parsed = JSON.parse(bodyText);
+        return typeof parsed.error?.code === 'string' ? parsed.error.code : '';
+    }
+    catch {
+        return '';
+    }
+}
+function buildCliHint(command, url, bodyText) {
+    if (command !== 'get') {
+        return [];
+    }
+    const code = parseErrorCode(bodyText);
+    if (url.pathname === '/api/daiso/inventory' || code === 'MISSING_PRODUCT_ID') {
+        return [
+            '힌트: 제품명만 알면 먼저 daiso products <상품명> 명령으로 productId를 확인하세요.',
+            '다음 명령 예시: daiso inventory <productId> --keyword 강남역',
+        ];
+    }
+    if (url.pathname === '/api/daiso/products') {
+        return ['힌트: 제품 검색은 daiso products <상품명> 명령을 사용할 수 있습니다.'];
+    }
+    if (url.pathname === '/api/daiso/display-location' || code === 'MISSING_STORE_CODE') {
+        return [
+            '힌트: storeCode는 daiso inventory <productId> --keyword <매장명> 결과에서 확인하세요.',
+            '다음 명령 예시: daiso display-location <productId> <storeCode>',
+        ];
+    }
+    if (url.pathname === '/api/lottemart/products') {
+        return [
+            '힌트: 롯데마트 상품 조회는 매장 정보가 필요합니다.',
+            '다음 명령 예시: daiso lottemart-products <상품명> --storeName <매장명>',
+        ];
+    }
+    if (url.pathname === '/api/gs25/inventory') {
+        return [
+            '힌트: GS25 상품명만 알면 daiso gs25-inventory <상품명> --storeKeyword <매장명> 명령을 사용하세요.',
+            'itemCode만 알면 daiso gs25-inventory <itemCode> 형식 대신 daiso get /api/gs25/inventory --itemCode <itemCode> --storeKeyword <매장명> 을 사용하세요.',
+        ];
+    }
+    if (url.pathname === '/api/emart24/inventory') {
+        return [
+            '힌트: 이마트24 상품명만 알면 daiso emart24-products <상품명> 명령으로 pluCd를 확인하세요.',
+            '다음 명령 예시: daiso emart24-inventory <pluCd> --storeKeyword 강남',
+        ];
+    }
+    if (url.pathname === '/api/seveneleven/inventory') {
+        return [
+            '힌트: 세븐일레븐 재고는 매장 키워드가 필요합니다.',
+            '다음 명령 예시: daiso get /api/seveneleven/inventory --keyword <상품명> --storeKeyword 강남',
+        ];
+    }
+    return [];
+}
 export async function requestAndPrintResponse(fetchImpl, writeOut, writeErr, url, command, asJson) {
     try {
         const response = await fetchImpl(url.toString());
@@ -12,6 +67,9 @@ export async function requestAndPrintResponse(fetchImpl, writeOut, writeErr, url
             writeErr(`요청 실패: HTTP ${response.status}`);
             if (bodyText) {
                 writeErr(bodyText);
+                for (const hint of buildCliHint(command, url, bodyText)) {
+                    writeErr(hint);
+                }
             }
             return 1;
         }

package/dist/cli/interactiveItemSearch.js

@@ -93,8 +93,10 @@ export async function runLotteCinemaSearch(deps, prompt, theater) {
         deps.writeOut(`  ...외 ${seats.length - 15}건`);
     }
 }
-export async function runDaisoItemSearch(deps, prompt, store) {
-    const keyword = await askNonEmpty(prompt, '찾을 상품 키워드를 입력하세요: ');
+export async function runDaisoItemSearch(deps, prompt, store, initialKeyword) {
+    const keyword = initialKeyword && initialKeyword.trim().length > 0
+        ? initialKeyword.trim()
+        : await askNonEmpty(prompt, '찾을 상품 키워드를 입력하세요: ');
     const productsPayload = await fetchEnvelope(deps.fetchImpl, '/api/daiso/products', {
         q: keyword,
         pageSize: '10',

package/dist/cli/interactivePrompt.js

@@ -1,11 +1,12 @@
 /**
  * 인터랙티브 CLI 입력/출력 헬퍼
  */
-export async function askMenu(prompt, title, options) {
+export async function askMenu(prompt, title, options, writeOut) {
     while (true) {
         const answer = await prompt.ask(`${title} `);
         const picked = Number.parseInt(answer, 10);
         if (Number.isNaN(picked) || picked < 0 || picked > options.length) {
+            writeOut?.(`번호로 입력하세요. 0부터 ${options.length} 사이에서 선택할 수 있습니다.`);
             continue;
         }
         return picked;
@@ -36,7 +37,7 @@ export async function askNextAction(prompt, writeOut) {
     writeOut('1. 같은 매장에서 다른 상품 찾기');
     writeOut('2. 다른 매장/서비스 다시 선택하기');
     writeOut('3. 종료하기');
-    const choice = await askMenu(prompt, '번호를 선택하세요:', ['same-store', 'change-store', 'exit']);
+    const choice = await askMenu(prompt, '번호를 선택하세요:', ['same-store', 'change-store', 'exit'], writeOut);
     return choice === 1 ? 'same-store' : choice === 2 ? 'change-store' : 'exit';
 }
 export function printStoreDetail(writeOut, store) {

package/dist/cli.js

@@ -9,8 +9,14 @@ import { fileURLToPath } from 'node:url';
 import { printHelp, printCommandHelp } from './cliHelp.js';
 import { createDefaultDeps } from './cli/deps.js';
 import { DEFAULT_BASE_URL, DEFAULT_MCP_URL } from './cli/constants.js';
+import { parseCliArgs } from './cli/args.js';
+import { validateCommandOptions } from './cli/commandOptions.js';
 import { handleGet, handleProducts, handleProduct, handleStores, handleInventory, handleDisplayLocation, } from './cli/commands/daiso.js';
 import { handleCuStores, handleCuInventory, handleEmart24Stores, handleEmart24Products, handleEmart24Inventory, handleLotteMartStores, handleLotteMartProducts, handleGs25Stores, handleGs25Products, handleGs25Inventory, handleSevenElevenProducts, handleSevenElevenStores, handleSevenElevenPopwords, handleSevenElevenCatalog, handleLottecinemaTheaters, handleLottecinemaMovies, handleLottecinemaSeats, } from './cli/commands/convenience.js';
+function rejectTopLevelUnknownOptions(options, command, deps) {
+    const parsed = parseCliArgs(options);
+    return validateCommandOptions(command, parsed.options, deps.writeErr);
+}
 export async function runCli(argv, deps) {
     const resolvedDeps = {
         ...createDefaultDeps(),
@@ -39,14 +45,23 @@ export async function runCli(argv, deps) {
         return 0;
     }
     if (command === 'version' || command === '--version' || command === '-v') {
+        if (rejectTopLevelUnknownOptions(options, 'version', resolvedDeps)) {
+            return 1;
+        }
         resolvedDeps.writeOut(resolvedDeps.getVersion());
         return 0;
     }
     if (command === 'url') {
+        if (rejectTopLevelUnknownOptions(options, 'url', resolvedDeps)) {
+            return 1;
+        }
         resolvedDeps.writeOut(DEFAULT_MCP_URL);
         return 0;
     }
     if (command === 'health') {
+        if (rejectTopLevelUnknownOptions(options, 'health', resolvedDeps)) {
+            return 1;
+        }
         try {
             const response = await resolvedDeps.fetchImpl(`${DEFAULT_BASE_URL}/health`);
             if (!response.ok) {
@@ -68,6 +83,9 @@ export async function runCli(argv, deps) {
         }
     }
     if (command === 'claude') {
+        if (rejectTopLevelUnknownOptions(options, 'claude', resolvedDeps)) {
+            return 1;
+        }
         const cliArgs = ['mcp', 'add', 'daiso', DEFAULT_BASE_URL, '--transport', 'sse'];
         if (options.includes('--exec')) {
             try {
@@ -129,6 +147,10 @@ export async function runCli(argv, deps) {
     if (command === 'seveneleven-catalog')
         return await handleSevenElevenCatalog(options, resolvedDeps);
     resolvedDeps.writeErr(`알 수 없는 명령어: ${command}`);
+    if (command === 'search') {
+        const query = options[0] ?? '<검색어>';
+        resolvedDeps.writeErr(`혹시 찾으신 명령: daiso products ${query}`);
+    }
     resolvedDeps.writeErr('도움말: daiso help');
     return 1;
 }

package/dist/cliHelp.js

@@ -323,6 +323,12 @@ export function printHelp(writeOut) {
     writeOut('  npx daiso seveneleven-catalog --limit 10');
     writeOut('  npx daiso get /api/cgv/movies --playDate 20260307 --theaterCode 0056');
     writeOut('');
+    writeOut('정보가 부족할 때:');
+    writeOut('  제품명을 먼저 검색해 productId를 확인: npx daiso products 수납박스');
+    writeOut('  productId로 재고 확인: npx daiso inventory <productId> --keyword 강남역');
+    writeOut('  매장을 먼저 검색해 storeName 또는 storeCode를 확인: npx daiso stores 강남역');
+    writeOut('  롯데마트 매장 확인: npx daiso lottemart-stores 잠실 --area 서울');
+    writeOut('');
     writeOut('상세 도움말:');
     writeOut('  npx daiso help <command>');
 }