feat: hooked the APIs of the app into the pyoide core.

tests/engine/PackagingConfig.test.ts

@@ -52,4 +52,28 @@ describe('package.json packaging configuration', () => {
     expect(dependencies.uuid).toBeTypeOf('string');
     expect(devDependencies.uuid).toBeUndefined();
   });
+
+  it('copies API documentation into packaged app resources', () => {
+    const build = packageJson.build as Record<string, any>;
+    const extraResources = build.extraResources as Array<{ from: string; to: string }>;
+
+    expect(Array.isArray(extraResources)).toBe(true);
+    expect(extraResources).toEqual(expect.arrayContaining([
+      expect.objectContaining({
+        from: 'API.md',
+      }),
+    ]));
+  });
+
+  it('copies user documentation into packaged app resources', () => {
+    const build = packageJson.build as Record<string, any>;
+    const extraResources = build.extraResources as Array<{ from: string; to: string }>;
+
+    expect(Array.isArray(extraResources)).toBe(true);
+    expect(extraResources).toEqual(expect.arrayContaining([
+      expect.objectContaining({
+        from: 'DOCUMENTATION.md',
+      }),
+    ]));
+  });
 });

tests/renderer/menuCommands.test.ts

@@ -13,6 +13,17 @@ describe('Help menu documentation entry', () => {
     expect(APP_MENU_ACTION_EVENT_MAP.openDocumentation).toBe('menu:openDocumentation');
   });
 
+  it('includes an API documentation action in Help menu', () => {
+    const helpGroup = APP_MENU_GROUPS.find((group) => group.label === 'Help');
+
+    expect(helpGroup).toBeDefined();
+    expect(helpGroup?.items.some((item) => item.action === 'openApiDocumentation')).toBe(true);
+  });
+
+  it('maps API documentation to a renderer menu event', () => {
+    expect(APP_MENU_ACTION_EVENT_MAP.openApiDocumentation).toBe('menu:openApiDocumentation');
+  });
+
   it('includes Open in Browser and Open Data Folder actions in File menu', () => {
     const fileGroup = APP_MENU_GROUPS.find((group) => group.label === 'File');
 

tests/renderer/navigation/editorRouting.test.ts

@@ -19,6 +19,7 @@ describe('editorRouting', () => {
       'metadata-diff': 'metadata-diff',
       'git-diff': 'git-diff',
       documentation: 'documentation',
+      'api-documentation': 'api-documentation',
       'site-validation': 'site-validation',
       scripts: 'scripts',
     });

tests/renderer/python/PythonRuntimeManager.test.ts

@@ -421,4 +421,85 @@ describe('PythonRuntimeManager', () => {
 
     await expect(runPromise).rejects.toThrow('Invalid macro result');
   });
+
+  it('handles worker apiCall by invoking host bridge and returning apiResult', async () => {
+    const worker = new MockWorker();
+    const invokeApiCall = vi.fn().mockResolvedValue({ id: 'post-1', title: 'Hello' });
+    const manager = new PythonRuntimeManager(
+      () => worker as unknown as Worker,
+      {
+        invokeApiCall,
+      }
+    );
+
+    const initPromise = manager.initialize();
+    worker.emitMessage({ type: 'ready' });
+    await initPromise;
+
+    const runPromise = manager.execute('print("hello")');
+    await Promise.resolve();
+
+    const runRequest = worker.postedMessages[0] as { requestId: string };
+    worker.emitMessage({
+      type: 'apiCall',
+      requestId: runRequest.requestId,
+      callId: 'call-1',
+      method: 'posts.get',
+      args: { postId: 'post-1' },
+    });
+
+    await Promise.resolve();
+
+    expect(invokeApiCall).toHaveBeenCalledWith('posts.get', { postId: 'post-1' });
+    expect(worker.postedMessages[1]).toEqual({
+      type: 'apiResult',
+      requestId: runRequest.requestId,
+      callId: 'call-1',
+      ok: true,
+      result: { id: 'post-1', title: 'Hello' },
+    });
+
+    worker.emitMessage({ type: 'runResult', requestId: runRequest.requestId, result: 'done' });
+    await expect(runPromise).resolves.toEqual({ result: 'done', stdout: '' });
+  });
+
+  it('returns apiResult with error when host bridge invocation fails', async () => {
+    const worker = new MockWorker();
+    const invokeApiCall = vi.fn().mockRejectedValue(new Error('unknown api method'));
+    const manager = new PythonRuntimeManager(
+      () => worker as unknown as Worker,
+      {
+        invokeApiCall,
+      }
+    );
+
+    const initPromise = manager.initialize();
+    worker.emitMessage({ type: 'ready' });
+    await initPromise;
+
+    const runPromise = manager.execute('print("hello")');
+    await Promise.resolve();
+
+    const runRequest = worker.postedMessages[0] as { requestId: string };
+    worker.emitMessage({
+      type: 'apiCall',
+      requestId: runRequest.requestId,
+      callId: 'call-2',
+      method: 'posts.nonExisting',
+      args: {},
+    });
+
+    await Promise.resolve();
+
+    expect(worker.postedMessages[1]).toEqual({
+      type: 'apiResult',
+      requestId: runRequest.requestId,
+      callId: 'call-2',
+      ok: false,
+      error: 'unknown api method',
+    });
+
+    worker.emitMessage({ type: 'runResult', requestId: runRequest.requestId, result: 'done' });
+    await expect(runPromise).resolves.toEqual({ result: 'done', stdout: '' });
+  });
 });

tests/renderer/python/apiDocumentationSync.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { generateApiDocumentationMarkdownV1 } from '../../../src/renderer/python/generateApiDocumentationMarkdownV1';
+
+describe('API documentation markdown sync', () => {
+  it('matches generated contract documentation', () => {
+    const apiMarkdownPath = resolve(process.cwd(), 'API.md');
+    const committedMarkdown = readFileSync(apiMarkdownPath, 'utf8');
+    const generatedMarkdown = generateApiDocumentationMarkdownV1();
+
+    expect(committedMarkdown).toBe(generatedMarkdown);
+  });
+});

tests/renderer/python/generateApiDocumentationMarkdownV1.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+import { generateApiDocumentationMarkdownV1 } from '../../../src/renderer/python/generateApiDocumentationMarkdownV1';
+
+describe('generateApiDocumentationMarkdownV1', () => {
+  it('includes a top-level table of contents with module jump links', () => {
+    const markdown = generateApiDocumentationMarkdownV1();
+
+    expect(markdown).toContain('## Table of contents');
+    expect(markdown).toContain('- [projects](#projects)');
+    expect(markdown).toContain('- [posts](#posts)');
+    expect(markdown).toContain('- [media](#media)');
+    expect(markdown).toContain('- [Data Structures](#data-structures)');
+  });
+
+  it('includes per-module API sub-table of contents with endpoint jump links', () => {
+    const markdown = generateApiDocumentationMarkdownV1();
+
+    expect(markdown).toContain('**Module APIs**');
+    expect(markdown).toContain('- [projects.create](#projectscreate)');
+    expect(markdown).toContain('- [posts.getAll](#postsgetall)');
+    expect(markdown).toContain('- [media.import](#mediaimport)');
+  });
+
+  it('includes quick links back to top navigation sections', () => {
+    const markdown = generateApiDocumentationMarkdownV1();
+
+    expect(markdown).toContain('[↑ Back to Table of contents](#table-of-contents)');
+  });
+
+  it('documents chat APIs in a dedicated module section', () => {
+    const markdown = generateApiDocumentationMarkdownV1();
+
+    expect(markdown).toContain('## chat');
+    expect(markdown).toContain('### chat.getConversations');
+    expect(markdown).toContain('### chat.sendMessage');
+    expect(markdown).toContain('- [chat](#chat)');
+    expect(markdown).toContain('- [chat.sendMessage](#chatsendmessage)');
+  });
+
+  it('includes a dedicated Data Structures section with core object shapes', () => {
+    const markdown = generateApiDocumentationMarkdownV1();
+
+    expect(markdown).toContain('## Data Structures');
+    expect(markdown).toContain('### PostData');
+    expect(markdown).toContain('- id (`string`, required)');
+    expect(markdown).toContain('- title (`string`, required)');
+    expect(markdown).toContain('- content (`string`, required)');
+    expect(markdown).toContain('### MediaData');
+    expect(markdown).toContain('- filename (`string`, required)');
+    expect(markdown).toContain('- mimeType (`string`, required)');
+  });
+
+  it('documents return type details in the response section', () => {
+    const markdown = generateApiDocumentationMarkdownV1();
+
+    expect(markdown).toContain('**Response specification**');
+    expect(markdown).toContain('- Return type: `PostData | null`');
+    expect(markdown).toContain('- Return type: `MediaData[]`');
+  });
+});

tests/renderer/python/pythonApiContractV1.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest';
+import {
+  BDS_PYTHON_API_CONTRACT_V1,
+  getPythonApiMethodContract,
+  listPythonApiMethodNames,
+} from '../../../src/renderer/python/pythonApiContractV1';
+import { generatePythonApiModuleV1 } from '../../../src/renderer/python/generatePythonApiModuleV1';
+
+describe('pythonApiContractV1', () => {
+  it('exposes broad stable method names for v1 contract', () => {
+    const methodNames = listPythonApiMethodNames();
+
+    expect(methodNames.length).toBeGreaterThan(40);
+    expect(methodNames).toEqual(expect.arrayContaining([
+      'projects.getAll',
+      'posts.get',
+      'posts.getAll',
+      'posts.search',
+      'media.get',
+      'media.search',
+      'meta.getProjectMetadata',
+      'tags.getAll',
+      'scripts.getAll',
+      'tasks.getAll',
+      'app.getSystemLanguage',
+      'chat.getConversations',
+      'chat.sendMessage',
+    ]));
+  });
+
+  it('returns method contract metadata by name', () => {
+    expect(getPythonApiMethodContract('posts.get')).toEqual({
+      method: 'posts.get',
+      description: 'Fetch one post by id.',
+      params: [
+        {
+          name: 'postId',
+          type: 'string',
+          required: true,
+        },
+      ],
+      returns: 'PostData | null',
+    });
+  });
+
+  it('contains semantic version metadata for compatibility checks', () => {
+    expect(BDS_PYTHON_API_CONTRACT_V1).toMatchObject({
+      version: '1.3.0',
+      generatedAt: expect.any(String),
+    });
+  });
+
+  it('includes canonical data structures for response documentation', () => {
+    expect(BDS_PYTHON_API_CONTRACT_V1.dataStructures).toEqual(expect.arrayContaining([
+      expect.objectContaining({ name: 'PostData' }),
+      expect.objectContaining({ name: 'MediaData' }),
+      expect.objectContaining({ name: 'ProjectData' }),
+    ]));
+  });
+});
+
+describe('generatePythonApiModuleV1', () => {
+  it('generates python facade that hides transport details', () => {
+    const moduleCode = generatePythonApiModuleV1();
+
+    expect(moduleCode).toContain('class BdsApiError(Exception):');
+    expect(moduleCode).toContain('class ProjectsApi:');
+    expect(moduleCode).toContain('class PostsApi:');
+    expect(moduleCode).toContain('class MediaApi:');
+    expect(moduleCode).toContain('class MetaApi:');
+    expect(moduleCode).toContain('class ChatApi:');
+    expect(moduleCode).toContain('async def get(self, post_id):');
+    expect(moduleCode).toContain('async def get_all(self, options=None):');
+    expect(moduleCode).toContain('async def search(self, query):');
+    expect(moduleCode).toContain('async def get_project_metadata(self):');
+    expect(moduleCode).toContain('async def get_conversations(self):');
+    expect(moduleCode).toContain('async def send_message(self, conversation_id, message):');
+    expect(moduleCode).toContain('class BdsApi:');
+    expect(moduleCode).toContain('bds = BdsApi(_transport)');
+  });
+});

tests/renderer/python/pythonApiInvokerV1.test.ts

@@ -0,0 +1,80 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { invokePythonApiMethodV1 } from '../../../src/renderer/python/pythonApiInvokerV1';
+
+describe('invokePythonApiMethodV1', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('invokes posts.get via electronAPI with validated args', async () => {
+    const getPost = vi.fn().mockResolvedValue({ id: 'p1', title: 'Post 1' });
+
+    vi.stubGlobal('window', {
+      electronAPI: {
+        posts: {
+          get: getPost,
+        },
+      },
+    });
+
+    await expect(invokePythonApiMethodV1('posts.get', { postId: 'p1' })).resolves.toEqual({
+      id: 'p1',
+      title: 'Post 1',
+    });
+    expect(getPost).toHaveBeenCalledWith('p1');
+  });
+
+  it('invokes methods from multiple namespaces via contract metadata', async () => {
+    const searchPosts = vi.fn().mockResolvedValue([{ id: 'p1', title: 'Hit' }]);
+    const getProjectMetadata = vi.fn().mockResolvedValue({ name: 'My Project' });
+    const getAllProjects = vi.fn().mockResolvedValue([{ id: 'prj-1', name: 'Main' }]);
+    const getAllPosts = vi.fn().mockResolvedValue({ items: [], hasMore: false, total: 0 });
+
+    vi.stubGlobal('window', {
+      electronAPI: {
+        projects: {
+          getAll: getAllProjects,
+        },
+        posts: {
+          search: searchPosts,
+          getAll: getAllPosts,
+        },
+        meta: {
+          getProjectMetadata,
+        },
+      },
+    });
+
+    await expect(invokePythonApiMethodV1('projects.getAll', {})).resolves.toEqual([{ id: 'prj-1', name: 'Main' }]);
+    await expect(invokePythonApiMethodV1('posts.getAll', { options: { limit: 10, offset: 5 } })).resolves.toEqual({ items: [], hasMore: false, total: 0 });
+    await expect(invokePythonApiMethodV1('posts.search', { query: 'hit' })).resolves.toEqual([{ id: 'p1', title: 'Hit' }]);
+    await expect(invokePythonApiMethodV1('meta.getProjectMetadata', {})).resolves.toEqual({ name: 'My Project' });
+    expect(getAllProjects).toHaveBeenCalledWith();
+    expect(getAllPosts).toHaveBeenCalledWith({ limit: 10, offset: 5 });
+    expect(searchPosts).toHaveBeenCalledWith('hit');
+    expect(getProjectMetadata).toHaveBeenCalledWith();
+  });
+
+  it('rejects unknown methods and malformed args', async () => {
+    vi.stubGlobal('window', {
+      electronAPI: {
+        posts: {
+          get: vi.fn(),
+          search: vi.fn(),
+          getAll: vi.fn(),
+        },
+        projects: {
+          getAll: vi.fn(),
+        },
+        meta: {
+          getProjectMetadata: vi.fn(),
+        },
+      },
+    });
+
+    await expect(invokePythonApiMethodV1('posts.unknown', {})).rejects.toThrow('Unsupported Python API method');
+    await expect(invokePythonApiMethodV1('posts.get', {})).rejects.toThrow('posts.get requires string arg postId');
+    await expect(invokePythonApiMethodV1('posts.search', { query: 1 })).rejects.toThrow('posts.search requires string arg query');
+    await expect(invokePythonApiMethodV1('posts.getAll', { options: 1 })).rejects.toThrow('posts.getAll requires object arg options');
+  });
+});