@openforge-app/plugin-sdk 0.1.0

package/dist/domain.js

@@ -0,0 +1,323 @@
+export function isClosedOrMergedPullRequest(state) {
+    return state === 'closed' || state === 'merged';
+}
+export function isMergedPullRequest(pr) {
+    return pr.state === 'merged' || pr.merged_at != null;
+}
+export function isClosedUnmergedPullRequest(pr) {
+    return pr.state === 'closed' && pr.merged_at == null;
+}
+export function hasMergeConflicts(pr) {
+    if (pr.state !== 'open')
+        return false;
+    const mergeableState = pr.mergeable_state?.toLowerCase() ?? null;
+    return mergeableState === 'dirty' || mergeableState === 'conflicting';
+}
+function mergeReadinessDetail(code, message) {
+    return { code, message };
+}
+function mergeReadinessResult(pr, status, action, blockers, warnings) {
+    return {
+        status,
+        action,
+        blockers,
+        warnings,
+        freshness: {
+            sourceSha: pr.head_sha ?? null,
+            checkedAt: pr.updated_at ?? null,
+        },
+    };
+}
+const MERGE_READINESS_STATUSES = [
+    'ready_to_merge',
+    'ready_to_enqueue',
+    'queued_pull_request',
+    'readiness_unknown',
+    'blocked',
+];
+const MERGE_READINESS_ACTIONS = [
+    'merge',
+    'enqueue',
+    'wait_for_queue',
+    'wait_for_github',
+    'resolve_blockers',
+];
+function isMergeReadinessStatus(value) {
+    return MERGE_READINESS_STATUSES.includes(value);
+}
+function isMergeReadinessAction(value) {
+    return MERGE_READINESS_ACTIONS.includes(value);
+}
+function parseMergeReadinessDetails(value) {
+    if (Array.isArray(value))
+        return value;
+    if (!value)
+        return [];
+    try {
+        const parsed = JSON.parse(value);
+        return Array.isArray(parsed)
+            ? parsed.filter((detail) => typeof detail?.code === 'string' && typeof detail?.message === 'string')
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+function isUnresolvedConversationDetail(detail) {
+    return detail.code === 'unresolved_conversations';
+}
+function hasNoPublishedChecksForUnstableMergeability(pr) {
+    const mergeableState = pr.mergeable_state?.toLowerCase() ?? null;
+    const ciStatus = pr.ci_status?.toLowerCase() ?? null;
+    return mergeableState === 'unstable' && (ciStatus === null || ciStatus === 'none');
+}
+function downgradeNoCheckPersistedFailures(pr, blockers) {
+    if (!hasNoPublishedChecksForUnstableMergeability(pr))
+        return blockers;
+    return blockers.map((blocker) => blocker.code === 'checks_failed'
+        ? mergeReadinessDetail('checks_pending', 'Required checks are still running.')
+        : blocker);
+}
+function removeUnresolvedConversationDetails(details) {
+    return details.filter((detail) => !isUnresolvedConversationDetail(detail));
+}
+function shouldIgnorePersistedUnresolvedConversationDetails(pr, blockers, warnings) {
+    return pr.unaddressed_comment_count === 0
+        && (blockers.some(isUnresolvedConversationDetail) || warnings.some(isUnresolvedConversationDetail));
+}
+function isPersistedMergeReadinessCurrent(pr) {
+    const sourceSha = pr.readiness_source_head_sha ?? null;
+    const headSha = pr.head_sha ?? null;
+    if (!sourceSha || !headSha || sourceSha !== headSha)
+        return false;
+    const checkedAt = pr.readiness_updated_at ?? null;
+    const updatedAt = pr.updated_at ?? null;
+    return checkedAt !== null && (updatedAt === null || checkedAt >= updatedAt);
+}
+export function getPersistedMergeReadiness(pr) {
+    const status = pr.merge_readiness_status ?? null;
+    const action = pr.merge_readiness_action ?? null;
+    if (!isMergeReadinessStatus(status) || !isMergeReadinessAction(action))
+        return null;
+    if (!isPersistedMergeReadinessCurrent(pr))
+        return null;
+    let blockers = downgradeNoCheckPersistedFailures(pr, parseMergeReadinessDetails(pr.merge_readiness_blockers));
+    let warnings = parseMergeReadinessDetails(pr.merge_readiness_warnings);
+    if (shouldIgnorePersistedUnresolvedConversationDetails(pr, blockers, warnings)) {
+        blockers = removeUnresolvedConversationDetails(blockers);
+        warnings = removeUnresolvedConversationDetails(warnings);
+        if (status === 'blocked' && blockers.length === 0)
+            return null;
+    }
+    return {
+        status,
+        action,
+        blockers,
+        warnings,
+        freshness: {
+            sourceSha: pr.readiness_source_head_sha ?? null,
+            checkedAt: pr.readiness_updated_at ?? null,
+        },
+    };
+}
+function hasMergeReadinessOptions(options) {
+    return options.requireBranchUpToDate === true
+        || options.requireConversationResolution === true
+        || options.requireMergeQueue === true;
+}
+/**
+ * Explains whether a pull request is ready for a direct merge, queue enqueueing,
+ * waiting on GitHub/merge queue, or blocked by hard requirements.
+ */
+export function getMergeReadiness(pr, options = {}) {
+    const warnings = [];
+    const blockers = [];
+    if (pr.state !== 'open') {
+        blockers.push(mergeReadinessDetail(pr.state === 'merged' ? 'already_merged' : 'pull_request_closed', pr.state === 'merged' ? 'Pull request is already merged.' : 'Pull request is closed.'));
+        return mergeReadinessResult(pr, 'blocked', 'resolve_blockers', blockers, warnings);
+    }
+    const persisted = hasMergeReadinessOptions(options) ? null : getPersistedMergeReadiness(pr);
+    if (persisted)
+        return persisted;
+    const mergeableState = pr.mergeable_state?.toLowerCase() ?? null;
+    const ciStatus = pr.ci_status?.toLowerCase() ?? null;
+    const reviewStatus = pr.review_status?.toLowerCase() ?? null;
+    const unaddressedCommentCount = pr.unaddressed_comment_count ?? 0;
+    if (pr.draft === true) {
+        blockers.push(mergeReadinessDetail('draft', 'Pull request is still marked as draft.'));
+    }
+    if (reviewStatus === 'changes_requested') {
+        blockers.push(mergeReadinessDetail('changes_requested', 'Review changes have been requested.'));
+    }
+    if (ciStatus === 'pending' || ciStatus === 'queued' || ciStatus === 'in_progress') {
+        blockers.push(mergeReadinessDetail('checks_pending', 'Required checks are still running.'));
+    }
+    else if (ciStatus === 'failure' || ciStatus === 'error' || ciStatus === 'cancelled' || ciStatus === 'timed_out' || ciStatus === 'action_required') {
+        blockers.push(mergeReadinessDetail('checks_failed', 'Required checks are failing.'));
+    }
+    const hasFailedChecks = blockers.some((blocker) => blocker.code === 'checks_failed');
+    const hasPendingChecks = blockers.some((blocker) => blocker.code === 'checks_pending');
+    if (mergeableState === 'unstable' && !hasFailedChecks && !hasPendingChecks) {
+        blockers.push(hasNoPublishedChecksForUnstableMergeability(pr)
+            ? mergeReadinessDetail('checks_pending', 'Required checks are still running.')
+            : mergeReadinessDetail('checks_failed', 'GitHub reports failing or unstable required checks.'));
+    }
+    if (mergeableState === 'dirty' || mergeableState === 'conflicting') {
+        blockers.push(mergeReadinessDetail('merge_conflict', 'Pull request has merge conflicts.'));
+    }
+    else if (mergeableState === 'blocked') {
+        blockers.push(mergeReadinessDetail('mergeability_blocked', 'GitHub reports that mergeability is blocked.'));
+    }
+    else if (mergeableState === 'behind') {
+        if (options.requireBranchUpToDate === true) {
+            blockers.push(mergeReadinessDetail('branch_out_of_date', 'Branch must be updated before merging.'));
+        }
+        else {
+            warnings.push(mergeReadinessDetail('branch_behind', 'Branch is behind the base branch.'));
+        }
+    }
+    if (unaddressedCommentCount > 0) {
+        const detail = mergeReadinessDetail('unresolved_conversations', 'Pull request has unresolved conversations.');
+        if (options.requireConversationResolution === true) {
+            blockers.push(detail);
+        }
+        else {
+            warnings.push(detail);
+        }
+    }
+    if (blockers.length > 0) {
+        return mergeReadinessResult(pr, 'blocked', 'resolve_blockers', blockers, warnings);
+    }
+    if (pr.is_queued === true) {
+        return mergeReadinessResult(pr, 'queued_pull_request', 'wait_for_queue', blockers, warnings);
+    }
+    const hasDirectMergeability = mergeableState === 'clean' || mergeableState === 'behind';
+    const hasNoCiStatus = ciStatus === null || ciStatus === 'none';
+    const hasNoReviewStatus = reviewStatus === null || reviewStatus === 'none';
+    const isUnprotectedFallback = mergeableState === null && pr.mergeable === true && hasNoCiStatus && hasNoReviewStatus;
+    if (isUnprotectedFallback) {
+        warnings.push(mergeReadinessDetail('unprotected_fallback', 'Using simple mergeability because no protected-branch checks or review state are available.'));
+    }
+    if (hasDirectMergeability || isUnprotectedFallback) {
+        return mergeReadinessResult(pr, options.requireMergeQueue === true ? 'ready_to_enqueue' : 'ready_to_merge', options.requireMergeQueue === true ? 'enqueue' : 'merge', blockers, warnings);
+    }
+    if (mergeableState === 'unknown' || pr.mergeable === null || (mergeableState === null && pr.mergeable !== false)) {
+        warnings.push(mergeReadinessDetail('mergeability_unknown', 'GitHub has not reported definitive mergeability yet.'));
+        return mergeReadinessResult(pr, 'readiness_unknown', 'wait_for_github', blockers, warnings);
+    }
+    blockers.push(mergeReadinessDetail('mergeability_blocked', 'Pull request is not mergeable.'));
+    return mergeReadinessResult(pr, 'blocked', 'resolve_blockers', blockers, warnings);
+}
+/** Check if a PR is ready for a direct merge action. */
+export function isReadyToMerge(pr, options) {
+    const readiness = getMergeReadiness(pr, options);
+    return readiness.status === 'ready_to_merge' && readiness.action === 'merge';
+}
+/** Check if a user-initiated merge affordance may be shown/executed now. */
+export function canMergePullRequest(pr) {
+    const readiness = getMergeReadiness(pr);
+    return readiness.status === 'ready_to_merge' && readiness.action === 'merge';
+}
+/** Check if a user-initiated merge-queue enqueue affordance may be shown/executed now. */
+export function canEnqueuePullRequest(pr) {
+    const readiness = getMergeReadiness(pr);
+    return readiness.status === 'ready_to_enqueue' && readiness.action === 'enqueue';
+}
+function mergeReadinessPriority(pr) {
+    if (pr.state !== 'open')
+        return pr.state === 'merged' ? 100 : 90;
+    const readiness = getMergeReadiness(pr);
+    switch (readiness.status) {
+        case 'ready_to_merge': return 600;
+        case 'ready_to_enqueue': return 590;
+        case 'blocked': {
+            const blockerCodes = new Set(readiness.blockers.map((blocker) => blocker.code));
+            return blockerCodes.size === 1 && blockerCodes.has('checks_pending') ? 350 : 500;
+        }
+        case 'readiness_unknown': return 300;
+        case 'queued_pull_request': return 250;
+    }
+}
+export function getMostAttentionWorthyPullRequest(prs) {
+    let best = null;
+    let bestPriority = Number.NEGATIVE_INFINITY;
+    for (const pr of prs) {
+        const priority = mergeReadinessPriority(pr);
+        if (priority > bestPriority) {
+            best = pr;
+            bestPriority = priority;
+        }
+    }
+    return best;
+}
+/** Check if GitHub reports a PR as queued in a merge queue. */
+export function isQueuedForMerge(pr) {
+    return pr.state === 'open' && pr.is_queued;
+}
+/** Preserves optimistic and definitive states across transient background syncs */
+export function preservePullRequestState(oldPr, newPr) {
+    if (!oldPr)
+        return newPr;
+    const result = { ...newPr };
+    // Preserve irreversible merged state if new PR hasn't caught up.
+    // Closed-but-unmerged PRs can be reopened, so a fresh open state must win.
+    if (oldPr.state === 'merged' && result.state === 'open') {
+        result.state = 'merged';
+        result.merged_at = oldPr.merged_at;
+    }
+    // Preserve definitive mergeability if new state is transient
+    const isTransient = result.mergeable === null || result.mergeable_state === 'unknown' || result.mergeable_state === null;
+    const oldIsDefinitive = oldPr.mergeable_state !== 'unknown' && oldPr.mergeable_state !== null;
+    if (isTransient && oldIsDefinitive) {
+        result.mergeable = oldPr.mergeable;
+        result.mergeable_state = oldPr.mergeable_state;
+    }
+    const oldReadiness = getPersistedMergeReadiness(oldPr);
+    const newReadiness = getPersistedMergeReadiness(result);
+    const sameReadinessSource = (oldPr.readiness_source_head_sha ?? oldPr.head_sha ?? null) === (result.readiness_source_head_sha ?? result.head_sha ?? null);
+    const newReadinessIsTransient = newReadiness === null || newReadiness.status === 'readiness_unknown';
+    if (sameReadinessSource && oldReadiness && oldReadiness.status !== 'readiness_unknown' && newReadinessIsTransient) {
+        result.merge_readiness_status = oldPr.merge_readiness_status;
+        result.merge_readiness_action = oldPr.merge_readiness_action;
+        result.merge_readiness_blockers = oldPr.merge_readiness_blockers;
+        result.merge_readiness_warnings = oldPr.merge_readiness_warnings;
+        result.readiness_source_head_sha = oldPr.readiness_source_head_sha;
+        result.readiness_updated_at = oldPr.readiness_updated_at;
+        result.merge_group_sha = oldPr.merge_group_sha;
+        result.required_checks_policy_known = oldPr.required_checks_policy_known;
+        result.required_reviews_policy_known = oldPr.required_reviews_policy_known;
+        result.merge_queue_required = oldPr.merge_queue_required;
+        result.merge_queue_state = oldPr.merge_queue_state;
+    }
+    return result;
+}
+/** GitHub label that suppresses a PR from review counting and grays out its card. */
+export const DO_NOT_REVIEW_LABEL = 'DO NOT REVIEW';
+/** True when the PR carries the "DO NOT REVIEW" label (case-insensitive, trimmed). */
+export function hasDoNotReviewLabel(pr) {
+    return (pr.labels ?? []).some((label) => label.name.trim().toUpperCase() === DO_NOT_REVIEW_LABEL);
+}
+export function parseCheckRuns(json) {
+    if (!json)
+        return [];
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return [];
+    }
+}
+/** Split check runs into visible (non-passing) and a count of hidden passing checks. */
+export function splitCheckRuns(checks) {
+    const visible = [];
+    let passingCount = 0;
+    for (const check of checks) {
+        if (check.status === 'completed' && check.conclusion === 'success') {
+            passingCount++;
+        }
+        else {
+            visible.push(check);
+        }
+    }
+    return { visible, passingCount };
+}

package/dist/frontend.d.ts

@@ -0,0 +1,7 @@
+import type { CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, Disposable, FrontendBackendBridge, FrontendOpenForgeAPI, FrontendPlugin, FrontendPluginContext, FrontendSettingsRegistry, FrontendTaskPaneRegistry, FrontendViewRegistry, NavigationAPI, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, PluginSettingsSectionProps, PluginSettingsSectionRegistration, PluginStorageScope, PluginTaskPaneProps, PluginTaskPaneTabRegistration, PluginViewProps, PluginViewRegistration } from './types';
+export declare const OPENFORGE_FRONTEND_PLUGIN_MARKER = "__openforgeFrontendPlugin";
+export type MarkedFrontendPlugin<TPlugin extends FrontendPlugin = FrontendPlugin> = TPlugin & {
+    readonly [OPENFORGE_FRONTEND_PLUGIN_MARKER]: true;
+};
+export declare function defineFrontendPlugin<const TPlugin extends FrontendPlugin>(plugin: TPlugin): MarkedFrontendPlugin<TPlugin>;
+export type { CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, Disposable, FrontendBackendBridge, FrontendOpenForgeAPI, FrontendPlugin, FrontendPluginContext, FrontendSettingsRegistry, FrontendTaskPaneRegistry, FrontendViewRegistry, NavigationAPI, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, PluginSettingsSectionProps, PluginSettingsSectionRegistration, PluginStorageScope, PluginTaskPaneProps, PluginTaskPaneTabRegistration, PluginViewProps, PluginViewRegistration, };

package/dist/frontend.js

@@ -0,0 +1,9 @@
+export const OPENFORGE_FRONTEND_PLUGIN_MARKER = '__openforgeFrontendPlugin';
+export function defineFrontendPlugin(plugin) {
+    Object.defineProperty(plugin, OPENFORGE_FRONTEND_PLUGIN_MARKER, {
+        value: true,
+        enumerable: false,
+        configurable: false,
+    });
+    return plugin;
+}

package/dist/helpers.d.ts

@@ -0,0 +1,4 @@
+import type { OpenForgePackageMetadata, OpenForgePluginCapability } from './types';
+export declare function getRequiredOpenForgeCapabilities(metadata: OpenForgePackageMetadata): OpenForgePluginCapability[];
+export declare function hasFrontendEntry(metadata: OpenForgePackageMetadata): boolean;
+export declare function hasBackendEntry(metadata: OpenForgePackageMetadata): boolean;

package/dist/helpers.js

@@ -0,0 +1,9 @@
+export function getRequiredOpenForgeCapabilities(metadata) {
+    return metadata.requires ?? [];
+}
+export function hasFrontendEntry(metadata) {
+    return typeof metadata.frontend === 'string' && metadata.frontend.length > 0;
+}
+export function hasBackendEntry(metadata) {
+    return typeof metadata.backend === 'string' && metadata.backend.length > 0;
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { OPENFORGE_PACKAGE_METADATA_SCHEMA, OPENFORGE_PLUGIN_CAPABILITIES, isOpenForgePackageMetadata, isPluginPackageMetadata, isSupportedOpenForgeApiVersion, validateOpenForgePackageMetadata, validatePluginPackageMetadata, } from './manifest';
+export { createMemoryPluginStorage, createMockBackendOpenForgeApi, createMockFrontendOpenForgeApi, createMockOpenForgeApi, createMockPluginContext, createOpenForgeRegistryFake, createTestingCalls, TestingOpenForgeRegistryFake, TestingSubscriptionSink, } from './testing';
+export { MAX_SUPPORTED_API_VERSION, MIN_SUPPORTED_API_VERSION, OPENFORGE_PLUGIN_API_VERSION, SUPPORTED_OPENFORGE_API_VERSIONS, isPluginViewKey, makePluginViewKey, parsePluginViewKey, } from './types';
+export type { AttentionAPI, BackendReadyState, CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, ConfigureStartPromptContributionRequest, CreateTaskRequest, Disposable, FileSystemAPI, ImplementationRun, JsonObject, JsonPrimitive, JsonSchema, JsonValue, MaybePromise, KeyValueConfigAPI, NotificationRequest, NavigationAPI, NotificationsAPI, OpenForgeCommonAPI, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, OpenForgePackageMetadata, OpenForgePluginCapability, OpenForgePluginContext, OpenForgePluginPackageJson, PluginComponentLoader, PluginComponentModule, PluginEntry, PluginSettingsSectionProps, PluginState, PluginTaskPaneProps, PluginViewProps, PluginStorage, PluginStorageScope, PluginViewKey, ProjectsAPI, ShellAPI, ShellResizeRequest, ShellSessionRequest, ShellSpawnRequest, ShellWriteRequest, StartPromptContribution, StartTaskImplementationRequest, SubscriptionSink, SupportedOpenForgeApiVersion, SystemAPI, TasksAPI, ValidationError, } from './types';
+export type { MockBackendOpenForgeAPI, MockFrontendOpenForgeAPI, TestingBackgroundServiceContribution, TestingBackendMethodContribution, TestingCommandContribution, TestingContributionBase, TestingEventListenerContribution, TestingOpenForgeApiCalls, TestingOpenForgeApiOptions, TestingOpenForgeRegistrySnapshot, TestingRuntimeKind, TestingRuntimeScope, TestingSettingsSectionContribution, TestingTaskPaneTabContribution, TestingViewContribution, } from './testing';
+export { parseStrictFiniteNumber } from './numberParsing';
+export { buildProjectFileTree, flattenVisibleProjectFileTree, formatProjectFileTreeSize, getProjectFileTreeDepth, getProjectFileTreeItemAccessibility, getProjectFileTreeKeyboardAction, getProjectFileTreeParentPath, hasProjectFileTreeShortcutModifier, projectFileTreePathToId, } from './projectFileTree';
+export type { ProjectFileTreeEntry, ProjectFileTreeItemAccessibility, ProjectFileTreeKeyboardAction, ProjectFileTreeNode, } from './projectFileTree';
+export { canMergePullRequest, getMergeReadiness, hasMergeConflicts, isClosedUnmergedPullRequest, isMergedPullRequest, isQueuedForMerge, isReadyToMerge, parseCheckRuns, preservePullRequestState, splitCheckRuns, } from './domain';
+export type * from './domain';

package/dist/index.js

@@ -0,0 +1,6 @@
+export { OPENFORGE_PACKAGE_METADATA_SCHEMA, OPENFORGE_PLUGIN_CAPABILITIES, isOpenForgePackageMetadata, isPluginPackageMetadata, isSupportedOpenForgeApiVersion, validateOpenForgePackageMetadata, validatePluginPackageMetadata, } from './manifest';
+export { createMemoryPluginStorage, createMockBackendOpenForgeApi, createMockFrontendOpenForgeApi, createMockOpenForgeApi, createMockPluginContext, createOpenForgeRegistryFake, createTestingCalls, TestingOpenForgeRegistryFake, TestingSubscriptionSink, } from './testing';
+export { MAX_SUPPORTED_API_VERSION, MIN_SUPPORTED_API_VERSION, OPENFORGE_PLUGIN_API_VERSION, SUPPORTED_OPENFORGE_API_VERSIONS, isPluginViewKey, makePluginViewKey, parsePluginViewKey, } from './types';
+export { parseStrictFiniteNumber } from './numberParsing';
+export { buildProjectFileTree, flattenVisibleProjectFileTree, formatProjectFileTreeSize, getProjectFileTreeDepth, getProjectFileTreeItemAccessibility, getProjectFileTreeKeyboardAction, getProjectFileTreeParentPath, hasProjectFileTreeShortcutModifier, projectFileTreePathToId, } from './projectFileTree';
+export { canMergePullRequest, getMergeReadiness, hasMergeConflicts, isClosedUnmergedPullRequest, isMergedPullRequest, isQueuedForMerge, isReadyToMerge, parseCheckRuns, preservePullRequestState, splitCheckRuns, } from './domain';

package/dist/manifest.d.ts

@@ -0,0 +1,58 @@
+import type { OpenForgePackageMetadata, OpenForgePluginCapability, ValidationError } from './types';
+import { SUPPORTED_OPENFORGE_API_VERSIONS } from './types';
+export declare const OPENFORGE_PACKAGE_METADATA_SCHEMA: {
+    $schema: string;
+    $id: string;
+    title: string;
+    description: string;
+    type: string;
+    additionalProperties: boolean;
+    required: string[];
+    properties: {
+        id: {
+            type: string;
+            minLength: number;
+            pattern: string;
+            description: string;
+        };
+        apiVersion: {
+            enum: number[];
+        };
+        displayName: {
+            type: string;
+            minLength: number;
+        };
+        description: {
+            type: string;
+            minLength: number;
+        };
+        icon: {
+            type: string;
+            minLength: number;
+            description: string;
+        };
+        frontend: {
+            type: string;
+            minLength: number;
+            description: string;
+        };
+        backend: {
+            type: string;
+            minLength: number;
+            description: string;
+        };
+        requires: {
+            type: string;
+            uniqueItems: boolean;
+            items: {
+                enum: string[];
+            };
+        };
+    };
+};
+export declare const OPENFORGE_PLUGIN_CAPABILITIES: readonly OpenForgePluginCapability[];
+export declare function isSupportedOpenForgeApiVersion(apiVersion: unknown): apiVersion is (typeof SUPPORTED_OPENFORGE_API_VERSIONS)[number];
+export declare function validateOpenForgePackageMetadata(data: unknown): ValidationError[];
+export declare const validatePluginPackageMetadata: typeof validateOpenForgePackageMetadata;
+export declare function isOpenForgePackageMetadata(data: unknown): data is OpenForgePackageMetadata;
+export declare const isPluginPackageMetadata: typeof isOpenForgePackageMetadata;

package/dist/manifest.js

@@ -0,0 +1,93 @@
+import packageMetadataSchemaData from './openforgePackageMetadataSchema.json';
+import { SUPPORTED_OPENFORGE_API_VERSIONS } from './types';
+export const OPENFORGE_PACKAGE_METADATA_SCHEMA = packageMetadataSchemaData;
+export const OPENFORGE_PLUGIN_CAPABILITIES = packageMetadataSchemaData.properties.requires.items.enum;
+const CAPABILITIES = new Set(OPENFORGE_PLUGIN_CAPABILITIES);
+function isString(value) {
+    return typeof value === 'string';
+}
+function isNonEmptyString(value) {
+    return isString(value) && value.length > 0;
+}
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function validateRequiredString(value, path) {
+    if (!isNonEmptyString(value)) {
+        return [{ path, message: 'Required string' }];
+    }
+    return [];
+}
+function validateOptionalString(value, path) {
+    if (value === undefined) {
+        return [];
+    }
+    if (!isNonEmptyString(value)) {
+        return [{ path, message: 'Must be a non-empty string' }];
+    }
+    return [];
+}
+export function isSupportedOpenForgeApiVersion(apiVersion) {
+    return typeof apiVersion === 'number'
+        && Number.isInteger(apiVersion)
+        && SUPPORTED_OPENFORGE_API_VERSIONS.includes(apiVersion);
+}
+function validateApiVersion(value) {
+    if (typeof value !== 'number' || !Number.isInteger(value)) {
+        return [{ path: 'apiVersion', message: 'Required integer' }];
+    }
+    if (!isSupportedOpenForgeApiVersion(value)) {
+        return [{ path: 'apiVersion', message: `API version ${value} not supported (supported: ${SUPPORTED_OPENFORGE_API_VERSIONS.join(', ')})` }];
+    }
+    return [];
+}
+function validateRequires(value) {
+    const errors = [];
+    if (value === undefined) {
+        return errors;
+    }
+    if (!Array.isArray(value)) {
+        return [{ path: 'requires', message: 'Must be an array' }];
+    }
+    value.forEach((item, index) => {
+        const path = `requires[${index}]`;
+        if (!isString(item)) {
+            errors.push({ path, message: 'Must be a string' });
+            return;
+        }
+        if (!CAPABILITIES.has(item)) {
+            errors.push({ path, message: `Unknown OpenForge capability "${item}"` });
+        }
+    });
+    return errors;
+}
+export function validateOpenForgePackageMetadata(data) {
+    const errors = [];
+    if (!isObject(data)) {
+        return [{ path: '', message: 'OpenForge package metadata must be an object' }];
+    }
+    errors.push(...validateRequiredString(data.id, 'id'));
+    errors.push(...validateApiVersion(data.apiVersion));
+    errors.push(...validateRequiredString(data.displayName, 'displayName'));
+    errors.push(...validateRequiredString(data.description, 'description'));
+    errors.push(...validateOptionalString(data.icon, 'icon'));
+    errors.push(...validateOptionalString(data.frontend, 'frontend'));
+    errors.push(...validateOptionalString(data.backend, 'backend'));
+    errors.push(...validateRequires(data.requires));
+    if (data.contributes !== undefined) {
+        errors.push({ path: 'contributes', message: 'Manifest contribution arrays are not supported; register contributions at runtime' });
+    }
+    for (const key of Object.keys(data)) {
+        if (!Object.prototype.hasOwnProperty.call(OPENFORGE_PACKAGE_METADATA_SCHEMA.properties, key)) {
+            if (key !== 'contributes') {
+                errors.push({ path: key, message: 'Unknown OpenForge package metadata field' });
+            }
+        }
+    }
+    return errors;
+}
+export const validatePluginPackageMetadata = validateOpenForgePackageMetadata;
+export function isOpenForgePackageMetadata(data) {
+    return validateOpenForgePackageMetadata(data).length === 0;
+}
+export const isPluginPackageMetadata = isOpenForgePackageMetadata;

package/dist/markdown.d.ts

@@ -0,0 +1,5 @@
+export interface RenderMarkdownOptions {
+    imageBaseUrl?: string | null;
+}
+export declare function resolveMarkdownImageSrc(src: string | null, imageBaseUrl: string | null | undefined): string | null;
+export declare function renderMarkdownHtml(content: string, options?: RenderMarkdownOptions): string;

package/dist/markdown.js

@@ -0,0 +1,54 @@
+import { marked } from 'marked';
+import { sanitizeHtml } from './sanitize';
+const RELATIVE_PARENT_SEGMENT = /^\.\.\//;
+const RELATIVE_CURRENT_SEGMENT = /^\.\//;
+const markedOptions = {
+    gfm: true,
+    breaks: true,
+};
+function hasAbsoluteOrSpecialUrl(value) {
+    return /^[a-z][a-z\d+.-]*:/i.test(value) || value.startsWith('//') || value.startsWith('#');
+}
+function normalizeRepoRelativeImagePath(value) {
+    let normalized = value.startsWith('/') ? value.slice(1) : value;
+    while (RELATIVE_CURRENT_SEGMENT.test(normalized)) {
+        normalized = normalized.replace(RELATIVE_CURRENT_SEGMENT, '');
+    }
+    while (RELATIVE_PARENT_SEGMENT.test(normalized)) {
+        normalized = normalized.replace(RELATIVE_PARENT_SEGMENT, '');
+    }
+    return normalized;
+}
+function withTrailingSlash(value) {
+    return value.endsWith('/') ? value : `${value}/`;
+}
+export function resolveMarkdownImageSrc(src, imageBaseUrl) {
+    if (!src || !imageBaseUrl)
+        return null;
+    const trimmedSrc = src.trim();
+    if (!trimmedSrc || hasAbsoluteOrSpecialUrl(trimmedSrc))
+        return null;
+    try {
+        return new URL(normalizeRepoRelativeImagePath(trimmedSrc), withTrailingSlash(imageBaseUrl)).href;
+    }
+    catch {
+        return null;
+    }
+}
+function resolveMarkdownImageSources(html, imageBaseUrl) {
+    if (!imageBaseUrl || typeof document === 'undefined')
+        return html;
+    const template = document.createElement('template');
+    template.innerHTML = html;
+    for (const image of template.content.querySelectorAll('img[src]')) {
+        const resolvedSrc = resolveMarkdownImageSrc(image.getAttribute('src'), imageBaseUrl);
+        if (resolvedSrc) {
+            image.setAttribute('src', resolvedSrc);
+        }
+    }
+    return template.innerHTML;
+}
+export function renderMarkdownHtml(content, options = {}) {
+    const rawHtml = marked.parse(content, markedOptions);
+    return sanitizeHtml(resolveMarkdownImageSources(rawHtml, options.imageBaseUrl));
+}

package/dist/numberParsing.d.ts

@@ -0,0 +1 @@
+export declare function parseStrictFiniteNumber(value: string): number | null;

package/dist/numberParsing.js

@@ -0,0 +1,8 @@
+const STRICT_FINITE_NUMBER_PATTERN = /^[+-]?(?:\d+(?:\.\d+)?|\.\d+)$/;
+export function parseStrictFiniteNumber(value) {
+    if (!STRICT_FINITE_NUMBER_PATTERN.test(value)) {
+        return null;
+    }
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}