@reftrixmcp/mcp-server 0.1.7

package/dist/utils/mcp-response.d.ts

@@ -0,0 +1,317 @@
+/**
+ * MCP統一レスポンス形式
+ *
+ * 全MCPツールで使用する統一レスポンス形式を定義
+ * 成功/エラーを同じ構造で表現し、クライアント側の処理を簡素化
+ *
+ * 設計原則:
+ * - 成功/エラーを success フィールドで明示的に区別
+ * - 軽量化モード情報を metadata で統一表現
+ * - エラー情報は error オブジェクトに集約
+ * - 型安全性を確保（TypeScript discriminated union）
+ *
+ * @see SEC監査: 機密情報漏洩防止のため details は開発環境のみ
+ */
+import { z } from "zod";
+import type { ErrorCode } from "./errors";
+/**
+ * 最適化モード
+ * - full: 全フィールド返却
+ * - summary: 軽量化（主要フィールドのみ）
+ * - compact: 最小限（ID等のみ）
+ * - truncated: 切り詰め（サイズ制限適用）
+ */
+export type OptimizationMode = "full" | "summary" | "compact" | "truncated";
+/**
+ * メタデータ（全レスポンス共通）
+ */
+export interface McpResponseMetadata {
+    /** リクエストID（ログ/メトリクス相関用） */
+    request_id?: string;
+    /** 処理時間（ミリ秒） */
+    processing_time_ms?: number;
+    /** 適用された最適化モード */
+    optimization_mode?: OptimizationMode;
+    /** 切り詰めが適用されたか */
+    truncated?: boolean;
+    /** 元のサイズ（切り詰め時） */
+    original_size?: number;
+    /** 総件数（ページネーション時） */
+    total_count?: number;
+    /** オフセット（ページネーション時） */
+    offset?: number;
+    /** リミット（ページネーション時） */
+    limit?: number;
+}
+/**
+ * エラー情報
+ */
+export interface McpErrorInfo {
+    /** エラーコード */
+    code: string;
+    /** エラーメッセージ */
+    message: string;
+    /** 詳細情報（開発環境のみ） */
+    details?: unknown;
+}
+/**
+ * 成功レスポンス
+ */
+export interface McpSuccessResponse<T> {
+    success: true;
+    data: T;
+    metadata?: McpResponseMetadata;
+}
+/**
+ * エラーレスポンス
+ */
+export interface McpErrorResponse {
+    success: false;
+    error: McpErrorInfo;
+    metadata?: McpResponseMetadata;
+}
+/**
+ * 統一レスポンス型（discriminated union）
+ */
+export type McpResponse<T> = McpSuccessResponse<T> | McpErrorResponse;
+/**
+ * 最適化モードスキーマ
+ */
+export declare const optimizationModeSchema: z.ZodEnum<["full", "summary", "compact", "truncated"]>;
+/**
+ * メタデータスキーマ
+ */
+export declare const mcpResponseMetadataSchema: z.ZodObject<{
+    request_id: z.ZodOptional<z.ZodString>;
+    processing_time_ms: z.ZodOptional<z.ZodNumber>;
+    optimization_mode: z.ZodOptional<z.ZodEnum<["full", "summary", "compact", "truncated"]>>;
+    truncated: z.ZodOptional<z.ZodBoolean>;
+    original_size: z.ZodOptional<z.ZodNumber>;
+    total_count: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    limit?: number | undefined;
+    truncated?: boolean | undefined;
+    request_id?: string | undefined;
+    processing_time_ms?: number | undefined;
+    optimization_mode?: "summary" | "full" | "compact" | "truncated" | undefined;
+    original_size?: number | undefined;
+    total_count?: number | undefined;
+    offset?: number | undefined;
+}, {
+    limit?: number | undefined;
+    truncated?: boolean | undefined;
+    request_id?: string | undefined;
+    processing_time_ms?: number | undefined;
+    optimization_mode?: "summary" | "full" | "compact" | "truncated" | undefined;
+    original_size?: number | undefined;
+    total_count?: number | undefined;
+    offset?: number | undefined;
+}>;
+/**
+ * エラー情報スキーマ
+ */
+export declare const mcpErrorInfoSchema: z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodString;
+    details: z.ZodOptional<z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    message: string;
+    details?: unknown;
+}, {
+    code: string;
+    message: string;
+    details?: unknown;
+}>;
+/**
+ * 成功レスポンススキーマファクトリ
+ * @param dataSchema - データ部分のスキーマ
+ */
+export declare function createSuccessResponseSchema<T extends z.ZodTypeAny>(dataSchema: T): z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    data: T;
+    metadata: z.ZodOptional<typeof mcpResponseMetadataSchema>;
+}>;
+/**
+ * エラーレスポンススキーマ
+ */
+export declare const mcpErrorResponseSchema: z.ZodObject<{
+    success: z.ZodLiteral<false>;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        details: z.ZodOptional<z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        code: string;
+        message: string;
+        details?: unknown;
+    }, {
+        code: string;
+        message: string;
+        details?: unknown;
+    }>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        request_id: z.ZodOptional<z.ZodString>;
+        processing_time_ms: z.ZodOptional<z.ZodNumber>;
+        optimization_mode: z.ZodOptional<z.ZodEnum<["full", "summary", "compact", "truncated"]>>;
+        truncated: z.ZodOptional<z.ZodBoolean>;
+        original_size: z.ZodOptional<z.ZodNumber>;
+        total_count: z.ZodOptional<z.ZodNumber>;
+        offset: z.ZodOptional<z.ZodNumber>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        limit?: number | undefined;
+        truncated?: boolean | undefined;
+        request_id?: string | undefined;
+        processing_time_ms?: number | undefined;
+        optimization_mode?: "summary" | "full" | "compact" | "truncated" | undefined;
+        original_size?: number | undefined;
+        total_count?: number | undefined;
+        offset?: number | undefined;
+    }, {
+        limit?: number | undefined;
+        truncated?: boolean | undefined;
+        request_id?: string | undefined;
+        processing_time_ms?: number | undefined;
+        optimization_mode?: "summary" | "full" | "compact" | "truncated" | undefined;
+        original_size?: number | undefined;
+        total_count?: number | undefined;
+        offset?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+    success: false;
+    metadata?: {
+        limit?: number | undefined;
+        truncated?: boolean | undefined;
+        request_id?: string | undefined;
+        processing_time_ms?: number | undefined;
+        optimization_mode?: "summary" | "full" | "compact" | "truncated" | undefined;
+        original_size?: number | undefined;
+        total_count?: number | undefined;
+        offset?: number | undefined;
+    } | undefined;
+}, {
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+    success: false;
+    metadata?: {
+        limit?: number | undefined;
+        truncated?: boolean | undefined;
+        request_id?: string | undefined;
+        processing_time_ms?: number | undefined;
+        optimization_mode?: "summary" | "full" | "compact" | "truncated" | undefined;
+        original_size?: number | undefined;
+        total_count?: number | undefined;
+        offset?: number | undefined;
+    } | undefined;
+}>;
+/**
+ * 統一レスポンススキーマファクトリ
+ * @param dataSchema - 成功時のデータスキーマ
+ */
+export declare function createMcpResponseSchema<T extends z.ZodTypeAny>(dataSchema: T): z.ZodUnion<[
+    z.ZodObject<{
+        success: z.ZodLiteral<true>;
+        data: T;
+        metadata: z.ZodOptional<typeof mcpResponseMetadataSchema>;
+    }>,
+    typeof mcpErrorResponseSchema
+]>;
+/**
+ * 成功レスポンスを作成
+ * @param data - レスポンスデータ
+ * @param metadata - オプションのメタデータ
+ */
+export declare function createSuccessResponse<T>(data: T, metadata?: McpResponseMetadata): McpSuccessResponse<T>;
+/**
+ * エラーレスポンスを作成
+ * @param code - エラーコード
+ * @param message - エラーメッセージ
+ * @param details - 詳細情報（開発環境のみ含める）
+ * @param metadata - オプションのメタデータ
+ */
+export declare function createErrorResponse(code: string | ErrorCode, message: string, details?: unknown, metadata?: McpResponseMetadata): McpErrorResponse;
+/**
+ * レスポンスが成功かどうかを判定（型ガード）
+ */
+export declare function isSuccessResponse<T>(response: McpResponse<T>): response is McpSuccessResponse<T>;
+/**
+ * レスポンスがエラーかどうかを判定（型ガード）
+ */
+export declare function isErrorResponse<T>(response: McpResponse<T>): response is McpErrorResponse;
+/**
+ * 処理時間を計測してメタデータに追加
+ * @param startTime - 開始時刻（performance.now()）
+ * @param existingMetadata - 既存のメタデータ
+ */
+export declare function withProcessingTime(startTime: number, existingMetadata?: McpResponseMetadata): McpResponseMetadata;
+/**
+ * ページネーション情報をメタデータに追加
+ * @param totalCount - 総件数
+ * @param offset - オフセット
+ * @param limit - リミット
+ * @param existingMetadata - 既存のメタデータ
+ */
+export declare function withPagination(totalCount: number, offset: number, limit: number, existingMetadata?: McpResponseMetadata): McpResponseMetadata;
+/**
+ * 最適化モードをメタデータに追加
+ * @param mode - 最適化モード
+ * @param existingMetadata - 既存のメタデータ
+ */
+export declare function withOptimizationMode(mode: OptimizationMode, existingMetadata?: McpResponseMetadata): McpResponseMetadata;
+/**
+ * 切り詰め情報をメタデータに追加
+ * @param originalSize - 元のサイズ
+ * @param existingMetadata - 既存のメタデータ
+ */
+export declare function withTruncation(originalSize: number, existingMetadata?: McpResponseMetadata): McpResponseMetadata;
+/**
+ * 一意のリクエストIDを生成（UUIDv7形式）
+ *
+ * 形式: UUIDv7（時間順序付きUUID）
+ * 例: 01932a6e-8b7c-7d8e-9f0a-1b2c3d4e5f6a
+ *
+ * 用途:
+ * - ログ/メトリクスとの相関
+ * - エラートレーシング
+ * - クライアント側での追跡
+ *
+ * セキュリティ:
+ * - UUIDv7は暗号学的に安全なランダム成分を持つ
+ * - 予測不可能（SEC要件準拠）
+ * - RESP-14 (L-02): フォールバック処理でエラー耐性を確保
+ */
+export declare function generateRequestId(): string;
+/**
+ * リクエストIDをメタデータに追加
+ * @param requestId - リクエストID（省略時は自動生成）
+ * @param existingMetadata - 既存のメタデータ
+ */
+export declare function withRequestId(requestId?: string, existingMetadata?: McpResponseMetadata): McpResponseMetadata;
+/**
+ * 成功レスポンスを作成（requestId付き）
+ * @param data - レスポンスデータ
+ * @param requestId - リクエストID（省略時は自動生成）
+ * @param metadata - 追加のメタデータ
+ */
+export declare function createSuccessResponseWithRequestId<T>(data: T, requestId?: string, metadata?: Omit<McpResponseMetadata, "request_id">): McpSuccessResponse<T>;
+/**
+ * エラーレスポンスを作成（requestId付き）
+ * @param code - エラーコード
+ * @param message - エラーメッセージ
+ * @param requestId - リクエストID（省略時は自動生成）
+ * @param details - 詳細情報（開発環境のみ含める）
+ * @param metadata - 追加のメタデータ
+ */
+export declare function createErrorResponseWithRequestId(code: string | ErrorCode, message: string, requestId?: string, details?: unknown, metadata?: Omit<McpResponseMetadata, "request_id">): McpErrorResponse;
+//# sourceMappingURL=mcp-response.d.ts.map

package/dist/utils/mcp-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-response.d.ts","sourceRoot":"","sources":["../../src/utils/mcp-response.ts"],"names":[],"mappings":"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"}

package/dist/utils/mcp-response.js

@@ -0,0 +1,270 @@
+"use strict";
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mcpErrorResponseSchema = exports.mcpErrorInfoSchema = exports.mcpResponseMetadataSchema = exports.optimizationModeSchema = void 0;
+exports.createSuccessResponseSchema = createSuccessResponseSchema;
+exports.createMcpResponseSchema = createMcpResponseSchema;
+exports.createSuccessResponse = createSuccessResponse;
+exports.createErrorResponse = createErrorResponse;
+exports.isSuccessResponse = isSuccessResponse;
+exports.isErrorResponse = isErrorResponse;
+exports.withProcessingTime = withProcessingTime;
+exports.withPagination = withPagination;
+exports.withOptimizationMode = withOptimizationMode;
+exports.withTruncation = withTruncation;
+exports.generateRequestId = generateRequestId;
+exports.withRequestId = withRequestId;
+exports.createSuccessResponseWithRequestId = createSuccessResponseWithRequestId;
+exports.createErrorResponseWithRequestId = createErrorResponseWithRequestId;
+/**
+ * MCP統一レスポンス形式
+ *
+ * 全MCPツールで使用する統一レスポンス形式を定義
+ * 成功/エラーを同じ構造で表現し、クライアント側の処理を簡素化
+ *
+ * 設計原則:
+ * - 成功/エラーを success フィールドで明示的に区別
+ * - 軽量化モード情報を metadata で統一表現
+ * - エラー情報は error オブジェクトに集約
+ * - 型安全性を確保（TypeScript discriminated union）
+ *
+ * @see SEC監査: 機密情報漏洩防止のため details は開発環境のみ
+ */
+const zod_1 = require("zod");
+const uuid_1 = require("uuid");
+const logger_1 = require("./logger");
+// =============================================================================
+// Zodスキーマ
+// =============================================================================
+/**
+ * 最適化モードスキーマ
+ */
+exports.optimizationModeSchema = zod_1.z.enum(["full", "summary", "compact", "truncated"]);
+/**
+ * メタデータスキーマ
+ */
+exports.mcpResponseMetadataSchema = zod_1.z.object({
+    request_id: zod_1.z.string().optional(),
+    processing_time_ms: zod_1.z.number().optional(),
+    optimization_mode: exports.optimizationModeSchema.optional(),
+    truncated: zod_1.z.boolean().optional(),
+    original_size: zod_1.z.number().optional(),
+    total_count: zod_1.z.number().optional(),
+    offset: zod_1.z.number().optional(),
+    limit: zod_1.z.number().optional(),
+});
+/**
+ * エラー情報スキーマ
+ */
+exports.mcpErrorInfoSchema = zod_1.z.object({
+    code: zod_1.z.string(),
+    message: zod_1.z.string(),
+    details: zod_1.z.unknown().optional(),
+});
+/**
+ * 成功レスポンススキーマファクトリ
+ * @param dataSchema - データ部分のスキーマ
+ */
+function createSuccessResponseSchema(dataSchema) {
+    return zod_1.z.object({
+        success: zod_1.z.literal(true),
+        data: dataSchema,
+        metadata: exports.mcpResponseMetadataSchema.optional(),
+    });
+}
+/**
+ * エラーレスポンススキーマ
+ */
+exports.mcpErrorResponseSchema = zod_1.z.object({
+    success: zod_1.z.literal(false),
+    error: exports.mcpErrorInfoSchema,
+    metadata: exports.mcpResponseMetadataSchema.optional(),
+});
+/**
+ * 統一レスポンススキーマファクトリ
+ * @param dataSchema - 成功時のデータスキーマ
+ */
+function createMcpResponseSchema(dataSchema) {
+    return zod_1.z.union([createSuccessResponseSchema(dataSchema), exports.mcpErrorResponseSchema]);
+}
+// =============================================================================
+// ヘルパー関数
+// =============================================================================
+/**
+ * 成功レスポンスを作成
+ * @param data - レスポンスデータ
+ * @param metadata - オプションのメタデータ
+ */
+function createSuccessResponse(data, metadata) {
+    return {
+        success: true,
+        data,
+        ...(metadata && { metadata }),
+    };
+}
+/**
+ * エラーレスポンスを作成
+ * @param code - エラーコード
+ * @param message - エラーメッセージ
+ * @param details - 詳細情報（開発環境のみ含める）
+ * @param metadata - オプションのメタデータ
+ */
+function createErrorResponse(code, message, details, metadata) {
+    return {
+        success: false,
+        error: {
+            code: String(code),
+            message,
+            // SEC: 詳細情報は開発環境のみ
+            ...((0, logger_1.isDevelopment)() && details !== undefined && { details }),
+        },
+        ...(metadata && { metadata }),
+    };
+}
+/**
+ * レスポンスが成功かどうかを判定（型ガード）
+ */
+function isSuccessResponse(response) {
+    return response.success === true;
+}
+/**
+ * レスポンスがエラーかどうかを判定（型ガード）
+ */
+function isErrorResponse(response) {
+    return response.success === false;
+}
+/**
+ * 処理時間を計測してメタデータに追加
+ * @param startTime - 開始時刻（performance.now()）
+ * @param existingMetadata - 既存のメタデータ
+ */
+function withProcessingTime(startTime, existingMetadata) {
+    return {
+        ...existingMetadata,
+        processing_time_ms: performance.now() - startTime,
+    };
+}
+/**
+ * ページネーション情報をメタデータに追加
+ * @param totalCount - 総件数
+ * @param offset - オフセット
+ * @param limit - リミット
+ * @param existingMetadata - 既存のメタデータ
+ */
+function withPagination(totalCount, offset, limit, existingMetadata) {
+    return {
+        ...existingMetadata,
+        total_count: totalCount,
+        offset,
+        limit,
+    };
+}
+/**
+ * 最適化モードをメタデータに追加
+ * @param mode - 最適化モード
+ * @param existingMetadata - 既存のメタデータ
+ */
+function withOptimizationMode(mode, existingMetadata) {
+    return {
+        ...existingMetadata,
+        optimization_mode: mode,
+    };
+}
+/**
+ * 切り詰め情報をメタデータに追加
+ * @param originalSize - 元のサイズ
+ * @param existingMetadata - 既存のメタデータ
+ */
+function withTruncation(originalSize, existingMetadata) {
+    return {
+        ...existingMetadata,
+        truncated: true,
+        original_size: originalSize,
+        optimization_mode: "truncated",
+    };
+}
+// =============================================================================
+// リクエストID生成
+// =============================================================================
+/**
+ * 一意のリクエストIDを生成（UUIDv7形式）
+ *
+ * 形式: UUIDv7（時間順序付きUUID）
+ * 例: 01932a6e-8b7c-7d8e-9f0a-1b2c3d4e5f6a
+ *
+ * 用途:
+ * - ログ/メトリクスとの相関
+ * - エラートレーシング
+ * - クライアント側での追跡
+ *
+ * セキュリティ:
+ * - UUIDv7は暗号学的に安全なランダム成分を持つ
+ * - 予測不可能（SEC要件準拠）
+ * - RESP-14 (L-02): フォールバック処理でエラー耐性を確保
+ */
+function generateRequestId() {
+    try {
+        return (0, uuid_1.v7)();
+    }
+    catch {
+        // SEC: フォールバック - crypto.randomUUID()を使用
+        // UUIDv7生成に失敗した場合の耐障害性確保
+        if (typeof crypto !== "undefined" && crypto.randomUUID) {
+            return crypto.randomUUID();
+        }
+        // 最終フォールバック: タイムスタンプ + ランダム文字列
+        return `fallback-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+    }
+}
+/**
+ * リクエストIDをメタデータに追加
+ * @param requestId - リクエストID（省略時は自動生成）
+ * @param existingMetadata - 既存のメタデータ
+ */
+function withRequestId(requestId, existingMetadata) {
+    return {
+        ...existingMetadata,
+        request_id: requestId ?? generateRequestId(),
+    };
+}
+/**
+ * 成功レスポンスを作成（requestId付き）
+ * @param data - レスポンスデータ
+ * @param requestId - リクエストID（省略時は自動生成）
+ * @param metadata - 追加のメタデータ
+ */
+function createSuccessResponseWithRequestId(data, requestId, metadata) {
+    return {
+        success: true,
+        data,
+        metadata: {
+            request_id: requestId ?? generateRequestId(),
+            ...metadata,
+        },
+    };
+}
+/**
+ * エラーレスポンスを作成（requestId付き）
+ * @param code - エラーコード
+ * @param message - エラーメッセージ
+ * @param requestId - リクエストID（省略時は自動生成）
+ * @param details - 詳細情報（開発環境のみ含める）
+ * @param metadata - 追加のメタデータ
+ */
+function createErrorResponseWithRequestId(code, message, requestId, details, metadata) {
+    return {
+        success: false,
+        error: {
+            code: String(code),
+            message,
+            // SEC: 詳細情報は開発環境のみ
+            ...((0, logger_1.isDevelopment)() && details !== undefined && { details }),
+        },
+        metadata: {
+            request_id: requestId ?? generateRequestId(),
+            ...metadata,
+        },
+    };
+}
+//# sourceMappingURL=mcp-response.js.map

package/dist/utils/mcp-response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-response.js","sourceRoot":"","sources":["../../src/utils/mcp-response.ts"],"names":[],"mappings":"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"}

package/dist/utils/path-security.d.ts

@@ -0,0 +1,73 @@
+/**
+ * ローカルパスアクセスを無効化する環境変数
+ * true に設定すると project_context.project_path 機能が無効化される
+ */
+export declare const ENV_DISABLE_LOCAL_PATH_ACCESS = "REFTRIX_DISABLE_LOCAL_PATH_ACCESS";
+/**
+ * 許可されたワークスペースパスを指定する環境変数
+ * カンマ区切りで複数パスを指定可能
+ * 例: /home/user/projects,/var/www/apps
+ */
+export declare const ENV_ALLOWED_WORKSPACE_PATHS = "REFTRIX_ALLOWED_WORKSPACE_PATHS";
+/**
+ * パス検証結果
+ */
+export interface PathValidationResult {
+    /** 検証成功かどうか */
+    isValid: boolean;
+    /** 正規化されたパス（成功時のみ） */
+    normalizedPath?: string;
+    /** エラー理由（失敗時のみ） */
+    error?: {
+        code: PathSecurityErrorCode;
+        message: string;
+    };
+}
+/**
+ * パスセキュリティエラーコード
+ */
+export type PathSecurityErrorCode = "LOCAL_PATH_ACCESS_DISABLED" | "PATH_NOT_ALLOWED" | "DIRECTORY_TRAVERSAL_DETECTED" | "BLOCKED_PATH_PATTERN" | "PATH_NOT_FOUND" | "PATH_NOT_DIRECTORY" | "SYMLINK_ESCAPE_DETECTED";
+/**
+ * ローカルパスアクセスが無効化されているか確認
+ */
+export declare function isLocalPathAccessDisabled(): boolean;
+/**
+ * 許可されたワークスペースパスを取得
+ */
+export declare function getAllowedWorkspacePaths(): string[];
+/**
+ * ファイル名がブロックされるパターンに一致するか確認
+ */
+export declare function matchesBlockedFilePattern(filename: string): boolean;
+/**
+ * プロジェクトパスを検証
+ *
+ * セキュリティチェック:
+ * 1. ローカルパスアクセスが無効化されていないか
+ * 2. パスが正規化後も許可されたワークスペース配下にあるか
+ * 3. ディレクトリトラバーサル攻撃パターンが含まれていないか
+ * 4. ブロックされるシステムパスパターンに一致しないか
+ * 5. シンボリックリンクによるワークスペース外へのエスケープがないか
+ *
+ * @param inputPath - 検証するパス
+ * @returns 検証結果
+ *
+ * @example
+ * ```typescript
+ * const result = validateProjectPath('/home/user/my-project');
+ * if (!result.isValid) {
+ *   throw new Error(result.error?.message);
+ * }
+ * // result.normalizedPath を使用
+ * ```
+ */
+export declare function validateProjectPath(inputPath: string): PathValidationResult;
+/**
+ * ファイルパスを検証（スキャン対象ファイル用）
+ *
+ * @param filePath - 検証するファイルパス
+ * @param workspacePath - 許可されたワークスペースパス
+ * @returns 検証成功かどうか
+ */
+export declare function validateFilePath(filePath: string, workspacePath: string): boolean;
+//# sourceMappingURL=path-security.d.ts.map

package/dist/utils/path-security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-security.d.ts","sourceRoot":"","sources":["../../src/utils/path-security.ts"],"names":[],"mappings":"AAyBA;;;GAGG;AACH,eAAO,MAAM,6BAA6B,sCAAsC,CAAC;AAEjF;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,oCAAoC,CAAC;AA6D7E;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,eAAe;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,sBAAsB;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mBAAmB;IACnB,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,qBAAqB,CAAC;QAC5B,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAC7B,4BAA4B,GAC5B,kBAAkB,GAClB,8BAA8B,GAC9B,sBAAsB,GACtB,gBAAgB,GAChB,oBAAoB,GACpB,yBAAyB,CAAC;AAM9B;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,OAAO,CAGnD;AAED;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,EAAE,CAYnD;AAcD;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAOnE;AAqCD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,oBAAoB,CA6H3E;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAgCjF"}