@openforge-app/plugin-sdk 0.1.0

package/dist/openforgePackageMetadataSchema.json

@@ -0,0 +1,70 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://openforge.dev/schemas/package-openforge.v1.schema.json",
+    "title": "OpenForge package metadata",
+    "description": "Schema for package.json#openforge metadata used by OpenForge plugin packages.",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["id", "apiVersion", "displayName", "description"],
+    "properties": {
+        "id": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$",
+            "description": "Explicit app-wide plugin id. Host-exposed contribution ids are qualified with this id."
+        },
+        "apiVersion": {
+            "enum": [1]
+        },
+        "displayName": {
+            "type": "string",
+            "minLength": 1
+        },
+        "description": {
+            "type": "string",
+            "minLength": 1
+        },
+        "icon": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Semantic OpenForge icon key or package asset reference."
+        },
+        "frontend": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Path to the built frontend JavaScript entry artifact."
+        },
+        "backend": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Path to the built backend JavaScript entry artifact."
+        },
+        "requires": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": {
+                "enum": [
+                    "commands",
+                    "events",
+                    "views",
+                    "taskPane",
+                    "settings",
+                    "background",
+                    "backend",
+                    "storage",
+                    "context",
+                    "navigation",
+                    "tasks",
+                    "projects",
+                    "fs",
+                    "shell",
+                    "notifications",
+                    "attention",
+                    "system.openUrl",
+                    "config",
+                    "projectConfig"
+                ]
+            }
+        }
+    }
+}

package/dist/prStatusPresentation.d.ts

@@ -0,0 +1,30 @@
+import { type MergeReadinessAction, type MergeReadinessDetail, type MergeReadinessStatus, type MergeStatusInfo } from './domain';
+export type PrChipSurface = 'compact' | 'detail';
+export type PrChipVariant = 'success' | 'error' | 'pending' | 'muted' | 'neutral' | 'done' | 'merged' | 'closed';
+export type PrChipType = 'draft' | 'ci' | 'review' | 'merge';
+export type PrChipIcon = 'check' | 'cross' | 'clock' | null;
+export interface PrStatusChipSpec {
+    type: PrChipType;
+    label: string;
+    variant: PrChipVariant;
+    surface: PrChipSurface;
+    icon?: PrChipIcon;
+    pulse?: boolean;
+}
+export interface PrInput extends MergeStatusInfo {
+    draft?: boolean;
+    is_queued?: boolean;
+    ci_status?: string | null;
+    review_status?: string | null;
+    merged_at?: number | null;
+    head_sha?: string | null;
+    updated_at?: number | null;
+    unaddressed_comment_count?: number;
+    merge_readiness_status?: MergeReadinessStatus | null;
+    merge_readiness_action?: MergeReadinessAction | null;
+    merge_readiness_blockers?: string | MergeReadinessDetail[] | null;
+    merge_readiness_warnings?: string | MergeReadinessDetail[] | null;
+    readiness_source_head_sha?: string | null;
+    readiness_updated_at?: number | null;
+}
+export declare function getPrStatusChips(pr: PrInput, surface: PrChipSurface): PrStatusChipSpec[];

package/dist/prStatusPresentation.js

@@ -0,0 +1,151 @@
+import { getMergeReadiness, isClosedUnmergedPullRequest, isMergedPullRequest } from './domain';
+export function getPrStatusChips(pr, surface) {
+    const chips = [];
+    if (pr.draft && pr.state === 'open') {
+        chips.push({
+            type: 'draft',
+            label: 'Draft',
+            variant: 'muted',
+            surface,
+        });
+    }
+    if (pr.ci_status && pr.ci_status !== 'none' && pr.state === 'open') {
+        if (surface === 'compact') {
+            const labels = {
+                success: 'CI Passed',
+                failure: 'CI Failed',
+                pending: 'CI Pending',
+            };
+            chips.push({
+                type: 'ci',
+                label: labels[pr.ci_status] || pr.ci_status,
+                variant: pr.ci_status === 'success' ? 'success' : pr.ci_status === 'failure' ? 'error' : 'pending',
+                surface,
+            });
+        }
+        else {
+            const labels = {
+                success: 'Passing',
+                failure: 'Failing',
+                pending: 'Running',
+            };
+            const icons = {
+                success: 'check',
+                failure: 'cross',
+                pending: 'clock',
+            };
+            chips.push({
+                type: 'ci',
+                label: labels[pr.ci_status] || pr.ci_status,
+                variant: pr.ci_status === 'success' ? 'success' : pr.ci_status === 'failure' ? 'error' : 'pending',
+                icon: icons[pr.ci_status] || null,
+                surface,
+            });
+        }
+    }
+    const normalizedReviewStatus = pr.review_status === 'pending' || pr.review_status === 'review_required'
+        ? 'review_required'
+        : pr.review_status;
+    if (normalizedReviewStatus && normalizedReviewStatus !== 'none' && pr.state === 'open') {
+        if (surface === 'compact') {
+            const labels = {
+                approved: 'Approved',
+                changes_requested: 'Changes Req.',
+                review_required: 'Needs Review',
+            };
+            chips.push({
+                type: 'review',
+                label: labels[normalizedReviewStatus] || normalizedReviewStatus,
+                variant: normalizedReviewStatus === 'approved' ? 'success' : normalizedReviewStatus === 'changes_requested' ? 'pending' : 'neutral',
+                surface,
+            });
+        }
+        else {
+            const labels = {
+                approved: 'Approved',
+                changes_requested: 'Changes Requested',
+                review_required: 'Review Required',
+            };
+            const icons = {
+                approved: 'check',
+                changes_requested: 'cross',
+                review_required: 'clock',
+            };
+            chips.push({
+                type: 'review',
+                label: labels[normalizedReviewStatus] || normalizedReviewStatus,
+                variant: normalizedReviewStatus === 'approved' ? 'success' : normalizedReviewStatus === 'changes_requested' ? 'pending' : 'neutral',
+                icon: icons[normalizedReviewStatus] || null,
+                surface,
+            });
+        }
+    }
+    if (isMergedPullRequest(pr)) {
+        chips.push({
+            type: 'merge',
+            label: surface === 'compact' ? 'merged' : 'Merged',
+            variant: 'merged',
+            icon: surface === 'detail' ? 'check' : undefined,
+            surface,
+        });
+    }
+    else if (isClosedUnmergedPullRequest(pr)) {
+        chips.push({
+            type: 'merge',
+            label: surface === 'compact' ? 'closed' : 'Closed',
+            variant: 'closed',
+            icon: surface === 'detail' ? 'cross' : undefined,
+            surface,
+        });
+    }
+    else if (pr.state === 'open') {
+        const readiness = getMergeReadiness(pr);
+        const hasMergeConflict = readiness.blockers.some((blocker) => blocker.code === 'merge_conflict');
+        if (hasMergeConflict) {
+            chips.push({
+                type: 'merge',
+                label: 'Merge Conflict',
+                variant: 'error',
+                icon: surface === 'detail' ? 'cross' : undefined,
+                surface,
+            });
+        }
+        else if (readiness.status === 'queued_pull_request') {
+            chips.push({
+                type: 'merge',
+                label: surface === 'compact' ? 'Queued' : 'Queued Pull Request',
+                variant: 'done',
+                icon: surface === 'detail' ? 'check' : undefined,
+                surface,
+            });
+        }
+        else if (readiness.status === 'ready_to_enqueue') {
+            chips.push({
+                type: 'merge',
+                label: 'Ready to Enqueue',
+                variant: 'done',
+                icon: surface === 'detail' ? 'check' : undefined,
+                surface,
+            });
+        }
+        else if (readiness.status === 'ready_to_merge') {
+            chips.push({
+                type: 'merge',
+                label: 'Ready to Merge',
+                variant: 'done',
+                icon: surface === 'detail' ? 'check' : undefined,
+                surface,
+            });
+        }
+        else if (readiness.status === 'readiness_unknown') {
+            chips.push({
+                type: 'merge',
+                label: 'Readiness Unknown',
+                variant: 'neutral',
+                icon: surface === 'detail' ? 'clock' : undefined,
+                surface,
+            });
+        }
+    }
+    return chips;
+}

package/dist/projectFileTree.d.ts

@@ -0,0 +1,68 @@
+export interface ProjectFileTreeEntry {
+    name: string;
+    path: string;
+    isDir: boolean;
+    size: number | null;
+}
+export interface ProjectFileTreeNode<Entry extends ProjectFileTreeEntry = ProjectFileTreeEntry> {
+    entry: Entry;
+    children: ProjectFileTreeNode<Entry>[];
+    level: number;
+    parentPath: string | null;
+    posInSet: number;
+    setSize: number;
+}
+export type ProjectFileTreeKeyboardAction = {
+    handled: false;
+} | {
+    handled: true;
+    type: 'activate';
+    path: string;
+} | {
+    handled: true;
+    type: 'focus';
+    path: string;
+} | {
+    handled: true;
+    type: 'toggle';
+    path: string;
+} | {
+    handled: true;
+    type: 'none';
+};
+export interface ProjectFileTreeItemAccessibility {
+    level: number;
+    setSize: number;
+    posInSet: number;
+    expanded: boolean | undefined;
+    current: 'true' | undefined;
+    selected: 'true' | 'false' | undefined;
+    labelledBy: string;
+}
+interface ProjectFileTreeItemAccessibilityState {
+    expandedDirs: ReadonlySet<string>;
+    selectedPath: string | null;
+    labelId: string;
+    sizeId: string;
+}
+interface ProjectFileTreeKeyboardState {
+    expandedDirs: ReadonlySet<string>;
+    visiblePaths: readonly string[];
+}
+interface ProjectFileTreeKeyboardEventLike {
+    key: string;
+    altKey: boolean;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    shiftKey: boolean;
+}
+export declare function getProjectFileTreeDepth(path: string): number;
+export declare function getProjectFileTreeParentPath(path: string): string | null;
+export declare function buildProjectFileTree<Entry extends ProjectFileTreeEntry>(flatEntries: readonly Entry[]): ProjectFileTreeNode<Entry>[];
+export declare function flattenVisibleProjectFileTree<Entry extends ProjectFileTreeEntry>(nodes: readonly ProjectFileTreeNode<Entry>[], expandedDirs: ReadonlySet<string>): ProjectFileTreeNode<Entry>[];
+export declare function getProjectFileTreeItemAccessibility<Entry extends ProjectFileTreeEntry>(node: ProjectFileTreeNode<Entry>, state: ProjectFileTreeItemAccessibilityState): ProjectFileTreeItemAccessibility;
+export declare function formatProjectFileTreeSize(size: number | null): string;
+export declare function projectFileTreePathToId(path: string): string;
+export declare function hasProjectFileTreeShortcutModifier(event: ProjectFileTreeKeyboardEventLike): boolean;
+export declare function getProjectFileTreeKeyboardAction<Entry extends ProjectFileTreeEntry>(event: ProjectFileTreeKeyboardEventLike, node: ProjectFileTreeNode<Entry>, state: ProjectFileTreeKeyboardState): ProjectFileTreeKeyboardAction;
+export {};

package/dist/projectFileTree.js

@@ -0,0 +1,141 @@
+export function getProjectFileTreeDepth(path) {
+    return path.split('/').length - 1;
+}
+export function getProjectFileTreeParentPath(path) {
+    const lastSlash = path.lastIndexOf('/');
+    return lastSlash === -1 ? null : path.slice(0, lastSlash);
+}
+export function buildProjectFileTree(flatEntries) {
+    const nodesByPath = new Map();
+    const roots = [];
+    for (const entry of flatEntries) {
+        nodesByPath.set(entry.path, {
+            entry,
+            children: [],
+            level: 1,
+            parentPath: getProjectFileTreeParentPath(entry.path),
+            posInSet: 1,
+            setSize: 1,
+        });
+    }
+    for (const entry of flatEntries) {
+        const node = nodesByPath.get(entry.path);
+        if (!node)
+            continue;
+        const parent = node.parentPath ? nodesByPath.get(node.parentPath) : null;
+        if (parent) {
+            parent.children.push(node);
+        }
+        else {
+            roots.push(node);
+        }
+    }
+    assignProjectFileTreeMetadata(roots, 1);
+    return roots;
+}
+function assignProjectFileTreeMetadata(nodes, level) {
+    const setSize = nodes.length;
+    nodes.forEach((node, index) => {
+        node.level = level;
+        node.posInSet = index + 1;
+        node.setSize = setSize;
+        assignProjectFileTreeMetadata(node.children, level + 1);
+    });
+}
+export function flattenVisibleProjectFileTree(nodes, expandedDirs) {
+    const result = [];
+    function visit(items) {
+        for (const item of items) {
+            result.push(item);
+            if (item.entry.isDir && expandedDirs.has(item.entry.path)) {
+                visit(item.children);
+            }
+        }
+    }
+    visit(nodes);
+    return result;
+}
+export function getProjectFileTreeItemAccessibility(node, state) {
+    const isSelectedFile = !node.entry.isDir && state.selectedPath === node.entry.path;
+    return {
+        level: node.level,
+        setSize: node.setSize,
+        posInSet: node.posInSet,
+        expanded: node.entry.isDir ? state.expandedDirs.has(node.entry.path) : undefined,
+        current: isSelectedFile ? 'true' : undefined,
+        selected: !node.entry.isDir ? (isSelectedFile ? 'true' : 'false') : undefined,
+        labelledBy: !node.entry.isDir && node.entry.size !== null ? `${state.labelId} ${state.sizeId}` : state.labelId,
+    };
+}
+export function formatProjectFileTreeSize(size) {
+    if (size === null)
+        return '';
+    if (size < 1024)
+        return `${size} B`;
+    if (size < 1024 * 1024)
+        return `${(size / 1024).toFixed(1)} KB`;
+    return `${(size / (1024 * 1024)).toFixed(1)} MB`;
+}
+export function projectFileTreePathToId(path) {
+    return `project-file-tree-${Array.from(path).map((char) => char.charCodeAt(0).toString(36)).join('-')}`;
+}
+export function hasProjectFileTreeShortcutModifier(event) {
+    return event.altKey || event.ctrlKey || event.metaKey || event.shiftKey;
+}
+export function getProjectFileTreeKeyboardAction(event, node, state) {
+    if (hasProjectFileTreeShortcutModifier(event))
+        return { handled: false };
+    switch (event.key) {
+        case 'ArrowDown':
+            return focusByOffset(node.entry.path, state.visiblePaths, 1);
+        case 'ArrowUp':
+            return focusByOffset(node.entry.path, state.visiblePaths, -1);
+        case 'Home':
+            return focusFirst(state.visiblePaths);
+        case 'End':
+            return focusLast(state.visiblePaths);
+        case 'ArrowRight':
+            return getArrowRightAction(node, state.expandedDirs);
+        case 'ArrowLeft':
+            return getArrowLeftAction(node, state.expandedDirs, state.visiblePaths);
+        case 'Enter':
+        case ' ':
+            return { handled: true, type: 'activate', path: node.entry.path };
+        default:
+            return { handled: false };
+    }
+}
+function focusByOffset(currentPath, visiblePaths, offset) {
+    const currentIndex = visiblePaths.indexOf(currentPath);
+    if (currentIndex === -1)
+        return { handled: true, type: 'none' };
+    const nextIndex = Math.max(0, Math.min(visiblePaths.length - 1, currentIndex + offset));
+    const nextPath = visiblePaths[nextIndex];
+    return nextPath ? { handled: true, type: 'focus', path: nextPath } : { handled: true, type: 'none' };
+}
+function focusFirst(visiblePaths) {
+    const firstPath = visiblePaths[0];
+    return firstPath ? { handled: true, type: 'focus', path: firstPath } : { handled: true, type: 'none' };
+}
+function focusLast(visiblePaths) {
+    const lastPath = visiblePaths.at(-1);
+    return lastPath ? { handled: true, type: 'focus', path: lastPath } : { handled: true, type: 'none' };
+}
+function getArrowRightAction(node, expandedDirs) {
+    if (!node.entry.isDir)
+        return { handled: true, type: 'none' };
+    if (!expandedDirs.has(node.entry.path)) {
+        return { handled: true, type: 'toggle', path: node.entry.path };
+    }
+    const firstChild = node.children[0];
+    return firstChild ? { handled: true, type: 'focus', path: firstChild.entry.path } : { handled: true, type: 'none' };
+}
+function getArrowLeftAction(node, expandedDirs, visiblePaths) {
+    if (node.entry.isDir && expandedDirs.has(node.entry.path)) {
+        return { handled: true, type: 'toggle', path: node.entry.path };
+    }
+    if (node.parentPath && visiblePaths.includes(node.parentPath)) {
+        return { handled: true, type: 'focus', path: node.parentPath };
+    }
+    return { handled: true, type: 'none' };
+}

package/dist/sanitize.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Sanitize HTML to prevent XSS attacks.
+ * Strips all dangerous tags (script, iframe, etc.) and event handlers.
+ * Allows safe structural/formatting HTML through.
+ */
+export declare function sanitizeHtml(dirty: string): string;

package/dist/sanitize.js

@@ -0,0 +1,13 @@
+import DOMPurify from 'dompurify';
+/**
+ * Sanitize HTML to prevent XSS attacks.
+ * Strips all dangerous tags (script, iframe, etc.) and event handlers.
+ * Allows safe structural/formatting HTML through.
+ */
+export function sanitizeHtml(dirty) {
+    return DOMPurify.sanitize(dirty, {
+        USE_PROFILES: { html: true },
+        FORBID_TAGS: ['style'],
+        FORBID_ATTR: ['style'],
+    });
+}

package/dist/svelteHostRuntimeContract.d.mts

@@ -0,0 +1,18 @@
+export type SvelteHostRuntimeModule = Readonly<{
+  specifier: string
+  sourcePath: string
+  assetPath: string
+}>
+
+export const SVELTE_HOST_RUNTIME_MODULES: readonly SvelteHostRuntimeModule[]
+export const OPENFORGE_HOST_RUNTIME_SVELTE_SPECIFIERS: readonly string[]
+export const SVELTE_HOST_RUNTIME_IMPORTS: Readonly<Record<string, string>>
+export function svelteHostRuntimeImportUrl(specifier: string): string | null
+export function svelteHostRuntimeBuildEntries(): Record<string, string>
+export function svelteHostRuntimeImportMapEntries(): Record<string, string>
+export function terminalRuntimeImportMapEntries(): Record<string, string>
+export function rendererImportMapEntries(): Record<string, string>
+export function rendererImportMapScriptBody(): string
+export function rendererImportMapScriptSha256(): string
+export function rendererImportMapScriptHashSource(): string
+export function rendererImportMapHtml(): string

package/dist/svelteHostRuntimeContract.mjs

@@ -0,0 +1,81 @@
+import { createHash } from 'node:crypto'
+
+const HOST_RUNTIME_SVELTE_BASE_URL = 'plugin://host-runtime/svelte/'
+
+export const SVELTE_HOST_RUNTIME_MODULES = Object.freeze([
+  { specifier: 'svelte', sourcePath: 'index-client.js', assetPath: 'index.js' },
+  { specifier: 'svelte/animate', sourcePath: 'animate/index.js', assetPath: 'animate.js' },
+  { specifier: 'svelte/attachments', sourcePath: 'attachments/index.js', assetPath: 'attachments.js' },
+  { specifier: 'svelte/easing', sourcePath: 'easing/index.js', assetPath: 'easing.js' },
+  { specifier: 'svelte/events', sourcePath: 'events/index.js', assetPath: 'events.js' },
+  { specifier: 'svelte/internal', sourcePath: 'internal/index.js', assetPath: 'internal.js' },
+  { specifier: 'svelte/internal/client', sourcePath: 'internal/client/index.js', assetPath: 'internal/client/index.js' },
+  { specifier: 'svelte/internal/disclose-version', sourcePath: 'internal/disclose-version.js', assetPath: 'internal/disclose-version.js' },
+  { specifier: 'svelte/internal/flags/async', sourcePath: 'internal/flags/async.js', assetPath: 'internal/flags/async.js' },
+  { specifier: 'svelte/internal/flags/legacy', sourcePath: 'internal/flags/legacy.js', assetPath: 'internal/flags/legacy.js' },
+  { specifier: 'svelte/internal/flags/tracing', sourcePath: 'internal/flags/tracing.js', assetPath: 'internal/flags/tracing.js' },
+  { specifier: 'svelte/legacy', sourcePath: 'legacy/legacy-client.js', assetPath: 'legacy.js' },
+  { specifier: 'svelte/motion', sourcePath: 'motion/index.js', assetPath: 'motion.js' },
+  { specifier: 'svelte/reactivity', sourcePath: 'reactivity/index-client.js', assetPath: 'reactivity.js' },
+  { specifier: 'svelte/reactivity/window', sourcePath: 'reactivity/window/index.js', assetPath: 'reactivity/window/index.js' },
+  { specifier: 'svelte/store', sourcePath: 'store/index-client.js', assetPath: 'store.js' },
+  { specifier: 'svelte/transition', sourcePath: 'transition/index.js', assetPath: 'transition.js' },
+])
+
+export const OPENFORGE_HOST_RUNTIME_SVELTE_SPECIFIERS = Object.freeze(
+  SVELTE_HOST_RUNTIME_MODULES.map(module => module.specifier),
+)
+
+export const SVELTE_HOST_RUNTIME_IMPORTS = Object.freeze(Object.fromEntries(
+  SVELTE_HOST_RUNTIME_MODULES.map(module => [module.specifier, `${HOST_RUNTIME_SVELTE_BASE_URL}${module.assetPath}`]),
+))
+
+export function svelteHostRuntimeImportUrl(specifier) {
+  return SVELTE_HOST_RUNTIME_IMPORTS[specifier] ?? null
+}
+
+export function svelteHostRuntimeBuildEntries() {
+  return Object.fromEntries(
+    SVELTE_HOST_RUNTIME_MODULES.map(module => [module.assetPath.replace(/\.js$/, ''), module.sourcePath]),
+  )
+}
+
+export function svelteHostRuntimeImportMapEntries() {
+  return { ...SVELTE_HOST_RUNTIME_IMPORTS }
+}
+
+export function terminalRuntimeImportMapEntries() {
+  return {
+    '@openforge-app/terminal-runtime': 'plugin://host-runtime/terminal-runtime/index.js',
+    '@openforge-app/terminal-runtime/terminalRuntime': 'plugin://host-runtime/terminal-runtime/terminalRuntime.js',
+    '@openforge-app/terminal-runtime/terminalOptions': 'plugin://host-runtime/terminal-runtime/terminalOptions.js',
+    '@openforge-app/terminal-runtime/theme': 'plugin://host-runtime/terminal-runtime/theme.js',
+    '@openforge-app/terminal-runtime/shortcuts': 'plugin://host-runtime/terminal-runtime/shortcuts.js',
+    '@openforge-app/terminal-runtime/shortcutController': 'plugin://host-runtime/terminal-runtime/shortcutController.js',
+    '@openforge-app/terminal-runtime/TerminalTabsShell': 'plugin://host-runtime/terminal-runtime/TerminalTabsShell.js',
+  }
+}
+
+export function rendererImportMapEntries() {
+  return {
+    ...svelteHostRuntimeImportMapEntries(),
+    '@openforge-app/plugin-sdk': 'plugin://host-runtime/plugin-sdk/index.js',
+    ...terminalRuntimeImportMapEntries(),
+  }
+}
+
+export function rendererImportMapScriptBody() {
+  return `\n${JSON.stringify({ imports: rendererImportMapEntries() }, null, 2)}\n`
+}
+
+export function rendererImportMapScriptSha256() {
+  return `sha256-${createHash('sha256').update(rendererImportMapScriptBody(), 'utf8').digest('base64')}`
+}
+
+export function rendererImportMapScriptHashSource() {
+  return `'${rendererImportMapScriptSha256()}'`
+}
+
+export function rendererImportMapHtml() {
+  return `<script type="importmap">${rendererImportMapScriptBody()}</script>`
+}