@crossdelta/pf-mcp 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,722 @@
+import { PfEffect, PfPluginContext, PfWorkspaceContext } from '@crossdelta/platform-sdk/facade';
+
+/**
+ * Effect Executor Types
+ *
+ * All type definitions for effect execution.
+ * Types first, following project conventions.
+ */
+
+/**
+ * Error codes for structured error reporting
+ */
+declare const ErrorCodes: {
+    readonly PATH_OUTSIDE_ROOT: "PATH_OUTSIDE_ROOT";
+    readonly REQUIRES_ELICITATION: "REQUIRES_ELICITATION";
+    readonly UNSUPPORTED_EFFECT: "UNSUPPORTED_EFFECT";
+    readonly WRITE_FAILED: "WRITE_FAILED";
+    readonly ATOMIC_RENAME_FAILED: "ATOMIC_RENAME_FAILED";
+    readonly PLAN_HASH_MISMATCH: "PLAN_HASH_MISMATCH";
+    readonly REVIEW_REQUIRED: "REVIEW_REQUIRED";
+    readonly REVIEW_TOKEN_INVALID: "REVIEW_TOKEN_INVALID";
+    readonly REVIEW_TOKEN_MISMATCH: "REVIEW_TOKEN_MISMATCH";
+    readonly POLICY_VERSION_MISMATCH: "POLICY_VERSION_MISMATCH";
+    readonly POLICY_VIOLATION: "POLICY_VIOLATION";
+    readonly FORBIDDEN_DIR: "FORBIDDEN_DIR";
+    readonly CONSOLE_IN_DOMAIN: "CONSOLE_IN_DOMAIN";
+    readonly PROCESS_ENV_IN_DOMAIN: "PROCESS_ENV_IN_DOMAIN";
+    readonly FETCH_IN_DOMAIN: "FETCH_IN_DOMAIN";
+};
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+type EffectStatus = 'created' | 'updated' | 'skipped' | 'error' | 'would_create' | 'would_update' | 'would_skip';
+interface PreviewInfo {
+    /** Existing file size in bytes */
+    oldBytes?: number;
+    /** New content size in bytes */
+    newBytes?: number;
+    /** SHA-256 hash of existing content */
+    oldHash?: string;
+    /** SHA-256 hash of new content */
+    newHash?: string;
+    /** Would overwrite existing file */
+    wouldOverwrite?: boolean;
+    /** @deprecated Use oldBytes/newBytes */
+    existingLength?: number;
+    /** @deprecated Use oldBytes/newBytes */
+    newLength?: number;
+}
+interface EffectExecutionResult {
+    /** Effect that was executed */
+    effect: PfEffect;
+    /** Whether execution succeeded (false for errors and dryRun) */
+    success: boolean;
+    /** Result status */
+    status: EffectStatus;
+    /** Human-readable message */
+    message: string;
+    /** Path affected (if applicable) */
+    path?: string;
+    /** Target identifier (file path, env key, etc.) */
+    target?: string;
+    /** Error code (if error) */
+    code?: ErrorCode;
+    /** Reason for skip/decision */
+    reason?: string;
+    /** Preview info for dryRun (rich artifacts) */
+    preview?: PreviewInfo;
+}
+interface EffectSummary {
+    /** Counts by effect kind */
+    byKind: Record<string, {
+        total: number;
+        created: number;
+        updated: number;
+        skipped: number;
+        error: number;
+    }>;
+    /** Total bytes that would be written */
+    totalNewBytes: number;
+    /** Total bytes that would be overwritten */
+    totalOldBytes: number;
+}
+interface EffectCounts {
+    created: number;
+    updated: number;
+    skipped: number;
+    error: number;
+    wouldCreate: number;
+    wouldUpdate: number;
+    wouldSkip: number;
+}
+interface PolicyViolationInfo {
+    code: string;
+    message: string;
+    path: string;
+    line?: number;
+}
+interface ApplyResult {
+    /** Overall success (all effects succeeded, or dryRun completed) */
+    ok: boolean;
+    /** Summary message */
+    summary: string;
+    /** Individual effect results */
+    results: EffectExecutionResult[];
+    /** Counts by status */
+    counts: EffectCounts;
+    /** Whether this was a dry run */
+    dryRun: boolean;
+    /** Error code (if top-level error) */
+    code?: ErrorCode;
+    /** Structured summary (M9: rich preview) */
+    structuredSummary?: EffectSummary;
+    /** Policy violations (if any) */
+    policyViolations?: PolicyViolationInfo[];
+}
+
+/**
+ * Plan Types
+ *
+ * Types for the deterministic planning system.
+ * MCP = Planner (structure), AI = Code Generator (content)
+ *
+ * Flow:
+ * 1. AI/Copilot delivers Intent + Inputs
+ * 2. pf generates Plan + Preview (deterministic)
+ * 3. Optional: plan_review for validation
+ * 4. User OK Gate
+ * 5. apply_changes with expectedPlanHash (idempotent)
+ */
+
+type PlanIssueSeverity = 'error' | 'warning' | 'info';
+interface PlanIssue {
+    /** Issue severity */
+    severity: PlanIssueSeverity;
+    /** Error code for programmatic handling */
+    code: string;
+    /** Human-readable message */
+    message: string;
+    /** Affected path (if applicable) */
+    path?: string;
+    /** Line number (if applicable) */
+    line?: number;
+}
+interface PlanPreviewCounts {
+    /** Files that would be created */
+    wouldCreate: number;
+    /** Files that would be updated */
+    wouldUpdate: number;
+    /** Files that would be skipped (no changes) */
+    wouldSkip: number;
+    /** Effects with errors */
+    errors: number;
+}
+interface PlanPreview {
+    /** Counts by action type */
+    counts: PlanPreviewCounts;
+    /** Total bytes that would be written */
+    totalNewBytes: number;
+    /** Total bytes that would be overwritten */
+    totalOldBytes: number;
+    /** Files grouped by action */
+    files: {
+        create: string[];
+        update: string[];
+        skip: string[];
+    };
+}
+interface FilePlanEntry {
+    /** Absolute path where file should be created */
+    path: string;
+    /** Human-readable intent (what this file should do) */
+    intent: string;
+    /** Inputs for AI code generation */
+    inputs: Record<string, unknown>;
+    /** File layer for constraint enforcement */
+    layer?: 'domain' | 'useCase' | 'adapter' | 'infra' | 'config';
+    /** File kind for context */
+    kind?: 'handler' | 'adapter' | 'service' | 'useCase' | 'contract' | 'config' | 'test';
+}
+interface DependencyIntent {
+    /** Package name (e.g., '@pusher/push-notifications-server') */
+    name: string;
+    /** Version constraint (e.g., '^1.0.0', 'latest') */
+    version?: string;
+    /** Whether this is a dev dependency */
+    dev?: boolean;
+    /** Reason for adding this dependency */
+    reason?: string;
+}
+interface EnvVarIntent {
+    /** Environment variable key */
+    key: string;
+    /** Description for documentation */
+    description: string;
+    /** Whether this env var is required */
+    required: boolean;
+    /** Example value (for .env.example) */
+    example?: string;
+}
+interface GenerationPlanResult {
+    /** Whether plan generation succeeded */
+    ok: boolean;
+    /** Service name */
+    serviceName: string;
+    /** Service directory (relative to workspace) */
+    serviceDir: string;
+    /** Files to generate (paths/intent only - AI fills content) */
+    files: FilePlanEntry[];
+    /** Effects ready to apply (scaffold files with content) */
+    effects: PfEffect[];
+    /** Dependencies to add */
+    dependencies: DependencyIntent[];
+    /** Environment variables needed */
+    envVars: EnvVarIntent[];
+    /** Post-generation commands */
+    postCommands: string[];
+    /** SHA-256 hash of the plan for integrity verification */
+    planHash: string;
+    /** Preview of what would happen */
+    preview: PlanPreview;
+    /** Whether plan can be applied (no blocking errors) */
+    canApply: boolean;
+    /** Validation issues */
+    issues: PlanIssue[];
+    /** Metadata for debugging/logging */
+    metadata: Record<string, unknown>;
+}
+interface ApplyChangesInput {
+    /** Effects to apply (AI-generated content merged with plan) */
+    changes: PfEffect[];
+    /** Optional: Workspace root path */
+    workspaceRoot?: string;
+    /** Optional: Expected plan hash for drift detection */
+    expectedPlanHash?: string;
+    /** Optional: If true, requires a valid reviewToken */
+    requireReview?: boolean;
+    /** Optional: Review token from plan_review */
+    reviewToken?: string;
+    /** Optional: Expected policy version */
+    expectedPolicyVersion?: string;
+}
+interface DependencyPolicy {
+    /** Patterns to deny (e.g., file:, git+, https://) */
+    denyPatterns: string[];
+    /** Pinning strategy for new dependencies */
+    pinningStrategy: 'caret' | 'exact' | 'tilde';
+    /** Registry URL (optional, for private registries) */
+    registryUrl?: string;
+}
+declare const DEFAULT_DEPENDENCY_POLICY: DependencyPolicy;
+declare const isFilePlanEntry: (value: unknown) => value is FilePlanEntry;
+declare const isDependencyIntent: (value: unknown) => value is DependencyIntent;
+
+/**
+ * Deps Add Executor
+ *
+ * Handles deps:add effects:
+ * - Adds dependency to package.json
+ * - Validates against DependencyPolicy (denyPatterns)
+ * - Idempotent: skips if dependency already exists with compatible version
+ */
+
+interface DepsAddEffect {
+    readonly kind: 'deps:add';
+    /** Package name */
+    readonly name: string;
+    /** Version constraint (e.g., '^1.0.0', 'latest') */
+    readonly version?: string;
+    /** Whether this is a dev dependency */
+    readonly dev?: boolean;
+    /** Target service directory (relative to workspace root) */
+    readonly targetDir?: string;
+}
+declare const isDepsAddEffect: (effect: unknown) => effect is DepsAddEffect;
+
+/**
+ * Audit Module
+ *
+ * Writes audit artifacts for apply_changes operations.
+ * Provides traceability for what was applied, when, and by whom.
+ *
+ * Audit artifacts are stored in: .pf/audit/<planHash>-<timestamp>.json
+ *
+ * Format:
+ * {
+ *   planHash: string,
+ *   reviewToken?: string,
+ *   policyVersion: string,
+ *   appliedAt: string (ISO),
+ *   reviewedAt?: string (ISO),
+ *   dryRun: boolean,
+ *   summary: string,
+ *   counts: {...},
+ *   effects: PfEffect[],
+ *   results: EffectExecutionResult[]
+ * }
+ */
+
+/**
+ * Audit artifact data
+ */
+interface AuditArtifact {
+    /** Plan hash (SHA-256) */
+    planHash: string;
+    /** Review token used (if any) */
+    reviewToken?: string;
+    /** Policy version */
+    policyVersion: string;
+    /** ISO timestamp when apply was executed */
+    appliedAt: string;
+    /** ISO timestamp when plan was reviewed (from review token) */
+    reviewedAt?: string;
+    /** Whether this was a dry run */
+    dryRun: boolean;
+    /** Summary message */
+    summary: string;
+    /** Execution counts */
+    counts: ApplyResult['counts'];
+    /** Effects that were applied */
+    effects: readonly PfEffect[];
+    /** Individual execution results */
+    results: readonly EffectExecutionResult[];
+}
+/**
+ * Audit directory name (relative to workspace root)
+ */
+declare const AUDIT_DIR = ".pf/audit";
+/**
+ * Generate audit artifact filename
+ *
+ * Format: <planHash>-<timestamp>.json
+ * Timestamp is ISO format with colons replaced by dashes for filesystem safety
+ */
+declare const generateAuditFilename: (planHash: string, appliedAt: string) => string;
+/**
+ * Write audit artifact to filesystem
+ *
+ * @param audit - Audit artifact data
+ * @param workspaceRoot - Workspace root path
+ * @returns Absolute path to written audit file
+ */
+declare const writeAuditArtifact: (audit: AuditArtifact, workspaceRoot: string) => string;
+/**
+ * Create audit artifact from apply result
+ */
+declare const createAuditArtifact: (planHash: string, policyVersion: string, effects: readonly PfEffect[], result: ApplyResult, options?: {
+    reviewToken?: string;
+    reviewedAt?: string;
+}) => AuditArtifact;
+
+/**
+ * Plan Cache Module
+ *
+ * In-memory cache for plans and reviews.
+ * Used by MCP resources to retrieve plan/review data by hash.
+ *
+ * Cache Keys:
+ * - plan:<hash> → Plan data (effects array, metadata)
+ * - review:<hash> → Review result (from plan_review)
+ *
+ * Cache is scoped to the MCP server process lifetime.
+ * No persistence - restart clears cache.
+ */
+
+/**
+ * Cached plan entry
+ */
+interface CachedPlan {
+    /** Plan hash (SHA-256) */
+    planHash: string;
+    /** Effects array */
+    effects: readonly PfEffect[];
+    /** ISO timestamp when plan was created/cached */
+    createdAt: string;
+    /** Source operation (generate_service, etc.) */
+    source: string;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Cached review entry
+ */
+interface CachedReview {
+    /** Plan hash this review is for */
+    planHash: string;
+    /** Policy version at review time */
+    policyVersion: string;
+    /** Review token (planHash.policyVersion) */
+    reviewToken: string;
+    /** ISO timestamp when review was performed */
+    reviewedAt: string;
+    /** Whether the plan passed review */
+    valid: boolean;
+    /** Whether the plan can be applied */
+    canApply: boolean;
+    /** Preview counts */
+    preview: {
+        wouldCreate: number;
+        wouldUpdate: number;
+        wouldSkip: number;
+        errors: number;
+    };
+    /** Issues found during review */
+    issues: ReadonlyArray<{
+        severity: 'error' | 'warning' | 'info';
+        code: string;
+        message: string;
+        target?: string;
+    }>;
+}
+/**
+ * Get a cached plan by hash
+ */
+declare const getPlan: (planHash: string) => CachedPlan | undefined;
+/**
+ * Get a cached review by plan hash
+ */
+declare const getReview: (planHash: string) => CachedReview | undefined;
+/**
+ * Store a plan in the cache
+ */
+declare const cachePlan: (plan: CachedPlan) => void;
+/**
+ * Store a review in the cache
+ */
+declare const cacheReview: (review: CachedReview) => void;
+/**
+ * Check if a plan exists in the cache
+ */
+declare const hasPlan: (planHash: string) => boolean;
+/**
+ * Check if a review exists in the cache
+ */
+declare const hasReview: (planHash: string) => boolean;
+/**
+ * Get all cached plan hashes
+ */
+declare const listPlanHashes: () => string[];
+/**
+ * Get all cached review hashes
+ */
+declare const listReviewHashes: () => string[];
+/**
+ * Clear all caches (for testing)
+ */
+declare const clearCache: () => void;
+/**
+ * Get cache statistics
+ */
+declare const getCacheStats: () => {
+    planCount: number;
+    reviewCount: number;
+};
+
+/**
+ * Plan Hash Module
+ *
+ * Provides deterministic hashing for effect plans.
+ * Used for integrity verification between generate→review→apply flow.
+ *
+ * Key Features:
+ * - stableStringify: Deterministic JSON serialization (sorted keys)
+ * - computePlanHash: SHA-256 hex hash of normalized plan
+ * - computeContentHash: SHA-256 hex hash of file content
+ */
+
+/**
+ * Stable JSON stringify with deterministic key ordering
+ *
+ * Ensures identical plans always produce identical strings,
+ * regardless of object key insertion order.
+ *
+ * @param value - Any JSON-serializable value
+ * @returns Deterministic JSON string
+ */
+declare const stableStringify: (value: unknown) => string;
+/**
+ * Compute SHA-256 hash of a plan (effects array)
+ *
+ * Uses stableStringify for deterministic serialization.
+ * Returns lowercase hex string.
+ *
+ * @param changes - Array of effects to hash
+ * @returns SHA-256 hex hash (64 characters)
+ */
+declare const computePlanHash: (changes: readonly PfEffect[]) => string;
+/**
+ * Compute SHA-256 hash of file content
+ *
+ * Uses UTF-8 encoding. Returns lowercase hex string.
+ *
+ * @param content - File content string
+ * @returns SHA-256 hex hash (64 characters)
+ */
+declare const computeContentHash: (content: string) => string;
+/**
+ * Verify plan hash matches expected value
+ *
+ * @param changes - Current effects array
+ * @param expectedHash - Expected hash to verify against
+ * @returns true if hashes match, false otherwise
+ */
+declare const verifyPlanHash: (changes: readonly PfEffect[], expectedHash: string) => boolean;
+
+/**
+ * Policy Module
+ *
+ * Manages policy versioning and review tokens for the MCP apply flow.
+ *
+ * Key Concepts:
+ * - POLICY_VERSION: Current version of apply policies (semantic versioning)
+ * - Review Token: Binds planHash + policyVersion for tamper-evident verification
+ *
+ * Flow:
+ * 1. generate_service → planHash
+ * 2. plan_review → reviewToken (planHash + policyVersion)
+ * 3. apply_changes → verify reviewToken OR skip if requireReview=false
+ *
+ * Upgrade Path:
+ * - Current: Simple concatenation (planHash.policyVersion)
+ * - Future: HMAC-based tokens for cryptographic binding (see docs)
+ */
+/**
+ * Current policy version
+ *
+ * Bump this when apply policies change (new validations, behavior changes).
+ * Format: YYYY-MM-DD (date-based versioning)
+ *
+ * History:
+ * - 2025-01-03: Initial policy version (M10)
+ */
+declare const POLICY_VERSION = "2025-01-03";
+/**
+ * Review token format: `${planHash}.${policyVersion}`
+ *
+ * Simple format for initial implementation.
+ * Future: HMAC-based `${planHash}.${policyVersion}.${signature}`
+ */
+type ReviewToken = string;
+/**
+ * Generate a review token from planHash and policyVersion
+ *
+ * @param planHash - SHA-256 hash of the plan (from computePlanHash)
+ * @param policyVersion - Policy version (defaults to POLICY_VERSION)
+ * @returns Review token in format `${planHash}.${policyVersion}`
+ */
+declare const generateReviewToken: (planHash: string, policyVersion?: string) => ReviewToken;
+/**
+ * Parse a review token into its components
+ *
+ * @param token - Review token to parse
+ * @returns Parsed components or null if invalid format
+ */
+declare const parseReviewToken: (token: string) => {
+    planHash: string;
+    policyVersion: string;
+} | null;
+/**
+ * Validation result for review tokens
+ */
+interface ReviewTokenValidation {
+    valid: boolean;
+    code?: 'REVIEW_TOKEN_INVALID' | 'REVIEW_TOKEN_MISMATCH' | 'POLICY_VERSION_MISMATCH';
+    message?: string;
+    parsed?: {
+        planHash: string;
+        policyVersion: string;
+    };
+}
+/**
+ * Validate a review token against expected planHash and policyVersion
+ *
+ * @param token - Review token to validate
+ * @param expectedPlanHash - Expected plan hash
+ * @param expectedPolicyVersion - Expected policy version (defaults to POLICY_VERSION)
+ * @returns Validation result with code and message if invalid
+ */
+declare const validateReviewToken: (token: string, expectedPlanHash: string, expectedPolicyVersion?: string) => ReviewTokenValidation;
+
+/**
+ * MCP Resource Types
+ *
+ * Types for pf-mcp resources.
+ *
+ * @module resources/types
+ */
+/**
+ * MCP Resource definition (matches SDK's Resource type)
+ */
+interface McpResource {
+    /** Unique URI for the resource */
+    uri: string;
+    /** Human-readable name */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** MIME type of the resource content */
+    mimeType?: string;
+}
+/**
+ * Resource content returned by read
+ */
+interface McpResourceContent {
+    /** URI of the resource */
+    uri: string;
+    /** MIME type */
+    mimeType?: string;
+    /** Text content (for text resources) */
+    text?: string;
+}
+/**
+ * Resource reader function type
+ */
+type ResourceReader = (uri: string) => Promise<McpResourceContent>;
+/**
+ * Resource definition with reader
+ */
+interface ResourceDefinition {
+    /** Static resource metadata */
+    resource: McpResource;
+    /** Function to read the resource content */
+    read: ResourceReader;
+}
+
+/**
+ * Generator Documentation Resources
+ *
+ * Exposes generator guidelines (service.md, etc.) as MCP resources
+ * for AI to read on-demand.
+ *
+ * @module resources/generator-docs
+ */
+
+/**
+ * Create a resource for a specific generator doc
+ */
+declare const createGeneratorDocResource: (docName: string) => ResourceDefinition;
+/**
+ * Create a discovery resource listing all available generator docs
+ */
+declare const createGeneratorDocsListResource: () => ResourceDefinition;
+/**
+ * Create all generator doc resources (individual docs + list)
+ */
+declare const createAllGeneratorDocResources: () => Promise<ResourceDefinition[]>;
+
+declare const readTemplateFile: (templateName: string, filePath: string) => Promise<string>;
+declare const createTemplatesListResource: () => ResourceDefinition;
+declare const createTemplateResource: (templateName: string) => ResourceDefinition;
+declare const createTemplateFileResourceTemplate: () => {
+    uriTemplate: string;
+    name: string;
+    description: string;
+    mimeType: string;
+};
+declare const createAllTemplateResources: () => Promise<ResourceDefinition[]>;
+
+/**
+ * MCP Server Implementation
+ *
+ * Thin adapter between MCP SDK and Platform SDK facade.
+ * Uses execute() dispatch for tool calls (plan-only by default).
+ *
+ * Handles elicitation effects from tools:
+ * - Detects elicit:input effects in tool results
+ * - Returns structured error with missing fields (MCP elicitation not yet supported by VS Code)
+ * - Future: Use server.elicitInput() when client declares elicitation capability
+ *
+ * @module server
+ */
+
+/**
+ * MCP Server configuration
+ */
+interface McpServerOptions {
+    /** Server name (shown in MCP clients) */
+    name: string;
+    /** Server version */
+    version: string;
+    /** Workspace context */
+    workspace: PfWorkspaceContext;
+    /** Plugin modules to load */
+    plugins: string[];
+    /** Optional logger */
+    logger?: PfPluginContext['logger'];
+}
+/**
+ * MCP Server configuration with auto-discovery
+ */
+interface McpServerAutoOptions {
+    /** Server name (shown in MCP clients) */
+    name: string;
+    /** Server version */
+    version: string;
+    /** Optional workspace root (auto-discovered if omitted) */
+    workspaceRoot?: string;
+    /** Plugin modules to load */
+    plugins: string[];
+    /** Optional logger */
+    logger?: PfPluginContext['logger'];
+}
+/**
+ * Create and start an MCP server
+ *
+ * Uses execute() dispatch for all tool calls.
+ * Built-in tools (services.generate) are always included.
+ * Plugin-based tools are loaded from specified modules.
+ *
+ * @param options - Server configuration
+ * @returns Promise that resolves when server is ready
+ */
+declare const createMcpServer: (options: McpServerOptions) => Promise<void>;
+/**
+ * Create and start MCP server with auto-discovered workspace
+ *
+ * Automatically discovers workspace configuration from package.json and filesystem.
+ * This is the recommended way to start the server.
+ *
+ * @param options - Server options (workspace auto-discovered)
+ */
+declare const createMcpServerFromWorkspace: (options: McpServerAutoOptions) => Promise<void>;
+
+export { AUDIT_DIR, type ApplyChangesInput, type AuditArtifact, type CachedPlan, type CachedReview, DEFAULT_DEPENDENCY_POLICY, type DependencyIntent, type DependencyPolicy, type DepsAddEffect, type EnvVarIntent, type FilePlanEntry, type GenerationPlanResult, type McpServerAutoOptions, type McpServerOptions, POLICY_VERSION, type PlanIssue, type PlanIssueSeverity, type PlanPreview, type PlanPreviewCounts, type ReviewToken, type ReviewTokenValidation, cachePlan, cacheReview, clearCache, computeContentHash, computePlanHash, createAllGeneratorDocResources, createAllTemplateResources, createAuditArtifact, createGeneratorDocResource, createGeneratorDocsListResource, createMcpServer, createMcpServerFromWorkspace, createTemplateFileResourceTemplate, createTemplateResource, createTemplatesListResource, generateAuditFilename, generateReviewToken, getCacheStats, getPlan, getReview, hasPlan, hasReview, isDependencyIntent, isDepsAddEffect, isFilePlanEntry, listPlanHashes, listReviewHashes, parseReviewToken, readTemplateFile, stableStringify, validateReviewToken, verifyPlanHash, writeAuditArtifact };