snow-flow 10.0.1-dev.362 → 10.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
-  "version": "10.0.1-dev.362",
+  "version": "10.0.2",
   "name": "snow-flow",
   "description": "Snow-Flow - ServiceNow Multi-Agent Development Framework powered by AI",
   "license": "Elastic-2.0",

package/src/servicenow/servicenow-mcp-unified/tools/deployment/index.ts

@@ -27,3 +27,7 @@ export { toolDefinition as snow_deployment_debug_def, execute as snow_deployment
 export { toolDefinition as snow_deployment_status_def, execute as snow_deployment_status_exec } from './snow_deployment_status.js';
 export { toolDefinition as snow_rollback_deployment_def, execute as snow_rollback_deployment_exec } from './snow_rollback_deployment.js';
 export { toolDefinition as snow_validate_deployment_def, execute as snow_validate_deployment_exec } from './snow_validate_deployment.js';
+
+// ==================== GitHub Pipeline Tools (Enterprise) ====================
+export { toolDefinition as snow_github_tree_def, execute as snow_github_tree_exec } from './snow_github_tree.js';
+export { toolDefinition as snow_github_deploy_def, execute as snow_github_deploy_exec } from './snow_github_deploy.js';

package/src/servicenow/servicenow-mcp-unified/tools/deployment/shared/artifact-constants.ts

@@ -0,0 +1,131 @@
+/**
+ * Shared Artifact Constants
+ *
+ * Centralized mappings for ServiceNow artifact types, identifier fields,
+ * and file-to-field mappings used by snow_artifact_manage, snow_github_deploy,
+ * and other deployment tools.
+ */
+
+// ==================== ARTIFACT TYPE → TABLE MAPPING ====================
+export const ARTIFACT_TABLE_MAP: Record<string, string> = {
+  sp_widget: 'sp_widget',
+  widget: 'sp_widget',
+  sp_page: 'sp_page',
+  page: 'sp_page',
+  sys_ux_page: 'sys_ux_page',
+  uib_page: 'sys_ux_page',
+  script_include: 'sys_script_include',
+  business_rule: 'sys_script',
+  client_script: 'sys_script_client',
+  ui_policy: 'sys_ui_policy',
+  ui_action: 'sys_ui_action',
+  rest_message: 'sys_rest_message',
+  scheduled_job: 'sysauto_script',
+  transform_map: 'sys_transform_map',
+  fix_script: 'sys_script_fix',
+  table: 'sys_db_object',
+  field: 'sys_dictionary',
+  flow: 'sys_hub_flow',
+  application: 'sys_app'
+};
+
+// ==================== TABLE → IDENTIFIER FIELD MAPPING ====================
+export const ARTIFACT_IDENTIFIER_FIELD: Record<string, string> = {
+  sp_widget: 'id',
+  sp_page: 'id',
+  sys_ux_page: 'name',
+  sys_script_include: 'name',
+  sys_script: 'name',
+  sys_script_client: 'name',
+  sys_ui_policy: 'short_description',
+  sys_ui_action: 'name',
+  sys_rest_message: 'name',
+  sysauto_script: 'name',
+  sys_transform_map: 'name',
+  sys_script_fix: 'name',
+  sys_db_object: 'name',
+  sys_dictionary: 'element',
+  sys_hub_flow: 'name',
+  sys_app: 'name'
+};
+
+// ==================== FILE MAPPINGS FOR IMPORT (artifact_directory / GitHub deploy) ====================
+export const FILE_MAPPINGS: Record<string, Record<string, string[]>> = {
+  sp_widget: {
+    template: ['template.html', 'index.html', 'widget.html'],
+    script: ['server.js', 'server-script.js', 'script.js'],
+    client_script: ['client.js', 'client-script.js', 'controller.js'],
+    css: ['style.css', 'styles.css', 'widget.css'],
+    option_schema: ['options.json', 'option_schema.json', 'schema.json']
+  },
+  sys_script: {  // business_rule
+    script: ['script.js', 'index.js', 'main.js'],
+    condition: ['condition.js', 'condition.txt']
+  },
+  sys_script_include: {
+    script: ['script.js', 'index.js', 'main.js', '{name}.js']
+  },
+  sys_script_client: {
+    script: ['script.js', 'client.js', 'index.js']
+  },
+  sp_page: {
+    // SP pages don't have script content
+  },
+  sys_ux_page: {
+    // UIB pages don't have script content in same way
+  },
+  sys_ui_action: {
+    script: ['script.js', 'action.js', 'index.js'],
+    condition: ['condition.js']
+  },
+  sysauto_script: {  // scheduled_job
+    script: ['script.js', 'job.js', 'index.js']
+  },
+  sys_script_fix: {
+    script: ['script.js', 'fix.js', 'index.js']
+  }
+};
+
+// ==================== FILE MAPPINGS FOR EXPORT ====================
+export const EXPORT_FILE_MAPPINGS: Record<string, Record<string, string>> = {
+  sp_widget: {
+    template: 'template.html',
+    script: 'server.js',
+    client_script: 'client.js',
+    css: 'style.css',
+    option_schema: 'options.json'
+  },
+  sys_script: {  // business_rule
+    script: 'script.js',
+    condition: 'condition.js'
+  },
+  sys_script_include: {
+    script: 'script.js'
+  },
+  sys_script_client: {
+    script: 'script.js'
+  },
+  sys_ui_action: {
+    script: 'script.js',
+    condition: 'condition.js'
+  },
+  sysauto_script: {
+    script: 'script.js'
+  },
+  sys_script_fix: {
+    script: 'script.js'
+  }
+};
+
+// ==================== DEFAULT FILE EXTENSIONS PER ARTIFACT TYPE ====================
+export const DEFAULT_FILE_EXTENSIONS: Record<string, string> = {
+  sys_script_include: '.js',
+  sys_script: '.js',
+  sys_script_client: '.js',
+  sys_ui_action: '.js',
+  sysauto_script: '.js',
+  sys_script_fix: '.js',
+  sp_widget: '',   // Widgets use directory mode, not single-file
+  sp_page: '',
+  sys_ux_page: '',
+};

package/src/servicenow/servicenow-mcp-unified/tools/deployment/snow_artifact_manage.ts

@@ -15,116 +15,12 @@ import { createSuccessResult, createErrorResult, SnowFlowError, ErrorType } from
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import { existsSync } from 'fs';
-
-// ==================== ARTIFACT TYPE MAPPING ====================
-const ARTIFACT_TABLE_MAP: Record<string, string> = {
-  sp_widget: 'sp_widget',
-  widget: 'sp_widget',
-  sp_page: 'sp_page',
-  page: 'sp_page',
-  sys_ux_page: 'sys_ux_page',
-  uib_page: 'sys_ux_page',
-  script_include: 'sys_script_include',
-  business_rule: 'sys_script',
-  client_script: 'sys_script_client',
-  ui_policy: 'sys_ui_policy',
-  ui_action: 'sys_ui_action',
-  rest_message: 'sys_rest_message',
-  scheduled_job: 'sysauto_script',
-  transform_map: 'sys_transform_map',
-  fix_script: 'sys_script_fix',
-  table: 'sys_db_object',
-  field: 'sys_dictionary',
-  flow: 'sys_hub_flow',
-  application: 'sys_app'
-};
-
-const ARTIFACT_IDENTIFIER_FIELD: Record<string, string> = {
-  sp_widget: 'id',
-  sp_page: 'id',
-  sys_ux_page: 'name',
-  sys_script_include: 'name',
-  sys_script: 'name',
-  sys_script_client: 'name',
-  sys_ui_policy: 'short_description',
-  sys_ui_action: 'name',
-  sys_rest_message: 'name',
-  sysauto_script: 'name',
-  sys_transform_map: 'name',
-  sys_script_fix: 'name',
-  sys_db_object: 'name',
-  sys_dictionary: 'element',
-  sys_hub_flow: 'name',
-  sys_app: 'name'
-};
-
-// ==================== FILE MAPPINGS FOR IMPORT (artifact_directory) ====================
-const FILE_MAPPINGS: Record<string, Record<string, string[]>> = {
-  sp_widget: {
-    template: ['template.html', 'index.html', 'widget.html'],
-    script: ['server.js', 'server-script.js', 'script.js'],
-    client_script: ['client.js', 'client-script.js', 'controller.js'],
-    css: ['style.css', 'styles.css', 'widget.css'],
-    option_schema: ['options.json', 'option_schema.json', 'schema.json']
-  },
-  sys_script: {  // business_rule
-    script: ['script.js', 'index.js', 'main.js'],
-    condition: ['condition.js', 'condition.txt']
-  },
-  sys_script_include: {
-    script: ['script.js', 'index.js', 'main.js', '{name}.js']
-  },
-  sys_script_client: {
-    script: ['script.js', 'client.js', 'index.js']
-  },
-  sp_page: {
-    // SP pages don't have script content
-  },
-  sys_ux_page: {
-    // UIB pages don't have script content in same way
-  },
-  sys_ui_action: {
-    script: ['script.js', 'action.js', 'index.js'],
-    condition: ['condition.js']
-  },
-  sysauto_script: {  // scheduled_job
-    script: ['script.js', 'job.js', 'index.js']
-  },
-  sys_script_fix: {
-    script: ['script.js', 'fix.js', 'index.js']
-  }
-};
-
-// ==================== FILE MAPPINGS FOR EXPORT ====================
-const EXPORT_FILE_MAPPINGS: Record<string, Record<string, string>> = {
-  sp_widget: {
-    template: 'template.html',
-    script: 'server.js',
-    client_script: 'client.js',
-    css: 'style.css',
-    option_schema: 'options.json'
-  },
-  sys_script: {  // business_rule
-    script: 'script.js',
-    condition: 'condition.js'
-  },
-  sys_script_include: {
-    script: 'script.js'
-  },
-  sys_script_client: {
-    script: 'script.js'
-  },
-  sys_ui_action: {
-    script: 'script.js',
-    condition: 'condition.js'
-  },
-  sysauto_script: {
-    script: 'script.js'
-  },
-  sys_script_fix: {
-    script: 'script.js'
-  }
-};
+import {
+  ARTIFACT_TABLE_MAP,
+  ARTIFACT_IDENTIFIER_FIELD,
+  FILE_MAPPINGS,
+  EXPORT_FILE_MAPPINGS,
+} from './shared/artifact-constants.js';
 
 export const toolDefinition: MCPToolDefinition = {
   name: 'snow_artifact_manage',
@@ -212,31 +108,31 @@ export const toolDefinition: MCPToolDefinition = {
       },
       description: {
         type: 'string',
-        description: '[create] Artifact description'
+        description: '[create/update] Artifact description'
       },
       template: {
         type: 'string',
-        description: '[create] HTML template (for widgets/pages)'
+        description: '[create/update] HTML template (for widgets/pages)'
       },
       server_script: {
         type: 'string',
-        description: '[create] Server-side script (ES5 only!)'
+        description: '[create/update] Server-side script (ES5 only!)'
       },
       client_script: {
         type: 'string',
-        description: '[create] Client-side script'
+        description: '[create/update] Client-side script'
       },
       css: {
         type: 'string',
-        description: '[create] CSS stylesheet (for widgets)'
+        description: '[create/update] CSS stylesheet (for widgets)'
       },
       option_schema: {
         type: 'string',
-        description: '[create] Option schema JSON (for widgets)'
+        description: '[create/update] Option schema JSON (for widgets)'
       },
       script: {
         type: 'string',
-        description: '[create] Script content (for script includes, business rules, etc.)'
+        description: '[create/update] Script content (for script includes, business rules, etc.)'
       },
       api_name: {
         type: 'string',
@@ -1094,8 +990,17 @@ async function executeUpdate(args: any, context: ServiceNowContext, tableName: s
     return createErrorResult(fileResolution.error);
   }
 
-  // Merge: config values (highest priority) > file-based content
-  const mergedConfig = { ...fileResolution.resolvedFields, ...config };
+  // Extract inline params from args (same fields supported by create)
+  const inlineParams: Record<string, any> = {};
+  const inlineFieldKeys = ['script', 'template', 'server_script', 'client_script', 'css', 'option_schema', 'description', 'active'];
+  for (const key of inlineFieldKeys) {
+    if (args[key] !== undefined) {
+      inlineParams[key] = args[key];
+    }
+  }
+
+  // Merge priority: config (highest) > inline params > _file params > artifact_directory (lowest)
+  const mergedConfig = { ...fileResolution.resolvedFields, ...inlineParams, ...config };
 
   if (Object.keys(mergedConfig).length === 0) {
     return createErrorResult('No update content provided. Use config object and/or file parameters (script_file, template_file, artifact_directory, etc.)');

package/src/servicenow/servicenow-mcp-unified/tools/deployment/snow_github_deploy.ts

@@ -0,0 +1,630 @@
+/**
+ * snow_github_deploy - GitHub → ServiceNow Deployment Pipeline (Enterprise)
+ *
+ * Deploys files directly from a GitHub repository to ServiceNow without
+ * file content passing through the LLM context window. Content flows:
+ *
+ *   tool process → proxyToolCall('github_get_content') → enterprise server → GitHub API
+ *   tool process → getAuthenticatedClient() → ServiceNow Table API
+ *
+ * Three deployment modes:
+ * 1. Single file: Deploy one file to a specific artifact field
+ * 2. Directory → Widget: Auto-map directory files to widget fields via FILE_MAPPINGS
+ * 3. Bulk: Deploy all matching files in a directory as separate artifacts
+ *
+ * Requires enterprise license with 'github' feature enabled.
+ * GitHub PAT is managed server-side via the enterprise portal.
+ */
+
+import { MCPToolDefinition, ServiceNowContext, ToolResult } from '../../shared/types.js';
+import { getAuthenticatedClient } from '../../shared/auth.js';
+import { createSuccessResult, createErrorResult } from '../../shared/error-handler.js';
+import { proxyToolCall } from '../../../enterprise-proxy/proxy.js';
+import {
+  ARTIFACT_TABLE_MAP,
+  ARTIFACT_IDENTIFIER_FIELD,
+  FILE_MAPPINGS,
+  DEFAULT_FILE_EXTENSIONS,
+} from './shared/artifact-constants.js';
+
+export const toolDefinition: MCPToolDefinition = {
+  name: 'snow_github_deploy',
+  description: `Deploy files directly from GitHub to ServiceNow — content never passes through LLM context.
+
+Three modes:
+1. Single file: source_path → one artifact field
+2. Directory → Widget: source_directory auto-maps files (template.html→template, server.js→script, etc.)
+3. Bulk: source_directory + bulk=true → each file becomes a separate artifact
+
+Requires: Enterprise license with 'github' feature. GitHub PAT is managed server-side.
+
+Supported target types: widget, script_include, business_rule, client_script, ui_action, scheduled_job, fix_script, etc.`,
+  category: 'development',
+  subcategory: 'deployment',
+  use_cases: ['github', 'deployment', 'pipeline', 'widgets', 'scripts'],
+  complexity: 'intermediate',
+  frequency: 'high',
+
+  permission: 'write',
+  allowedRoles: ['developer', 'admin'],
+  inputSchema: {
+    type: 'object',
+    properties: {
+      owner: {
+        type: 'string',
+        description: 'GitHub owner or organization'
+      },
+      repo: {
+        type: 'string',
+        description: 'Repository name'
+      },
+      branch: {
+        type: 'string',
+        description: 'Branch name (default: "main")'
+      },
+      source_path: {
+        type: 'string',
+        description: '[Mode 1] Path to a single file in the repo (e.g. "scripts/MyScript.js")'
+      },
+      source_directory: {
+        type: 'string',
+        description: '[Mode 2/3] Path to a directory in the repo (e.g. "widgets/my_widget/")'
+      },
+      target_type: {
+        type: 'string',
+        description: 'ServiceNow artifact type',
+        enum: [
+          'sp_widget', 'widget', 'sp_page', 'page', 'sys_ux_page', 'uib_page',
+          'script_include', 'business_rule', 'client_script', 'ui_policy',
+          'ui_action', 'rest_message', 'scheduled_job', 'transform_map',
+          'fix_script', 'flow', 'application'
+        ]
+      },
+      target_identifier: {
+        type: 'string',
+        description: '[Mode 1/2] Name or ID of the target artifact in ServiceNow'
+      },
+      target_sys_id: {
+        type: 'string',
+        description: 'Alternative: sys_id of the target artifact'
+      },
+      target_field: {
+        type: 'string',
+        description: '[Mode 1] Which field to update (auto-detected if omitted, e.g. "script", "template")'
+      },
+      upsert: {
+        type: 'boolean',
+        description: 'Create artifact if it does not exist (default: true)'
+      },
+      bulk: {
+        type: 'boolean',
+        description: '[Mode 3] Deploy each file in directory as a separate artifact (default: false)'
+      },
+      file_extension_filter: {
+        type: 'string',
+        description: '[Mode 3] Filter files by extension in bulk mode (e.g. ".js")'
+      },
+      field_mapping: {
+        type: 'object',
+        description: '[Mode 2] Custom filename→field mapping override (e.g. {"my-template.html": "template"})'
+      },
+      dry_run: {
+        type: 'boolean',
+        description: 'Preview what would be deployed without actually deploying (default: false)'
+      }
+    },
+    required: ['owner', 'repo', 'target_type']
+  }
+};
+
+export async function execute(args: any, context: ServiceNowContext): Promise<ToolResult> {
+  const {
+    owner,
+    repo,
+    branch = 'main',
+    source_path,
+    source_directory,
+    target_type,
+    target_identifier,
+    target_sys_id,
+    target_field,
+    upsert = true,
+    bulk = false,
+    file_extension_filter,
+    field_mapping,
+    dry_run = false
+  } = args;
+
+  // Enterprise feature gate
+  if (!context.enterprise?.features?.includes('github')) {
+    return createErrorResult(
+      'GitHub integration requires an enterprise license with the "github" feature enabled.\n\n' +
+      'Upgrade at https://portal.snow-flow.dev or contact support.'
+    );
+  }
+
+  // Validate artifact type
+  const tableName = ARTIFACT_TABLE_MAP[target_type];
+  if (!tableName) {
+    return createErrorResult(
+      `Unsupported target_type: ${target_type}. Valid types: ${Object.keys(ARTIFACT_TABLE_MAP).join(', ')}`
+    );
+  }
+
+  // Determine mode
+  if (source_path) {
+    return await deploySingleFile(args, context, tableName);
+  } else if (source_directory && bulk) {
+    return await deployBulk(args, context, tableName);
+  } else if (source_directory) {
+    return await deployDirectory(args, context, tableName);
+  } else {
+    return createErrorResult('Provide either source_path (single file) or source_directory (directory/bulk mode).');
+  }
+}
+
+// ==================== MODE 1: SINGLE FILE ====================
+async function deploySingleFile(args: any, context: ServiceNowContext, tableName: string): Promise<ToolResult> {
+  const {
+    owner, repo, branch = 'main', source_path, target_type,
+    target_identifier, target_sys_id, target_field, upsert = true, dry_run = false
+  } = args;
+
+  if (!target_identifier && !target_sys_id) {
+    return createErrorResult('target_identifier or target_sys_id is required for single-file mode.');
+  }
+
+  // Fetch file content from GitHub via enterprise proxy
+  let fileContent: string;
+  try {
+    const result = await proxyToolCall('github_get_content', {
+      owner, repo, path: source_path, ref: branch
+    });
+
+    // GitHub API returns base64-encoded content for files
+    if (result.content && result.encoding === 'base64') {
+      fileContent = Buffer.from(result.content, 'base64').toString('utf-8');
+    } else if (typeof result.content === 'string') {
+      fileContent = result.content;
+    } else if (typeof result === 'string') {
+      fileContent = result;
+    } else {
+      return createErrorResult(`Unexpected response format from GitHub for ${source_path}. Expected file content.`);
+    }
+  } catch (error: any) {
+    return createErrorResult(`Failed to fetch ${source_path} from ${owner}/${repo}: ${error.message}`);
+  }
+
+  // Determine target field
+  const resolvedField = target_field || autoDetectField(source_path, tableName);
+  if (!resolvedField) {
+    return createErrorResult(
+      `Cannot auto-detect target field for "${source_path}" on ${target_type}. Specify target_field explicitly.`
+    );
+  }
+
+  if (dry_run) {
+    return createSuccessResult({
+      mode: 'single_file',
+      dry_run: true,
+      source: { owner, repo, branch, path: source_path, size: fileContent.length },
+      target: { type: target_type, table: tableName, identifier: target_identifier || target_sys_id, field: resolvedField },
+      message: 'Dry run — no changes made.'
+    });
+  }
+
+  // Deploy to ServiceNow
+  const client = await getAuthenticatedClient(context);
+  const deployResult = await upsertArtifact(
+    client, context, tableName, target_type,
+    target_sys_id, target_identifier,
+    { [resolvedField]: fileContent },
+    upsert
+  );
+
+  return createSuccessResult({
+    mode: 'single_file',
+    deployed: true,
+    source: { owner, repo, branch, path: source_path, size: fileContent.length },
+    target: {
+      type: target_type,
+      table: tableName,
+      sys_id: deployResult.sys_id,
+      name: deployResult.name,
+      field: resolvedField,
+      action: deployResult.action
+    },
+    url: `${context.instanceUrl}/nav_to.do?uri=${tableName}.do?sys_id=${deployResult.sys_id}`
+  });
+}
+
+// ==================== MODE 2: DIRECTORY → WIDGET ====================
+async function deployDirectory(args: any, context: ServiceNowContext, tableName: string): Promise<ToolResult> {
+  const {
+    owner, repo, branch = 'main', source_directory, target_type,
+    target_identifier, target_sys_id, field_mapping, upsert = true, dry_run = false
+  } = args;
+
+  if (!target_identifier && !target_sys_id) {
+    return createErrorResult('target_identifier or target_sys_id is required for directory mode.');
+  }
+
+  // List directory contents from GitHub
+  let dirEntries: any[];
+  try {
+    const result = await proxyToolCall('github_get_content', {
+      owner, repo, path: source_directory, ref: branch
+    });
+    dirEntries = Array.isArray(result) ? result : [];
+  } catch (error: any) {
+    return createErrorResult(`Failed to list ${source_directory} in ${owner}/${repo}: ${error.message}`);
+  }
+
+  // Build file→field mapping: custom override or auto-map via FILE_MAPPINGS
+  const fileMappings = FILE_MAPPINGS[tableName] || {};
+  const resolvedMapping: Record<string, string> = {}; // filename → field
+
+  for (const entry of dirEntries) {
+    if (entry.type !== 'file') continue;
+    const filename = entry.name || entry.path?.split('/').pop();
+    if (!filename) continue;
+
+    // Check custom field_mapping first
+    if (field_mapping && field_mapping[filename]) {
+      resolvedMapping[filename] = field_mapping[filename];
+      continue;
+    }
+
+    // Auto-map via FILE_MAPPINGS
+    for (const [field, filenames] of Object.entries(fileMappings)) {
+      if ((filenames as string[]).includes(filename)) {
+        resolvedMapping[filename] = field;
+        break;
+      }
+    }
+  }
+
+  if (Object.keys(resolvedMapping).length === 0) {
+    return createErrorResult(
+      `No files in ${source_directory} matched field mappings for ${target_type}. ` +
+      `Expected files: ${JSON.stringify(fileMappings)}. ` +
+      `Found: ${dirEntries.filter((e: any) => e.type === 'file').map((e: any) => e.name).join(', ')}`
+    );
+  }
+
+  if (dry_run) {
+    return createSuccessResult({
+      mode: 'directory',
+      dry_run: true,
+      source: { owner, repo, branch, directory: source_directory },
+      mapping: resolvedMapping,
+      target: { type: target_type, table: tableName, identifier: target_identifier || target_sys_id },
+      message: 'Dry run — no changes made.'
+    });
+  }
+
+  // Fetch each mapped file and combine into one update payload
+  const updatePayload: Record<string, string> = {};
+  const fetchedFiles: string[] = [];
+
+  for (const [filename, field] of Object.entries(resolvedMapping)) {
+    const filePath = source_directory.replace(/\/$/, '') + '/' + filename;
+    try {
+      const result = await proxyToolCall('github_get_content', {
+        owner, repo, path: filePath, ref: branch
+      });
+
+      let content: string;
+      if (result.content && result.encoding === 'base64') {
+        content = Buffer.from(result.content, 'base64').toString('utf-8');
+      } else if (typeof result.content === 'string') {
+        content = result.content;
+      } else if (typeof result === 'string') {
+        content = result;
+      } else {
+        continue;
+      }
+
+      updatePayload[field] = content;
+      fetchedFiles.push(`${filename} → ${field} (${content.length} chars)`);
+    } catch (error: any) {
+      fetchedFiles.push(`${filename} → ${field} (FAILED: ${error.message})`);
+    }
+  }
+
+  if (Object.keys(updatePayload).length === 0) {
+    return createErrorResult('Failed to fetch any matched files from GitHub.');
+  }
+
+  // Deploy combined payload to ServiceNow
+  const client = await getAuthenticatedClient(context);
+  const deployResult = await upsertArtifact(
+    client, context, tableName, target_type,
+    target_sys_id, target_identifier,
+    updatePayload,
+    upsert
+  );
+
+  return createSuccessResult({
+    mode: 'directory',
+    deployed: true,
+    source: { owner, repo, branch, directory: source_directory },
+    files: fetchedFiles,
+    fields_updated: Object.keys(updatePayload),
+    target: {
+      type: target_type,
+      table: tableName,
+      sys_id: deployResult.sys_id,
+      name: deployResult.name,
+      action: deployResult.action
+    },
+    url: `${context.instanceUrl}/nav_to.do?uri=${tableName}.do?sys_id=${deployResult.sys_id}`
+  });
+}
+
+// ==================== MODE 3: BULK ====================
+async function deployBulk(args: any, context: ServiceNowContext, tableName: string): Promise<ToolResult> {
+  const {
+    owner, repo, branch = 'main', source_directory, target_type,
+    file_extension_filter, upsert = true, dry_run = false
+  } = args;
+
+  // Determine extension filter
+  const extFilter = file_extension_filter || DEFAULT_FILE_EXTENSIONS[tableName] || '.js';
+
+  // List directory contents
+  let dirEntries: any[];
+  try {
+    const result = await proxyToolCall('github_get_content', {
+      owner, repo, path: source_directory, ref: branch
+    });
+    dirEntries = Array.isArray(result) ? result : [];
+  } catch (error: any) {
+    return createErrorResult(`Failed to list ${source_directory} in ${owner}/${repo}: ${error.message}`);
+  }
+
+  // Filter files by extension
+  const matchedFiles = dirEntries.filter((entry: any) => {
+    if (entry.type !== 'file') return false;
+    const name = entry.name || entry.path?.split('/').pop() || '';
+    return name.endsWith(extFilter);
+  });
+
+  if (matchedFiles.length === 0) {
+    return createErrorResult(
+      `No files matching "${extFilter}" found in ${source_directory}. ` +
+      `Found: ${dirEntries.filter((e: any) => e.type === 'file').map((e: any) => e.name).join(', ') || '(empty)'}`
+    );
+  }
+
+  if (dry_run) {
+    return createSuccessResult({
+      mode: 'bulk',
+      dry_run: true,
+      source: { owner, repo, branch, directory: source_directory },
+      files: matchedFiles.map((f: any) => ({
+        filename: f.name,
+        artifact_name: deriveArtifactName(f.name),
+        size: f.size
+      })),
+      filter: extFilter,
+      target: { type: target_type, table: tableName },
+      message: `Dry run — would deploy ${matchedFiles.length} files.`
+    });
+  }
+
+  // Deploy each file as a separate artifact
+  const client = await getAuthenticatedClient(context);
+  const results: any[] = [];
+  let successCount = 0;
+  let failCount = 0;
+
+  // Determine which field to populate based on artifact type
+  const scriptField = getDefaultScriptField(tableName);
+
+  for (const file of matchedFiles) {
+    const filename = file.name || file.path?.split('/').pop();
+    const artifactName = deriveArtifactName(filename);
+    const filePath = source_directory.replace(/\/$/, '') + '/' + filename;
+
+    try {
+      // Fetch file content
+      const result = await proxyToolCall('github_get_content', {
+        owner, repo, path: filePath, ref: branch
+      });
+
+      let content: string;
+      if (result.content && result.encoding === 'base64') {
+        content = Buffer.from(result.content, 'base64').toString('utf-8');
+      } else if (typeof result.content === 'string') {
+        content = result.content;
+      } else if (typeof result === 'string') {
+        content = result;
+      } else {
+        results.push({ filename, artifact_name: artifactName, success: false, error: 'Unexpected response format' });
+        failCount++;
+        continue;
+      }
+
+      // Upsert to ServiceNow
+      const deployResult = await upsertArtifact(
+        client, context, tableName, target_type,
+        undefined, artifactName,
+        { [scriptField]: content, name: artifactName },
+        upsert
+      );
+
+      results.push({
+        filename,
+        artifact_name: artifactName,
+        success: true,
+        sys_id: deployResult.sys_id,
+        action: deployResult.action,
+        size: content.length
+      });
+      successCount++;
+    } catch (error: any) {
+      results.push({
+        filename,
+        artifact_name: artifactName,
+        success: false,
+        error: error.message
+      });
+      failCount++;
+    }
+  }
+
+  return createSuccessResult({
+    mode: 'bulk',
+    deployed: true,
+    source: { owner, repo, branch, directory: source_directory, filter: extFilter },
+    target: { type: target_type, table: tableName },
+    summary: {
+      total: matchedFiles.length,
+      success: successCount,
+      failed: failCount
+    },
+    results
+  });
+}
+
+// ==================== HELPER FUNCTIONS ====================
+
+/**
+ * Auto-detect the ServiceNow field based on file extension and artifact type
+ */
+function autoDetectField(filePath: string, tableName: string): string | null {
+  const ext = filePath.split('.').pop()?.toLowerCase();
+  const filename = filePath.split('/').pop()?.toLowerCase() || '';
+
+  // Check FILE_MAPPINGS for exact filename match
+  const mappings = FILE_MAPPINGS[tableName];
+  if (mappings) {
+    for (const [field, filenames] of Object.entries(mappings)) {
+      if ((filenames as string[]).some(f => filename === f || filename.endsWith(f))) {
+        return field;
+      }
+    }
+  }
+
+  // Fallback: extension-based detection
+  if (ext === 'html') return 'template';
+  if (ext === 'css') return 'css';
+  if (ext === 'json' && filename.includes('option')) return 'option_schema';
+  if (ext === 'js') return getDefaultScriptField(tableName);
+
+  return null;
+}
+
+/**
+ * Get the default script field name for a given table
+ */
+function getDefaultScriptField(tableName: string): string {
+  // Widgets use 'script' for server-side (confusingly, not 'server_script')
+  if (tableName === 'sp_widget') return 'script';
+  return 'script';
+}
+
+/**
+ * Derive artifact name from filename (strip extension)
+ */
+function deriveArtifactName(filename: string): string {
+  // Remove extension
+  const lastDot = filename.lastIndexOf('.');
+  return lastDot > 0 ? filename.substring(0, lastDot) : filename;
+}
+
+/**
+ * Find or create an artifact in ServiceNow
+ */
+async function upsertArtifact(
+  client: any,
+  context: ServiceNowContext,
+  tableName: string,
+  artifactType: string,
+  sysId: string | undefined,
+  identifier: string | undefined,
+  fields: Record<string, string>,
+  upsert: boolean
+): Promise<{ sys_id: string; name: string; action: 'created' | 'updated' }> {
+  const identifierField = ARTIFACT_IDENTIFIER_FIELD[tableName] || 'name';
+
+  // Try to find existing artifact
+  let existingArtifact: any = null;
+
+  if (sysId) {
+    try {
+      const response = await client.get(`/api/now/table/${tableName}/${sysId}`, {
+        params: { sysparm_fields: 'sys_id,name,id' }
+      });
+      existingArtifact = response.data.result;
+    } catch (e) {
+      // Not found by sys_id
+    }
+  }
+
+  if (!existingArtifact && identifier) {
+    const queryParts = [`${identifierField}=${identifier}`];
+    if (tableName === 'sp_widget') {
+      queryParts.push(`id=${identifier}`);
+    }
+    queryParts.push(`name=${identifier}`);
+
+    try {
+      const response = await client.get(`/api/now/table/${tableName}`, {
+        params: {
+          sysparm_query: queryParts.join('^OR'),
+          sysparm_fields: 'sys_id,name,id',
+          sysparm_limit: 1
+        }
+      });
+
+      if (response.data.result && response.data.result.length > 0) {
+        existingArtifact = response.data.result[0];
+      }
+    } catch (e) {
+      // Not found
+    }
+  }
+
+  if (existingArtifact) {
+    // Update existing
+    const updateResponse = await client.patch(
+      `/api/now/table/${tableName}/${existingArtifact.sys_id}`,
+      fields
+    );
+    return {
+      sys_id: existingArtifact.sys_id,
+      name: updateResponse.data.result?.name || existingArtifact.name || existingArtifact.id || identifier || '',
+      action: 'updated'
+    };
+  }
+
+  if (!upsert) {
+    throw new Error(`Artifact '${identifier || sysId}' not found and upsert=false.`);
+  }
+
+  // Create new artifact
+  // Ensure identifier fields are set
+  const createData: Record<string, any> = { ...fields };
+  if (identifier) {
+    if (identifierField === 'id') {
+      createData.id = identifier;
+      if (!createData.name) createData.name = identifier;
+    } else {
+      createData[identifierField] = identifier;
+    }
+  }
+
+  const createResponse = await client.post(`/api/now/table/${tableName}`, createData);
+  const created = createResponse.data.result;
+
+  return {
+    sys_id: created.sys_id,
+    name: created.name || created.id || identifier || '',
+    action: 'created'
+  };
+}
+
+export const version = '1.0.0';
+export const author = 'Snow-Flow Enterprise GitHub Pipeline';

package/src/servicenow/servicenow-mcp-unified/tools/deployment/snow_github_tree.ts

@@ -0,0 +1,120 @@
+/**
+ * snow_github_tree - GitHub Repository Tree Browser (Enterprise)
+ *
+ * Retrieves directory structure of a GitHub repository via the enterprise proxy.
+ * Returns metadata only (paths, types, sizes) — no file content enters the LLM context.
+ *
+ * Requires enterprise license with 'github' feature enabled.
+ * GitHub PAT is managed server-side via the enterprise portal.
+ */
+
+import { MCPToolDefinition, ServiceNowContext, ToolResult } from '../../shared/types.js';
+import { createSuccessResult, createErrorResult } from '../../shared/error-handler.js';
+import { proxyToolCall } from '../../../enterprise-proxy/proxy.js';
+
+export const toolDefinition: MCPToolDefinition = {
+  name: 'snow_github_tree',
+  description: `Browse GitHub repository structure via enterprise proxy. Returns metadata only (paths, types, sizes) — no file content in LLM context.
+
+Use this to explore a repo before deploying files with snow_github_deploy.
+
+Requires: Enterprise license with 'github' feature. GitHub PAT is managed server-side.`,
+  category: 'development',
+  subcategory: 'deployment',
+  use_cases: ['github', 'deployment', 'browse', 'repository'],
+  complexity: 'beginner',
+  frequency: 'medium',
+
+  permission: 'read',
+  allowedRoles: ['developer', 'stakeholder', 'admin'],
+  inputSchema: {
+    type: 'object',
+    properties: {
+      owner: {
+        type: 'string',
+        description: 'GitHub owner or organization (e.g. "groeimetai")'
+      },
+      repo: {
+        type: 'string',
+        description: 'Repository name (e.g. "snow-flow")'
+      },
+      path: {
+        type: 'string',
+        description: 'Subdirectory path to browse (default: root "/")'
+      },
+      branch: {
+        type: 'string',
+        description: 'Branch name (default: "main")'
+      }
+    },
+    required: ['owner', 'repo']
+  }
+};
+
+export async function execute(args: any, context: ServiceNowContext): Promise<ToolResult> {
+  const { owner, repo, path: dirPath, branch } = args;
+
+  // Enterprise feature gate
+  if (!context.enterprise?.features?.includes('github')) {
+    return createErrorResult(
+      'GitHub integration requires an enterprise license with the "github" feature enabled.\n\n' +
+      'Upgrade at https://portal.snow-flow.dev or contact support.'
+    );
+  }
+
+  try {
+    // Call enterprise proxy to get directory listing from GitHub API
+    const result = await proxyToolCall('github_get_content', {
+      owner,
+      repo,
+      path: dirPath || '/',
+      ref: branch || 'main'
+    });
+
+    // GitHub API returns an array for directories, an object for files
+    const entries = Array.isArray(result) ? result : [result];
+
+    // Filter to metadata only — strip file content
+    let totalSizeBytes = 0;
+    let fileCount = 0;
+    let dirCount = 0;
+
+    const tree = entries.map((entry: any) => {
+      const item: any = {
+        path: entry.path || entry.name,
+        type: entry.type,  // 'file' or 'dir'
+        size: entry.size || 0
+      };
+
+      if (entry.type === 'file') {
+        fileCount++;
+        totalSizeBytes += entry.size || 0;
+      } else if (entry.type === 'dir') {
+        dirCount++;
+      }
+
+      return item;
+    });
+
+    return createSuccessResult({
+      owner,
+      repo,
+      path: dirPath || '/',
+      branch: branch || 'main',
+      entries: tree,
+      summary: {
+        files: fileCount,
+        directories: dirCount,
+        total_size_bytes: totalSizeBytes
+      }
+    });
+
+  } catch (error: any) {
+    return createErrorResult(
+      `Failed to browse GitHub repository ${owner}/${repo}: ${error.message}`
+    );
+  }
+}
+
+export const version = '1.0.0';
+export const author = 'Snow-Flow Enterprise GitHub Pipeline';