;
- };
-
- function isWebViewProvider(x: unknown): x is WebViewProvider {
- return (
- !!x && typeof x === 'object' && 'getWebView' in x && typeof x.getWebView === 'function'
- );
- }
-
- /** Retrieves the provider registered with the platform and asserts it exists. */
- function getRegisteredProvider(): WebViewProvider {
- const raw = jest.mocked(__mockRegisterWebViewProvider).mock.calls[0]?.[1];
- if (!isWebViewProvider(raw)) throw new Error('Expected registered provider');
- return raw;
- }
-
it('returns WebView definition when webViewType matches', async () => {
const context = createTestActivationContext();
@@ -176,7 +252,7 @@ describe('main', () => {
webViewType: mainWebViewType,
};
- const result = await provider.getWebView(savedWebView, {});
+ const result = await provider.getWebView(savedWebView, {}, 'nonce');
expect(result).toMatchObject({
...savedWebView,
@@ -197,7 +273,7 @@ describe('main', () => {
};
const options: InterlinearizerOpenOptions = { projectId: 'my-project' };
- const result = await provider.getWebView(savedWebView, options);
+ const result = await provider.getWebView(savedWebView, options, 'nonce');
expect(result).toMatchObject({ projectId: 'my-project' });
});
@@ -213,7 +289,7 @@ describe('main', () => {
projectId: 'saved-project',
};
- const result = await provider.getWebView(savedWebView, {});
+ const result = await provider.getWebView(savedWebView, {}, 'nonce');
expect(result).toMatchObject({ projectId: 'saved-project' });
});
@@ -229,7 +305,7 @@ describe('main', () => {
webViewType: 'other.webView',
};
- await expect(provider.getWebView(savedWebView, {})).rejects.toThrow(
+ await expect(provider.getWebView(savedWebView, {}, 'nonce')).rejects.toThrow(
`${mainWebViewType} provider received request to provide a ${savedWebView.webViewType} WebView`,
);
});
@@ -245,7 +321,7 @@ describe('main', () => {
projectId: 'saved-project',
};
- const result = await provider.getWebView(savedWebView, undefined);
+ const result = await provider.getWebView(savedWebView, undefined, 'nonce');
expect(result).toMatchObject({ projectId: 'saved-project' });
});
@@ -338,6 +414,133 @@ describe('main', () => {
expect(result).toBe('interlinearizer-webview-id');
});
+
+ it('propagates errors thrown by selectProject', async () => {
+ __mockGetOpenWebViewDefinition.mockResolvedValue(undefined);
+ __mockSelectProject.mockRejectedValue(new Error('picker failed'));
+ const openForWebView = await getOpenForWebViewHandler();
+
+ await expect(openForWebView('some-webview')).rejects.toThrow('picker failed');
+ });
+ });
+
+ describe('interlinearizer.newProject command', () => {
+ it('registers the interlinearizer.newProject command', async () => {
+ const context = createTestActivationContext();
+
+ await activate(context);
+
+ expect(__mockRegisterCommand).toHaveBeenCalledWith(
+ 'interlinearizer.newProject',
+ expect.any(Function),
+ expect.any(Object),
+ );
+ });
+
+ it('resolves to undefined and triggers no side effects (handled entirely in the WebView)', async () => {
+ const context = createTestActivationContext();
+ await activate(context);
+ const rawHandler = findRegisteredHandler('interlinearizer.newProject');
+ if (!rawHandler) throw new Error('Handler not found for interlinearizer.newProject');
+
+ await expect(rawHandler()).resolves.toBeUndefined();
+ expect(__mockOpenWebView).not.toHaveBeenCalled();
+ expect(__mockSelectProject).not.toHaveBeenCalled();
+ expect(__mockNotificationsSend).not.toHaveBeenCalled();
+ });
+ });
+
+ describe('interlinearizer.viewProjectInfo command', () => {
+ it('registers the interlinearizer.viewProjectInfo command', async () => {
+ const context = createTestActivationContext();
+
+ await activate(context);
+
+ expect(__mockRegisterCommand).toHaveBeenCalledWith(
+ 'interlinearizer.viewProjectInfo',
+ expect.any(Function),
+ expect.any(Object),
+ );
+ });
+
+ it('resolves to undefined and triggers no side effects (handled entirely in the WebView)', async () => {
+ const context = createTestActivationContext();
+ await activate(context);
+ const rawHandler = findRegisteredHandler('interlinearizer.viewProjectInfo');
+ if (!rawHandler) throw new Error('Handler not found for interlinearizer.viewProjectInfo');
+
+ await expect(rawHandler()).resolves.toBeUndefined();
+ expect(__mockOpenWebView).not.toHaveBeenCalled();
+ expect(__mockSelectProject).not.toHaveBeenCalled();
+ expect(__mockNotificationsSend).not.toHaveBeenCalled();
+ });
+ });
+
+ describe('interlinearizer.createProject command', () => {
+ const mockCreateProject = jest.mocked(projectStorage.createProject);
+ const emptyAnalysis = { segmentAnalyses: [], tokenAnalyses: [], phrases: [] };
+ const stubProject = {
+ id: 'new-project-id',
+ createdAt: '2026-01-01T00:00:00.000Z',
+ sourceProjectId: 'src-project',
+ analysisWritingSystem: 'en',
+ sourceAnalysis: emptyAnalysis,
+ targetAnalysis: emptyAnalysis,
+ links: [],
+ };
+
+ it('registers the interlinearizer.createProject command', async () => {
+ const context = createTestActivationContext();
+
+ await activate(context);
+
+ expect(__mockRegisterCommand).toHaveBeenCalledWith(
+ 'interlinearizer.createProject',
+ expect.any(Function),
+ expect.any(Object),
+ );
+ });
+
+ it('delegates to projectStorage.createProject and returns the JSON-serialized project', async () => {
+ mockCreateProject.mockResolvedValue(stubProject);
+ const handler = await getCreateProjectHandler();
+
+ const result = await handler('src-project', 'en');
+
+ expect(mockCreateProject).toHaveBeenCalledWith(
+ expect.anything(),
+ 'src-project',
+ 'en',
+ undefined,
+ undefined,
+ );
+ expect(result).toBe(JSON.stringify(stubProject));
+ });
+
+ it('does not show a project picker dialog', async () => {
+ mockCreateProject.mockResolvedValue(stubProject);
+ const handler = await getCreateProjectHandler();
+
+ await handler('src-project', 'en');
+
+ expect(__mockSelectProject).not.toHaveBeenCalled();
+ });
+
+ it('logs the error, sends an error notification, and returns undefined when storage fails', async () => {
+ mockCreateProject.mockRejectedValue(new Error('disk full'));
+ const handler = await getCreateProjectHandler();
+
+ const result = await handler('src-project', 'en');
+
+ expect(result).toBeUndefined();
+ expect(__mockLogger.error).toHaveBeenCalledWith(
+ 'Interlinearizer: failed to create project',
+ expect.any(Error),
+ );
+ expect(__mockNotificationsSend).toHaveBeenCalledWith(
+ expect.objectContaining({ severity: 'error' }),
+ );
+ });
});
describe('WebView lifecycle event subscriptions', () => {
@@ -484,6 +687,176 @@ describe('main', () => {
});
});
+ describe('interlinearizer.deleteProject command', () => {
+ const mockDeleteProject = jest.mocked(projectStorage.deleteProject);
+
+ it('registers the interlinearizer.deleteProject command', async () => {
+ const context = createTestActivationContext();
+
+ await activate(context);
+
+ expect(__mockRegisterCommand).toHaveBeenCalledWith(
+ 'interlinearizer.deleteProject',
+ expect.any(Function),
+ expect.any(Object),
+ );
+ });
+
+ it('delegates to projectStorage.deleteProject with the given ID', async () => {
+ mockDeleteProject.mockResolvedValue(undefined);
+ const handler = await getDeleteProjectHandler();
+
+ await handler('to-delete-id');
+
+ expect(mockDeleteProject).toHaveBeenCalledWith(expect.anything(), 'to-delete-id');
+ });
+
+ it('logs the error and sends an error notification when storage throws', async () => {
+ mockDeleteProject.mockRejectedValue(new Error('disk full'));
+ const handler = await getDeleteProjectHandler();
+
+ await handler('to-delete-id');
+
+ expect(__mockLogger.error).toHaveBeenCalledWith(
+ 'Interlinearizer: failed to delete project',
+ expect.any(Error),
+ );
+ expect(__mockNotificationsSend).toHaveBeenCalledWith(
+ expect.objectContaining({ severity: 'error' }),
+ );
+ });
+ });
+
+ describe('interlinearizer.getProjectsForSource command', () => {
+ const mockGetProjectsForSource = jest.mocked(projectStorage.getProjectsForSource);
+ const emptyAnalysis = { segmentAnalyses: [], tokenAnalyses: [], phrases: [] };
+ const stubProject = {
+ id: 'proj-id',
+ createdAt: '2026-01-01T00:00:00.000Z',
+ sourceProjectId: 'src-project',
+ analysisWritingSystem: 'en',
+ sourceAnalysis: emptyAnalysis,
+ targetAnalysis: emptyAnalysis,
+ links: [],
+ };
+
+ it('registers the interlinearizer.getProjectsForSource command', async () => {
+ const context = createTestActivationContext();
+
+ await activate(context);
+
+ expect(__mockRegisterCommand).toHaveBeenCalledWith(
+ 'interlinearizer.getProjectsForSource',
+ expect.any(Function),
+ expect.any(Object),
+ );
+ });
+
+ it('returns a JSON string of matching projects', async () => {
+ mockGetProjectsForSource.mockResolvedValue([stubProject]);
+ const handler = await getProjectsForSourceHandler();
+
+ const result = await handler('src-project');
+
+ expect(result).toBe(JSON.stringify([stubProject]));
+ });
+
+ it('throws and logs an error when storage throws', async () => {
+ mockGetProjectsForSource.mockRejectedValue(new Error('disk full'));
+ const handler = await getProjectsForSourceHandler();
+
+ await expect(handler('src-project')).rejects.toThrow('disk full');
+ expect(__mockLogger.error).toHaveBeenCalledWith(
+ 'Interlinearizer: failed to list projects for source',
+ expect.any(Error),
+ );
+ });
+ });
+
+ describe('interlinearizer.updateProjectMetadata command', () => {
+ const mockUpdateProjectMetadata = jest.mocked(projectStorage.updateProjectMetadata);
+ const emptyAnalysis = { segmentAnalyses: [], tokenAnalyses: [], phrases: [] };
+ const stubProject = {
+ id: 'proj-id',
+ createdAt: '2026-01-01T00:00:00.000Z',
+ sourceProjectId: 'src-project',
+ analysisWritingSystem: 'en',
+ sourceAnalysis: emptyAnalysis,
+ targetAnalysis: emptyAnalysis,
+ links: [],
+ };
+
+ it('registers the interlinearizer.updateProjectMetadata command', async () => {
+ const context = createTestActivationContext();
+
+ await activate(context);
+
+ expect(__mockRegisterCommand).toHaveBeenCalledWith(
+ 'interlinearizer.updateProjectMetadata',
+ expect.any(Function),
+ expect.any(Object),
+ );
+ });
+
+ it('passes name and description to projectStorage.updateProjectMetadata', async () => {
+ mockUpdateProjectMetadata.mockResolvedValue({ ...stubProject, name: 'My Name' });
+ const handler = await getUpdateProjectMetadataHandler();
+
+ await handler('proj-id', 'My Name', 'My Desc');
+
+ expect(mockUpdateProjectMetadata).toHaveBeenCalledWith(
+ expect.anything(),
+ 'proj-id',
+ 'My Name',
+ 'My Desc',
+ undefined,
+ );
+ });
+
+ it('passes analysisWritingSystem to projectStorage.updateProjectMetadata when provided', async () => {
+ mockUpdateProjectMetadata.mockResolvedValue({
+ ...stubProject,
+ analysisWritingSystem: 'fr',
+ });
+ const handler = await getUpdateProjectMetadataHandler();
+
+ await handler('proj-id', undefined, undefined, 'fr');
+
+ expect(mockUpdateProjectMetadata).toHaveBeenCalledWith(
+ expect.anything(),
+ 'proj-id',
+ undefined,
+ undefined,
+ 'fr',
+ );
+ });
+
+ it('returns undefined when the project does not exist', async () => {
+ mockUpdateProjectMetadata.mockResolvedValue(undefined);
+ const handler = await getUpdateProjectMetadataHandler();
+
+ const result = await handler('missing', undefined, undefined);
+
+ expect(result).toBeUndefined();
+ });
+
+ it('logs the error, sends an error notification, and returns undefined when storage throws', async () => {
+ mockUpdateProjectMetadata.mockRejectedValue(new Error('disk full'));
+ const handler = await getUpdateProjectMetadataHandler();
+
+ const result = await handler('proj-id', 'My Name', 'My Desc');
+
+ expect(result).toBeUndefined();
+ expect(__mockLogger.error).toHaveBeenCalledWith(
+ 'Interlinearizer: failed to update project metadata',
+ expect.any(Error),
+ );
+ expect(__mockNotificationsSend).toHaveBeenCalledWith(
+ expect.objectContaining({ severity: 'error' }),
+ );
+ });
+ });
+
describe('deactivate', () => {
it('returns true to indicate successful deactivation', async () => {
const result = await deactivate();
diff --git a/src/__tests__/parsers/papi/usjBookExtractor.test.ts b/src/__tests__/parsers/papi/usjBookExtractor.test.ts
index 5e819f7..c2089ac 100644
--- a/src/__tests__/parsers/papi/usjBookExtractor.test.ts
+++ b/src/__tests__/parsers/papi/usjBookExtractor.test.ts
@@ -276,4 +276,42 @@ describe('extractBookFromUsj', () => {
const hash = extractBookFromUsj(withUndefined, WS).contentHash;
expect(hash).toBe(extractBookFromUsj(withoutUndefined, WS).contentHash);
});
+
+ it('treats undefined array elements the same as null when computing contentHash', () => {
+ // stableStringify recurses into all object properties; traverse only follows .content.
+ // Putting undefined inside an extra non-content array lets us exercise the
+ // `if (value === undefined) return 'null'` path without crashing traverse.
+ // eslint-disable-next-line no-type-assertion/no-type-assertion
+ const withUndefined = {
+ content: [{ type: 'book', code: 'GEN', content: [], extra: [undefined] }],
+ } as unknown as UsjDocument;
+ // eslint-disable-next-line no-type-assertion/no-type-assertion
+ const withNull = {
+ // eslint-disable-next-line no-null/no-null
+ content: [{ type: 'book', code: 'GEN', content: [], extra: [null] }],
+ } as unknown as UsjDocument;
+
+ expect(extractBookFromUsj(withUndefined, WS).contentHash).toBe(
+ extractBookFromUsj(withNull, WS).contentHash,
+ );
+ });
+
+ it('throws on a duplicate verse SID', () => {
+ const usj: UsjDocument = {
+ content: [
+ { type: 'book', code: 'GEN', content: [] },
+ {
+ type: 'para',
+ marker: 'p',
+ content: [
+ { type: 'verse', sid: 'GEN 1:1' },
+ 'First occurrence.',
+ { type: 'verse', sid: 'GEN 1:1' },
+ 'Duplicate.',
+ ],
+ },
+ ],
+ };
+ expect(() => extractBookFromUsj(usj, WS)).toThrow('duplicate verse SID "GEN 1:1"');
+ });
});
diff --git a/src/__tests__/projectStorage.test.ts b/src/__tests__/projectStorage.test.ts
new file mode 100644
index 0000000..6e00452
--- /dev/null
+++ b/src/__tests__/projectStorage.test.ts
@@ -0,0 +1,414 @@
+/** @file Unit tests for projectStorage.ts. */
+///
+
+import papiBackendMock from '@papi/backend';
+import {
+ createProject,
+ deleteProject,
+ getProject,
+ getProjectsForSource,
+ listProjects,
+ updateProjectMetadata,
+} from '../projectStorage';
+import { createTestActivationContext } from './test-helpers';
+
+interface StorageMock {
+ __mockReadUserData: jest.Mock;
+ __mockWriteUserData: jest.Mock;
+ __mockDeleteUserData: jest.Mock;
+}
+
+function isStorageMock(m: unknown): m is StorageMock {
+ return (
+ !!m &&
+ typeof m === 'object' &&
+ '__mockReadUserData' in m &&
+ '__mockWriteUserData' in m &&
+ '__mockDeleteUserData' in m
+ );
+}
+
+if (!isStorageMock(papiBackendMock)) throw new Error('Expected mocked @papi/backend with storage');
+const { __mockReadUserData, __mockWriteUserData, __mockDeleteUserData } = papiBackendMock;
+
+const token = createTestActivationContext().executionToken;
+
+const EMPTY_ANALYSIS = { segmentAnalyses: [], tokenAnalyses: [], phrases: [] };
+
+function enoentError(): Error {
+ return Object.assign(new Error('ENOENT: no such file or directory'), { code: 'ENOENT' });
+}
+
+describe('projectStorage', () => {
+ beforeEach(() => {
+ __mockWriteUserData.mockResolvedValue(undefined);
+ __mockDeleteUserData.mockResolvedValue(undefined);
+ jest.spyOn(crypto, 'randomUUID').mockReturnValue('00000000-0000-0000-0000-000000000001');
+ });
+
+ describe('createProject', () => {
+ it('returns a project with the given fields and empty analysis/links', async () => {
+ __mockReadUserData.mockRejectedValue(enoentError());
+
+ const project = await createProject(token, 'src-proj', 'en');
+
+ expect(project).toMatchObject({
+ id: '00000000-0000-0000-0000-000000000001',
+ sourceProjectId: 'src-proj',
+ analysisWritingSystem: 'en',
+ sourceAnalysis: EMPTY_ANALYSIS,
+ targetAnalysis: EMPTY_ANALYSIS,
+ links: [],
+ });
+ expect(project.createdAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+ });
+
+ it('stores name and description when provided', async () => {
+ __mockReadUserData.mockRejectedValue(enoentError());
+
+ const project = await createProject(token, 'src-proj', 'en', 'My Name', 'My Desc');
+
+ expect(project.name).toBe('My Name');
+ expect(project.description).toBe('My Desc');
+ });
+
+ it('writes the project JSON under the project key', async () => {
+ __mockReadUserData.mockRejectedValue(enoentError());
+
+ const project = await createProject(token, 'src-proj', 'en');
+
+ expect(__mockWriteUserData).toHaveBeenCalledWith(
+ token,
+ 'project:00000000-0000-0000-0000-000000000001',
+ JSON.stringify(project),
+ );
+ });
+
+ it('creates a new index when none exists', async () => {
+ __mockReadUserData.mockRejectedValue(enoentError());
+
+ await createProject(token, 'src-proj', 'en');
+
+ expect(__mockWriteUserData).toHaveBeenCalledWith(
+ token,
+ 'projectIds',
+ JSON.stringify(['00000000-0000-0000-0000-000000000001']),
+ );
+ });
+
+ it('appends to an existing index', async () => {
+ __mockReadUserData.mockResolvedValue(JSON.stringify(['existing-id']));
+
+ await createProject(token, 'src-proj', 'en');
+
+ expect(__mockWriteUserData).toHaveBeenCalledWith(
+ token,
+ 'projectIds',
+ JSON.stringify(['existing-id', '00000000-0000-0000-0000-000000000001']),
+ );
+ });
+ });
+
+ describe('getProject', () => {
+ it('returns the parsed project when the key exists', async () => {
+ const stored = {
+ id: 'abc',
+ createdAt: '2026-01-01T00:00:00.000Z',
+ sourceProjectId: 'src',
+ analysisWritingSystem: 'fr',
+ sourceAnalysis: EMPTY_ANALYSIS,
+ targetAnalysis: EMPTY_ANALYSIS,
+ links: [],
+ };
+ __mockReadUserData.mockResolvedValue(JSON.stringify(stored));
+
+ const result = await getProject(token, 'abc');
+
+ expect(result).toEqual(stored);
+ expect(__mockReadUserData).toHaveBeenCalledWith(token, 'project:abc');
+ });
+
+ it('returns undefined when the key does not exist', async () => {
+ __mockReadUserData.mockRejectedValue(enoentError());
+
+ const result = await getProject(token, 'missing');
+
+ expect(result).toBeUndefined();
+ });
+ });
+
+ describe('listProjects', () => {
+ it('returns an empty array when no index exists', async () => {
+ __mockReadUserData.mockRejectedValue(enoentError());
+
+ const result = await listProjects(token);
+
+ expect(result).toEqual([]);
+ });
+
+ it('returns all projects listed in the index', async () => {
+ const p1 = {
+ id: 'id-1',
+ createdAt: '2026-01-01T00:00:00.000Z',
+ sourceProjectId: 'src',
+ analysisWritingSystem: 'en',
+ sourceAnalysis: EMPTY_ANALYSIS,
+ targetAnalysis: EMPTY_ANALYSIS,
+ links: [],
+ };
+ const p2 = { ...p1, id: 'id-2' };
+ __mockReadUserData
+ .mockResolvedValueOnce(JSON.stringify(['id-1', 'id-2']))
+ .mockResolvedValueOnce(JSON.stringify(p1))
+ .mockResolvedValueOnce(JSON.stringify(p2));
+
+ const result = await listProjects(token);
+
+ expect(result).toEqual([p1, p2]);
+ });
+
+ it('omits projects whose storage keys are missing', async () => {
+ const p1 = {
+ id: 'id-1',
+ createdAt: '2026-01-01T00:00:00.000Z',
+ sourceProjectId: 'src',
+ analysisWritingSystem: 'en',
+ sourceAnalysis: EMPTY_ANALYSIS,
+ targetAnalysis: EMPTY_ANALYSIS,
+ links: [],
+ };
+ __mockReadUserData
+ .mockResolvedValueOnce(JSON.stringify(['id-1', 'id-missing']))
+ .mockResolvedValueOnce(JSON.stringify(p1))
+ .mockRejectedValueOnce(enoentError());
+
+ const result = await listProjects(token);
+
+ expect(result).toEqual([p1]);
+ });
+ });
+
+ describe('updateProjectMetadata', () => {
+ const storedProject = {
+ id: 'proj-id',
+ createdAt: '2026-01-01T00:00:00.000Z',
+ sourceProjectId: 'src',
+ analysisWritingSystem: 'en',
+ sourceAnalysis: EMPTY_ANALYSIS,
+ targetAnalysis: EMPTY_ANALYSIS,
+ links: [],
+ };
+
+ it('returns the updated project with the new name and description', async () => {
+ __mockReadUserData.mockResolvedValue(JSON.stringify(storedProject));
+
+ const result = await updateProjectMetadata(token, 'proj-id', 'My Name', 'My Desc');
+
+ expect(result).toMatchObject({ id: 'proj-id', name: 'My Name', description: 'My Desc' });
+ });
+
+ it('writes the updated project to storage', async () => {
+ __mockReadUserData.mockResolvedValue(JSON.stringify(storedProject));
+
+ await updateProjectMetadata(token, 'proj-id', 'My Name', 'My Desc');
+
+ expect(__mockWriteUserData).toHaveBeenCalledWith(
+ token,
+ 'project:proj-id',
+ JSON.stringify({ ...storedProject, name: 'My Name', description: 'My Desc' }),
+ );
+ });
+
+ it('removes name and description when called with undefined', async () => {
+ const withMeta = { ...storedProject, name: 'Old', description: 'Old desc' };
+ __mockReadUserData.mockResolvedValue(JSON.stringify(withMeta));
+
+ const result = await updateProjectMetadata(token, 'proj-id', undefined, undefined);
+
+ expect(result?.name).toBeUndefined();
+ expect(result?.description).toBeUndefined();
+ const writtenArg: unknown = __mockWriteUserData.mock.calls[0]?.[2];
+ expect(typeof writtenArg).toBe('string');
+ if (typeof writtenArg === 'string') {
+ const parsed: unknown = JSON.parse(writtenArg);
+ expect(parsed).not.toHaveProperty('name');
+ expect(parsed).not.toHaveProperty('description');
+ }
+ });
+
+ it('returns undefined when the project does not exist', async () => {
+ __mockReadUserData.mockRejectedValue(enoentError());
+
+ const result = await updateProjectMetadata(token, 'missing', 'Name', 'Desc');
+
+ expect(result).toBeUndefined();
+ expect(__mockWriteUserData).not.toHaveBeenCalled();
+ });
+
+ it('updates analysisWritingSystem when a non-empty value is provided', async () => {
+ __mockReadUserData.mockResolvedValue(JSON.stringify(storedProject));
+
+ const result = await updateProjectMetadata(token, 'proj-id', 'Name', 'Desc', 'fr');
+
+ expect(result?.analysisWritingSystem).toBe('fr');
+ const writtenArg: unknown = __mockWriteUserData.mock.calls[0]?.[2];
+ expect(typeof writtenArg).toBe('string');
+ if (typeof writtenArg === 'string') {
+ const parsed: unknown = JSON.parse(writtenArg);
+ expect(parsed).toMatchObject({ analysisWritingSystem: 'fr' });
+ }
+ });
+
+ it('does not update analysisWritingSystem when an empty string is provided', async () => {
+ __mockReadUserData.mockResolvedValue(JSON.stringify(storedProject));
+
+ const result = await updateProjectMetadata(token, 'proj-id', 'Name', 'Desc', '');
+
+ expect(result?.analysisWritingSystem).toBe('en');
+ });
+
+ it('does not update analysisWritingSystem when undefined is provided', async () => {
+ __mockReadUserData.mockResolvedValue(JSON.stringify(storedProject));
+
+ const result = await updateProjectMetadata(token, 'proj-id', 'Name', 'Desc');
+
+ expect(result?.analysisWritingSystem).toBe('en');
+ });
+ });
+
+ describe('deleteProject', () => {
+ it('deletes the project key from storage', async () => {
+ __mockReadUserData.mockResolvedValue(JSON.stringify(['to-delete', 'other']));
+
+ await deleteProject(token, 'to-delete');
+
+ expect(__mockDeleteUserData).toHaveBeenCalledWith(token, 'project:to-delete');
+ });
+
+ it('removes the project ID from the index', async () => {
+ __mockReadUserData.mockResolvedValue(JSON.stringify(['to-delete', 'other']));
+
+ await deleteProject(token, 'to-delete');
+
+ expect(__mockWriteUserData).toHaveBeenCalledWith(
+ token,
+ 'projectIds',
+ JSON.stringify(['other']),
+ );
+ });
+
+ it('writes an empty index when the deleted project was the only one', async () => {
+ __mockReadUserData.mockResolvedValue(JSON.stringify(['to-delete']));
+
+ await deleteProject(token, 'to-delete');
+
+ expect(__mockWriteUserData).toHaveBeenCalledWith(token, 'projectIds', JSON.stringify([]));
+ });
+
+ it('no-ops silently when the project is not in the index', async () => {
+ __mockReadUserData.mockResolvedValue(JSON.stringify(['other']));
+
+ await deleteProject(token, 'nonexistent');
+
+ expect(__mockWriteUserData).toHaveBeenCalledWith(
+ token,
+ 'projectIds',
+ JSON.stringify(['other']),
+ );
+ });
+
+ it('completes index cleanup when the project file is already missing', async () => {
+ __mockDeleteUserData.mockRejectedValue(enoentError());
+ __mockReadUserData.mockResolvedValue(JSON.stringify(['to-delete', 'other']));
+
+ await deleteProject(token, 'to-delete');
+
+ expect(__mockWriteUserData).toHaveBeenCalledWith(
+ token,
+ 'projectIds',
+ JSON.stringify(['other']),
+ );
+ });
+
+ it('propagates unexpected errors from deleteUserData', async () => {
+ __mockDeleteUserData.mockRejectedValue(new Error('permission denied'));
+ __mockReadUserData.mockResolvedValue(JSON.stringify(['to-delete']));
+
+ await expect(deleteProject(token, 'to-delete')).rejects.toThrow('permission denied');
+ });
+
+ it('completes successfully when the project index does not exist', async () => {
+ __mockReadUserData.mockRejectedValue(enoentError());
+
+ await deleteProject(token, 'nonexistent-id');
+
+ expect(__mockWriteUserData).toHaveBeenCalledWith(token, 'projectIds', JSON.stringify([]));
+ });
+ });
+
+ describe('getProjectsForSource', () => {
+ const baseProject = {
+ id: 'id-1',
+ createdAt: '2026-01-01T00:00:00.000Z',
+ sourceProjectId: 'src-a',
+ analysisWritingSystem: 'en',
+ sourceAnalysis: EMPTY_ANALYSIS,
+ targetAnalysis: EMPTY_ANALYSIS,
+ links: [],
+ };
+
+ it('returns only projects whose sourceProjectId matches', async () => {
+ const p1 = { ...baseProject, id: 'id-1', sourceProjectId: 'src-a' };
+ const p2 = { ...baseProject, id: 'id-2', sourceProjectId: 'src-b' };
+ const p3 = { ...baseProject, id: 'id-3', sourceProjectId: 'src-a' };
+ __mockReadUserData
+ .mockResolvedValueOnce(JSON.stringify(['id-1', 'id-2', 'id-3']))
+ .mockResolvedValueOnce(JSON.stringify(p1))
+ .mockResolvedValueOnce(JSON.stringify(p2))
+ .mockResolvedValueOnce(JSON.stringify(p3));
+
+ const result = await getProjectsForSource(token, 'src-a');
+
+ expect(result).toEqual([p1, p3]);
+ });
+
+ it('returns an empty array when no projects match the source', async () => {
+ const p1 = { ...baseProject, id: 'id-1', sourceProjectId: 'src-b' };
+ __mockReadUserData
+ .mockResolvedValueOnce(JSON.stringify(['id-1']))
+ .mockResolvedValueOnce(JSON.stringify(p1));
+
+ const result = await getProjectsForSource(token, 'src-a');
+
+ expect(result).toEqual([]);
+ });
+ });
+
+ describe('error propagation', () => {
+ it('propagates non-ENOENT errors from readIds', async () => {
+ __mockReadUserData.mockRejectedValue(new Error('disk full'));
+
+ await expect(createProject(token, 'src', 'en')).rejects.toThrow('disk full');
+ });
+
+ it('propagates non-ENOENT errors from getProject', async () => {
+ __mockReadUserData.mockRejectedValue(new Error('disk full'));
+
+ await expect(getProject(token, 'abc')).rejects.toThrow('disk full');
+ });
+
+ it('propagates a JSON parse error from readIds as a corrupt-index signal', async () => {
+ __mockReadUserData.mockResolvedValue('not valid json');
+
+ await expect(listProjects(token)).rejects.toThrow(SyntaxError);
+ });
+
+ it('propagates a JSON parse error from getProject as a corrupt-record signal', async () => {
+ __mockReadUserData
+ .mockResolvedValueOnce(JSON.stringify(['abc']))
+ .mockResolvedValueOnce('not valid json');
+
+ await expect(listProjects(token)).rejects.toThrow(SyntaxError);
+ });
+ });
+});
diff --git a/src/components/CreateProjectModal.tsx b/src/components/CreateProjectModal.tsx
new file mode 100644
index 0000000..c46dc4a
--- /dev/null
+++ b/src/components/CreateProjectModal.tsx
@@ -0,0 +1,142 @@
+import papi, { logger } from '@papi/frontend';
+import { useLocalizedStrings } from '@papi/frontend/react';
+import { Button } from 'platform-bible-react';
+import { useState, useCallback, useMemo } from 'react';
+import {
+ type InterlinearProjectSummary,
+ isInterlinearProjectSummary,
+} from './SelectInterlinearProjectModal';
+
+/** Localized string keys used by {@link CreateProjectModal}. */
+const CREATE_PROJECT_MODAL_STRING_KEYS = [
+ '%interlinearizer_modal_create_title%',
+ '%interlinearizer_modal_create_name_label%',
+ '%interlinearizer_modal_create_name_placeholder%',
+ '%interlinearizer_modal_create_description_label%',
+ '%interlinearizer_modal_create_description_placeholder%',
+ '%interlinearizer_modal_create_language_label%',
+ '%interlinearizer_modal_create_language_placeholder%',
+ '%interlinearizer_modal_create_submit%',
+ '%interlinearizer_modal_create_cancel%',
+] as const;
+
+/**
+ * Modal dialog that collects project name, description, and analysis language tag before creating a
+ * new interlinear project. Submitting sends the `interlinearizer.createProject` command with the
+ * known source project ID and the entered values.
+ *
+ * @param props - Component props
+ * @param props.projectId - Source project to create the interlinear project for
+ * @param props.onClose - Callback invoked when the modal should be dismissed (cancel or submit)
+ * @param props.onProjectCreated - Optional callback invoked with the full persisted project after
+ * successful creation, before `onClose` is called.
+ * @returns The modal overlay with name, description, language inputs and submit/cancel buttons, or
+ * nothing while localized strings are loading.
+ */
+export function CreateProjectModal({
+ projectId,
+ onClose,
+ onProjectCreated,
+}: Readonly<{
+ projectId: string;
+ onClose: () => void;
+ onProjectCreated?: (project: InterlinearProjectSummary) => void;
+}>) {
+ const [localizedStrings, stringsLoading] = useLocalizedStrings(
+ useMemo(() => [...CREATE_PROJECT_MODAL_STRING_KEYS], []),
+ );
+
+ const [name, setName] = useState('');
+ const [description, setDescription] = useState('');
+ const [analysisLanguage, setAnalysisLanguage] = useState('und');
+ const [isSubmitting, setIsSubmitting] = useState(false);
+
+ /**
+ * Sends the `interlinearizer.createProject` command with the collected form values, notifies the
+ * caller via `onProjectCreated`, then closes the modal. Logs and shows a notification on
+ * failure.
+ *
+ * @returns A promise that resolves when the command completes or the error notification is sent.
+ */
+ const handleSubmit = useCallback(async () => {
+ setIsSubmitting(true);
+ const normalizedAnalysisLanguage = analysisLanguage.trim() || 'und';
+ try {
+ const projectJson = await papi.commands.sendCommand(
+ 'interlinearizer.createProject',
+ projectId,
+ normalizedAnalysisLanguage,
+ name || undefined,
+ description || undefined,
+ );
+ if (!projectJson) return;
+ const parsed: unknown = JSON.parse(projectJson);
+ if (!isInterlinearProjectSummary(parsed))
+ throw new Error('Created project has unexpected shape');
+ onProjectCreated?.(parsed);
+ onClose();
+ } catch (e) {
+ logger.error('Interlinearizer: failed to create project', e);
+ await papi.notifications
+ .send({ message: '%interlinearizer_error_create_project_failed%', severity: 'error' })
+ .catch(() => {});
+ } finally {
+ setIsSubmitting(false);
+ }
+ }, [projectId, analysisLanguage, name, description, onClose, onProjectCreated]);
+
+ if (stringsLoading) return undefined;
+
+ return (
+
+