sf-git-ai-meta-insights 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 1.0.0 (2026-04-12)
+
+
+### Features
+
+* init release ([3ef828a](https://github.com/mcarvin8/sf-git-ai-meta-insights/commit/3ef828abaca2649cf726c9295f8bb3095743fc2c))
+* **sgai:** llm gateway auth, diff size limits, and coverage ([4e5d5dc](https://github.com/mcarvin8/sf-git-ai-meta-insights/commit/4e5d5dc7ffcf7fc53ed0af2218d1e87c2ffcb195))
+
+
+### Bug Fixes
+
+* **deps:** bump @salesforce/sf-plugins-core from 12.0.11 to 12.2.6 ([#3](https://github.com/mcarvin8/sf-git-ai-meta-insights/issues/3)) ([2222526](https://github.com/mcarvin8/sf-git-ai-meta-insights/commit/22225267752a399095ae43e69f3f8f904381f084))
+* **deps:** bump openai from 5.23.2 to 6.34.0 ([#7](https://github.com/mcarvin8/sf-git-ai-meta-insights/issues/7)) ([0a03423](https://github.com/mcarvin8/sf-git-ai-meta-insights/commit/0a034230ee192fabc6e99e55d1a2a1560d4cbf43))
+
+

package/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Matthew Carvin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# sf-git-ai-meta-insights
+
+[![NPM](https://img.shields.io/npm/v/sf-git-ai-meta-insights.svg?label=sf-git-ai-meta-insights)](https://www.npmjs.com/package/sf-git-ai-meta-insights) [![Downloads/week](https://img.shields.io/npm/dw/sf-git-ai-meta-insights.svg)](https://npmjs.org/package/sf-git-ai-meta-insights) [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://raw.githubusercontent.com/salesforcecli/sf-git-ai-meta-insights/main/LICENSE.md)
+
+`sf-git-ai-meta-insights` is an `sf` plugin that generates AI-assisted summaries of Salesforce metadata changes from a git diff.
+
+## Overview
+
+This plugin summarizes metadata changes between two Git refs, optionally filters commits by message, and writes a Markdown summary file. When an **OpenAI-compatible** LLM gateway is configured (see below), it calls that HTTP API; otherwise it falls back to a local summary.
+
+## Installation
+
+```bash
+sf plugins install sf-git-ai-meta-insights@latest
+```
+
+## Command
+
+### `sf sgai metadata summarize`
+
+Summarize metadata changes between two Git refs and write the generated summary to a Markdown file.
+
+#### Flags
+
+- `--from` `-f` (**required**) Start reference for the git diff range. You must pass an explicit ref (for example `HEAD~1`, a tag, or a commit hash); there is no default.
+- `--to` `-t` End reference for the git diff range. Defaults to `HEAD`.
+- `--message-filter` `-m` Regex filter for commit messages.
+- `--team` Optional team or squad label for the summary (also supported via `METADATA_AUDIT_TEAM` or `SF_GIT_AI_TEAM`).
+- `--output` `-p` Output file path for the generated summary. Defaults to `metadata-summary.md`.
+- `--model` OpenAI model used for the summary. Defaults to `gpt-4o-mini`.
+- `--ignore-package-directory` `-i` Ignore package directories defined in `sfdx-project.json`. This flag may be provided multiple times.
+
+#### Examples
+
+Summarize changes since the previous commit:
+
+```bash
+sf sgai metadata summarize --from HEAD~1 --to HEAD
+```
+
+Summarize a custom range and save to `changes.md`:
+
+```bash
+sf sgai metadata summarize --from HEAD~5 --to HEAD --output changes.md
+```
+
+Summarize only commits whose messages match a regex:
+
+```bash
+sf sgai metadata summarize --from main --to HEAD --message-filter "(feature|fix)"
+```
+
+Use a custom OpenAI model:
+
+```bash
+sf sgai metadata summarize --from HEAD~1 --to HEAD --model gpt-4o-mini
+```
+
+## Requirements
+
+- `sf` CLI installed
+- Node.js 20 or later
+- A Salesforce DX project repository with a `sfdx-project.json` file present in the repo root
+- Optional: LLM configuration (see below)
+
+This plugin depends on running inside an SFDX project because it reads `packageDirectories` from `sfdx-project.json` to determine which metadata files from the git diff to include in the summary.
+
+If no LLM gateway is configured, the plugin still generates a local fallback summary.
+
+The plugin uses the official Node [`openai`](https://www.npmjs.com/package/openai) client: optional **`baseURL`**, optional **`defaultHeaders`** (JSON), and an API key string the SDK expects.
+
+### `LLM_*` overrides `OPENAI_*`
+
+| Variable                 | Purpose                                                                                     |
+| ------------------------ | ------------------------------------------------------------------------------------------- |
+| `OPENAI_API_KEY`         | Default API key for api.openai.com or your gateway.                                         |
+| `LLM_API_KEY`            | Overrides `OPENAI_API_KEY` when set.                                                        |
+| `OPENAI_BASE_URL`        | Default base URL (OpenAI-compatible).                                                       |
+| `LLM_BASE_URL`           | Overrides `OPENAI_BASE_URL` when set.                                                       |
+| `OPENAI_DEFAULT_HEADERS` | JSON object of extra HTTP headers (string values only).                                     |
+| `LLM_DEFAULT_HEADERS`    | JSON object merged **on top of** `OPENAI_DEFAULT_HEADERS` (same header names are replaced). |
+
+The OpenAI Node client always sends `Authorization: Bearer <apiKey>`. If you put a raw `sk-...` value in `LLM_DEFAULT_HEADERS` / `OPENAI_DEFAULT_HEADERS` as `Authorization` **without** `Bearer`, many gateways treat that as the final header and return errors like `401` with `param: api_key`. When `LLM_API_KEY` / `OPENAI_API_KEY` is unset, this plugin detects `Authorization: sk-...` or `Authorization: Bearer sk-...` in the merged JSON headers, moves that token into the client `apiKey` (so the SDK sends a proper `Bearer` value), and removes the duplicate `Authorization` entry from `defaultHeaders` while keeping your other headers (for example `x-alfa-rbac`).
+
+Prefer setting `LLM_API_KEY` (or `OPENAI_API_KEY`) to your `sk-...` token when your gateway documents API-key auth that way.
+
+**PowerShell: company gateway**
+
+```powershell
+$env:LLM_BASE_URL = "https://llm-gateway.mycompany.example/v1"
+$env:LLM_DEFAULT_HEADERS = '{"Authorization":"Bearer <token>","x-tenant-id":"salesforce"}'
+sf sgai metadata summarize --from HEAD~1 --to HEAD
+```
+
+### OpenAI (api.openai.com)
+
+Set `OPENAI_API_KEY` only, or `LLM_API_KEY` if you standardize on `LLM_*` in your environment.
+
+### Token limits
+
+`OPENAI_MAX_TOKENS` caps `max_tokens`; `LLM_MAX_TOKENS` overrides it when set.
+
+### Diff size (context window)
+
+The full unified diff is capped before it is sent to the LLM so requests stay within typical context limits (for example 128k tokens). If you see errors about context length exceeded, narrow `--from`/`--to`, use `--message-filter`, or lower `--max-diff-chars` / `LLM_MAX_DIFF_CHARS`. Only raise the cap when your model and gateway allow a larger context.
+
+## License
+
+MIT

package/lib/ai/metadataSummary.d.ts

@@ -0,0 +1,19 @@
+import type { CommitInfo } from '../git/gitDiff.js';
+import { type OpenAiLikeClient } from './openAiConfig.js';
+/** Resolve max unified-diff characters for the LLM path. CLI wins, then env, then default. */
+export declare function resolveLlmMaxDiffChars(cliOverride?: number): number;
+export declare function truncateUnifiedDiffForLlm(diffText: string, maxChars: number): string;
+export type SummarizeFlags = {
+    /** Start ref for the diff (required when invoking the CLI). */
+    from: string;
+    to?: string;
+    messageFilter?: string;
+    model?: string;
+    /** Optional team or squad label for the summary (CLI or env). */
+    team?: string;
+    /** Max characters of unified diff sent to the LLM (CLI); see `resolveLlmMaxDiffChars`. */
+    maxDiffChars?: number;
+};
+type OpenAiClientProvider = () => Promise<OpenAiLikeClient>;
+export declare function generateSummary(diffText: string, fileNames: string[], commits: CommitInfo[], flags: SummarizeFlags, openAiClientProvider?: OpenAiClientProvider): Promise<string>;
+export {};

package/lib/ai/metadataSummary.js

@@ -0,0 +1,129 @@
+import { createOpenAiLikeClient, shouldUseLlmGateway } from './openAiConfig.js';
+/**
+ * Cap on unified-diff characters sent to the LLM (only the diff body; preamble is extra).
+ * Tuned for ~128k-token context models; override with `LLM_MAX_DIFF_CHARS` or `--max-diff-chars`.
+ */
+const DEFAULT_LLM_MAX_DIFF_CHARS = 120_000;
+/** Resolve max unified-diff characters for the LLM path. CLI wins, then env, then default. */
+export function resolveLlmMaxDiffChars(cliOverride) {
+    if (cliOverride !== undefined && Number.isFinite(cliOverride) && cliOverride > 0) {
+        return Math.trunc(cliOverride);
+    }
+    const raw = process.env.LLM_MAX_DIFF_CHARS?.trim();
+    if (raw) {
+        const parsed = Number.parseInt(raw, 10);
+        if (Number.isFinite(parsed) && parsed > 0) {
+            return parsed;
+        }
+    }
+    return DEFAULT_LLM_MAX_DIFF_CHARS;
+}
+export function truncateUnifiedDiffForLlm(diffText, maxChars) {
+    if (diffText.length <= maxChars) {
+        return diffText;
+    }
+    const marker = `\n\n--- TRUNCATED: unified diff was ${diffText.length} characters; only the first ${maxChars} were sent. Narrow the ref range, use --message-filter, or raise --max-diff-chars / LLM_MAX_DIFF_CHARS only if your model context allows. ---\n`;
+    return diffText.slice(0, maxChars) + marker;
+}
+/** System prompt for OpenAI when summarizing whatever git range / filter the user requested. */
+const OPENAI_SYSTEM_PROMPT = `You are a senior Salesforce architect helping developers understand Salesforce metadata changes from the git context they supplied.
+You receive: commit subject lines (when available), changed metadata paths, and unified git patch(es) scoped to Salesforce metadata package directories—either one range diff or concatenated per-commit patches, depending on how the diff was produced. Patches may be truncated mid-section with an explicit marker—do not infer changes beyond visible lines.
+Explain what functionality changed: user-visible behavior, automations, integrations, data model, and security/access. Tie claims to the patch when possible.
+Produce a concise, developer-focused summary in Markdown.
+Use sections: Highlights, Risky or breaking changes, Data model changes, Automation & flows, Security & access.
+Group related changes; do not list every individual component or file. When multiple commits appear in the context, briefly separate notable themes by commit when helpful.`;
+function resolveSummaryTeam(flags) {
+    const fromFlag = flags.team?.trim();
+    if (fromFlag)
+        return fromFlag;
+    const auditTeam = process.env.METADATA_AUDIT_TEAM?.trim();
+    if (auditTeam)
+        return auditTeam;
+    const sfGitAiTeam = process.env.SF_GIT_AI_TEAM?.trim();
+    return sfGitAiTeam ?? undefined;
+}
+export async function generateSummary(diffText, fileNames, commits, flags, openAiClientProvider) {
+    const fileSection = fileNames.length
+        ? fileNames.map((name) => `- ${name}`).join('\n')
+        : '- No metadata files changed.';
+    if (shouldUseLlmGateway()) {
+        const maxDiffChars = resolveLlmMaxDiffChars(flags.maxDiffChars);
+        const diffForLlm = truncateUnifiedDiffForLlm(diffText, maxDiffChars);
+        const userContent = buildOpenAiUserContent(flags, commits, fileNames, diffForLlm);
+        return callOpenAi(userContent, flags.model ?? 'gpt-4o-mini', openAiClientProvider ??
+            /* istanbul ignore next */ (async () => createOpenAiLikeClient()));
+    }
+    return buildFallbackSummary(fileSection, commits, diffText, flags);
+}
+function buildOpenAiUserContent(flags, commits, fileNames, diffText) {
+    const from = flags.from;
+    const to = flags.to ?? 'HEAD';
+    const team = resolveSummaryTeam(flags);
+    const ts = new Date().toISOString();
+    const teamLine = team ? `Team: ${team}\n` : '';
+    const filterLine = flags.messageFilter
+        ? `Commit message filter (regex): ${flags.messageFilter}\nGit context shape: concatenated per-commit unified patches for matching commits only.\n`
+        : 'Commit message filter: none.\nGit context shape: single unified diff for the full ref range.\n';
+    const commitBlock = commits.length > 0
+        ? commits.map((c) => `- ${c.hash.slice(0, 7)} ${c.message.replace(/\r?\n/g, ' ')}`).join('\n')
+        : '- (no commits in range after filtering)';
+    const pathsBlock = fileNames.length > 0 ? fileNames.join('\n') : '(no metadata paths in diff scope)';
+    return (`${teamLine}` +
+        `Date: ${ts}\n\n` +
+        `Git refs: ${from}..${to}\n` +
+        filterLine +
+        '\n' +
+        '=== Included commits (subject lines) ===\n' +
+        `${commitBlock}\n\n` +
+        '=== Changed metadata paths ===\n' +
+        `${pathsBlock}\n\n` +
+        '=== Git context (unified diff(s) scoped to Salesforce metadata paths; patches may be truncated with an explicit marker) ===\n' +
+        diffText);
+}
+function buildFallbackSummary(fileSection, commits, diffText, flags) {
+    const filterText = flags.messageFilter
+        ? `Filtered by: \`${flags.messageFilter}\`\n\n`
+        : 'No commit message filter applied.\n\n';
+    const team = resolveSummaryTeam(flags);
+    const teamSection = team ? `## Team\n${team}\n\n` : '';
+    return ('# Metadata Change Summary\n\n' +
+        '## Range\n' +
+        `From: ${flags.from}\n` +
+        `To: ${flags.to ?? 'HEAD'}\n\n` +
+        teamSection +
+        '## Commit Filter\n' +
+        filterText +
+        `## Changed Files\n${fileSection}\n\n` +
+        '## Local Summary\n' +
+        'No LLM gateway was configured (set `OPENAI_API_KEY` or `LLM_API_KEY`, `OPENAI_BASE_URL` or `LLM_BASE_URL`, and/or `OPENAI_DEFAULT_HEADERS` / `LLM_DEFAULT_HEADERS`), so this is a local summary instead.\n\n' +
+        '### Commits\n' +
+        commits.map((commit) => `- ${commit.hash.slice(0, 7)} ${commit.message}`).join('\n') +
+        `\n\n### Diff Snippet\n\n${diffText.substring(0, 10_000)}`);
+}
+async function callOpenAi(userContent, model, openAiClientProvider) {
+    const client = await openAiClientProvider();
+    const maxTokensRaw = process.env.LLM_MAX_TOKENS ?? process.env.OPENAI_MAX_TOKENS;
+    const parsed = maxTokensRaw !== undefined ? Number.parseInt(maxTokensRaw, 10) : 4000;
+    const maxTokens = Number.isFinite(parsed) && parsed > 0 ? parsed : 4000;
+    const response = await client.chat.completions.create({
+        model,
+        messages: [
+            {
+                role: 'system',
+                content: OPENAI_SYSTEM_PROMPT,
+            },
+            {
+                role: 'user',
+                content: userContent,
+            },
+        ],
+        temperature: 0.2,
+        // OpenAI Chat Completions API uses snake_case for this field.
+        // eslint-disable-next-line camelcase -- matches OpenAI request body
+        max_tokens: maxTokens,
+    });
+    const typedResponse = response;
+    const text = typedResponse.choices?.[0]?.message?.content?.trim() ?? '';
+    return text.length > 0 ? text : 'No summary generated by OpenAI.';
+}
+//# sourceMappingURL=metadataSummary.js.map

package/lib/ai/metadataSummary.js.map

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

package/lib/ai/openAiConfig.d.ts

@@ -0,0 +1,38 @@
+/**
+ * OpenAI-compatible LLM gateways (OpenAI.com, Azure OpenAI, corporate proxies, etc.).
+ * `LLM_*` environment variables override matching `OPENAI_*` defaults where applicable.
+ */
+/** `LLM_BASE_URL` overrides `OPENAI_BASE_URL` when set. */
+export declare function resolveLlmBaseUrl(): string | undefined;
+/**
+ * Merged default headers: `OPENAI_DEFAULT_HEADERS` first, then `LLM_DEFAULT_HEADERS` overrides.
+ */
+export declare function parseLlmDefaultHeadersFromEnv(): Record<string, string> | undefined;
+/**
+ * OpenAI's Node SDK always sends `Authorization: Bearer ${apiKey}`.
+ * If `Authorization` is only present in `defaultHeaders` as a raw `sk-...` token (no Bearer),
+ * that header overrides the SDK value and many OpenAI-compatible gateways reject the request
+ * (`param: api_key`). When no `LLM_API_KEY` / `OPENAI_API_KEY` is set, promote recognizable
+ * tokens from `Authorization` into `apiKey` and drop that header from `defaultHeaders`.
+ */
+export declare function splitPromotableAuthorizationFromHeaders(headers: Record<string, string>): {
+    defaultHeaders: Record<string, string>;
+    apiKeyFromAuthHeader?: string;
+};
+export declare function shouldUseLlmGateway(): boolean;
+export type OpenAiLikeClient = {
+    chat: {
+        completions: {
+            create(...options: unknown[]): Promise<unknown>;
+        };
+    };
+};
+/** Constructor-style options for the official OpenAI Node SDK (for tests and `createOpenAiLikeClient`). */
+export type OpenAiLikeClientInit = {
+    apiKey: string;
+    baseURL?: string;
+    defaultHeaders?: Record<string, string>;
+};
+export declare function resolveOpenAiLikeClientInit(): OpenAiLikeClientInit;
+/** Build options for `new OpenAI(...)` (official OpenAI Node SDK). */
+export declare function createOpenAiLikeClient(): Promise<OpenAiLikeClient>;

package/lib/ai/openAiConfig.js

@@ -0,0 +1,112 @@
+/**
+ * OpenAI-compatible LLM gateways (OpenAI.com, Azure OpenAI, corporate proxies, etc.).
+ * `LLM_*` environment variables override matching `OPENAI_*` defaults where applicable.
+ */
+/** `LLM_BASE_URL` overrides `OPENAI_BASE_URL` when set. */
+export function resolveLlmBaseUrl() {
+    return process.env.LLM_BASE_URL?.trim() ?? process.env.OPENAI_BASE_URL?.trim();
+}
+function parseHeaderJsonObject(raw) {
+    const trimmed = raw?.trim();
+    if (!trimmed)
+        return {};
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            return {};
+        }
+        const out = {};
+        for (const [key, value] of Object.entries(parsed)) {
+            if (typeof value === 'string' && value.length > 0) {
+                out[key] = value;
+            }
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Merged default headers: `OPENAI_DEFAULT_HEADERS` first, then `LLM_DEFAULT_HEADERS` overrides.
+ */
+export function parseLlmDefaultHeadersFromEnv() {
+    const base = parseHeaderJsonObject(process.env.OPENAI_DEFAULT_HEADERS);
+    const override = parseHeaderJsonObject(process.env.LLM_DEFAULT_HEADERS);
+    const merged = { ...base, ...override };
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+function findAuthorizationHeaderName(headers) {
+    return Object.keys(headers).find((k) => k.toLowerCase() === 'authorization');
+}
+/** Strip a single `Bearer <token>` prefix; otherwise return the trimmed value. */
+function stripBearerPrefix(value) {
+    const trimmed = value.trim();
+    const match = /^Bearer\s+(\S+)/i.exec(trimmed);
+    return match?.[1] ?? trimmed;
+}
+/**
+ * OpenAI's Node SDK always sends `Authorization: Bearer ${apiKey}`.
+ * If `Authorization` is only present in `defaultHeaders` as a raw `sk-...` token (no Bearer),
+ * that header overrides the SDK value and many OpenAI-compatible gateways reject the request
+ * (`param: api_key`). When no `LLM_API_KEY` / `OPENAI_API_KEY` is set, promote recognizable
+ * tokens from `Authorization` into `apiKey` and drop that header from `defaultHeaders`.
+ */
+export function splitPromotableAuthorizationFromHeaders(headers) {
+    const authName = findAuthorizationHeaderName(headers);
+    if (!authName) {
+        return { defaultHeaders: headers };
+    }
+    const raw = headers[authName];
+    if (!raw) {
+        return { defaultHeaders: headers };
+    }
+    const token = stripBearerPrefix(raw);
+    const looksBearer = /^Bearer\s+\S+/i.test(raw.trim());
+    const looksOpenAiKey = /^sk-/i.test(token);
+    if (!looksBearer && !looksOpenAiKey) {
+        return { defaultHeaders: headers };
+    }
+    const next = { ...headers };
+    delete next[authName];
+    return { defaultHeaders: next, apiKeyFromAuthHeader: token };
+}
+export function shouldUseLlmGateway() {
+    const apiKey = process.env.LLM_API_KEY?.trim() ?? process.env.OPENAI_API_KEY?.trim();
+    if (apiKey)
+        return true;
+    if (resolveLlmBaseUrl())
+        return true;
+    const jsonHeaders = parseLlmDefaultHeadersFromEnv();
+    if (jsonHeaders && Object.keys(jsonHeaders).length > 0)
+        return true;
+    return false;
+}
+export function resolveOpenAiLikeClientInit() {
+    const baseURL = resolveLlmBaseUrl();
+    const mergedHeaders = parseLlmDefaultHeadersFromEnv() ?? {};
+    const envApiKey = process.env.LLM_API_KEY?.trim() ?? process.env.OPENAI_API_KEY?.trim() ?? '';
+    let defaultHeaders;
+    let apiKey = envApiKey;
+    if (apiKey.length === 0) {
+        const split = splitPromotableAuthorizationFromHeaders(mergedHeaders);
+        if (split.apiKeyFromAuthHeader) {
+            apiKey = split.apiKeyFromAuthHeader;
+        }
+        defaultHeaders = Object.keys(split.defaultHeaders).length > 0 ? split.defaultHeaders : undefined;
+    }
+    else {
+        defaultHeaders = Object.keys(mergedHeaders).length > 0 ? mergedHeaders : undefined;
+    }
+    return {
+        apiKey: apiKey.length > 0 ? apiKey : 'unused',
+        ...(baseURL ? { baseURL } : {}),
+        ...(defaultHeaders ? { defaultHeaders } : {}),
+    };
+}
+/** Build options for `new OpenAI(...)` (official OpenAI Node SDK). */
+export async function createOpenAiLikeClient() {
+    const { default: OpenAI } = await import('openai');
+    return new OpenAI(resolveOpenAiLikeClientInit());
+}
+//# sourceMappingURL=openAiConfig.js.map

package/lib/ai/openAiConfig.js.map

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

package/lib/commands/sgai/metadata/summarize.d.ts

@@ -0,0 +1,20 @@
+import { SfCommand } from '@salesforce/sf-plugins-core';
+export type SgaiMetadataSummarizeResult = {
+    path: string;
+};
+export default class SgaiMetadataSummarize extends SfCommand<SgaiMetadataSummarizeResult> {
+    static readonly summary: string;
+    static readonly description: string;
+    static readonly examples: string[];
+    static readonly flags: {
+        from: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        to: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'message-filter': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        team: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        model: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'max-diff-chars': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'ignore-package-directory': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<SgaiMetadataSummarizeResult>;
+}

package/lib/commands/sgai/metadata/summarize.js

@@ -0,0 +1,110 @@
+import { writeFile } from 'node:fs/promises';
+import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
+import { Messages, SfError } from '@salesforce/core';
+import { createGitClient, filterCommits, getCommits, getDiff, getChangedFiles } from '../../../git/gitDiff.js';
+import { generateSummary } from '../../../ai/metadataSummary.js';
+Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
+const messages = Messages.loadMessages('sf-git-ai-meta-insights', 'sgai.metadata.summarize');
+export default class SgaiMetadataSummarize extends SfCommand {
+    static summary = messages.getMessage('summary');
+    static description = messages.getMessage('description');
+    static examples = messages.getMessages('examples');
+    static flags = {
+        from: Flags.string({
+            summary: messages.getMessage('flags.from.summary'),
+            description: messages.getMessage('flags.from.description'),
+            char: 'f',
+            required: true,
+        }),
+        to: Flags.string({
+            summary: messages.getMessage('flags.to.summary'),
+            description: messages.getMessage('flags.to.description'),
+            char: 't',
+            required: false,
+        }),
+        'message-filter': Flags.string({
+            summary: messages.getMessage('flags.message-filter.summary'),
+            description: messages.getMessage('flags.message-filter.description'),
+            char: 'm',
+            required: false,
+        }),
+        team: Flags.string({
+            summary: messages.getMessage('flags.team.summary'),
+            description: messages.getMessage('flags.team.description'),
+            required: false,
+        }),
+        output: Flags.string({
+            summary: messages.getMessage('flags.output.summary'),
+            description: messages.getMessage('flags.output.description'),
+            char: 'p',
+            required: false,
+            default: 'metadata-summary.md',
+        }),
+        model: Flags.string({
+            summary: messages.getMessage('flags.model.summary'),
+            description: messages.getMessage('flags.model.description'),
+            required: false,
+            default: 'gpt-4o-mini',
+        }),
+        'max-diff-chars': Flags.integer({
+            summary: messages.getMessage('flags.max-diff-chars.summary'),
+            description: messages.getMessage('flags.max-diff-chars.description'),
+            required: false,
+        }),
+        'ignore-package-directory': Flags.directory({
+            summary: messages.getMessage('flags.ignore-package-directory.summary'),
+            description: messages.getMessage('flags.ignore-package-directory.description'),
+            char: 'i',
+            required: false,
+            multiple: true,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(SgaiMetadataSummarize);
+        const maxDiffCharsFlag = flags['max-diff-chars'];
+        if (maxDiffCharsFlag !== undefined && (maxDiffCharsFlag < 5000 || maxDiffCharsFlag > 5_000_000)) {
+            throw new SfError(`--max-diff-chars must be between 5000 and 5,000,000 (received ${maxDiffCharsFlag}).`, 'InvalidMaxDiffChars');
+        }
+        const from = flags.from;
+        const to = flags.to ?? 'HEAD';
+        const outputPath = flags.output ?? 'metadata-summary.md';
+        const ignorePackageDirectories = Array.isArray(flags['ignore-package-directory'])
+            ? flags['ignore-package-directory'].filter(Boolean)
+            : flags['ignore-package-directory']
+                ? [flags['ignore-package-directory']]
+                : undefined;
+        const git = createGitClient(process.cwd());
+        const commits = await getCommits(git, from, to);
+        let filteredCommits;
+        try {
+            filteredCommits = filterCommits(commits, flags['message-filter']);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (message.includes('Invalid commit message filter')) {
+                throw new SfError(message, 'InvalidMessageFilter');
+            }
+            throw err;
+        }
+        if (flags['message-filter'] && filteredCommits.length === 0) {
+            const message = `No commits matched the filter '${flags['message-filter']}' between ${from} and ${to}.`;
+            await writeFile(outputPath, `# Metadata Summary\n\n${message}\n`, 'utf8');
+            this.log(`Generated metadata summary at ${outputPath}`);
+            return { path: outputPath };
+        }
+        const diffText = await getDiff(git, from, to, filteredCommits, Boolean(flags['message-filter']), ignorePackageDirectories);
+        const fileNames = await getChangedFiles(git, from, to, filteredCommits, Boolean(flags['message-filter']), ignorePackageDirectories);
+        const summary = await generateSummary(diffText, fileNames, filteredCommits, {
+            from,
+            to: flags.to,
+            messageFilter: flags['message-filter'],
+            model: flags.model,
+            team: flags.team,
+            maxDiffChars: maxDiffCharsFlag,
+        });
+        await writeFile(outputPath, summary, 'utf8');
+        this.log(`Generated metadata summary at ${outputPath}`);
+        return { path: outputPath };
+    }
+}
+//# sourceMappingURL=summarize.js.map

package/lib/commands/sgai/metadata/summarize.js.map

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

package/lib/git/gitDiff.d.ts

@@ -0,0 +1,11 @@
+import type { SimpleGit } from 'simple-git';
+export type CommitInfo = {
+    hash: string;
+    message: string;
+};
+export declare function createGitClient(cwd?: string): SimpleGit;
+export declare function getCommits(git: SimpleGit, from: string, to: string): Promise<CommitInfo[]>;
+export declare function filterCommits(commits: CommitInfo[], messageFilter?: string): CommitInfo[];
+export declare function getRepoRoot(git: SimpleGit): Promise<string>;
+export declare function getDiff(git: SimpleGit, from: string, to: string, commits: CommitInfo[], filterByCommits: boolean, ignorePackageDirectories?: string[], repoRootOverride?: string): Promise<string>;
+export declare function getChangedFiles(git: SimpleGit, from: string, to: string, commits: CommitInfo[], filterByCommits: boolean, ignorePackageDirectories?: string[], repoRootOverride?: string): Promise<string[]>;