feat(file-menu): add plugin architecture for file actions

- Add FileActionExtension for menu/toolbar/both targets
- Add ExtensionRegistry service for dynamic extension loading
- Add extensions.config.ts for configuration
- Add Copy Link as example internal extension
- Support external npm packages as extensions

See docs/file-extensions.md for usage.

Author: yacchin1205

.gitignore

@@ -44,3 +44,6 @@ testem.log
 # System files
 .DS_Store
 Thumbs.db
+
+# Generated extensions config
+src/app/extensions.config.ts

docs/file-extensions.md

@@ -0,0 +1,215 @@
+# File Extensions
+
+Plugin architecture for adding custom actions to the file browser.
+
+## Overview
+
+Extensions can be placed internally (`src/app/extensions/`) or externally (npm package). Both are managed via `extensions.config.ts`.
+
+| Location | Example |
+|----------|---------|
+| `src/app/extensions/` | Copy Links |
+| npm package | [osf-extension-onlyoffice](https://github.com/yacchin1205/osf-extension-onlyoffice) (experimental) |
+
+> **Note:** `osf-extension-onlyoffice` is currently experimental and used for testing the plugin architecture.
+
+## FileActionExtension
+
+```typescript
+interface FileActionExtension {
+  id: string;
+  label: string;
+  icon: string;
+  command: (ctx: FileActionContext) => void;
+  parentId?: string;
+  position?: 'start' | 'end' | number;
+  visible?: (ctx: FileActionContext) => boolean;
+  disabled?: (ctx: FileActionContext) => boolean;
+}
+```
+
+### parentId
+
+If `parentId` is set, the extension appears only in that submenu (e.g., `'share'`).
+If not set, the extension appears in both menu and toolbar.
+
+### FileActionContext
+
+```typescript
+interface FileActionContext {
+  target: FileModel | FileDetailsModel | FileFolderModel;
+  location: 'file-list' | 'file-detail';
+  isViewOnly: boolean;
+  canWrite: boolean;
+}
+```
+
+## Example: Submenu Extension
+
+```typescript
+export function copyLinksExtensionFactory(): FileActionExtension[] {
+  return [
+    {
+      id: 'copy-link',
+      label: 'Copy Link',
+      icon: 'fas fa-link',
+      command: (ctx) => {
+        navigator.clipboard.writeText(ctx.target.links.html);
+      },
+      parentId: 'share',  // appears in Share submenu only
+      position: 'end',
+      visible: (ctx) => ctx.target.kind === 'file',
+      disabled: (ctx) => ctx.isViewOnly,
+    },
+  ];
+}
+```
+
+> **Heads up:** Context menus honor `position` exactly (for example, `'start'` inserts before built-in items). Top-level toolbars append extensions after the core OSF buttons but still keep extension-to-extension ordering based on `position`. Design UX with that constraint in mind.
+
+## Example: Menu + Toolbar Extension
+
+```typescript
+export function createFileExtensionFactory(config: Config): FileActionExtension[] {
+  return [
+    {
+      id: 'create-file',
+      label: 'Create File',
+      icon: 'fas fa-file-plus',
+      command: (ctx) => {
+        window.open(`${config.editorUrl}?path=${ctx.target.path}`, '_blank');
+      },
+      // no parentId: appears in both menu and toolbar
+      position: 'end',
+      visible: (ctx) =>
+        ctx.location === 'file-list' &&
+        ctx.target.kind === 'folder' &&
+        !ctx.isViewOnly &&
+        ctx.canWrite,
+    },
+  ];
+}
+```
+
+## Configuration
+
+The extension configuration is managed via `extensions.config.ts`, which is generated at build time.
+
+### File Structure
+
+```
+src/app/
+  extensions.config.ts          # Generated (not in git)
+  extensions.config.default.ts  # Default config (in git)
+```
+
+### Build-time Configuration
+
+By default, `extensions.config.default.ts` is used. To use a custom configuration:
+
+```bash
+EXTENSIONS_CONFIG=/path/to/my-extensions.config.ts npm run build
+```
+
+The `scripts/setup-extensions.js` helper runs before `npm run build`, `npm start`, and `npm test` (see the `prebuild` / `prestart` / `pretest` npm scripts) and handles this:
+- If `EXTENSIONS_CONFIG` is set, copies that file
+- Otherwise, copies `extensions.config.default.ts`
+
+## Registration
+
+### extensions.config.ts
+
+```typescript
+export const extensionConfig: ExtensionConfig[] = [
+  // Internal
+  {
+    load: () => import('./extensions/copy-links'),
+    factory: 'copyLinksExtensionFactory',
+    enabled: true,
+  },
+  // External
+  {
+    load: () => import('@nii/osf-extension-onlyoffice'),
+    factory: 'editWithOnlyOfficeExtensionFactory',
+    enabled: true,
+    config: { editorUrl: 'https://...' },
+  },
+  {
+    load: () => import('@nii/osf-extension-onlyoffice'),
+    factory: 'createFileExtensionFactory',
+    enabled: true,
+    config: { editorUrl: 'https://...' },
+  },
+];
+```
+
+## Creating an External Plugin
+
+```
+my-extension/
+├── package.json
+├── tsconfig.json
+└── src/
+    ├── index.ts      # re-export
+    ├── types.ts      # type definitions
+    └── my-feature.ts # factory function
+```
+
+### types.ts
+
+```typescript
+export interface FileActionContext {
+  target: { id: string; name: string; kind: string; path?: string; links: { html: string } };
+  location: 'file-list' | 'file-detail';
+  isViewOnly: boolean;
+  canWrite: boolean;
+}
+
+export interface FileActionExtension {
+  id: string;
+  label: string;
+  icon: string;
+  command: (ctx: FileActionContext) => void;
+  parentId?: string;
+  position?: 'start' | 'end' | number;
+  visible?: (ctx: FileActionContext) => boolean;
+  disabled?: (ctx: FileActionContext) => boolean;
+}
+```
+
+The `config` parameter in factory functions is passed from `extensions.config.ts`.
+
+## Developing External Plugins with npm link
+
+To test an external plugin locally without publishing to npm:
+
+```bash
+# 1. In the extension directory, build and create a global link
+cd ../osf-extension-onlyoffice
+npm run build
+npm link
+
+# 2. In angular-osf, link the package
+cd ../angular-osf
+npm link @nii/osf-extension-onlyoffice
+
+# 3. Add to extensions.config.ts and start
+npm start
+```
+
+After making changes to the extension:
+
+```bash
+# Rebuild the extension
+cd ../osf-extension-onlyoffice
+npm run build
+
+# Restart angular-osf to pick up changes
+```
+
+To unlink:
+
+```bash
+cd ../angular-osf
+npm unlink @nii/osf-extension-onlyoffice
+```

package.json

@@ -4,6 +4,8 @@
   "scripts": {
     "ng": "ng",
     "analyze-bundle": "ng build --configuration=analyze-bundle && source-map-explorer dist/**/*.js --no-border-checks",
+    "prebuild": "node scripts/setup-extensions.js",
+    "prestart": "node scripts/setup-extensions.js",
     "build": "ng build",
     "check:config": "node ./docker/check-config.js",
     "ci:test": "jest",
@@ -23,6 +25,7 @@
     "start:docker:local": "npm run check:config && ng serve --host 0.0.0.0 --port 4200 --poll 2000 --configuration docker",
     "start:test": "ng serve --configuration test-osf",
     "start:test:future": "ng serve --configuration test",
+    "pretest": "node scripts/setup-extensions.js",
     "test": "jest",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage && npm run test:display",

scripts/setup-extensions.js

@@ -0,0 +1,18 @@
+const fs = require('fs');
+const path = require('path');
+
+const targetPath = path.join(__dirname, '../src/app/extensions.config.ts');
+const defaultPath = path.join(__dirname, '../src/app/extensions.config.default.ts');
+const customPath = process.env.EXTENSIONS_CONFIG;
+
+if (customPath) {
+  const resolvedPath = path.resolve(customPath);
+  if (!fs.existsSync(resolvedPath)) {
+    throw new Error(`EXTENSIONS_CONFIG file not found: ${resolvedPath}`);
+  }
+  fs.copyFileSync(resolvedPath, targetPath);
+  console.log(`Extensions config: ${resolvedPath}`);
+} else if (!fs.existsSync(targetPath)) {
+  fs.copyFileSync(defaultPath, targetPath);
+  console.log(`Extensions config: ${defaultPath} (default)`);
+}

src/app/app.config.ts

@@ -17,6 +17,7 @@ import { authInterceptor } from '@core/interceptors/auth.interceptor';
 import { errorInterceptor } from '@core/interceptors/error.interceptor';
 import { viewOnlyInterceptor } from '@core/interceptors/view-only.interceptor';
 import { APPLICATION_INITIALIZATION_PROVIDER } from '@core/provider/application.initialization.provider';
+import { EXTENSION_INITIALIZATION_PROVIDER } from '@core/provider/extension.initialization.provider';
 import { SENTRY_PROVIDER } from '@core/provider/sentry.provider';
 
 import CustomPreset from './core/theme/custom-preset';
@@ -53,5 +54,8 @@ export const appConfig: ApplicationConfig = {
     provideStore(STATES),
     provideZoneChangeDetection({ eventCoalescing: true }),
     SENTRY_PROVIDER,
+
+    // Dynamic Extension Loading (configured in extensions.config.ts)
+    EXTENSION_INITIALIZATION_PROVIDER,
   ],
 };

src/app/core/provider/extension.initialization.provider.ts

@@ -0,0 +1,36 @@
+import { APP_INITIALIZER, Provider } from '@angular/core';
+
+import { ExtensionRegistry } from '@core/services/extension-registry.service';
+import { FileActionExtension } from '@osf/shared/tokens/file-action-extensions.token';
+
+import { ExtensionConfig, extensionConfig } from '../../extensions.config';
+
+type FactoryFunction = (config?: unknown) => FileActionExtension[];
+
+async function loadExtensions(registry: ExtensionRegistry): Promise<void> {
+  for (const ext of extensionConfig) {
+    if (!ext.enabled) continue;
+    await loadExtension(ext, registry);
+  }
+}
+
+async function loadExtension(extConfig: ExtensionConfig, registry: ExtensionRegistry): Promise<void> {
+  const module = await extConfig.load();
+  const factory = (module as Record<string, FactoryFunction>)[extConfig.factory];
+
+  if (typeof factory !== 'function') {
+    throw new Error(`Extension factory "${extConfig.factory}" not found in module`);
+  }
+
+  const extensions = factory(extConfig.config);
+  registry.register(extensions);
+}
+
+export const EXTENSION_INITIALIZATION_PROVIDER: Provider = {
+  provide: APP_INITIALIZER,
+  useFactory: (registry: ExtensionRegistry) => {
+    return () => loadExtensions(registry);
+  },
+  deps: [ExtensionRegistry],
+  multi: true,
+};

src/app/core/services/extension-registry.service.spec.ts

@@ -0,0 +1,34 @@
+import { TestBed } from '@angular/core/testing';
+
+import { FileActionExtension } from '@osf/shared/tokens/file-action-extensions.token';
+
+import { ExtensionRegistry } from './extension-registry.service';
+
+describe('ExtensionRegistry', () => {
+  let service: ExtensionRegistry;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({});
+    service = TestBed.inject(ExtensionRegistry);
+  });
+
+  it('registers extensions cumulatively', () => {
+    const extA: FileActionExtension = {
+      id: 'a',
+      label: 'A',
+      icon: 'a',
+      command: jest.fn(),
+    };
+    const extB: FileActionExtension = {
+      id: 'b',
+      label: 'B',
+      icon: 'b',
+      command: jest.fn(),
+    };
+
+    service.register([extA]);
+    service.register([extB]);
+
+    expect(service.extensions()).toEqual([extA, extB]);
+  });
+});

src/app/core/services/extension-registry.service.ts

@@ -0,0 +1,19 @@
+import { Injectable, signal } from '@angular/core';
+
+import { FileActionExtension } from '@osf/shared/tokens/file-action-extensions.token';
+
+/**
+ * Central registry for all plugin extensions.
+ * Extensions are registered at app initialization time via APP_INITIALIZER.
+ */
+@Injectable({ providedIn: 'root' })
+export class ExtensionRegistry {
+  private readonly _extensions = signal<FileActionExtension[]>([]);
+
+  /** Read-only signal of all extensions */
+  readonly extensions = this._extensions.asReadonly();
+
+  register(extensions: FileActionExtension[]): void {
+    this._extensions.update((current) => [...current, ...extensions]);
+  }
+}

src/app/extensions.config.default.ts

@@ -0,0 +1,20 @@
+/**
+ * Extension Configuration
+ *
+ * See docs/file-extensions.md for details.
+ */
+export interface ExtensionConfig {
+  load: () => Promise<unknown>;
+  factory: string;
+  enabled: boolean;
+  config?: unknown;
+}
+
+export const extensionConfig: ExtensionConfig[] = [
+  // Copy Link - adds "Copy Link" to Share submenu
+  {
+    load: () => import('./extensions/copy-links'),
+    factory: 'copyLinksExtensionFactory',
+    enabled: true,
+  },
+];